MCP Task Orchestrator · Field guidePlate 3 of 10
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.
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.
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.
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.
Reopening a child under a terminal parent sends that parent back to work. One level up only.
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.
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 type | Meaning |
|---|---|
blocks | The 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_to | A link with no ordering constraint. |
deps_write(ops=[{op:"linear",
ids:[A, B, C]}])
deps_write(ops=[{op:"fan_out",
from:A, toIds:[B, C, D]}])
deps_write(ops=[{op:"fan_in",
fromIds:[A, B], to:C}])
unblockAt | The edge is satisfied when the blocker reaches |
|---|---|
| queue | any role except blocked, so almost immediately |
| work | work, review or terminal |
| review | review or terminal |
| terminal | terminal (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.