Wave Orchestration

Wave Orchestration Skill

Overview

Wave Orchestration combines two powerful patterns:

• Ralph Loop: Iterative self-improvement through repeated prompts
• Swarm Orchestration: Parallel agent execution for speed

The result: Iterative waves of parallel work that compound until completion.

Core Concept

        TIME -->

    +-----------------------------------------------------------+
    |  Wave 1           Wave 2           Wave 3                 |
    |                                                           |
    |  +---+ +---+      +---+ +---+      +---+                  |
    |  | A | | B |      | D | | E |      | G |                  |
    |  +---+ +---+      +---+ +---+      +---+                  |
    |  +---+            +---+                                   |
    |  | C |            | F |            COMPLETE               |
    |  +---+            +---+                                   |
    |                                                           |
    +-----------------------------------------------------------+

Each wave spawns multiple agents in parallel. Each wave builds on prior results.

When to Use Wave Orchestration

Good for:

• Complex multi-component features
• Tasks requiring both parallelism AND iteration
• Work where you can "walk away" and let it run
• Tasks with clear completion criteria
• Research spanning multiple areas simultaneously

Not good for:

• Simple single-file changes
• Tasks requiring constant human judgment
• One-shot operations
• Unclear requirements (clarify first!)

The Wave Cycle

1. ASSESS

Read state and agent outputs from previous wave:

• .claude/wave-state.local.md - Iteration counter
• .claude/wave-outputs/ - Agent results

2. DECOMPOSE

Identify remaining work and parallelization opportunities:

• What's done?
• What failed?
• What can run in parallel NOW?
• What's blocked?

3. SPAWN

Launch background agents for ALL unblocked work:

Task(
    subagent_type="general-purpose",
    prompt="WORKER preamble + task",
    run_in_background=True
)

4. SYNTHESIZE

Combine agent results:

• Read output files
• Update shared state
• Check completion criteria
• Prepare for next wave or complete

Key Commands

• /wave "goal" - Start wave orchestration
• /wave-status - Check current progress
• /cancel-wave - Stop the loop

State Files

.claude/
├── wave-state.local.md     # Iteration, config, prompt
└── wave-outputs/           # Agent results
    ├── explore-auth.md
    ├── implement-jwt.md
    └── test-results.md

Completion

Output <wave-complete>PROMISE</wave-complete> when:

• All required work is done
• Tests pass (if applicable)
• No blocking issues remain

Never lie to escape - the loop exists to ensure quality.

Patterns

See references/patterns.md for:

• Feature implementation pattern
• Research/exploration pattern
• Test generation pattern
• Refactoring pattern

Philosophy

1. Iteration beats perfection - Let waves refine the work
2. Parallel beats sequential - Spawn many agents
3. Failures inform - Each failure teaches the next wave
4. State persists - Agents see prior work in files
5. Completion is earned - Only exit when truly done