MCP Task Orchestrator · Field guidePlate 6 of 10
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.
This project's own bug-fix schema with its default traits. Select a seat to see what the server serves for it.
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 }
| Field | Meaning | Server's part |
|---|---|---|
name, phase | A 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 |
enters | This 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 |
transitions | The 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 |
after | Seats whose work this one follows. | Serves as a hint |
reads_exclude | Note keys this seat should not read. Keeps a test author blind to the implementation. | Serves as a hint |
note seat | The seat that owns a note. | Groups missing notes by owner, and inside a run refuses other seats' writes |
note independent_of | Seats whose author must differ from this note's author. | Checks at the gate |
dispatch.<phase>.seats | Agent, 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.
"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.
"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?}.
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].
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.
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.
Whoever writes the note can add the waiver line. Treat reject as a discipline aid for cooperating agents. It is not a security control.
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.
diagnosis and test-plan. The expected results for the tests are fixed before any code exists.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.test-manifest.session-tracking and advances the item. The work gate checks all three seats' notes.review-checklist and test-independence-audit.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).
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.
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.
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 document | Result |
|---|---|
Two seats with enters: true in the same phase | The 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 seats | A warning. The note is served under unowned. |
| A malformed seat entry or dispatch override | An error at a push and at the boot import. Only a stored version being read again skips the entry, with a warning. |