MCP Task Orchestrator · Field guidePlate 9 of 10

From a request to finished items

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.

Size the work first

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.

Plan mode
Queue notes
Build
Review
Class of workUse
coordinatorRun and wave coordinators, orchestration sessions
planningPlanner seats, specifications, task scope
planning-high-stakesArchitecture decisions and other high-stakes planning
implementationWell-specified implementation work
implementation-complexComplex or cross-cutting implementation
test-authoringIndependent test authors
reviewReviewer seats and defect search
review-high-stakesReview of high-stakes changes
researchRead-only research and exploration
bulkBulk writes and other checkable mechanical work
extractionExtractors 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.

One feature, start to finish

  1. Request

    Orchestration context
    Classifies the tier. Larger work goes to plan mode.Nothing yet.
  2. Enter plan mode

    hook on EnterPlanMode → pre-plan-workflow
    Reads existing items and the schemas' required notes, so the plan covers what the gates will ask for.Nothing new. Creating items before approval is forbidden.
  3. Approve the plan

    hook on ExitPlanMode → plan-capture
    Stores the approved plan text on the server. Skipped silently when no REST API is configured.A plan document under the project root.
  4. Materialize

    post-plan-workflow
    Creates the work tree, wires dependency edges and fills the queue notes.Every item, edge and queue note, before any code is written.
  5. Dispatch

    run-wave, or hand dispatch
    Sends agents to items. Each entering agent reads 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.
  6. Verify and advance

    orchestrator
    Checks the commits, audits that the required notes are filled, writes its own tracking notes, then advances the items in one batch.Items in review, or terminal when the schema has no review notes.
  7. Review

    reviewer agent
    Verifies the work against the plan and fills the review notes. The orchestrator completes the items.Terminal items. An auto parent completes by cascade, but never from review.
  8. Retrospective

    hook on runs_write close, then the Stop backstop
    A closed run triggers a nudge or a background retrospective. Plate 10 follows it from there.A retrospective item.

Columns: the step, what drives it, what happens, and what the server holds afterwards.

The plan becomes the queue notes

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.

Plan document: my-plan # Overview goal, non-goals, risks… ## Task 1 scope, acceptance criteria… ## Task 2 scope, acceptance criteria… anchor: overview anchor: task-1 anchor: task-2 Feature Xnote feature-summary, queue Task 1note task-scope, queue Task 2note task-scope, queue
The server slices each section by its heading and writes it as the note body. Items, edges, notes and the document's adopted mark are one transaction: a missing anchor fails the whole call and creates nothing.

Running many items as one wave

Frontier ready and resumable items Run plan seat stages for each item Method A the implement-wave workflow Method B direct agent dispatch, the fallback Post-run verify, then advance Both methods execute the same plan. The server run is the state (runs_read), so an interrupted run can resume.
The plan comes from each item's resolved schema: its seats decide which agents run, in what order, on which model. Method B takes over when the Workflow tool is missing, when --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.

When the plan routes here

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.

What post-run checks

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.

Five agents, four seats

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).

Rules: operating text the server hands out

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 ruleWhat it tells an agent
protocol.entry-seatEnter the phase once with start. Never complete. Stop on a real failure.
protocol.in-phase-seatNever enter or advance. Fill only your own seat's notes.
protocol.read-only-agentNever transition. Put findings in your own note.
commit-disciplineCommit only your own paths, by path, and check the file list.
review-scopingReview the diff of the files an agent owns. Edits outside them are a breach.
closure-notesA closure note holds only what the diff, git log and CI do not show.

Where rule text comes from

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.

Safe updates

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)

Attended or unattended

run-waveralph
Where it runsIn your interactive sessionA 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 chosenA frontier of ready items under a featureEach 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 runOpened for the wave and closed by the coordinatorOne run per loop. Each seat ends by outcome, and the driver closes the run.
PlanningA run plan of seat stagesNone. The claimed item's schema is the contract.
AgentsOne per seat, dispatched by the orchestratorNo sub-agents. One process does the item.
How it stopsThe frontier is done, or a human checkpointThe queue is empty, or a limit trips

Ralph's limits

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.

Each iteration reports

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.

Run it on work you trust

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.

What else ships in the plugin

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.

ChannelBehaviour
Orchestration contextA session-start hook delivers the orchestration core, including after a compact. Plans, delegates, tracks and reports.
Orchestrate skillOn-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 promptThe terse single-item rules each headless iteration runs under, appended to its system prompt.
extensions.claude-code.orchestration.mode: workflowThe default. Tier-aware, with a model policy. Small fixes are done inline.
extensions.claude-code.orchestration.mode: schemaNo tiers and no model policy. The item's schema alone sets the process.
extensions.claude-code.orchestration.mode: offThe orchestration hooks stay silent.
Dispatch model guardDenies 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 hintAfter an advance lands in work or review, tells the dispatcher the item's agent, model and effort.
Phase guardRecords the items a subagent entered. When it tries to stop with required notes missing, sends it back with the keys named.
Subagent startInjects the agent-owned-phase protocol into a phase-owner agent.
Workflow scriptPurpose
implement-waveSchedules queue and work seats across a wave, with per-file locks and safe replay.
review-waveIndependent review lanes over items in review, combined into one verdict.
auditA read-only code audit in quick, standard or full size that ends in a findings proposal.
retro-analysisMatches retrospective findings against known trends. Read-only.