Custom Claude Code command for Automated phase-by-phase plan executor using Task tool with full tool access

auto-implement.md

description
Automated phase-by-phase plan executor using Task tool with full tool access

Auto-Implement Plan

You are executing an automated implementation workflow that runs each phase of a plan using the Task tool, which spawns agents with full tool access. Each phase agent can spawn parallel sub-agents for exploration, architecture, and review.

Arguments

PLAN_PATH: $ARGUMENTS

Workflow

Step 1: Validate Input

If no plan path was provided:

1. Check conversation context for any recently discussed/created plan files (look for paths like thoughts/*/plans/*.md or similar plan references)
2. Check for plan files in common locations: thoughts/shared/plans/, thoughts/plans/, docs/plans/
3. If a single plan is found, use it automatically
4. If multiple plans found, pick the most recently modified one
5. Only if NO plan can be inferred, ask:

I'll help you auto-implement a plan. Please provide:
- The path to your implementation plan (created by /hlyr:create_plan)
- Optionally, a starting phase number if resuming

Example: /auto-implement thoughts/shared/plans/2025-01-06-my-feature.md
Example: /auto-implement thoughts/shared/plans/2025-01-06-my-feature.md 3

Step 2: Parse Plan

1. Read the plan file fully - use the Read tool with no limit/offset
2. Extract phases - identify all ## Phase N: sections
3. Count total phases and note their titles

If the plan structure is invalid (no phases found), explain what's missing.

Step 3: Commit Research & Plan Documents

Before execution begins, ensure all research and plan documents are committed:

1. Check for uncommitted plan/research files:

   • The plan file itself
   • Any related research files in the same directory or thoughts/ directories
   • Any progress files from previous runs

2. If uncommitted files exist:

   # Stage only the relevant plan/research files (NEVER git add -A)
   git add [plan-file-path]
   git add [any related research files in thoughts/ or docs/]
   
   # Commit with descriptive message
   git commit -m "docs: add implementation plan for [feature-name]"

3. Skip if already committed - check with git status first

This ensures:

• Clean git history showing when implementation started
• Plan is versioned before any changes are made
• Easy rollback point if implementation needs to be reverted

Step 4: Show Preview & Start Immediately

Display a brief preview and immediately start execution (no confirmation needed):

## Auto-Implementation Starting

**Plan**: [plan file path]
**Total Phases**: [N]
**Starting From**: Phase [X]

### Phases to Execute:
- Phase 1: [Phase title]
- Phase 2: [Phase title]
...

Starting Phase 1 now...

NOTE: No user confirmation required. Execution begins immediately after showing the preview.

Step 5: Execute Phases

For EACH phase (starting from start_phase), spawn a Task with this prompt:

Use Task tool with subagent_type: "general-purpose"
Description: "Phase [N]: [Phase Title]"

Prompt:
---
You are implementing Phase [N] of [TOTAL] from an implementation plan.

## Full Plan Context
[Include the FULL plan file content - read without limit/offset]

## Previous Phase Summaries
[Include summaries from phases 1 to N-1 if resuming]

## YOUR CURRENT TASK: Phase [N]

[Include the extracted phase content]

---

## IMPLEMENTATION APPROACH

Follow the feature-dev pattern with parallel sub-agents when beneficial:

### 1. Exploration (if needed for complex phases)

If this phase involves modifying unfamiliar code, launch 2-3 code-explorer agents IN PARALLEL using ONE message with multiple Task calls:

Task(subagent_type="feature-dev:code-explorer", description="Explore [aspect 1]", prompt="...") Task(subagent_type="feature-dev:code-explorer", description="Explore [aspect 2]", prompt="...")

**CRITICAL**: All parallel Task calls MUST be in ONE message - never split them!

Each explorer should:
- Target a different aspect of the code
- Return a list of 5-10 key files to read
- Trace execution paths and identify patterns

After explorers complete, READ all files they identified to build deep understanding.

### 2. Architecture (if needed for significant changes)

If this phase requires architectural decisions, launch 2-3 code-architect agents IN PARALLEL:

Task(subagent_type="feature-dev:code-architect", description="Minimal approach", prompt="Design with minimal changes...") Task(subagent_type="feature-dev:code-architect", description="Clean approach", prompt="Design for maintainability...")

Review approaches, pick the best one, and proceed.

### 3. Implementation

Implement the changes:
- **Read files fully** before modifying (never use limit/offset)
- **Commit as you go** with clear messages (selective commits, never `git add -A`)
- **Update plan checkboxes** to `- [x]` as sections complete
- **Run verification commands** from Success Criteria

### 4. Review (after implementation)

Launch 2-3 code-reviewer agents IN PARALLEL to review your changes:

Task(subagent_type="feature-dev:code-reviewer", description="Review for bugs", prompt="Review for bugs and logic errors...") Task(subagent_type="feature-dev:code-reviewer", description="Review for conventions", prompt="Review for project conventions...")

Address any issues with confidence ≥ 80 before completing.

---

## CRITICAL RULES

1. **STOP BEFORE NEXT PHASE** - Do NOT proceed to the next phase
2. **COMMIT ALONG THE WAY** - Make selective commits as you complete logical units
3. **UPDATE PLAN CHECKBOXES** - Mark completed items with `- [x]`
4. **USE PARALLEL SUB-AGENTS** - When exploring/architecting/reviewing, spawn multiple agents IN ONE MESSAGE
5. **READ FILES FULLY** - Never use limit/offset parameters

---

## OUTPUT FORMAT

End your response with this exact format:

---

Phase [N] Summary

[3-5 sentence summary of what was implemented]

Status: [COMPLETE|FAILED|NEEDS_ATTENTION]

Commits: [list of commit hashes made]

Tests: [PASS|FAIL|PARTIAL]

Notes: [any important notes for next phase]

Manual Testing Instructions

[Brief numbered list of manual testing steps to verify this phase works]

1. [First test step]
2. [Second test step] ...

---

### Step 5b: Capture Summary & Commit Progress

After the Task completes:
1. Extract the phase summary from the Task output
2. Append it to the progress file: `[plan-parent-dir]/progress/[plan-name]-progress.md`
3. Note any issues or failures
4. **Commit the progress file update**:
   ```bash
   git add [progress-file-path]
   git commit -m "docs: update progress - Phase [N] complete"

This ensures:

• Progress is saved incrementally in git history
• Easy to see what was done in each phase
• Can resume from any point if interrupted

Step 5c: Run Manual Test Runner

If the phase has manual testing instructions, spawn:

Task(subagent_type="manual-test-runner", description="Test Phase [N]", prompt="
Execute these manual testing instructions from Phase [N]:

[Include the manual testing instructions from the phase summary]

Report results of each test step.
")

Step 5d: Check Status & Continue (Ralph-Style Retry)

After manual testing:

• If COMPLETE and tests pass: Continue to next phase
• If FAILED or tests fail: RETRY THE PHASE ONCE (Ralph Wiggum style)
  • Spawn another Task for the same phase with context about what failed
  • Include the failure details so the agent can fix the issues
  • After retry, continue to next phase regardless of outcome
• If NEEDS_ATTENTION: RETRY ONCE, then continue regardless

CRITICAL: Once execution starts on Phase 1, NEVER stop to ask the user. Keep going through all phases.

There is NO user confirmation step - execution begins immediately after showing the preview.

Step 6: Final Summary

After all phases complete (or on failure), output:

## Auto-Implementation Complete

### Execution Summary:
- Phases Executed: [X of Y]
- Overall Status: [SUCCESS|PARTIAL|FAILED]
- Total Commits: [list all commit hashes]

### Phase Results:
| Phase | Status | Commits | Tests |
|-------|--------|---------|-------|
| 1 | PASS | abc123 | PASS |
| 2 | PASS | def456 | PASS |
...

### Progress File:
`[path to progress file]`

### Next Steps:
1. Review progress file
2. Address any issues found
3. Create PR: `/hlyr:describe_pr`

Progress File Format

The progress file (progress/[plan-name]-progress.md) accumulates phase summaries:

---
plan: [plan file path]
started: [ISO timestamp]
status: in_progress
---

# Implementation Progress: [plan-name]

**Plan**: [plan file path]
**Started**: [timestamp]

---

## Phase 1

**Completed**: [timestamp]
**Status**: COMPLETE
**Commits**: abc123, def456
**Tests**: PASS

### Summary
[Summary from Task output]

### Sub-Agents Used
- 2x code-explorer (explored X and Y)
- 2x code-architect (designed approaches)
- 2x code-reviewer (reviewed changes)

### Manual Test Results
[Results from manual-test-runner]

---

## Phase 2
...

Resuming Interrupted Runs

If a starting phase > 1 is specified:

1. Check for existing progress file
2. Read summaries from phases 1 to N-1
3. Include those summaries in context for the current phase
4. Append new phase summaries to the existing progress file

Key Patterns Integrated

From feature-dev Plugin

Pattern	How It's Used
Parallel exploration	2-3 code-explorer agents before complex implementation
Read-after-explore	Agents identify files, parent reads them
Parallel architecture	2-3 code-architect agents for design decisions
Confidence-based review	code-reviewer agents filter to ≥80 confidence

From implement_plan

Pattern	How It's Used
Full file reading	Never use limit/offset parameters
Todo tracking	Track progress with TodoWrite
Checkbox updates	Mark - [x] as sections complete

From Ralph Wiggum

Pattern	How It's Used
Retry on failure	If phase fails, retry once before continuing
No stopping	Once started, NEVER stop to ask user
Keep going	Continue through all phases regardless of issues

Parallel Execution Rules

CRITICAL: When spawning multiple sub-agents:

• ALL Task calls MUST be in ONE message
• NEVER split parallel Task calls across messages
• Each agent can have different focus/prompt but run simultaneously

Example of correct parallel spawning:

// ONE message with multiple Task calls:
Task(subagent_type="feature-dev:code-explorer", description="Explore auth", prompt="...")
Task(subagent_type="feature-dev:code-explorer", description="Explore API", prompt="...")
Task(subagent_type="feature-dev:code-explorer", description="Explore UI", prompt="...")

Important Notes

• NEVER STOP once Phase 1 starts - there is NO confirmation step, execution begins immediately
• Retry on failure - if a phase fails, retry once (Ralph style) then continue regardless
• Each Task agent has full tool access (Read, Write, Edit, Bash, etc.)
• Task agents can spawn their own sub-agents for exploration/architecture/review
• Sub-agents (code-explorer, code-architect, code-reviewer) are read-only analyzers
• The manual-test-runner agent handles manual verification steps
• Progress is saved after each phase for resume capability
• Never use git add -A - always selective commits
• Never commit with "generated with" or "co-authored-by" details