• Phase gate enforcement — items cannot advance until required notes are filled
• Per-tag documentation requirements (different schemas for features, bug fixes, tasks)
• The guidance field — schema authors communicate authoring intent; agents resolve it via guidanceKey (a reference) or query_items(operation="schema") (full text)
• Universal fallback via the default schema for untagged items

• Tier 1: Bare MCP setup complete
• Write access to your project root (to create .taskorchestrator/config.yaml)

This is the most important concept to understand before configuring schemas.

• Schemas = rules defined in .taskorchestrator/config.yaml. They specify which notes must exist at each phase. Never stored in the database.
• Notes = content that agents write via manage_notes. Stored in the MCP database. Notes carry no reference to schemas.
• They meet only at gate-check time: when advance_item fires, it fetches the item's notes from the database and checks them against schema requirements. If required notes are missing, the gate rejects the transition.

Items with no matching schema tag — and no default schema — advance freely with no gate enforcement.

Create .taskorchestrator/config.yaml in your project root:

note_schemas:
  my-feature:
    - key: task-scope
      role: queue
      required: true
      description: "What the feature must do."
    - key: implementation-notes
      role: work
      required: true
      description: "How you will build it."

This schema says: any item tagged my-feature must have a task-scope note filled before it can advance past queue, and an implementation-notes note before it can advance past work.

The MCP server reads config from the project directory. Mount it read-only alongside the data volume.

For a project-level .mcp.json (shareable with teammates):

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

For a global CLI registration (user-level, not per-project):

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

Only the .taskorchestrator/ folder is exposed — the server has no access to the rest of your project.

See Quick Start Step 8 for the full Docker mount example. If you work across multiple projects, /task-orchestrator:configure-server sets up config-sync instead, which hot-reloads each project's config without a read-only mount or a restart.

The server caches schemas on first access. After editing config.yaml, reconnect the MCP server by running /mcp in Claude Code and toggling the connection, or restart the container.

note_schemas:
  <schema-key>:
    - key: <note-key>
      role: <queue|work|review>
      required: <true|false>
      description: "<Short description of expected content.>"
      guidance: "<Optional longer authoring instructions for agents.>"

A full lifecycle schema with gates at every transition:

note_schemas:
  feature:
    - key: feature-summary
      role: queue
      required: true
      description: "Problem statement, approach, and acceptance criteria."
      guidance: "Cover: what problem this solves, who benefits, acceptance criteria, and alternatives considered (minimum 2 real options plus 'do nothing')."
    - key: implementation-notes
      role: work
      required: true
      description: "What was built, deviations from the plan, decisions made."
      guidance: "Document decisions not captured in the feature-summary. Focus on what downstream agents or reviewers need to know."
    - key: review-checklist
      role: review
      required: true
      description: "Quality gate — plan alignment and test coverage."
      guidance: "Verify: what was built matches the feature-summary, tests cover the acceptance criteria."

With this schema:

• advance_item(trigger="start") from queue checks feature-summary exists, then advances to work
• advance_item(trigger="start") from work checks implementation-notes exists, then advances to review
• advance_item(trigger="start") from review checks review-checklist exists, then advances to terminal
• advance_item(trigger="complete") checks all required notes across all phases before advancing to terminal

When an item has no review-phase required notes, start from work advances directly to terminal, skipping review.

The default key matches any item whose tags do not match any other schema key:

note_schemas:
  feature:
    # feature-specific notes
  default:
    - key: session-tracking
      role: work
      required: true
      description: "What happened during this work session."

This means every item gets at least session-tracking enforced, even items with no matching tag. Keep the default schema minimal — it applies to everything that falls through the tag-matching rules.

The guidance field is a communication channel from the schema author to the agent. get_context and advance_item return only a guidanceKey — the key of the first unfilled required note with guidance — not the guidance text itself.

- key: feature-summary
  role: queue
  required: true
  description: "Problem statement and approach."
  guidance: "Cover: problem statement, who benefits, acceptance criteria, alternatives (min 2 + 'do nothing'), blast radius, and test strategy."

Full guidance text surfaces in two places; elsewhere agents get only a reference:

guidanceKey is omitted when all required notes for the current phase are filled, or when no schema entry for the current phase defines a guidance value.

See Workflow Guide Section 5.5 for full guidance-resolution semantics.

• Items can have multiple tags (comma-separated string)
• The first tag that matches a schema key wins — each item matches at most one schema
• If no tag matches, the default schema applies (if defined)
• Items with no matching schema and no default advance freely with no gates

See Workflow Guide Section 9 for the full matching specification.

Schema:

note_schemas:
  bug-fix:
    - key: diagnosis
      role: queue
      required: true
      description: "Reproduction steps, root cause, and fix approach."
      guidance: "Include: exact reproduction steps, root cause (file + function + condition), fix approach, alternatives considered, and regression test plan."

Workflow:

1. Create the item:

manage_items(operation="create", items=[{
  "title": "Fix login timeout",
  "tags": "bug-fix"
}])

Response includes expectedNotes listing the diagnosis note (key/role/required/exists only — resolve its guidance via query_items(operation="schema")).

2. Check gate status:

get_context(itemId="<uuid>")

Response shows gateStatus.canAdvance: false, gateStatus.missing: ["diagnosis"], and guidanceKey: "diagnosis" (resolve the authoring instructions via query_items(operation="schema", itemId=...)).

3. Try to advance (rejected):

advance_item(transitions=[{ "itemId": "<uuid>", "trigger": "start" }])
// Error: required notes not filled for queue phase: diagnosis

4. Fill the note:

manage_notes(operation="upsert", notes=[{
  "itemId": "<uuid>",
  "key": "diagnosis",
  "role": "queue",
  "body": "## Reproduction\n1. Log in with a valid account\n2. Leave session idle for 28 minutes\n3. Submit any form — request fails with 401\n\n## Root cause\nSessionManager.refreshToken() does not extend expiry when called within the last 5 minutes of the token window.\n\n## Fix approach\nExtend refresh window to 10 minutes. Considered: (1) always refresh on request — rejected, too many DB writes. (2) do nothing — rejected, breaks UX.\n\n## Regression test\nNew unit test for token refresh boundary conditions."
}])

5. Advance (succeeds):

advance_item(transitions=[{ "itemId": "<uuid>", "trigger": "start" }])
// Item moves queue → work

If you have the plugin installed, the /task-orchestrator:manage-schemas skill walks you through creating, viewing, editing, and validating schemas without editing YAML directly. See Plugin: Skills and Hooks.

Signal: You want automated workflows — plan-mode integration, subagent protocols, skill-based commands — not just schema-enforced gates.

Next: Plugin: Skills and Hooks — install the Claude Code plugin for automated orchestration.