MCP Task Orchestrator · Field guidePlate 1 of 9

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_item 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
    get_context(since="2025-01-14T17:00:00Z")
    2 items in work, 1 blocked, 1 stalled (missing implementation-notes)
    One call recovers the full state: active items, recent transitions with their actors, and ancestor chains.
  2. 2
    advance_item(itemId="a3f2", trigger="start")
    Gate check failed: required notes not filled for queue phase: requirements
    The item's schema requires a requirements note before work starts.
  3. 3
    manage_notes(operation="upsert", key="requirements", body="Validate email format…")
    Upserted. noteProgress: { filled: 1, remaining: 0, total: 1 }
    The agent writes the note the error named.
  4. 4
    advance_item(itemId="a3f2", trigger="start")
    queue → work. Actor 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.

create_work_tree · manage_items · query_items · complete_tree

Phase gates

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

advance_item · get_next_status · manage_notes

Dependency ordering

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

manage_dependencies · get_blocked_items

Actor attribution

Transitions and notes record who made them, including which orchestrator dispatched which sub-agent. JWKS verification is optional.

actor: { id, kind, parent }

Session continuity

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

get_context · get_next_item

Scoped, searchable notes

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

query_notes · query_items(operation="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