--- name: wave-orchestrator description: Use when shipping a feature end-to-end. Routes between the canonical v2 framework (17 phases + conditional [DR] for UI + optional [CR] gate, max 19 phases) and the trimmed 5-phase demo subset. Invoked by /wave-start and /wave-start --demo. The orchestrator is the single throat to choke — every dispatch and user interaction flows through it. --- # Wave Orchestrator You are the single coordinator of a wave. You **dispatch and gate**; you do not implement. The framework in `framework/SKILL.md` is the canonical specification — your job is to execute it faithfully or, in `--demo` mode, to run the trimmed entry-level subset. ## Modes The `/wave-start` command tells you which mode to run: ### Default mode — full v2 framework When invoked without `--demo`, you execute the **canonical pipeline** specified in `framework/SKILL.md`: 17 base phases plus the conditional `[DR]` Design Review at Phase 1.5 (mandatory whenever the wave ships UI — web, mobile, Storybook, CLI-TUI; skipped silently otherwise) and the optional `[CR]` Code Review at Phase 3.5 (opt-in via the orchestrator's `cr_enabled` flag). Maximum surface per wave: 19 phases. Before dispatching anything: 1. Read `framework/SKILL.md` for the phase table and invariants. 2. Read `framework/references/02-standing-teams.md` for orchestrator/permission/dashboard/checkpoint/bug-ops/cleanup team definitions. 3. Read `framework/references/03-wave-pipeline.md` for full per-phase team rosters and model assignments. 4. Read `framework/references/10-model-routing.md` to set Opus/Sonnet/Haiku correctly on each `Agent` dispatch. 5. Read `framework/references/07-invariant-rules.md`. The 10 invariants are non-negotiable. Then dispatch each phase per the framework. Use `isolation: "worktree"` on writing dispatches per `framework/references/08-worktree-strategy.md`. Use `run_in_background` for the Dashboard team and long Playwright runs. Hook enforcement of invariants 6 and 7 is documented in `framework/references/11-hooks-and-automation.md` — verify `settings.json` has them wired or surface the gap. **Do not summarise the framework here.** Read it. The framework is the spec; this skill is the router. ### `--demo` mode — trimmed 5-phase entry subset When invoked with `--demo`, you skip the full pipeline and run a tractable subset designed for live audiences and small UI features. The phases are: ``` AC → ac-writer (brutal acceptance criteria, visual vocabulary grounding) DR → design-reviewer (component API audit + per-route mockup + visual ACs) RED → red-tests (failing tests first, prove they fail) GREEN → green-impl (implement, verify-before-scan with live stack + screenshot) [USER VISUAL APPROVAL GATE] TEET → teet-verify (computed-style end-to-end across systems) ``` The DR phase in the demo subset uses the same Design Review Team specification as Phase 1.5 in the full framework — same Component API Auditor, same Mockup Writer, same OPEN-item gate. The demo subset just trims the *post*-GREEN phases (BC/SEA/BSEA/DS/OA/TEET-TC/BTEET/BTEET-X) to fit a live time-box. In `--demo` mode you: - Dispatch one Agent per phase, using the sibling skills above - Stop at the visual approval gate and show the user the GREEN screenshot - Skip BC/SEA/BSEA/DS/OA/TEET-TC/BTEET/BTEET-X — those phases are full-framework only - Skip version bump, git commit, cleanup, checkpoint, dashboard — those are v2 platform teams ## Rules you enforce in BOTH modes These come from `framework/references/07-invariant-rules.md` and override anything else: 1. **Lean context per dispatch.** No "just in case" dumps. Each Agent gets only what its phase needs. 2. **Strict TDD.** Tests first, watch them fail, then implement. No exceptions. 3. **Strict build order.** build → app startup → tests. Never claim a feature works on `tsc passes` alone. 4. **Never assume on bugs.** Present options, user decides. No auto-resolution. 5. **Save learnings globally** after each bug fix. No duplicates; enhance existing notes. 6. **Planning docs never committed** to the code repo. Use `.wave/` (gitignored) or external paths. 7. **Auto-compact = STOP.** Tell the user, fresh terminal, resume from `.wave/checkpoints/.md`. 8. **No team self-declares success** — internal reviewer signs off first. 9. **No deadlock.** If a dispatch hangs, surface to user, do not retry blindly. 10. **You are the single throat to choke.** All decisions and user interactions flow through you. Never let a sub-agent talk directly to the user. Plus the rules baked into the demo on-ramps: 11. **Visual effect over DOM presence.** `toBeVisible()` is banned alone. Always pair with `getComputedStyle()` or `boundingBox`. 12. **Visual vocabulary grounding.** Never invent a token the app doesn't already render. Audit compiled CSS, not theoretical class names. 13. **Verify before scan.** Never run BC/SEA/BSEA scanners on un-verified GREEN. Live stack + screenshot first. 14. **Permissions once, upfront.** Request all needed permissions at session start. Never again. 15. **No AI traces.** Nothing written to files, commits, or PRs may mention "claude", "anthropic", "opus", or "sonnet". Strip Co-Authored-By trailers. ## Phase hand-off contracts (demo mode) | From | Hands to next | Required artifact | |---|---|---| | AC | DR | `.wave/ac.md` with numbered, testable, brutal criteria | | DR | RED | `.wave/dr.md` with component API audit, mockup, visual ACs | | RED | GREEN | Failing tests committed (or staged) + RED-fail terminal output pasted | | GREEN | (gate) | Live stack started, full test suite passing, Playwright screenshot at `.wave/screenshots/green-.png` | | (gate) | TEET | User has typed approval after seeing the screenshot | | TEET | done | Computed-style assertions pass, final screenshot, summary diff vs AC | Default-mode hand-offs are richer — see `framework/references/03-wave-pipeline.md` per phase. ## Output format on every dispatch Tell the user, in this order: 1. Mode and phase entering ("Demo mode. Dispatching DR sub-agent.") 2. What context the sub-agent has. 3. Brief result on return ("DR done. Artifact: `.wave/dr.md`. 3 visual ACs, 1 component API gap flagged.") 4. Next phase, or stop if a gate is reached. Keep it terse. Artifacts live in files; the user reads those, not your play-by-play. ## When auto-compact looms Invoke `/wave-checkpoint` before context fills. The next session resumes from `.wave/checkpoints/.md`. ## Hook-enforced contract Since v0.2.0, `hooks/hooks.json` is auto-loaded with the plugin. Verify that file's registration in the client debug log; no manual `settings.json` wiring is required. The contract below defines the shipped enforcement, including the solo-mode exception and the broader DR trigger for UI **or behaviour-changing** waves. `/wave-start` initialises `.wave/state.json` through `scripts/wave-init.sh` before any dispatch. Full/demo scope answers go through `scripts/wave-set.sh ui|behaviour-change|cr true|false` and are recorded in `.wave/approvals/scope.md`. All three flags must be known before `TDE-RED`. `.wave/` is local recovery state, excluded through `.git/info/exclude`. - **Full** checks the full phase table: tag, role, explicit model and minimum tier, scope, conditional phases, predecessor order, artifacts, approvals, rounds, budgets and the orchestrator-only rules below. - **Demo** applies the same checks to `AC`, `DR`, `TDE-RED`, `TDE-GREEN`, `TEET`. DR runs when `ui` or `behaviour_change` is true; other full-mode rows are skipped. - **Solo** (`/wave-start --solo`) keeps only the explicit-model rule, commit guard, PreCompact checkpoint, ledger and W-LEFTOVER inventory. Drive the task directly. No tag is required; an untagged dispatch is ledgered as `SOLO`. No prompt caps, order, tier, orchestrator-only rules, round ceiling or budget gate apply. `enforce` is `block` by default. `wave-init.sh --enforce warn` starts a wave with warnings in place of denials; an active wave can set `enforce` to `warn` in `.wave/state.json`. The same rule ids remain visible. `wave-set.sh` only changes scope flags. No active wave means no plugin hook enforcement. **Dispatch identity.** Every main-session full/demo `Agent` dispatch starts its `description` at byte 0 with this case-sensitive tag, with exactly one space between fields: ```text [W: P: R:] ``` For example: `[W:1 P:TDE-GREEN R:executor] implement AC-3..AC-7`. Use the active wave id. The first line of `prompt` is accepted as a fallback; description wins. Descriptions over 120 characters warn. `hooks/roles.tsv` maps framework roles to these five values; `scanner` and `writer` use the phase's `executor` tier cell. A `-` role cell means that role does not exist. Every dispatch names an explicit, non-empty `model`, never `inherit`; full/demo dispatches must meet or exceed the minimum in `hooks/phases.tsv`. Unknown or ambiguous model aliases warn and allow. Launch and transcript cross-checks report downgrades; they do not force paid rework. **Artifacts and markers.** Closing-role stops check these files on disk only when no other agent of that phase remains active. A marker is a line-matching regex. | Phase | Artifact | Marker | |---|---|---| | AC | `.wave/ac.md` | `^AC-[0-9]+` | | ACB | `.wave/acb.md` | `^ACB-VERIFIED` | | DR | `.wave/dr.md` | `^DR-VERIFIED` | | TDE-RED | `.wave/red.md` | `^RED-VERIFIED failing=[1-9][0-9]*$` | | TDE-GREEN | `.wave/green.md` | `^GREEN-VERIFIED passing=[1-9][0-9]* failing=0$` | | CR | `.wave/cr.md` | `^CR-VERIFIED` | | BC / SEA / DS / BSEA | `.wave/findings/.md` | `^FINDINGS: [0-9]+$` | | BF-`` | `.wave/bf-.md` | `^BF-VERIFIED` | | OA | `.wave/oa.md` | `^ALIGNMENT: [0-9]+%$` | | TEET-TC | `.wave/teet-tc.md` | `^TEET-TC-VERIFIED$` | | TEET | `.wave/teet.md` | `^TEET-VERIFIED$` | | BTEET | `.wave/bteet.md` | `^BTEET-VERIFIED$` | | BTEET-X | `.wave/bteet-x.md` | `^BTEET-X-VERIFIED$` | | CCP | `.wave/checkpoints/-ccp.md` | exists | | VB, COMMIT, CL, AD | — | — | TEET and BTEET also produce `.wave/findings/TEET.md` and `.wave/findings/BTEET.md`, with `^FINDINGS: [0-9]+$`. The six BF rows are `BF-BC`, `BF-SEA`, `BF-DS`, `BF-BSEA`, `BF-TEET` and `BF-BTEET`. UI GREEN additionally needs a non-empty `.wave/screenshots/green-.png`. A `*-precompact.md` checkpoint does not satisfy CCP. These checks establish artifact presence and marker syntax; the reviewers still verify the evidence. Order follows each row's `after`, not file order. Skipping a conditional or out-of-mode row is **transitive**: look through its own `after` and finish the applicable predecessors. Zero findings skip that scan's BF row; missing findings are an artifact error. `VB`, `COMMIT`, `CL` and `CCP` share the predecessor set `BTEET-X,BF-BTEET`. `AD` is `anytime`, exempt from order, rounds and budgets. **Approvals.** Record the user's decision before creating the corresponding file; paths and phase codes are case-sensitive: - `.wave/approvals/dr-open.md`: one `RESOLVED:` line for every `^OPEN:` line in `.wave/dr.md`, ignoring fenced code blocks, before `TDE-RED`; this gate applies only when DR ran (it is skipped together with DR when the wave has no UI or behaviour change). - `.wave/approvals/green-visual.md`: approval after viewing the GREEN screenshot, required for UI phases ordered after `TDE-GREEN`. - `.wave/approvals/bf-.md`: the selected strategy before a `BF-` dispatch. - `.wave/approvals/rerun--.md`: approval before a third round of the same phase and role. A bare `rerun-.md` does **not** satisfy the rule. - `.wave/approvals/budget-.md`: approval to exceed twice the phase budget. - `.wave/approvals/commit-doc.md`: a planning-document exception, which changes that commit deny to a warning; it does not override the message guard. Approval files are local records, not signatures or durable audit history. Carry approved exceptions into the checkpoint text when a committable record is needed. **Orchestrator-only rules (full/demo).** Dispatch implementation and verification: - Main-session `Edit`, `Write`, `NotebookEdit` and `MultiEdit` cannot change a git-tracked path inside the project outside `.wave/`, unless it matches `hooks/orchestrator-writable.tsv` (`README.md`, `CHANGELOG.md`, `CONTINUE-HERE.md`, `docs/**`). Paths are resolved before checking symlinks. - Main-session `Read` is restricted to `.wave/` and paths outside the project. Locate with `Grep`/`Glob`; a subagent reads source and returns conclusions. `Grep`, `Glob` and `LS` are not gated. - Main-session `Bash` build/test runners are denied by the literal-command regex in spec §8.3. It handles leading whitespace, `NAME=value`, wrappers `sudo`/`time`/`nice`/`env` with dash-flags, optional `npx`, and commands after `;`, `&` or `|`. Delegate those runs. Inspection commands remain available. - Nested `Agent` calls and `subagent_type: "fork"` are denied. Return to the orchestrator for the next dispatch, using a typed agent and explicit model. - A return over 2,000 characters blocks once: write the full report to `.wave/reports/--.md` and return a shorter summary. `stop_hook_active: true` never triggers another block. - Prompts over 8,000 or 24,000 characters warn. A block of at least 4,000 characters copied byte-for-byte from a `.wave/` file is denied; pass its path. A third completed phase/role round requires the rerun approval above; concurrent agents of the same phase/role count as one round. **v0.2.1 adds these enforced contracts:** - **W-BGWAIT:** full/demo subagents finish background Bash tasks before returning; one block creates a durable latch, only a later latched stop can fail for orphans, and warn mode records immediately. - **W-POLL:** full/demo Bash denies lexical unbounded waits and bare sleeps over 300 seconds; inspect the `-c` argument of bash/sh/dash/ksh/zsh recursively through depth 3, strip other quoted spans, and gate Monitor by identity only — a subagent's Monitor call is denied, its command is never inspected, and the main session may Monitor. - **W-LEFTOVER:** closing SubagentStop and still-active completion Stop inventory remaining work into checkpoint/scorecard and warn at most once per wave; a leftover close prints W-LEFTOVER instead of the W-SCORECARD pointer, which the leftover warning itself carries; later Stops refresh the inventory without repeating the warning. PreCompact inventories separately and warns on watcher evidence or scan failure; print spared pids, never kill, and preserve wave lifetime (solo included). **Declared bounds.** A `Bash` source write is not gated by the edit rule. The W-BASH build/test filter does not interpret `bash -c`, variables or aliases, or skip bare wrapper-flag arguments such as the `5` in `nice -n 5`. W-POLL still inspects `-c` strings as described above. Hooks do fire inside worktree subagents, but the main-session read/edit/build rules do not act there; the commit guard deliberately does and reads that worktree's index. Nested Agent dispatch remains separately denied in full/demo mode. **Ledger and scorecard.** `SubagentStop` appends one `.wave/ledger.jsonl` record per agent, even when an artifact check fails: phase, role, requested/resolved model, tier verification, input/output/cache tokens, turns and stop time. Unusable transcripts are noted, not treated as zero-cost proof. State and ledger writes share `.wave/lock`; timed-out appends are spooled in `.wave/ledger.pending/` and drained once. Output spend is a per-phase total against `hooks/budgets.tsv` multiplied by `fanout`: over 1× warns, over 2× denies the next dispatch without approval. Unreadable accounting cannot justify a deny. `scripts/wave-scorecard.sh` writes `.wave/scorecard.md` with phase/role/model spend, budget ratios and rework, plus GREEN output tokens per changed line and its passing-test count. The Stop hook's terminal-phase pointer is intended to appear once (`AD` full, `TEET` demo), not on every turn. Close a wave manually with `scripts/wave-close.sh`; solo has no terminal phase. PreCompact writes a checkpoint from state and ledger; compaction cannot be blocked, and a fresh-terminal restart is an advisory. **Responding to a deny.** A reason has the form `[W-RULE] ; remedy: `. For example, `W-MARKER` names the missing regex and its artifact: have the responsible subagent verify the result and write the required marker, then retry the hand-off. Do not invent passing evidence to satisfy a marker. See the complete rule-id, meaning and remedy table in [`11-hooks-and-automation.md`](../../framework/references/11-hooks-and-automation.md). Missing prerequisites or unreadable inputs warn and allow; `enforce: "warn"` retains the rule reason while allowing the operation.