# Wave Playbook

## How Waves Work

Each spec is broken into **waves** — vertical slices that deliver testable progress. A wave is never just "backend" or "frontend" — it's a complete slice that can be verified.

## Wave Lifecycle

```
1. Read spec + plan + contract for the wave
2. Spawn implementation agent(s) with VERBATIM prompts from execution-plan.md
3. Agent implements + runs quality gates
4. Spawn reviewer agent to verify contract adherence
5. If PASS → update PROGRESS.md → next wave
6. If FAIL → max 2 fix attempts → escalate to user
```

## Quality Gate Tiers

### Tier 1: After Every Change
```bash
uv run ruff check src/ tests/ --fix
uv run ruff format src/ tests/
uv run mypy src/exokit/
uv run pytest tests/ -v
```

### Tier 2: After Every Wave
```bash
# All Tier 1 gates plus:
uv run pytest tests/ -v --cov=src/exokit --cov-report=term-missing
# Coverage must be >= 80%
```

### Tier 3: Before Spec Completion
- Code review agent grades all changed files (must be B or above)
- Architecture review on public API surface
- All templates render correctly with sample data

## Rules

1. **Never skip the reviewer between waves.** Even if you're confident. The reviewer catches what you miss.
2. **Never improvise agent prompts.** Copy from execution-plan.md VERBATIM. The prompts are crafted to give agents exactly the right context.
3. **Never implement and review in the same agent.** The implementer cannot review their own work.
4. **Update PROGRESS.md after every wave.** This is the session resilience mechanism — if context is lost, PROGRESS.md tells the next session where we are.
5. **Escalate on second failure.** If a quality gate fails twice, don't brute-force it. Ask the user.

## Session Resilience

If a session is lost or the user starts a new conversation:

1. Read `CLAUDE.md` — understand the project
2. Read `docs/PROGRESS.md` — understand where we are
3. Read the current spec's `contract.md` — understand what's left
4. Continue from the next pending wave

The combination of CLAUDE.md + PROGRESS.md + contract.md gives any session enough context to resume without repeating work.
