quick-start

What this skill does

# 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:

| Want to... | Skill | What it does |
|---|---|---|
| Track a feature with documentation gates | `/manage-schemas` | Create sc