# 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

```bash
# 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:

```markdown
## 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