/waves

name: waves
description: WAVES — Workers · Aggregate · Verify · Extend — wave-based orchestration for Cursor. Decompose a big goal into independent slices, fan them out to isolated parallel subagents via parallel Task tool calls as a bounded "wave", verify each structured handoff, then synthesize, and extend into another wave only when warranted. Invoke explicitly with /waves; bounded by design to avoid runaway token loops. For big research, analysis, audits, and codebase or data exploration where one linear pass is slow. Formerly parallel-orchestrate; also fan out, parallelize, orchestrate subagents, multi-agent.
disable-model-invocation: true

WAVES — Workers · Aggregate · Verify · Extend (Cursor)

Run **wave-based orchestration** inside one local Cursor session. A **wave** is a bounded round of isolated agents working in parallel, then a round that verifies what came back, then a deliberate decision to build on it — not an open-ended loop. You are the **orchestrator**: you discover, decompose the goal into independent slices, fan them out to parallel **workers** (multiple `Task` tool calls in one message, backgrounded where the surface supports it), read each worker's structured **handoff**, verify it, and synthesize one deliverable. Workers are isolated and return exactly one handoff.

**The shape of every wave — WAVE:**

• **W — Workers.** Fan out isolated workers across disjoint slices (the bounded

parallel round).

• **A — Aggregate.** Wait for all of them and merge their structured handoffs at

the synthesize barrier.

• **V — Verify.** The moat: check the evidence behind each handoff before you

trust it.

• **E — Extend.** Decide — deliberately — whether to launch another wave, or stop.

A loop doesn't know when to stop; a wave does, because verification is the stop function. (Invoked explicitly with `/waves`: a run spawns more agents than usual, so it's opt-in, not auto-triggered.)

Waves runs **in place of** cloud orchestration. It adopts the principles the Cursor team proved out in their cloud `orchestrate` plugin — planners plan, workers hand off up, no cross-talk — but runs them on local subagents with zero setup: no separate cloud agents, no API keys, no runtime. Local subagent runs are the whole story here.

When to use

• A large goal that splits into **independent** slices (research areas, data

chunks, files/modules, audit dimensions).

• The work is mostly **read / research / analysis** — the safest thing to

parallelize locally (see "Parallel writes" for why).

• A single linear pass would be slow and you want real speedup from concurrency.

When to skip

• Small or linear tasks (just do them — fan-out overhead isn't worth it).
• Work needing tight back-and-forth or shared mutable state between steps.
• Parallel **edits to the same files** — local workers share one filesystem.

Core principles

Adapted from `orchestrate`. These keep the run converging without coordination.

1. **Orchestrator plans and synthesizes; it does not do the heavy lifting.** Discovering, decomposing, reading handoffs, and writing the final deliverable are your job. The bulk reading/research/analysis is delegated to workers. 2. **Workers are isolated.** A subagent has **no access to the user's message, your prior steps, or sibling workers.** Every worker prompt must be fully self-contained: goal context, its exact slice, where to look, what to return. 3. **One worker, one slice, one handoff.** The worker's final message is the only thing you read back. Define its exact shape (see `references/handoff-format.md`). 4. **Parallelism is for reading, not writing.** Local workers share the workspace; concurrent writes to overlapping paths corrupt each other. 5. **Continuous motion.** A handoff can reveal new work. Spawn a second wave (driven by a handoff gap *or* a new user request). Stop only when every slice is terminal and the synthesis is complete. 6. **Verify before you trust.** A worker's `Status: success` is a claim, not evidence. Check each handoff against something re-openable before folding it into the synthesis. See "Verification" below and `references/verification.md`. 7. **Decomposition is entropy reduction.** A vague goal is high-entropy — many plausible plans still fit it. Your first job is to shrink that space (dig locally, then pull from attached resources, then ask the user only if it pays) *before* you slice it; slicing a high-entropy goal yields overlapping, mis-sized slices. See "Entropy-first decomposition."

Entropy-first decomposition

Before you fan out, treat the goal as an **entropy-reduction** problem: shrink how many plausible interpretations and plans still fit what you know. A vague, high-entropy request ("build a Flappy Bird game", "make my app faster") doesn't slice cleanly yet — reduce the uncertainty first, then decompose the low-entropy version. Name what's uncertain, because the two kinds resolve differently:

• **Specification uncertainty** — what the *user* wants (ambiguous goal, missing

acceptance criteria, unstated constraints). Resolve by stating an explicit assumption and proceeding — or, only when a wrong guess is expensive, by asking.

• **Environment / knowledge uncertainty** — facts you don't have yet but *can*

get (repo shape, schema, API behavior, current docs, data size). Resolve by gathering, not by asking.

Spend the cheapest action that buys the most certainty first — an **information-gain ladder** — and aim each probe at the unknown whose answer eliminates the most plans: the highest-information question is the one that splits the surviving interpretations roughly in half, not the one easiest to look up.

1. **Dig locally first (cheap).** Tool calls in the main session (list, read the schema/README, grep, sample data). This *is* Step 0, framed as entropy reduction; it often collapses most of the uncertainty for free. 2. **Then pull from attached resources.** If the en