┌──▶ @validator ──┐
User ──▶ (@researcher)* ──▶ @architect ──▶ @builder              ├──▶ @scribe
                                          └──▶ @tester   ──┘
                                               (PARALLEL)

┌──▶ @validator ──┐
User ──▶ @builder                  ├──▶ (done)
                └──▶ @tester   ──┘

┌──▶ @validator ──┐
User ──▶ (@researcher)* ──▶ @architect ──▶ @api-guardian ──▶ @builder              ├──▶ @scribe
                                                              └──▶ @tester   ──┘

┌──▶ @validator ──┐
User ──▶ @architect ──▶ @builder              ├──▶ (done)
                            └──▶ @tester   ──┘

**Decision Matrix:**

| @validator | @tester | Action |
|------------|---------|--------|
| ✅ APPROVED | ✅ APPROVED | → @scribe |
| ✅ APPROVED | 🔴 BLOCKED | → @builder (tester concerns) |
| 🔴 BLOCKED | ✅ APPROVED | → @builder (code concerns) |
| 🔴 BLOCKED | 🔴 BLOCKED | → @builder (merged feedback) |

### Gate 1: @validator (Code Quality)
- TypeScript compiles (`tsc --noEmit`)
- Unit tests pass
- No security issues
- All consumers updated (for API changes)

### Gate 2: @tester (UX Quality)
- E2E tests pass
- Screenshots at 3 viewports
- A11y compliant (WCAG 2.1 AA)
- Core Web Vitals OK (LCP, CLS, INP, FCP)

---

## Critical Paths (API Changes)

Changes in these paths **MUST** go through @api-guardian:

- `src/api/**`
- `backend/routes/**`
- `shared/types/**`
- `types/`
- `*.d.ts`
- `openapi.yaml` / `openapi.json`
- `schema.graphql`

---

## File Structure for Reports

---

## Handoff Matrix

| Agent | Receives from | Passes to |
|-------|---------------|-----------|
| @researcher | User/Orchestrator | @architect |
| @architect | User/@researcher | @api-guardian or @builder |
| @api-guardian | @architect | @builder |
| @builder | @architect/@api-guardian | @validator AND @tester (PARALLEL) |
| @validator | @builder | SYNC POINT |
| @tester | @builder | SYNC POINT |
| @scribe | Both gates approved | @github-manager (for release) |
| @github-manager | @scribe/User | Done |

---

## Pre-Push Requirements

**Before ANY push:**

1. **VERSION file MUST be updated** (project root)
2. **CHANGELOG.md MUST be updated**
3. **README.md updated if needed** (user-facing changes)
4. **NEVER push the same version twice**

**Versioning Schema (Semantic Versioning):**
- **MAJOR** (X.0.0): Breaking changes
- **MINOR** (0.X.0): New features
- **PATCH** (0.0.X): Bug fixes

---

## Detailed Agent Specifications

<details>
<summary><strong>@researcher</strong> - Knowledge Discovery Specialist</summary>

### Role
Knowledge Discovery Specialist - expert in web research, documentation lookup, and technology evaluation.

### Tools
| Tool | Usage |
|------|-------|
| WebSearch | Search internet for current information |
| WebFetch | Fetch specific URLs, documentation pages |
| Read | Read local documentation, previous research |
| Glob | Find existing documentation in codebase |
| memory MCP | Store key findings, no-go technologies |

### What I Do
1. **Technology Research** - Evaluate technologies with pros/cons
2. **Best Practices Lookup** - Find current patterns (2024/2025)
3. **Security Research** - Check CVE databases, security advisories
4. **Documentation Discovery** - Find official API docs, guides
5. **Competitive Analysis** - How do similar projects solve this?

### Output Format

### Timeout & Graceful Degradation
- **Hard timeout: 30 seconds MAX** per research task
- If timeout reached: STOP → Report partial results → Indicate what's incomplete
- Uses graceful degradation: Full → Partial → Search Results Only → Failure Report

**Model:** haiku (fast & cost-effective)

</details>

<details>
<summary><strong>@architect</strong> - System Architect</summary>

### Role
System Architect - strategic planner for React/Node.js/TypeScript enterprise applications.

### Tools
| Tool | Usage |
|------|-------|
| Read | Analyze existing architecture docs |
| Grep | Code pattern and dependency search |
| Glob | Capture module structures |
| WebFetch | Research best practices |

### What I Do
1. **Design high-level architecture** - Module structure, dependency graphs
2. **Make technical decisions** - Stack selection, state management, patterns
3. **Create handoff specifications** - Clear specs for @api-guardian and @builder

### Decision Template

### Design Principles
- Single Responsibility Principle
- Composition over Inheritance
- Props Drilling Max 2 Levels (then Context)
- Server State Separation (React Query/SWR)

**Model:** opus (complex reasoning, high-impact decisions)

</details>

<details>
<summary><strong>@api-guardian</strong> - API Lifecycle Expert</summary>

### Role
API Lifecycle Expert - specialist for REST/GraphQL APIs, TypeScript type systems, and cross-service contract management.

### Tools
| Tool | Usage |
|------|-------|
| Read | Read API files and type definitions |
| Grep | Consumer discovery (find all imports/usages) |
| Glob | Locate API/type files |
| Bash | TypeScript compilation, git diff, schema validation |

### What I Do
1. **Identify change type** - Additive, Modification, Removal
2. **Perform consumer discovery** - Find ALL usages of changed types/endpoints
3. **Create impact report** - List affected consumers, migration checklist

### Change Classification
| Type | Example | Breaking? |
|------|---------|-----------|
| Additive | New fields, new endpoints | Usually safe |
| Modification | Type changes, renamed fields | ⚠️ BREAKING |
| Removal | Deleted fields/endpoints | ⚠️ BREAKING |

### Output Format

**Model:** sonnet (balanced analysis + documentation)

</details>

<details>
<summary><strong>@builder</strong> - Full-Stack Developer</summary>

### Role
Senior Full-Stack Developer - specialist for React/Node.js/TypeScript implementation.

### Tools
| Tool | Usage |
|------|-------|
| Read | Read existing code, analyze specs |
| Write | Create new files |
| Edit | Modify existing files |
| Bash | Run TypeCheck, Tests, Lint |
| Glob | Find affected files |
| Grep | Search code patterns |

### What I Do
1. **Process specifications** from @architect and @api-guardian
2. **Implement code** in order: Types → Backend → Services → Components → Tests
3. **Pass quality gates** - TypeScript, tests, lint must pass

### Implementation Order
1. TypeScript Types (`shared/types/`)
2. Backend API (if relevant)
3. Frontend Services/Hooks
4. UI Components
5. Tests

### Code Standards
- Functional Components with Hooks (no Classes)
- Named Exports preferred
- Barrel Files (`index.ts`) for modules
- All Promises with try/catch
- No `any` Types

### Output Format

**Model:** sonnet (optimal for implementation)

</details>

<details>
<summary><strong>@validator</strong> - Code Quality Engineer</summary>

### Role
Code Quality Engineer - specialist for verification and quality assurance.

### Tools
| Tool | Usage |
|------|-------|
| Read | Read implementation reports |
| Grep | Verify consumer updates |
| Glob | Locate changed files |
| Bash | Run TypeCheck, Tests, Lint, git diff |

### What I Do
1. **Verify TypeScript compilation** - `tsc --noEmit`
2. **Verify tests** - All pass, adequate coverage
3. **Verify consumer updates** - Cross-reference @api-guardian's list
4. **Security checks** - No hardcoded secrets, auth on protected routes
5. **Performance checks** - No N+1 patterns, reasonable bundle size

### Checklist
- [ ] TypeScript compiles (no errors)
- [ ] Unit tests pass
- [ ] All listed consumers were updated
- [ ] No security issues
- [ ] No performance anti-patterns

### Output (Success)