MCP Task Orchestrator · Field guidePlate 1 of 10

Workflow rules the server enforces

Task Orchestrator is an MCP server that gives AI coding agents a persistent work item graph with quality gates. Prompt-based frameworks hope the model follows instructions. This server blocks the call when it doesn't.

Where the rule lives

In the prompt

Prompt: “write the design note first” Agent set status = in progress Task tracker accepts any write The note was never written. Nothing checked, so the skipped step still succeeds.
The instruction is advice. A long session, a fresh sub-agent or a compacted context can drop it, and no one finds out.

In the server

Agent advance names the note Gate notes filled? blockers done? pass Work item queue → work ownership → seat → table → dependency → notes → lease One call, one gate order. Each transition records who made it.
The rule is structure. An agent that skips the note gets an error that names it, fills it, and tries again. The order above is for a trigger an agent sends. A cascade runs three more gates (warrant, hold, review-pending), and the service fences it on claim and seat separately.

One gate, seen from the agent

A new session with no memory of yesterday picks up an item and runs into the gate. Write calls take an ops list, and each element answers in data.results[].

  1. 1
    items_read(select="context")
    2 items in work, 1 blocked, 1 stalled (missing implementation-notes)
    One call recovers the current state: active, blocked and stalled items and claim counts, with ancestor chains on request. A second read, select="history", lists recent transitions.
  2. 2
    advance(ops=[{op:"transition", itemId:"a3f2c91e", trigger:"start"}])
    results[0].error: gate_blocked (permanent). "Item a3f2c91e-... is missing 1 required notes." detail.missing: requirements (queue)
    The item's schema requires a requirements note before work starts. The error names it in detail.missing.
  3. 3
    notes_write(ops=[{op:"upsert", itemId:"a3f2c91e", key:"requirements", role:"queue", body:"Validate email format..."}])
    results[0]: note created, version 1.
    The agent writes the note the error named.
  4. 4
    advance(ops=[{op:"transition", itemId:"a3f2c91e", trigger:"start"}])
    results[0]: queue → work, statusLabel in-progress. Principal recorded.
    Same call, now it passes. Nothing was rebuilt from conversation history.

What the server owns

A work item graph

Everything is a WorkItem. Items nest to any depth and connect with typed dependency edges.

items_write (create_tree, complete_tree) · items_read

Phase gates

Schemas declare which notes must exist at each phase. Transitions fail until they do.

advance · items_read (context) · notes_write

Dependency ordering

A blocked item cannot start until its blocker reaches the agreed phase. Finishing a blocker reports what it unblocked.

deps_write · items_read (blocked)

Identity and attribution

Transitions and notes record who made them: the principal of the credential the caller presented, or the single local principal for stdio and unauthenticated modes. A caller cannot name itself.

principal: api:<id> | local

Claims

A caller can hold a time-limited claim on an item. While the claim is live, a transition from any other caller is refused. This fence is always on.

advance (claim, release, heartbeat)

Runs and decisions

A run groups items for a coordinator and hands each seat its own token. A seat that needs a ruling raises a decision, and a human or director answers it.

runs_read · runs_write

Documents

Longer text lives in documents anchored to a project root and attached to items, apart from the short notes the gates read.

docs_read · docs_write

Versioned config

Schemas, traits and status labels are stored per project in the database with a version history. Push, validate, roll back or reset them without a restart.

config

Session continuity

A fresh session reads active, blocked and stalled items in one response instead of replaying a conversation.

items_read (context, next)

Scoped, searchable notes

Notes are keyed by phase. Agents read only the note they need, or search items and notes by keyword.

notes_read · items_read (search)

The server owns these guardrails and nothing else. It has no opinion on how agents plan or write code. Claim fencing, note ownership and the required item type are always on. Note schemas, traits, lifecycle modes and run seats are the layers you opt into through config. The tools come in three profiles: orchestration (the default), knowledge and director.

Adopt it one tier at a time

Each tier builds on the one before. Note schemas (tier 3) can be added at any point.

  1. Bare MCP

    Any MCP clientThe tools of one profile (a stdio server serves one, HTTP serves all three), a persistent SQLite store and the role-based workflow.
  2. CLAUDE.md-driven

    Claude Code usersConsistent agent behaviour from project instructions.
  3. Note schemas

    Anyone who wants gatesRequired documentation per phase, checked when an item starts or completes, and by cascades.
  4. Plugin: skills and hooks

    Claude Code with the pluginPlan-mode integration, sub-agent protocols and per-project config sync.
  5. Orchestration mode

    Power usersClaude plans, delegates to sub-agents and tracks progress as an orchestrator.
  6. Self-improving workflow

    Teams tuning their processObservations and retrospectives feed proposals that change the schemas.

Built with

Kotlin + coroutinesSQLite · Exposed ORM · FTS5Flyway migrationsMCP Kotlin SDK (STDIO, Streamable HTTP)Ktor REST + SSEDocker image on ghcr.io