jpicklyk/task-orchestrator/quick-start

Quick Start - MCP Task Orchestrator

Not a director-mode skill: run it outside director mode (/task-orchestrator:director off); director-guard denies its file, shell and config steps partway through.

Interactive onboarding that teaches by doing. Detects your workspace state and adapts. Calls are 4.0 tool calls; shapes live in `../_generated/call-shapes.md`. Every answer is the response envelope (ok, data or error). A write is {ops: [...]} of flat elements (one per to-call block here). Results come back as data.results[i] in request order with data.summary {ok, failed}; read ops of an ops tool (config get, validate, effective) answer there too. These calls are non-atomic: if any element fails, even in a one-element call, the answer is ok: false with top-level error.code: partial_failure (no detail, no fix) beside the full data, and the cause is that element's data.results[i].error (code, message, detail, fix). Any other top-level error.code is a call-level rejection (envelope, unknown field, access).

Step 0: Learn Your Tools First

Teach this before anything else. The server shows a client only the tools of its profile:

/task-orchestrator:init sets up the registration for you. A client sees only its own profile's selects and ops; a hidden one looks absent.

Any tool answers describe: true with its own parameters and errors instead of running. When unsure about a field, ask the tool:

{ "describe": true }

{ "select": "overview", "describe": true }

The first form works on any tool; the second asks a select tool about one select. The same data is rendered in `../_generated/call-shapes.md`.

Step 1: Detect Workspace State

Resolve the scope first. Check the SessionStart context: a ## Project Scope section carries a project rootId (it scopes reads and anchors new items); a ## Personal Scope section carries a personal root (it only anchors new items; reads stay unscoped).

Without session context, ask the config locator, not a cwd-relative file read. Resolve <plugin root> as init Step 0 does, then:

node --input-type=module -e "const m = await import('file:///<plugin root>/hooks/config-locator.mjs'); const l = m.locateConfig(); console.log(JSON.stringify({scope: l.scope, path: l.path, rootId: l.rootId, name: l.name}))"

(forward slashes only; the drive-letter form on Windows). Scope project with a rootId is a project rootId; scope user with a rootId is the personal root.

Health check; pass ancestorId only when a project rootId is known (personal scope, or a truly fresh workspace, calls it unscoped):

{"tool": "items_read", "select": "context", "args": {"ancestorId": "<rootId>"}}

The health view lists work and review items as active and never lists queue items, so a backlog-only workspace looks empty there. Check the queue too, with one cheap read (add ancestorId when a project rootId is known):

{"tool": "items_read", "select": "list", "args": {"role": "queue", "limit": 1, "ancestorId": "<rootId>"}}

If `data.active.items`, `data.blocked.items` and `data.stalled` are all empty AND the queue read returns no items, follow the Fresh-Start Path (Steps 2-8). Otherwise follow the Orientation Path (Steps A-C).

Step 1.5: Project Setup (delegated to init)

Check whether this workspace has a project anchor yet: if either kind of root (project or personal) is known from Step 1, it is set up.

If no root is known, offer setup via AskUserQuestion: "This workspace isn't set up for Task Orchestrator yet. Run `/task-orchestrator:init` to create a project anchor (or `/task-orchestrator:init --user` for a personal root that serves every unconfigured directory)?" /task-orchestrator:init owns the anchor, the config.yaml project: block, the server push and the bundled-rule seeding; this skill does none of that. If the user declines, proceed unscoped; nothing else here requires an anchor.

Fresh-Start Path

Step 2: Welcome - The Big Picture

Explain briefly:

• For anything non-trivial Claude enters plan mode: it explores the codebase and writes a plan to a persistent markdown file.
• The MCP Task Orchestrator complements the plan by tracking execution state: what is started, blocked, done, and next.
• The plan file is your design document (the what and how); the MCP is your project board (progress and status).
• The MCP also helps during planning: Claude checks for existing tracked work and schema requirements first, setting a definition floor so the plan accounts for documentation gates and does not duplicate work in progress.
• Together they give continuity across sessions: the plan tells you the approach, the MCP tells you where you left off.

Step 3: The Plan Mode Pipeline

You describe what you want
        |
        v
  EnterPlanMode              <- Claude explores the codebase
        |
  pre-plan hook fires        <- sets the definition floor: existing work, schemas, gates
        |
        v
  Plan written to disk       <- persistent markdown file: your design document
        |
  Plan approved (ExitPlanMode)
        |
  post-plan hook fires       <- tells Claude to materialize before implementing
        |
        v
  Materialize                <- Claude creates MCP items from the plan
        |                       items, dependencies, notes: execution tracking
        v
  Implement                  <- subagents work, each moving its own item
        |                       advance transition: start -> work -> complete
        v
  Health check               <- items_read context shows what completed and what did not

Reinforce: the plan file and MCP items are not duplicates, they serve different roles; MCP items track each unit of work through a lifecycle (who is on it, what is blocked, what is done); the plugin hooks inject this guidance automatically.

Step 4: Hands-On - Create Your First Items

Determine the topic: use $ARGUMENTS if given; otherwise ask via AskUserQuestion with options like "A web app feature", "A bug fix workflow", "A documentation project", or Other.

Read the declared types first. The server rejects an undeclared type with schema_violation whenever it declares any, so ask which exist (pass rootId when a root is known):

{"tool": "config", "op": "effective", "args": {"rootId": "<rootId>"}}

data.results[0].types lists the declared types and data.results[0].schemas their resolved schemas. Use the root type: "container" when it is declared (or any declared type, or any name when the server declares none); give the children a declared non-container type, shown below as <task-type>. If the list is long, ask the user which type fits a task.

Create the container, three children and two dependencies as ONE atomic unit. With a project or personal root known, add parentId so the tree hangs under it.

{"tool": "items_write", "op": "create_tree", "args": {"root": {"title": "<Project Name> - Tutorial", "summary": "Quick-start tutorial project to learn MCP Task Orchestrator", "type": "container", "priority": "medium"}, "children": [{"ref": "design", "title": "Design <topic>", "summary": "Define requirements and approach", "type": "<task-type>", "priority": "high"}, {"ref": "implement", "title": "Implement <topic>", "summary": "Build the solution", "type": "<task-type>", "priority": "high"}, {"ref": "test", "title": "Test <topic>", "summary": "Verify the implementation", "type": "<task-type>", "priority": "medium"}], "deps": [{"from": "design", "to": "implement", "type": "blocks"}, {"from": "implement", "to": "test", "type": "blocks"}]}}

Read the envelope: ok, then data.results[0].ok; on success data.results[0].items is [{ref, id, depth}] (keep the ids) and on failure data.results[0].error.code (schema_violation carries data.results[0].error.detail.availableTypes); the top-level error.code is then partial_failure.

Explain:

• create_tree creates everything atomically: the container, three children and two edges. In a real workflow Claude does this after a plan is approved.
• A blocks edge means the target cannot start until the source completes.
• ref names are local aliases used only within this call.

<Project Name> - Tutorial (container)
  |- Design <topic>          <- actionable (no blockers)
  |- Implement <topic>       <- blocked by Design
  '- Test <topic>            <- blocked by Implement

These items are the project board side; the plan file would hold the design decisions behind each.

Fill the required notes (gate prerequisite). start needs the current phase's required notes filled, and complete needs every required note across all phases of the resolved schema, including notes traits add. Read the exact list for the design item; schema[] shows each key with required and filled:

{"tool": "items_read", "select": "context", "args": {"itemId": "<design-id>"}}

Fill each missing required key (one upsert element per key; the first shown, other keys the same way):

{"tool": "notes_write", "op": "upsert", "args": {"itemId": "<design-id>", "key": "<note-key>", "role": "<queue|work|review>", "body": "Define requirements and approach for <topic>."}}

Check ok and each data.results[i].ok; a failed element's cause is data.results[i].error.code. Tell the user: in a real workflow subagents fill these notes as work happens, phase by phase; here we pre-fill them only so the complete call in Step 5 is not gate-blocked.

Step 5: The Role Lifecycle

Items move queue, work, review, terminal through advance transition triggers.

5a. Start the design task:

{"tool": "advance", "op": "transition", "args": {"itemId": "<design-id>", "trigger": "start"}}

Check ok and data.results[0].newRole; on a failure data.results[0].error.code (gate_blocked: error.detail.missing names the unfilled notes). Point out cascades: a parent whose schema lifecycle is auto (or that has no schema) moves queue to work when its first child starts and is listed there; a manual container, such as the server floor's container, does not cascade and stays in queue (cascades empty) until advanced itself. In a real workflow each subagent calls this when it begins its item.

5b. Complete the design task:

{"tool": "advance", "op": "transition", "args": {"itemId": "<design-id>", "trigger": "complete"}}

Point out unblocked: implement is now unblocked. An auto container stays in work while siblings are active and completes with the last child; a manual one moves only when you advance it.

5c. Confirm what is next:

{"tool": "items_read", "select": "next", "args": {"limit": 3}}

Implement is now recommended: it was unblocked when design completed. This is how the MCP answers "what should I work on next?" across sessions.

Step 6: Cross-Session Continuity