A light touch MCP task orchestration server for AI agents. Persistent work tracking and context storage across sessions and agents. Defines planning floors through composable notes with optional gating transitions. Coordinates multi-agent execution without prescribing how agents do their work.
AI Agentsai-coding-assistantai-developmentai-memoryai-toolsclaude
Installation
# Add to your Claude Code skills
git clone https://github.com/jpicklyk/task-orchestrator
README.md
MCP Task Orchestrator
Schema-driven workflow enforcement for AI agents.
An MCP server that gives AI coding assistants a persistent work item graph with server-enforced quality gates. Define workflow schemas in YAML to do two things: (1) set a planning floor that enforces your minimum specification requirements before work can start, and (2) guide agent workflows through each phase with structured instructions the server surfaces at exactly the right moment. Items flow through queue → work → review → terminal with dependency enforcement and gate-checked transitions — the server blocks progression until required work is done and tells agents precisely what's missing. The result: deterministic workflow progression that doesn't depend on prompt discipline, and persistent state that lets agents pick up where they left off across sessions.
Why This Exists
AI agents have no built-in way to manage complex work. Without persistent state, every session starts from zero — no memory of what was planned, what's done, or what's blocked. Multi-step projects fall apart as the agent loses track of decisions, dependencies, and progress.
Task Orchestrator gives agents a structured backbone: a persistent work item graph where items flow through queue → work → review → terminal with dependency enforcement and note-based documentation at every phase. The server — not the AI — enforces what can happen next: gate-checked transitions, dependency ordering, and required documentation create regardless of which model, session, or sub-agent is driving. Agents read concise notes instead of replaying conversation history — implementing that keep the agent aligned across sessions and sub-agent boundaries.
This is a one-time step — Docker caches the image locally. Pulling first ensures your MCP client connects instantly rather than waiting silently on first launch.
The mcp-task-data Docker volume persists the SQLite database across container restarts. The server auto-initializes its schema on first run — no additional setup required.
Option C: Other MCP Clients
Configure your client with the same JSON as Option A above. STDIO transport works with any MCP-compatible client.
Advanced: Per-Project Note Schemas
By default the server runs in schema-free mode — all 13 tools work with no additional configuration. If you want to define custom note schemas that gate role transitions (e.g., require an acceptance-criteria note before a work item can advance), you can point the server at your project's .taskorchestrator/config.yaml.
Add the config mount to your Option B.mcp.json only (not the global Option A registration — a globally-registered server should not have its schema config vary per project):
Security note: Only the .taskorchestrator/ folder is mounted — the server has no access to the rest of your project. The container's /project path contains nothing else.
See Workflow Guide for the .taskorchestrator/config.yaml schema format and examples.
Advanced: Per-Project Data Isolation
By default, all projects share the mcp-task-data Docker volume — a single SQLite database for everything. To give a project its own isolated task store, change the volume name in the -v flag to something project-specific:
"-v", "my-project-data:/app/data",
Docker creates the volume automatically on first run. Each named volume is a completely separate database — work items, notes, and dependencies from one project never appear in another. Combine this with the per-project .mcp.json (Option B) so the scoped volume and config schema travel together with the project.
Step 3: Claude Code Plugin (optional)
The plugin adds workflow skills, automation hooks, and an orchestrator output style to Claude Code. The MCP server (Step 2) must be connected first.
After installing, restart Claude Code and verify with /plugin list — you should see task-orchestrator enabled.
Skills — invoke as slash commands in any Claude Code session:
| Command | Description |
|---------|-------------|
| /task-orchestrator:work-summary | Insight-driven dashboard: active work, blockers, and next actions |
| /task-orchestrator:create-item | Create a tracked work item from the current conversation context |
| /task-orchestrator:quick-start | Interactive onboarding — teaches by doing, adapts to empty or populated workspaces |
| /task-orchestrator:manage-schemas | Create, view, edit, delete, and validate note schemas in config |
| /task-orchestrator:status-progression | Navigate role transitions; shows gate status and the correct trigger |
| /task-orchestrator:dependency-manager | Visualize, create, and diagnose dependencies between work items |
| /task-orchestrator:batch-complete | Complete or cancel multiple items at once — close out features or workstreams |
Hooks — automatic, no invocation needed:
Session start — loads current work context at the beginning of each Claude Code session
Plan mode — after plan approval, prompts Claude to create MCP items so persistent tracking stays in sync
Subagent start — injects task context into spawned subagents so they start with full awareness
Output style — The plugin includes a Workflow Orchestrator output style that turns Claude Code into a project management orchestrator: it plans, delegates to subagents, and tracks progress without writing code directly. Select it from the output style menu (/output-style) or enable it in your Claude Code settings. See Output Styles and Self-Improving Workflow for advanced patterns.
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
