MCP Task Orchestrator · Field guidePlate 1 of 5

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 Every transition goes through the same call, and each one 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.

One gate, seen from the agent

A new session with no memory of yesterday picks up an item and runs into the gate.

  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(op="transition", itemId="a3f2c91e", trigger="start")
    gate_blocked: missing note requirements (queue)
    The item's schema requires a requirements note before work starts.
  3. 3
    notes_write(op="upsert", itemId="a3f2c91e", key="requirements", role="queue", body="Validate email format…")
    Upserted. Note version 1.
    The agent writes the note the error named.
  4. 4
    advance(op="transition", itemId="a3f2c91e", trigger="start")
    queue → work. 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)

Actor 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

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, and every enforcement layer is opt-in through a YAML file.

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 full tool surface, 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, enforced on every transition.

  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