Initial: pi-skill — 68 skills, 43 extensions, 11 themes for Pi
This commit is contained in:
Kunthawat Greethong
863
commands/commander/task.md
Normal file
863
commands/commander/task.md
Normal file
@@ -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 |
|
||||
Reference in New Issue
Block a user