• 4 automatic hooks that fire on session start, plan mode entry, plan approval, and subagent launch
• 7 user-invocable skills as /task-orchestrator:* slash commands
• 3 internal skills that power the plan-mode pipeline
• The Agent-Owned-Phase Protocol injected into every subagent automatically

• Claude Code CLI installed
• Tier 1: Bare MCP setup complete

Two commands in Claude Code:

/plugin marketplace add https://github.com/jpicklyk/task-orchestrator
/plugin install task-orchestrator@task-orchestrator-marketplace

Verify with /plugin list — you should see task-orchestrator as enabled.

After editing plugin files, content is cached and the marketplace must be removed and re-added to pick up changes. For initial installation this is not required.

See Quick Start Step 4 for the full installation walkthrough.

Hooks fire automatically — no invocation needed after installation.

Event: SessionStart — every new Claude Code session.

What it injects: The 13-tool surface (manage_items, query_items, manage_notes, query_notes, manage_dependencies, query_dependencies, advance_item, get_next_item, get_blocked_items, get_next_status, create_work_tree, complete_tree, get_context), the role lifecycle (queue → work → review → terminal), and a session tip to call get_context() to see active and stalled items.

Effect: The agent knows the MCP tool names and workflow conventions from the first prompt, without any CLAUDE.md instructions.

Event: PreToolUse on EnterPlanMode — when Claude enters plan mode.

What it injects: An instruction to invoke the pre-plan-workflow internal skill.

Effect: Before writing a plan, the agent checks MCP state — existing items, note schemas, gate requirements. This sets a "definition floor" so the plan does not duplicate tracked work or ignore schema constraints.

Event: PostToolUse on ExitPlanMode — when the user approves a plan.

What it injects: An instruction to invoke the post-plan-workflow internal skill.

Effect: After plan approval, the agent materializes MCP items from the plan — creates work trees, wires dependencies, fills queue-phase notes — before implementation begins. Items exist in the MCP before any code is written.

Event: SubagentStart — any subagent launched via the Agent tool.

What it injects: The full Agent-Owned-Phase Protocol (see below).

Effect: Every subagent knows to call advance_item(trigger="start") to enter its phase, fill notes using the guidancePointer loop, commit changes, and return without calling complete. The orchestrator handles terminal transitions.

Skills are invoked as slash commands in any Claude Code session:

These are triggered by hooks and output styles, not invoked directly by users:

This is the core automation the plugin provides:

User describes a feature
 |
 v
Enter Plan Mode
 |
Pre-plan hook fires
 → agent calls pre-plan-workflow skill
 → checks existing MCP items, reads note schemas, confirms definition floor
 |
 v
Agent writes plan (with MCP awareness)
 |
User approves plan
 |
Post-plan hook fires
 → agent calls post-plan-workflow skill
 → create_work_tree for hierarchy
 → manage_dependencies for cross-item edges
 → manage_notes for queue-phase notes
 |
 v
Implementation begins
 (items exist, dependencies are set, gates are configured)

Without the pipeline, agents write plans that never get tracked. With it, every plan becomes a structured work tree with dependency ordering and schema-driven documentation requirements that survive across sessions.

When a subagent is dispatched via the Agent tool, the subagent-start hook injects this protocol automatically. Each subagent owns exactly one phase: it enters that phase, fills required notes, then returns without advancing further.

1. Enter the phase:

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

This moves the item into the subagent's phase (queue→work or work→review). The response includes guidancePointer (authoring instructions for the first required note) and noteProgress { filled, remaining, total }.

If the item is already in the target phase (applied: false in the response), call get_context(itemId="<item-UUID>") instead to get the guidance.

2. Read guidance:

guidancePointer is the schema author's instruction for the first unfilled required note. If it references a skill, load it via the Skill tool.

3. Do work and fill the note:

manage_notes(operation="upsert", notes=[{
 "itemId": "<uuid>",
 "key": "<note-key>",
 "role": "<phase>",
 "body": "<content>"
}])

If noteProgress.total is 1 (or absent), this was the only note — skip to step 6.

4. Get next guidance:

get_context(itemId="<item-UUID>")

Returns updated guidancePointer and noteProgress.

5. Check if done:

If guidancePointer is null, all required notes are filled. Proceed to step 6. Otherwise go back to step 2.

6. Return results:

Commit all changes with a descriptive message. Report: (1) files changed with line counts, (2) test results summary, (3) any blockers. The orchestrator handles the terminal transition.

• Each agent owns exactly one phase — do not advance beyond it
• Do NOT call advance_item(trigger="complete") — the orchestrator handles terminal transitions
• Commit before returning — the orchestrator needs committed changes to push and create a PR

This walkthrough shows the full pipeline from description to completion.

1. User: "Add rate limiting to the API."

2. Agent enters plan mode — the pre-plan hook fires. The agent calls pre-plan-workflow, checks for existing rate-limiting work, reads the feature-implementation schema requirements, and sets the definition floor.

3. Agent writes a plan — 4 subtasks: middleware design, Redis integration, error responses, tests. Plan is written with awareness of existing work and schema gates.

4. User approves — the post-plan hook fires. The agent calls post-plan-workflow and materializes:

create_work_tree(
 root={ "title": "Rate limiting", "tags": "feature-implementation", "priority": "high" },
 children=[
 { "ref": "middleware", "title": "Middleware design", "tags": "feature-task" },
 { "ref": "redis", "title": "Redis integration", "tags": "feature-task" },
 { "ref": "errors", "title": "Error responses", "tags": "feature-task" },
 { "ref": "tests", "title": "Integration tests", "tags": "feature-task" }
 ],
 deps=[
 { "from": "tests", "to": "middleware" },
 { "from": "tests", "to": "redis" }
 ]
)

Queue-phase notes (specification / task-scope) are filled before dispatching.

5. Agent dispatches implementation subagents — each subagent receives one child item UUID. The subagent-start hook injects the Agent-Owned-Phase Protocol automatically.

6. Each subagent:

• Calls advance_item(trigger="start") — queue→work
• Reads guidancePointer — fills implementation-notes and session-tracking notes
• Commits changes
• Returns to the orchestrator

7. Orchestrator advances each item — calls advance_item(trigger="start"). If newRole is review (schema has review-phase notes): dispatches a reviewer or fills review notes inline, then advances review→terminal. If newRole is terminal (no review phase): item is complete.

8. Parent auto-cascades — when all four children reach terminal, the root item cascades to terminal automatically. The cascadeEvents field in the response confirms the cascade.

The plugin works best when combined with note schemas (Tier 3). The pre-plan hook reads your config.yaml schemas to inform the definition floor. The subagent-start protocol uses guidancePointer from those schemas to tell agents exactly what to write.

See Note Schemas for schema setup.

Signal: You want Claude to operate as a full workflow orchestrator — planning, delegating, tracking, and reporting — rather than implementing directly.

Next: Output Styles — activate Workflow Analyst mode for delegation-based operation.