MCP Task Orchestrator · Field guidePlate 8 of 9

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
Kind of taskModel
Bulk item operations, materialization, simple querieshaiku
Reading code, implementation, writing testssonnet
Architecture, hard trade-offs, synthesis across many filesopus

The model table is the style's default, flagged as a project convention. A schema's dispatch block overrides it per phase or per seat (plates 4 and 6). The orchestrator always names the model 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 calls advance_item(start) once, fills its notes and returns.Items in work, with actors on every transition and note.

  6. Verify and advance

    orchestrator
    Checks the commits, audits the actors, 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. The parent completes by cascade.

  8. Retrospective

    hook on advance_item
    A finished run triggers a nudge or a background retrospective. Plate 9 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 create_work_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. Run state is saved as plan documents under run/<runId>, 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 or the server does not serve seats.

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

That each commit exists and stays inside the files its seat owns, that every note carries the actor of the seat that should have written it, and that the orchestrator's own notes are filled. Items that fail are left out of the batch advance.

Four agents, four jobs

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.

Rules: operating text the server hands out

A rule is a short piece of operating text stored per project and served verbatim by query_rules. 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.

Where rule text comes from

Your own rules live in .taskorchestrator/rules/<key>.md. The plugin ships the five on the left. Both are synced to the server at session start, and a workspace file with the same key wins.

Safe updates

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.

query_rules(operation="get", rootId, key="commit-discipline")
query_rules(operation="get", itemId, noteKey="test-manifest")
query_rules(operation="list", 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
How work is chosenA frontier of ready items under a featureEach iteration claims one item from the queue with claim_item
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 30-minute claim. The loop stops after 3 gate failures in a row, 2 errors in a row or 3 idle results.

Each iteration reports

One outcome line: terminal, gate-blocked, error, skip, idle or no-item. The loop reads it to decide whether to continue.

Run it on work you trust

Iterations run with permission prompts bypassed, each in its own temporary worktree. The budget and the claim expiry are the hard stops.

What else ships in the plugin

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 table and phase-owner dispatch rules.
Ralph iteration promptThe terse single-item rules each headless iteration runs under, appended to its system prompt.
orchestration.mode: workflowThe default. Tier-aware, with a model policy. Small fixes are done inline.
orchestration.mode: schemaNo tiers and no model policy. The item's schema alone sets the process.
orchestration.mode: offThe orchestration hooks stay silent.
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.