Wave Execution Framework v2 — Model-Routed

A multi-wave, multi-team engineering execution framework. Work is decomposed into waves; each wave runs a strict pipeline of 31 phase rows. 18 of them run in every full-mode wave. 13 are conditional: the seven [BF-*] rows run only when the scan before them reported findings, and six more depend on what the wave is — [UIA] and [ES] when the wave introduces new vocabulary, [BEN] when it changes existing behaviour, [DR] Design Review at Phase 1.5 when it ships UI (web, mobile, Storybook, CLI-TUI) or changes existing behaviour, [CR] Code Review at Phase 3.5 when the code-review gate is opted in, and [BEN-CLOSE] when [BEN] ran. Maximum surface per wave: 31 phases; the smallest full-mode wave runs 18. 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) host CLI / agent SDK primitives:

1. 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.
2. Team-as-dispatch-pattern. Nested subagents are not supported in the host CLI, 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.
3. 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

UIA=User-Intent Criteria (vocabulary waves) · BEN=Benefit Contract (behaviour-changing waves) · AC=Acceptance Criteria · ACB=Brutal AC · DR=Design Review (UI or behaviour-changing waves) · TDE=Test-Driven Execution · CR=Code Review (optional) · BC=Bug Capture · BF=Bug Fix · ES=Empty-State Scan (vocabulary waves) · BF-ES=Fix ES findings · 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 · BEN-CLOSE=Benefit Verdict · CL=Cleanup · CCP=Checkpoint · AD=Dashboard Update · E=Enabling · SA=Stream-Aligned · QG=Quality Gate · P=Platform

Wave pipeline (31 rows — 18 unconditional, 13 conditional)

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) or changes existing behaviour. 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. On a behaviour-changing wave with no UI it reviews the changed behaviour's surface and topology instead of its pixels. [DR] is skipped silently only when the wave neither ships UI nor changes behaviour; [TDE-RED] does not begin while any DR OPEN item is unresolved.

Scope rule (v0.3.0): a full-mode wave answers vocabulary and behaviour-change before its first dispatch, because [AC] names [UIA] and [BEN] as predecessors and an unanswered flag on a predecessor denies the successor. ui and cr may still be answered any time before [TDE-RED]. Demo mode is unchanged: its five phases and its gates are exactly as they were.

Benefit rule (v0.3.0): a wave whose value is an outcome rather than a computation states that outcome as one Benefit AC at [BEN] before any criteria are written, and gets a written verdict at [BEN-CLOSE] before version bump and commit. BENEFIT: UNDELIVERED is a label, not a block — the wave still closes, and the verdict is recorded in state and printed in the scorecard.

The 10 Invariant Rules (non-negotiable, verbatim from v1)

1. Lean context per unit — no "just in case" dumps.
2. Strict TDD — tests first, watch them fail, then implement.
3. Strict build order — build → app startup → tests.
4. Never assume on bugs — present options, user decides.
5. Save learnings globally after every bug fix (no duplicates, enhance existing).
6. Planning docs never committed to the code repo.
7. Auto-compact = STOP. Fresh terminal. Resume from checkpoint.
8. No team self-declares success — internal reviewer signs off first.
9. No hanging the system — teams must not deadlock or block indefinitely.
10. 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)