---
description: "Break down an active plan into CodeRabbit-style microtasks in Commander using deep codebase analysis, then coordinate parallel agent execution"
argument-hint: "[plan description or horizon plan ID]"
allowed-tools: ["Task", "mcp__commander__commander_task", "mcp__commander__commander_task_lifecycle", "mcp__commander__commander_task_group", "mcp__commander__commander_session", "mcp__commander__commander_comment", "mcp__commander__commander_log", "AskUserQuestion"]
---

# Commander Plan - Multi-Agent Task Orchestration

**⚠️ CRITICAL RULE: NO AD-HOC TASKS — ALL tasks MUST be created inside a task group using `commander_task_group(operation="create")`. NEVER use `commander_task(operation="create")` for standalone tasks. Even single tasks must belong to a group for proper Initiative Progress UI tracking and wave management.**

This command breaks down a plan into microtasks using a **planning agent architecture**, creates them in Commander MCP, and coordinates parallel agent execution.

## Planning Agent Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                         MAIN AGENT                                  │
│                    (Orchestrator Only)                              │
└─────────────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    │   Phase 1: Parse   │
                    │   & Delegate       │
                    └─────────┬─────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│ SCOUT AGENT 1 │   │ SCOUT AGENT 2 │   │ SCOUT AGENT 3 │
│  Architecture │   │   Security    │   │   Quality     │
│   Analysis    │   │   Analysis    │   │   Analysis    │
└───────┬───────┘   └───────┬───────┘   └───────┬───────┘
        │                   │                   │
        └─────────────────┬─┴───────────────────┘
                          │
                          ▼
              ┌─────────────────────┐
              │    PLANNER AGENT       │
              │  (Planning Agent)   │
              │   Synthesize &      │
              │   Create Plan       │
              └─────────┬───────────┘
                        │
                        ▼
              ┌─────────────────────┐
              │    MAIN AGENT       │
              │  Present Plan to    │
              │  User for Approval  │
              └─────────────────────┘
```

**Key Principle: The main agent does NO context gathering itself.**

- **scout Subagents** - Fast, parallel context gathering (cheap, efficient)
- **planner Subagent** - Deep reasoning for plan synthesis (smart, thorough)
- **Main Agent** - Orchestration and user presentation only

---

## Input

Plan or feature to implement: **$ARGUMENTS**

---

## Workflow

### Phase 1: Parse & Delegate (Main Agent)

**The main agent ONLY parses input and delegates - it does NOT read files or gather context.**

1. **Extract Plan Intent**
   - If $ARGUMENTS references a Horizon plan, note the plan ID
   - If $ARGUMENTS is a description, parse the goal
   - Identify keywords that suggest scope (files, features, areas)

2. **Determine Analysis Dimensions**
   Based on the plan description, identify which analyses are needed:
   - **Architecture** - Always needed
   - **Security** - If auth, validation, data handling mentioned
   - **Quality** - If refactor, cleanup, improve mentioned
   - **Testing** - If test, coverage, spec mentioned
   - **Performance** - If optimize, speed, cache mentioned
   - **API** - If endpoint, route, API mentioned

3. **Spawn scout Agents in Parallel**
   Launch 3-5 scout subagents simultaneously for context gathering.

### Phase 2: Parallel Context Gathering (scout Subagents)

**Spawn multiple scout agents IN PARALLEL using the Task tool.**

Each agent receives a focused exploration task and returns structured findings.

**CRITICAL: Launch ALL scout agents in a SINGLE message with multiple Task tool calls.**

#### Agent 1: Architecture Explorer

```
Use the Task tool with:
- subagent_type: "Explore"
- model: "scout"
- prompt: |
    ## Architecture Analysis for: [PLAN_DESCRIPTION]

    **You Are Part of a Team**
    You work independently, but other scout agents may be exploring in parallel.
    Quick glance — check your inbox for context from other agents:
    `mcp__commander__commander_mailbox(operation="inbox", agent_name="scout")`
    If relevant findings already exist, incorporate them rather than redoing the work.
    If you discover something broadly useful, share it:
    `mcp__commander__commander_mailbox(operation="send", from_agent="scout", to_agent="@all", body="Found: [discovery]", message_type="status")`

    **Your Mission:** Explore the codebase architecture relevant to this feature.

    **Exploration Tasks:**
    1. Find the main entry points and module structure
    2. Identify relevant files that will need modification
    3. Map dependencies and imports between modules
    4. Document existing patterns (naming, structure, conventions)
    5. Find similar implementations to use as reference

    **Search Strategy:**
    - Glob for structure: `src/**/*.ts`, `lib/**/*.ts`
    - Grep for imports: `import.*from`, `require\(`
    - Read key files: entry points, configs, types

    **MANDATORY: Comment During Every Step**

    You MUST use Commander MCP to log progress at EVERY step:

    ```
    mcp__commander__commander_log(
      task_id=0,
      message="[PREFIX]: [details]",
      agent_name="scout"
    )
    ```

    **Required Prefixes (use for EACH operation):**
    - `ANALYZING:` Before reading any file
    - `FOUND:` After discovering relevant code
    - `DECISION:` When making analysis choices
    - `INSIGHT:` For patterns or learnings
    - `COMPLETE:` Summary at end of analysis

    **This is mandatory. Do not skip comments.**

    **Return Format (JSON):**
    ```json
    {
      "relevant_files": [
        {"path": "...", "purpose": "...", "lines_of_interest": "..."}
      ],
      "patterns_found": [
        {"pattern": "...", "example_file": "...", "description": "..."}
      ],
      "dependencies": [
        {"from": "...", "to": "...", "type": "..."}
      ],
      "reference_implementations": [
        {"file": "...", "relevance": "..."}
      ],
      "key_insights": ["...", "..."]
    }
    ```
```

#### Agent 2: Security Analyzer (if needed)

```
Use the Task tool with:
- subagent_type: "Explore"
- model: "scout"
- prompt: |
    ## Security Analysis for: [PLAN_DESCRIPTION]

    **Your Mission:** Identify security-relevant code and patterns.

    **Exploration Tasks:**
    1. Find authentication/authorization code
    2. Identify input validation patterns
    3. Look for data sanitization
    4. Find sensitive data handling
    5. Check for security vulnerabilities

    **Search Strategy:**
    - Glob: `**/*auth*`, `**/*valid*`, `**/*secur*`, `**/*sanitiz*`
    - Grep: `password`, `token`, `secret`, `api.?key`, `credential`
    - Read auth middleware, validation utilities

    **MANDATORY: Comment During Every Step**

    You MUST use Commander MCP to log progress at EVERY step:

    ```
    mcp__commander__commander_log(
      task_id=0,
      message="[PREFIX]: [details]",
      agent_name="scout"
    )
    ```

    **Required Prefixes (use for EACH operation):**
    - `ANALYZING:` Before reading any file
    - `FOUND:` After discovering security patterns
    - `DECISION:` When making analysis choices
    - `INSIGHT:` For security patterns or concerns
    - `COMPLETE:` Summary at end of analysis

    **This is mandatory. Do not skip comments.**

    **Return Format (JSON):**
    ```json
    {
      "auth_patterns": [
        {"file": "...", "mechanism": "...", "notes": "..."}
      ],
      "validation_patterns": [
        {"file": "...", "what": "...", "how": "..."}
      ],
      "security_concerns": [
        {"file": "...", "line": "...", "issue": "...", "severity": "..."}
      ],
      "recommendations": ["...", "..."]
    }
    ```
```

#### Agent 3: Quality Analyzer (if needed)

```
Use the Task tool with:
- subagent_type: "Explore"
- model: "scout"
- prompt: |
    ## Code Quality Analysis for: [PLAN_DESCRIPTION]

    **Your Mission:** Assess code quality and identify improvement opportunities.

    **Exploration Tasks:**
    1. Find code duplication
    2. Identify complex functions (>50 lines)
    3. Look for code smells
    4. Check for consistent patterns
    5. Find technical debt markers (TODO, FIXME, HACK)

    **Search Strategy:**
    - Grep: `TODO`, `FIXME`, `HACK`, `XXX`
    - Analyze function lengths
    - Look for duplicate patterns

    **MANDATORY: Comment During Every Step**

    You MUST use Commander MCP to log progress at EVERY step:

    ```
    mcp__commander__commander_log(
      task_id=0,
      message="[PREFIX]: [details]",
      agent_name="scout"
    )
    ```

    **Required Prefixes (use for EACH operation):**
    - `ANALYZING:` Before reading any file
    - `FOUND:` After discovering code smells or debt
    - `DECISION:` When making analysis choices
    - `INSIGHT:` For quality patterns or refactoring opportunities
    - `COMPLETE:` Summary at end of analysis

    **This is mandatory. Do not skip comments.**

    **Return Format (JSON):**
    ```json
    {
      "duplications": [
        {"files": ["...", "..."], "pattern": "...", "suggestion": "..."}
      ],
      "complex_functions": [
        {"file": "...", "function": "...", "lines": "...", "complexity": "..."}
      ],
      "tech_debt": [
        {"file": "...", "line": "...", "marker": "...", "context": "..."}
      ],
      "refactoring_opportunities": ["...", "..."]
    }
    ```
```

#### Agent 4: Test Coverage Analyzer (if needed)

```
Use the Task tool with:
- subagent_type: "Explore"
- model: "scout"
- prompt: |
    ## Test Coverage Analysis for: [PLAN_DESCRIPTION]

    **Your Mission:** Map test coverage and identify gaps.

    **Exploration Tasks:**
    1. Find all test files
    2. Map tests to source files
    3. Identify untested functions
    4. Check test patterns and frameworks
    5. Find integration vs unit test split

    **Search Strategy:**
    - Glob: `**/*.test.ts`, `**/*.spec.ts`, `**/__tests__/*`
    - Grep: `describe\(`, `it\(`, `test\(`
    - Read test configs: jest.config, vitest.config

    **MANDATORY: Comment During Every Step**

    You MUST use Commander MCP to log progress at EVERY step:

    ```
    mcp__commander__commander_log(
      task_id=0,
      message="[PREFIX]: [details]",
      agent_name="scout"
    )
    ```

    **Required Prefixes (use for EACH operation):**
    - `ANALYZING:` Before reading any file
    - `FOUND:` After discovering test coverage info
    - `DECISION:` When making analysis choices
    - `INSIGHT:` For test patterns or coverage gaps
    - `COMPLETE:` Summary at end of analysis

    **This is mandatory. Do not skip comments.**

    **Return Format (JSON):**
    ```json
    {
      "test_files": [
        {"path": "...", "tests_for": "...", "count": "..."}
      ],
      "coverage_gaps": [
        {"source_file": "...", "untested_functions": ["..."]}
      ],
      "test_patterns": {
        "framework": "...",
        "conventions": ["..."]
      },
      "recommendations": ["...", "..."]
    }
    ```
```

#### Agent 5: API/Integration Analyzer (if needed)

```
Use the Task tool with:
- subagent_type: "Explore"
- model: "scout"
- prompt: |
    ## API/Integration Analysis for: [PLAN_DESCRIPTION]

    **Your Mission:** Map API structure and integration points.

    **Exploration Tasks:**
    1. Find all API routes/endpoints
    2. Identify request/response patterns
    3. Map external service integrations
    4. Document API conventions
    5. Find API documentation

    **Search Strategy:**
    - Glob: `**/routes/*`, `**/api/*`, `**/controllers/*`
    - Grep: `router\.`, `app\.(get|post|put|delete)`, `fetch\(`
    - Read API handlers and middleware

    **MANDATORY: Comment During Every Step**

    You MUST use Commander MCP to log progress at EVERY step:

    ```
    mcp__commander__commander_log(
      task_id=0,
      message="[PREFIX]: [details]",
      agent_name="scout"
    )
    ```

    **Required Prefixes (use for EACH operation):**
    - `ANALYZING:` Before reading any file
    - `FOUND:` After discovering API endpoints or integrations
    - `DECISION:` When making analysis choices
    - `INSIGHT:` For API patterns or integration points
    - `COMPLETE:` Summary at end of analysis

    **This is mandatory. Do not skip comments.**

    **Return Format (JSON):**
    ```json
    {
      "endpoints": [
        {"path": "...", "method": "...", "handler": "...", "file": "..."}
      ],
      "integrations": [
        {"service": "...", "usage": "...", "file": "..."}
      ],
      "api_patterns": {
        "auth": "...",
        "error_handling": "...",
        "response_format": "..."
      },
      "documentation": ["...", "..."]
    }
    ```
```

### Phase 3: Planning Agent (planner Subagent)

**After ALL scout agents return, spawn a single planner agent to synthesize findings into a plan.**

```
Use the Task tool with:
- subagent_type: "Plan"
- model: "planner"
- prompt: |
    ## Create Implementation Plan for: [PLAN_DESCRIPTION]

    **Context from Parallel Analysis:**

    ### Architecture Findings:
    [INSERT ARCHITECTURE AGENT RESULTS]

    ### Security Findings:
    [INSERT SECURITY AGENT RESULTS - if applicable]

    ### Quality Findings:
    [INSERT QUALITY AGENT RESULTS - if applicable]

    ### Test Coverage Findings:
    [INSERT TEST AGENT RESULTS - if applicable]

    ### API Findings:
    [INSERT API AGENT RESULTS - if applicable]

    ---

    **Your Mission:** Synthesize all findings into a comprehensive implementation plan.

    **Planning Tasks:**

    1. **Analyze Dependencies**
       - Which changes depend on others?
       - What must be done first (foundation)?
       - What can be parallelized?

    2. **Create CodeRabbit-Style Microtasks**
       For each task, use this format:

       ```
       In {file} around lines {start} to {end}, {problem} is {diagnosis};
       {solution} by {implementation_details} with {fallback} and {error_handling}.
       ```

       Include:
       - Specific file and line numbers
       - Clear problem statement
       - Actionable solution
       - Implementation details
       - Error handling considerations

    3. **Organize into Waves**
       - Wave 1: Foundation/independent tasks
       - Wave 2: Tasks depending on Wave 1
       - Wave 3: Final integration/testing

    4. **Assign Work Types**
       Classify each task:
       - backend, frontend, testing, documentation, devops, refactoring

    5. **Set Priorities**
       1-10 scale (1=highest) based on:
       - Wave number
       - Severity (security > bugs > features)
       - Blocking status

    6. **Synthesize Scout Findings into Context** ⚠️ CRITICAL

       For EACH microtask, you MUST populate the full context object by synthesizing the scout agent findings:

       **context.source**: Always "commander-plan"

       **context.original_prompt**: The user's original $ARGUMENTS (cleaned up and concise)

       **context.wave**: The wave number (1, 2, or 3)

       **context.work_type**: Classify the task (backend, frontend, testing, documentation, devops, refactoring)

       **context.file**: Primary file path this task modifies

       **context.lines**: Line range to modify (e.g., "45-52")

       **context.severity**: HIGH/MEDIUM/LOW based on impact and risk

       **context.assigned_agent**: "reviewer" for complex tasks, "builder" for simple ones

       **context.backup_agent**: Fallback agent if primary fails

       **context.file_scope**: ⚠️ CRITICAL: file_scope is REQUIRED for policy generation
       - **allowed**: Array of files/directories this task CAN modify (from Architecture Explorer analysis)
         - **MUST contain at least one file path** - empty arrays will result in fallback policy (less restrictive)
         - Extract from Architecture Explorer findings: files that need modification
         - Include related files: imports, dependencies, test files
       - **forbidden**: Array of files/directories this task must NOT touch (core files, unrelated modules)
       
       **⚠️ VALIDATION CHECKLIST** - Before creating tasks, verify:
       1. Each microtask has `context.file_scope`
       2. `context.file_scope.allowed` is a non-empty array
       3. At least one allowed path is a specific file or directory relevant to the task
       4. If validation fails, STOP and report error - DO NOT create tasks without proper file_scope

       **context.implementation_guide**: Your detailed step-by-step guide for this specific task

       **context.analysis_context** ← THIS IS WHERE YOU SYNTHESIZE ALL SCOUT FINDINGS:
       - **architecture**: Extract relevant architecture findings from Architecture Explorer
         - Relevant file paths and their purposes
         - Module structure and organization
         - Import/export patterns
         Example: "This task modifies the auth middleware which is called by all protected routes. Dependencies: jwt library, user model."

       - **patterns**: Extract coding patterns and conventions from Architecture Explorer and Quality Analyzer
         - Naming conventions
         - Code style patterns
         - Common idioms used in the codebase
         Example: "Use async/await with try-catch. Follow existing error handling pattern with AppError class."

       - **dependencies**: Extract related imports/modules from Architecture Explorer's dependency analysis
         Example: ["import jwt from 'jsonwebtoken'", "import { User } from './models/User'"]

       - **reference_implementations**: Extract similar code examples from Architecture Explorer
         Example: ["See authMiddleware.ts:120-150 for similar token validation", "Follow pattern in refreshToken.ts"]

       **IMPORTANT**: Do NOT leave these fields empty! Synthesize the relevant parts of the scout analysis into each microtask's context. Each task should have context tailored to its specific implementation needs.

    **MANDATORY: Comment During Every Step**

    You MUST use Commander MCP to log progress at EVERY step:

    ```
    mcp__commander__commander_log(
      task_id=0,
      message="[PREFIX]: [details]",
      agent_name="planner"
    )
    ```

    **Required Prefixes (use for EACH operation):**
    - `SYNTHESIZING:` When combining agent findings
    - `DECISION:` When making architectural or priority choices
    - `PLANNING:` When creating microtask structure
    - `INSIGHT:` For patterns in the analysis data
    - `COMPLETE:` Summary at end of planning

    **This is mandatory. Do not skip comments.**

    **Return Format (JSON):**

    **⚠️ CRITICAL: `initiative_summary` and `total_waves` are REQUIRED fields for the Initiative Progress UI!**

    ```json
    {
      "plan_summary": "Brief summary of the implementation plan",
      "initiative_summary": "REQUIRED - 1-2 sentence summary of what this initiative accomplishes and why it matters. This appears in the dashboard UI!",
      "total_tasks": 10,
      "total_waves": 3,  // REQUIRED - Number of waves (derived from max wave number)
      "microtasks": [
        {
          "id": 1,
          "description": "In {file} around lines {X} to {Y}, {problem}; {solution}",
          "file": "path/to/file.ts",
          "lines": "45-52",
          "wave": 1,
          "priority": 1,
          "work_type": "backend",
          "dependencies": [],
          "context": {
            "source": "commander-plan",
            "original_prompt": "[user's original request, cleaned up]",
            "wave": 1,
            "work_type": "backend",
            "file": "path/to/file.ts",
            "lines": "45-52",
            "severity": "HIGH",
            "assigned_agent": "reviewer",
            "backup_agent": "builder",
            "file_scope": {
              "allowed": ["path/to/file.ts", "related/module/"],
              "forbidden": ["src/core/", "tests/"]
            },
            "implementation_guide": "## Steps\n1. Step 1\n2. Step 2\n\n## Tests\n- Test 1",
            "analysis_context": {
              "architecture": "[Synthesized from Architecture Explorer: relevant files, patterns, structure]",
              "patterns": "[Coding patterns and conventions from analysis]",
              "dependencies": ["related imports", "module dependencies"],
              "reference_implementations": ["similar code examples to follow"]
            }
          },
          "implementation_guide": "## Steps\n1. ...\n2. ...\n\n## Tests\n- ..."
        }
      ],
      "wave_summary": {
        "wave_1": {"count": 4, "types": ["backend", "security"]},
        "wave_2": {"count": 3, "types": ["frontend", "testing"]},
        "wave_3": {"count": 3, "types": ["integration", "documentation"]}
      },
      "files_to_modify": ["file1.ts", "file2.ts"],
      "key_decisions": [
        "Decision 1: ... because ...",
        "Decision 2: ... because ..."
      ],
      "risks": [
        "Risk 1: ... mitigation: ..."
      ]
    }
    ```
```

### Phase 3.5: Validate Planner Response (Main Agent)

**⚠️ CRITICAL VALIDATION - Before proceeding, verify the planner response contains:**

1. **`initiative_summary`** - A 1-2 sentence summary (NOT empty, NOT null)
2. **`total_waves`** - A number > 0 (typically 2-4)

If either field is missing or invalid:
- Extract from the plan: `initiative_summary` = first sentence of `plan_summary`
- Calculate: `total_waves` = max wave number from microtasks

**Example validation:**
```
If planner returns:
  initiative_summary: null or ""  → Use: "{plan_summary first sentence}"
  total_waves: null or 0          → Use: max(microtasks[].wave)
```

**DO NOT proceed to Phase 6 without valid values for both fields!**

---

### Phase 4: Present Plan to User (Main Agent)

**The main agent receives the plan from planner and presents it to the user.**

Display the plan in a clear format:

```
## Implementation Plan: [PLAN_DESCRIPTION]

### Initiative Summary
[initiative_summary from planner agent - 1-2 sentence summary]

### Overview
[plan_summary from planner agent]

### Wave Overview
- Wave 1: [count] tasks ([types]) - Foundation
- Wave 2: [count] tasks ([types]) - Implementation
- Wave 3: [count] tasks ([types]) - Integration

---

### Wave 1 (Foundation - Independent)

**[work_type]**
- [ ] **Task 1** (priority: 1, severity: HIGH)
      In `file.ts:45-52` - [problem]; [solution]

**[work_type]**
- [ ] **Task 2** (priority: 2, severity: MEDIUM)
      In `file.ts:100-120` - [problem]; [solution]

---

### Wave 2 (Implementation - depends on Wave 1)

**[work_type]**
- [ ] **Task 3** (priority: 3, depends on: Task 1)
      In `file.ts:200-220` - [problem]; [solution]

---

### Key Decisions
1. [decision 1]
2. [decision 2]

### Risks
1. [risk 1]

### Files to Modify
- file1.ts
- file2.ts
- file3.ts
```

### Phase 5: Approval Gate

**Use AskUserQuestion tool to present options:**

```
AskUserQuestion({
  questions: [{
    question: "I've created a plan with X tasks organized into Y waves. How would you like to proceed?",
    header: "Plan Ready",
    options: [
      { label: "Create Tasks", description: "Create all tasks in Commander backlog and start execution" },
      { label: "Modify Plan", description: "Let me adjust the plan based on your feedback" },
      { label: "Cancel", description: "Don't create tasks, discard the plan" }
    ],
    multiSelect: false
  }]
})
```

Wait for user response before proceeding to Phase 6.

### Phase 6: Create Tasks in Commander (On Approval)

**Create tasks in Commander BACKLOG status with FULL CONTEXT.**

**CRITICAL: Persist all gathered context so execute phase can skip re-analysis.**

**⚠️ Policy Auto-Generation:**
- Policies are automatically generated from `file_scope` in each task's context
- If `file_scope.allowed` is missing or empty, a fallback policy will be generated (less restrictive, working directory scope)
- Fallback policies are logged with warnings for visibility
- Ensure `file_scope.allowed` contains at least one file path for proper policy generation

**⚠️ CRITICAL: The planner agent has already created the full context for each microtask.**

Your job as the Main agent is to **PASS THROUGH** what planner provides, NOT construct it yourself.

**⚠️⚠️⚠️ MANDATORY FIELDS FOR INITIATIVE UI ⚠️⚠️⚠️**

The following fields MUST be included in every `mcp__commander__commander_task_group` call:
- **`initiative_summary`** - WITHOUT this, the Initiative Progress section shows empty!
- **`total_waves`** - WITHOUT this, wave progress tracking breaks!

**NEVER omit these fields. ALWAYS include them from the planner agent's response.**

**⚠️ CRITICAL VALIDATION - Before calling mcp__commander__commander_task_group:**

**Policy Generation Validation:**
1. Each microtask has a non-empty `context` field
2. Each microtask has `context.file_scope` (REQUIRED for policy generation)
3. Each microtask has `context.file_scope.allowed` as a non-empty array
4. At least one allowed path is a specific file or directory relevant to the task
5. `context.analysis_context` exists and has data from scout agents

**If validation fails:**
- STOP immediately
- Report error: "Task [N] missing required file_scope.allowed - cannot generate policy"
- DO NOT create tasks without proper file_scope
- DO NOT create placeholders

**Note:** Policies are auto-generated from `file_scope` in context. Missing `file_scope` will result in fallback policy (less restrictive, working directory scope).

```
mcp__commander__commander_task_group(
  operation="create",
  group_name="[PLAN_DESCRIPTION]",
  group_description="[plan_summary from planner]",
  initiative_summary="[initiative_summary from planner]",  // ⚠️ NEVER OMIT
  total_waves=[total_waves from planner],                   // ⚠️ NEVER OMIT
  working_directory="[Current working directory]",
  tasks=[
    // For each microtask from planner plan:
    {
      description: "[Format microtask.description as nicely formatted markdown for UI]",
      task_prompt: "[Use microtask.description as CodeRabbit-style prompt for agent execution]",
      priority: microtask.priority,
      dependency_order: microtask.wave - 1,  // Wave 1 → 0, Wave 2 → 1, Wave 3 → 2
      context: JSON.stringify(microtask.context)  // ← PASS THROUGH - Don't construct!
    }
  ]
)
```

**Field Purposes:**
- `description`: Format the microtask description as markdown for Commander dashboard UI
- `task_prompt`: Use the microtask description as the CodeRabbit-style prompt for agent execution
- `context`: **PASS THROUGH** planner-provided context unchanged (already has all scout findings synthesized)

**IMPORTANT: Create ONE task group with ALL tasks:**

The dashboard's Initiative Progress UI tracks a single group with multiple waves.
Each task's `dependency_order` field determines which wave it belongs to:
- `dependency_order: 0` = Wave 1 (foundation/independent tasks)
- `dependency_order: 1` = Wave 2 (depends on Wave 1)
- `dependency_order: 2` = Wave 3 (depends on Wave 2)

**Example - Single group with all tasks across waves:**

```
// Iterate through ALL microtasks from planner plan and create tasks
const tasksForMCP = opusPlan.microtasks.map(microtask => ({
  description: formatAsMarkdown(microtask.description),
  task_prompt: microtask.description,  // CodeRabbit-style prompt
  priority: microtask.priority,
  dependency_order: microtask.wave - 1,  // Convert wave 1/2/3 to order 0/1/2
  context: JSON.stringify(microtask.context)  // ← PASS THROUGH from planner
}));

mcp__commander__commander_task_group(
  operation="create",
  group_name="[PLAN_DESCRIPTION]",
  group_description="[plan_summary from planner]",
  initiative_summary="[initiative_summary from planner]",  // ⚠️ From planner response
  total_waves=[total_waves from planner],                  // ⚠️ From planner response
  working_directory="[Current working directory]",
  tasks=tasksForMCP  // All tasks with planner-provided context
)
```

**Key Points:**
- Loop through `opusPlan.microtasks` - don't construct tasks manually
- Use `JSON.stringify(microtask.context)` - don't build context object yourself
- Planner has already synthesized all scout findings into each microtask's context

**DO NOT create separate groups per wave** - this breaks initiative progress tracking.

**Why save all this context?**

When `/commander-execute` runs:
- Task groups with `dependency_order` already define execution sequence
- `file_scope` is already computed - no need to re-analyze
- `assigned_agent` is already determined - no need to re-classify
- `implementation_guide` has all the details - agents can execute directly

**Execute phase can skip planning for these tasks!**

### Phase 7: Display Task Board

Show created tasks:

```
## Tasks Created in Commander (Backlog)

### Wave 1 (Foundation)
- [ID:123] BACKLOG - In file.ts:45-52 - Fix auth bug (priority: 1)
- [ID:124] BACKLOG - In file.ts:100-120 - Add validation (priority: 2)

### Wave 2 (Implementation)
- [ID:125] BACKLOG - In module.ts:200-220 - Implement handler (priority: 3)

### Wave 3 (Integration)
- [ID:126] BACKLOG - In test.ts:1-50 - Add tests (priority: 4)

---

### Execution Model: Claim-Loop (Multi-Agent Aware)

When user chooses "Execute All" or "Execute Wave 1", tasks are executed using the **claim-loop pattern**:

```
┌─────────────────────────────────────────────────────────────────┐
│                    CLAIM-LOOP EXECUTION                          │
│                                                                  │
│  Each agent:                                                     │
│  1. Claims ONE task at a time (atomic, race-safe)               │
│  2. Works on it, completes it                                   │
│  3. Claims the next available task                               │
│  4. Continues until all tasks in all waves complete              │
└─────────────────────────────────────────────────────────────────┘
```

**Multi-Agent Support:**
- Multiple `/commander-execute` instances can run in parallel
- Agents naturally distribute work via atomic claiming
- No central coordinator needed
- Race conditions are handled gracefully (just try the next task)

**Wave Boundaries:**
- All Wave N tasks must complete before Wave N+1 starts
- Agents wait if no tasks available but wave incomplete
- Commit checkpoint created after each wave

**Trigger execution:**
- `/commander-execute backlog` - Execute all backlog tasks
- `/commander-execute` - Execute pending tasks
- Run from multiple terminals for parallel execution

---

**Use AskUserQuestion for next steps:**

```
AskUserQuestion({
  questions: [{
    question: "Tasks created successfully! What would you like to do next?",
    header: "Next Steps",
    options: [
      { label: "Execute All", description: "Run /commander-execute to begin claim-loop execution" },
      { label: "Execute Wave 1", description: "Start with foundation tasks only" },
      { label: "Review First", description: "I'll review the tasks in Commander dashboard before executing" },
      { label: "Done", description: "Tasks are saved, I'll execute them later" }
    ],
    multiSelect: false
  }]
})
```

---

## MANDATORY: Comment Protocol

**ALL agents (scout explorers and planner) follow this protocol.**

### Comment Types
| Type | When to Use |
|------|-------------|
| `progress` | Normal work updates |
| `error` | When something goes wrong |
| `attempt` | When trying a solution |
| `handoff` | Information for next agent |
| `info` | General observations |

### Comment Prefixes
```
ANALYZING: [file] - [what you are looking for]
FOUND: [discovery] - [relevance to task]
DECISION: [choice] because [reasoning]
PLANNING: [what you will do] - [why]
INSIGHT: [pattern or learning]
```

---

## Agent Roles Summary

| Agent | Name | Role | When Used |
|-------|------|------|-----------|
| Main Agent | `pi` | Orchestrator | Always |
| Architecture Explorer | `scout` | Find structure, patterns, dependencies | Always |
| Security Analyzer | `scout` | Find auth, validation, vulnerabilities | If security-related |
| Quality Analyzer | `scout` | Find duplication, tech debt, smells | If quality-related |
| Test Analyzer | `scout` | Map coverage, find gaps | If testing-related |
| API Analyzer | `scout` | Map endpoints, integrations | If API-related |
| Planning Agent | `planner` | Synthesize findings into plan | Always |

---

## MCP Tools Reference

| Tool | Purpose |
|------|---------|
| `mcp__commander__commander_task` | Create/get/update/list tasks |
| `mcp__commander__commander_task_lifecycle` | Claim, complete, fail tasks |
| `mcp__commander__commander_task_group` | Create task groups with ordering |
| `mcp__commander__commander_comment` | Add progress comments |
| `mcp__commander__commander_log` | Real-time dashboard updates |

---

## Usage Examples

```bash
# Feature implementation
/commander-plan Implement user authentication with JWT tokens

# From Horizon plan
/commander-plan horizon:plan_auth_system

# UI feature
/commander-plan Add dark mode support to the application

# Refactoring
/commander-plan Refactor the payment processing module

# API development
/commander-plan Create REST API for user management
```
