Quick Start — MCP Task Orchestrator

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

Step 1: Detect Workspace State

Call the health check to determine which path to follow:

get_context()

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).

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.

Step 5: The Role Lifecycle

Every MCP item moves through roles: queue (planned) → work (active) → review (verifying) → terminal (done). This is how the MCP knows what's in progress and what's finished.

5a. Start the design task:

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

Point out in the response:

• Design moved from queue → work
• Check cascadeEvents — the container likely cascaded from queue → work automatically (first child started)
• In a real workflow, each subagent calls this when it begins working on its assigned item

5b. Complete the design task:

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

Point out in the response:

• Design moved from work → terminal
• Check unblockedItems — implement should now be 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.

Step 6: Cross-Session Continuity

This is where the plan file and MCP complement each other most visibly. Explain:

• If a session ends mid-work, the next session can call get_context() or /work-summary to see exactly which items are in progress, which are blocked, and which are done
• The plan file is still on disk — Claude can re-read it to recall the design approach
• The MCP items show execution state — no need to re-explain what's been completed
• Together: "Read the plan to remember the approach. Check the MCP to see where you left off."

This is the difference between having a plan document alone vs. having a plan document plus a live project board. The plan doesn't change as work progresses — the MCP does.

Step 7: Note Schemas (Optional Power Feature)

Briefly mention that MCP items can have required notes that act as documentation gates:

• A .taskorchestrator/config.yaml file defines schemas under work_item_schemas: — which notes must be filled before an item can advance
• Items match schemas via their type field (e.g., type: "feature-implementation" activates that schema's notes and gates)
• Example: the feature-implementation schema requires a specification note before work can start, and a review-checklist note before completion
• Each schema can set a lifecycle mode (auto, manual, auto-reopen, permanent) controlling cascade behavior
• Notes can carry a guidance field (authoring hints) and a skill field (structured evaluation framework to invoke before filling)
• Composable traits add additional note requirements per-item — e.g., traits: "needs-security-review" adds a security-assessment note at the review phase
• Run /manage-schemas to set one up interactively — it can also generate a companion lifecycle skill for your schema

Step 8: What's Next

Present this capabilities table:

Offer cleanup: Ask via AskUserQuestion whether to keep the tutorial items for reference or delete them. If delete, use the container UUID returned in Step 4 above:

manage_items(operation="delete", ids=["<container-UUID>"], recursive=true)

Orientation Path

For users with an existing populated workspace.

Step A: Health Check Dashboard

Run two calls in parallel:

get_context()
query_items(operation="overview", includeChildren=true)

Present a condensed dashboard with these sections:

• Active Work (role=work or review): items currently in progress — show title, role, and ancestor path
• Blocked / Stalled: items that cannot advance — either dependency-blocked or missing required notes
• Containers: root items with child counts by role
• Recommendations: from get_next_item(limit=3, includeDetails=true)

Use status symbols: ◉ in-progress, ⊘ blocked, ○ pending, ✓ completed

Step B: Explain What You're Seeing

For each section of the dashboard, add a brief annotation:

• Active items are in work or review role — these are things being worked on right now
• Blocked items have unsatisfied dependencies (another item must complete first) or are missing required notes that gate advancement
• Stalled items have required notes that haven't been filled — use get_context(itemId=...) to see which notes are missing, then manage_notes(upsert) to fill them
• Containers at depth 0 organize your work hierarchically — items can nest up to depth 3

If blocked items exist, explain: "Run /status-progression on a blocked item to see exactly what's needed to unblock it."

Explain the plan mode connection: These MCP items are the execution tracking side of your work. When Claude enters plan mode, it writes a persistent plan file (your design document). When the plan is approved, the plugin hooks tell Claude to create MCP items like these to track implementation progress. The plan file and MCP items are complementary — the plan captures what and how, the MCP tracks progress and status.

Step C: Suggested Next Action

Based on the dashboard, recommend one concrete action:

End with: "Run /work-summary anytime to see this dashboard. When you're ready to build something, just describe it — Claude will enter plan mode, write a plan file, and create MCP items to track the work automatically."