From task-orchestrator
Provides interactive onboarding for MCP Task Orchestrator by detecting workspace state and guiding through plan mode, persistent tracking, and workflow integration.
npx claudepluginhub jpicklyk/task-orchestrator --plugin task-orchestratorThis skill uses the workspace's default tool permissions.
Interactive onboarding that teaches by doing. Detects your workspace state and adapts.
Checks MCP for existing work and stalled items, discovers note schemas from .taskorchestrator/config.yaml, and identifies gate requirements to set definition floor before plan mode.
Captures tasks from conversations, generates prioritized daily plans, tracks patterns, and delivers energy-aware recommendations via MCP tools.
Executes multi-step DeepWork workflows with quality gates using MCP tools. Start via /deepwork for code reviews, new jobs, or continuing sessions.
Share bugs, ideas, or general feedback.
Interactive onboarding that teaches by doing. Detects your workspace state and adapts.
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).
Explain briefly:
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:
Now let's create some MCP items to see how the execution tracking works.
Determine the project topic:
$ARGUMENTS is provided, use it as the project topicAskUserQuestion with options like "A web app feature", "A bug fix workflow", "A documentation project", or OtherCreate 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",
priority: "medium"
},
children: [
{ ref: "design", title: "Design <topic>", summary: "Define requirements and approach", priority: "high" },
{ ref: "implement", title: "Implement <topic>", summary: "Build the solution", priority: "high" },
{ ref: "test", title: "Test <topic>", summary: "Verify the implementation", 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 edgesBLOCKS dependency means: implement cannot start until design completes, test cannot start until implement completesref names ("design", "implement", "test") are local aliases used only within this callShow 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.
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:
queue → workcascadeEvents — the container likely cascaded from queue → work automatically (first child started)5b. Complete the design task:
advance_item(transitions=[{ itemId: "<design-UUID>", trigger: "complete" }])
Point out in the response:
work → terminalunblockedItems — implement should now be unblockedwork because siblings are still active5c. 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.
This is where the plan file and MCP complement each other most visibly. Explain:
get_context() or /work-summary to see exactly which items are in progress, which are blocked, and which are doneThis 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.
Briefly mention that MCP items can have required notes that act as documentation gates:
.taskorchestrator/config.yaml file defines note schemas — which notes must be filled before an item can advancefeature-implementation schema might require requirements and design notes before work can startadvance_item allows progressionguidance field — authoring hints that tell agents exactly what to write in each note./manage-schemas to set one up interactively, or /feature-implementation to see the full lifecycle in actionPresent this capabilities table:
| Want to... | Skill | What it does |
|---|---|---|
| Track a feature with documentation gates | /feature-implementation | Full lifecycle with required notes at each phase |
| Create items from conversation context | /create-item | Infers type, priority, and container placement |
| Build custom workflow schemas | /manage-schemas | Create, view, edit, delete, and validate note schemas |
| See project health dashboard | /work-summary | Active work, blockers, next actions at a glance |
| Advance an item through gates | /status-progression | Shows current role, gate status, correct trigger |
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)
For users with an existing populated workspace.
Run two calls in parallel:
get_context(includeAncestors=true)
query_items(operation="overview", includeChildren=true)
Present a condensed dashboard with these sections:
get_next_item(limit=3, includeDetails=true)Use status symbols: ◉ in-progress, ⊘ blocked, ○ pending, ✓ completed
For each section of the dashboard, add a brief annotation:
work or review role — these are things being worked on right nowget_context(itemId=...) to see which notes are missing, then manage_notes(upsert) to fill themIf 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.
Based on the dashboard, recommend one concrete action:
| Situation | Recommendation |
|---|---|
| Stalled items with missing notes | Fill the required notes — show the exact manage_notes call |
| Blocked items with satisfied deps | Advance with advance_item(trigger="start") |
| No active work, queue items exist | Start the highest-priority queue item |
| Empty workspace | Switch to the Fresh-Start path (Step 2) |
| Everything terminal | Suggest creating new work with /create-item |
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."