# Wave Coordinator

> Dispatch many subagents in coordinated waves with per-wave review. Use for "fan out agents", "wave dispatch", "batch agents", "generate N variations", or any fan-out beyond about five parallel subagents that needs batching, ordering, and result reconciliation.

- Skill: `b-open-io-prompts/wave-coordinator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add b-open-io-prompts/wave-coordinator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/b-open-io-prompts/wave-coordinator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: b-open-io (https://skillmd.com/u/b-open-io-prompts)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/b-open-io-prompts/wave-coordinator

---


# Wave Coordinator

Manage large-scale subagent dispatch through structured waves. Prevent context
exhaustion, preserve output diversity, and avoid duplication across batches.
On Claude, this can compose with
`Skill(superpowers:dispatching-parallel-agents)`; on Codex, use the native
subagent runtime. Wave Coordinator owns batching and diversity while the host
runtime owns thread creation.

## Prefer Native Workflows on Claude Code and Grok Build

Claude Code and Grok Build provide different native workflow engines. When the
current session exposes one and the user asked for a fan-out, prefer it over
hand-managed waves. Load only the applicable host guide:
[Claude Code](../coordinator/references/hosts/claude.md) or
[Grok Build](../coordinator/references/hosts/grok.md). Codex and OpenCode keep
the manual wave protocol below; see their respective Coordinator host guides.

## The Core Problem

Dispatching 10+ agents at once causes three failures:
1. **Context exhaustion** — spawning agents is expensive; running out mid-batch leaves work incomplete
2. **Homogeneous output** — identical prompts produce near-identical results, wasting compute
3. **Duplication** — later waves repeat what earlier waves already produced

Wave coordination solves all three.

## Waves inside the canonical flow

Before external implementation dispatch, load the shared contract at
`../coordinator/references/dispatch-contract.md` and follow it. Waves are how
its parallel-maker stage runs at scale; this skill adds only batching,
diversity, and reconciliation.

## Wave Sizing Rule

Use five concurrent subagents as a conservative planning default, then clamp
the wave to the host's advertised concurrency limit, currently free agent
slots, task shape, and remaining context/token budget. Treat any advertised
concurrency cap as an upper bound, not a promise that all slots are free. If
N exceeds the effective limit, divide the work into sequential waves:

```
N=12 → Wave 1 (5) → Wave 2 (5) → Wave 3 (2)
N=7  → Wave 1 (5) → Wave 2 (2)
N=5  → Wave 1 (5) — single wave, no split needed
```

Each wave completes fully before the next launches. Do not launch wave 2 until
all wave 1 agents have returned results.

Compute the effective wave size as the minimum of:

1. Five, unless the user or host deliberately chooses another wave size.
2. The host-advertised concurrency cap.
3. The number of currently free agent slots.
4. The number of genuinely independent remaining units.
5. The size the remaining context and token budget can safely synthesize.

Never assume a configured maximum means those slots are all available.

## Context Budget Check

Before launching each wave, estimate context budget:

1. Count tokens consumed so far (rough estimate: each spawned agent costs ~2-4k tokens in overhead)
2. Reserve at minimum 20% of the context window for synthesis and final output
3. If budget is tight, reduce the next wave size to 2-3 agents
4. If budget is critically low, stop dispatching and synthesize from what you have

**Hard rule:** Never launch a wave if you estimate it will hit the context limit before completion. Stop early and synthesize. Incomplete partial output is better than a context overflow crash.

## Directive Diversity

Each agent in a wave must receive **unique creative direction**. Do not send the same prompt to all agents in a wave.

### How to generate diverse directives

Before dispatching, generate N distinct emphasis angles for N agents. Vary along at least one axis:

| Axis | Example variations |
|------|--------------------|
| Tone | formal / conversational / terse / expansive |
| Focus | conciseness / error handling / edge cases / performance / examples |
| Perspective | beginner / expert / skeptic / advocate |
| Structure | prose / bullet list / table / code-first |
| Constraint | max 200 words / no jargon / no code / examples only |

**Example:** Generating 5 skill variants

```
Agent 1: "Write the most concise version possible. No examples, pure principle."
Agent 2: "Lead with 3 concrete examples, then derive the rule."
Agent 3: "Focus entirely on error cases and what can go wrong."
Agent 4: "Write for someone encountering this concept for the first time."
Agent 5: "Assume expert audience. Skip fundamentals, go deep on edge cases."
```

Never assign the same emphasis to two agents in the same wave.

## Deduplication Check

Before launching each wave after the first:

1. Read the output produced by all prior waves
2. Identify themes, approaches, or content already covered
3. Add exclusion instructions to the new wave's directives: "Do NOT produce a version similar to [description of prior output]"
4. If a prior wave already produced a high-quality result for a particular angle, skip that angle in subsequent waves

## Wave Progress Tracking

Maintain a mental (or written) wave ledger before each dispatch:

```
Wave 1: [5 agents] — launched, awaiting results
Wave 2: [5 agents] — pending (blocked on wave 1)
Wave 3: [2 agents] — pending (blocked on wave 2)

Output so far: [list of completed items]
Remaining: [list of items not yet produced]
```

Update the ledger after each wave completes. This prevents re-dispatching work already done and helps identify what the final synthesis pass needs.

## Host Dispatch Adapters

Before assigning a wave slot to a generic worker, match it against the roster
in `../deploy-agent-team/references/agent-roster.md` and pass the specific
`subagent_type` (e.g. `review:code-auditor`). Each wave slot picks a
roster agent before defaulting to a generic explorer/worker — use the generic
adapter only when no roster agent fits, and say so explicitly in the wave
ledger.

### Grok Build

Use `spawn_subagent` with the installed roster `subagent_type` (e.g.
`research:researcher`, `review:code-auditor`). `bopen-tools:<name>` aliases
also resolve when that plugin is installed. Confirm the current model name
and budget defaults in the live configuration before dispatching; the values
below were correct when written and may have moved. Native `agent().model` is
`grok-4.6` only. Do not dispatch `grok-4.5`. Run Sol as
`grok --single -m gpt-5.6-sol` inside a supervisor, or `codex exec`.
Prefer the native `workflow` tool over hand waves when the fan-out has
shape and the host guide confirms the primitive exists. Live children default
to 32; `agent_budget` defaults to 128.

### Claude Code

Use `Skill(superpowers:dispatching-parallel-agents)` when installed. Otherwise
use Claude Code's native Agent tool and plugin-qualified agent IDs. Preserve one
self-contained assignment per agent.

### Codex

Use Codex native subagents. Prefer installed `bopen_*` custom agents for named
specialists and built-in `worker` or `explorer` agents when no matching custom
adapter exists. Do not claim a `bopen_*` persona was used unless that adapter is
actually installed and its thread was spawned.

Check the live configuration for the current concurrency cap and delegation
depth instead of assuming fixed defaults. Keep wave coordination in the main
thread under the default depth. If a workflow genuinely requires nested
delegation, explain the token and runaway-fan-out risk before the user raises
the depth limit; never change global Codex configuration as part of this
skill.

Use `/agent` or the available agent activity view to inspect active and
completed threads. Account for already-open threads when calculating the next
wave.

### OpenCode

Use native OpenCode agents (`.opencode/agent(s)/<name>.md`) with the installed
roster id where one fits. `--agent <name>` selects a primary/all-mode agent,
not a subagent; invoke a real child from the primary with `@name`, as defined
by Coordinator. Pin and verify the parent model, then require a child marker
in the log before counting the run as delegated. There is no native multi-stage
workflow engine: the caller sequences dispatches and owns barriers.

## Integration with superpowers

Wave-coordinator handles **what** to dispatch and **when**. `Skill(superpowers:dispatching-parallel-agents)` handles **how** to spawn subagents. Use them together:

1. Use this skill to plan wave sizes, generate diverse directives, and track progress
2. Use `Skill(superpowers:dispatching-parallel-agents)` for the actual subagent spawning call syntax

If the superpowers plugin is not installed, use the current host's native
subagent runtime instead. Do not silently degrade: state whether the wave uses
Claude agents, Codex custom/built-in agents, or another explicitly authorized
worker lane.

## Worked Example

**Task:** Generate 8 variations of a landing page headline.

**Wave plan:**

Wave 1 (5 agents):
- Agent A: Urgency angle ("Limited time, immediate benefit")
- Agent B: Social proof angle ("Join 10,000+ users who...")
- Agent C: Problem-first angle ("Tired of X? Meet Y.")
- Agent D: Benefit-first angle ("Do X in half the time.")
- Agent E: Curiosity angle ("The surprising way to X")

Collect wave 1 output. Review for quality and coverage.

Wave 2 (3 agents — note: reduced from 5 because only 3 remain):
- Check wave 1 output first
- Agent F: Contrast angle not yet covered
- Agent G: Minimalist / single-word-impact angle
- Agent H: Question format not yet tried

Synthesize all 8 results. Rank by quality. Present top 3 with rationale.

## Key Rules

- Five agents per wave is the conservative planning default; clamp it to the host cap and currently free slots
- A host concurrency cap includes already-open threads; it is not a fresh allowance of that many new agents
- Keep orchestration at the main thread unless the live configuration explicitly permits nested delegation
- Check context budget before each wave
- Unique directive per agent — never duplicate prompts within a wave
- Read prior output before launching the next wave
- Stop and synthesize if budget runs low — do not push through to completion at the cost of a crash
- Wave 2+ directives must explicitly exclude angles already covered in prior waves