# 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:

1. **`/start <issue>`** — validates env, reads issue, creates branch, builds plan with agent roster (interactive)
2. **`/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:

```markdown
# 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