# 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)](#askuserquestion)
2. [Agent Types](#agent-types)
3. [Task Tool](#task-tool)
4. [Subagent Prompting Guide](#subagent-prompting-guide)
5. [TaskOutput Tool](#taskoutput-tool)
6. [Hybrid Task Management](#hybrid-task-management)
7. [Agent-Task Workflow](#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

```python
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.

```python
# 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.

```python
# 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.

```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.

```python
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

```bash
# 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
```

```python
# 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
```

```bash
npx cc-mirror tasks update 1 --status resolved
```

```python
# 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 ──────────────────
```