Orchestration Tools Reference

┌─────────────────────────────────────────────────────────────┐
│  Your toolkit for turning ambitious requests into reality.  │
│  Master these tools, and complex work becomes effortless.   │
└─────────────────────────────────────────────────────────────┘

Table of Contents

1. AskUserQuestion (Most Important)
2. Agent Types
3. Task Tool
4. Subagent Prompting Guide
5. TaskOutput Tool
6. Hybrid Task Management
7. Agent-Task Workflow

---

AskUserQuestion

Your most important tool. When you need user input, ALWAYS use this tool. Never present text-only menus.

Why This Tool Matters

┌──────────────────────────────────────────────────┐
│  Text menu:          vs    AskUserQuestion:      │
│                                                  │
│  "Pick one:                 [Visual buttons]     │
│   1. Option A               [Rich descriptions]  │
│   2. Option B               [One click to pick]  │
│   3. Option C"              [Multiple questions] │
│                                                  │
│  Slow, error-prone          Fast, delightful     │
└──────────────────────────────────────────────────┘

The Maximal Philosophy

┌──────────────────────────────────────────────────┐
│                                                  │
│   GO MAXIMAL                                     │
│                                                  │
│   • 4 questions when gathering context           │
│   • 4 options per question                       │
│   • RICH descriptions (no length limit!)         │
│   • Creative options they haven't considered     │
│   • Cover every relevant dimension               │
│   • Be a consultant, not a waiter                │
│                                                  │
│   Descriptions can be full sentences,            │
│   explain trade-offs, give examples,             │
│   mention implications. GO DEEP.                 │
│                                                  │
│   Users don't know what they want until          │
│   they see the options. Surface dimensions       │
│   they haven't thought about.                    │
│                                                  │
└──────────────────────────────────────────────────┘

Golden Rules

| Rule | Why | | ------------------------------ | ------------------------------------------------------- | | 4 questions when unclear | Explore every dimension of the request | | 4 options per question | Comprehensive choices, including creative angles | | Recommended first | Guide users toward the best choice with "(Recommended)" | | Rich descriptions | Help users make informed decisions quickly | | multiSelect where relevant | Let them pick multiple when choices aren't exclusive | | Never text menus | Always use the tool. No exceptions. |

Comprehensive Example

AskUserQuestion(questions=[
    {
        "question": "What's the scope you're envisioning?",
        "header": "Scope",
        "options": [
            {"label": "Production-ready (Recommended)", "description": "Full implementation with tests, error handling, docs"},
            {"label": "Functional MVP", "description": "Core feature working, polish later"},
            {"label": "Prototype/spike", "description": "Explore feasibility, throwaway code OK"},
            {"label": "Just the design", "description": "Architecture and plan only, no code yet"}
        ],
        "multiSelect": False
    },
    {
        "question": "What matters most for this feature?",
        "header": "Priority",
        "options": [
            {"label": "User experience", "description": "Smooth, intuitive, delightful to use"},
            {"label": "Performance", "description": "Fast, efficient, scales well"},
            {"label": "Maintainability", "description": "Clean code, easy to extend later"},
            {"label": "Ship speed", "description": "Get it working ASAP, refine later"}
        ],
        "multiSelect": True
    },
    {
        "question": "Any technical constraints I should know?",
        "header": "Constraints",
        "options": [
            {"label": "Must match existing patterns", "description": "Follow conventions already in codebase"},
            {"label": "Specific tech/library required", "description": "You have preferences on tools to use"},
            {"label": "Backward compatibility", "description": "Can't break existing functionality"},
            {"label": "No constraints", "description": "Free to choose the best approach"}
        ],
        "multiSelect": True
    },
    {
        "question": "How should I handle edge cases?",
        "header": "Edge Cases",
        "options": [
            {"label": "Comprehensive (Recommended)", "description": "Handle all edge cases, defensive coding"},
            {"label": "Happy path focus", "description": "Main flow solid, edge cases basic"},
            {"label": "Fail fast", "description": "Throw errors early, let caller handle"},
            {"label": "Graceful degradation", "description": "Always return something usable"}
        ],
        "multiSelect": False
    }
])

---

Agent Types

┌─────────────────────────────────────────────────────────────┐
│  Choose the right agent for the job:                        │
│                                                             │
│  🔍 Explore      → Finding things, understanding codebase   │
│  📋 Plan         → Designing approaches, architecture       │
│  🔧 general-purpose → Building, implementing, executing     │
│  📚 claude-code-guide → Questions about Claude Code         │
└─────────────────────────────────────────────────────────────┘

| Agent Type | Best For | Strengths | | ------------------- | --------------------------------------------- | ------------------------------- | | Explore | Finding files, patterns, understanding code | Fast, focused, low-cost | | Plan | Architecture decisions, implementation design | Systematic analysis, trade-offs | | general-purpose | Implementation, complex multi-step work | Full tool access, autonomous | | claude-code-guide | Claude Code feature questions | Documentation expertise |

Quick Selection Guide

| User Says | Agent Type | | ----------------------------------- | ------------------- | | "Find X" / "Where is Y" | Explore | | "How should we implement X" | Plan | | "Build X" / "Fix Y" / "Implement Z" | general-purpose | | "Can Claude Code do X" | claude-code-guide |

---

Task Tool

Spawn an agent to handle work. This is how you delegate.

Remember: Subagents do NOT inherit skills. They only know what you tell them in the prompt. You are the conductor — they are the musicians.

Parameters

| Parameter | Required | Description | | ------------------- | -------- | ---------------------------------------------- | | subagent_type | Yes | Agent type to spawn | | prompt | Yes | Detailed instructions for the agent | | description | Yes | Short 3-5 word summary | | run_in_background | Yes | ALWAYS set to True for async orchestration | | model | No | Override model (haiku, sonnet, opus) |

Background Agents: The Default

ALWAYS use run_in_background=True. This is the foundation of powerful orchestration.

# Correct: Background agents (ALWAYS) with explicit model
Task(subagent_type="Explore", prompt="...", model="haiku", run_in_background=True)
Task(subagent_type="general-purpose", prompt="...", model="sonnet", run_in_background=True)

Model Selection

| Task Type | Model | Why | | -------------------------------- | -------- | ---------------------------------------- | | Fetch files, grep, find things | haiku | Errand runner - spawn many in parallel | | Gather info for synthesis | haiku | No judgment needed, just retrieval | | Well-structured implementation | sonnet | Capable worker - needs clear direction | | Research, reading docs | sonnet | Can follow patterns and instructions | | Security review | opus | Critical thinking, trust its judgment | | Architecture/design decisions | opus | Ambiguous, needs creative problem-solving| | Complex debugging | opus | Reasoning across systems |

---

Subagent Prompting Guide

Your agents are only as good as your prompts. Invest in clear instructions.

The WORKER Preamble (Required)

Every agent prompt MUST start with this preamble:

CONTEXT: You are a WORKER agent, not an orchestrator.

RULES:
- Complete ONLY the task described below
- Use tools directly (Read, Write, Edit, Bash, etc.)
- Do NOT spawn sub-agents
- Do NOT manage tasks
- Report your results with absolute file paths

TASK:
[Your specific task here]

This prevents agents from recursively trying to orchestrate.

The Five Elements

After the preamble, include:

┌─────────────────────────────────────────────────────────────┐
│  1. PREAMBLE   → WORKER context and rules (required!)       │
│  2. CONTEXT    → What's the bigger picture?                 │
│  3. SCOPE      → What exactly should this agent do?         │
│  4. CONSTRAINTS → What rules or patterns to follow?         │
│  5. OUTPUT     → What should the agent return?              │
└─────────────────────────────────────────────────────────────┘

Example: Implementation Prompt

CONTEXT: You are a WORKER agent, not an orchestrator.

RULES:
- Complete ONLY the task described below
- Use tools directly (Read, Write, Edit, Bash, etc.)
- Do NOT spawn sub-agents
- Do NOT manage tasks
- Report your results with absolute file paths

TASK:
Create server/src/routes/auth.js with:
- POST /signup - Create user, hash password with bcrypt, return JWT
- POST /login - Verify credentials, return JWT

CONTEXT: Building a Todo app with Express backend and SQLite.
The users table exists in server/src/db/database.js.

CONSTRAINTS:
- Use the existing db from database.js
- JWT secret from process.env.JWT_SECRET
- Follow existing code patterns

RETURN: Confirm files created and summarize implementation.

---

TaskOutput Tool

Retrieve results from background agents.

# Wait for completion
result = TaskOutput(task_id="abc123")

# Check without waiting
result = TaskOutput(task_id="abc123", block=False)

# Wait with timeout
result = TaskOutput(task_id="abc123", timeout=60000)

---

Hybrid Task Management

This orchestration skill uses a two-layer task management approach:

Layer 1: cc-mirror tasks (Strategic)

Persistent task management with dependency tracking. Use via Bash.

# CREATE tasks
npx cc-mirror tasks create --subject "Setup database schema" --description "Create user tables, indexes"
npx cc-mirror tasks create --subject "Implement auth routes" --description "Login, logout, register"
npx cc-mirror tasks create --subject "Build auth middleware" --description "JWT verification"

# SET DEPENDENCIES
npx cc-mirror tasks update 2 --add-blocked-by 1
npx cc-mirror tasks update 3 --add-blocked-by 2

# LIST tasks
npx cc-mirror tasks                    # Open tasks
npx cc-mirror tasks --status all       # All tasks
npx cc-mirror tasks --blocked          # Blocked only

# VIEW dependency graph
npx cc-mirror tasks graph

# MARK COMPLETE
npx cc-mirror tasks update 1 --status resolved

# ADD PROGRESS NOTE
npx cc-mirror tasks update 1 --add-comment "Schema design complete"

# CLEANUP
npx cc-mirror tasks archive --resolved

Layer 2: TodoWrite (Tactical)

Real-time session visibility. Users see this in their UI.

TodoWrite([
    {"content": "Design auth architecture", "status": "in_progress", "activeForm": "Designing auth architecture"},
    {"content": "Implement user model", "status": "pending", "activeForm": "Implementing user model"},
    {"content": "Build auth routes", "status": "pending", "activeForm": "Building auth routes"}
])

Why Two Layers?

| Layer | Purpose | Persistence | Dependencies | User Visibility | |-------|---------|-------------|--------------|-----------------| | cc-mirror tasks | Strategic planning | Cross-session | Yes | Via CLI | | TodoWrite | Real-time tracking | Session only | No | In UI |

Use both: cc-mirror tasks for the graph, TodoWrite for live feedback.

---

Agent-Task Workflow

The complete flow for orchestrated execution:

┌─────────────────────────────────────────────────────────────┐
│  1. DECOMPOSE                                               │
│     cc-mirror tasks create → create → create                │
│     TodoWrite for session visibility                        │
│                                                             │
│  2. SET DEPENDENCIES                                        │
│     cc-mirror tasks update --add-blocked-by                 │
│                                                             │
│  3. FIND READY WORK                                         │
│     cc-mirror tasks → find tasks with no blockers           │
│                                                             │
│  4. SPAWN BACKGROUND AGENTS                                 │
│     Task(..., run_in_background=True) ← ALWAYS background   │
│                                                             │
│  5. CONTINUE OR YIELD                                       │
│     More work? Continue. Otherwise update user, yield.      │
│                                                             │
│  6. PROCESS NOTIFICATIONS                                   │
│     <agent-notification> arrives → Read results             │
│     cc-mirror tasks update --status resolved                │
│     TodoWrite to update session                             │
│                                                             │
│  7. REPEAT                                                  │
│     Back to step 3 until all done                           │
└─────────────────────────────────────────────────────────────┘

Example Flow

# 1. Decompose
npx cc-mirror tasks create --subject "Setup database schema" --description "..."
npx cc-mirror tasks create --subject "Implement auth routes" --description "..."
npx cc-mirror tasks create --subject "Build auth middleware" --description "..."

# 2. Dependencies
npx cc-mirror tasks update 2 --add-blocked-by 1
npx cc-mirror tasks update 3 --add-blocked-by 2

# 3. Track in session
TodoWrite([
    {"content": "Setup database schema", "status": "in_progress", "activeForm": "Setting up database"},
    {"content": "Implement auth routes", "status": "pending", "activeForm": "Implementing auth routes"},
    {"content": "Build auth middleware", "status": "pending", "activeForm": "Building auth middleware"}
])

# 4. Spawn background agent (ALWAYS background, explicit model)
Task(subagent_type="general-purpose",
     description="Setup database",
     prompt="Create SQLite database with users table...",
     model="sonnet",
     run_in_background=True)

# 5. Update user and yield (or continue other work)
"Setting up the database schema..."
─── ◈ Orchestrating ── Database Setup ──

# 6. Notification arrives, read results, mark complete

npx cc-mirror tasks update 1 --status resolved

# Update TodoWrite
TodoWrite([
    {"content": "Setup database schema", "status": "completed", "activeForm": "Setting up database"},
    {"content": "Implement auth routes", "status": "in_progress", "activeForm": "Implementing auth routes"},
    {"content": "Build auth middleware", "status": "pending", "activeForm": "Building auth middleware"}
])

# 7. Repeat - task 2 now unblocked, launch next agent...

---

Best Practices Summary

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  ✓ ALWAYS use run_in_background=True for agents             │
│  ✓ Always use AskUserQuestion for user input                │
│  ✓ Decompose before spawning agents                         │
│  ✓ Set dependencies explicitly with cc-mirror tasks         │
│  ✓ Use TodoWrite for real-time user visibility              │
│  ✓ Launch multiple background agents in single message      │
│  ✓ Rich, detailed prompts for agents                        │
│  ✓ Process notifications as they arrive                     │
│  ✓ Mark tasks resolved immediately when done                │
│  ✓ Show active work in signature                            │
│                                                             │
│  ✗ Never use foreground (blocking) agents                   │
│  ✗ Never use text menus for choices                         │
│  ✗ Never run independent work sequentially                  │
│  ✗ Never give vague prompts to agents                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

─── ◈ Tools Reference Complete ──────────────────