wave-orchestrator

wave-orchestrator

Run your coding agent like an engineering org. Wave-based execution with dedicated sub-agents per phase, computed-style visual verification, no "tsc passes" lies.

A real /wave-orchestrator:wave-start run end-to-end, recorded on 0.2.x: 17 phases dispatched through dedicated sub-agents, TDD-RED → GREEN → visual gates → cleanup → checkpoint. Unattended.

The defaults of "vibe-coding" optimise for time-to-first-demo. This plugin optimises for time-to-shippable.

Table of contents

• How is this different?
• Why this exists
• Prerequisites
• Install
• Quickstart — your first wave
• What you get
• Hook enforcement (v0.2.0)
• The 10 invariants
• The 5 hard-won rules
• Repository structure
• Community
• Listed on
• Used in production by
• Talks & writing
• Status
• Contributing
• License

How is this different?

Both wave-orchestrator and Superpowers are serious frameworks built by people shipping real code with the host CLI. They optimise for different problems. If you're brainstorming a new product feature, Superpowers' creative flow is excellent. If you're shipping into a production codebase where "the agent said it's done" is not acceptable evidence, this plugin is for you.

Why this exists

Most single-agent workflows are one-shot: type a prompt, get a diff, ship it. That works for prototypes. It produces piles of fake-done features in production codebases — features whose tests pass but whose pages render blank, whose configs validate but whose runtime never reads them, whose data-theme="dark" attribute gets set on <html> while the screenshot stays light.

Wave-based execution treats the host CLI as an orchestration layer, not an autocomplete. Every phase of shipping a feature gets its own dedicated sub-agent with lean context — and the orchestrator gates each hand-off on real evidence (live stack screenshots, computed-style assertions, true end-to-end runs), not on "build clean".

This plugin packages that workflow.

Prerequisites

• The host CLI installed and authenticated. See its official documentation.
• A project to run waves against (any language / stack).
• For hook enforcement: Bash, Git, jq, flock, realpath and standard shell utilities. Missing hook prerequisites warn and allow; install them for the gates to operate.
• For UI waves: a browser-driving setup such as Playwright. The framework's TEET phase uses Playwright via the official MCP.
• Optional but recommended: the CodeRabbit plugin if you want the [CR] Code Review gate at Phase 3.5.

Install

# Add this repo as a plugin source
/plugins marketplace add https://github.com/Harshvardhan86/claude-wave-plugin

# Then install the plugin
/plugins install wave-orchestrator

After installation you should see two new slash commands available:

• /wave-orchestrator:wave-start
• /wave-orchestrator:wave-checkpoint

…and seven skills registered: wave-orchestrator, benefit-contract, ac-writer, design-reviewer, red-tests, green-impl, teet-verify.

Command names

Claude Code lists plugin commands under the plugin's name, so type /wave-orchestrator:wave-start and /wave-orchestrator:wave-checkpoint. Typing the bare /wave-start does not run the command. If you already installed the plugin, you don't need to do anything else: use the prefixed form in your existing setup.

Manual install (no marketplace)

If you'd rather install directly:

git clone https://github.com/Harshvardhan86/claude-wave-plugin.git \
  ~/.claude/plugins/local/wave-orchestrator

Restart the host CLI. The plugin should be picked up automatically.

Quickstart — your first wave

In any project you want to ship a feature in:

/wave-orchestrator:wave-start --demo "make the save button show a loading spinner"

What you'll see:

1. The orchestrator dispatches the AC sub-agent. .wave/ac.md lands with brutal, testable criteria.
2. DR sub-agent audits your design system's installed dist files, writes a per-route mockup, defines computed-style visual ACs. Any design-system gap becomes an OPEN item that pauses the wave.
3. RED writes failing tests against those ACs and prints the failure output. That's the point.
4. GREEN writes the minimum code, starts the live stack, runs the full test suite, takes a Playwright screenshot.
5. Visual approval gate. The orchestrator stops, shows you the screenshot, asks you to confirm before proceeding.
6. TEET runs cross-system computed-style assertions and produces the final verdict.

If the agent says "done" without showing you a screenshot, refuse the hand-off — that's the failure mode the plugin exists to prevent.

Once you've shipped two or three waves with --demo successfully, drop the flag:

/wave-orchestrator:wave-start "implement the new payment flow"

This invokes the canonical pipeline: 31 phase rows, 18 of which run in every full wave and 13 of which depend on what the wave is — [UIA] and [ES] on a wave that introduces new vocabulary, [BEN] and [BEN-CLOSE] on a wave that changes existing behaviour, [DR] on a wave that does either, [CR] when the code-review gate is opted in, and each [BF-*] row when the scan before it found something. Benefit contract, user-intent criteria, Brutal AC, Empty-State Scan, Silent Error Analysis, Brutal SEA, Dependency Audit, Output Alignment, Brutalised E2E, benefit verdict, version bump, commit, cleanup, checkpoint, dashboard — all dispatched as separate Agents with proper model-tier routing.

Before that first dispatch the command asks whether the wave introduces new vocabulary and whether it changes existing behaviour. Both answers are required: they decide four of the conditional rows, and an unanswered scope flag is never read as "no".

If context fills before completion, /wave-orchestrator:wave-checkpoint writes resume state to .wave/checkpoints/. A fresh session picks up exactly where you left off.

What you get

The full v2 framework (framework/)

This plugin vendors the complete Wave Execution Framework v2 — refined over months of production engineering work where bugs cost real money. A table of 31 phase rows: 18 run in every full wave, 7 are the [BF-*] fix rows that run only when the scan before them reported findings, and 6 depend on the wave's scope — [UIA] at 0.5 and [ES] at 4.2 (new vocabulary), [BEN] at 0.8 and [BEN-CLOSE] at 12.5 (changed behaviour), [DR] Design Review at 1.5 (UI or changed behaviour) and [CR] Code Review at 3.5 (optional, opt-in). Maximum surface per wave: 31 phases; the smallest full wave runs 18. Model-routed across three tiers (advisor, executor, mechanical), with hook-enforced invariants and worktree isolation for writing dispatches.

Demo on-ramps (skills/)

For first-time users, small features, and live-demo segments, the plugin ships six polished entry skills plus the orchestrator:

These run as /wave-orchestrator:wave-start --demo "<feature>". The recommended starting point.

Commands (commands/)

• /wave-orchestrator:wave-start <feature> — runs the full v2 pipeline (31 rows; 18 always, 13 conditional)
• /wave-orchestrator:wave-start --demo <feature> — runs the trimmed 5-phase entry subset
• /wave-orchestrator:wave-start --solo <feature> — runs a direct task with explicit models, commit guard, PreCompact checkpoint and token ledger
• /wave-orchestrator:wave-checkpoint — saves wave state to disk so an auto-compact (or laptop battery dying) doesn't kill the run

Hook enforcement (v0.2.0)

An active wave now has executable gates: phase order, valid phase/role/model, hand-off artifacts and markers, scope answers, design-review resolutions, UI screenshot approval and bug-fix strategy approval. Hooks keep the full/demo orchestrator focused on dispatch by gating tracked source edits, source reads, recognised build/test commands, nested dispatches and forks. Third phase/role rounds and output-token budget overruns require recorded approval.

Every main-session full/demo Agent dispatch starts its description with:

[W:<wave> P:<PHASE> R:<lead|executor|reviewer|scanner|writer>]

For example: [W:1 P:TDE-GREEN R:executor] implement AC-3. The tag is case-sensitive, begins at byte 0 and has exactly one space between fields. The first line of prompt is accepted as a fallback. Name model explicitly; full/demo routing requires at least the tier in hooks/phases.tsv.

• Full applies the full phase table and all process gates. DR runs for UI or behaviour-changing waves; CR is conditional on its scope flag.
• Demo applies the same rules to AC, DR, TDE-RED, TDE-GREEN, TEET. Skipped conditional or out-of-mode rows are looked through transitively so unfinished applicable predecessors cannot be bypassed.
• Solo (/wave-orchestrator:wave-start --solo) keeps only the explicit-model rule, commit