/quick-start

name: quick-start
description: Interactive onboarding for the MCP Task Orchestrator. Detects empty or populated workspaces and walks through how plan mode, persistent tracking, and the MCP work together. Use when a user says "get started", "how do I use this", "quick start", "first time setup", "onboard me", "what can this MCP do", or "help me learn task orchestrator".
argument-hint: "[optional: describe what you want to track, e.g. 'a web app project']"

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: "fe