MCP Task Orchestrator · Field guidePlate 3 of 10

A work breakdown the server keeps in order

Items nest inside parents and block one another through dependency edges. The server refuses to start an item whose blockers are unfinished, and it moves parents on its own, when the rules allow, as their children move.

Run a feature through the graph

Click an item to advance it: queue to work, work to terminal, terminal back to queue with reopen. Thick arrows are blocks edges. The frame is the parent. Pick a gate problem to see a cascade get stopped, or press complete_tree to see each item answer on its own.

User Authentication queue Database schemaqueue Login APIqueue Session tokensqueue Integration testsqueue
A dashed red outline marks an item that is still in queue because a blocker has not reached terminal. An arrow fades once its blocker is done.

Server says

Parents move without a call

Start cascade

When a child enters work, by start or by resume, a parent still in queue moves to work. One level up only, and only if the parent's own gates pass.

Terminal cascade

When a child reaches terminal, the parent reaches terminal too, but only if it has at least one child and every child is terminal. The check repeats up the ancestor chain. A parent in review is never completed this way: a reviewer's explicit advance moves it, and the cascade is reported as review-pending.

Reopen cascade

Reopening a child under a terminal parent sends that parent back to work. One level up only.

Reparent and delete

Moving a child to another parent, or deleting it, re-evaluates its old parent with the same terminal check. The items_write result reports it.

Each applied cascade is listed in the cascades of the result and recorded as a system-made transition (origin: cascade in the history), attributed to the principal whose write set it off. A cascade that a gate stops is listed too, with applied: false and its reason: a blocked parent, an unmet blocker, a missing note, another caller's claim or seat, or review-pending. It never fails the call that set it off. A schema's lifecycle decides whether any cascade runs: auto (default) cascades, manual and permanent suppress all of them and report nothing, and none gives items no role at all. A parent with lifecycle auto that is already terminal refuses new children: creating or moving a child under it fails invalid_transition.

Build the whole tree in one call

items_write(ops=[{
  "op": "create_tree",
  "root": { "title": "User Authentication", "type": "feature" },
  "children": [
    { "ref": "schema", "title": "Database schema", "type": "task" },
    { "ref": "api",    "title": "Login API", "type": "task" },
    { "ref": "tokens", "title": "Session tokens", "type": "task" },
    { "ref": "tests",  "title": "Integration tests", "type": "task" }
  ],
  "deps": [
    { "from": "schema", "to": "api" },
    { "from": "schema", "to": "tokens" },
    { "from": "api",    "to": "tests" },
    { "from": "tokens", "to": "tests" }
  ]
}])

The hierarchy and its edges are created atomically, so agents never work against a half-built plan. items_write complete_tree is the mirror image, but it is not all-or-nothing. It applies one trigger (complete by default, or cancel) to each descendant in blocking order, then to the root last (includeRoot, default true). Every item answers for itself: applied, skipped (already_terminal, or upstream_failed with blockedBy) or failed with its own error. A rejection never rolls back the items that applied, and descendants with lifecycle none are left out.

Edge typeMeaning
blocksThe target cannot start, complete, or resume into work or review until the source reaches the threshold; the call fails dependency_unmet and lists the detail.blockers. The default. The blocker is always the from end.
relates_toA link with no ordering constraint.

Dependency shortcuts

A B C

linear

deps_write(ops=[{op:"linear",
  ids:[A, B, C]}])
A B C D

fan-out

deps_write(ops=[{op:"fan_out",
  from:A, toIds:[B, C, D]}])
A B C

fan-in

deps_write(ops=[{op:"fan_in",
  fromIds:[A, B], to:C}])
unblockAtThe edge is satisfied when the blocker reaches
queueany role except blocked, so almost immediately
workwork, review or terminal
reviewreview or terminal
terminalterminal (the default)

An earlier threshold lets downstream work begin while the blocker is still in review, for example building against an API whose shape is settled. A blocker that is itself blocked never satisfies an edge, whatever its threshold.