workflow-wave-dispatch

Workflow Wave Dispatch

Sequential waves, not parallel fan-out, when the work has real dependencies. This skill is the workflow-side scheduling view: which waves exist, what order they run in, and what to do when a gate fails.

The dispatch discipline — the per-wave gate set, the research-before-WO gate, the ~10-line inline-fix threshold, the stable shared-file exclusion list, and Return Contract reuse — lives in agent-patterns-plugin:wave-based-dispatch. This skill does not restate it; it schedules around it.

When to Use This Skill

parallel-agent-dispatch is the right call inside a wave. Waves are the layer above it — they answer "which agents run together, in what order" before parallel-agent-dispatch answers "how each agent is briefed."

Wave Structure

Wave 1 (research)
  └── Single agent or small fan-out → artefacts in tmp/
      └── Gate: artefacts exist, agent returned a clean contract

Wave 2 (foundation)
  └── Parallel fan-out against wave-1 artefacts
      └── Gate: build green, tests green, tracker advanced

Wave 3 (extension)
  └── Parallel fan-out referencing wave-2 types/APIs
      └── Gate: smoke recipes pass, clean tree

Wave N …

Each wave is itself a parallel-agent-dispatch call. This skill covers wave scheduling: which waves exist, what gates between them, what to do when a gate fails. The gate set itself is the six-gate table in agent-patterns-plugin:wave-based-dispatch § Six-Gate Verification Table.

Scheduling Heuristics

• Put the lock-holder (Ghidra, migration, bulk taskwarrior) alone in its wave. See agent-patterns-plugin:exclusive-lock-dispatch.
• Put the research wave before any implementation wave that depends on its artefacts (the research-before-WO gate in agent-patterns-plugin:wave-based-dispatch explains why the downstream WO's size collapses once the probe lands).
• Put foundation (new types, new APIs, new files that others will import) in the earliest implementation wave.
• Put extensions (new call sites, new tests, new docs) in later waves.
• Inside a single wave, fan out to the widest safe parallelism that parallel-agent-dispatch allows.

Schema-Constrained Agents Under Rate-Limit Storms

Schema-constrained agent() calls — agents bound to a StructuredOutput schema — are fragile under rate-limit storms (issue #1463). A rate-limit hit that occurs before the agent emits its StructuredOutput is reported as a hard parse failure: the caller receives no partial output and the agent's work is unrecoverable from the schema path, even when substantial work was done inside the agent's context window.

Why this matters at the wave layer. A wide wave of schema-bound agents (e.g. 8–10 concurrent structured-output extractors) creates a rate-limit storm risk. If the storm wipes half the wave, the gate fails and the orchestrator has no partial results to salvage — unlike a plain agent() call where the worktree holds the work.

Blast-radius containment — apply at wave-scheduling time:

For concurrency caps, wave-splitting mechanics, and the recovery-dispatch routine for rate-limited agents, see agent-patterns-plugin:parallel-agent-dispatch § Concurrent rate-limit risk and its references/failure-recovery.md § Concurrent rate-limit risk — recovery-dispatch routine. (Named, not path-linked: a relative path into another plugin is dead for anyone who installed only one of the two — .claude/rules/skill-consolidation.md § 2.) Do not duplicate that guidance here.

Gate Failure: Roll Back, Don't Paper Over

Every wave ends with a gate (the six-gate set lives in agent-patterns-plugin:wave-based-dispatch). No brief for wave N+1 is written before wave N's gate passes.

A gate failure rolls back to "fix in place, retry the gate" — never to "dispatch wave N+1 and paper over the failure." If the wave as a whole is un-recoverable, revert it and re-brief.

Whether a returned issue is fixed inline or filed as a follow-up WO for the next wave is the ~10-line inline-fix threshold — see agent-patterns-plugin:wave-based-dispatch § The ~10-Line Inline-Fix Threshold.

Shared Mechanics (owned by wave-based-dispatch)

These are defined once in agent-patterns-plugin:wave-based-dispatch and referenced — never restated — when scheduling waves:

Quick Reference

Orchestrator Checklist (scheduling)

• Waves enumerated with explicit dependencies identified
• Research wave scheduled first if any scope depends on tool output
• Lock-holder isolated in its own wave
• Foundation scheduled before extensions
• A gate defined for every wave boundary (set per wave-based-dispatch)
• No brief for wave N+1 written until wave N's gate passes
• Gate failure → fix in place and retry, never dispatch-over

Common Scheduling Mistakes

Related

• agent-patterns-plugin:wave-based-dispatch — the dispatch discipline and the shared between-wave gate set this skill schedules around
• agent-patterns-plugin:parallel-agent-dispatch — intra-wave dispatch contract
• agent-patterns-plugin:exclusive-lock-dispatch — pre-dump pattern for lock-contending waves
• agent-patterns-plugin:agent-teams — implicit-team / SendMessage mechanics that waves sit on top of
• tools-plugin:cli-smoke-recipes — smoke-gate mechanics between waves
• .claude/rules/parallel-safe-queries.md — empty-result exit codes inside gates

Evidence: a six-wave landing shipped six dependent work-orders in one day with zero merge conflicts and exactly one inline fix. Earlier attempts without wave discipline produced two-day cycles dominated by re-work when later WOs broke earlier interfaces.