MCP Task Orchestrator · Field guidePlate 6 of 10

Who does what inside a phase

A phase is often several jobs: plan, build, test, record. Seats name those jobs in config. The orchestrator learns which agent to send, the gate reports missing notes by owner, and the server can check that the tests and the code were written by different (principal, seat) pairs.

The seats of a bug fix

This project's own bug-fix schema with its default traits. Select a seat to see what the server serves for it.

queue work review after after planner diagnosis test-plan implementer enters the phase implementation-notes test-author added by a trait test-manifest orchestrator the main session session-tracking Arrows are after hints: an order the orchestrator follows. The server serves them and does not enforce them. reviewer review-checklist test-independence-audit
Each box is a seat with the required notes it owns. Amber bars are the phase gates from plate 2. The gate checks the notes of every seat in the phase it guards.

implementer

Phase
Enters phase
Works after
Told not to read
Owns notes
Declared by
Dispatch
Apply a per-item trait to this item:

What a seat declares

work_item_schemas:
  bug-fix:
    default_traits: [delegated, session-tracked, needs-test-author]
    seats:
      - { name: planner,      phase: queue }
      - { name: implementer,  phase: work, enters: true }
      - { name: orchestrator, phase: work, after: [implementer] }
      - { name: reviewer,     phase: review }
    notes:
      - { key: implementation-notes, role: work,
          required: true, seat: implementer }

traits:
  needs-test-author:
    seats:
      - { name: test-author, phase: work,
          after: [implementer],
          reads_exclude: [implementation-notes] }
    notes:
      - { key: test-manifest, role: work, required: true,
          seat: test-author,
          independent_of: [implementer] }
  delegated:
    dispatch:
      work:
        agent: task-orchestrator:implementer
        seats:
          implementer: { model: sonnet }
          test-author: { agent: null, model: sonnet }
  session-tracked:
    notes:
      - { key: session-tracking, role: work, required: true,
          seat: orchestrator }
FieldMeaningServer's part
name, phaseA named role in queue, work or review. The name means nothing to the server, with two exceptions: orchestrator is the seat whose note keys a run's coordinator token writes, and unowned is reserved.Validates and serves
entersThis seat makes the transition into the phase. Inside a run, it is the only schema seat that may start the item (the run's coordinator token may too).Allows one per phase
transitionsThe triggers other than start that a token for this seat may send. The default is block and hold. start is governed by enters and is never listed.Refuses the rest as seat_forbidden, inside a run
afterSeats whose work this one follows.Serves as a hint
reads_excludeNote keys this seat should not read. Keeps a test author blind to the implementation.Serves as a hint
note seatThe seat that owns a note.Groups missing notes by owner, and inside a run refuses other seats' writes
note independent_ofSeats whose author must differ from this note's author.Checks at the gate
dispatch.<phase>.seatsAgent, model and effort for one seat. null clears a field inherited from the phase.Resolves and serves

Inside a run that is not closed, on an item whose pinned schema declares seats, the server enforces these: a refused trigger is seat_forbidden, and a write to another seat's note is note_owned_by_other. Outside a run they stay signals for the orchestrator. The mechanics are on plate 8, Runs and Decisions.

The YAML is abridged from this project's config, and its independent_of line follows the reference example in the config documentation. A config with no seats anywhere is unaffected: every seat field is left out of every response.

The gate answers by owner

Without seats

"gateStatus": {
  "canAdvance": false,
  "missing": [
    "implementation-notes",
    "test-manifest",
    "session-tracking"
  ]
}

A flat list of keys. The orchestrator has to know, from somewhere outside the config, whose job each note is.

With seats

"gateStatus": {
  "canAdvance": false,
  "missing": [ ... ],
  "missingBySeat": {
    "implementer":  ["implementation-notes"],
    "test-author":  ["test-manifest"],
    "orchestrator": ["session-tracking"]
  }
}

The same failure, routed. A required note that no seat owns is listed under unowned, last. A refused advance says the same in gate_blocked, whose detail.missing is a list of {key, role, seat?}.

Independence is the one thing the server checks

When a note declares independent_of, the gate compares who wrote it with who wrote the named seat's notes. Who is a pair: the principal of the credential, and the seat of the note's latest write (null for a write made without a seat token). Here the implementer's note was written by (local, implementer), and test-manifest declares independent_of: [implementer].

independence.mode


    

Credential identity, not a claim

The principal is the one of the credential that wrote the note, never a string the caller sent. Seat tokens separate the seats of one principal: stdio and unauthenticated sessions all share the local principal, and outside a run every write there is (local, no seat). With require_verified: true only a cryptographic proof counts. A server-issued token is unverified.

A note has an owner

The owner is the (principal, seat) whose write created the note. An upsert or delete from another pair is note_owned_by_other, naming ownerSeat. A note entry with shared: true is exempt, and only an admin takeover moves an owner.

The waiver is self-service

Whoever writes the note can add the waiver line. Treat reject as a discipline aid for cooperating agents. It is not a security control.

A bug fix, seat by seat

How four of the Claude Code plugin's five agent definitions (planner, implementer, test author, reviewer) and the main session take these seats. The fifth, the director, takes no seat.

  1. planner · queueWrites diagnosis and test-plan. The expected results for the tests are fixed before any code exists.
  2. implementer · enters workReads items_read context first and sends advance (transition, start) only when the role is queue. The queue gate checks the planner's notes. Then it writes the fix and its note.
  3. test-author · workWrites tests from the test plan without reading the implementer's note. Fills test-manifest.
  4. orchestrator · workFills session-tracking and advances the item. The work gate checks all three seats' notes.
  5. reviewer · reviewFills review-checklist and test-independence-audit.
  6. orchestratorAdvances the item to terminal. The review gate checks the reviewer's notes.

Only the entry seat calls advance. Every other seat fills its own notes and returns, and the orchestrator owns each later transition. For several items at once, the run-wave skill builds these stages from each item's seats. It opens a server run, assigns each seat a token, each seat ends itself with end_seat, and the coordinator closes the run (plate 8, Runs and Decisions).

How seats combine, and what fails the load

Traits add seats, they never redefine one

A trait seat whose name already exists on the schema is dropped with a warning. Across traits, the first to declare a name keeps it.

Dispatch follows the same trait order

Per-item traits come first, then default_traits, and the first declaration wins. One exception: a seat-only trait whose override sets model and neither sets nor clears agent wins that phase and seat whatever the order. That is how complex-implementation and high-stakes raise models, as the toggles above show.

A late second entry seat is demoted

If merging traits at resolve time yields two entry seats in one phase, the first keeps the role and the later one is served with enters: false.

In one config documentResult
Two seats with enters: true in the same phaseThe load fails. A push is rejected config_invalid and nothing is stored. The boot import of the server file fails startup.
Two seats with the same name
A seat named unowned
A cycle in after
A seat with enters: true whose transitions lists complete or cancel
A required note with no seat, in a schema that has seatsA warning. The note is served under unowned.
A malformed seat entry or dispatch overrideAn error at a push and at the boot import. Only a stored version being read again skips the entry, with a warning.