任务编排器

3. Multi-project setup (HTTP + config-sync)

If you work across several repositories, run one persistent server with the REST API enabled. Each project's .taskorchestrator/config.yaml then syncs into it automatically through the plugin's config-sync hook: no per-project container, no manual mount, and config changes hot-reload without a restart. The plugin's /task-orchestrator:configure-server skill renders this setup interactively; the manual equivalent is:

docker pull ghcr.io/jpicklyk/task-orchestrator:latest

docker run -d --name mcp-task-orchestrator-http --restart unless-stopped \
  -v mcp-task-data:/app/data \
  -e MCP_TRANSPORT=http -e API_ENABLED=true -e API_AUTH_MODE=none -e API_ALLOW_UNAUTHENTICATED=true \
  -p 127.0.0.1:3001:3001 \
  ghcr.io/jpicklyk/task-orchestrator:latest

Register it in .mcp.json using the HTTP shape:

{
  "mcpServers": {
    "mcp-task-orchestrator": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

And export the client-side variable that tells config-sync where the server is (without it, config-sync silently does nothing):

export TASK_ORCHESTRATOR_API_URL=http://localhost:3001

Alternatively, a client.json (apiUrl only, no token) supplies the URL. Project-mode /task-orchestrator:init writes it beside the project config, only for a loopback server and only as a bare origin with no path, query or fragment (add .taskorchestrator/client.json to .gitignore, the URL is machine-specific); /task-orchestrator:init --user writes the user-level file, which works for any host. The order is the environment variable, then the project-level file, then the user-level file. /task-orchestrator:init sets up a project root for the current directory, and /task-orchestrator:init --user creates a personal root that serves every directory without its own config.

SECURITY: unauthenticated REST means anyone who can reach the port has full read/write/delete access. This is only safe because the port is published loopback-only (-p 127.0.0.1:3001:3001). Never publish it on 0.0.0.0 or a wider interface. For shared or networked deployments use bearer tokens or JWKS auth — see Fleet Deployment.

Prefer to run without Docker? CONTRIBUTING.md covers building the fat JAR from source.

---

Quick Start

Prerequisite: Docker installed and running.

.taskorchestrator/config.yaml

work_item_schemas: feature-task: notes: - key: requirements role: queue required: true description: "Acceptance criteria before starting" guidance: "Cover: problem statement, acceptance criteria, alternatives considered, test strategy." skill: "spec-quality" - key: implementation-notes role: work required: true description: "What was built and why" ```

With this schema, advance_item(trigger="start") from queue requires requirements to be filled. The server returns an error listing exactly which notes are missing.

The guidance field provides authoring instructions surfaced at the right moment: when an agent is about to fill that note, the response carries the guidance as a guidancePointer. The skill field goes further, naming a skill the agent should invoke before filling the note so the evaluation follows a defined framework rather than freeform prose.

REST API

An optional HTTP layer (API_ENABLED=true) exposes items, notes, dependencies, transitions, config, and real-time SSE events to dashboards, CI systems, and operators. It supports static bearer tokens, JWKS JWT auth, and the unauthenticated loopback mode shown in the Quick Start. It also powers config-sync, so one server can serve many projects with per-project schemas. See the REST API Reference.

Illustrated: Runtime Map covers the server's layers, both deployment shapes, the REST API, claims and actor identity.

2. Enable workflow schemas

Create .taskorchestrator/config.yaml in your project (see Workflow Enforcement for an example, or use the plugin's /task-orchestrator:manage-schemas skill) and mount that folder into the container:

{
  "mcpServers": {
    "mcp-task-orchestrator": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "mcp-task-data:/app/data",
        "-v", "/absolute/path/to/your/project/.taskorchestrator:/project/.taskorchestrator:ro",
        "-e", "AGENT_CONFIG_DIR=/project",
        "ghcr.io/jpicklyk/task-orchestrator:latest"
      ]
    }
  }
}

Use an absolute host path. Claude Code's .mcp.json expands only environment variables (${VAR} and ${VAR:-default}), so editor-style placeholders such as ${workspaceFolder} are not substituted. Only the .taskorchestrator/ folder is exposed; the server has no access to the rest of your project.

Workflow Enforcement

Schemas define what agents must produce at each phase, and the server blocks progression until it's done. They also set a planning floor: when an agent enters plan mode, the schema tells it what documentation must exist before implementation can start, shaping the plan itself.

```yaml

Claude Code Plugin

The plugin adds workflow automation on top of the MCP server: skills, hooks, and an orchestration context.

Install:

/plugin marketplace add https://github.com/jpicklyk/task-orchestrator
/plugin install task-orchestrator@task-orchestrator-marketplace

What it adds:

The MCP server works without the plugin. The plugin makes it seamless with Claude Code.

Optional mod (early access): task-orchestrator-mod is a separate, opt-in plugin of in-process function hooks: a live work-graph pane, an in-flight band and status line, and in-process retrospective, phase-guard and call-shape hooks. It relies on an early-access Claude Code API and is best paired with a current task-orchestrator plugin.

/plugin install task-orchestrator-mod@task-orchestrator-marketplace

Illustrated: Orchestrating a Run follows one feature from request to finished items. Improvement Loop shows how friction noticed during work becomes a reviewed config change.

---