firehose/.pi/extensions/plan-executor/README.md

Plan Executor

Execute multi-phase plan files deterministically, one phase at a time, in isolated contexts.

Concept

Instead of dumping an entire plan into one conversation (where context bloats and the agent loses focus), this extension:

1. Parses your plan file into numbered phases
2. Executes each phase in a clean, isolated pi subprocess (fresh context window)
3. Runs the quality gate (default: make precommit) after each phase
4. Auto-fixes any gate failures in another clean context (up to 3 attempts)
5. Only proceeds to the next phase when the gate passes

This gives you deterministic, phase-by-phase execution with automatic quality gates.

Usage

# Execute entire plan (default gate: make precommit)
/execute-plan plans/fix-readme-issues.md

# Start from a specific phase
/execute-plan plans/fix-readme-issues.md --phase 2

# Use a custom gate command
/execute-plan plans/fix-readme-issues.md --gate "mix test && mix credo --strict"

# Dry run — show detected phases without executing
/execute-plan plans/fix-readme-issues.md --dry-run

Plan File Format

Phases are detected by numbered headings:

## 1. Fix test failure

Remove the fragile describe block...

Verify: `mix test`

---

## 2. Fix credo issues

Fix all 41 credo issues...

Verify: `mix credo --strict`

Each phase's content includes everything between its heading and the next phase heading (or a non-phase section like "Execution order" or "Risk assessment").

Execution Flow

┌─────────────────────┐
│ Parse plan file     │
│ extract phases      │
└────────┬────────────┘
         ▼
┌─────────────────────┐
│ For each phase:     │
│                     │
│  1. Spawn clean pi  │──► Agent executes phase
│     subprocess      │    in isolated context
│                     │
│  2. Agent says DONE │──► Phase changes applied
│                     │
│  3. Run quality     │──► Quality gate
│     gate command    │
│                     │
│  4a. Gate passes?   │──✅ Yes → Next phase
│                     │
│  4b. Gate fails?    │──❌ No → Spawn fix agent
│     (up to 3x)      │    in another clean context
│                     │
│     Fix agent runs  │──► Re-check gate
│     & re-verify     │
└─────────────────────┘

Widget

While running, a widget in the TUI shows:

• Phase status (⏳ pending, 🔄 running, ✅ done, ❌ failed)
• Turn count and token usage per phase
• Gate attempt count
• Final summary with total cost

Configuration

The extension uses your current pi model and tool configuration for spawned agents. Each phase runs with:

• Full tool access (bash, read, write, edit)
• Your default model
• A custom system prompt scoped to the phase

Safety

• Each phase runs in a separate pi process (no shared state)
• Ctrl+C aborts the current agent and cleans up
• Quality gate prevents broken state from propagating between phases
• Max 3 fix attempts per phase before failing