| name | orchestrate-guide |
| description | How and when to fan a large goal out across parallel worker agents using the `/orchestrate:orchestrate` workflow — planner, isolated workers, independent verifiers, one reconciled report. Use when a task is too large for one agent's context, when the same step must run across many files or subsystems, or when the user asks to parallelize, fan out, or orchestrate agents. |
Orchestrate
Fan a large goal out across parallel agents: a planner decomposes it, one worker owns each task in
its own git worktree, an independent verifier checks each result against the acceptance criteria,
and the run returns a single reconciled report.
The orchestration itself is a workflow, not a script you invoke by hand:
/orchestrate:orchestrate <goal>
Intermediate results stay inside the workflow runtime rather than in the conversation, which is
what lets the run be much larger than one agent's context.
When this earns its cost
Use it when both hold:
- The goal genuinely decomposes into tasks that different agents can own without editing the same
files.
- The whole thing is too large for one agent to hold — a broad migration, a multi-surface feature,
an audit across many subsystems.
Do not use it when:
- One agent could just do the work. A fan-out of one is pure overhead.
- The tasks are actually sequential. Every
dependsOn serializes the run, and a fully chained plan
is slower than doing it directly.
- The work needs continuous human steering. Workers do not talk to you or to each other mid-run;
they report once, at the end.
How a run is shaped
| Phase | What happens |
|---|
| Plan | One planner agent reads the repo and returns a structured plan: tasks with a scoped goal, allow/forbid paths, observable acceptance criteria, and any real dependsOn edges. |
| Build | One worker per task, each in its own worktree (isolation: "worktree"), so parallel file edits cannot collide. Each returns a structured handoff: done / partial / blocked, plus evidence. |
| Verify | An independent verifier per task, which re-checks the acceptance criteria against the actual repository rather than trusting the worker's summary. |
| Synthesize | Handoffs reconcile into passed / failed / unresolved, plus any agents that died. |
Build and verify run as a pipeline(), not a barrier: a fast task is being verified while a slow
one is still building.
Passing input
The workflow takes the goal as args — a bare string, or an object:
/orchestrate:orchestrate { "goal": "Migrate every route to the new auth middleware", "maxTasks": 4 }
| Field | Default | Meaning |
|---|
goal | required | What the run is trying to achieve |
maxTasks | 6 | Upper bound on the decomposition |
verify | true | Set false to skip the verifier pass |
Reading the result
The run returns passed, failed, unresolved, lost, and followUps.
Check lost and unresolved before treating a run as complete. An agent can be stopped or die
on an unrecoverable error; those tasks are reported by name rather than dropped, precisely so a
partial run is never mistaken for a finished one. A failed verdict lists the unmet criteria — that
is a real finding, not a workflow error.
Editing the orchestration
The workflow script is workflows/orchestrate.js in this plugin. It is plain JavaScript using
agent(), pipeline(), parallel(), phase(), and log(). To change how the fan-out works —
different phases, a different verification strategy, an adversarial panel instead of a single
verifier — edit that file. Run /workflow-authoring first to load the script-writing reference.
Watch a run live with /workflows.
Supporting material
prompts/ — the root, subplanner, worker, and verifier prompt fragments this plugin was built
around. The workflow inlines current versions; these remain the reference for the reasoning
behind each instruction, and are worth reading before you reword an agent prompt.references/planner.md — how to decompose a goal, and why acceptance criteria have to be
observable.references/handoffs.md — what a good handoff contains and how to read status.
