wave-orchestration

Wave Orchestration Plugin

Iterative parallel orchestration for Claude Code

Combines Ralph Loop (persistent iteration) with swarm parallelism (multiple agents) to create waves of parallel work that compound until completion.

What It Does

        TIME -->

    Wave 1           Wave 2           Wave 3

    [A] [B]          [D] [E]          [G]
    [C]              [F]              DONE!

    Each wave spawns parallel agents.
    Each wave builds on prior results.
    Iterate until complete.

Installation

# Step 1: Add the marketplace
/plugin marketplace add sethdford/wave-orchestration

# Step 2: Install the plugin
/plugin install wave-orchestration@wave-orchestration

Alternative: Local Installation

git clone https://github.com/sethdford/wave-orchestration.git ~/wave-orchestration
/plugin install ~/wave-orchestration

Quick Start

# Check environment is ready
/wave-orchestration:wave-preflight

# Start wave orchestration with a goal
/wave-orchestration:wave "Build a REST API with user auth, CRUD endpoints, and tests" --max-iterations 15

# Check status
/wave-orchestration:wave-status

# Cancel if needed
/wave-orchestration:cancel-wave

Commands

Command	Description
/wave-orchestration:wave "goal"	Start wave orchestration
/wave-orchestration:wave-status	Check current iteration and progress
/wave-orchestration:cancel-wave	Stop the orchestration loop
/wave-orchestration:cancel-wave --clean	Stop and clean up output files
/wave-orchestration:wave-preflight	Verify environment is ready
/wave-orchestration:wave-clean	Remove wave output files
/wave-orchestration:wave-help	Show help and usage

Options

/wave-orchestration:wave "goal" [--max-iterations N] [--completion-promise TEXT] [--clean]

• --max-iterations N — Stop after N iterations (default: 20)
• --completion-promise TEXT — Phrase that signals completion (default: DONE)
• --clean — Clear previous wave outputs before starting

How It Works

The Complete Flow

┌─────────────────────────────────────────────────────────────────┐
│  /wave-orchestration:wave "Build a REST API"                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  setup-wave.sh                                                  │
│  ├── Creates .claude/wave-state.local.md (iteration: 1)        │
│  └── Creates .claude/wave-outputs/ directory                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Claude becomes the Orchestrator                                │
│  ├── Reads state file                                           │
│  ├── Decomposes goal into parallel tasks                        │
│  └── Spawns background agents via Task tool                     │
│       ├── Agent A: "Explore codebase" → wave-outputs/explore.md │
│       ├── Agent B: "Design schema" → wave-outputs/schema.md     │
│       └── Agent C: "Setup project" → wave-outputs/setup.md      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Claude tries to exit/complete                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  stop-hook.sh intercepts                                        │
│  ├── Checks for <wave-complete>DONE</wave-complete>             │
│  ├── If NOT complete → increment iteration, feed prompt back    │
│  └── If complete → allow exit, cleanup                          │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌──────────────────────────┐    ┌──────────────────────────┐
│  Not Complete            │    │  Complete                │
│  ├── iteration++         │    │  ├── Remove state file   │
│  └── Loop continues...   │    │  └── Exit successfully   │
└──────────────────────────┘    └──────────────────────────┘

Step-by-Step

1. Preflight Check (/wave-orchestration:wave-preflight)
   • Verifies jq and perl are installed
   • Checks .claude/ directory is writable
   • Confirms no active wave is running