Task Orchestrator

Server-enforced workflow discipline for AI agents.

Prompt-based frameworks hope the LLM follows instructions. This one blocks the call if it doesn't.

Task Orchestrator is an MCP server that gives AI coding agents a persistent work item graph with quality gates enforced by the server, not the prompt. It is built for developers running multi-agent or multi-session coding workflows: an orchestrator dispatching sub-agents, a fresh session picking up yesterday's work, or an autonomous loop draining a backlog. It ships as a Docker image, works with any MCP client, and has an optional Claude Code plugin that adds skills and hooks on top.

The Problem

Multi-agent workflows need infrastructure the model doesn't provide. When an orchestrator dispatches sub-agents across sessions, there's no built-in way to enforce what documentation must exist before work starts, track which agent made which change, or guarantee dependency ordering across a work breakdown. These are structural concerns — they belong in the server, not in prompts.

Task Orchestrator puts them in the server. If a required design note isn't filled, advance_item returns an error naming the missing note. If an upstream dependency isn't complete, the transition is blocked. Every transition and note records who made it. A new session recovers the full state in one call instead of replaying a conversation. And the rules are YAML config, not hardcoded prompts — change them without changing code.

What It Looks Like

Morning — new session, new agent, zero context:

Agent: get_context(since="2025-01-14T17:00:00Z")
       → 2 items in work, 1 blocked, 1 stalled (missing implementation-notes)
       → Recent transitions show orchestrator-1 dispatched 3 sub-agents yesterday
       → Full ancestor chains: "Auth Feature > Login API > Input validation"

Agent: advance_item(transitions=[{ itemId: "a3f2", trigger: "start",
         actor: { id: "morning-agent", kind: "subagent", parent: "orchestrator-1" } }])
       → Error: "Gate check failed: required notes not filled for queue phase: requirements"

Agent: manage_notes(operation="upsert", notes=[{ itemId: "a3f2", key: "requirements",
         body: "Validate email format, enforce password complexity...",
         actor: { id: "morning-agent", kind: "subagent" } }])
       → Upserted. noteProgress: { filled: 1, remaining: 0, total: 1 }

Agent: advance_item(transitions=[{ itemId: "a3f2", trigger: "start",
         actor: { id: "morning-agent", kind: "subagent" } }])
       → queue → work. Actor recorded. No context rebuilding.

Quick Start

Prerequisite: Docker installed and running.

1. Register the server

The simplest setup is a per-session STDIO container: no port, no daemon, no REST API. Add it to your project's .mcp.json:

{
  "mcpServers": {
    "mcp-task-orchestrator": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "mcp-task-data:/app/data",
        "ghcr.io/jpicklyk/task-orchestrator:latest"
      ]
    }
  }
}

Claude Code users can register the same shape from the CLI instead:

claude mcp add-json mcp-task-orchestrator '{
  "command": "docker",
  "args": ["run", "--rm", "-i", "-v", "mcp-task-data:/app/data", "ghcr.io/jpicklyk/task-orchestrator:latest"]
}'