MCP Task Orchestrator · Field guidePlate 4 of 10

The rules are YAML, and they compose

A schema says which notes an item type must carry at each phase. Traits add cross-cutting requirements to any type. Both are written as YAML, but the server runs on stored, versioned copies of that YAML in its database, never on the file itself. Changing the process never means changing code or prompts.

From config to the gate an item actually faces

The item

type: feature-task
traits: [needs-migration-review]

Its schema

work_item_schemas:
  feature-task:
    lifecycle: auto
    default_traits: [needs-security-review]
    notes:
      - { key: requirements, role: queue, required: true }
      - { key: implementation-notes, role: work, required: true }

Traits

traits:
  needs-security-review:
    notes:
      - { key: security-assessment, role: review,
          required: true, skill: security-review }
  needs-migration-review:
    notes:
      - { key: migration-assessment, role: queue,
          required: true, skill: migration-review }

Resolved schema for this item

queue
  • requirementsfrom the base schema
  • migration-assessmentfrom the per-item trait. Routes the author to the migration-review skill.
work
  • implementation-notesfrom the base schema
review
  • security-assessmentfrom the default trait. Because a review-phase note now exists, the item passes through review.

Four steps pick the schema

An item's schema is its per-root schema for the type, then the server's schema for the type, then the per-root default, then the server default. Tags never select a schema. A null type uses only the two default steps, and with nothing found the item is schema-free and advances freely. Creating an item always requires a type. When the config declares types, one it does not declare fails schema_violation with detail.availableTypes; when it declares none, any type is accepted.

Per-item traits, then default traits

Traits resolve in one order everywhere: the item's own traits first, then the schema's default_traits, duplicates dropped with the first position kept. When two declarations share a note key, the content comes from the first declaration (base schema before traits) and required is true if any declaration marks it.

Traits add, they never relax

A trait cannot make a required note optional, because required is OR-merged. A trait also cannot change the role of a note the base schema already declares.

A per-root trait replaces the server's whole

When a project's traits: map contains a trait name, every dimension of that trait comes from the project entry: notes, seats, resources and both dispatch shapes. A dimension it leaves out is empty, never inherited from the server's trait of that name.

A trait carries six signals

Traits are orchestration signals. Note requirements are only the first of them.

Notes

Which notes must exist, in which phase. Enforced at the gate.

notes:
  - key: migration-assessment
    role: queue
    required: true

Guidance

How to write the note. advance and items_read context return a guidanceKey; the text itself comes from items_read schema with fields: ["guidance"].

guidance: "Cover table
  recreation and data
  migration strategy."

Skill routing

Names a skill to run first, so the note follows a defined evaluation framework.

skill: "migration-review"

Resources

Shared resources the item needs. An exclusive one is leased when the item enters work, and a second item's start is rejected until it frees. Every key, advisory ones too, must be in the server's resource registry.

resources:
  - staging-db
  - key: deploy-token
    mode: advisory

Dispatch

Which agent, model and effort should pick up each phase. Returned to the orchestrator with the transition. Per-seat overrides resolve first-in-trait-order, except that a seat-only trait whose override sets model and neither sets nor clears agent wins its seat whatever the order (config-reference, Seat dispatch precedence).

dispatch:
  review:
    agent: reviewer
    effort: high

Seats

Named roles inside a phase. A trait can add a seat to any type it is applied to. See the next figure.

seats:
  - name: test-author
    phase: work

Keeping notes short

A note is what the next agent reads in place of the whole conversation, so its value depends on staying small. A schema can cap each note, and the server can warn or refuse when a body runs over. Whatever the schema says, a body over 65536 UTF-8 bytes is refused as payload_too_large.

note_limits:
  mode: reject            # warn (default) | reject

work_item_schemas:
  bug-fix:
    notes:
      - key: diagnosis
        role: queue
        required: true
        maxLength: 6000   # characters

A cap per note

maxLength is a backstop on one note. Guidance text usually names a much smaller target.

Warn or reject

In warn mode an over-long note is stored with a warning on the result. In reject mode that note fails with note_too_long and the rest of the batch is still written. A project can set its own mode.

Long artifacts go by file

For test output, diffs and logs, an agent passes bodyFromFile and the server reads the file itself, so the text never passes through the model's context. The path is relative and must stay inside the agent config root (no .., no symlink out), and the file must be regular UTF-8 of at most 65536 bytes. CRLF becomes LF.

Shared notes

A note is owned by the (principal, seat) whose write created it, and a write from another principal, or from the same principal under another seat, is note_owned_by_other. A note entry with shared: true is exempt, for notes several seats legitimately co-author.

Seats split a phase between agents

A phase is often more than one agent's job. A schema or trait can name the seats inside each phase: which seat enters the phase, which seat owns each required note, and in what order they work.

queue work review planner diagnosis test-plan independent_of: a different (principal, seat) writes test-manifest implementer enters the phase implementation-notes after test-author added by a trait test-manifest after orchestrator session-tracking reads_exclude: the test author is told not to read implementation-notes or session-tracking. reviewer review-checklist test-independence-audit
Each box is a seat with the notes it owns. The seat layout is this project's own bug-fix schema with the needs-test-author trait. The independent_of bracket follows the reference example in the config documentation.

The server serves seats to the orchestrator as signals, reports missing notes grouped by the seat that owns them, and can check that an independent_of note was written by a different (principal, seat) identity than the latest write of the named seat. Plate 6 covers seats in full.

A config with no seats anywhere behaves exactly as before. Seats are optional at every level.

Resource leases: a gate on shared things

Some work needs something only one item can use at a time: a staging slot, a test database, a deploy window. A trait can declare that resource, and the server holds a lease on it for as long as the item is in work. There is no acquire or release call. The lease rides on advance.

Item A Item B start in work · holds the lease on staging-db complete lease released start rejected: resource_unavailable, retryAfterMs set start in work · holds the lease time
The rejection is transient, not a gate failure: Item B's notes are fine. The agent should work on something else and try again later. The response names the contended key and never says who holds it. retryAfterMs is the time until the soonest contending lease expires, not a fixed delay.
# server file only: the registry
resources:
  staging-db:
    description: "Shared staging database"
    defaultTtlSeconds: 1800
  deploy-token:
    description: "Deploy credential"

# server file or per-root push
traits:
  needs-staging:
    resources:
      - staging-db          # exclusive by default
      - key: deploy-token
        mode: advisory      # recorded, never locked

Exclusive or advisory

exclusive admits one item at a time. advisory takes no lock and only records that the item used the resource. Reserve exclusive for things that cannot be shared. A credential several agents can use at once should be advisory.

Held for the whole work phase

Taken on start or resume into work. Released on any exit from work: start (to review, or to terminal when there is no review phase), complete, block, hold or cancel. It expires after an hour by default (24 hours at most). There is no renew call, though the same holder acquiring again refreshes it. An hourly sweep, plus one at start, clears expired leases, and a contender can take an expired one in any case.

Task-level items only

Put exclusive resources on leaf task types. A feature container can sit in work for days and would hold the lock the whole time.

The registry is server-only

One registry per server: a per-root push that carries resources: is rejected, and every key a trait names must be registered. Keys are server-wide, so prefix them per project to avoid accidents.

Operator controls

The REST API lists active leases and their history, and an admin can force-release one. RESOURCE_LEASES_ENFORCED=false skips the lease gate and acquisition on every advance (releases still run). The server reads it only at startup, so changing it needs a restart.

There is no queue and no fairness: whoever retries first after release gets the lease. A lease is checked on entry to work only. It is a coordination aid for cooperating agents.

One server, many projects, two layers

Task Orchestrator server project-a / config.yaml project-b / config.yaml config push (config-sync) Root heads (database) root A · config head root B · config head hot-reloads, no restart server config.yaml located by AGENT_CONFIG_DIR boot import every start SERVER head file-import version, stored steps 1 and 3 steps 2 and 4 Schema resolver picks a project by item.rootId four steps, no tags
The server file is imported by the server-config-import step at every boot, and a new file-import version is appended only when its fingerprint changed. The workspace file is the source of truth for a project: the plugin's config-sync hook pushes it at session start and whenever it changes, and a push of older content than the head, such as from a stale checkout, is version_conflict. A solo developer gets this too: one persistent server serves every repository with its own rules.

Lookup order for an item's type

Exact match on typeThe layer's default schema Per-root
1Project schema named for the type
3Project default
Server
2Server schema named for the type
4Server default

An exact match in either layer is tried before either default, so a server schema named for the type beats a project default. An item with no type skips steps 1 and 2. Nothing found means schema-free.

Config versions and schema pins

Every config is an append-only list of immutable versions, one list for the server and one per project root. An item records the versions it started under, so a later push cannot change the gate it already faces. That record is its pin.

{"ops": [
  {"op": "validate", "rootId": "<root>",
   "configYaml": "<yaml>"},
  {"op": "push", "rootId": "<root>",
   "configYaml": "<yaml>", "expectedVersion": 4}
]}

// one data.results[i] per ops[] element, in order
{"ok": true, "data": {"results": [
  {"ok": true, "rootId": "<root>", "valid": true,
   "errors": [], "warnings": [],
   "diff": {"types": {"added": [], "removed": [],
                      "changed": ["bug-fix"]}, ...},
   "affectedInFlight": {"count": 2, "sample": [
     {"itemId": "...", "changedNotes": ["diagnosis"]}]}},
  {"ok": true, "rootId": "...", "version": 5,
   "fingerprint": "...", "appended": true,
   "createdAt": "..."}
], "summary": {"ok": 2, "failed": 0}},
 "meta": {"reqId": "..."}}

Eight ops on one tool

get, history, push, validate, rollback, reset, effective and rules. reset appends an empty version so the root falls back to the server config.

Look before you push

validate writes nothing. It returns the errors, a diff against the head and affectedInFlight: how many in-flight items would resolve a different gate if repinned, with a sample of the first 20.

Compare-and-set

A wrong expectedVersion is version_conflict, and so is re-pushing older content. force skips only the rootId and older-content guards, never validation or expectedVersion.

When an item is pinned

ReasonPin point
createThe item is created.
type_changeAn update changes the item's type.
reparentAn update moves the item under another root, and every descendant that moves with it.
trait_changeAn update changes the item's traits.
reopenA transition leaves terminal. The gate of that transition still runs under the old pin.
repinitems_write repin is called and the recomputed pin differs from the stored one.

What a pin governs

Notes and gates, trait merge, seats, dispatch and resource requirements come from the pinned versions. Status labels, note_limits, independence, the resource registry and the declared type and trait lists always follow the heads.

Stale pins show

items_read renders the pin as schemaVersion and adds stale: true when either pinned version is no longer the head of its scope. An unpinned item resolves at the heads.

Repin to catch up

items_write repin moves the pin to the heads. A note key the pinned schema lacks but the head schema requires cannot be written until then: schema_pinned_conflict.

Lifecycle modes, and where plugin settings go

lifecycle on a schema

Lowercase, one of four. auto (the default): a parent cascades to terminal when all its children are terminal. manual: every parent cascade is suppressed (start, terminal and reopen), so the parent is moved explicitly. permanent: never auto-terminates and never auto-reopens, and suppresses the same cascades.

none means no phases at all

A lifecycle-free item has no role. Its schema may declare notes but none required, and no seats. No trigger applies to it, it cannot be claimed, and it cannot be an endpoint of a blocks edge. It suits pages of knowledge or reference material.

extensions.claude-code

Plugin settings live under extensions.<tool>. The server stores the namespace and never reads it. The old top-level orchestration and retrospective sections are rejected in a new push; move them under extensions.claude-code.