# Agent Team Upgrade Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Upgrade all 16 agents with domain-specific tools (browser, MCP, CLI), Context7 refs, new rules, hooks, and permissions. **Architecture:** No application code changes. All work is config files (`.mcp.json`, `settings.local.json`, `pyproject.toml`), rule files (`.claude/rules/*.md`), and agent prompt files (`.claude/agents/*.md`). Phases are parallelizable — infrastructure first, then agents. **Tech Stack:** Claude Code config (YAML frontmatter, JSON settings), uv (Python deps), brew (binaries), MCP servers (uvx/bunx) **Spec:** `docs/superpowers/specs/2026-03-21-agent-team-upgrade-design.md` --- ## Phase 1: Infrastructure (Tasks 1-5) These tasks have no dependencies on each other and can run in parallel. --- ### Task 1: Create `.mcp.json` with 4 MCP servers **Files:** - Create: `.mcp.json` - [ ] **Step 1: Create `.mcp.json` in 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"] } } } ``` - [ ] **Step 2: Verify Postgres MCP connects** Run: `DATABASE_URI="postgresql://postgres:postgres@localhost:5332/cofee" uvx postgres-mcp --access-mode=unrestricted` Expected: Server starts, connects to PostgreSQL. Ctrl+C to stop. - [ ] **Step 3: Verify Redis MCP connects** Run: `uvx --from redis-mcp-server@latest redis-mcp-server --url redis://localhost:6379/0` Expected: Server starts, connects to Redis. Ctrl+C to stop. - [ ] **Step 4: Verify Lighthouse MCP starts** Run: `bunx @danielsogl/lighthouse-mcp@latest` Expected: Server starts. Ctrl+C to stop. - [ ] **Step 5: Verify Docker MCP starts** Run: `uvx mcp-server-docker` Expected: Server starts, connects to Docker socket. Ctrl+C to stop. --- ### Task 2: Add Python tools dependency group **Files:** - Modify: `cofee_backend/pyproject.toml:30-37` - [ ] **Step 1: Add tools group to pyproject.toml** After the existing `dev` group (line 37), add: ```toml tools = [ "semgrep", "bandit", "pip-audit", "schemathesis", "radon", ] ``` The `[dependency-groups]` section should now look like: ```toml [dependency-groups] dev = [ "mypy>=1.19.1", "ruff>=0.6.0", "pytest>=8.0.0", "pytest-asyncio>=0.23.0", "aiosqlite>=0.20.0", ] tools = [ "semgrep", "bandit", "pip-audit", "schemathesis", "radon", ] ``` - [ ] **Step 2: Install the tools group** Run: `cd cofee_backend && uv sync --group tools` Expected: All 5 packages install successfully. - [ ] **Step 3: Verify tools run** Run: `cd cofee_backend && uv run --group tools bandit --version` Expected: Prints bandit version. Run: `cd cofee_backend && uv run --group tools radon --version` Expected: Prints radon version. --- ### Task 3: Install brew binaries - [ ] **Step 1: Install gitleaks, k6, hyperfine** Run: `brew install gitleaks k6 hyperfine` Expected: All three install successfully. - [ ] **Step 2: Verify installations** Run: `gitleaks version && k6 version && hyperfine --version` Expected: All three print version numbers. --- ### Task 4: Create 3 new rules files **Files:** - Create: `.claude/rules/testing.md` - Create: `.claude/rules/security.md` - Create: `.claude/rules/remotion-service.md` - [ ] **Step 1: Create `.claude/rules/testing.md`** ```markdown # Testing Conventions ## Backend Tests - Real DB + real Redis. No mocks. conftest.py has shared fixtures. - Location: cofee_backend/tests/integration/.py - Naming: test__ (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 ``` - [ ] **Step 2: Create `.claude/rules/security.md`** ```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) ``` - [ ] **Step 3: Create `.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 ``` --- ### Task 5: Update hooks and permissions in settings.local.json **Files:** - Modify: `.claude/settings.local.json` - [ ] **Step 1: Add new Bash permissions** Add these entries to the `permissions.allow` array: ```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:*)", "Bash(curl:*)", "Bash(uv run ruff format:*)", "Bash(uv run alembic:*)" ``` - [ ] **Step 2: Upgrade backend ruff hook** Replace the third PostToolUse hook (the ruff check one) — change: ```json "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" ``` To: ```json "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" ``` - [ ] **Step 3: Add PreCompact hook** Add a new top-level key `"PreCompact"` to the `hooks` object: ```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'" } ] } ] ``` - [ ] **Step 4: Add Notification hooks (macOS + Telegram)** Add a new top-level key `"Notification"` to the `hooks` object: ```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" } ] } ] ``` - [ ] **Step 5: Verify the final settings.local.json is valid JSON** Run: `python3 -c "import json; json.load(open('.claude/settings.local.json')); print('Valid JSON')"` Expected: `Valid JSON` --- ## Phase 2: Agent Updates (Tasks 6-13) These tasks can run in parallel. Each updates a group of related agents. Read the spec Section 7 for full details — the spec contains the exact instruction blocks to add. **Important:** For every agent, the existing `tools:` line in frontmatter must be extended (not replaced). The base tools (`Read, Grep, Glob, Bash, WebSearch, WebFetch, mcp__context7__resolve-library-id, mcp__context7__query-docs`) stay. New tools are appended. --- ### Task 6: Update Chrome agents — UI/UX Designer + Product Strategist **Files:** - Modify: `.claude/agents/ui-ux-designer.md` - Modify: `.claude/agents/product-strategist.md` The Chrome tools string to append to `tools:` for both 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 ``` - [ ] **Step 1: Update ui-ux-designer.md frontmatter** Append the Chrome tools string above to the existing `tools:` line. - [ ] **Step 2: Add Chrome Session Protocol to ui-ux-designer.md** After the Identity section, add the Chrome Session Protocol block from spec Section 1. Then add: ```markdown ## Browser Focus Your primary Chrome tools: - `gif_creator` — record interaction demos when proposing animations or multi-step flows - `resize_window` — verify designs at mobile (375x812), tablet (768x1024), desktop (1440x900) - `computer` with `screenshot` — capture visual state for comparison When proposing a design, if the dev server is running, navigate to localhost:3000 to see the current UI state before recommending changes. ``` - [ ] **Step 3: Add Context7 block to ui-ux-designer.md** ```markdown ## Context7 Documentation Lookup When you need current API docs, use these pre-resolved library IDs — call query-docs directly (no resolve-library-id needed): | Library | ID | When to query | |---------|----|---------------| | Radix Primitives | `/websites/radix-ui_primitives` | Available components, API constraints, slot structure | If query-docs returns no results, fall back to resolve-library-id to get the current ID. ``` - [ ] **Step 4: Update product-strategist.md frontmatter** Append the same Chrome tools string to the existing `tools:` line. - [ ] **Step 5: Add Chrome Session Protocol to product-strategist.md** After the Identity section, add the Chrome Session Protocol block, then: ```markdown ## Browser Focus Your primary Chrome tools: - `read_page` + `find` — understand page structure and discover interactive elements - `computer` with `screenshot` — capture conversion-critical pages - `form_input` — fill sign-up/onboarding forms to test conversion funnel end-to-end 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? When comparing competitors, navigate to competitor sites and screenshot relevant flows. ``` - [ ] **Step 6: Add Context7 instruction to product-strategist.md** ```markdown ## Context7 Documentation Lookup Use context7 generically — query any library relevant to what you're researching. Example: mcp__context7__query-docs with libraryId="/vercel/next.js" and topic="pricing page patterns" ``` --- ### Task 7: Update Chrome agents — Design Auditor + Frontend Architect **Files:** - Modify: `.claude/agents/design-auditor.md` - Modify: `.claude/agents/frontend-architect.md` - [ ] **Step 1: Update design-auditor.md frontmatter** Append Chrome tools string (same as Task 6) to `tools:` line. This agent also gets Lighthouse MCP tools — but since exact Lighthouse tool names are discovered at runtime, for now just add Chrome tools. Add a comment after the frontmatter closing `---`: `` - [ ] **Step 2: Add Chrome + Lighthouse + CLI blocks to design-auditor.md** After the Identity section, add the Chrome Session Protocol block, then: ```markdown ## Browser Focus Your primary Chrome tools: - `javascript_tool` — extract computed styles: `getComputedStyle(document.querySelector('[data-testid="..."]'))` and cross-reference against `_variables.scss` tokens - `get_page_text` + `read_page` — read content and a11y tree for semantic structure - `resize_window` — screenshot components at mobile/tablet/desktop breakpoints Cross-reference Lighthouse accessibility issues with visual Chrome inspection — Lighthouse catches ARIA violations, Chrome shows visual presentation. ## CLI Tools ### Accessibility audit bunx pa11y http://localhost:3000 --standard WCAG2AA --reporter json ### Dead FSD export detection cd cofee_frontend && bunx knip --include files,exports,dependencies ## Context7 Documentation Lookup When you need current API docs, use these pre-resolved library IDs — call query-docs directly: | Library | ID | When to query | |---------|----|---------------| | Radix Primitives | `/websites/radix-ui_primitives` | Correct props, slot structure, accessibility patterns | If query-docs returns no results, fall back to resolve-library-id. ``` - [ ] **Step 3: Update frontend-architect.md frontmatter** Append Chrome tools string to `tools:` line. - [ ] **Step 4: Add Chrome + CLI + Context7 blocks to frontend-architect.md** After the Identity section, add the Chrome Session Protocol block, then: ```markdown ## Browser Focus Your primary Chrome tools: - `read_page` — inspect a11y tree to verify component structure - `computer` with `screenshot` — spot-check rendering after architectural changes - `resize_window` — verify layout at different viewports After recommending architectural changes, spot-check the result in Chrome to verify components render correctly and hydration succeeds. ## CLI Tools ### Dead export detection cd cofee_frontend && bunx knip --include files,exports,dependencies ## Context7 Documentation Lookup When you need current API docs, use these pre-resolved library IDs — call query-docs directly: | Library | ID | When to query | |---------|----|---------------| | Next.js | `/vercel/next.js` | App Router, Server Components, caching, ISR | | TanStack Query | `/tanstack/query` | v5 hooks, queries, mutations, testing | | Radix Primitives | `/websites/radix-ui_primitives` | Component APIs, slot structure | If query-docs returns no results, fall back to resolve-library-id. ``` --- ### Task 8: Update Chrome agents — Debug Specialist + Performance Engineer **Files:** - Modify: `.claude/agents/debug-specialist.md` - Modify: `.claude/agents/performance-engineer.md` - [ ] **Step 1: Update debug-specialist.md frontmatter** Append Chrome tools string to `tools:` line. This agent also gets Redis MCP — add comment: `` - [ ] **Step 2: Add Chrome + Redis blocks to debug-specialist.md** After the Identity section, add the Chrome Session Protocol block, then: ```markdown ## Browser Focus Your primary Chrome tools: - `read_console_messages` — filter by pattern "error|warn|Error" to find JS errors - `read_network_requests` — filter by urlPattern "/api/" to find failed API calls (4xx/5xx) - `javascript_tool` — execute diagnostic JS in page context For UI bugs, reproduce in Chrome before investigating code. Navigate to the affected page, interact with it, check console and network. ## Redis MCP (Dramatiq / WebSocket debugging) When Redis MCP tools are available: - For notification delivery bugs, inspect Redis pub/sub channels directly to determine if the backend published the event - For stuck Dramatiq jobs, inspect Redis keys to see queue depth and job state ``` - [ ] **Step 3: Update performance-engineer.md frontmatter** Append Chrome tools string to `tools:` line. Also gets Lighthouse and Postgres MCP — add comment: `` - [ ] **Step 4: Add Chrome + Lighthouse + CLI + Context7 blocks to performance-engineer.md** After the Identity section, add the Chrome Session Protocol block, then: ```markdown ## Browser Focus Your primary Chrome tools: - `javascript_tool` — execute `performance.getEntries()` to extract LCP/FID/CLS, measure TTFB - `read_network_requests` — monitor network waterfall for slow `/api/` calls - `resize_window` — test performance at different viewports For frontend performance, run Lighthouse audit first (pass `url: 'http://localhost:3000'` as tool parameter), then use Chrome JS execution for targeted measurements. ## Postgres MCP (query performance) When Postgres MCP tools are available: - Query pg_stat_statements for the slowest queries across the 11 modules - Check index health: unused indexes, missing indexes on foreign keys ## CLI Tools ### Load testing k6 run --vus 50 --duration 30s