MCP Task Orchestrator · Field guidePlate 9 of 10
The Claude Code plugin turns one request into a plan, a tree of gated items, a set of dispatched agents and a verified result. How much of that process runs depends on the size of the work.
The orchestration context classifies every request into a tier before anything else, using the orchestrate skill. Describe a request and see the process it gets. This is a simplified reading of those rules.
| Class of work | Use |
|---|---|
coordinator | Run and wave coordinators, orchestration sessions |
planning | Planner seats, specifications, task scope |
planning-high-stakes | Architecture decisions and other high-stakes planning |
implementation | Well-specified implementation work |
implementation-complex | Complex or cross-cutting implementation |
test-authoring | Independent test authors |
review | Reviewer seats and defect search |
review-high-stakes | Review of high-stakes changes |
research | Read-only research and exploration |
bulk | Bulk writes and other checkable mechanical work |
extraction | Extractors and retrospective data pulls |
The plugin's dispatch policy assigns a model and an effort to each class of work, and task-orchestrator:model-effort reads it. The values live in the policy and change with it. A schema's dispatch block overrides it per phase or per seat (plates 4 and 6). The orchestrator always names the model and the effort on a dispatch.
items_read context first, sends advance (transition, start) once and only from the role just before its phase, carries its seat token, fills its own notes and returns.Items in work, with each seat's notes.auto parent completes by cascade, but never from review.runs_write close, then the Stop backstopColumns: the step, what drives it, what happens, and what the server holds afterwards.
The approved plan is already written. Retyping it into notes would cost tokens and invite drift. So items_write create_tree can point at the stored plan document and name which heading feeds which note.
--method B is passed, or when the run's maxActiveSeats is below the number of schema seats. A server that serves no seats or no rules stops both methods.After materializing, the plugin hands off to run-wave only if at least two leaf items are unblocked, a project root resolves, their queue notes are filled, and the three protocol rules are served. Otherwise it dispatches by hand and says which condition failed.
In order: end any seat still active, verify that each commit exists and stays inside the files its seat owns, audit that the required notes are filled, write the orchestrator's own notes, advance in one batch, hand off to review, close the run. Who wrote a note is not audited, because the server enforces each seat's lane. Items that fail are left out of the batch advance.
The planner verifies the plan against source and cannot edit files. The implementer builds. The test author writes tests without opening the production files. The reviewer reports findings and never advances the item. The fifth, the director, runs the board and never code (plate 8, Runs and Decisions).
The run is recorded in the parent's session-tracking note (the single item's, in a one-item run) as a pointer line, run-wave: <runId> run=<uuid8> parent=<state>, which is how a later session finds it to resume. A seat that finds the plan wrong raises a deviation decision with block: true and stops. An answer never resumes the item: the coordinator does (plate 8, Runs and Decisions).
A rule is a short piece of operating text stored per project and served verbatim by the rules op of config. Agents fetch a rule by key when they need it, so a dispatch prompt can name a rule and leave the text out.
| Bundled rule | What it tells an agent |
|---|---|
protocol.entry-seat | Enter the phase once with start. Never complete. Stop on a real failure. |
protocol.in-phase-seat | Never enter or advance. Fill only your own seat's notes. |
protocol.read-only-agent | Never transition. Put findings in your own note. |
commit-discipline | Commit only your own paths, by path, and check the file list. |
review-scoping | Review the diff of the files an agent owns. Edits outside them are a breach. |
closure-notes | A closure note holds only what the diff, git log and CI do not show. |
A rule is a document of kind rule under the project root. The config-sync hook pushes your .taskorchestrator/rules/*.md, and the plugin's bundled rules at session start only. It needs a REST URL, plus a token that may write documents when the server requires one. Without them, /task-orchestrator:init seeds the bundled rules. A workspace key wins over a bundled one.
A manifest governs them. A bundled rule overwrites the server copy only when that copy matches a version the plugin shipped before. A copy someone customized is left alone and reported.
config(op="rules", rootId, key="commit-discipline") config(op="rules", itemId, noteKey="test-manifest") config(op="rules", rootId)
run-wave | ralph | |
|---|---|---|
| Where it runs | In your interactive session | A detached script that starts a fresh headless Claude process and worktree per item. It needs the REST API and exits 64 without it. |
| How work is chosen | A frontier of ready items under a feature | Each iteration selects the oldest ready item with items_read next, assigns it an implementer seat and claims it under that seat's token |
| The server run | Opened for the wave and closed by the coordinator | One run per loop. Each seat ends by outcome, and the driver closes the run. |
| Planning | A run plan of seat stages | None. The claimed item's schema is the contract. |
| Agents | One per seat, dispatched by the orchestrator | No sub-agents. One process does the item. |
| How it stops | The frontier is done, or a human checkpoint | The queue is empty, or a limit trips |
Defaults: 10 iterations, 5 US dollars per iteration, a 45-minute iteration timeout, a 30-minute claim. The loop stops after 3 gate failures in a row, 2 errors in a row or 3 idle results. The run has no cap unless --max-attempts is passed.
The iteration ends with one outcome line: ready-to-complete (or the legacy terminal), gate-blocked, error or skip. The driver itself adds idle and no-item. The loop reads the outcome to decide whether to continue.
Iterations run with permission prompts bypassed, each in its own temporary worktree. The per-iteration dollar cap and the claim expiry are the hard stops.
The mode lives under extensions.claude-code.orchestration. A top-level orchestration block is rejected by a push. The orchestration context stays silent in subagents, director sessions, headless ralph iterations, when no config is located, and in mode off. The director's own hooks are on plate 8.
| Channel | Behaviour |
|---|---|
| Orchestration context | A session-start hook delivers the orchestration core, including after a compact. Plans, delegates, tracks and reports. |
| Orchestrate skill | On-demand tier table, delegation rules (an explicit model and effort on every dispatch, one effort level higher on a fix) and phase-owner dispatch rules. The class table is in task-orchestrator:model-effort. |
| Ralph iteration prompt | The terse single-item rules each headless iteration runs under, appended to its system prompt. |
extensions.claude-code.orchestration.mode: workflow | The default. Tier-aware, with a model policy. Small fixes are done inline. |
extensions.claude-code.orchestration.mode: schema | No tiers and no model policy. The item's schema alone sets the process. |
extensions.claude-code.orchestration.mode: off | The orchestration hooks stay silent. |
| Dispatch model guard | Denies an Agent dispatch that is missing a model or an effort, because the shipped agents inherit the caller's model and carry no effort. |
| Dispatch hint | After an advance lands in work or review, tells the dispatcher the item's agent, model and effort. |
| Phase guard | Records the items a subagent entered. When it tries to stop with required notes missing, sends it back with the keys named. |
| Subagent start | Injects the agent-owned-phase protocol into a phase-owner agent. |
| Workflow script | Purpose |
|---|---|
implement-wave | Schedules queue and work seats across a wave, with per-file locks and safe replay. |
review-wave | Independent review lanes over items in review, combined into one verdict. |
audit | A read-only code audit in quick, standard or full size that ends in a findings proposal. |
retro-analysis | Matches retrospective findings against known trends. Read-only. |