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.