AndrewBrown-USDA/aigb-skills-usda / skills/wave-orchestration
wave-orchestration
VerifiedDecomposes a large implementation plan into small-model-sized tasks executed by supervised worker agents in dependency-ordered parallel waves, with a plan-first approval gate inside every task, file-based state for context compaction, and a hard escalation ladder. Use when a master plan or multi-workstream feature is too large for one session and should be executed cheaply by many small agents under frontier-model supervision.
Wave Orchestration (plan-gated, small-model workers)
An architecture for executing a large, multi-workstream plan as a pipeline of small, cheap worker agents supervised by one frontier-model orchestrator. Three ideas do all the work:
- Waves over a task DAG -- tasks grouped into coherent work clusters; tasks within a wave touch disjoint files and can run in parallel; waves are sequential and depend on prior waves. Every orchestration (planning-file set) can contain multiple waves.
- Plan-first inside every task -- a worker may not write code or run state-changing commands until its micro-plan is approved. The approval gate is the orchestrator, not the human, so the loop stays autonomous.
- State on disk, not in context -- a
STATE.mdfile is the single resume point. Worker context never enters the orchestrator; the orchestrator's own context is disposable after every wave (compact or clear freely).
For repository state, branch selection, focused local commits, and remote-action boundaries, follow git-workflow-standards. An approved task plan and micro-plan authorize focused local commits after logical work units pass verification; neither authorizes remote actions.
Key terms
- Orchestration: one planning-file set (EXECUTION_PLAN_N, PROMPT_TEMPLATE_N, STATE_N). Each orchestration has a unique number; wave numbers reset to 1 for each new orchestration.
- Wave: a logical work cluster of tasks sequenced together. All tasks in a wave touch disjoint files and run in parallel.
- Task: a single coherent change unit, <=12 micro-plan steps, executed by one worker. File format:
tasks/N.W.id.todo.md(e.g.,tasks/5.2.3.todo.md= Orchestration 5, Wave 2, Task 3).
Roles
| Role | Model | Responsibilities | Never does |
|---|---|---|---|
| Orchestrator | frontier (one session) | inspect Git repository/branch/worktree state; decompose plan into waves; spawn workers; gate plans; verify diffs/tests; integrate and record commits; maintain STATE_N.md | write feature code |
| Worker | small/cheap (one per task) | read scoped context, produce micro-TODO, stop, execute after approval, run targeted tests, commit verified logical task work locally, report commit IDs | pick its own scope, run shared/global test suites, work off-plan, perform remote actions |
Artifacts (all under planning/ in the target repo)
Each orchestration (planning-file set) is numbered. Use the next available number:
EXECUTION_PLAN_N.md-- the task directed acyclic graph (DAG): wave table + one spec per task (N = orchestration number).PROMPT_TEMPLATE_N.md-- the fill-in-the-slots worker prompt (below).STATE_N.md-- baseline record, wave board, and appended worker reports.tasks/N.W.id.todo.md-- each worker's approved micro-TODO; N = orchestration number, W = wave number within that orchestration, id = task ID (e.g.,tasks/5.2.3.todo.mdfor Orchestration 5, Wave 2, Task 3).
Example: Orchestration 5 has EXECUTION_PLAN_5.md, PROMPT_TEMPLATE_5.md, STATE_5.md with tasks named 5.1.1.todo.md, 5.1.2.todo.md, 5.2.1.todo.md, etc. When Orchestration 6 starts, it has EXECUTION_PLAN_6.md, STATE_6.md, and tasks 6.1.1.todo.md, 6.1.2.todo.md, etc.
A fresh orchestrator session resumes from the highest-numbered EXECUTION_PLAN_N.md in planning/. That is the contract that makes compaction safe. To start a new orchestration, create the next numeric set; do not reuse or overwrite prior orchestrations.
[Orchestrator] Decomposition
Break the master plan into tasks sized for a small model. A task is right-sized when all of these hold:
- One coherent change cluster; a micro-plan for it fits in <=12 checkbox steps.
- Files in scope is an explicit list: must edit (existing files the task changes), can create (output files, build dirs). Temp/scratch goes in an untracked folder per repo conventions (e.g.,
.development/); everything else is off-limits. - Acceptance criteria are mechanically checkable (named test file + command).
- Large files are entered via grep anchors (symbol names, approximate line numbers), never "read the whole file" -- multi-thousand-line files are where small models drown.
- Reference implementations are named explicitly ("port the pattern in X").
Each task spec records: id, repo, files in scope (with temp folder location), depends-on, spec prose, anchors, acceptance + targeted test command.
Before planning Git operations, determine whether each target workspace is a Git repository and record its current branch/worktree state. If there is no repository, ask whether the user wants one initialized and do not initialize without explicit approval. Reuse a branch identified by the user or task context; if the intended branch is unclear, ask the user before choosing or creating one. Do not switch branches in a way that risks existing changes.
Use the planning-artifact tracking choice recorded in the approved plan. If none is recorded, ask the user whether to track or ignore the orchestration artifacts before creating them. When tracked, make planning-only docs(planning): commits separate from task code. When ignored, ensure the applicable planning/ and other planning paths are ignored and never stage or commit those artifacts.
Building the wave table
Cluster tasks by logical work phase, not just parallelism. Tasks in a wave are sequenced together and run in parallel (file scopes are disjoint):
- Group by feature tier: "API layer", "migrations", "frontend UI" as separate waves, even if they could run in parallel.
- Keep tightly coupled work (schema, backfill, validation) in one wave; testing is clearer when phases advance together.
- Same-file tasks: sequence them, never parallelize (UI shells collide in same files; backend and frontend rarely do).
- Monolithic waves risk: >8 tasks -> split into 2-3 waves by theme. A 10-task wave hides dependencies and complicates review.
Record the green baseline (all suites, all repos) in STATE_N.md before wave 1; "no regressions" is meaningless without it.
[Orchestrator] Templating
Every worker gets the same skeleton with slots filled from its task spec:
You are implementing exactly one scoped task, supervised by an orchestrator
that reviews your plan before you may write code.
## Task {{id}}: {{title}}
{{task spec verbatim}}
## Ground rules (non-negotiable)
- NEVER make implementation changes or run implementation state-changing commands before your plan is approved. Creating or updating the scoped micro-TODO and other planning artifacts required for review is allowed before approval; if tracked, commit those planning-only changes separately using `docs(planning):`.
- After approval, a focused local commit is part of executing the approved task; no separate per-commit approval is required. This does not authorize pushes, pull requests, comments, remote changes, or other outward-facing actions; obtain explicit user instruction for those.
- NEVER touch files outside "Files in scope"; if required, STOP and report.
- NEVER go off-plan; discovered work goes in "## Discovered" and waits.
- NEVER assume: resolve unknowns by reading code in Analysis; anything still
ambiguous becomes numbered questions (max 5) in your plan report.
- If a test fails twice for the same reason, stop and report -- do not thrash.
## [Worker] Analysis
Read: project conventions file; the named plan section(s); STATE_N.md reports of
your dependency tasks; the grep anchors; the named reference implementation.
## [Worker] Micro-planning
Write planning/tasks/{{id}}.todo.md:
# {{id}} -- {{title}}
## Goal <one sentence>
## TODO items - [ ] small, verifiable steps incl. explicit test steps
## Notes <facts discovered in Analysis, constraints honored, risks>
## Questions <numbered, max 5, omit if none>
Output the file contents as your report and END YOUR TURN.
## [Worker] Execution
Work the TODO strictly in order, flipping - [ ] to - [x]. Match surrounding
code style. Run only the targeted tests named in the spec. Commit each
verified, reviewable logical unit locally rather than waiting for the entire
orchestration. If using a worktree, commit its in-scope implementation
deliverables before integration; report each code commit ID. Keep planning
artifact updates out of code commits.
## [Worker] Reporting
Append to planning/STATE_N.md under ## {{id}} (<=15 lines): status; files
changed with line ranges; code commit IDs; exact test commands + pass/fail counts; deviations
from the approved plan (or "none"); gotchas for dependent tasks.
Spawn with the cheapest capable model; use worktree isolation when a wave has more than one task in the same repo.
[Orchestrator] Wave execution
Read the current orchestration's STATE_N.md. Repeat until the wave board is all done:
- Read
STATE_N.md; pick the next wave whose dependencies are all done. - Spawn one worker per task in the wave (parallel).
- Plan review -- inspect the micro-TODO for: in-scope files only, acceptance criteria mapped, <=12 steps, no re-work vs. dependencies (check STATE_N.md), spot-check code claims. Approve or request revisions.
- Unblock worker -- use SendMessage or equivalent to send
APPROVED -- execute the plan as written. [Answers to any questions from their plan.]to the agent. This message is mandatory and unblocks Phase 3 execution; the worker reads it as the execution trigger. - Inform user -- tell the user you've sent the approval and what the agent will do next (reference the task id and goal).
- Verify -- inspect diff, re-run targeted tests. At wave end, run full suites serially (shared resources flake under concurrency).
- Commit and record -- after each task passes its targeted verification, ensure its implementation is committed locally in a focused Conventional Commit; do not defer all commits until the end of the wave or orchestration. Before integrating a worktree, verify its in-scope implementation is committed. Preserve and record code commit IDs in STATE_N.md. If planning artifacts are tracked, commit coherent plan/state updates separately with
docs(planning):; if ignored, never stage them. Mark the task done only after its verified work and required planning-state update are recorded. Fail: escalation ladder. - Distill Decisions (optional / milestone) -- run adr-distillation to extract enduring architectural decisions from
EXECUTION_PLAN_N.mdandSTATE_N.mdintodocs/decisions/before compacting or archiving planning state. - Wave done -- update wave board in STATE_N.md, then
/compactor/clearorchestrator.
Escalation ladder (hard limits -- small models must not loop)
- Micro-plan off-spec twice => orchestrator writes the micro-TODO itself and hands it to the worker as fixed input.
- Acceptance fails after one retry (retry = failure output fed back with
FAILED VERIFICATION: ...) => stop the worker; re-run the task on a mid-tier model. Never a third small-model attempt. - Worker doesn't produce completion report or produces malformed report => send feedback describing what is missing or incorrect (e.g., "report did not include file changes" or "test output truncated"); allow one retry. If the worker still fails to produce a valid completion report, stop and re-run the task on a mid-tier model.
- Worker needs out-of-scope edits => that is a decomposition bug: re-scope the task spec in EXECUTION_PLAN.md; don't widen the worker's permissions ad hoc.
Why each piece exists
- Orchestration numbering: preserves history, prevents overwrites, signals orchestration boundaries.
- Worker approval loop: worker stops after Micro-planning so orchestrator catches plan errors before code exists. Approval message sent via SendMessage or equivalent is the only Execution trigger; narration to the user is separate from this action.
- Plan gate: catches wrong-file, wrong-schema, over-scoped work before code.
- Wave clustering by phase: forces logical grouping; monolithic waves hide dependencies.
- Targeted tests only: full suites are slow and flaky under concurrency; orchestrator owns pass/fail.
- <=15-line reports: forces distillation; keeps resume file readable.
- One commit per task: bisectable history; failed tasks revert cleanly.
- Local versus remote authorization: task approval permits verified local commits only; every outward-facing or remote Git action still requires explicit user instruction.
- Planning versus implementation history: tracked planning artifacts use separate
docs(planning):commits; ignored artifacts never enter code commits. - Escalation caps: converts silent thrash into visible, priced decisions.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |