MCP Task Orchestrator · Field guidePlate 7 of 10

Ask the graph what to do next

Agents read state far more often than they change it. A handful of read calls answer the questions a session actually has: where was I, what is next, why is this stuck, and what does this item need.

Which call answers which question

The questionThe callWhat comes back
Where did we leave off?items_read(select="history", since="…")
items_read(select="context")
Recent transitions, newest first, with their actors when the caller may see attribution, and the active and stalled items.
Is anything unhealthy?items_read(select="context")Active, blocked and stalled items, plus a count of live and expired claims.
What does this item need?items_read(select="context", itemId="a3f2c91e")Its gate status: which required notes exist, which are missing (and which seat owes each, as missingBySeat), and the key of the guidance and skill for the next one. When it cannot advance it adds blockedBy. Any decisions raised on the item are listed too, in every status except withdrawn.
What should I pick up?items_read(select="next")Ranked items that can start right now.
Why can't this start?items_read(select="blocked")
items_read(select="context", itemId)
Each blocked item with its blockers, the role each must reach and whether that is satisfied. An explicitly blocked item also carries its reason, the decisionId it waits on and whether it is resumable. For one item, the context says whether it can advance and which gate fails first.
What is under this feature?items_read(select="overview", itemId)The item, its direct children, and a count of children per role. Three modes: no id for the whole database, itemId for one item, anchorId to list an item's children with subtree counts.
Have we seen this before?items_read(select="search", query="…")Relevance-ranked hits with snippets, across item content, note bodies and documents.
What must this note contain?items_read(select="schema", itemId, fields=["guidance"])The resolved schema with the description, skill and (with fields) guidance text of every note.

An item is stalled when it is in work or review and a required note for its current phase is still missing.

How the next item is chosen

A sample backlog, listed oldest first. Change the call and watch which items qualify and in what order.


    
RankItemPriorityComplexityOutcome

Ranking

By default: high, then medium, then low priority. Within a priority, lowest complexity first, with unset complexity last. Remaining ties go to the lower id. oldest gives fair first-in, first-out draining.

What never appears

Items whose blockers have not reached their threshold, items with an active claim, and items under an ancestor with an active claim (the caller's own claims included in both cases). Items with no lifecycle never appear, and complexityMax also drops items with no complexity set. includeClaimed lifts the two claim filters for operators and adds isClaimed to every row, true only for the item's own active claim. An empty page says why in data.reason, claim_held or dependency_unmet, and gives no reason when nothing matched at all.

Other roles

The default role is queue. A review fleet asks with role="review", a triage agent with role="blocked".

The fields on every item

FieldValuesWhat it drives
title, summaryUp to 500 and 2000 charactersWhat agents see in lists and search.
description, statusLabelFree text, both optionalA long description, and a free-form label for the item's status.
typeOne schema key, such as bug-fix. Required on createSelects the schema, so the gates and the lifecycle mode. A missing type is invalid_request and a blank one is schema_violation. When the root declares types, an undeclared one is a schema_violation that lists the availableTypes.
tagsA list, lowercase with hyphensFiltering. Tags never select a schema.
priorityhigh, medium (default), lowFirst key of the next-item ranking.
complexity1 to 10, optionalSecond key of the ranking, and the complexityMax filter.
traitsA list of trait namesExtra notes, seats, resources and dispatch for this one item.
propertiesA JSON object, optionalFree-form data on the item. It cannot carry a traits key.
schemaVersion{server, root, key, layer}, read-onlyThe schema pin: the config versions and base schema the item resolves through. It is taken on create and moves on a type or trait change, a move to another root, a reopen from terminal, or items_write repin.
requiresVerification, metadataA boolean; free-form textWhether completion needs verification, and free-form metadata text.
parentIdAn item id, or none for a rootThe hierarchy. Depth is computed and has no fixed limit.

The role is not among them: it only changes through advance. Ids accept a full UUID or a prefix of 8 to 32 hex characters. An ambiguous prefix is an error. The server never guesses.

Read cheaply

Overview before detail

One overview call returns a feature, its children and per-role counts. That replaces a get per item plus their notes when all you need is status.

Note metadata first

notes_read list returns notes without bodies and gives each body's length. Fetch a body only for the note you will read, filtered by role.

Search is ranked, not exact

Full-text search runs a substring index and a word-stem index and fuses the two rankings. Several words mean all of them. Scope it to a subtree, a role or tags.

Paging and profiles

Pages carry a cursor

A list answers {items, page: {total, truncated, next?, capped?}}. next is present exactly when truncated is true. capped means the underlying list was cut at a fixed ceiling, so total is the capped size. Pass page.next back as cursor. There is no offset.

The tool profile limits the selects

The orchestration profile has every select. The knowledge profile has get, list, overview, related, schema and search: no context, next, blocked or history. The director profile has get, list, overview and blocked, plus deps_read list and graph.

Knowledge reads

related finds items by dependency, link, shared tag and similar text and says why in reasons. docs_read reads plan documents, deps_read walks incoming links and the graph, and get takes fields or ifVersion to stay small.

One database, several projects

Project Atype: project feature bugs task task bug a project read: ancestorId = root A Project Btype: project feature proposals Personalproject, tagged personal-root quick task anchors new items, reads stay unscoped Session Retrospectivescontainer Improvement Proposalscontainer, process-wide Retrospective Trendscontainer agent-observation itemsstandalone, no container process-wide, outside every project
Every box in the top row is a root item at depth 0. A project root is an ordinary item of type project. Its id is the rootId that per-project config, plan documents and rules are stored under. Project-scoped improvement proposals live in a container under their project root; the process-wide container holds the rest.

Set up a project

/task-orchestrator:init finds or creates the project root, writes project: { rootId, name } into the repo's .taskorchestrator/config.yaml, pushes the config and seeds the bundled rules.

Set up a personal root

init --user creates one root for every directory that has no config of its own. It gives new items a home. It does not narrow what reads return.

Scope every read

With a project root, agents pass ancestorId on the items_read selects list, search, next, context and blocked, and parent new top-level items under the root.