start agents.md to guide coding assistants

Author: groovecoder

.claude/commands/check-dependency-updates.md

@@ -0,0 +1,155 @@
+# Check Dependency Update PRs
+
+You are helping review unmerged dependency update PRs (from Dependabot or manual updates). Follow these steps:
+
+## 1. Find Dependency PRs
+
+If the user provides specific PR number(s), use those. Otherwise, automatically find ALL recent **unmerged** dependency PRs:
+
+- Run `gh pr list --repo mozilla/fx-private-relay --state open --limit 30 --json number,title,author` to get open PRs
+- Filter for PRs with patterns: "build(deps)", "bump", "update", or authored by "dependabot"
+- Process ALL matching dependency PRs found (not just one)
+- **IMPORTANT**: Only check OPEN/UNMERGED PRs - do NOT check merged dependency PRs
+- If no open dependency PRs are found, inform the user
+
+## 2. Process Each PR
+
+For EACH dependency PR found, follow these steps:
+
+### 2.1 Fetch PR Information
+
+Run in parallel:
+
+- `gh pr view <PR_NUMBER> --json title,body,files`
+- Extract from PR body and title:
+  - Dependency name(s)
+  - Current version(s)
+  - New version(s)
+  - Version range (all versions between current → new)
+
+### 2.2 Identify Dependency Type
+
+Based on the changed files:
+
+- **Python dependencies**: `requirements.txt`, `pyproject.toml`, `Pipfile`
+- **JavaScript/Node**: `package.json`, `package-lock.json`, `yarn.lock`
+- **Other**: `Gemfile`, `Cargo.toml`, etc.
+
+### 2.3 Find Changelog/Release Notes
+
+Try multiple sources in order:
+
+1. **PR body**: Look for "Release notes" or "Changelog" links in Dependabot PR description
+2. **GitHub releases**: Check for links or try `https://github.com/{org}/{repo}/releases`
+3. **CHANGELOG file**: Common locations:
+   - `https://raw.githubusercontent.com/{org}/{repo}/{branch}/CHANGELOG.md`
+   - `https://raw.githubusercontent.com/{org}/{repo}/{branch}/CHANGELOG.rst`
+   - `https://raw.githubusercontent.com/{org}/{repo}/{branch}/CHANGES.md`
+   - Try branches: `main`, `master`, `develop`
+4. **Package registry**: npm, PyPI, etc. may have release notes
+
+**Special case - boto3/botocore**:
+
+- These have VERY large changelogs that must be fetched incrementally
+- URL: `https://raw.githubusercontent.com/boto/boto3/develop/CHANGELOG.rst`
+- Use curl with head/tail to fetch 20-30 lines at a time
+- Continue fetching until you find all versions in the update range
+- Extract only the relevant version entries
+
+For other large changelogs, fetch incrementally (20-30 lines at a time) until you find all relevant version entries.
+
+### 2.4 Analyze Codebase Usage
+
+Search the codebase to understand how the dependency is used:
+
+**For Python packages**:
+
+- Search for import statements: `from {package}` or `import {package}`
+- Check for specific class/function usage patterns
+- Look in configuration files for related settings
+
+**For JavaScript packages**:
+
+- Search for import statements: `import ... from '{package}'` or `require('{package}')`
+- Check for specific API usage patterns
+- Look in config files for related settings
+
+**For specific dependency types**:
+
+- **AWS/boto3/botocore**:
+  - Search for boto3 client/resource usage patterns
+  - Check privaterelay/settings.py for AWS\_\* configuration
+  - Known services in Relay: SES (email sending), S3 (storage), SQS (queue), SNS (notifications)
+  - Focus ONLY on changes to these specific AWS services
+- **Testing libraries**: Find test files and usage patterns
+- **Build tools**: Check build scripts and configurations
+- **UI libraries**: Search for component imports and usage
+
+### 2.5 Cross-reference Changes with Usage
+
+For each changelog entry in the version range:
+
+- Identify if it affects features/APIs used in the codebase
+- Categorize as:
+  - **⚠️ Breaking changes**: Require code updates
+  - **🔧 Important**: Bug fixes or deprecations affecting used features
+  - **✨ Relevant**: New features or improvements to used functionality
+  - **ℹ️ Not relevant**: Changes to unused features/services
+
+## 3. Provide Summary
+
+For EACH PR, provide a structured summary:
+
+### PR #{number}: {dependency_name}
+
+#### Version Update
+
+- Current: `v{old}`
+- New: `v{new}`
+- [Link to full changelog/releases]
+
+#### Codebase Usage
+
+- Brief description of how the dependency is used
+- Key files/locations where it's imported or configured
+
+#### Relevant Changes
+
+For each version in the range, list:
+
+- Version number and date
+- Changes that affect your codebase (with severity indicator)
+- Direct quotes from changelog for important items
+
+#### Changes Not Affecting Your Code
+
+Brief summary of other changes in the version range that don't affect used features.
+
+#### Risk Assessment
+
+- **Low/Medium/High risk** classification
+- Specific concerns or action items (if any)
+- Test areas to focus on
+- ✅/⚠️ Recommendation on whether to merge
+
+---
+
+## 4. Final Summary
+
+After reviewing all PRs, provide a brief overview:
+
+- Total PRs reviewed
+- High-risk updates (if any)
+- Recommended merge order (if applicable)
+- Overall assessment
+
+## Tips
+
+- Process PRs concurrently when possible for efficiency
+- Be concise and actionable - focus on what matters to this codebase
+- If changelog is unavailable or unclear, state this explicitly
+- For patch versions (x.x.X), typically focus on bug fixes
+- For minor versions (x.X.x), look for new features and deprecations
+- For major versions (X.x.x), carefully check for breaking changes
+- Include relevant links so the team can dig deeper if needed
+- For boto3/botocore, be especially careful to filter to only the AWS services actually used by Relay

.gitignore

@@ -22,3 +22,5 @@ gcp_key.json
 version.json
 docs/api_schema.yaml
 docs/api_docs.html
+
+.claude/settings.local.json

CLAUDE.md

@@ -0,0 +1,5 @@
+# Agent Lightbeam - Project Context
+
+This file is automatically loaded by Claude Code.
+
+@agents.md