# Agent Team Upgrade — Tools, MCPs, Browser Access, Rules & Hooks

**Date:** 2026-03-21
**Status:** Draft
**Scope:** Comprehensive upgrade of all 16 agents with domain-specific tools, MCP servers, browser access, Context7 references, new rules, and hooks

**Changelog:**
- v1.0 — Initial draft
- v1.1 — Fixed MCP package names (Postgres→uvx, Redis→uvx, Lighthouse→bunx, Docker→uvx), all Chrome tools to all 6 agents, all Playwright tools to testing agents, bun over node, verified `uv run --group` syntax, added curl+context7 for Backend QA and Backend Architect, merged .mcp.json, squawk pipe fix, macOS+Telegram notification via channel config, Backend QA full Playwright access
- v1.2 — Fixed squawk to lint only new migrations (revision range), fixed Telegram token extraction (`cut -d= -f2--`), added Bash permissions guidance to installation checklist

---

## 1. Browser Access Distribution

### Claude-in-Chrome (6 agents)

Primary browser tool for visual inspection, console/network debugging, GIF recording. Shares the user's real Chrome session (cookies, auth state).

**All Chrome tools granted to all 6 agents:**
`mcp__claude-in-chrome__tabs_context_mcp`, `mcp__claude-in-chrome__tabs_create_mcp`, `mcp__claude-in-chrome__navigate`, `mcp__claude-in-chrome__computer`, `mcp__claude-in-chrome__read_page`, `mcp__claude-in-chrome__find`, `mcp__claude-in-chrome__form_input`, `mcp__claude-in-chrome__get_page_text`, `mcp__claude-in-chrome__javascript_tool`, `mcp__claude-in-chrome__read_console_messages`, `mcp__claude-in-chrome__read_network_requests`, `mcp__claude-in-chrome__resize_window`, `mcp__claude-in-chrome__gif_creator`, `mcp__claude-in-chrome__upload_image`, `mcp__claude-in-chrome__shortcuts_execute`, `mcp__claude-in-chrome__shortcuts_list`, `mcp__claude-in-chrome__switch_browser`, `mcp__claude-in-chrome__update_plan`

All tools are available to every Chrome agent. Per-agent instructions direct focus to specific tools:

| Agent | Focus Tools | Primary Use Cases |
|-------|------------|-------------------|
| **UI/UX Designer** | `gif_creator`, `resize_window`, `computer` (screenshot) | View localhost:3000 after changes, resize to mobile (375x812) / tablet (768x1024) / desktop (1440x900), GIF-record proposed interaction flows |
| **Design Auditor** | `javascript_tool`, `get_page_text`, `read_page`, `resize_window` | Extract computed styles via `getComputedStyle()`, cross-reference against `_variables.scss` tokens, screenshot components at breakpoints, read a11y tree for semantic structure |
| **Debug Specialist** | `read_console_messages`, `read_network_requests`, `javascript_tool` | Navigate to broken page, filter console by `"error\|warn"`, filter network by `"/api/"` for 4xx/5xx, execute diagnostic JS |
| **Frontend Architect** | `read_page`, `computer` (screenshot), `resize_window` | Spot-check Server Component rendering, verify hydration, validate layout after architectural changes |
| **Performance Engineer** | `javascript_tool`, `read_network_requests`, `resize_window` | Execute `performance.getEntries()` for LCP/FID/CLS, monitor network waterfall for slow `/api/` calls, measure TTFB |
| **Product Strategist** | `read_page`, `find`, `computer` (screenshot), `form_input` | Walk localhost:3000 as new user, assess onboarding/conversion flows, fill forms to test UX, screenshot critical pages, view competitor sites |

**Chrome Session Protocol (added to all 6 agents):**

```markdown
## Browser Inspection (Claude-in-Chrome)

When your task involves visual inspection or UI debugging:

1. Call `tabs_context_mcp` to discover existing tabs
2. Call `tabs_create_mcp` to create a fresh tab for this session
3. Store the returned tabId — use it for ALL subsequent browser calls
4. Navigate to `http://localhost:3000` (or the relevant URL)

Guidelines:
- Use `read_page` (accessibility tree) as primary page understanding tool
- Use `computer` with action `screenshot` only for visual verification (layout, colors, spacing)
- Before clicking: always screenshot first, then click CENTER of elements
- Filter console messages: always provide a pattern (e.g., "error|warn|Error")
- Filter network requests: use urlPattern "/api/" to avoid noise
- For responsive testing: resize to 375x812 (mobile), 768x1024 (tablet), 1440x900 (desktop)
- Close your tab when done — do not leave orphan tab groups
- NEVER trigger JavaScript alerts/confirms/prompts — they block all browser events

If your task does NOT involve visual inspection, skip browser tools entirely.
```

### Playwright MCP (2 testing agents)

Structured accessibility snapshots, headless execution, cross-browser validation. For test plan design and integration verification only.

**All Playwright tools granted to both testing agents:**
`mcp__playwright__browser_click`, `mcp__playwright__browser_close`, `mcp__playwright__browser_console_messages`, `mcp__playwright__browser_drag`, `mcp__playwright__browser_evaluate`, `mcp__playwright__browser_file_upload`, `mcp__playwright__browser_fill_form`, `mcp__playwright__browser_handle_dialog`, `mcp__playwright__browser_hover`, `mcp__playwright__browser_install`, `mcp__playwright__browser_navigate`, `mcp__playwright__browser_navigate_back`, `mcp__playwright__browser_network_requests`, `mcp__playwright__browser_press_key`, `mcp__playwright__browser_resize`, `mcp__playwright__browser_run_code`, `mcp__playwright__browser_select_option`, `mcp__playwright__browser_snapshot`, `mcp__playwright__browser_tabs`, `mcp__playwright__browser_take_screenshot`, `mcp__playwright__browser_type`, `mcp__playwright__browser_wait_for`

| Agent | Primary Use Cases |
|-------|-------------------|
| **Frontend QA** | Snapshot component a11y trees for test selector design, verify `data-testid` coverage, reproduce edge cases (empty states, error states, loading states), cross-browser validation, file upload testing, drag-and-drop testing, dialog handling |
| **Backend QA** | Verify frontend-backend integration — navigate authenticated flows, check that API responses render correctly, verify WebSocket notification delivery in UI, run Playwright code snippets via `browser_run_code` |

**Playwright Protocol (added to both agents):**

```markdown
## Browser Testing (Playwright MCP)

When verifying UI behavior or designing test plans:

1. Use `browser_snapshot` as your PRIMARY interaction tool (structured a11y tree, ref-based)
2. Use `browser_take_screenshot` only for visual verification — you CANNOT perform actions based on screenshots
3. Prefer `browser_snapshot` with incremental mode for token efficiency on complex pages
4. Use `browser_wait_for` before assertions on async-loaded content
5. Use `browser_console_messages` to check for JS errors during flows
6. Use `browser_network_requests` to verify API calls match expected contracts
7. Use `browser_run_code` for complex multi-step verification (async (page) => { ... })
8. Use `browser_handle_dialog` to accept/dismiss browser dialogs

This is Playwright, not Claude-in-Chrome. Key differences:
- Separate browser instance (does NOT share your login cookies)
- Ref-based interaction (from snapshot), not coordinate-based
- Supports headless mode and cross-browser (Chromium, Firefox, WebKit)
- No GIF recording
- Full Playwright API via browser_run_code
```

---

## 2. MCP Servers

Four new MCP servers, each scoped to specific agents via agent frontmatter `tools:` field.

**Note:** Postgres MCP Pro, Redis MCP, and Docker MCP are Python packages (run via `uvx`). Lighthouse MCP is a Node package (run via `bunx`). Exact MCP tool names are discovered at runtime after server start — agent frontmatter will list them once servers are running.

### 2a. Postgres MCP Pro

**Server:** `crystaldba/postgres-mcp` (PyPI: `postgres-mcp`)
**Connects to:** `postgresql://postgres:postgres@localhost:5332/cofee`
**Agents:** DB Architect, Performance Engineer, Backend Architect

**Capabilities used:**
- Live schema inspection — agents verify current DB state without reading `models.py`
- `pg_stat_statements` slow query analysis — Performance Engineer finds N+1 queries
- Index health checks — unused indexes, missing indexes on foreign keys across 11 modules
- EXPLAIN ANALYZE execution — DB Architect validates query plans for the 11-module schema

### 2b. Redis MCP

**Server:** `redis/mcp-redis` (PyPI: `redis-mcp-server`)
**Connects to:** `redis://localhost:6379`
**Agents:** Backend Architect, Debug Specialist

**Capabilities used:**
- Dramatiq queue inspection — see pending/failed transcription and render jobs, queue depths
- Pub/sub channel monitoring — debug WebSocket notification delivery (when `job_type === "TRANSCRIPTION_GENERATE"` notifications don't arrive)
- Key inspection — check task state, verify job progress tracking

### 2c. Lighthouse MCP

**Server:** `danielsogl/lighthouse-mcp-server` (npm: `@danielsogl/lighthouse-mcp`)
**Audits:** Any URL (passed as tool parameter per invocation, not config-level)
**Agents:** Performance Engineer, Design Auditor

**Capabilities used:**
- Core Web Vitals (LCP, FID, CLS) with structured JSON — not just a score, but actionable breakdown
- Accessibility audit (WCAG 2.1 AA) — Design Auditor uses alongside visual Chrome inspection and `pa11y`
- Performance budget checking — catch regressions when new dependencies are added

### 2d. Docker MCP

**Server:** `ckreiling/mcp-server-docker` (PyPI: `mcp-server-docker`)
**Connects to:** Docker socket
**Agents:** DevOps Engineer

**Capabilities used:**
- Container health checks across compose stack (postgres, redis, minio, api, worker, remotion)
- Log tailing per container — debug worker crashes, Remotion render failures
- Container restart — recover from stuck services
- Compose stack management — start/stop service groups

### Complete `.mcp.json` (project root)

```json
{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["postgres-mcp", "--access-mode=unrestricted"],
      "env": {
        "DATABASE_URI": "postgresql://postgres:postgres@localhost:5332/cofee"
      }
    },
    "redis": {
      "command": "uvx",
      "args": ["--from", "redis-mcp-server@latest", "redis-mcp-server", "--url", "redis://localhost:6379/0"]
    },
    "lighthouse": {
      "command": "bunx",
      "args": ["@danielsogl/lighthouse-mcp@latest"]
    },
    "docker": {
      "command": "uvx",
      "args": ["mcp-server-docker"]
    }
  }
}
```

---

## 3. CLI Tools

### 3a. Python Tools — `uv` dependency group

Add to `cofee_backend/pyproject.toml` under `[dependency-groups]`:

```toml
[dependency-groups]
tools = [
    "semgrep",
    "bandit",
    "pip-audit",
    "schemathesis",
    "radon",
]
```

Install: `cd cofee_backend && uv sync --group tools`

Agents invoke with `cd cofee_backend && uv run --group tools <tool> ...`

(`uv run --group` is a valid flag — it includes the specified dependency group for the run without needing a prior `uv sync --group`.)

### 3b. Node Tools — bunx (zero-install)

No installation needed. Agents invoke directly:

| Tool | Command | Agent |
|------|---------|-------|
| pa11y | `bunx pa11y http://localhost:3000 --standard WCAG2AA --reporter json` | Design Auditor |
| knip | `cd cofee_frontend && bunx knip --include files,exports,dependencies` | Frontend Architect, Design Auditor |
| squawk | `cd cofee_backend && uv run alembic upgrade <prev>:head --sql 2>/dev/null \| bunx squawk` | DB Architect |

**Note:** Alembic migrations are `.py` files, not `.sql`. The pipe pattern (`alembic --sql | squawk`) outputs SQL to stdout for squawk to lint.

### 3c. Brew Binaries

```bash
brew install gitleaks k6 hyperfine
```

| Tool | Command | Agent |
|------|---------|-------|
| gitleaks | `gitleaks detect --source . --report-format json --no-banner` | Security Auditor |
| k6 | `k6 run --vus 50 --duration 30s <script>.js` | Performance Engineer |
| hyperfine | `hyperfine 'bun run build' --warmup 1` | Performance Engineer |

### 3d. Agent-Specific CLI Instructions

Each agent gets concrete commands in their instructions, not generic "use tool X":

**Security Auditor:**
```markdown
## Security Scanning Tools

Run these from the project root via Bash:

### Python SAST (backend)
cd cofee_backend && uv run --group tools semgrep scan --config p/python --config p/jwt cpv3/
cd cofee_backend && uv run --group tools bandit -r cpv3/ -ll  # medium+ severity only

### Python dependency vulnerabilities
cd cofee_backend && uv run --group tools pip-audit

### Frontend SAST
Note: semgrep is installed in the backend's uv tools group but scans any language.
cd cofee_backend && uv run --group tools semgrep scan --config p/typescript --include "*.ts" --include "*.tsx" ../cofee_frontend/src/

### Secret detection (git history)
gitleaks detect --source . --report-format json --no-banner

All tools are installed project-locally (Python via uv tools group) or via brew (gitleaks).
Do NOT install new tools — use only what is listed above.
```

**Backend QA:**
```markdown
## API Fuzzing

Property-based testing against the FastAPI OpenAPI schema:
cd cofee_backend && uv run --group tools schemathesis run http://localhost:8000/api/schema/ --checks all --workers 4

This auto-generates edge-case payloads for all 11 module endpoints.
Requires the backend to be running (docker-compose up or uv run uvicorn).

## API Testing with curl

For quick endpoint verification and contract testing, use curl with proper headers:

### Authenticated request (replace <token> with a valid JWT)
curl -s -H "Authorization: Bearer <token>" -H "Content-Type: application/json" http://localhost:8000/api/projects/ | python3 -m json.tool

### POST with JSON body
curl -s -X POST -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '{"name": "test"}' http://localhost:8000/api/projects/ | python3 -m json.tool

### Measure response time
curl -o /dev/null -s -w "HTTP %{http_code} in %{time_total}s\n" -H "Authorization: Bearer <token>" http://localhost:8000/api/projects/

### Health check
curl -s http://localhost:8000/api/system/health | python3 -m json.tool

Always include Authorization header for protected endpoints. Use -s (silent) and pipe through python3 -m json.tool for readable output.
```

**Backend Architect:**
```markdown
## Code Complexity Analysis

Check cyclomatic complexity of service files (your "when in doubt, put logic in service.py" rule means these grow):
cd cofee_backend && uv run --group tools radon cc cpv3/modules/*/service.py -a -nc

Grade C or worse = too complex, recommend extraction.

## API Testing with curl

Verify endpoints you've designed or modified:

### Authenticated request
curl -s -H "Authorization: Bearer <token>" -H "Content-Type: application/json" http://localhost:8000/api/<endpoint>/ | python3 -m json.tool

### POST with JSON body
curl -s -X POST -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '{"key": "value"}' http://localhost:8000/api/<endpoint>/ | python3 -m json.tool

### Measure response time
curl -o /dev/null -s -w "HTTP %{http_code} in %{time_total}s\n" -H "Authorization: Bearer <token>" http://localhost:8000/api/<endpoint>/

Always test your endpoint changes before finalizing recommendations.

## MinIO / S3 Browsing

Browse uploaded videos and rendered outputs:
aws s3 ls --endpoint-url http://localhost:9000 s3://cofee-media/ --recursive
aws s3 ls --endpoint-url http://localhost:9000 s3://cofee-renders/

Requires AWS CLI configured with MinIO credentials (see .env).
```

**DB Architect:**
```markdown
## Migration Linting

Before approving any Alembic migration, lint the generated SQL:
cd cofee_backend && uv run alembic upgrade <prev>:head --sql 2>/dev/null | bunx squawk

Replace `<prev>` with the revision ID before the new migration (find it with `uv run alembic history`).
Squawk catches unsafe patterns: adding NOT NULL without default, CREATE INDEX without CONCURRENTLY, dropping columns with dependent views.
Do NOT lint all migrations from base — only lint the new one.
```

**Remotion Engineer:**
```markdown
## Video Inspection Tools

Validate input video before Remotion render:
ffprobe -v quiet -print_format json -show_format -show_streams /path/to/input.mp4

Check output after render (verify caption overlay, resolution, codec):
ffprobe -v quiet -print_format json -show_entries stream=width,height,r_frame_rate,codec_name /path/to/output.mp4

Extract specific frame to verify caption positioning:
ffmpeg -i /path/to/output.mp4 -vf "select=eq(n\,100)" -frames:v 1 /tmp/frame_100.png

Get container metadata (duration, bitrate, audio channels):
mediainfo --Output=JSON /path/to/video.mp4
```

**Performance Engineer:**
```markdown
## Load Testing

Load-test the transcription endpoint under concurrent video submissions:
k6 run --vus 50 --duration 30s <script>.js

Benchmark build times:
hyperfine 'cd cofee_frontend && bun run build' --warmup 1
hyperfine 'cd cofee_backend && uv run pytest tests/' --min-runs 3
```

**DevOps Engineer:**
```markdown
## MinIO / S3 Browsing

Browse and verify storage contents:
aws s3 ls --endpoint-url http://localhost:9000 s3://cofee-media/ --recursive

Requires AWS CLI configured with MinIO credentials (see .env).
```

---

## 4. Context7 Library References

Each agent gets specific library IDs in their instructions for targeted documentation lookup.

**Instruction block added to each agent:**

```markdown
## Context7 Documentation Lookup

When you need current API docs, use these pre-resolved library IDs:
- mcp__context7__resolve-library-id is NOT needed for these — call query-docs directly.

<agent-specific library table here>

Example: mcp__context7__query-docs with libraryId="/vercel/next.js" and topic="app router server components"

Note: Library IDs may change over time. If query-docs returns no results for a known library, fall back to resolve-library-id to get the current ID.
```

| Agent | Libraries |
|-------|-----------|
| **Frontend Architect** | `/vercel/next.js` (App Router, Server Components), `/tanstack/query` (v5 hooks, queries, mutations), `/websites/radix-ui_primitives` (component APIs, slot structure) |
| **Backend Architect** | `/websites/fastapi_tiangolo` (dependency injection, middleware), `/websites/sqlalchemy_en_21` (async sessions, relationships), `/pydantic/pydantic` (v2 validators, model_config), `/bogdanp/dramatiq` (actors, middleware, retry) |
| **DB Architect** | `/websites/sqlalchemy_en_21` (Alembic, DDL, type system), `/websites/sqlalchemy_en_20_orm` (relationship loading, hybrid properties) |
| **Remotion Engineer** | `/websites/remotion_dev` (interpolate, spring, composition config), `/remotion-dev/remotion` (bundle, render CLI), `/remotion-dev/skills` (best practices) |
| **Frontend QA** | `/websites/playwright_dev` (locators, expect, fixtures), `/microsoft/playwright` (test config, reporters), `/tanstack/query` (testing patterns) |
| **Backend QA** | `/websites/fastapi_tiangolo` (TestClient, dependency overrides), `/pydantic/pydantic` (schema edge cases), `/bogdanp/dramatiq` (test broker, StubBroker). For curl patterns, use `resolve-library-id` with query "curl" if needed. |
| **Performance Engineer** | `/vercel/next.js` (caching, ISR, static generation), `/websites/fastapi_tiangolo` (middleware, async patterns), `/redis/redis-py` (connection pooling, pipelines) |
| **Security Auditor** | `/websites/fastapi_tiangolo` (OAuth2, JWT, Security dependencies), `/pydantic/pydantic` (strict mode, input validation) |
| **ML/AI Engineer** | `/websites/fastapi_tiangolo` (BackgroundTasks, streaming), `/bogdanp/dramatiq` (actor retry, timeout, priority) |
| **DevOps Engineer** | `/vercel/next.js` (standalone output, Docker build), `/websites/fastapi_tiangolo` (workers, deployment settings) |
| **UI/UX Designer** | `/websites/radix-ui_primitives` (available components, API constraints) |
| **Design Auditor** | `/websites/radix-ui_primitives` (correct props, slot structure, accessibility) |
| **Orchestrator** | Generic access — queries ad-hoc based on task domain |
| **Technical Writer** | Generic access — queries based on documentation target |
| **Product Strategist** | Generic access — queries based on feature research |

---

## 5. New Rules Files

### 5a. `.claude/rules/testing.md` (no path scope — universal)

```markdown
# Testing Conventions

## Backend Tests
- Real DB + real Redis. No mocks. conftest.py has shared fixtures.
- Location: cofee_backend/tests/integration/<module>.py
- Naming: test_<action>_<scenario> (e.g., test_create_project_without_name)
- Run: cd cofee_backend && uv run pytest
- Single test: uv run pytest -k "test_name"
- API fuzzing: cd cofee_backend && uv run --group tools schemathesis run http://localhost:8000/api/schema/ --checks all

## Frontend E2E Tests
- Playwright with data-testid selectors on every interactive element
- Location: cofee_frontend/tests/
- Run: cd cofee_frontend && bun run test:e2e
- Every component root element must have data-testid

## General
- Never mock the database — use real test DB
- Tests must be deterministic — no Date.now(), no Math.random()
- Test error paths, not just happy paths
```

### 5b. `.claude/rules/security.md` (no path scope — universal)

```markdown
# Security Conventions

## Authentication
- JWT tokens via get_current_user dependency injection
- Passwords: bcrypt hash, never plain text
- Token refresh: handled by users module

## File Uploads
- Validated by extension + MIME type in files module
- Upload via uploadFile() from @shared/api/uploadFile — never raw FormData
- Endpoint: /api/files/upload/

## Secrets Management
- All config via get_settings() (cached @lru_cache) — never hardcode
- S3/MinIO credentials: env vars only, never in code or commits
- JWT secret: env var, never in code

## Data Protection
- Soft deletes: is_deleted flag — ensure deleted records never leak through API responses
- CORS: configured in main.py — restrict to frontend origin in production
- SQL injection: prevented by SQLAlchemy parameterized queries — never use raw SQL strings
- XSS: React auto-escapes — never use dangerouslySetInnerHTML

## Scanning Tools (for Security Auditor agent)
- Python SAST: semgrep + bandit (via uv run --group tools)
- Dependency CVEs: pip-audit (via uv run --group tools)
- Secret detection: gitleaks (via brew)
```

### 5c. `.claude/rules/remotion-service.md`

```yaml
---
paths:
  - "remotion_service/**"
---

# Remotion Service Rules

## Animations
- ONLY use Remotion interpolate()/spring() for all animations
- NEVER use CSS transitions, CSS animations, or Framer Motion
- All timing must be frame-based, not time-based

## Compositions
- Deterministic frame rendering: no Date.now(), no Math.random(), no network calls during render
- All data must be passed via inputProps from the server
- useCurrentFrame() and useVideoConfig() for all timing calculations

## Server
- ElysiaJS, single POST /api/render endpoint
- Flow: receive S3 path + transcription → Remotion CLI render → upload to S3 → return path
- Health check: GET /health

## Captions
- All caption presets live in src/components/captions/
- Caption data format: Word[] with start/end timestamps from transcription module

## Video Inspection
- Use ffprobe (installed) to validate input video codec/resolution/fps before render
- Use ffprobe to verify output after render
- Use ffmpeg to extract single frames for visual caption verification
- Use mediainfo for detailed container metadata
```

---

## 6. Hooks

### 6a. PreCompact — Context Preservation

Added to `settings.local.json`. Hook stdout is injected into compaction context as a system reminder.

```json
{
  "PreCompact": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "echo 'PRESERVE ACROSS COMPACTION: 1) All modified files and their purposes 2) Test results (pass/fail with commands) 3) Architecture decisions made this session 4) Error messages and resolutions 5) Current subproject (frontend/backend/remotion) 6) Pending agent handoff requests 7) Current task/phase in any active plan'"
        }
      ]
    }
  ]
}
```

### 6b. Notification — macOS Desktop Alert + Telegram

Two hooks fire on Notification events. macOS notification fires always. Telegram notification reads bot token and chat ID from the existing Telegram channel config at `~/.claude/channels/telegram/` — no env vars to configure, leverages what's already set up via `/telegram:configure`. Silently skips if Telegram channel is not configured.

```json
{
  "Notification": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Cofee Project\"' 2>/dev/null; exit 0"
        },
        {
          "type": "command",
          "command": "CHAT_ID=$(cat ~/.claude/channels/telegram/access.json 2>/dev/null | python3 -c \"import sys,json; a=json.load(sys.stdin); print(a['allowFrom'][0] if a.get('allowFrom') else '')\" 2>/dev/null) && TOKEN=$(grep TELEGRAM_BOT_TOKEN ~/.claude/channels/telegram/.env 2>/dev/null | cut -d= -f2-) && [ -n \"$CHAT_ID\" ] && [ -n \"$TOKEN\" ] && curl -s -X POST \"https://api.telegram.org/bot$TOKEN/sendMessage\" -d \"chat_id=$CHAT_ID\" -d \"text=Claude Code needs your attention (Cofee Project)\" > /dev/null 2>&1; exit 0"
        }
      ]
    }
  ]
}
```

### 6c. Backend Auto-Format Upgrade

Current backend hook runs only `ruff check`. Upgrade to `ruff check --fix` + `ruff format`:

**Before:**
```json
{
  "type": "command",
  "command": "filepath=$(cat | jq -r '.tool_input.file_path // empty') && case \"$filepath\" in */cofee_backend/cpv3/*.py) cd cofee_backend && uv run ruff check \"$filepath\" 2>&1 | head -20 ;; esac; exit 0"
}
```

**After:**
```json
{
  "type": "command",
  "command": "filepath=$(cat | jq -r '.tool_input.file_path // empty') && case \"$filepath\" in */cofee_backend/cpv3/*.py) cd cofee_backend && uv run ruff check --fix \"$filepath\" 2>&1 | head -20 && uv run ruff format \"$filepath\" 2>&1 | head -5 ;; esac; exit 0"
}
```

---

## 7. Per-Agent Instruction Changes

Summary of what changes in each agent's `.md` file.

### 7.1 Orchestrator (`orchestrator.md`)

**Changes:**
- Updated team roster table with new capabilities column showing what each agent can now do that it couldn't before
- Dispatch guidance: "If the task involves visual inspection, include 'Use Chrome browser tools to...' in the agent context"
- Dispatch guidance: "If the task involves database schema or query performance, dispatch DB Architect who can now inspect the live database via Postgres MCP"
- Dispatch guidance: "If the task involves Dramatiq job debugging, dispatch Debug Specialist or Backend Architect who can now inspect Redis directly"

### 7.2 UI/UX Designer (`ui-ux-designer.md`)

**Changes:**
- `tools:` add all Chrome tools (18 tools, see Section 1)
- Add Chrome Session Protocol block
- Add Context7 block with `/websites/radix-ui_primitives`
- Add instruction: "When proposing a design, if the dev server is running, navigate to localhost:3000 to see the current UI state before recommending changes"
- Add instruction: "Use `resize_window` to verify your proposals work at mobile (375x812), tablet (768x1024), and desktop (1440x900)"
- Add instruction: "Use `gif_creator` to record interaction demos when proposing animations or multi-step flows"

### 7.3 Design Auditor (`design-auditor.md`)

**Changes:**
- `tools:` add all Chrome tools (18 tools) + Lighthouse MCP tools
- Add Chrome visual audit protocol
- Add Context7 block with `/websites/radix-ui_primitives`
- Add Lighthouse accessibility audit instructions
- Add CLI tools block: `bunx pa11y` for WCAG 2.1 AA, `bunx knip` for dead FSD exports
- Add instruction: "Use `javascript_tool` with `getComputedStyle(document.querySelector('[data-testid=\"...\"]'))` to extract actual rendered values and compare against `_variables.scss` tokens"
- Add instruction: "Cross-reference Lighthouse accessibility issues with visual Chrome inspection — Lighthouse catches ARIA violations, Chrome shows visual presentation"

### 7.4 Debug Specialist (`debug-specialist.md`)

**Changes:**
- `tools:` add all Chrome tools (18 tools) + Redis MCP tools
- Add Chrome debugging protocol
- Add instruction: "For UI bugs, reproduce in Chrome before investigating code. Navigate to the affected page, interact with it, read console with pattern 'error|warn|Error', and check network requests filtered by '/api/'"
- Add instruction: "For notification delivery bugs, inspect Redis pub/sub channels directly to determine if the backend published the event"
- Add instruction: "For stuck Dramatiq jobs, inspect Redis keys to see queue depth and job state"

### 7.5 Frontend Architect (`frontend-architect.md`)

**Changes:**
- `tools:` add all Chrome tools (18 tools)
- Add Chrome spot-check protocol
- Add Context7 block with `/vercel/next.js`, `/tanstack/query`, `/websites/radix-ui_primitives`
- Add CLI tools block: `bunx knip` for dead exports
- Add instruction: "After recommending architectural changes, spot-check the result in Chrome to verify components render correctly and hydration succeeds"

### 7.6 Performance Engineer (`performance-engineer.md`)

**Changes:**
- `tools:` add all Chrome tools (18 tools) + Lighthouse MCP tools + Postgres MCP Pro tools
- Add Chrome performance protocol
- Add Context7 block with `/vercel/next.js`, `/websites/fastapi_tiangolo`, `/redis/redis-py`
- Add Lighthouse audit instructions: "Pass `url: 'http://localhost:3000'` as a tool parameter to each Lighthouse tool invocation"
- Add CLI tools block: `k6` for load testing, `hyperfine` for benchmarking
- Add instruction: "For backend performance, use Postgres MCP Pro to query pg_stat_statements for the slowest queries across the 11 modules"
- Add instruction: "For frontend performance, run Lighthouse audit first, then use Chrome JS execution for targeted measurements"

### 7.7 Product Strategist (`product-strategist.md`)

**Changes:**
- `tools:` add all Chrome tools (18 tools)
- Add Chrome UX walkthrough protocol
- Add instruction: "When evaluating the product, navigate localhost:3000 as a first-time user would. Document: what do they see first? What's the path to value? Where is friction?"
- Add instruction: "When comparing competitors, navigate to competitor sites and screenshot relevant flows"
- Add instruction: "Use `form_input` to fill sign-up/onboarding forms and test the conversion funnel end-to-end"

### 7.8 Frontend QA (`frontend-qa.md`)

**Changes:**
- `tools:` add all Playwright MCP tools (22 tools, see Section 1)
- Add Playwright protocol block
- Add Context7 block with `/websites/playwright_dev`, `/microsoft/playwright`, `/tanstack/query`
- Add instruction: "Use `browser_snapshot` to inspect the accessibility tree of components under test. Verify every interactive element has `data-testid`. Use the snapshot refs to design reliable test selectors"
- Add instruction: "Reproduce edge cases before recommending tests: navigate to the page, trigger empty states, error states, and loading states via Playwright to confirm the behavior you're testing for"
- Add instruction: "Use `browser_file_upload` to test file upload flows, `browser_drag` for drag-and-drop, `browser_handle_dialog` for confirmation dialogs"

### 7.9 Backend QA (`backend-qa.md`)

**Changes:**
- `tools:` add all Playwright MCP tools (22 tools, see Section 1)
- Add Playwright protocol block
- Add Context7 block with `/websites/fastapi_tiangolo`, `/pydantic/pydantic`, `/bogdanp/dramatiq`. For curl, use `resolve-library-id` with query "curl" if needed.
- Add CLI tools block: schemathesis commands + curl patterns with headers (see Section 3d)
- Add instruction: "For integration testing, use Playwright to verify that API responses render correctly in the frontend — navigate to the page, trigger the action, check network requests match expected contracts"
- Add instruction: "Run schemathesis against /api/schema/ to find endpoints that return 500 errors under edge-case payloads"
- Add instruction: "Use curl with -H 'Authorization: Bearer <token>' for quick endpoint verification. Always include Content-Type and Authorization headers for protected endpoints."

### 7.10 Security Auditor (`security-auditor.md`)

**Changes:**
- No new MCP tools
- Add Context7 block with `/websites/fastapi_tiangolo`, `/pydantic/pydantic`
- Add CLI tools block: semgrep, bandit, pip-audit, gitleaks commands (see Section 3d)
- Add instruction: "Start every security review by running the scanning tools. Report findings with severity, file:line, and remediation recommendation"
- Add instruction: "For the frontend, run semgrep with the typescript config against cofee_frontend/src/ (invoked from cofee_backend/ since semgrep is in the backend tools group)"
- Add instruction: "Check git history for leaked secrets with gitleaks before any deployment-related review"

### 7.11 DB Architect (`db-architect.md`)

**Changes:**
- `tools:` add Postgres MCP Pro tools
- Add Context7 block with `/websites/sqlalchemy_en_21`, `/websites/sqlalchemy_en_20_orm`
- Add CLI tools block: squawk via pipe pattern
- Add instruction: "Use Postgres MCP to inspect the live schema rather than reading models.py — the live database is the source of truth, models.py may be out of sync during migration development"
- Add instruction: "Before approving any Alembic migration, lint with squawk: `cd cofee_backend && uv run alembic upgrade head --sql | bunx squawk`"
- Add instruction: "Use pg_stat_statements to identify the slowest queries and recommend index improvements"

### 7.12 Backend Architect (`backend-architect.md`)

**Changes:**
- `tools:` add Redis MCP tools + Postgres MCP Pro tools
- Add Context7 block with `/websites/fastapi_tiangolo`, `/websites/sqlalchemy_en_21`, `/pydantic/pydantic`, `/bogdanp/dramatiq`
- Add CLI tools block: radon, curl patterns, MinIO browsing commands (see Section 3d)
- Add instruction: "Use Redis MCP to inspect Dramatiq queue state when designing or reviewing task processing patterns"
- Add instruction: "Check service.py complexity with radon — grade C or worse means the file needs extraction into helper functions"
- Add instruction: "Test your endpoint designs with curl before finalizing recommendations"
- Add instruction: "Browse MinIO buckets with `aws s3 ls --endpoint-url http://localhost:9000` when verifying file storage patterns. Requires AWS CLI configured with MinIO credentials (see .env)."

### 7.13 Remotion Engineer (`remotion-engineer.md`)

**Changes:**
- No new MCP tools
- Add Context7 block with `/websites/remotion_dev`, `/remotion-dev/remotion`, `/remotion-dev/skills`
- Add CLI tools block: ffprobe, mediainfo, ffmpeg commands (see Section 3d)
- Add instruction: "Validate input video before recommending Remotion composition changes: check codec, resolution, frame rate, and audio streams with ffprobe"
- Add instruction: "After render, verify output with ffprobe and extract a test frame with ffmpeg to confirm caption overlay positioning"

### 7.14 DevOps Engineer (`devops-engineer.md`)

**Changes:**
- `tools:` add Docker MCP tools
- Add Context7 block with `/vercel/next.js`, `/websites/fastapi_tiangolo`
- Add MinIO browsing via Bash instruction (requires AWS CLI + MinIO credentials from .env)
- Add instruction: "Use Docker MCP to inspect container health, tail logs, and manage the compose stack instead of crafting docker CLI commands"
- Add instruction: "For Next.js deployment, query Context7 for standalone output mode and Docker build patterns"

### 7.15 ML/AI Engineer (`ml-ai-engineer.md`)

**Changes:**
- No new MCP tools, no new CLI tools
- Add Context7 block with `/websites/fastapi_tiangolo`, `/bogdanp/dramatiq`
- Add instruction: "When modifying transcription actors, query Dramatiq docs for retry/timeout configuration and middleware patterns"

### 7.16 Technical Writer (`technical-writer.md`)

**Changes:**
- No new MCP tools, no new CLI tools
- Context7: generic access, queries based on documentation target
- Add instruction: "When documenting APIs, query the FastAPI docs for the current endpoint decorator patterns to ensure documentation matches implementation"

---

## 8. Installation Checklist

### One-time setup (run once):

1. **Python tools group:**
   ```bash
   cd cofee_backend
   # Add [dependency-groups] tools = [...] to pyproject.toml (see Section 3a)
   uv sync --group tools
   ```

2. **Brew binaries:**
   ```bash
   brew install gitleaks k6 hyperfine
   ```

3. **MCP servers — create `.mcp.json` in project root:**
   Use the complete merged config from Section 2.
   Then add MCP tool permissions to `settings.local.json` `permissions.allow` list once tool names are discovered.

4. **Rules files (create 3 new files):**
   ```
   .claude/rules/testing.md          (content: Section 5a)
   .claude/rules/security.md         (content: Section 5b)
   .claude/rules/remotion-service.md (content: Section 5c)
   ```

5. **Hooks (update settings.local.json):**
   - Add `PreCompact` hook (Section 6a)
   - Add `Notification` hook (Section 6b) — Telegram works automatically if channel is configured via `/telegram:configure`
   - Replace backend ruff hook with upgraded version (Section 6c)

6. **Bash permissions (update settings.local.json `permissions.allow`):**
   Add these patterns so agents can run new CLI tools without per-invocation prompts:
   ```json
   "Bash(uv run --group tools:*)",
   "Bash(gitleaks:*)",
   "Bash(k6:*)",
   "Bash(hyperfine:*)",
   "Bash(ffprobe:*)",
   "Bash(ffmpeg:*)",
   "Bash(mediainfo:*)",
   "Bash(aws s3:*)",
   "Bash(bunx pa11y:*)",
   "Bash(bunx knip:*)",
   "Bash(bunx squawk:*)"
   ```

7. **Agent files (update 16 .md files):**
   - Update `tools:` frontmatter per Section 7
   - Add browser protocol sections (Chrome or Playwright)
   - Add Context7 library reference blocks
   - Add CLI tool instruction blocks

### No installation needed:
- Node CLI tools (pa11y, knip, squawk) — agents use `bunx`, zero-install
- Chrome tools — already available via claude-in-chrome MCP
- Playwright tools — already available via playwright MCP
- Context7 — already configured
- Telegram notifications — uses existing channel config from `~/.claude/channels/telegram/`

### Verification after setup:

After completing installation, verify each MCP server starts correctly:
1. `uvx postgres-mcp --access-mode=unrestricted` with `DATABASE_URI` set — should connect to PostgreSQL
2. `uvx --from redis-mcp-server@latest redis-mcp-server --url redis://localhost:6379/0` — should connect to Redis
3. `bunx @danielsogl/lighthouse-mcp@latest` — should start Lighthouse server
4. `uvx mcp-server-docker` — should connect to Docker socket

Then dispatch a test task to one agent from each tool category to confirm tools work end-to-end.