Execute tasks from TODO file - Generic task runner [/todo-task-run xxx]
Target TODO file: $ARGUMENTS
/todo-task-run <file_path>
file_path (required): Path to the TODO file to executeCRITICAL - Forward-Only Policy:
git reset, git restore, git revert, or any rollback commandsIMPORTANT: When completing a task, be sure to follow these steps:
- [ ] to - [x] to mark completionBefore starting any task, read and follow /key-guidelines
The /todo-task-run command is designed as a generic task runner - it takes a pre-existing TODO.md file and systematically executes ALL tasks defined within it until completion.
- [x]/todo-task-planning to convert requirements into a structured TODO.md before using this commandThis command guarantees:
/todo-task-planning): Analyze requirements → Create TODO.md with actionable tasks/todo-task-run TODO.md
⚠️ CRITICAL EXECUTION POLICY:
This command MUST execute ALL tasks in TODO.md sequentially, completing every task:
- [x]Session Continuation Rule: The session ONLY ends when ONE of these conditions is met:
- [x] (complete)This command expects a TODO.md file with the following format:
- [ ] for incomplete, - [x] for complete)When executing tasks, select the appropriate subagent based on task characteristics:
Implementation Tasks (implement, add, create, update features) → Use general-purpose subagent
Investigation Tasks (explore, investigate, research) → Use Explore subagent
CRITICAL: Before starting task execution, initialize memory system:
At the start of task execution, declare context accumulation variables:
TASK_CONTEXT = {} # Store context across tasks
MEMORY_FILES = {} # Track active memory file paths
INVESTIGATION_FINDINGS = [] # Accumulate investigation results
Before executing any task, check and load relevant existing memory files:
/docs/memory/planning/*.md - Contains task breakdown and strategy/docs/memory/explorations/*.md - Contains codebase analysis results/docs/memory/patterns/*.md - Contains reusable technical patterns/docs/memory/investigation-*.md - Contains previous problem-solving insightsAs tasks progress:
TASK_CONTEXT for use in subsequent tasks⚠️ CRITICAL: Sequential Execution Pattern Required
All tasks MUST be executed sequentially using the Task tool. Each task's results inform the next task's context.
// Sequential execution pattern
const task_1_result = await Task({ subagent_type: "[subagent_type]", ... });
// ⚠️ WAIT for task_1 to complete, THEN proceed
const task_2_result = await Task({ subagent_type: "[subagent_type]", ... });
// ⚠️ WAIT for task_2 to complete, THEN proceed
const task_3_result = await Task({ subagent_type: "[subagent_type]", ... });
// ❌ WRONG: Parallel execution (DO NOT DO THIS)
Promise.all([
Task({ subagent_type: "...", ... }),
Task({ subagent_type: "...", ... }) // Tasks must be sequential!
]);
Before executing each task, determine the appropriate subagent based on task characteristics (see "Subagent Classification Rules" section):
subagent_type: "general-purpose" (or omit parameter)subagent_type: "Explore"For each incomplete task (- [ ]) in TODO.md, execute using this pattern:
const task_N_result = await Task({
subagent_type: "[determined_subagent_type]", // From classification rules
description: "Execute task N: [task title from TODO.md]",
prompt: `
## 📋 Development Rules (MUST Follow)
### 🚨 Guardrails (Prohibited Actions)
**CRITICAL - Forward-Only Policy:**
- ❌ NEVER use \`git reset\`, \`git restore\`, \`git revert\`, or any rollback commands
- ✅ Always move forward: Fix errors with new changes, not by undoing previous ones
### Task Completion Procedure
1. Update checkbox immediately after task execution (\`- [ ]\` → \`- [x]\`)
2. Document related files (list names of created/modified files)
## Task Context
**Current Task:** [Full task description from TODO.md]
**Task Number:** N of [total_tasks]
**Target File:** ${$ARGUMENTS}
## Previous Task Results
${task_N-1_result?.summary || "This is the first task"}
${task_N-1_result?.files_modified || ""}
${task_N-1_result?.key_findings || ""}
## Memory Files
${MEMORY_FILES.planning || ""}
${MEMORY_FILES.exploration || ""}
${MEMORY_FILES.patterns || ""}
## Task-Specific Instructions
### For Investigation Tasks (Explore subagent):
1. Create investigation memory file at start:
- Path: \`/docs/memory/investigation-YYYY-MM-DD-{topic}.md\`
- Record findings immediately during investigation
- Save technical patterns in \`/docs/memory/patterns/\`
2. Document discoveries and insights for future reference
3. Include links to related documentation
### For Implementation Tasks (General-purpose subagent):
1. Follow existing code patterns discovered in exploration
2. Adhere to YAGNI principle (implement only what's necessary)
3. Reference memory files for context and technical patterns
4. Record implementation context in TODO.md task notes
## Required Steps After Task Completion
1. **Update TODO.md file** (${$ARGUMENTS})
- Change completed task: \`- [ ]\` → \`- [x]\`
- Add related file information below task
- Record implementation details and notes
- Format example:
\`\`\`markdown
- [x] Task title
- Files: \`path/to/file1.rb\`, \`path/to/file2.rb\`
- Notes: Brief description of implementation
\`\`\`
2. **Save investigation results** (for investigation tasks)
- Consolidate insights in investigation memory file
- Record technical discoveries for future reference
- Link to related documentation and patterns
3. **Update TODO.md with execution context**
- Add task notes: implementation details, decisions, learnings
- Record blockers with 🚧 marker if encountered
- Document context for next task in task description
4. **Report results**
- Summarize changes made
- List modified/created files with absolute paths
- Note any issues or blockers encountered
- Provide context for next task
5. **⚠️ MANDATORY: Check for remaining tasks**
- See "Execution Checkpoints" section (Lines 482-612) for detailed 3-step procedure
- Must re-read TODO.md, detect `- [ ]` pattern, and branch appropriately
## Expected Output Format
Return structured results for context accumulation:
\`\`\`typescript
{
summary: "Brief description of what was accomplished",
files_modified: ["absolute/path/to/file1", "absolute/path/to/file2"],
key_findings: "Important discoveries or decisions (for investigation tasks)",
blockers: "Any issues encountered (if applicable)",
context_for_next_task: "Information needed by subsequent tasks"
}
\`\`\`
`
});
Critical Pattern: Each task's results must be passed to the next task through the prompt parameter.
// Task 1
const task_1_result = await Task({
subagent_type: "Explore",
description: "Investigate codebase for feature X",
prompt: `[instructions]`
});
// Task 2 receives task_1_result in context
const task_2_result = await Task({
subagent_type: "general-purpose",
description: "Implement feature X based on investigation",
prompt: `
## Previous Task Results
${task_1_result.summary}
Files discovered: ${task_1_result.files_modified.join(', ')}
Key findings: ${task_1_result.key_findings}
[rest of task 2 instructions]
`
});
⚠️ MANDATORY: After each Task tool execution, verify success before proceeding:
const task_N_result = await Task({ ... });
// Verification gate
if (!task_N_result || task_N_result.blockers) {
// Handle error:
// 1. Mark task with 🚧 in TODO.md
// 2. Record blocker in TODO.md with context
// 3. Report to user with details
// 4. STOP execution until blocker is resolved
throw new Error(`Task N blocked: ${task_N_result.blockers}`);
}
// Verify expected outputs exist
if (!task_N_result.summary || !task_N_result.files_modified) {
// Task completed but didn't return expected format
// Log warning but continue if non-critical
}
// ✅ Verification passed, proceed to next task
const task_N+1_result = await Task({ ... });
When a task encounters an error or blocker:
CRITICAL - Forward-Only Error Recovery:
git reset, git restore, git revert to undo errorsError Recovery Steps:
Mark task status in TODO.md:
- [ ] 🚧 Task title (BLOCKED: reason for blockage)
Record blocker details in TODO.md:
- [ ] 🚧 Task title (BLOCKED: reason)
- 🚧 Blocker: [Detailed description]
- 🔧 Attempted: [What was tried]
- 📋 Next steps: [How to resolve]
- ⚠️ Recovery: Fix forward, not rollback
Report to user:
STOP execution:
After blocker resolution:
High-Level Flow Diagram:
╔═══════════════════════════════════════════════════════════════════════════╗
║ TASK EXECUTION LOOP FLOW ║
╚═══════════════════════════════════════════════════════════════════════════╝
START: Read TODO.md and identify first incomplete task
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ PHASE 1: TASK EXECUTION │
│ ───────────────────────── │
│ │
│ 1. Read TODO.md → identify next incomplete task (`- [ ]`) │
│ 2. Classify task → determine subagent_type │
│ 3. Execute Task tool with accumulated context │
│ 4. Verify completion (verification gate) │
│ 5. Update TODO.md status (`- [ ]` → `- [x]`) │
│ 6. Store task result for next task's context │
│ │
└────────────────────────────┬────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 🚨 PHASE 2: CONTINUATION CHECK PROCEDURE (MANDATORY GATE) │
│ ──────────────────────────────────────────────────────── │
│ │
│ Step 1: Re-read TODO.md from disk │
│ const todo_content = await Read({ file_path: $ARGUMENTS }) │
│ │
│ Step 2: Detect incomplete tasks │
│ const has_incomplete_tasks = todo_content.includes('- [ ]') │
│ │
│ Step 3: Branch Decision ──────────────┐ │
│ │ │
└─────────────────────────────────────────┼────────────────────────────────┘
│
┌─────────────────────┴────────────────────┐
│ │
▼ ▼
┌───────────────────────┐ ┌────────────────────────┐
│ has_incomplete_tasks │ │ has_incomplete_tasks │
│ === true │ │ === false │
└───────────────────────┘ └────────────────────────┘
│ │
│ │
▼ ▼
┌───────────────────────┐ ┌────────────────────────┐
│ PATH A: │ │ PATH B: │
│ CONTINUE LOOP │ │ FINAL COMPLETION │
│ │ │ │
│ ✅ Execute next task │ │ ✅ Verify ALL [x] │
│ via Task tool │ │ ✅ Add timestamp │
│ │ │ ✅ Generate report │
│ ❌ DO NOT proceed to │ │ ✅ End session │
│ Final Completion │ │ │
│ │ │ │
│ ❌ DO NOT end session│ │ 🎯 COMPLETE │
└───────────────────────┘ └────────────────────────┘
│ │
│ │
│ (loop back to PHASE 1) END
│
└──────────────┐
│
▼
Return to PHASE 1: Execute next task
Critical Decision Points:
Verification Gate (After each task): Did the task complete successfully?
🚧), report to user, STOPContinuation Check Gate (Mandatory after EACH task): Are there incomplete tasks?
- [ ] found) → PATH A: Continue to next task (loop back to PHASE 1)- [x]) → PATH B: Proceed to Final Completion ProcessLoop Termination Conditions:
- [x] → Final Completion ProcessRepeat the Task tool pattern for each incomplete task until:
- [x] (completed), OR🚧 marker (stop and report)Execution Flow:
- [ ])subagent_type- [ ] → - [x])- [ ]), IMMEDIATELY continue to next task (return to step 1)- [x]⚠️ MANDATORY CONTINUATION CHECK:
See "Execution Checkpoints" section (Lines 482-612) for the required 3-step procedure that MUST be executed after EACH task completion.
⚠️ CRITICAL: Execute After EVERY Task Completion
After each Task tool execution completes, you MUST execute this 3-step checkpoint procedure:
╔════════════════════════════════════════════════════════════════╗
║ 🎯 EXECUTION CHECKPOINT - POST-TASK VERIFICATION ║
║ ───────────────────────────────────────────────────────── ║
║ ║
║ Execute this 3-step procedure after EVERY task completion: ║
║ ║
║ ┌──────────────────────────────────────────────────────┐ ║
║ │ STEP 1: Re-read TODO.md from disk │ ║
║ │ ↓ │ ║
║ │ const todo = await Read({ file_path: ... }) │ ║
║ │ │ ║
║ │ Purpose: Get fresh state, not stale in-memory data │ ║
║ └──────────────────────────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ ┌──────────────────────────────────────────────────────┐ ║
║ │ STEP 2: Check for '- [ ]' pattern existence │ ║
║ │ ↓ │ ║
║ │ const has_incomplete = todo.includes('- [ ]') │ ║
║ │ │ ║
║ │ Purpose: Detect if ANY incomplete tasks remain │ ║
║ └──────────────────────────────────────────────────────┘ ║
║ │ ║
║ ▼ ║
║ ┌──────────────────────────────────────────────────────┐ ║
║ │ STEP 3: Branch decision based on detection result │ ║
║ │ │ ║
║ │ if (has_incomplete === true) { │ ║
║ │ → Continue to next task (loop back to PHASE 1) │ ║
║ │ → DO NOT end session │ ║
║ │ } else { │ ║
║ │ → Proceed to Final Completion Process │ ║
║ │ → Safe to end session after final steps │ ║
║ │ } │ ║
║ │ │ ║
║ │ Purpose: Prevent premature session termination │ ║
║ └──────────────────────────────────────────────────────┘ ║
║ ║
╚════════════════════════════════════════════════════════════════╝
Checkpoint Implementation Code:
// ════════════════════════════════════════════════════════════════
// EXECUTION CHECKPOINT - Execute after EVERY task completion
// ════════════════════════════════════════════════════════════════
// STEP 1: Re-read TODO.md from disk
const todo_content = await Read({ file_path: $ARGUMENTS });
// STEP 2: Check for '- [ ]' pattern existence
const has_incomplete_tasks = todo_content.includes('- [ ]');
// STEP 3: Branch decision
if (has_incomplete_tasks) {
// ✅ PATH A: At least one incomplete task exists
// → MUST continue to next task
// → CANNOT proceed to Final Completion Process
// → CANNOT end session
console.log('✅ Checkpoint: Incomplete tasks detected, continuing loop...');
// Return to PHASE 1: Execute next task
const next_task_result = await Task({
subagent_type: "[determined_type]",
description: "Execute next incomplete task",
prompt: `[task instructions with accumulated context]`
});
// After next task completes, return to this checkpoint (recursive loop)
} else {
// ✅ PATH B: NO incomplete tasks remain
// → All tasks are marked '- [x]'
// → Safe to proceed to Final Completion Process
// → Session can end after final steps
console.log('✅ Checkpoint: All tasks complete, proceeding to final steps...');
// Proceed to "Final Completion Process" section
}
Checkpoint Failure Indicators:
If you find yourself in any of these situations, the checkpoint was not executed correctly:
| ❌ Failure Indicator | ✅ Correct Action |
|---|---|
Ending session while - [ ] exists in TODO.md | Execute checkpoint → Detect incomplete tasks → Continue loop |
| Proceeding to Final Completion without reading TODO.md | Execute STEP 1: Re-read file from disk |
| Assuming all tasks done based on in-memory state | Execute STEP 2: Explicit pattern detection |
| Skipping checkpoint "because task seemed final" | ALWAYS execute checkpoint after EVERY task |
Visual Reminder - When to Execute:
Task Execution Timeline:
════════════════════════════════════════════════════════════════
Task N-1 Task N 🎯 CHECKPOINT Task N+1
│ │ │ │
│ │ │ │
▼ ▼ ▼ ▼
[Execute] → [Complete] → [3-Step Check] → [Continue/End]
[Update TODO] │
├─ Step 1: Read
├─ Step 2: Detect
└─ Step 3: Branch
│
├─ Found [ ] → Next Task
└─ All [x] → Final Steps
🚨 CRITICAL: Checkpoint executes AFTER TODO.md update, BEFORE next decision
Connection to Continuation Check Procedure:
This checkpoint procedure is the in-loop implementation of the "Continuation Check Procedure" section (Lines 614-701):
Both sections describe the same mandatory 3-step process from different perspectives. The checkpoint ensures continuous execution until completion.
⚠️ MANDATORY GATE: This procedure is the critical decision point between task execution and final completion.
After completing each task, you MUST execute this 3-step continuation check procedure:
Why this is mandatory:
Detection logic:
- [x])(See Lines 532-571 in "Execution Checkpoints" for implementation code)
┌─────────────────────────────────────────────────────┐
│ Continuation Check Decision Tree │
└─────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────┐
│ has_incomplete_tasks? │
└────────────────────────────────┘
/ \
/ \
YES NO
│ │
▼ ▼
┌──────────────────┐ ┌─────────────────────┐
│ ✅ Continue Loop │ │ ✅ Final Completion │
│ │ │ │
│ - Execute next │ │ - Verify ALL tasks │
│ task via Task │ │ are [x] │
│ tool │ │ - Add completion │
│ │ │ timestamp │
│ - DO NOT proceed │ │ - Generate final │
│ to Final │ │ report │
│ Completion │ │ │
│ │ │ - End session │
│ - DO NOT end │ │ │
│ session │ │ │
└──────────────────┘ └─────────────────────┘
│
│ (loop continues)
▼
Return to Step 1 after
next task completion
See Lines 532-571 in "Execution Checkpoints" section for complete implementation code with detailed comments.
⚠️ WARNING: Common Mistakes to Avoid:
| ❌ WRONG | ✅ CORRECT |
|---|---|
Proceeding to Final Completion while - [ ] exists | Always check TODO.md before final steps |
| Ending session with incomplete tasks | Continue loop until all - [x] |
| Assuming all tasks are done without checking | Explicit file read + pattern detection |
| Using stale in-memory state | Fresh Read() call every time |
Visual Reminder:
╔═══════════════════════════════════════════════════════════╗
║ 🚨 CRITICAL CHECKPOINT ║
║ ║
║ Before proceeding to Final Completion Process: ║
║ ║
║ ✅ Read TODO.md from disk ║
║ ✅ Check for '- [ ]' pattern ║
║ ✅ If found → Continue to next task ║
║ ✅ If NOT found → Proceed to Final Completion ║
║ ║
║ This gate prevents premature session termination ║
╚═══════════════════════════════════════════════════════════╝
When encountering errors or unexpected issues during task execution:
CRITICAL - Forward-Only Error Recovery:
git reset, git restore, git revert to undo errors/docs/memory/ for previous investigations on similar issues/docs/memory/patterns/
/docs/memory/patterns/╔═══════════════════════════════════════════════════════════════════════════╗
║ 🚨 CRITICAL PREREQUISITE CHECK ║
║ ║
║ This section is ONLY accessible after: ║
║ 1. Executing "Execution Checkpoints" 3-step procedure (Lines 482-612) ║
║ 2. Passing "Continuation Check Procedure" gate (Lines 614-701) ║
║ 3. Confirming PATH B (Final Completion) - NO '- [ ]' in TODO.md ║
║ ║
║ If '- [ ]' exists → Return to Task Execution Loop (PATH A) ║
║ Only proceed if ALL tasks are '- [x]' (PATH B confirmed) ║
╚═══════════════════════════════════════════════════════════════════════════╝
⚠️ MANDATORY VERIFICATION:
This section is ONLY accessible if the Continuation Check Procedure (Lines 614-701) returned PATH B (all tasks complete).
Before proceeding, verify:
- [x] (no - [ ] pattern exists)🚧 markers)(See Lines 532-571 in "Execution Checkpoints" for verification code template)
Required steps upon all tasks completion:
- [x])Final Report to User:
After completing all final steps, provide a comprehensive summary: