Quick Start

Quick Start — MCP Task Orchestrator

Interactive onboarding that teaches by doing. Detects your workspace state and adapts.

Step 1: Detect Workspace State

Resolve the scope first. Check session context for the SessionStart hook's output: 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.

Call the health check to determine which path to follow:

get_context()

When a project rootId is known, pass it to scope the check to this project: get_context(ancestorId="<rootId>"). In personal scope, or when no rootId is known (a truly fresh workspace), call unscoped exactly as shown.

If no active or stalled items exist — follow the Fresh-Start Path (Steps 2-8). If active items exist — follow the Orientation Path (Steps A-C).

Step 1.5: Project Setup (delegated to init)

Before following either path, check whether this workspace has a project anchor yet. Use the scope resolved in Step 1: if either kind of root (project or personal) is known, the workspace is set up and nothing more is needed here.

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 itself. If the user accepts, run it (or tell them to) and then continue here.

If the user declines, proceed unscoped. Nothing else in this skill requires an anchor.

Fresh-Start Path

Step 2: Welcome — The Big Picture

Explain briefly:

• When you ask Claude to build something non-trivial, it enters plan mode — exploring the codebase and writing a plan saved as a persistent markdown file
• The MCP Task Orchestrator complements the plan file by tracking execution state — what's been started, what's blocked, what's done, and what's next
• Think of it this way: the plan file is your design document (the what and how), while the MCP is your project board (the progress and status)
• The MCP also helps during planning — Claude automatically checks for existing tracked work and schema requirements before planning, setting a definition floor so the plan accounts for documentation gates and doesn't duplicate what's already in progress
• Together, they give you full continuity across sessions — the plan tells you the approach, the MCP tells you where you left off

Step 3: The Plan Mode Pipeline

Show how plan mode and the MCP work together. This is the workflow users will experience:

You describe what you want
        │
        ▼
  EnterPlanMode              ← Claude explores the codebase
        │
  pre-plan hook fires        ← Plugin sets the definition floor: existing work, schemas, gate requirements
        │
        ▼
  Plan written to disk       ← Persistent markdown file — your design document
        │
  Plan approved (ExitPlanMode)
        │
  post-plan hook fires       ← Plugin tells Claude to materialize before implementing
        │
        ▼
  Materialize                ← Claude creates MCP items from the plan
        │                       Items, dependencies, notes — execution tracking
        ▼
  Implement                  ← Subagents work, each transitioning their MCP item
        │                       advance_item(start) → work → advance_item(complete)
        ▼
  Health check               ← get_context() shows what completed and what didn't

Reinforce to the user:

• The plan file and MCP items are not duplicates — they serve different roles
• MCP items track individual units of work through a lifecycle: who's working on what, what's blocked, and what's done
• The plugin hooks inject guidance automatically so Claude follows this pipeline — you don't need to ask for it

Step 4: Hands-On — Create Your First Items

Now let's create some MCP items to see how the execution tracking works.

Determine the project topic:

• If $ARGUMENTS is provided, use it as the project topic
• Otherwise, ask via AskUserQuestion with options like "A web app feature", "A bug fix workflow", "A documentation project", or Other

Create a container with child items and dependencies in one atomic call:

create_work_tree(
  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: "feature-task", priority: "high" },
    { ref: "implement", title: "Implement <topic>", summary: "Build the solution", type: "feature-task", priority: "high" },
    { ref: "test", title: "Test <topic>", summary: "Verify the implementation", type: "feature-task", priority: "medium" }
  ],
  deps: [
    { from: "design", to: "implement", type: "BLOCKS" },
    { from: "implement", to: "test", type: "BLOCKS" }
  ]
)

Explain to the user:

• create_work_tree creates everything atomically — the container, three child items, and two dependency edges
• In a real workflow, Claude creates these automatically after a plan is approved — the post-plan hook triggers this
• The BLOCKS dependency means: implement cannot start until design completes, test cannot start until implement completes
• The ref names ("design", "implement", "test") are local aliases used only within this call

Show the structure:

<Project Name> — Tutorial (container)
  ├── Design <topic>          ← actionable (no blockers)
  ├── Implement <topic>       ← blocked by Design
  └── Test <topic>            ← blocked by Implement

This is the project board side — these items track progress. The plan file (if this were a real feature) would contain the design decisions behind each of these tasks.

Fill required notes (gate prerequisite): feature-task items require a task-scope note (queue, required) before advance_item(trigger="start") will succeed, and a complete trigger checks ALL required notes across every phase the resolved schema declares — not just the current phase, and not just the base schema's own notes. Traits merge in too: a session-tracked default trait adds a required session-tracking work note, for example, while review-phase notes like review-checklist are typically opt-in per item via a trait (e.g. needs-task-review), not a base requirement. Call get_context(itemId="<design-UUID>") to see the exact resolved note list before filling — schemas vary per project. create_work_tree above created the children with no notes — its createNotes option only auto-fills blank bodies, which don't count as "filled" for gate purposes — so fill every required note the resolved schema lists on the design item now, before Step 5a, so both the start and complete calls succeed. For a feature-task schema with the common task-scope + implementation-notes base plus a session-tracked default trait:

manage_notes(
  operation="upsert",
  notes=[
    { itemId: "<design-UUID>", key: "task-scope", role: "queue", body: "Define requirements and approach for <topic>." },
    { itemId: "<design-UUID>", key: "implementation-notes", role: "work", body: "Design work completed for <topic>." },
    { itemId: "<design-UUID>", key: "session-tracking", role: "work", body: "Design phase completed this session." }
  ]
)

Explain to the user: in a real workflow, subagents fill these notes as work actually happens, phase by phase. Here we're pre-filling all of them up front purely so the tutorial's Step 5b complete call isn't gate-blocked — note bodies don't need to match the item's current role to be saved, only to satisfy the gate check at advance time. If get_context shows additional required notes (e.g. a review-checklist from an opted-in review trait), fill those too before advancing.

Step 5: The Role Lifecycle

Items move queue → work → review → terminal via advance_item triggers — see the advance_item tool description for full trigger semantics.

5a. Start the design task:

advance_item(transitions=[{ itemId: "<design-UUID>", trigger: "start" }])

Point out in the response: cascadeEvents shows the container cascading queue → work (first child started). In a real workflow, each subagent calls this when it begins its assigned item.

5b. Complete the design task:

advance_item(transitions=[{ itemId: "<design-UUID>", trigger: "complete" }])

Point out in the response: unblockedItems shows implement is now unblocked; the container stays in work because siblings are still active.

5c. Confirm what's next:

get_next_item(limit=3, includeDetails=true)

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