| name | wave-execution-framework-v2 |
| description | Use when executing multi-wave engineering work needing strict TDD, bug-capture/fix split, quality gates, and orchestrated teams with per-agent Opus-advisor / Sonnet-executor model routing. |
| effort | xhigh |
Wave Execution Framework v2 — Model-Routed
A multi-wave, multi-team engineering execution framework. Work is decomposed into waves; each wave runs a strict 17-phase pipeline plus two conditional gates: [DR] Design Review at Phase 1.5 (mandatory when the wave ships UI — web, mobile, Storybook, or CLI-TUI) and [CR] Code Review at Phase 3.5 (optional, opt-in). Maximum surface per wave: 19 phases. Enforced by specialized subagent teams (Stream-Aligned, Quality Gate, Platform, Enabling). The orchestrator is the single point of coordination and the single throat to choke.
v2 preserves every phase, invariant, and cardinal rule from v1 and adds three changes that realize the framework against the current (2026) Claude Code / Agent SDK primitives:
- Model routing. Every dispatch specifies its model on the
Agent tool. Opus = advisory (plan, critique, decide). Sonnet = executor (write code, run tests, scan, fix). Haiku = mechanical (dashboard render, version bump). See references/10-model-routing.md.
- Team-as-dispatch-pattern. Nested subagents are not supported in Claude Code, so v2 re-expresses every L2 "team" as either a single Agent dispatch carrying Lead + Executor + Reviewer personas, or a sequence of dispatches the orchestrator coordinates. Fresh-eyes hardening (
[ACB], [BSEA], [BTEET]) is enforced by separate dispatches with only the prior output in context. See references/01-architecture.md.
- Native platform primitives.
isolation: "worktree" on writing dispatches; run_in_background for Dashboard and long Playwright runs; PreCompact / PostToolUse / PreToolUse hooks to enforce invariants; TaskCreate replaces tasks/todo.md; ToolSearch gates the per-phase tool surface. See references/09-platform-deltas.md, references/11-hooks-and-automation.md, references/12-mcp-and-plugins.md.
When to use
- Multi-wave projects (3+ discrete vertical slices of value).
- Work requiring strict TDD (RED → GREEN) and user-approved bug fixes.
- Projects where silent errors, skipped tests, or context pollution have burned you before.
- Cross-language binding work (N-API / FFI / WASM) — see
references/05-language-binding-rules.md.
- Any time quality gates (dependency audit, silent-error scan, brutal E2E) must block release.
When NOT to use
- Single-file edits, typo fixes, renames.
- Research-only tasks with no code changes.
- Prototypes where discipline intentionally slows exploration.
Abbreviations
AC=Acceptance Criteria · ACB=Brutal AC · DR=Design Review (UI waves only) · TDE=Test-Driven Execution · CR=Code Review (optional) · BC=Bug Capture · BF=Bug Fix · SEA=Silent Error Analysis · BSEA=Brutal SEA · DS=Dependency Scan · OA=Output Alignment · TEET=True E2E Testing · TEET-TC=TEET Test Case Design · BTEET=Brutal TEET · BTEET-X=Brutal TEET Execution · CL=Cleanup · CCP=Checkpoint · AD=Dashboard Update · E=Enabling · SA=Stream-Aligned · QG=Quality Gate · P=Platform
Wave pipeline (17 sequential phases + 2 conditional gates)
| # | Code | Phase | Team | Topology | Lead / Executor / Reviewer model |
|---|
| 1 | [AC] | Acceptance Criteria | AC Team | E | Opus / Sonnet / Opus |
| 1.2 | [ACB] | Brutal AC Review (fresh eyes) | AC Hardening Team | E | Opus / Opus / Opus |
| 1.5 | [DR] | Design Review (mandatory for UI waves, skipped otherwise) | Design Review Team | E | Opus / Sonnet / Opus |
| 2 | [TDE-RED] | Write tests, verify FAIL | TDD-RED Team | SA | Sonnet / Sonnet / Sonnet |
| 3 | [TDE-GREEN] | Implement, verify PASS (isolation: worktree) | TDD-GREEN Team | SA | Sonnet / Sonnet / Opus |
| 3.5 | [CR] | Code Review gate (CodeRabbit — optional) | CodeRabbit Plugin | QG | plugin-managed |
| 4 | [BC] | Bug Capture | Bug Capture Team | QG | Sonnet |
| 4.1 | [BF-BC] | Fix BC findings (user approves) | Bug Fix Team | SA | Opus / Sonnet / Opus |
| 5 | [SEA] | Silent Error Scan | Silent Error Team | QG | Sonnet |
| 5.1 | [BF-SEA] | Fix SEA findings | Bug Fix Team | SA | Opus / Sonnet / Opus |
| 6 | [DS] | Dependency Validation | Dependency Audit Team | QG | Sonnet |
| 6.1 | [BF-DS] | Fix DS findings | Bug Fix Team | SA | Opus / Sonnet / Opus |
| 7 | [BSEA] | Brutal Silent Error Scan (fresh eyes) | SEA Hardening Team | QG | Opus / Opus / Opus |
| 7.1 | [BF-BSEA] | Fix BSEA findings | Bug Fix Team | SA | Opus / Sonnet / Opus |
| 8 | [OA] | Output Alignment vs AC | Output Alignment Team | E | Opus / Opus / Opus |
| 9 | [TEET-TC] | E2E Test Case Design | TEET Test Design Team | E | Opus / Sonnet / Opus |
| 10 | [TEET] | True End-to-End Testing (Playwright MCP for UI) | E2E Team | SA | Sonnet / Sonnet / Sonnet |
| 10.1 | [BF-TEET] | Fix TEET findings | Bug Fix Team | SA | Opus / Sonnet / Opus |
| 11 | [BTEET] | Brutal E2E Hardening (fresh eyes) | E2E Hardening Team | QG | Opus / Opus / Opus |
| 12 | [BTEET-X] | Execute brutalized E2E tests | E2E Execution Team | SA | Sonnet / Sonnet / Sonnet |
| 12.1 | [BF-BTEET] | Fix BTEET findings | Bug Fix Team | SA | Opus / Sonnet / Opus |
| 13 | — | Version Bump (parallel with 14) | Standalone subagent | — | Haiku |
| 14 | — | Git Commit (specific files only) | Standalone subagent | — | Sonnet |
| 15 | [CL] | Cleanup | Cleanup Team | P | Sonnet |
| 16 | [CCP] | Save Checkpoint | Checkpoint Team | P | Sonnet |
| 17 | [AD] | Dashboard Update (run_in_background) | Dashboard Team | P | Haiku |
Fresh-eyes rule — unchanged from v1: every hardening phase ([ACB], [BSEA], [BTEET]) must be a separate dispatch from the team that did the first pass. Every [BF-*] runs only if its preceding scan found bugs, and every fix strategy is user-approved — never auto-resolved.
Design Review rule (Phase 1.5): [DR] is mandatory for any wave that ships UI (web, mobile, Storybook, CLI-TUI). It is a separate team from [AC] and [ACB] because its inputs (installed design-system dist files, compiled CSS, route topology) and its outputs (component API audit, per-route mockup, computed-style visual ACs, gaps as OPEN items) are categorically different from functional acceptance criteria. [DR] skipped silently on non-UI waves; [TDE-RED] does not begin while any DR OPEN item is unresolved.
The 10 Invariant Rules (non-negotiable, verbatim from v1)
- Lean context per unit — no "just in case" dumps.
- Strict TDD — tests first, watch them fail, then implement.
- Strict build order — build → app startup → tests.
- Never assume on bugs — present options, user decides.
- Save learnings globally after every bug fix (no duplicates, enhance existing).
- Planning docs never committed to the code repo.
- Auto-compact = STOP. Fresh terminal. Resume from checkpoint.
- No team self-declares success — internal reviewer signs off first.
- No hanging the system — teams must not deadlock or block indefinitely.
- The orchestrator is the single throat to choke — all decisions and user interactions flow through it.
Invariants 6, 7 are now hook-enforced in v2; see references/11-hooks-and-automation.md.
Reference index (load on demand)
