Initial: pi-skill — 68 skills, 43 extensions, 11 themes for Pi

commands/commander/co-op.md

@@ -0,0 +1,213 @@
+---
+description: "Spawn up to 10 cooperative agents that actively help each other, share discoveries, request assistance, and spawn helpers"
+argument-hint: "[task description or 'pending'/'backlog' to process existing tasks]"
+allowed-tools: ["Task", "TaskOutput", "mcp__commander__commander_task", "mcp__commander__commander_session", "mcp__commander__commander_mailbox", "mcp__commander__commander_cooperation", "mcp__commander__commander_orchestration", "mcp__commander__commander_dependency", "Bash", "Read", "Edit"]
+---
+
+# /co-op — Cooperative Agent Team Mode
+
+Spawn up to **10 cooperative agents** that actively help each other through Commander's cooperation system. Unlike regular teams where agents work in isolation, `/co-op` agents share discoveries, request help when stuck, offer assistance when done early, and can request helper spawns for specialist work.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    COORDINATOR (You)                         │
+│              Monitor cooperation, handle spawns              │
+└──────────────────────┬──────────────────────────────────────┘
+                       │ spawns up to 10
+        ┌──────────────┼──────────────┐
+        ▼              ▼              ▼
+  ┌───────────┐  ┌───────────┐  ┌───────────┐
+  │ co-op-1   │  │ co-op-2   │  │ co-op-N   │
+  │           │◄─►│           │◄─►│           │
+  │ share     │  │ help      │  │ discover  │
+  │ discover  │  │ offer     │  │ spawn     │
+  └───────────┘  └───────────┘  └───────────┘
+        │              │              │
+        └──────────────┼──────────────┘
+                       ▼
+              commander_cooperation
+              (shared discoveries,
+               help requests, team status)
+```
+
+## Step 1: Determine Task Source
+
+Parse `$ARGUMENTS` to determine the work:
+
+**If processing existing tasks** (e.g., "pending", "backlog", "failed"):
+```
+mcp__commander__commander_task(operation="list", status="pending", limit=20)
+```
+
+**If given a new task description**, decompose it into subtasks. Think about:
+- What are the independent work streams?
+- What dependencies exist?
+- What specialist knowledge is needed?
+- Aim for 3-10 subtasks that can be parallelized.
+
+## Step 2: Create Task Group
+
+```
+mcp__commander__commander_task(
+  operation="group:create",
+  group_name="co-op: [brief summary]",
+  initiative_summary="[1-2 sentence summary of the cooperative effort]",
+  total_waves=1,
+  working_directory="[current working directory]",
+  tasks=[
+    {
+      "description": "[subtask 1]",
+      "task_prompt": "[detailed instructions including cooperative protocol]",
+      "dependency_order": 0,
+      "context": "[relevant context for this subtask]"
+    },
+    // ... more tasks
+  ]
+)
+```
+
+## Step 3: Spawn Cooperative Agents (Up to 10)
+
+For each task, spawn a background agent with the **cooperative protocol** baked in.
+
+**IMPORTANT**: Spawn ALL agents in a SINGLE response using multiple Task() calls:
+
+```
+Task(
+  subagent_type="general-purpose",
+  run_in_background=true,
+  prompt="You are co-op-agent-1, a COOPERATIVE agent in /co-op team mode.
+
+## Your Task
+- Task ID: {task_id}
+- Description: {description}
+- Working Directory: {working_directory}
+- Group ID: {group_id}
+- Your Agent Name: co-op-agent-1
+
+## Sibling Tasks (your teammates):
+{list of other tasks and their descriptions}
+
+## COOPERATIVE PROTOCOL
+
+### 1. Claim your task
+mcp__commander__commander_task(operation='claim', task_id={task_id}, agent_name='co-op-agent-1', model_id='claude-sonnet-4-20250514')
+
+### 2. Check in with team FIRST
+mcp__commander__commander_cooperation(operation='team:status', group_id={group_id})
+mcp__commander__commander_cooperation(operation='team:discoveries', group_id={group_id})
+mcp__commander__commander_mailbox(operation='inbox', agent_name='co-op-agent-1')
+
+### 3. Do your work — and SHARE discoveries as you go
+When you find something useful (file locations, API patterns, config, architecture insights):
+mcp__commander__commander_cooperation(operation='share:discovery', from_agent='co-op-agent-1', group_id={group_id}, body='...', discovery_type='...', tags=['...'])
+
+### 4. Ask for help if stuck (after 2+ failed attempts)
+mcp__commander__commander_cooperation(operation='help:request', from_agent='co-op-agent-1', task_id={task_id}, body='Stuck on: ...', urgency='high')
+
+### 5. When done, check if teammates need help
+mcp__commander__commander_cooperation(operation='team:help_needed', group_id={group_id})
+If someone needs help, offer:
+mcp__commander__commander_cooperation(operation='help:offer', from_agent='co-op-agent-1', to_agent='[stuck agent]', body='I can help with...')
+
+### 6. Complete your task
+mcp__commander__commander_task(operation='complete', task_id={task_id}, result='[summary]')
+
+### 7. Send status update
+mcp__commander__commander_mailbox(operation='send', from_agent='co-op-agent-1', to_agent='commander', body='Completed: [summary]', message_type='worker_done', task_id={task_id}, group_id={group_id})
+
+### 8. Cleanup
+mcp__commander__commander_session(operation='cleanup:self')
+
+## Rules
+- ALWAYS check team discoveries before starting work
+- Share discoveries IMMEDIATELY — don't hoard knowledge
+- Ask for help after 2 failed attempts
+- Offer help when you finish early
+- Keep status updates concise"
+)
+```
+
+## Step 4: Monitor Cooperation
+
+While agents work, periodically check:
+
+```
+# Team-wide status
+mcp__commander__commander_cooperation(operation="team:status", group_id={group_id})
+
+# Any open help requests needing intervention
+mcp__commander__commander_cooperation(operation="team:help_needed", group_id={group_id})
+
+# Check agent progress
+TaskOutput(task_id="{agent_id}", block=false)
+```
+
+### Handle Spawn Requests
+
+If an agent sends a `spawn:request`, create and spawn the helper:
+
+```
+# Create helper task
+mcp__commander__commander_task(
+  operation="create",
+  description="[helper task from spawn request]",
+  working_directory="[cwd]",
+  context="Helper spawned by {requesting_agent}: {reason}"
+)
+
+# Spawn helper agent
+Task(
+  subagent_type="general-purpose",
+  run_in_background=true,
+  prompt="You are co-op-helper-{N}, spawned to help {requesting_agent}.
+  Their request: {spawn_body}
+  Group ID: {group_id}
+  
+  1. Check team discoveries first
+  2. Do the requested work
+  3. Share your results via share:context
+  4. Notify the requesting agent via mailbox
+  5. Cleanup your session"
+)
+```
+
+### Handle Blockers
+
+If a blocker is reported, try to resolve it or escalate to the user.
+
+## Step 5: Report Summary
+
+When all agents complete, report:
+
+```
+## /co-op Summary
+
+### Results
+- **Tasks**: X completed, Y failed out of Z total
+- **Agents**: N cooperative agents spawned
+- **Helpers**: M helper agents spawned on-demand
+
+### Cooperation Activity
+- **Discoveries shared**: D findings (list highlights)
+- **Help interactions**: H (who helped whom)
+- **Spawn requests**: S (what specialists were needed)
+
+### Key Discoveries
+1. [Most impactful discovery]
+2. [Second discovery]
+...
+
+### Execution Time
+Total: Xm Ys
+```
+
+## Notes
+
+- **Maximum 10 agents** at once (configurable)
+- You are the **coordinator** — do NOT do the work yourself
+- Use `TaskOutput(block=true)` only when all agents are running and you need to wait
+- Discoveries persist in the database — future agents can access them
+- The cooperation protocol is what makes `/co-op` special — enforce it

commands/commander/plan.md

@@ -0,0 +1,979 @@
+---
+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
+```

commands/commander/session-cleanup.md

@@ -0,0 +1,244 @@
+---
+description: "Clean up stale terminal sessions - check health, remove zombies, and self-cleanup when done"
+argument-hint: "[status|cleanup|terminate <session_id>|cleanup-self]"
+allowed-tools: ["mcp__commander__commander_session_cleanup", "mcp__commander__commander_terminal_sessions"]
+---
+
+# Commander Session Cleanup - Terminal Session Lifecycle Management
+
+This command manages terminal session lifecycle and cleanup. Use it to:
+- Check session health (stale/zombie counts)
+- Clean up old sessions (>24 hours)
+- Terminate specific sessions
+- Clean up your own session when done
+
+## IMPORTANT: Agent Self-Cleanup Protocol
+
+**Every agent should follow this cleanup protocol:**
+
+1. **At start of major work:** Check session health with `status` operation
+2. **If >10 REALLY stale sessions:** Clean them up proactively with `cleanup`
+3. **When work is DONE:** Call `terminate_self` to clean up your own session
+
+```
+MANDATORY: Sessions older than 24 hours are REALLY stale.
+Sessions older than 48 hours are ZOMBIES and MUST be cleaned.
+```
+
+---
+
+## Input
+
+Operation: **$ARGUMENTS**
+
+### Available Operations
+
+| Operation | Example | Description |
+|-----------|---------|-------------|
+| `status` | `/session-cleanup status` | Check stale session counts |
+| `cleanup` | `/session-cleanup cleanup` | Remove sessions >24h old |
+| `cleanup 6` | `/session-cleanup cleanup 6` | Remove sessions >6h old |
+| `terminate <id>` | `/session-cleanup terminate abc-123` | Terminate specific session |
+| `cleanup-self` | `/session-cleanup cleanup-self` | Terminate your own session |
+
+---
+
+## Workflow
+
+### 1. Check Session Health (status)
+
+```
+mcp__commander__commander_session_cleanup(
+  operation="status"
+)
+```
+
+**Returns:**
+```
+Session Health:
+- Total: 45
+- Active: 12
+- Stale (>6h): 8
+- REALLY Stale (>24h): 15
+- Zombie (>48h): 10
+
+Recommendation: Run cleanup_stale immediately! (15 REALLY stale sessions)
+```
+
+### 2. Clean Up Stale Sessions (cleanup_stale)
+
+```
+mcp__commander__commander_session_cleanup(
+  operation="cleanup_stale",
+  min_age_hours=24,          // Default: 24 hours
+  include_browser_mode=true, // Default: true
+  dry_run=false              // Set true to preview
+)
+```
+
+**Returns:**
+```
+Cleaned up 25 stale sessions:
+- 15 sessions >24 hours old terminated
+- 10 zombie sessions (>48h) terminated
+
+Sessions cleaned:
+- abc-123: claude, health-dashboard, 36h old
+- def-456: cursor, commander, 48h old
+...
+```
+
+### 3. Terminate Specific Session (terminate)
+
+```
+mcp__commander__commander_session_cleanup(
+  operation="terminate",
+  session_id="abc-123-def-456"
+)
+```
+
+### 4. Clean Up Your Own Session (terminate_self)
+
+**Call this when your work is complete:**
+
+```
+mcp__commander__commander_session_cleanup(
+  operation="terminate_self"
+)
+```
+
+---
+
+## Staleness Thresholds
+
+| Threshold | Time | Status | Action |
+|-----------|------|--------|--------|
+| Active | <6h | Healthy | None |
+| Stale | 6-24h | Warning | Monitor |
+| REALLY Stale | 24-48h | Cleanup candidate | Should clean |
+| Zombie | >48h | Critical | MUST clean |
+
+---
+
+## Dry Run Mode
+
+To preview what would be cleaned without actually cleaning:
+
+```
+mcp__commander__commander_session_cleanup(
+  operation="cleanup_stale",
+  dry_run=true
+)
+```
+
+**Returns:**
+```
+DRY RUN - Would clean up 25 sessions:
+- 15 sessions >24 hours old
+- 10 zombie sessions (>48h)
+
+No sessions were actually terminated. Run without dry_run=true to clean.
+```
+
+---
+
+## MCP Tool Reference
+
+```typescript
+{
+  name: 'commander_session_cleanup',
+  description: 'Manage terminal session lifecycle and cleanup stale sessions.',
+  inputSchema: {
+    operation: 'status' | 'cleanup_stale' | 'terminate' | 'terminate_self',
+    session_id?: string,     // Required for 'terminate'
+    min_age_hours?: number,  // Default: 24
+    dry_run?: boolean,       // Default: false
+    include_browser_mode?: boolean  // Default: true
+  }
+}
+```
+
+---
+
+## Best Practices for Agents
+
+### On Session Startup
+```typescript
+// Check if cleanup is needed
+const status = await mcp__commander__commander_session_cleanup({
+  operation: "status"
+});
+
+if (status.really_stale_24h > 10) {
+  // Clean up before starting work
+  await mcp__commander__commander_session_cleanup({
+    operation: "cleanup_stale",
+    min_age_hours: 24
+  });
+}
+```
+
+### On Session Completion
+```typescript
+// Always clean up your own session when done
+await mcp__commander__commander_session_cleanup({
+  operation: "terminate_self"
+});
+```
+
+### Periodic Health Check
+```typescript
+// If session count seems high, check and clean
+const sessions = await mcp__commander__commander_terminal_sessions({
+  operation: "list"
+});
+
+if (sessions.length > 20) {
+  // Too many sessions - clean up zombies
+  await mcp__commander__commander_session_cleanup({
+    operation: "cleanup_stale",
+    min_age_hours: 48  // Only clean zombies
+  });
+}
+```
+
+---
+
+## Usage Examples
+
+```bash
+# Check current session health
+/session-cleanup status
+
+# Clean up all sessions older than 24 hours
+/session-cleanup cleanup
+
+# Clean up all sessions older than 6 hours
+/session-cleanup cleanup 6
+
+# Preview what would be cleaned (dry run)
+/session-cleanup cleanup --dry-run
+
+# Terminate a specific session
+/session-cleanup terminate abc-123-def-456
+
+# Clean up your own session when done
+/session-cleanup cleanup-self
+```
+
+---
+
+## Why This Matters
+
+**Problem:** Terminal sessions persist indefinitely in Commander. Without cleanup:
+- Memory usage grows continuously
+- 64+ stale sessions can accumulate
+- Dashboard becomes cluttered
+- System performance degrades
+
+**Solution:** Responsible agents clean up after themselves:
+1. Check session health at start
+2. Proactively clean stale sessions
+3. Terminate their own session when done
+
+**Goal:** Keep active sessions < 20 at any time

commands/commander/task.md

@@ -0,0 +1,863 @@
+---
+description: "Plan and execute a single task with full Commander MCP tracking - uses planning agents for context, then implements directly"
+argument-hint: "[task description - what to implement, fix, or build]"
+allowed-tools: ["Task", "Read", "Write", "Edit", "Glob", "Grep", "Bash", "WebFetch", "WebSearch", "mcp__commander__commander_task", "mcp__commander__commander_task_lifecycle", "mcp__commander__commander_comment", "mcp__commander__commander_log", "AskUserQuestion"]
+---
+
+# Commander Task - Planning + Execution with Full Tracking
+
+**⚠️ 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 combines **planning agent architecture** with **direct execution** for single-task workflows. Unlike `/commander-plan` (multi-task planning) or `/commander-execute` (batch execution), this command:
+
+1. Uses scout agents to gather context in parallel
+2. Uses planner agent to create an implementation plan
+3. Creates the task **in a Commander task group** for tracking
+4. **Executes the task directly with full observability**
+
+## Planning + Execution Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         MAIN AGENT                                  │
+│                    (Orchestrator Only)                              │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                    ┌─────────┴─────────┐
+                    │   Phase 1: Parse   │
+                    │   Task Request     │
+                    └─────────┬─────────┘
+                              │
+        ┌─────────────────────┼─────────────────────┐
+        ▼                     ▼                     ▼
+┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+│ SCOUT AGENT 1 │   │ SCOUT AGENT 2 │   │ SCOUT AGENT 3 │
+│  Codebase     │   │   Related     │   │   Patterns    │
+│  Structure    │   │   Files       │   │   & Context   │
+└───────┬───────┘   └───────┬───────┘   └───────┬───────┘
+        │                   │                   │
+        └─────────────────┬─┴───────────────────┘
+                          │
+                          ▼
+              ┌─────────────────────┐
+              │    PLANNER AGENT       │
+              │  (Planning Agent)   │
+              │   Create Detailed   │
+              │   Implementation    │
+              │   Plan              │
+              └─────────┬───────────┘
+                        │
+                        ▼
+              ┌─────────────────────┐
+              │    MAIN AGENT       │
+              │  Create Task in     │
+              │  Commander & EXECUTE│
+              │  with Full Tracking │
+              └─────────────────────┘
+```
+
+**Key Principle: The main agent does NO context gathering - delegates to subagents, then executes the plan.**
+
+---
+
+## When to Use
+
+Use `/commander-task` for:
+- **Single tasks** that benefit from codebase context
+- Bug fixes where you need to understand surrounding code
+- Feature additions that should follow existing patterns
+- Any work that needs planning before implementation
+- Tasks where you want **full observability** via Commander dashboard
+
+Use `/commander-plan` instead if:
+- Task decomposes into **multiple subtasks**
+- You want tasks created but NOT executed immediately
+- Feature requires parallel agent execution
+
+Use the simpler direct approach if:
+- Task is trivial (e.g., "fix typo in README")
+- No context gathering needed
+- You don't need Commander tracking
+
+---
+
+## Input
+
+Task description: **$ARGUMENTS**
+
+Examples:
+- `Fix the null pointer exception in UserService.findById`
+- `Add email validation to the signup form`
+- `Implement the logout endpoint following existing auth patterns`
+- `Refactor the payment processing to use the new billing service`
+
+---
+
+## Workflow
+
+### Phase 1: Parse Task Request (Main Agent)
+
+**The main agent ONLY parses the request - it does NOT gather context.**
+
+1. **Extract Task Intent**
+   - Parse the goal from $ARGUMENTS
+   - Identify keywords suggesting scope (files, features, areas)
+   - Note any mentioned files or patterns
+
+2. **Determine Context Needs**
+   Based on the task description, identify what context is needed:
+   - **Structure** - Always needed (where are relevant files?)
+   - **Related Files** - Files mentioned or implied in the task
+   - **Patterns** - Existing patterns to follow
+
+3. **Spawn scout Agents in Parallel**
+   Launch 2-3 scout subagents for focused context gathering.
+
+### Phase 2: Parallel Context Gathering (scout Subagents)
+
+**Spawn multiple scout agents IN PARALLEL using the Task tool.**
+
+**CRITICAL: Launch ALL scout agents in a SINGLE message with multiple Task tool calls.**
+
+#### Agent 1: Codebase Structure Explorer
+
+```
+Use the Task tool with:
+- subagent_type: "Explore"
+- model: "scout"
+- prompt: |
+    ## Codebase Structure for Task: [TASK_DESCRIPTION]
+
+    **Your Mission:** Find the relevant parts of the codebase for this task.
+
+    **Exploration Tasks:**
+    1. Find files related to the task (by name, location, imports)
+    2. Identify the main entry point or module
+    3. Map the directory structure of relevant areas
+    4. Find configuration files that may be relevant
+
+    **Search Strategy:**
+    - Glob for relevant file patterns
+    - Grep for keywords from the task description
+    - Read key files to understand structure
+
+    **Return Format (JSON):**
+    ```json
+    {
+      "relevant_files": [
+        {"path": "...", "purpose": "...", "relevance": "high|medium|low"}
+      ],
+      "directory_structure": {
+        "src/": ["models/", "services/", "utils/"]
+      },
+      "entry_points": ["...", "..."],
+      "config_files": ["...", "..."],
+      "key_insights": ["...", "..."]
+    }
+    ```
+```
+
+#### Agent 2: Related Files Analyzer
+
+```
+Use the Task tool with:
+- subagent_type: "Explore"
+- model: "scout"
+- prompt: |
+    ## Related Files for Task: [TASK_DESCRIPTION]
+
+    **Your Mission:** Find and analyze files directly related to this task.
+
+    **Exploration Tasks:**
+    1. Find the specific file(s) that need modification
+    2. Read the file content to understand current implementation
+    3. Identify imports and dependencies
+    4. Find tests for these files
+    5. Look for similar implementations to reference
+
+    **Search Strategy:**
+    - Direct file reads for mentioned files
+    - Grep for related function/class names
+    - Find test files
+
+    **Return Format (JSON):**
+    ```json
+    {
+      "files_to_modify": [
+        {
+          "path": "...",
+          "current_content_summary": "...",
+          "lines_of_interest": "45-60",
+          "imports": ["...", "..."],
+          "exports": ["...", "..."]
+        }
+      ],
+      "test_files": ["...", "..."],
+      "similar_implementations": [
+        {"file": "...", "what": "...", "how_similar": "..."}
+      ],
+      "dependencies": ["...", "..."]
+    }
+    ```
+```
+
+#### Agent 3: Patterns & Context Analyzer
+
+```
+Use the Task tool with:
+- subagent_type: "Explore"
+- model: "scout"
+- prompt: |
+    ## Patterns & Context for Task: [TASK_DESCRIPTION]
+
+    **Your Mission:** Understand the patterns and conventions used in this codebase.
+
+    **Exploration Tasks:**
+    1. Identify coding patterns in related files
+    2. Find naming conventions
+    3. Look for error handling patterns
+    4. Check for existing utilities that could be reused
+    5. Find documentation or comments about conventions
+
+    **Search Strategy:**
+    - Read multiple related files to see patterns
+    - Grep for common patterns (try/catch, async/await, etc.)
+    - Look for utility functions
+
+    **Return Format (JSON):**
+    ```json
+    {
+      "patterns": [
+        {
+          "name": "Error handling",
+          "example_file": "...",
+          "example_lines": "45-60",
+          "description": "..."
+        }
+      ],
+      "naming_conventions": {
+        "functions": "camelCase",
+        "files": "kebab-case",
+        "classes": "PascalCase"
+      },
+      "reusable_utilities": [
+        {"name": "...", "file": "...", "purpose": "..."}
+      ],
+      "conventions_to_follow": ["...", "..."]
+    }
+    ```
+```
+
+### Phase 3: Implementation Planning (planner Subagent)
+
+**After ALL scout agents return, spawn planner to create the implementation plan.**
+
+```
+Use the Task tool with:
+- subagent_type: "Plan"
+- model: "planner"
+- prompt: |
+    ## Create Implementation Plan for Task: [TASK_DESCRIPTION]
+
+    **Context from Analysis:**
+
+    ### Codebase Structure:
+    [INSERT STRUCTURE AGENT RESULTS]
+
+    ### Related Files:
+    [INSERT FILES AGENT RESULTS]
+
+    ### Patterns & Context:
+    [INSERT PATTERNS AGENT RESULTS]
+
+    ---
+
+    **Your Mission:** Create a detailed, step-by-step implementation plan.
+
+    **Planning Requirements:**
+
+    1. **Analyze the Task**
+       - What exactly needs to be done?
+       - What files need to be modified?
+       - What patterns should be followed?
+
+    2. **Create Step-by-Step Plan**
+       For each step:
+       - What file to modify
+       - What specific changes to make
+       - What patterns to follow
+       - What to test
+
+    3. **Identify Risks**
+       - What could go wrong?
+       - What edge cases exist?
+       - What tests are needed?
+
+    4. **Define Success Criteria**
+       - How do we know when the task is complete?
+       - What tests should pass?
+       - What behavior should change?
+
+    **Return Format (JSON):**
+    ```json
+    {
+      "task_summary": "Brief description of what will be done",
+      "files_to_modify": [
+        {
+          "file": "src/services/UserService.ts",
+          "action": "modify",
+          "changes": "Add null check in findById method",
+          "lines": "45-52"
+        }
+      ],
+      "implementation_steps": [
+        {
+          "step": 1,
+          "description": "Add null check after database query",
+          "file": "src/services/UserService.ts",
+          "details": "After line 47, add: if (!user) throw new UserNotFoundError(id)",
+          "pattern_reference": "See similar pattern in src/services/ProductService.ts:89"
+        },
+        {
+          "step": 2,
+          "description": "Add test for null case",
+          "file": "src/services/UserService.test.ts",
+          "details": "Add test case: 'should throw UserNotFoundError when user not found'",
+          "pattern_reference": "Follow existing test patterns in file"
+        }
+      ],
+      "tests_to_run": ["npm test -- UserService"],
+      "success_criteria": [
+        "findById throws UserNotFoundError for invalid ID",
+        "All existing tests pass",
+        "New test passes"
+      ],
+      "risks": [
+        {
+          "risk": "Breaking change for callers expecting null",
+          "mitigation": "Check all callers handle the error"
+        }
+      ],
+      "estimated_complexity": "low|medium|high"
+    }
+    ```
+```
+
+### Phase 4: Create Task & Present Plan (Main Agent)
+
+**The main agent creates the task in Commander and presents the plan to the user.**
+
+1. **Create Task Group in Commander (MANDATORY - Never Create Ad-Hoc Tasks)**
+
+   **⚠️ CRITICAL: ALL tasks MUST be created inside a task group. NEVER use `commander_task(operation="create")` to create standalone/ad-hoc tasks. Always use `commander_task_group(operation="create")` even for single tasks.**
+
+   ```
+   mcp__commander__commander_task_group(
+     operation="create",
+     group_name="[TASK_DESCRIPTION - short title]",
+     group_description="[plan_summary from planner]",
+     initiative_summary="[1-2 sentence summary of what this task accomplishes]",
+     total_waves=1,
+     working_directory="[Current working directory]",
+     tasks=[
+       {
+         description: "[Nicely formatted markdown description for UI]",
+         task_prompt: "[CodeRabbit-style prompt: In {file} around lines {X} to {Y}, {problem}; {solution}]",
+         priority: 5,
+         dependency_order: 0,
+         context: JSON.stringify({
+           source: "commander-task",
+           original_prompt: "$ARGUMENTS",
+           wave: 1,
+           work_type: "[backend|frontend|testing|etc]",
+           file_scope: {
+             allowed: ["[files from plan]"],
+             forbidden: ["[files NOT to touch]"]
+           },
+           implementation_guide: "[step-by-step from planner plan]",
+           analysis_context: {
+             architecture: "[from scout findings]",
+             patterns: "[from scout findings]",
+             dependencies: ["[relevant imports]"],
+             reference_implementations: ["[similar code examples]"]
+           }
+         })
+       }
+     ]
+   )
+   ```
+
+   Save the returned `group_id` and `task_id` for tracking.
+
+2. **Present Plan to User**
+
+   ```
+   ## Implementation Plan
+
+   ### Summary
+   [task_summary from planner]
+
+   ### Files to Modify
+   - `file1.ts` - [action]: [changes]
+   - `file2.ts` - [action]: [changes]
+
+   ### Steps
+   1. [step 1 description]
+      - File: [file]
+      - Details: [details]
+      - Pattern: [reference]
+
+   2. [step 2 description]
+      - File: [file]
+      - Details: [details]
+
+   ### Success Criteria
+   - [ ] [criterion 1]
+   - [ ] [criterion 2]
+
+   ### Risks
+   - [risk 1]: [mitigation]
+
+   ---
+
+   **Task group created:** [GROUP_NAME] with task #[task_id]
+
+   Ready to execute this plan?
+   - **Yes** - Begin implementation with full tracking
+   - **Modify** - Let me adjust the plan first
+   - **Cancel** - Don't execute
+   ```
+
+### Phase 5: Execute with Full Tracking (Main Agent)
+
+**On approval, the main agent executes the plan with constant Commander updates.**
+
+#### 5.0 Awareness Check (Quick Glance)
+
+You work independently, but other agents may be active in this project. Before starting execution, check your inbox for context:
+
+```
+mcp__commander__commander_mailbox(
+  operation="inbox",
+  agent_name="pi"
+)
+```
+
+If there are messages with discoveries or context from other agents, use them — don't redo work that's already been done. If another agent is already working on this exact task, stop and report the conflict.
+
+While you work, you have tools available if you need them:
+- **Share a discovery**: `mcp__commander__commander_mailbox(operation="send", from_agent="pi", to_agent="@all", body="Found: [discovery]", message_type="status")`
+- **Ask for help** (stuck after 2+ attempts): `mcp__commander__commander_mailbox(operation="send", from_agent="pi", to_agent="commander", body="Stuck on: [problem]", message_type="error")`
+- **Request a helper**: `mcp__commander__commander_mailbox(operation="send", from_agent="pi", to_agent="commander", body="Need help with: [task]", message_type="question")`
+
+None of these are required. Use them when they would actually help.
+
+#### 5.1 Claim and Start
+
+```
+mcp__commander__commander_task_lifecycle(
+  operation="claim",
+  task_id=[TASK_ID],
+  agent_id="pi",
+  agent_name="pi",
+  working_directory="[Current working directory]"
+)
+
+mcp__commander__commander_comment(
+  operation="add",
+  task_id=[TASK_ID],
+  type="progress",
+  agent_name="pi",
+  message="STARTED: Beginning implementation. Plan: [brief summary]. First step: [step 1]"
+)
+```
+
+#### 5.2 Execute Each Step with Comments
+
+**For each step in the plan, follow this pattern:**
+
+```
+# Before starting step
+mcp__commander__commander_comment(
+  operation="add",
+  task_id=[TASK_ID],
+  type="progress",
+  agent_name="pi",
+  message="STEP [N]: Starting - [description]"
+)
+
+# During the step - comment on every action
+mcp__commander__commander_comment(
+  operation="add",
+  task_id=[TASK_ID],
+  type="progress",
+  agent_name="pi",
+  message="ANALYZING: [file] - [what you're looking for]"
+)
+
+# Do the actual work (Read, Edit, Write, etc.)
+# ...
+
+mcp__commander__commander_comment(
+  operation="add",
+  task_id=[TASK_ID],
+  type="progress",
+  agent_name="pi",
+  message="MODIFIED: [file] lines [X-Y] - [what changed]"
+)
+
+# After completing step
+mcp__commander__commander_comment(
+  operation="add",
+  task_id=[TASK_ID],
+  type="progress",
+  agent_name="pi",
+  message="STEP [N]: Complete - [summary]"
+)
+```
+
+#### 5.3 Comment Patterns
+
+**Use these exact prefixes for consistent tracking:**
+
+```
+STEP [N]: Starting - [description]
+ANALYZING: [file] - [what you're looking for]
+FOUND: [discovery] - [relevance]
+DECISION: [choice] because [reasoning]
+PLANNING: [what you will do] - [why]
+MODIFIED: [file] lines [X-Y] - [what changed]
+STEP [N]: Complete - [summary]
+TESTING: Running [test] - [expected outcome]
+RESULT: [passed/failed] - [details]
+ISSUE: [problem] - attempting [solution]
+RESOLVED: [issue] by [solution]
+BLOCKER: [issue]. Tried: [attempts]. Need: [help]
+INSIGHT: [pattern or learning]
+```
+
+#### 5.4 Use Logs for Real-Time Dashboard
+
+```
+mcp__commander__commander_log(
+  task_id=[TASK_ID],
+  message="[Concise progress update]",
+  agent_name="pi",
+  level="info"  // or "warn" for issues, "error" for failures
+)
+```
+
+### Phase 6: Complete or Fail
+
+#### On Successful Completion
+
+```
+# Final verification comment
+mcp__commander__commander_comment(
+  operation="add",
+  task_id=[TASK_ID],
+  type="progress",
+  agent_name="pi",
+  message="COMPLETING: Final verification - [what you checked]"
+)
+
+# Complete the task
+mcp__commander__commander_task_lifecycle(
+  operation="complete",
+  task_id=[TASK_ID],
+  result="[1-2 sentence summary: what was done, files changed, tests status]"
+)
+
+# Final summary comment
+mcp__commander__commander_comment(
+  operation="add",
+  task_id=[TASK_ID],
+  type="info",
+  agent_name="pi",
+  message="COMPLETED: [detailed summary]. Files: [list]. Tests: [status]. Changes: [brief]"
+)
+```
+
+#### On Failure
+
+```
+mcp__commander__commander_comment(
+  operation="add",
+  task_id=[TASK_ID],
+  type="error",
+  agent_name="pi",
+  message="FAILING: [immediate reason]"
+)
+
+mcp__commander__commander_task_lifecycle(
+  operation="fail",
+  task_id=[TASK_ID],
+  error_message="[Clear, actionable error description]"
+)
+
+mcp__commander__commander_comment(
+  operation="add",
+  task_id=[TASK_ID],
+  type="handoff",
+  agent_name="pi",
+  message="FAILED: [root cause]. Attempted: [what tried]. Files touched: [partial changes]. Suggestion: [retry guidance]"
+)
+```
+
+#### If Task Needs Review
+
+```
+mcp__commander__commander_task(
+  operation="update",
+  task_id=[TASK_ID],
+  status="needs_review"
+)
+
+mcp__commander__commander_comment(
+  operation="add",
+  task_id=[TASK_ID],
+  type="handoff",
+  agent_name="pi",
+  message="NEEDS REVIEW: [what needs checking]. Work completed: [list]. Question: [specific question]. Recommendation: [suggestion]"
+)
+```
+
+---
+
+### Phase 6.5: Check for Related Tasks (Claim-Loop Continuation)
+
+**After completing the primary task, check if there are pending tasks to continue with.**
+
+This enables seamless multi-agent coordination where `/commander-task` can continue with related work.
+
+```
+// After primary task completion, check for more work
+pending_tasks = mcp__commander__commander_task(
+  operation="list",
+  status="pending",
+  working_directory="[CURRENT_WORKING_DIRECTORY]"
+)
+
+// Also check backlog
+backlog_tasks = mcp__commander__commander_task(
+  operation="list",
+  status="backlog",
+  working_directory="[CURRENT_WORKING_DIRECTORY]"
+)
+
+all_available = [...pending_tasks, ...backlog_tasks]
+```
+
+**If tasks found:**
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Primary task complete. Found X pending tasks in this directory. Continue executing?",
+    header: "Continue?",
+    options: [
+      { label: "Continue", description: "Enter claim-loop mode and execute remaining tasks" },
+      { label: "Done", description: "Stop here, leave tasks for later" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+**If user chooses "Continue":**
+
+Enter claim-loop mode (same pattern as `/commander-execute`):
+
+```
+CLAIM_LOOP:
+  WHILE TRUE:
+    // Find next available task
+    task = findAvailableTask(current_wave)
+
+    IF task is NULL:
+      // Check if wave is complete
+      IF isWaveComplete(current_wave):
+        IF hasMoreWaves():
+          current_wave++
+          CONTINUE
+        ELSE:
+          Log: "All tasks complete."
+          BREAK
+      ELSE:
+        // Other agents may be working
+        WAIT 30 seconds
+        CONTINUE
+
+    // Claim atomically
+    result = mcp__commander__commander_task_lifecycle(
+      operation="claim",
+      task_id=task.id,
+      agent_id="pi",
+      agent_name="pi"
+    )
+
+    IF result.success:
+      executeTask(task)  // Follow Phase 5 protocol
+    ELSE:
+      // Race condition - another agent claimed it
+      Log: "Task claimed by another agent, trying next"
+      CONTINUE
+```
+
+**Multi-Agent Awareness:**
+- Expect claim failures - other agents may be working in parallel
+- Do NOT re-claim tasks marked as 'working'
+- Trust the atomic claim mechanism
+
+---
+
+## Completion Report
+
+After execution, display:
+
+```
+## Task Complete
+
+### Summary
+Task #[ID]: [DESCRIPTION]
+Status: ✅ Completed
+
+### Implementation
+- **Files modified:**
+  - `file1.ts` (lines 45-52) - Added null check
+  - `file1.test.ts` (lines 89-98) - Added test
+
+- **Tests run:**
+  - `npm test -- UserService` - ✅ 12/12 passed
+
+### Success Criteria
+- [x] findById throws UserNotFoundError for invalid ID
+- [x] All existing tests pass
+- [x] New test passes
+
+### Comments Trail
+1. STARTED: Beginning implementation...
+2. STEP 1: Starting - Add null check...
+3. MODIFIED: UserService.ts lines 45-52...
+4. STEP 1: Complete - Null check added
+5. STEP 2: Starting - Add test...
+6. MODIFIED: UserService.test.ts lines 89-98...
+7. TESTING: Running tests...
+8. RESULT: 12/12 passed
+9. COMPLETED: Fixed null pointer bug
+
+### Next Steps
+- Consider adding similar checks to other services
+- Review error handling in downstream callers
+```
+
+---
+
+## Agent Roles Summary
+
+| Agent | Name | Role | When Used |
+|-------|------|------|-----------|
+| Main Agent | `pi` | Orchestrator + Executor | Always |
+| Structure Explorer | `scout` | Find codebase structure | Always |
+| Files Analyzer | `scout` | Analyze related files | Always |
+| Patterns Analyzer | `scout` | Find patterns to follow | Always |
+| Planning Agent | `planner` | Create implementation plan | Always |
+
+---
+
+## MANDATORY: Comment Protocol
+
+**You MUST add comments throughout execution. This is NOT optional.**
+
+### Minimum Comments Per Task
+
+| Phase | Minimum |
+|-------|---------|
+| Start | 1: approach and first step |
+| Per step | 2: starting + completed |
+| Per file read | 1: what was learned |
+| Per file modify | 1: what changed |
+| Per test run | 1: results |
+| Completion | 1: final summary |
+
+**Typical task: 10-20 comments minimum**
+
+### Why Comments Matter
+
+- Comments appear on Commander dashboard in real-time
+- Future agents can learn from your work
+- Humans can audit what happened
+- Knowledge is preserved for the project
+
+---
+
+## MCP Tools Reference
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__commander__commander_task` | Create task (operation: "create") |
+| `mcp__commander__commander_task_lifecycle` | Claim, complete, fail |
+| `mcp__commander__commander_comment` | Add progress comments |
+| `mcp__commander__commander_log` | Real-time dashboard logs |
+
+---
+
+## Usage Examples
+
+```bash
+# Bug fix with context
+/commander-task Fix the null pointer exception in UserService.findById
+
+# Feature with patterns
+/commander-task Add email validation to signup form following existing validation patterns
+
+# Refactoring
+/commander-task Refactor payment processing to use the new billing service
+
+# API endpoint
+/commander-task Implement the logout endpoint following existing auth patterns
+
+# Testing
+/commander-task Add unit tests for PaymentService.processRefund
+```
+
+---
+
+## Task Lifecycle
+
+```
+backlog → pending → working → completed/failed/needs_review
+```
+
+- **backlog → pending → working → completed** - Always follow this flow
+- **Start from backlog** - Tasks created by commander-plan live in backlog
+- **Move to pending before execution** - Approve tasks before they're worked on
+- **Comment at every transition** - Comments are mandatory for knowledge capture
+
+### Lifecycle for `/commander-task`
+
+Since `/commander-task` creates AND executes a single task, the lifecycle is compressed:
+
+1. **Create** → Task starts in `pending` (not backlog, since we're executing immediately)
+2. **Claim** → Move to `working` when execution begins
+3. **Complete/Fail** → Final state based on outcome
+
+### State Transitions
+
+| From | To | When | Required Action |
+|------|-----|------|-----------------|
+| (new) | pending | Task group created | `commander_task_group(operation="create")` |
+| pending | working | Agent claims task | `commander_task_lifecycle(operation="claim")` |
+| working | completed | Success | `commander_task_lifecycle(operation="complete")` |
+| working | failed | Error | `commander_task_lifecycle(operation="fail")` |
+| working | needs_review | Human input needed | `commander_task(operation="update", status="needs_review")` |
+
+---
+
+## Comparison with Other Commands
+
+| Command | Planning | Creates Tasks | Executes | Best For |
+|---------|----------|---------------|----------|----------|
+| `/commander-task` | ✅ scout+planner | ✅ Single | ✅ Direct | Single task with context |
+| `/commander-plan` | ✅ scout+planner | ✅ Multiple | ❌ No | Multi-task planning |
+| `/commander-execute` | ✅ Analysis | ❌ No | ✅ Batch | Running existing tasks |