Agent Orchestration
Available Agents
Located in .claude/agents/ (project-level):
| Agent | Purpose | When to Use |
|---|---|---|
| product-owner | Requirements, prioritization, GitHub issues | Discussing features, creating/managing issues |
| tdd-guide | Test-driven development | Invoked by /orchestrate Phase 2a |
| code-reviewer | Code quality review | Invoked by /orchestrate Phase 4 + fix loop |
| security-reviewer | Security analysis | Invoked by /orchestrate Phase 6 |
| nextjs-developer | Next.js App Router specialist | Invoked by /orchestrate Phase 2b (parallel) |
| e2e-tester | E2E testing: browser verification + API route HTTP requests | Invoked by /orchestrate Phase 7 |
| shadcn-ui-builder | UI components via MCP | Invoked by /orchestrate Phase 2b (parallel) |
| aws-infrastructure | AWS infra: CDK, App Runner, RDS, ECR, deployment | Invoked by /orchestrate Phase 2b (parallel) |
Agent Coordination
All agents (except product-owner) are coordinated by the /start → /orchestrate pipeline:
/start <issue>— validates env, reads issue, creates branch, builds plan with agent roster (interactive)/orchestrate— executes all phases automatically: TDD → domain specialists (parallel) → quality gates → code review → fix loop → security → E2E → commit
Domain Specialists (delegate BEFORE writing — see domain-specialists.md)
| Domain | Agent |
|---|---|
UI components (src/components/) | shadcn-ui-builder |
Next.js app (src/app/, including src/app/api/) | nextjs-developer |
AWS infrastructure (infra/, CDK stacks, Dockerfile, CI/CD) | aws-infrastructure |
Agent Roster (determined by /start plan)
| Condition | Agent | Always/Conditional |
|---|---|---|
| Always | tdd-guide | Always |
| Always | code-reviewer | Always |
Files in src/components/ | shadcn-ui-builder | Conditional |
Files in src/app/ | nextjs-developer | Conditional |
Files in infra/, Dockerfile, .github/ | aws-infrastructure | Conditional |
| API routes, auth, user input | security-reviewer | Conditional |
| UI pages or API routes | e2e-tester | Conditional |
Fix Loop Routing (Phase 5)
| File Pattern | Responsible Agent |
|---|---|
src/components/** | shadcn-ui-builder |
src/app/** | nextjs-developer |
infra/**, Dockerfile, .github/** | aws-infrastructure |
src/lib/**, src/db/**, **/*.test.*, everything else | tdd-guide |
Parallel Task Execution
ALWAYS use parallel Task execution for independent operations:
# GOOD: Parallel execution (Phase 2b)
Launch domain specialists in parallel:
1. shadcn-ui-builder: refine UI components
2. nextjs-developer: refine App Router patterns
3. aws-infrastructure: refine infra code
# GOOD: Fix loop parallel execution (Phase 5)
Group issues by agent, launch fixes simultaneously:
1. nextjs-developer: fix 2 issues in src/app/
2. tdd-guide: fix 1 issue in src/lib/
# BAD: Sequential when unnecessary
First agent 1, then agent 2, then agent 3
Multi-Perspective Analysis
For complex problems, use split role sub-agents:
- Factual reviewer
- Senior engineer
- Security expert
- Consistency reviewer
- Redundancy checker