44 KiB
44 KiB
description, argument-hint, allowed-tools
| description | argument-hint | allowed-tools | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Execute pending tasks from Commander with intelligent orchestration: dependency analysis, work type classification, and execution guards | [task IDs or 'all' or filter like 'pending' or 'backlog'] |
|
Commander Execute - Intelligent Task Orchestration with Execution Guards
This command executes existing tasks from Commander MCP using a planning agent architecture with sophisticated orchestration: dependency analysis, work type classification, commit checkpoints, and execution guards.
Planning Agent Architecture for Execution
┌─────────────────────────────────────────────────────────────────────┐
│ MAIN AGENT │
│ (Orchestrator Only) │
└─────────────────────────────────────────────────────────────────────┘
│
┌─────────┴─────────┐
│ Phase 0: Fetch │
│ Tasks from MCP │
└─────────┬─────────┘
│
┌─────────────────────┼─────────────────────┐
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ SCOUT AGENT 1 │ │ SCOUT AGENT 2 │ │ SCOUT AGENT 3 │
│ Dependency │ │ File Scope │ │ Work Type │
│ Analysis │ │ Analysis │ │ Classification│
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
│ │ │
└─────────────────┬─┴───────────────────┘
│
▼
┌─────────────────────┐
│ PLANNER AGENT │
│ (Execution Planner) │
│ Build Waves & │
│ Assign Agents │
└─────────┬───────────┘
│
▼
┌─────────────────────┐
│ MAIN AGENT │
│ Present Plan & │
│ Execute Waves │
└─────────────────────┘
Key Principle: The main agent does NO analysis itself - only fetches tasks and delegates.
Execution Agent Architecture: builder with Escalation to reviewer
All task execution uses builder agents with a structured escalation protocol:
┌─────────────────────────────────────────────────────────┐
│ TASK EXECUTION FLOW │
└─────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ builder (Primary) │
│ Attempts Task │
└───────────┬───────────┘
│
┌───────────────┼───────────────┐
│ │
▼ Success ▼ Stuck
┌──────────┐ ┌──────────────────┐
│ Complete │ │ Escalation │
│ Task │ │ → reviewer │
└──────────┘ └─────────┬────────┘
│
┌───────────┼───────────┐
│ │
▼ Success ▼ Failure
┌──────────┐ ┌──────────┐
│ Complete │ │ Fail Task│
│ Task │ │ (No more │
└──────────┘ │ escalation│
└──────────┘
Escalation Rules
- Primary Agent: All tasks start with
builderagent - Escalation: builder →
reviewer(when stuck)- builder must document attempts and blockers before escalating
- Maximum 1 escalation to reviewer per task
- Only builder can escalate to reviewer
- builder must attempt the task before escalating
- Total Limit: Maximum 1 escalation per task (builder → reviewer)
- Escalation Tracking: All escalations logged in task comments with reason
When to Escalate
- Complex architectural decisions beyond current model's capability
- Persistent errors that cannot be resolved after reasonable attempts
- Need for deep codebase understanding or pattern recognition
- Multi-step reasoning that exceeds current model's capacity
- Type system or compilation issues requiring advanced reasoning
CRITICAL: Execution Only - No Planning
Commander Execute does NOT create tasks. It only:
- Fetches existing tasks from Commander (backlog or pending)
- Uses planning agents to analyze dependencies and organize waves
- Moves tasks through lifecycle: backlog → pending → working → completed
- Orchestrates parallel agent execution
If you need to create new tasks:
- Use
/commander-plan [description]to analyze and create tasks - Commander-execute can DELEGATE to commander-plan when subtasks are discovered
- Never directly create tasks in commander-execute
⚠️ CRITICAL: NO AD-HOC TASKS — ALL tasks MUST belong to a group.
- NEVER use
commander_task(operation="create")to create standalone tasks - ALWAYS use
commander_task_group(operation="create")— even for a single task - Ad-hoc/ungrouped tasks break the Initiative Progress UI and wave tracking
Input
Task selection: $ARGUMENTS
Options:
allor empty - Execute all pending tasksbacklog- Move backlog tasks to pending, then execute- Task IDs (comma-separated) - Execute specific tasks:
123, 124, 125 pending- All tasks with pending statusworking- Resume tasks that were in progress
Workflow
Phase 0: Fetch Tasks & Classify (Main Agent)
The main agent fetches tasks and determines if planning is needed.
CRITICAL: Only execute tasks for the current working directory.
-
Fetch Tasks Based on $ARGUMENTS (Filtered by Current Directory)
Use
mcp__commander__commander_taskwithoperation: "list":- ALWAYS include
working_directoryparameter set to the current folder - If
backlog:status="backlog",working_directory="[CURRENT_DIR]" - If
pending:status="pending",working_directory="[CURRENT_DIR]" - If
working:status="working",working_directory="[CURRENT_DIR]" - If specific IDs: Use
operation: "get"with eachtask_id, then verifyworking_directorymatches - If
allor empty: Fetch all non-completed tasks withworking_directory="[CURRENT_DIR]"
If no tasks match the current directory:
- Display message: "No tasks found for this directory: [CURRENT_DIR]"
- List other directories that have pending tasks (if any)
- Exit without executing
- ALWAYS include
-
Classify Tasks: Pre-Planned vs Ad-Hoc
Check task fields to classify (NOT the context JSON):
Pre-Planned Tasks (from
/commander-plan):- Have
sourcefield equal to"commander-plan"(checktask.source, NOTtask.context) - OR have
groupIdset (belongs to a task group - most reliable indicator) - Have
dependencyOrderset - Context JSON contains
file_scope,assigned_agent,implementation_guide
Ad-Hoc Tasks (individual tasks):
- Have
sourcefield equal to"ad-hoc"or undefined - No
groupId(null or undefined) - Missing execution context
IMPORTANT: The
sourcefield is a dedicated column on the task, NOT inside the context JSON. Usetask.source === 'commander-plan'ortask.groupId !== undefinedfor classification. - Have
-
Decision Point: Skip or Analyze
IF all tasks are Pre-Planned (same group or ordered groups): → SKIP to Phase 2.5 (Direct Execution Planning) → Use existing context from tasks ELSE IF mixed (some Pre-Planned, some Ad-Hoc): → Only analyze Ad-Hoc tasks (Phase 1) → Merge with Pre-Planned context (Phase 2) ELSE IF all Ad-Hoc: → Run full analysis (Phase 1 + Phase 2)
Phase 1: Parallel Analysis (Ad-Hoc Tasks Only)
SKIP THIS PHASE if all tasks are Pre-Planned from /commander-plan.
Only run for Ad-Hoc tasks that lack execution context.
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: Dependency Analyzer
Use the Task tool with:
- subagent_type: "Explore"
- model: "scout"
- prompt: |
## Dependency Analysis for Commander Tasks
**Tasks to Analyze:**
[INSERT TASK LIST WITH DESCRIPTIONS]
**Your Mission:** Analyze task dependencies and build execution order.
**Analysis Tasks:**
1. Parse each task description for dependency keywords:
- "after", "depends on", "requires", "blocks", "must complete before"
- Explicit IDs: "Task #123", "#456", "task 789"
2. Build dependency map: `{ taskA: [taskB, taskC] }` means A depends on B and C
3. Detect circular dependencies
4. Perform topological sort for execution order
5. Group independent tasks into waves
**Return Format (JSON):**
```json
{
"dependency_map": {
"task_123": [],
"task_124": ["task_123"],
"task_125": ["task_123", "task_124"]
},
"waves": {
"wave_1": ["task_123"],
"wave_2": ["task_124"],
"wave_3": ["task_125"]
},
"circular_dependencies": [],
"execution_order": ["task_123", "task_124", "task_125"],
"analysis_notes": ["...", "..."]
}
```
Agent 2: File Scope Analyzer
Use the Task tool with:
- subagent_type: "Explore"
- model: "scout"
- prompt: |
## File Scope Analysis for Commander Tasks
**Tasks to Analyze:**
[INSERT TASK LIST WITH DESCRIPTIONS AND CONTEXT]
**Your Mission:** Determine file scope for each task (for execution guards).
**Analysis Tasks:**
1. Parse task descriptions for scope keywords:
- "modifies:", "affects:", "scope:", "files:", "updates:"
- File paths mentioned: "src/auth/*.ts", "src/models/user.ts"
2. Extract file patterns from task context metadata
3. Identify files that SHOULD be modified (whitelist)
4. Identify files that MUST NOT be modified
5. Map dependencies and services used
**Return Format (JSON):**
```json
{
"task_scopes": {
"task_123": {
"allowed_files": ["src/models/user.ts", "src/types/user.ts"],
"may_also_touch": ["src/utils/validation.ts"],
"must_not_touch": ["frontend/*", "tests/*"],
"services_used": ["database", "auth"]
}
},
"scope_conflicts": [],
"notes": ["...", "..."]
}
```
Agent 3: Work Type Classifier
Use the Task tool with:
- subagent_type: "Explore"
- model: "scout"
- prompt: |
## Work Type Classification for Commander Tasks
**Tasks to Analyze:**
[INSERT TASK LIST WITH DESCRIPTIONS]
**Your Mission:** Classify each task by work type and complexity (for escalation likelihood estimation).
**Classification Keywords:**
| Work Type | Keywords |
|-----------|----------|
| Backend | api, database, service, auth, business logic, endpoint, schema |
| Frontend | ui, component, styling, state, form, button, page |
| Testing | test, unit, integration, e2e, coverage, spec |
| Documentation | doc, readme, comment, guide, api docs |
| DevOps | ci, cd, deployment, infra, config, docker, k8s |
| Refactoring | refactor, cleanup, optimize, improve, simplify |
**Note:** All tasks are executed by builder agents with escalation capability.
**Return Format (JSON):**
```json
{
"task_classifications": {
"task_123": {
"work_type": "backend",
"keywords_matched": ["api", "endpoint"],
"complexity": "medium"
}
},
"work_type_summary": {
"backend": 3,
"frontend": 2,
"testing": 1
},
"complexity_distribution": {
"low": 4,
"medium": 2,
"high": 0
}
}
```
Phase 2: Execution Planning (planner Subagent)
After ALL scout agents return, spawn planner to create the execution plan.
Use the Task tool with:
- subagent_type: "Plan"
- model: "planner"
- prompt: |
## Create Execution Plan for Commander Tasks
**Tasks to Execute:**
[INSERT TASK LIST]
**Analysis Results:**
### Dependency Analysis:
[INSERT DEPENDENCY AGENT RESULTS]
### File Scope Analysis:
[INSERT SCOPE AGENT RESULTS]
### Work Type Classification:
[INSERT CLASSIFIER AGENT RESULTS]
---
**Your Mission:** Create a comprehensive execution plan with waves, agent assignments, and guards.
**Planning Tasks:**
1. **Validate Waves**
- Verify dependency ordering is correct
- Ensure no circular dependencies
- Group parallel tasks within each wave
2. **Assign Execution Strategy**
- All tasks execute with builder agents
- Escalation protocol available (scout → builder → reviewer)
- Consider task complexity for escalation likelihood
3. **Configure Guards**
- Set file scope guards for each task
- Define commit checkpoint after each wave
- Establish scope violation rules
4. **Estimate Execution**
- Order tasks by priority within waves
- Identify potential bottlenecks
- Note tasks that may need human review
**Return Format (JSON):**
```json
{
"execution_plan": {
"total_tasks": 10,
"total_waves": 3,
"waves": [
{
"wave_number": 1,
"tasks": [
{
"task_id": 123,
"description": "...",
"work_type": "backend",
"execution_agent": "builder",
"priority": 1,
"file_scope": {
"allowed": ["src/models/user.ts"],
"forbidden": ["frontend/*"]
},
"dependencies": []
}
],
"parallel_groups": [
{"group": "backend", "task_ids": [123, 124]},
{"group": "testing", "task_ids": [125]}
]
}
],
"commit_checkpoints": ["after_wave_1", "after_wave_2", "after_wave_3"],
"guard_rules": {
"scope_violation": "block_task",
"dependency_violation": "block_wave"
}
},
"execution_strategy": {
"primary_agent": "builder",
"escalation_available": true,
"task_distribution": {
"builder": [123, 124, 125, 126, 127, 128]
}
},
"risks": ["...", "..."],
"recommendations": ["...", "..."]
}
```
Phase 2.5: Direct Execution Plan (Pre-Planned Tasks)
USE THIS PHASE when all tasks are Pre-Planned from /commander-plan.
Skip Phase 1 and Phase 2 entirely - the context already exists!
-
Extract Execution Context from Tasks
For each Pre-Planned task, the task has:
description: Nicely formatted markdown (for UI display)task_prompt: CodeRabbit-style technical prompt (for agent execution)context: JSON with full analysis data
The context JSON contains:
{ "source": "commander-plan", "wave": 1, "dependency_order": 0, "work_type": "backend", "execution_agent": "builder", "escalation_protocol": "builder → reviewer (escalation)", "file_scope": { "allowed": ["src/models/user.ts"], "forbidden": ["frontend/*"] }, "implementation_guide": "## Steps\n1. ...", "analysis_context": { "architecture": "...", "patterns": "...", "dependencies": ["..."] } } -
Build Execution Plan from Context
- Group tasks by
dependency_order(0 = Wave 1, 1 = Wave 2, etc.) - Tasks with same
dependency_ordercan run in parallel - All tasks execute with builder (escalation available)
- Use
file_scopefrom context for guards - Use
task_prompt(notdescription) when passing to agents - Use
implementation_guidefrom context for additional instructions
- Group tasks by
-
Construct Execution Plan Object
{ "execution_plan": { "source": "pre-planned", "total_tasks": [count], "total_waves": [max dependency_order + 1], "waves": [ { "wave_number": 1, "dependency_order": 0, "tasks": [/* tasks where dependency_order === 0 */], "parallel_groups": [/* group by work_type */] } ], "planning_skipped": true, "reason": "Tasks created by /commander-plan with full context" } } -
Proceed directly to Phase 3 (Present Execution Plan)
Phase 3: Present Execution Plan (Main Agent)
Display the execution plan to the user.
For Pre-Planned Tasks (Phase 2.5), show simplified header:
## Execution Plan (Pre-Planned)
⚡ **Planning Skipped** - Tasks from `/commander-plan` with full context
### Summary
- Total tasks: X
- Waves: Y (from dependency_order)
- Source: commander-plan
- Execution: builder (with escalation available)
---
For Ad-Hoc/Mixed Tasks (Phase 1+2), show standard header:
## Execution Plan
### Summary
- Total tasks: X
- Waves: Y
- Execution: builder (with escalation: reviewer → planner)
---
### Wave 1 (Foundation - Independent)
**Backend Group (parallel)**
- [123] Implement user model → builder
Scope: src/models/user.ts, src/types/user.ts
- [124] Create database schema → builder
Scope: db/migrations/*, db/schema.ts
**Testing Group (parallel)**
- [125] Add unit tests for auth → builder
Scope: tests/auth.test.ts
---
### Wave 2 (Implementation - depends on Wave 1)
**Frontend Group (parallel)**
- [126] Create login form → builder
Scope: frontend/pages/login.tsx
- [127] Add password reset UI → builder
Scope: frontend/components/PasswordReset.tsx
---
### Execution Guards
- File scope validation: ENABLED (BLOCKING)
- Commit checkpoints: After each wave
- Scope violations will BLOCK task completion
---
### Risks
1. [risk 1]
2. [risk 2]
Phase 4: Approval Gate
Use AskUserQuestion tool to present options:
AskUserQuestion({
questions: [{
question: "Ready to execute X tasks across Y waves. How would you like to proceed?",
header: "Execute Tasks",
options: [
{ label: "Execute All", description: "Begin orchestrated execution of all waves" },
{ label: "Wave 1 Only", description: "Start with foundation tasks first" },
{ label: "Modify Plan", description: "Adjust dependencies or execution guards" },
{ label: "Cancel", description: "Don't execute, keep tasks in backlog" }
],
multiSelect: false
}]
})
Wait for user response before proceeding to Phase 5.
Phase 5: Continuous Claim-Loop Execution (On Approval)
Execute tasks using a continuous claim-loop pattern. Each agent claims ONE task at a time, works on it, then claims the next. This supports multi-agent environments where multiple Claude instances may run in parallel.
Key Principles:
- Atomic claiming: Use
commander_task_lifecycle(operation="claim")which prevents race conditions - Wave boundaries: Complete Wave N before starting Wave N+1
- No pre-assignment: Tasks are NOT pre-assigned - agents claim from the available pool
- Self-termination: Loop ends when no tasks remain and all waves complete
- Multi-agent aware: Assume other agents may be working in parallel
5.1 Claim-Loop Algorithm
┌─────────────────────────────────────────────────────────────────────┐
│ CLAIM-LOOP EXECUTION FLOW │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────┐
│ 1. Get Group Progress │
│ (current wave status) │
└───────────────┬───────────────┘
│
▼
┌───────────────────────────────┐
│ 2. Find Available Task │
│ in Current Wave │
│ (status=pending|backlog, │
│ dependencyOrder=N) │
└───────────────┬───────────────┘
│
┌───────────────┴───────────────┐
│ │
▼ Found ▼ Not Found
┌────────────────┐ ┌────────────────────────┐
│ 3. Claim Task │ │ 4. Check Wave Complete │
│ Atomically │ │ All tasks completed?│
└───────┬────────┘ └───────────┬────────────┘
│ │
┌───────┴───────┐ ┌───────────┴───────────┐
│ │ │ │
▼ Success ▼ Failed ▼ Yes ▼ No
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ 5. Work │ │ Retry │ │ 6. Next │ │ 7. Wait │
│ on Task │ │ another │ │ Wave? │ │ for tasks│
└────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │ │
│ │ │ │
▼ │ ┌────┴────┐ │
┌──────────┐ │ │ │ │
│ Complete │ │ ▼ Yes ▼ No │
│ or Fail │ │ ┌───────┐ ┌────────┐ │
└────┬─────┘ │ │Start │ │ 8. ALL │ │
│ │ │Wave │ │ DONE │ │
│ │ │N+1 │ │ EXIT │ │
└─────────────┴───┴───────┴───┴────────┴─────────┘
│
(loop back to step 2)
Critical: This loop runs continuously until ALL waves are complete.
5.2 Wave Completion Checking
Before claiming from a new wave, verify the previous wave is 100% complete.
FUNCTION: canStartWave(groupId, waveNumber)
1. Get group progress:
mcp__commander__commander_task_group(
operation="get",
group_id=[GROUP_ID]
)
2. Check wave_status from response:
- Find wave N-1 in wave_status array
- If wave N-1 exists:
- Return TRUE if is_complete === true
- Return FALSE otherwise
- If wave N-1 does not exist (waveNumber === 0):
- Return TRUE (Wave 1 can always start)
Wave Transition Logic:
IF current_wave tasks exhausted (none pending/backlog):
1. Check if current_wave is complete:
- All tasks in current wave have status 'completed' or 'failed'
2. IF complete AND more waves exist:
- Log: "Wave {N} complete. Starting Wave {N+1}"
- Update group: completed_waves = N
- Trigger commit checkpoint
- Move to next wave (increment current_wave)
3. IF NOT complete:
- Some tasks still 'working' by other agents
- Wait 30 seconds, re-check
4. IF no more waves:
- Mark group complete
- EXIT loop
5.3 Main Claim-Loop Implementation
Each executing agent runs this loop continuously:
INITIALIZE:
current_wave = 0
group_id = [GROUP_ID from task group]
working_directory = [CURRENT_WORKING_DIRECTORY]
max_consecutive_failures = 5
consecutive_failures = 0
MAIN_LOOP:
WHILE TRUE:
// Step 1: Find available task in current wave
available_task = findAvailableTask(group_id, current_wave, working_directory)
IF available_task is NULL:
// No tasks available in current wave
// Check if wave is complete
wave_complete = isWaveComplete(group_id, current_wave)
IF wave_complete:
// Commit checkpoint for this wave
commitWaveCheckpoint(current_wave)
// Update group progress
mcp__commander__commander_task_group(
operation="update",
group_id=group_id,
completed_waves=current_wave + 1
)
// Check if more waves exist
IF hasMoreWaves(group_id, current_wave):
current_wave = current_wave + 1
Log: "Moving to Wave {current_wave + 1}"
consecutive_failures = 0
CONTINUE // Try to find task in next wave
ELSE:
// All waves complete
mcp__commander__commander_task_group(
operation="update",
group_id=group_id,
overall_status="completed"
)
Log: "All waves complete. Exiting."
BREAK // Exit main loop
ELSE:
// Wave not complete - other agents still working
Log: "Waiting for Wave {current_wave + 1} tasks to complete..."
WAIT 30 seconds
CONTINUE
// Step 2: Attempt to claim the task
claim_result = mcp__commander__commander_task_lifecycle(
operation="claim",
task_id=available_task.id,
working_directory=working_directory,
agent_id="builder",
agent_name="builder"
)
IF claim_result.success:
consecutive_failures = 0
// Step 3: Execute the task (see 5.5 for full protocol)
executeTask(claim_result.task)
// Loop continues to claim next task
CONTINUE
ELSE:
// Claim failed (race condition - another agent claimed it)
consecutive_failures = consecutive_failures + 1
Log: "[INFO] Task {available_task.id} already claimed by another agent"
IF consecutive_failures >= max_consecutive_failures:
Log: "Multiple claim failures - refreshing task list..."
consecutive_failures = 0
WAIT 5 seconds
CONTINUE // Try to find another task
5.4 Helper Functions
findAvailableTask(groupId, waveNumber, workingDirectory):
1. List tasks in group:
mcp__commander__commander_task_group(
operation="list",
group_id=groupId
)
2. Filter tasks where:
- dependencyOrder === waveNumber
- status === 'pending' OR status === 'backlog'
- workingDirectory matches (if task has working_directory set)
3. Sort by priority (lower number = higher priority), then createdAt (older first)
4. Return first matching task, or NULL if none found
isWaveComplete(groupId, waveNumber):
1. Get group progress:
progress = mcp__commander__commander_task_group(
operation="get",
group_id=groupId
)
2. Find wave in wave_status:
wave_info = progress.wave_status.find(w => w.wave === waveNumber)
3. IF wave_info exists:
RETURN wave_info.is_complete
4. ELSE:
// Calculate manually
tasks = getAllTasksInWave(groupId, waveNumber)
RETURN tasks.every(t => t.status === 'completed' || t.status === 'failed')
hasMoreWaves(groupId, currentWave):
progress = mcp__commander__commander_task_group(
operation="get",
group_id=groupId
)
RETURN currentWave + 1 < progress.total_waves
5.5 Task Agent Execution Instructions
When spawning a Task agent for the claim-loop, use this prompt:
Use the Task tool with:
- subagent_type: "Code"
- model: "mercury-2"
- prompt: |
## CRITICAL: Commander MCP Protocol - Claim-Loop Execution
You are a **builder agent** executing tasks in a **claim-loop pattern**.
### Your Execution Loop
You will:
1. **Claim ONE task** from the available pool
2. **Work on that task** following all protocols
3. **Complete or fail the task**
4. **Loop back** to claim the next task
5. **Continue** until no more tasks available in the current wave
### Working Directory
Your working directory: [WORKING_DIRECTORY]
ONLY claim tasks that match this directory.
### Group Context
Group ID: [GROUP_ID]
Current Wave: [CURRENT_WAVE]
Total Waves: [TOTAL_WAVES]
---
### You Are Part of a Team
You work independently, but other builder agents may be active in this project — possibly in the same claim-loop, possibly from a different terminal.
**Before your first claim, take a quick glance** — check your inbox for context:
```
mcp__commander__commander_mailbox(
operation="inbox",
agent_name="builder"
)
```
If there are messages with discoveries or context from other agents, use them.
**While you work, you have tools available if you need them:**
- **Share a discovery** (a pattern, a gotcha, a file location that would help other builders):
`mcp__commander__commander_mailbox(operation="send", from_agent="builder", to_agent="@all", body="Found: [discovery]", message_type="status", task_id=[TASK_ID])`
- **Ask for help** (stuck after 2+ real attempts — don't spin):
`mcp__commander__commander_mailbox(operation="send", from_agent="builder", to_agent="commander", body="Stuck on: [problem]", message_type="error", task_id=[TASK_ID])`
- **Request a helper** (need specialist work done while you continue):
`mcp__commander__commander_mailbox(operation="send", from_agent="builder", to_agent="commander", body="Need help with: [task]", message_type="question", task_id=[TASK_ID])`
None of these are required. Use them when they would actually help.
---
### Claim Protocol
**To find and claim a task:**
1. List available tasks:
mcp__commander__commander_task_group(
operation="list",
group_id=[GROUP_ID]
)
2. Find a task where:
- dependencyOrder === [CURRENT_WAVE]
- status === 'pending' OR 'backlog'
- working_directory matches yours
3. Claim the task:
mcp__commander__commander_task_lifecycle(
operation="claim",
task_id=[TASK_ID],
working_directory="[WORKING_DIRECTORY]",
agent_id="builder",
agent_name="builder"
)
4. IF claim succeeds: Work on the task
IF claim fails: Try another task (race condition is NORMAL)
---
### Task Execution Protocol
**After successful claim:**
**1. ADD START COMMENT:**
mcp__commander__commander_comment(
operation="add",
task_id=[TASK_ID],
type="progress",
agent_name="builder",
message="STARTED: [approach]. Scope: [files]. Escalations remaining: 2"
)
**2. WORK WITH CONSTANT COMMENTS (MANDATORY - EVERY STEP):**
You MUST add a comment BEFORE and AFTER every operation. This is not optional.
| Operation | Before Comment | After Comment |
|-----------|----------------|---------------|
| Reading file | `ANALYZING: [file] - [goal]` | `FOUND: [discovery]` |
| Making edit | `PLANNING: [file:lines] - [change]` | `MODIFIED: [file:lines] - [summary]` |
| Running test | `TESTING: [test] - [expected]` | `RESULT: [pass/fail] - [details]` |
| Decision | `DECISION: [choice] because [reason]` | - |
**Use mcp__commander__commander_comment for EVERY comment:**
```
mcp__commander__commander_comment(
operation="add",
task_id=[TASK_ID],
type="progress",
agent_name="builder",
message="[PREFIX]: [details]"
)
```
**Do NOT batch comments. Comment in real-time as you work.**
**This creates the audit trail for debugging and handoffs.**
**3. ON COMPLETION:**
mcp__commander__commander_task_lifecycle(
operation="complete",
task_id=[TASK_ID],
result="[summary]"
)
mcp__commander__commander_comment(
operation="add",
task_id=[TASK_ID],
type="info",
agent_name="builder",
message="COMPLETED: [summary]. Files: [list]. Escalations used: [0/1/2]"
)
**4. ON FAILURE:**
mcp__commander__commander_comment(
operation="add",
task_id=[TASK_ID],
type="error",
agent_name="builder",
message="FAILED: [reason]. Attempted: [approaches]. Blocker: [what stopped progress]"
)
mcp__commander__commander_task_lifecycle(
operation="fail",
task_id=[TASK_ID],
error_message="[reason]"
)
**5. AFTER TASK COMPLETE - LOOP BACK:**
After completing or failing a task, IMMEDIATELY loop back to claim the next one:
```
// Task just completed
mcp__commander__commander_comment(
operation="add",
task_id=[COMPLETED_TASK_ID],
type="info",
agent_name="builder",
message="Task complete. Checking for next available task..."
)
// Find and claim next task in current wave
available_tasks = mcp__commander__commander_task_group(
operation="list",
group_id=[GROUP_ID]
)
// Filter for pending/backlog in current wave
next_task = available_tasks.filter(
t => t.status in ['pending', 'backlog'] &&
t.dependencyOrder === current_wave
)[0]
IF next_task:
// Claim and continue
GOTO: Claim Protocol step 3
ELSE:
// Check if wave is complete
IF all_tasks_in_wave_completed:
Log: "Wave complete. Waiting for main agent to advance."
ELSE:
Log: "No tasks available. Other agents may be working. Waiting..."
WAIT 30 seconds
RETRY
```
---
### Multi-Agent Awareness
**You are NOT alone.** Other agents may be working in parallel:
- **Expect claim failures** - Another agent got it first. This is NORMAL.
- **Do NOT re-claim** tasks you see as 'working' - they belong to other agents
- **Trust the atomic claim** mechanism - no coordination needed
- **Race conditions are healthy** - they mean the system is working
**When claim fails:**
```
mcp__commander__commander_comment(
operation="add",
task_id=0,
type="info",
agent_name="builder",
message="CLAIM_FAILED: Task [ID] already claimed. Trying next available."
)
// Immediately try the next task - don't wait
```
---
### Escalation Protocol (Maximum 1 escalation per task)
**You are `builder`. If you encounter blockers:**
1. **Escalation (builder → reviewer):**
- If stuck after reasonable attempts, escalate to `reviewer`
- Use Task tool with `model: "reviewer"` and include:
- What you've tried
- The specific blocker
- Current state of the code
- Add comment: `ESCALATION: Escalating to reviewer - [reason]`
2. **Escalation Limits:**
- Maximum 1 escalation per task (builder → reviewer)
- After reviewer, no further escalation available — task fails if reviewer can't resolve
**Escalation Criteria:**
- Complex architectural decisions beyond your capability
- Persistent errors you cannot resolve
- Need for deep codebase understanding you lack
---
### Loop Termination
**Stop claiming when:**
- No pending/backlog tasks in current wave AND wave is complete
- Main agent will handle wave transition and commit checkpoint
- When all waves complete, main agent will signal completion
**Do NOT exit prematurely:**
- If no tasks available but wave incomplete, WAIT and retry
- Other agents may be completing tasks that unblock you
Escalation Agent Instructions (for reference):
When reviewer receives an escalated task, it follows the same protocol above with agent_name="reviewer" and continues the claim-loop after completion.
5.6 Race Condition Handling
Expected behavior: In multi-agent environments, claim failures are NORMAL.
When claim fails:
- Log the failure (not an error, just info)
- Immediately try the next available task
- Do NOT retry the same task (another agent has it)
- Track consecutive failures to detect issues
Consecutive failure handling:
IF consecutive_failures >= 5:
Log: "Multiple claim failures - refreshing task list..."
WAIT 5 seconds
Reset consecutive_failures = 0
CONTINUE
IF consecutive_failures >= 10:
Log: "[WARN] Many consecutive failures - checking group status"
Check if wave is complete
IF complete: Move to next wave
ELSE: Wait for other agents to finish
Phase 6: Commit Checkpoint (After Each Wave)
-
Check for Changes
git status --porcelain -
Validate File Scope Compliance For each completed task:
- Read declared scope from plan
- Check actual files modified with
git diff - Flag violations
-
Create Wave Commit (if no violations)
git add . git commit -m "[commander-execute] Wave N complete Completed tasks: - Task [ID]: [Title] (Work type: [TYPE]) Wave N summary: - Total: [COUNT] tasks - All scope validations passed" -
Block on Violations If scope violation detected:
- Report violation to user
- Do NOT commit
- Ask for resolution before proceeding
-
Update Group Progress (after wave completes) After ALL tasks in a wave complete successfully:
// Get current group progress mcp__commander__commander_task_group( operation="get", group_id=[GROUP_ID] ) // Update completed waves count mcp__commander__commander_task_group( operation="update", group_id=[GROUP_ID], completed_waves=[CURRENT_COMPLETED + 1], overall_status="in_progress" )When ALL waves complete (completed_waves === total_waves):
mcp__commander__commander_task_group( operation="update", group_id=[GROUP_ID], overall_status="completed" )Track Initiative Start: When first task starts (first wave begins), update status:
mcp__commander__commander_task_group( operation="update", group_id=[GROUP_ID], overall_status="in_progress" )
Phase 7: Progress Display
## Execution Status (Live - Claim-Loop Mode)
Last updated: [timestamp]
Mode: Continuous Claim-Loop (Multi-Agent Aware)
### Initiative Progress
[initiative_summary from group]
████████████░░░░░░░░ 67% (Wave 2 of 3)
### Wave 2 Status
- Total tasks: 6
- Completed: 3 ✅
- Working: 2 🔵 (claimed by agents)
- Pending: 1 ⏳ (available for claiming)
### Active Agents
🔵 Agent executing claim-loop in Wave 2
- Last claimed: Task 124 (2 min ago)
- Tasks completed this session: 3
### Recent Activity
[124] builder: "CLAIMED: Starting implementation"
[125] builder: "COMPLETED: Added validation logic"
[123] builder: "CLAIM_FAILED: Task already claimed, trying next"
### Completed Tasks
✅ Task 120: Setup structure (Wave 1)
✅ Task 121: Configure database (Wave 1)
✅ Task 125: Add validation (Wave 2)
### Wave Summary
- Wave 1: ✅ Complete (4/4) - Committed: abc1234
- Wave 2: 🔵 In Progress (3/6)
- Wave 3: ⏳ Blocked (waiting for Wave 2)
Phase 8: Completion Report
## Execution Complete
### Summary
- Total: 10 tasks
- Successful: 9 ✅
- Failed: 1 ⚠️ (scope violation)
### Wave Breakdown
| Wave | Tasks | Success | Work Types |
|------|-------|---------|------------|
| 1 | 4 | 4/4 ✅ | Backend, Testing |
| 2 | 3 | 3/3 ✅ | Frontend, Docs |
| 3 | 3 | 2/3 ⚠️ | Refactoring |
### Scope Validation
✅ Wave 1: All within scope
✅ Wave 2: All within scope
⚠️ Wave 3: Task 127 modified unauthorized file
### Commits Created
- Wave 1: `abc1234` - Wave 1 complete (4 tasks)
- Wave 2: `def5678` - Wave 2 complete (3 tasks)
- Wave 3: Not committed (violation)
### Failed Tasks
- **Task 127**: SCOPE VIOLATION
- Modified: src/utils/logging.ts (NOT in scope)
- Recommendation: Expand scope or revert
### Next Steps
1. Investigate Task 127 scope violation
2. Run full test suite
3. Review agent insights
Agent Roles Summary
| Agent | Name | Role | When Used |
|---|---|---|---|
| Main Agent | pi |
Orchestrator, fetch & classify tasks | Always |
| Dependency Analyzer | scout |
Parse dependencies, build waves | Ad-Hoc tasks only |
| File Scope Analyzer | scout |
Determine file guards | Ad-Hoc tasks only |
| Work Type Classifier | scout |
Classify tasks by work type | Ad-Hoc tasks only |
| Execution Planner | planner |
Synthesize into execution plan | Ad-Hoc tasks only |
| Execution Agent (Primary) | builder |
Execute individual tasks | All tasks |
| Escalation Agent | reviewer |
Assist when builder is stuck | On escalation |
Escalation Protocol
builder (Primary)
↓ (if stuck)
reviewer (Escalation — final level)
Rules:
- Maximum 1 escalation per task (builder → reviewer)
- Only builder can escalate to reviewer
- Each escalation must document attempts and blockers
- Escalations tracked in task comments
Planning Skip Logic
Pre-Planned Tasks (from /commander-plan):
→ Phase 0 (fetch) → Phase 2.5 (extract context) → Phase 3+ (execute)
→ Saves 4 agent invocations per execution
Ad-Hoc Tasks:
→ Phase 0 (fetch) → Phase 1 (analyze) → Phase 2 (plan) → Phase 3+ (execute)
→ Full analysis needed
Mixed Tasks:
→ Phase 0 (fetch) → Phase 1 (analyze Ad-Hoc only) → Phase 2 (merge) → Phase 3+ (execute)
→ Partial analysis, merge with Pre-Planned context
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/list task groups |
mcp__commander__commander_comment |
Add progress comments |
mcp__commander__commander_log |
Real-time dashboard updates |
Usage Examples
# Execute all pending tasks
/commander-execute
# Execute specific tasks
/commander-execute 123, 124, 125
# Move backlog to pending and execute
/commander-execute backlog
# Resume in-progress work
/commander-execute working
# Execute all pending
/commander-execute pending