c-breakout-claude 1.0.0

package/skills/c-breakout.md

@@ -0,0 +1,1410 @@
+# C-Breakout: Distributed Task Execution
+
+Break down large tasks and distribute them across independent Claude Code instances, each with its own context budget.
+
+## Commands
+
+```
+/c-breakout summarize <file-pattern>    Summarize files using separate sub-agents
+/c-breakout distribute <task>           Break down and distribute a complex task
+/c-breakout orchestrate <project-goal>  Orchestrate project with specialized agents (RECOMMENDED)
+/c-breakout tasks                       Analyze todo list and farm out independent tasks
+/c-breakout status [run-id]             Check status of running sub-agents
+/c-breakout results [run-id]            Get results from a completed run
+/c-breakout resume <run-id>             Resume an interrupted run
+/c-breakout history                     Show run history for current project
+/c-breakout cancel [run-id]             Cancel running sub-agents
+```
+
+## Integration with TodoWrite (Auto-Detection)
+
+**CRITICAL: These steps apply automatically after EVERY TodoWrite operation throughout the session.**
+
+### After TodoWrite completes:
+
+1. **Silently analyze the current todo list:**
+   - Group tasks by likely file overlap
+   - Identify sequential dependencies (keywords: "after", "once", "then", "test for")
+   - Count truly independent groups (no file conflicts, no dependencies)
+
+2. **Check trigger conditions:**
+   ```
+   independent_groups = count of groups with no overlaps
+   context_percent = current context usage
+
+   if independent_groups >= 4:
+       → Inform with one-liner (don't ask)
+   elif independent_groups == 3:
+       → Ask user
+   elif context_percent > 60 AND independent_groups >= 3:
+       → Warn about context and suggest
+   else:
+       → Skip (no suggestion)
+   ```
+
+3. **Present suggestion inline:**
+   - Don't make it a separate message
+   - Add it after the TodoWrite confirmation
+   - Keep it brief (one-liner format for 4+ groups)
+
+**Example flow:**
+```
+User: Add these 5 tasks to the list
+Claude: [Uses TodoWrite to add tasks]
+Claude: "Todos updated. 💡 I can farm out 4 independent task groups to parallel agents, saving main session context. Run `/c-breakout tasks` when ready.
+
+For now, let me start with [task from main session group]..."
+```
+
+## Context-Aware Monitoring
+
+**Monitor context usage throughout the session and proactively suggest c-breakout when appropriate.**
+
+### When to check:
+- Before starting a large task (reading many files, implementing complex feature)
+- When context feels "heavy" (lots of conversation history, multiple file reads)
+- When user asks for something that will consume significant context
+
+### Context-based suggestions:
+
+**If context > 60% AND independent tasks exist:**
+```
+⚠️ Context at {X}%. I can offload {N} independent tasks to parallel agents, freeing up ~{Y}% of context. Run `/c-breakout tasks`?
+```
+
+**If context > 80%:**
+```
+⚠️ Context critically high at {X}%. Strong recommendation to use `/c-breakout tasks` to offload {N} tasks before continuing.
+```
+
+**When user requests batch file operations:**
+```
+User: "Read all files in src/components/"
+Claude: [Globs pattern, finds 15 files]
+Claude: "Found 15 files. 💡 I can summarize these in parallel using `/c-breakout summarize src/components/**/*.ts` to preserve context. Want to use c-breakout or read them directly?"
+```
+
+---
+
+## Auto-Breakout Guidelines
+
+**IMPORTANT: These guidelines apply automatically throughout the session, not just when user explicitly invokes /c-breakout.**
+
+### Automatic Detection Triggers
+
+**After every TodoWrite operation:**
+1. Analyze the updated todo list for independent task groups
+2. Count groups with no file overlap or sequential dependencies
+3. Apply auto-suggestion rules below
+
+**During session when context is high:**
+1. If context usage > 60% AND independent tasks exist → Suggest breakout
+2. If context usage > 80% → Strongly suggest breakout
+
+### Auto-Suggestion Rules
+
+#### Suggest with one-liner (don't ask, just inform):
+1. **4+ independent task groups** detected
+   - Format: "💡 I can farm out {N} independent task groups to parallel agents, saving main session context. Run `/c-breakout tasks` when ready."
+   - Then continue working on main session tasks
+
+2. **File summarization requested for 5+ files**
+   - Format: "💡 I can summarize these {N} files in parallel using `/c-breakout summarize {pattern}` to preserve context."
+   - Then ask: "Want me to use c-breakout or read them directly?"
+
+3. **User explicitly mentions "parallel", "distribute", or "breakout"**
+   - Automatically invoke `/c-breakout` with appropriate mode
+
+4. **Context usage > 60% AND 3+ independent tasks available**
+   - Format: "⚠️ Context at {X}%. I can offload {N} independent tasks to free up space. Run `/c-breakout tasks`?"
+
+#### Ask first (edge cases):
+1. **3 independent task groups** (borderline)
+   - Format: "I see 3 independent task groups. Want to use `/c-breakout tasks` to parallelize?"
+
+2. **Tasks might have subtle dependencies**
+   - Present analysis and ask for confirmation
+
+3. **First time suggesting breakout in this session**
+   - Add brief explanation: "C-breakout runs tasks in separate sessions, preserving our main context."
+
+#### Never auto-suggest:
+1. Tasks have sequential dependencies
+2. Single cohesive feature that shouldn't be split
+3. User is debugging/investigating (needs continuity)
+4. Less than 3 independent units of work
+5. User is in the middle of implementing something
+
+### Detailed Suggestion Format
+
+When suggesting (4+ groups or high context):
+```
+💡 C-Breakout Opportunity
+
+I can distribute {N} independent task groups to parallel agents:
+- Group 1: {task names} → ~{X} files
+- Group 2: {task names} → ~{Y} files
+- Group 3: {task names} → ~{Z} files
+
+Keeping in main session:
+- {dependent tasks}
+
+This frees up main context and speeds up completion. Run `/c-breakout tasks` when ready.
+```
+
+When asking (3 groups or edge cases):
+```
+I notice 3 independent task groups that could run in parallel. Want to use `/c-breakout tasks`?
+```
+
+---
+
+## Tracking & History
+
+### Directory Structure
+```
+/tmp/c-breakout/
+└── {RUN_ID}/
+    ├── state.json              # Full run state (for resume)
+    ├── pids.txt                # List of sub-agent PIDs
+    ├── agent_001.json          # Output from sub-agent 1
+    ├── agent_002.json          # Output from sub-agent 2
+    ├── combined_results.md     # All results combined
+    └── errors.log              # Error log for failures
+
+{PROJECT_DIR}/.claude/
+├── c-breakout-runs.md          # History of all runs for this project
+└── c-breakout-{RUN_ID}.md      # Results saved to project
+```
+
+### state.json format (enables resume)
+```json
+{
+  "run_id": "20260109_143022",
+  "status": "running|completed|failed|cancelled|interrupted",
+  "mode": "summarize|distribute|tasks",
+  "project_dir": "/path/to/project",
+  "started": "2026-01-09T14:30:22+08:00",
+  "completed": null,
+  "total_cost": 0.00,
+  "config": {
+    "max_concurrent": 3,
+    "max_retries": 2,
+    "batch_size": 5
+  },
+  "agents": [
+    {
+      "id": "001",
+      "type": "file|task",
+      "target": "src/api.ts",
+      "description": "Summarize API module",
+      "pid": 12345,
+      "status": "pending|running|completed|failed|retrying",
+      "retries": 0,
+      "output_file": "agent_001.json",
+      "error": null,
+      "started": null,
+      "completed": null,
+      "cost": 0.00
+    }
+  ],
+  "batches": [
+    {
+      "id": "batch_001",
+      "files": ["src/utils/a.ts", "src/utils/b.ts", "src/utils/c.ts"],
+      "agent_id": "001"
+    }
+  ]
+}
+```
+
+---
+
+## Mode: `summarize`
+
+**Purpose:** Read multiple files and create concise but comprehensive summaries, each in a separate sub-agent to preserve main session context.
+
+**Usage:**
+```
+/c-breakout summarize src/api/*.ts
+/c-breakout summarize src/models/ src/utils/
+/c-breakout summarize package.json tsconfig.json README.md
+```
+
+**Steps:**
+
+### 1. Resolve files and plan batching
+```bash
+# Expand patterns
+files=$(find {patterns} -type f)
+
+# Get file sizes for batching decisions
+for f in $files; do
+  wc -l "$f"
+done
+```
+
+**Batching rules:**
+- Files < 50 lines: batch up to 10 files per agent
+- Files 50-200 lines: batch up to 5 files per agent
+- Files 200-500 lines: batch up to 3 files per agent
+- Files > 500 lines: 1 file per agent
+
+### 2. Create run directory and state
+```bash
+RUN_ID=$(date +%Y%m%d_%H%M%S)
+mkdir -p /tmp/c-breakout/$RUN_ID
+```
+
+Initialize state.json with all agents in "pending" status.
+
+### 3. Show plan to user
+```
+## C-Breakout: Summarize Mode
+
+**Run ID:** {RUN_ID}
+**Files to summarize:** {total_count}
+**Batches:** {batch_count} (batching small files for efficiency)
+
+| Batch | Files | Est. Lines |
+|-------|-------|------------|
+| 001   | src/utils/a.ts, b.ts, c.ts | 120 |
+| 002   | src/api.ts | 450 |
+| 003   | src/models.ts | 380 |
+
+**Max concurrent agents:** 3
+**Estimated cost:** ~${estimate}
+
+Proceed? [Y/n]
+```
+
+### 4. Launch sub-agents with concurrency control
+
+Launch up to `max_concurrent` agents at a time. As each completes, launch the next pending one.
+
+**Sub-agent prompt for file summarization:**
+```
+You are a file analysis sub-agent. Create comprehensive yet concise summaries.
+
+## Files to Analyze
+{file_list_with_paths}
+
+## Instructions
+1. Read each file completely
+2. Create a structured summary capturing ALL important details
+
+## Summary Format (for each file)
+
+# {filename}
+
+## Purpose
+{1-2 sentence description}
+
+## Exports
+- {export}: {description}
+
+## Key Functions
+### {functionName}
+- Signature: `{signature}`
+- Purpose: {description}
+- Returns: {return_type}
+
+## Data Structures
+### {TypeName}
+{fields}
+
+## Dependencies
+- {import}: {usage}
+
+## Notes
+{important_details}
+
+---
+
+Be thorough - capture all public APIs, types, and significant implementation details.
+```
+
+**Launch command:**
+```bash
+claude -p "{prompt}" --model haiku --output-format json \
+  > /tmp/c-breakout/$RUN_ID/agent_{id}.json 2>&1 &
+echo $! >> /tmp/c-breakout/$RUN_ID/pids.txt
+```
+
+### 5. Monitor with progress streaming
+
+Poll every 5 seconds:
+```bash
+# Check which PIDs are still running
+for pid in $(cat pids.txt); do
+  if ps -p $pid > /dev/null 2>&1; then
+    echo "running"
+  else
+    echo "done"
+  fi
+done
+
+# Check output files for completion
+for f in agent_*.json; do
+  if [ -s "$f" ]; then
+    # Parse status from JSON
+    jq -r '.is_error // false' "$f"
+  fi
+done
+```
+
+**Progress display (update in place if possible):**
+```
+C-Breakout Progress: 3/7 agents complete (42%)
+[===========         ]
+- agent_001: completed ✓
+- agent_002: completed ✓
+- agent_003: completed ✓
+- agent_004: running...
+- agent_005: running...
+- agent_006: pending
+- agent_007: pending
+```
+
+### 6. Handle errors and retry
+
+When an agent fails:
+1. Log error to errors.log
+2. If retries < max_retries, increment and relaunch
+3. If max retries exceeded, mark as failed and continue
+
+```bash
+# Check for errors in output
+if jq -e '.is_error == true' agent_001.json > /dev/null; then
+  error_msg=$(jq -r '.error_message' agent_001.json)
+  echo "[$(date -Iseconds)] agent_001 failed: $error_msg" >> errors.log
+
+  # Update state for retry
+  # Relaunch if retries < max_retries
+fi
+```
+
+### 7. Collect and save results
+
+After all agents complete (or fail):
+```bash
+# Combine successful results
+for f in agent_*.json; do
+  if jq -e '.is_error != true' "$f" > /dev/null 2>&1; then
+    jq -r '.result' "$f"
+    echo -e "\n---\n"
+  fi
+done > combined_results.md
+
+# Calculate total cost
+total_cost=$(jq -s 'map(.total_cost_usd // 0) | add' agent_*.json)
+```
+
+### 8. Save to project and update history
+
+```bash
+# Save results to project
+cp combined_results.md "{PROJECT_DIR}/.claude/c-breakout-$RUN_ID.md"
+
+# Update history (prepend to c-breakout-runs.md)
+```
+
+### 9. Display final report
+```
+## C-Breakout Complete
+
+**Run ID:** {RUN_ID}
+**Mode:** Summarize
+**Status:** {completed|completed_with_errors}
+
+| Metric | Value |
+|--------|-------|
+| Files processed | {count} |
+| Successful | {success_count} |
+| Failed | {fail_count} |
+| Total cost | ${total_cost} |
+| Duration | {duration} |
+
+**Results saved to:**
+- {PROJECT_DIR}/.claude/c-breakout-{RUN_ID}.md
+
+{if errors}
+**Errors encountered:**
+- agent_003: {error_message}
+- agent_005: {error_message}
+{/if}
+```
+
+---
+
+## Mode: `tasks`
+
+**Purpose:** Analyze the current todo list, identify independent task groups, and farm them out to sub-agents while keeping dependent tasks in the main session.
+
+**Usage:**
+```
+/c-breakout tasks
+```
+
+**Steps:**
+
+### 1. Read current todo list
+
+Access the current todo list from the conversation context.
+
+### 2. Analyze task dependencies
+
+For each task, determine:
+1. **Files it will likely touch** (infer from task description)
+2. **Dependencies on other tasks** (must task X complete before task Y?)
+3. **Groupings** (related tasks that should stay together)
+
+**Dependency indicators:**
+- "after", "once", "when X is done" → sequential dependency
+- Same file modifications → should be same agent or sequential
+- "test for X", "verify X" → depends on X
+- Shared state/context requirements → same session
+
+### 3. Form independent groups
+
+```
+Analysis of 8 todo items:
+
+Group A (Main Session - has dependencies):
+  - Task 1: Add login endpoint
+  - Task 2: Add logout endpoint
+  - Task 3: Write auth tests (depends on 1,2)
+  Files: src/auth/*.ts, tests/auth.test.ts
+  Reason: Internal dependencies, should stay sequential
+
+Group B (Can distribute):
+  - Task 4: Refactor database models
+  Files: src/models/*.ts
+  Reason: Independent, no overlap
+
+Group C (Can distribute):
+  - Task 5: Add pagination to API
+  - Task 6: Add sorting to API
+  Files: src/api/list.ts, src/api/utils.ts
+  Reason: Related but independent of other groups
+
+Group D (Can distribute):
+  - Task 7: Update README
+  - Task 8: Add JSDoc comments to utils
+  Files: README.md, src/utils/*.ts
+  Reason: Documentation, independent
+```
+
+### 4. Present plan to user
+
+```
+## C-Breakout: Tasks Mode
+
+**Run ID:** {RUN_ID}
+**Todo items analyzed:** 8
+**Independent groups found:** 3 (can run in parallel)
+
+### Main Session (keeping these - have dependencies)
+- Task 1: Add login endpoint
+- Task 2: Add logout endpoint
+- Task 3: Write auth tests
+
+### Distributing to Sub-Agents
+
+| Group | Tasks | Files | Agent |
+|-------|-------|-------|-------|
+| B | Refactor database models | src/models/*.ts | 001 |
+| C | Add pagination, Add sorting | src/api/*.ts | 002 |
+| D | Update README, Add JSDoc | README.md, src/utils/*.ts | 003 |
+
+**Potential conflicts:** None detected
+**Estimated cost:** ~${estimate}
+
+Proceed? [Y/n]
+```
+
+### 5. Launch task agents
+
+**Sub-agent prompt for task execution:**
+```
+You are a task execution sub-agent working on a specific part of a larger project.
+
+## Working Directory
+{absolute_path}
+
+## Your Tasks
+{numbered_list_of_tasks}
+
+## Context
+{relevant_background_from_main_session}
+
+## Files You May Modify
+{list_of_files_for_this_group}
+
+## Files You Must NOT Modify (assigned to other agents)
+{files_for_other_groups}
+
+## Acceptance Criteria
+{specific_criteria_per_task}
+
+## Instructions
+1. Read any additional files needed for context
+2. Implement each task completely
+3. Verify your changes work (run relevant tests if applicable)
+4. Output a summary of what you changed per task
+
+Format your final output as:
+
+## Task: {task_name}
+**Status:** Complete|Partial|Failed
+**Files changed:**
+- {file}: {what_changed}
+**Notes:** {any_issues_or_decisions}
+
+---
+
+Begin now.
+```
+
+### 6. Update main session todo list
+
+After launching sub-agents:
+1. Mark distributed tasks as "distributed to c-breakout {RUN_ID}"
+2. Keep only main session tasks active
+3. Continue working on main session tasks
+
+### 7. Collect results and reconcile
+
+When sub-agents complete:
+1. Parse their outputs
+2. Update todo list with completion status
+3. Apply any file changes (verify no conflicts)
+4. Report results
+
+---
+
+## Mode: `distribute`
+
+**Purpose:** Break a complex task into independent sub-tasks, each executed by a separate sub-agent.
+
+**Usage:**
+```
+/c-breakout distribute Implement user authentication with login, logout, and session management
+/c-breakout distribute Refactor the API layer to use consistent error handling
+```
+
+**Steps:**
+
+### 1. Analyze the task
+- Read relevant files to understand scope
+- Identify natural decomposition points
+- Check for dependencies
+
+### 2. Decompose into sub-tasks
+
+Each sub-task must be:
+- **Self-contained:** Completable without other sub-tasks
+- **Independent:** Minimal file overlap with other sub-tasks
+- **Clear:** Specific files and acceptance criteria
+
+### 3. Present breakdown
+```
+## C-Breakout: Distribute Mode
+
+**Run ID:** {RUN_ID}
+**Original task:** {task}
+
+**Sub-tasks:**
+
+| # | Task | Files | Deliverable |
+|---|------|-------|-------------|
+| 1 | Create user model and migrations | src/models/user.ts, migrations/ | User schema |
+| 2 | Implement auth service | src/services/auth.ts | Login/logout logic |
+| 3 | Add auth API endpoints | src/api/auth.ts | REST endpoints |
+| 4 | Write auth tests | tests/auth.test.ts | Test coverage |
+
+**Dependencies:** Task 4 depends on 1-3 (will run after others complete)
+**Parallel tasks:** 1, 2, 3
+**Sequential tasks:** 4
+
+Proceed? [Y/n]
+```
+
+### 4. Execute with dependency awareness
+
+1. Launch independent tasks in parallel
+2. Wait for dependencies before launching dependent tasks
+3. Track progress and handle errors
+
+### 5. Collect and integrate results
+
+---
+
+## Mode: `orchestrate`
+
+**Purpose:** Intelligently orchestrate complex projects using specialized agents with minimal context overhead. The orchestrator analyzes the project, classifies tasks by type, and assigns specialized agents with only the tools they need.
+
+**Usage:**
+```
+/c-breakout orchestrate "Implement user authentication system"
+/c-breakout orchestrate "Refactor backend API and add comprehensive tests"
+/c-breakout orchestrate "Deploy application with CI/CD pipeline"
+```
+
+**Benefits:**
+- **43-50% token reduction** vs standard distribute mode
+- **Better reliability** - Agents only have access to tools they need
+- **Scalable** - Can handle 100+ tasks efficiently
+- **Cost optimized** - Uses Haiku for specialized agents, Sonnet for orchestrator
+
+**Architecture:**
+```
+ORCHESTRATOR (Sonnet, full context)
+    ├─→ PLANNER agents (Haiku, Read/Grep/WebSearch)
+    ├─→ DEV agents (Haiku, Read/Write/Edit/Bash)
+    └─→ DEPLOY agents (Haiku, Bash/Read)
+```
+
+---
+
+### Phase 1: Orchestrator Planning
+
+**Step 1: Create run directory and initialize**
+```bash
+RUN_ID=$(date +%Y%m%d_%H%M%S)
+mkdir -p /tmp/c-breakout/$RUN_ID
+```
+
+**Step 2: Launch orchestrator agent**
+
+The orchestrator is a full-context Sonnet agent that analyzes the project and creates an execution plan.
+
+**Orchestrator prompt:**
+```
+You are the C-Breakout Orchestrator Agent for distributed project execution.
+
+## Project Goal
+{project_goal}
+
+## Your Mission
+Analyze this project and create a detailed execution plan with specialized agents.
+
+## Steps
+
+### 1. Project Analysis
+- Read relevant project files to understand current state
+- Identify scope and requirements
+- List all files that will be involved
+
+### 2. Create Work Breakdown Structure (WBS)
+Break the project into discrete tasks. Each task should be:
+- Clear and actionable
+- Testable/verifiable
+- Estimated effort (S/M/L)
+
+### 3. Classify Tasks by Agent Type
+
+**PLANNER agents** (Research, exploration, analysis)
+- Tools: Read, Grep, Glob, WebSearch
+- Use for: Understanding codebase, research, architecture decisions
+- Examples: "Analyze current auth implementation", "Research best practices"
+
+**DEV agents** (Implementation, testing)
+- Tools: Read, Write, Edit, Bash
+- Use for: Writing code, implementing features, running tests
+- Examples: "Implement login endpoint", "Write unit tests"
+
+**DEPLOY agents** (Deployment, operations)
+- Tools: Bash, Read
+- Use for: Running commands, deployment scripts, CI/CD
+- Examples: "Deploy to staging", "Run migrations"
+
+### 4. Identify Dependencies
+Mark which tasks must complete before others can start.
+Use format: "Task X blocks Task Y"
+
+### 5. Generate Agent Prompts
+For each task, create a focused prompt that includes:
+- Task description
+- Relevant file paths
+- Acceptance criteria
+- Any context from project analysis
+
+### 6. Output Execution Plan
+
+Output a JSON plan in this exact format:
+
+{
+  "project_goal": "...",
+  "analysis_summary": "Brief summary of project state",
+  "agents": {
+    "planner": [
+      {
+        "id": "P001",
+        "task": "Task description",
+        "prompt": "Full prompt for agent",
+        "files": ["file1.ts", "file2.ts"],
+        "estimated_tokens": 5000,
+        "blocks": []
+      }
+    ],
+    "dev": [
+      {
+        "id": "D001",
+        "task": "Task description",
+        "prompt": "Full prompt for agent",
+        "files": ["file1.ts"],
+        "estimated_tokens": 8000,
+        "blocks": ["P001"]
+      }
+    ],
+    "deploy": [
+      {
+        "id": "DPL001",
+        "task": "Task description",
+        "prompt": "Full prompt for agent",
+        "files": [],
+        "estimated_tokens": 3000,
+        "blocks": ["D001", "D002"]
+      }
+    ]
+  },
+  "execution_order": [
+    ["P001", "P002"],  // Wave 1: parallel
+    ["D001", "D002", "D003"],  // Wave 2: parallel (after wave 1)
+    ["DPL001"]  // Wave 3: sequential (after wave 2)
+  ],
+  "estimated_cost": {
+    "orchestrator": 0.05,
+    "planner_agents": 0.10,
+    "dev_agents": 0.40,
+    "deploy_agents": 0.05,
+    "total": 0.60
+  }
+}
+
+## Critical Guidelines
+- Be thorough in project analysis - read key files
+- Create specific, actionable tasks
+- Classify agents correctly based on tools needed
+- Identify all dependencies to avoid conflicts
+- Keep agent prompts focused and clear
+
+Begin analysis now.
+```
+
+**Step 3: Execute orchestrator**
+```bash
+claude --model sonnet \
+  -p "$ORCHESTRATOR_PROMPT" \
+  --output-format json \
+  > /tmp/c-breakout/$RUN_ID/plan.json 2>&1
+```
+
+**Step 4: Parse and present plan to user**
+```bash
+python3 << 'EOF'
+import json
+
+with open(f'/tmp/c-breakout/{RUN_ID}/plan.json') as f:
+    data = json.load(f)
+    plan = json.loads(data['result'])
+
+print("## C-Breakout: Orchestrate Mode")
+print(f"\n**Run ID:** {RUN_ID}")
+print(f"**Project Goal:** {plan['project_goal']}")
+print(f"\n**Analysis:** {plan['analysis_summary']}")
+print("\n### Specialized Agents\n")
+print(f"| Type | Count | Tools | Est. Cost |")
+print(f"|------|-------|-------|-----------|")
+print(f"| Planner | {len(plan['agents']['planner'])} | Read, Grep, WebSearch | ${plan['estimated_cost']['planner_agents']:.2f} |")
+print(f"| Dev | {len(plan['agents']['dev'])} | Read, Write, Edit, Bash | ${plan['estimated_cost']['dev_agents']:.2f} |")
+print(f"| Deploy | {len(plan['agents']['deploy'])} | Bash, Read | ${plan['estimated_cost']['deploy_agents']:.2f} |")
+print(f"\n**Total Cost:** ${plan['estimated_cost']['total']:.2f}")
+print(f"**Orchestrator Cost:** ${plan['estimated_cost']['orchestrator']:.2f}")
+print(f"\n**Execution Waves:** {len(plan['execution_order'])}")
+
+# Show task breakdown
+print("\n### Tasks by Agent Type\n")
+for agent_type in ['planner', 'dev', 'deploy']:
+    if plan['agents'][agent_type]:
+        print(f"\n**{agent_type.upper()} AGENTS:**")
+        for agent in plan['agents'][agent_type]:
+            deps = f" (blocked by: {', '.join(agent['blocks'])})" if agent['blocks'] else ""
+            print(f"  • [{agent['id']}] {agent['task']}{deps}")
+
+print("\nProceed with execution? [Y/n]")
+EOF
+```
+
+---
+
+### Phase 2: Execute Specialized Agents
+
+**Step 1: Save plan to state**
+```bash
+# Save full plan to state.json
+python3 << EOF
+import json
+
+with open('/tmp/c-breakout/$RUN_ID/plan.json') as f:
+    plan_data = json.load(f)
+    plan = json.loads(plan_data['result'])
+
+# Create state.json with all agents
+state = {
+    "run_id": "$RUN_ID",
+    "status": "running",
+    "mode": "orchestrate",
+    "project_dir": "$(pwd)",
+    "started": "$(date -Iseconds)",
+    "completed": None,
+    "total_cost": 0.00,
+    "orchestrator_cost": plan_data['total_cost_usd'],
+    "config": {
+        "max_concurrent": 100,
+        "max_retries": 2
+    },
+    "plan": plan,
+    "agents": []
+}
+
+# Add all agents from plan
+for agent_type in ['planner', 'dev', 'deploy']:
+    for agent_spec in plan['agents'][agent_type]:
+        state['agents'].append({
+            "id": agent_spec['id'],
+            "type": agent_type,
+            "task": agent_spec['task'],
+            "prompt": agent_spec['prompt'],
+            "files": agent_spec['files'],
+            "blocks": agent_spec['blocks'],
+            "pid": None,
+            "status": "pending",
+            "retries": 0,
+            "output_file": f"agent_{agent_spec['id']}.json",
+            "error": None,
+            "started": None,
+            "completed": None,
+            "cost": 0.00
+        })
+
+with open('/tmp/c-breakout/$RUN_ID/state.json', 'w') as f:
+    json.dump(state, f, indent=2)
+
+print(f"State initialized with {len(state['agents'])} agents")
+EOF
+```
+
+**Step 2: Launch agents by wave**
+
+Execute agents in waves according to dependencies:
+
+```bash
+# Agent launch function with specialized tools
+launch_specialized_agent() {
+    local agent_id=$1
+    local agent_type=$2
+    local prompt=$3
+    local output_file=$4
+
+    # Determine tool allowlist based on agent type
+    case $agent_type in
+        planner)
+            tools="Read,Grep,Glob,WebSearch"
+            ;;
+        dev)
+            tools="Read,Write,Edit,Bash,Grep,Glob"
+            ;;
+        deploy)
+            tools="Bash,Read"
+            ;;
+    esac
+
+    # Launch with minimal context
+    echo "$prompt" | claude \
+        --model haiku \
+        --allowed-tools "$tools" \
+        --disable-slash-commands \
+        --no-session-persistence \
+        --output-format json \
+        --print \
+        > "$output_file" 2>&1 &
+
+    local pid=$!
+    echo "$pid" >> /tmp/c-breakout/$RUN_ID/pids.txt
+
+    # Update state with PID
+    python3 << PYEOF
+import json
+with open('/tmp/c-breakout/$RUN_ID/state.json', 'r+') as f:
+    state = json.load(f)
+    for agent in state['agents']:
+        if agent['id'] == '$agent_id':
+            agent['pid'] = $pid
+            agent['status'] = 'running'
+            agent['started'] = '$(date -Iseconds)'
+            break
+    f.seek(0)
+    json.dump(state, f, indent=2)
+    f.truncate()
+PYEOF
+}
+
+# Execute waves
+python3 << 'WAVEPY'
+import json
+import subprocess
+import time
+
+with open('/tmp/c-breakout/$RUN_ID/state.json') as f:
+    state = json.load(f)
+
+plan = state['plan']
+agents_by_id = {a['id']: a for a in state['agents']}
+
+print(f"Executing {len(plan['execution_order'])} waves...")
+
+for wave_num, wave in enumerate(plan['execution_order'], 1):
+    print(f"\n=== Wave {wave_num}/{len(plan['execution_order'])} ===")
+    print(f"Launching {len(wave)} agents in parallel...")
+
+    # Launch all agents in this wave
+    for agent_id in wave:
+        agent = agents_by_id[agent_id]
+        print(f"  • Launching [{agent_id}] {agent['task'][:50]}...")
+
+        subprocess.run([
+            'bash', '-c',
+            f"launch_specialized_agent '{agent_id}' '{agent['type']}' '{agent['prompt']}' '/tmp/c-breakout/$RUN_ID/agent_{agent_id}.json'"
+        ])
+
+    # Wait for wave to complete
+    print(f"Waiting for wave {wave_num} to complete...")
+    all_done = False
+    while not all_done:
+        time.sleep(5)
+        all_done = True
+        for agent_id in wave:
+            pid = agents_by_id[agent_id]['pid']
+            try:
+                subprocess.run(['ps', '-p', str(pid)], check=True, capture_output=True)
+                all_done = False
+            except:
+                pass
+
+    print(f"✓ Wave {wave_num} complete")
+
+print("\n✓ All waves complete!")
+WAVEPY
+```
+
+**Step 3: Monitor progress**
+
+Display real-time progress as agents complete:
+
+```bash
+# Progress monitor (runs in background)
+monitor_progress() {
+    while true; do
+        python3 << 'PY'
+import json
+import os
+
+with open('/tmp/c-breakout/$RUN_ID/state.json') as f:
+    state = json.load(f)
+
+total = len(state['agents'])
+completed = sum(1 for a in state['agents'] if a['status'] == 'completed')
+running = sum(1 for a in state['agents'] if a['status'] == 'running')
+failed = sum(1 for a in state['agents'] if a['status'] == 'failed')
+
+progress = (completed / total * 100) if total > 0 else 0
+
+print(f"\rProgress: {completed}/{total} ({progress:.0f}%) | Running: {running} | Failed: {failed}", end='', flush=True)
+PY
+        sleep 5
+
+        # Check if all done
+        if [ $(grep -c '"status": "completed"' /tmp/c-breakout/$RUN_ID/state.json) -eq $(jq '.agents | length' /tmp/c-breakout/$RUN_ID/state.json) ]; then
+            break
+        fi
+    done
+}
+```
+
+---
+
+### Phase 3: Aggregate Results
+
+**Step 1: Collect agent outputs**
+```bash
+python3 << 'EOF'
+import json
+import os
+
+run_dir = f'/tmp/c-breakout/{RUN_ID}'
+
+# Load state
+with open(f'{run_dir}/state.json') as f:
+    state = json.load(f)
+
+results = {
+    'planner': [],
+    'dev': [],
+    'deploy': []
+}
+
+total_cost = state['orchestrator_cost']
+
+# Collect results from each agent
+for agent in state['agents']:
+    output_file = f"{run_dir}/{agent['output_file']}"
+    if os.path.exists(output_file):
+        with open(output_file) as f:
+            output = json.load(f)
+            if not output.get('is_error'):
+                results[agent['type']].append({
+                    'id': agent['id'],
+                    'task': agent['task'],
+                    'result': output.get('result', ''),
+                    'cost': output.get('total_cost_usd', 0)
+                })
+                total_cost += output.get('total_cost_usd', 0)
+
+# Save aggregated results
+with open(f'{run_dir}/results.json', 'w') as f:
+    json.dump({
+        'project_goal': state['plan']['project_goal'],
+        'total_cost': total_cost,
+        'results_by_type': results
+    }, f, indent=2)
+
+print(f"Results aggregated. Total cost: ${total_cost:.2f}")
+EOF
+```
+
+**Step 2: Generate final report**
+```python
+## C-Breakout: Orchestrate Complete
+
+**Run ID:** {RUN_ID}
+**Project Goal:** {project_goal}
+
+### Results Summary
+
+| Agent Type | Completed | Failed | Cost |
+|------------|-----------|--------|------|
+| Planner | {planner_success}/{planner_total} | {planner_failed} | ${planner_cost:.2f} |
+| Dev | {dev_success}/{dev_total} | {dev_failed} | ${dev_cost:.2f} |
+| Deploy | {deploy_success}/{deploy_total} | {deploy_failed} | ${deploy_cost:.2f} |
+
+**Total Cost:** ${total_cost:.2f}
+**Token Savings vs Standard:** {savings_pct:.0f}%
+
+### Completed Tasks
+
+{list_of_completed_tasks}
+
+**Results saved to:**
+- {PROJECT_DIR}/.claude/c-breakout-{RUN_ID}.md
+- /tmp/c-breakout/{RUN_ID}/results.json
+```
+
+---
+
+### Error Handling for Orchestrate Mode
+
+**Orchestrator planning failure:**
+- Retry with more specific instructions
+- Fall back to standard distribute mode
+
+**Agent tool access errors:**
+- If agent requests blocked tool, log warning
+- Retry agent with expanded toolset if critical
+- Report misclassification to improve orchestrator
+
+**Dependency deadlock:**
+- Detect circular dependencies
+- Warn user and request manual intervention
+
+---
+
+### Configuration for Orchestrate Mode
+
+Add to default config:
+
+```json
+{
+  "orchestrate": {
+    "orchestrator_model": "sonnet",
+    "agent_model": "haiku",
+    "max_concurrent": 100,
+    "agent_types": {
+      "planner": {
+        "tools": ["Read", "Grep", "Glob", "WebSearch"],
+        "avg_overhead_tokens": 12000
+      },
+      "dev": {
+        "tools": ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
+        "avg_overhead_tokens": 10000
+      },
+      "deploy": {
+        "tools": ["Bash", "Read"],
+        "avg_overhead_tokens": 8000
+      }
+    }
+  }
+}
+```
+
+---
+
+## Mode: `status`
+
+**Purpose:** Check status of running sub-agents.
+
+**Usage:**
+```
+/c-breakout status           # Latest run
+/c-breakout status {RUN_ID}  # Specific run
+```
+
+**Steps:**
+
+1. Find run directory (latest or specified)
+2. Read state.json
+3. Check PID status for running agents
+4. Display formatted status
+
+**Output:**
+```
+## C-Breakout Status
+
+**Run ID:** 20260109_143022
+**Mode:** tasks
+**Started:** 2026-01-09 14:30:22 (5m 23s ago)
+**Status:** running
+
+| Agent | Target | Status | Retries | Duration |
+|-------|--------|--------|---------|----------|
+| 001 | Database models | completed ✓ | 0 | 2m 15s |
+| 002 | API pagination | running | 0 | 3m 02s |
+| 003 | Documentation | failed ✗ | 2 | - |
+
+**Progress:** 1/3 complete (33%)
+**Cost so far:** $0.45
+
+**Errors:**
+- agent_003: Rate limit exceeded (max retries reached)
+```
+
+---
+
+## Mode: `results`
+
+**Purpose:** Get results from a completed run.
+
+**Usage:**
+```
+/c-breakout results           # Latest run
+/c-breakout results {RUN_ID}  # Specific run
+```
+
+**Steps:**
+
+1. Read combined_results.md from run directory
+2. If not exists, aggregate from agent outputs
+3. Display formatted results
+4. Show cost summary
+
+---
+
+## Mode: `resume`
+
+**Purpose:** Resume an interrupted or failed run.
+
+**Usage:**
+```
+/c-breakout resume {RUN_ID}
+```
+
+**Steps:**
+
+1. Read state.json from run directory
+2. Identify incomplete agents (pending, running, failed with retries left)
+3. Show resume plan:
+   ```
+   ## C-Breakout Resume
+
+   **Run ID:** {RUN_ID}
+   **Original start:** {timestamp}
+   **Status when interrupted:** {status}
+
+   **Completed (will skip):**
+   - agent_001: Database models ✓
+   - agent_002: API pagination ✓
+
+   **Will resume:**
+   - agent_003: Documentation (was: failed, retries: 1/2)
+   - agent_004: Testing (was: pending)
+
+   Proceed? [Y/n]
+   ```
+4. Relaunch incomplete agents
+5. Continue normal monitoring
+
+---
+
+## Mode: `history`
+
+**Purpose:** Show run history for current project.
+
+**Usage:**
+```
+/c-breakout history
+```
+
+**Steps:**
+
+1. Read {PROJECT_DIR}/.claude/c-breakout-runs.md
+2. Display formatted history
+
+**Output:**
+```
+## C-Breakout History
+
+**Project:** claude-config
+
+| Run ID | Date | Mode | Status | Agents | Cost | Duration |
+|--------|------|------|--------|--------|------|----------|
+| 20260109_143022 | 2026-01-09 | tasks | completed | 3 | $0.89 | 8m 45s |
+| 20260108_091500 | 2026-01-08 | summarize | completed | 7 | $1.23 | 12m 30s |
+| 20260107_160000 | 2026-01-07 | distribute | failed | 4 | $0.45 | 5m 12s |
+
+**Total runs:** 3
+**Total cost:** $2.57
+
+View details: `/c-breakout results {RUN_ID}`
+```
+
+### History file format ({PROJECT_DIR}/.claude/c-breakout-runs.md)
+```markdown
+# C-Breakout Run History
+
+| Run ID | Date | Mode | Status | Agents | Cost | Duration | Summary |
+|--------|------|------|--------|--------|------|----------|---------|
+| 20260109_143022 | 2026-01-09 | tasks | completed | 3 | $0.89 | 8m 45s | Distributed todo tasks |
+| 20260108_091500 | 2026-01-08 | summarize | completed | 7 | $1.23 | 12m 30s | Summarized src/api/ |
+```
+
+---
+
+## Mode: `cancel`
+
+**Purpose:** Cancel running sub-agents.
+
+**Usage:**
+```
+/c-breakout cancel           # Latest run
+/c-breakout cancel {RUN_ID}  # Specific run
+```
+
+**Steps:**
+
+1. Read PIDs from run directory
+2. Kill all running processes
+3. Update state.json to "cancelled"
+4. Report what was cancelled
+
+---
+
+## Error Handling
+
+### Retry Logic
+- Max retries: 2 (configurable)
+- Retry on: timeout, rate limit, transient errors
+- No retry on: invalid prompt, permission denied, out of context
+
+### Error Aggregation
+All errors logged to `{RUN_DIR}/errors.log`:
+```
+[2026-01-09T14:35:22+08:00] agent_003 attempt 1: Rate limit exceeded
+[2026-01-09T14:36:22+08:00] agent_003 attempt 2: Rate limit exceeded
+[2026-01-09T14:37:22+08:00] agent_003 FAILED: Max retries exceeded
+```
+
+### Partial Success
+If some agents fail but others succeed:
+- Save successful results
+- Report failures clearly
+- Allow resume for failed agents
+
+---
+
+## Configuration
+
+Default config (can be overridden):
+```json
+{
+  "max_concurrent": 100,
+  "max_retries": 2,
+  "batch_small_files": true,
+  "small_file_threshold": 50,
+  "progress_interval": 5,
+  "model": "haiku",
+  "orchestrate": {
+    "orchestrator_model": "sonnet",
+    "agent_model": "haiku",
+    "agent_types": {
+      "planner": {
+        "tools": ["Read", "Grep", "Glob", "WebSearch"],
+        "avg_overhead_tokens": 12000
+      },
+      "dev": {
+        "tools": ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
+        "avg_overhead_tokens": 10000
+      },
+      "deploy": {
+        "tools": ["Bash", "Read"],
+        "avg_overhead_tokens": 8000
+      }
+    }
+  }
+}
+```
+
+**Model options:**
+- `haiku` (default) - Fastest and cheapest, ideal for most distributed tasks
+- `sonnet` - Use for orchestrator in orchestrate mode, or for complex task reasoning
+- `opus` - Use only for highly complex tasks requiring maximum capability
+
+**Orchestrate mode:**
+- Orchestrator uses `sonnet` for intelligent project planning
+- Specialized agents use `haiku` with minimal toolsets (43-50% token savings)
+- Agent types automatically classified: planner, dev, deploy
+
+---
+
+## Integration with Checkpoints
+
+When creating a checkpoint after using c-breakout, include:
+- Run IDs used during session
+- Summary of what was distributed
+- Link to results files
+
+Example in checkpoint:
+```markdown
+**C-Breakout runs:**
+- 20260109_143022 (tasks): Distributed 3 task groups, $0.89
+```
+
+---
+
+## Notes
+
+- Each sub-agent runs in a completely separate Claude Code session
+- Main session context only receives summaries/results, not full processing
+- Use `status` to monitor progress without consuming main session context
+- State files enable resume after interruption
+- History persists per-project for audit trail