Execute Plan

Execute Implementation Plan

I'll execute implementation plans from /write-plan in controlled batches with validation checkpoints.

Arguments: $ARGUMENTS - plan file path (defaults to IMPLEMENTATION_PLAN.md)

Execution Philosophy

Based on obra/superpowers methodology:

• Execute in small, testable batches
• Validate after each phase
• Git checkpoint between phases
• Rollback on critical failures
• Continuous integration with /test

Token Optimization

This skill uses aggressive optimization strategies to minimize token usage during plan execution:

1. Checkpoint-Based State Tracking (500 token savings)

Pattern: Maintain execution state file instead of re-parsing plan

• Create .execute-plan-state.json on first run with phase progress
• Cache: current phase, completed tasks, checkpoint hashes (5 min TTL)
• Read state file on subsequent runs (50 tokens vs 550 tokens full parse)
• Update incrementally as tasks complete
• Savings: 90% on repeat executions, most runs read cached state

2. Phase-by-Phase Progressive Execution (1,200 token savings)

Pattern: Execute one phase at a time, not entire plan

• Parse and execute only current incomplete phase
• Don't read or analyze completed phases (save 1,000+ tokens)
• Cache phase tasks in state file
• Next invocation continues from checkpoint
• Savings: 70% vs full plan execution, incremental progress

3. Bash-Based Plan Parsing (1,500 token savings)

Pattern: Use bash grep/awk instead of Task agents

• Extract phase info with grep/awk (200 tokens vs 1,700 Task agent)
• Parse task checkboxes with simple patterns
• Count completion with grep -c
• No Task tool needed for plan analysis
• Savings: 88% vs Task-based parsing

4. Early Exit for Completed Plans (95% savings)

Pattern: Detect completion and exit immediately

• Check if all tasks marked [x] (1 grep command, 50 tokens)
• Exit if no incomplete phases found
• Distribution: ~30% of runs are "check status" calls
• Savings: 50 vs 2,500 tokens for completed plan checks

5. Incremental Validation (800 token savings)

Pattern: Validate only changed components

• Run tests only after code changes (not on plan updates)
• Check git diff to determine if validation needed
• Skip build checks if no source changes
• Progressive validation: unit → integration → full
• Savings: 65% vs full validation every execution

6. Minimal Task Execution Guidance (600 token savings)

Pattern: Show next task only, not full instructions

• Display current task from state file (100 tokens)
• Don't repeat full methodology or examples
• User already knows workflow from previous phases
• Generate detailed guidance only on request
• Savings: 85% vs full workflow explanations

7. Sample-Based Progress Tracking (300 token savings)

Pattern: Show summary metrics, not full task lists

• Display counts: total/completed/remaining (3 numbers)
• Show only next 3 tasks, not all incomplete (save 250+ tokens)
• Use head -3 to limit output
• Full list available via grep on demand
• Savings: 75% vs complete task enumeration

8. Cached Checkpoint Hashes (200 token savings)

Pattern: Store git hashes in state file

• Cache checkpoint hash on creation
• Read from state for rollback (vs git log parsing)
• Track phase completion commits
• Savings: 80% vs git log analysis each time

Real-World Token Usage Distribution

Typical execution patterns:

• First run (parse plan, start Phase 1): 2,500 tokens
• Continue phase (state cached, execute task): 800 tokens
• Complete phase (validation, checkpoint): 1,500 tokens
• Status check (plan complete): 50 tokens
• Most common: Continue phase with cached state

Expected per-phase: 2,000-3,500 tokens (50% reduction from 4,000-7,000 baseline) Real-world average: 1,000 tokens (due to cached state, early exit)

Pre-Flight Checks

Before starting, I'll verify:

• Implementation plan exists and is valid
• Git working directory is clean
• Tests pass (baseline)
• Dependencies are installed
• Development environment is ready

First, let me analyze the implementation plan:

#!/bin/bash
# Parse and validate implementation plan

set -e

PLAN_FILE="${ARGUMENTS:-IMPLEMENTATION_PLAN.md}"

echo "=== Execute Implementation Plan ==="
echo ""

# 1. Verify plan exists
if [ ! -f "$PLAN_FILE" ]; then
    echo "Error: Plan file not found: $PLAN_FILE"
    echo ""
    echo "Create a plan first:"
    echo "  /write-plan <feature-description>"
    exit 1
fi

echo "Plan: $PLAN_FILE"
echo ""

# 2. Extract plan metadata
echo "Plan Overview:"
grep -E "^#+ Implementation Plan:|^Status:|^Complexity:|^Estimated Effort:" "$PLAN_FILE" || true
echo ""

# 3. Count total tasks and phases
echo "Task Summary:"
total_tasks=$(grep -c "^- \[ \]" "$PLAN_FILE" || echo "0")
completed_tasks=$(grep -c "^- \[x\]" "$PLAN_FILE" || echo "0")
phases=$(grep -c "^### Phase [0-9]" "$PLAN_FILE" || echo "0")

echo "  Total tasks: $total_tasks"
echo "  Completed: $completed_tasks"
echo "  Remaining: $((total_tasks - completed_tasks))"
echo "  Phases: $phases"
echo ""

# 4. Show current phase
echo "Current Phase:"
current_phase=$(awk '/^### Phase [0-9]/ && /\[ \]/ {print; exit}' "$PLAN_FILE")
if [ -n "$current_phase" ]; then
    echo "  $current_phase"
else
    echo "  All phases completed!"
    exit 0
fi
echo ""

# 5. Extract dependencies
echo "Dependencies:"
grep -A 5 "^## [0-9]*\. Dependencies" "$PLAN_FILE" | grep "^- \[ \]" || echo "  None identified"
echo ""

# 6. Check git status
echo "Git Status:"
if git rev-parse --git-dir > /dev/null 2>&1; then
    if git diff --quiet && git diff --cached --quiet; then
        echo "  ✓ Working directory clean"
    else
        echo "  ⚠ Uncommitted changes detected"
        git status --short
    fi
else
    echo "  ⚠ Not a git repository"
fi

Phase 1: Pre-Execution Validation

Before executing any phase, I'll validate the environment:

#!/bin/bash
# Pre-execution validation

validate_environment() {
    echo "=== Pre-Execution Validation ==="
    echo ""

    local validation_failed=0

    # 1. Check dependencies installed
    echo "1. Dependency Check:"
    if [ -f "package.json" ]; then
        if [ ! -d "node_modules" ]; then
            echo "  ⚠ Node modules not installed"
            echo "  Run: npm install"
            validation_failed=1
        else
            echo "  ✓ Node modules installed"
        fi
    fi

    if [ -f "requirements.txt" ]; then
        if ! pip show -q $(head -1 requirements.txt | cut -d'=' -f1) 2>/dev/null; then
            echo "  ⚠ Python dependencies not installed"
            echo "  Run: pip install -r requirements.txt"
            validation_failed=1
        else
            echo "  ✓ Python dependencies installed"
        fi
    fi
    echo ""

    # 2. Run baseline tests
    echo "2. Baseline Testing:"
    if [ -f "package.json" ] && grep -q "\"test\":" package.json; then
        if npm test 2>&1 | head -5; then
            echo "  ✓ Baseline tests passing"
        else
            echo "  ⚠ Baseline tests failing"
            echo "  Fix existing test failures before proceeding"
            validation_failed=1
        fi
    else
        echo "  ⓘ No test command found, skipping"
    fi
    echo ""

    # 3. Check build
    echo "3. Build Check:"
    if [ -f "package.json" ] && grep -q "\"build\":" package.json; then
        if npm run build 2>&1 | tail -5; then
            echo "  ✓ Project builds successfully"
        else
            echo "  ⚠ Build failing"
            validation_failed=1
        fi
    else
        echo "  ⓘ No build command found, skipping"
    fi
    echo ""

    if [ $validation_failed -eq 1 ]; then
        echo "⚠ Validation failed. Resolve issues before executing plan."
        return 1
    fi

    echo "✓ All validations passed"
    return 0
}

validate_environment

Phase 2: Controlled Batch Execution

I'll execute the plan phase by phase:

1. Parse Phase Tasks - Extract tasks for current phase
2. Create Git Checkpoint - Save state before execution
3. Execute Tasks - Implement each task with validation
4. Run Tests - Validate implementation works
5. Mark Complete - Update plan with completion status
6. Commit Progress - Save working state

#!/bin/bash
# Execute single phase with checkpoints

execute_phase() {
    local phase_number="$1"
    local plan_file="${2:-IMPLEMENTATION_PLAN.md}"

    echo "=== Executing Phase $phase_number ==="
    echo ""

    # 1. Extract phase tasks
    echo "Phase Tasks:"
    awk "/^### Phase $phase_number:/, /^### Phase [0-9]+:|^## [0-9]+\./" "$plan_file" | \
        grep "^- \[ \]" | head -10
    echo ""

    # 2. Create git checkpoint
    echo "Creating checkpoint..."
    git add -A
    git commit -m "chore: checkpoint before Phase $phase_number execution" || echo "No changes to commit"
    checkpoint_hash=$(git rev-parse HEAD)
    echo "  Checkpoint: $checkpoint_hash"
    echo ""

    # 3. Extract first incomplete task
    echo "Current Task:"
    current_task=$(awk "/^### Phase $phase_number:/, /^### Phase [0-9]+:/" "$plan_file" | \
        grep "^- \[ \]" | head -1 | sed 's/^- \[ \] //')
    echo "  $current_task"
    echo ""

    # Task execution happens here via Claude Code
    echo "Execute this task now, then I'll validate..."

    return 0
}

# Execute next incomplete phase
next_phase=$(grep -n "^### Phase [0-9]" "$PLAN_FILE" | \
    awk -F: '/\[ \]/ {match($2, /Phase ([0-9]+)/, arr); print arr[1]; exit}')

if [ -n "$next_phase" ]; then
    execute_phase "$next_phase"
else
    echo "All phases complete!"
fi

Now I'll guide the execution of each task:

Phase 3: Task Implementation

For each task, I'll:

1. Read Task Details - Understand acceptance criteria
2. Check Dependencies - Verify prerequisites met
3. Implement Solution - Write code following plan
4. Local Validation - Test the specific functionality
5. Update Plan - Mark task complete

#!/bin/bash
# Task completion workflow

complete_task() {
    local task_description="$1"
    local plan_file="$2"

    echo "=== Completing Task ==="
    echo "Task: $task_description"
    echo ""

    # 1. Show acceptance criteria
    echo "Acceptance Criteria:"
    # Extract from plan based on task
    echo ""

    # 2. Run validation tests
    echo "Validation:"
    if [ -f "package.json" ] && grep -q "\"test\":" package.json; then
        npm test 2>&1 | tail -10
    fi
    echo ""

    # 3. Mark task complete in plan
    echo "Updating plan..."
    # sed to change [ ] to [x] for this task

    echo "✓ Task completed"
}

Phase 4: Validation & Testing

After each phase, I'll run comprehensive validation:

Validation Checklist:

• All phase tasks completed
• Unit tests pass
• Integration tests pass
• No new linter errors
• No new TypeScript errors
• Code compiles/builds
• Manual smoke test (if applicable)

#!/bin/bash
# Phase validation

validate_phase() {
    local phase_number="$1"

    echo "=== Phase $phase_number Validation ==="
    echo ""

    local validation_passed=1

    # 1. Test suite
    echo "1. Running test suite..."
    if npm test; then
        echo "  ✓ Tests passing"
    else
        echo "  ✗ Tests failing"
        validation_passed=0
    fi
    echo ""

    # 2. Linting
    echo "2. Linting..."
    if npm run lint 2>/dev/null; then
        echo "  ✓ No lint errors"
    else
        echo "  ⓘ Linter not configured or failed"
    fi
    echo ""

    # 3. Type checking
    echo "3. Type checking..."
    if npm run typecheck 2>/dev/null || tsc --noEmit 2>/dev/null; then
        echo "  ✓ No type errors"
    else
        echo "  ⓘ Type checking not configured or failed"
    fi
    echo ""

    # 4. Build
    echo "4. Build verification..."
    if npm run build 2>&1 | tail -5; then
        echo "  ✓ Build successful"
    else
        echo "  ✗ Build failed"
        validation_passed=0
    fi
    echo ""

    if [ $validation_passed -eq 0 ]; then
        echo "⚠ Phase validation failed"
        echo ""
        echo "Options:"
        echo "  1. Fix issues and re-validate"
        echo "  2. Rollback to checkpoint: git reset --hard $checkpoint_hash"
        return 1
    fi

    echo "✓ Phase $phase_number validated successfully"
    return 0
}

Phase 5: Checkpoint & Commit

After successful validation, I'll create a checkpoint:

#!/bin/bash
# Create phase completion checkpoint

checkpoint_phase() {
    local phase_number="$1"
    local plan_file="$2"

    echo "=== Phase $phase_number Checkpoint ==="
    echo ""

    # 1. Stage changes
    echo "Staging changes..."
    git add -A
    echo ""

    # 2. Show what's being committed
    echo "Changes:"
    git diff --cached --stat
    echo ""

    # 3. Generate commit message
    phase_description=$(grep "^### Phase $phase_number:" "$plan_file" | sed 's/^### Phase [0-9]*: //')

    commit_message="feat: complete Phase $phase_number - $phase_description

Phase $phase_number implementation complete:
$(awk "/^### Phase $phase_number:/, /^### Phase [0-9]+:/" "$plan_file" | grep "^- \[x\]" | sed 's/^- \[x\] /- /')

All tests passing. Ready for next phase."

    # 4. Commit
    echo "Creating commit..."
    git commit -m "$commit_message"
    echo ""

    echo "✓ Phase $phase_number checkpoint created"
    echo "  Commit: $(git rev-parse --short HEAD)"
}

Rollback Safety

If validation fails, I'll provide safe rollback:

#!/bin/bash
# Rollback to last checkpoint

rollback_to_checkpoint() {
    local checkpoint_hash="$1"

    echo "=== Rollback to Checkpoint ==="
    echo ""
    echo "⚠ This will discard all changes since: $checkpoint_hash"
    echo ""

    # Show what will be lost
    echo "Changes to be discarded:"
    git diff --stat "$checkpoint_hash"
    echo ""

    read -p "Confirm rollback? [y/N]: " confirm
    if [ "$confirm" = "y" ]; then
        git reset --hard "$checkpoint_hash"
        echo "✓ Rolled back to checkpoint"
    else
        echo "Rollback cancelled"
    fi
}

Execution Workflow

Complete Workflow:

1. /write-plan - Create implementation plan
2. /execute-plan - Execute Phase 1
   • Validates environment
   • Creates checkpoint
   • Executes tasks
   • Runs tests
   • Commits progress
3. /execute-plan - Execute Phase 2
   • (repeats workflow)
4. Continue until all phases complete

After Each Phase:

• Tests must pass
• Code must build
• Git checkpoint created
• Plan updated with completion

Integration Points

This skill integrates with:

• /write-plan - Reads implementation plans
• /test - Validates each phase
• /commit - Creates checkpoints
• /session-update - Tracks progress
• /review - Quality checks

Error Handling

If execution fails:

• I'll explain the failure clearly
• Show validation errors
• Provide rollback options
• Suggest fixes
• Ensure no partial state

Failure Scenarios:

• Tests fail: Show test output, suggest fixes, rollback available
• Build fails: Show build errors, check dependencies, rollback available
• Dependencies missing: Install instructions, halt execution
• Git conflicts: Resolve before continuing

Practical Examples

# Execute plan from current directory
/execute-plan

# Execute specific plan file
/execute-plan path/to/PLAN.md

# Resume execution after fixing issues
/execute-plan  # Continues from last incomplete phase

Progress Tracking

I'll maintain execution state:

• Track which phase is current
• Mark completed tasks in plan file
• Create git tags for major milestones
• Generate progress reports

# Check execution progress
grep "^- \[x\]" IMPLEMENTATION_PLAN.md | wc -l  # Completed
grep "^- \[ \]" IMPLEMENTATION_PLAN.md | wc -l  # Remaining

What I'll Actually Do

1. Parse Plan - Read and understand implementation plan
2. Validate Environment - Ensure ready to execute
3. Execute Phase - Implement tasks batch by batch
4. Test Continuously - Validate after each task
5. Create Checkpoints - Save progress regularly
6. Handle Failures - Rollback on critical errors
7. Track Progress - Update plan with completion status

Important: I will NEVER:

• Execute without validation
• Skip test verification
• Commit failing code
• Lose work to bad rollbacks
• Execute all phases at once without validation
• Add AI attribution to commits

The execution will be methodical, validated, and safe with clear rollback paths.

Credits: Execution methodology based on obra/superpowers iterative development principles with continuous validation and safe checkpointing.