105 lines
3.2 KiB
Markdown
105 lines
3.2 KiB
Markdown
# 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
|