Versioned, reviewed Markdown plans land before any code changes.
Human-in-the-loop planning for the Pi coding agent.
A rough change request becomes a versioned Markdown plan instead of a surprise diff. The agent inspects your repository read-only, asks scoped planning questions one at a time, and stores every answer in a per-run ledger. Reviewer and criticizer subagents refine the plan until it converges — and only after you explicitly approve the handoff does the extension enter a tracked execution loop that injects the remaining verifier checklist every turn and lifts the write guard. Nothing outside planning artifacts is writable until that approval.
- How it works
- Quick start
- What it does
- Interface overview
- Skills
- Installation details
- Layout
- Safety model
- Verification
- FAQ
- License
rough change request
|
language + docs location (once per workspace)
|
planning questions, one ask_choice at a time | write guard ON
| | only .git/pi_plans/,
v | run artifacts, cache
PLAN_vN.md + Verifier Checklist | are writable
^ |
| refine rounds |
+----------------+
reviewer (x1..x3) -> criticizer -> revise
|
v
explicit approval (never auto-completed)
|
=============================================== write guard OFF
|
tracked execution loop
fused AGENTS.md × Ponytail executor rules
checklist injected each turn, [DONE:VC-xxx]
markers tracked via bottom status bar + detail panel
|
v
run status: done
Every plan version carries stable IDs (I-###, VC-###) that never get recycled across revisions, so acceptance criteria survive refinement rounds intact.
Install from npm:
pi install npm:pi-plans
# or try it without installing:
pi -e npm:pi-plansThen describe a change from any repository:
You: Create a plan to split the execution loop into smaller modules.
Pi: Which planning docs location should this workspace use?
1. ./docs/pi-plans (recommended)
2. ./.git/pi_plans/plans
3. Other
4. Auto-complete
Pi: Wrote ./docs/pi-plans/2026-08-26-split-execution-loop/PLAN_v1.md
Example verifier item:
- [ ] `VC-001` covers `I-001`; pass condition: `npm test` passes;
evidence: test output; metric: zero failing tests.
Pi: Accept the plan and execute it now?
1. ✓ Accept plan and execute now (recommended)
2. Accept plan, don't execute yet
3. Run another round: Reviewer
...
You: 1 — accept and execute.
Planning artifacts live under ./docs/pi-plans/YYYY-MM-DD-<topic>/ by default (public, committed). Prefer .git/pi_plans/plans if you want them private to the repository.
| Capability | In short |
|---|---|
| Planning router + five specialist skills | Start with /skill:planning to route to the narrowest matching specialist (plan-small → plan-big, debug-and-plan, plan-with-refs) |
| Choice prompts | ask_choice: recommended option first, answers auto-recorded per run |
| Refinement rounds | Read-only reviewer/criticizer Pi subagents consolidate findings into the next plan version |
| Workspace state | Config, runs, decisions, refs, and subagent ledgers in .git/pi_plans/ (git common dir) |
| Tracked execution | Checklist injected each turn; [DONE:VC-xxx] markers drive completion; implementation items report progress with [I-xxx:implemented] / [I-xxx:validating] markers; plans-list groups work by I-item with [Pending/Implementing/Implemented/Validating/VC passed] states (passed items struck through); the collapsed footer and expanded panel share the same progress projection, so x/y updates in real time in both views |
| Execution model | With plans set-execution-model <provider/model[:thinking]>, the main session switches to it at handoff and restores the planning model + thinking level on stop/complete/abandon; when unset, the first execution handoff prompts for one and recommends inheriting the current session model |
| Execution-phase compaction | Pi core owns threshold, overflow, and manual compaction scheduling; pi-plans only supplies a plan-aware session_before_compact summary and queues one hidden continuation when Pi reports willRetry: false, while preserving the raw execution tail and previousSummary chaining |
| Planning-phase auto compaction | In active planning runs (run.status=planning, no execution), context usage >=100% triggers a plan-aware compaction too: pre-plan history compresses, Q&A during planning stays in a dedicated section, the latest PLAN_vN.md and later conversation stay raw; cooldown + resume guard prevent ping-pong, and manual /compact follows the same rules |
| Efficient executor prompt | Each turn, the executor is steered by a fused rule set — Marcos Hernanz's AGENTS.md principles × Ponytail minimalism: layered growth, simplest implementation, long-term architecture (no stopgaps), library discipline — so plans finish in fewer tokens and fewer detours |
| Write guard | edit/write blocked outside planning artifacts while a run is active |
| Tool / Command | Purpose |
|---|---|
plans |
State CLI: init, show, set-language, set-artifact-root, set-execution-model, set-role, start-run, set-status, record-decision, record-ref, record-subagent |
ask_choice |
Numbered choice prompt; autoComplete: false for the merged accept/execute question and external-state questions |
refine |
Reviewer/criticizer round via read-only subagents (--tools read,grep,find,ls); reviewers: 3 for big plans; enforces role/model confirmation gates |
execute_plan |
Execution handoff: re-confirms with the user, prompts for an execution model if needed, and enters extension-managed execution mode |
/plans |
Show config, active run, and execution progress |
/plans-list |
Toggle the execution checklist panel |
/plans-execute [plan.md] |
Manual execution handoff (defaults to highest PLAN_vN.md; prompts for an execution model if unset) |
/update-plan [plan.md] [reason…] |
Interrupt-and-refine: stops execution (if any), returns the run to planning, and directs the agent to revise the plan into PLAN_vN+1.md while preserving verified work |
/plans-stop |
Stop execution mode |
/plans-abandon |
Abandon the active run (lifts the write guard; artifacts stay) |
| Status bar (lifecycle) | 💬 Q&A → 📝 draft written (planning sub-phases) → ⌛ executing x/y · spent · in/out-toks in the collapsed footer or expanded panel → ⛔ stopped / 🎯 done / 🚫 abandoned |
Once you approve the handoff, every turn injects a compact rule set that fuses Marcos Hernanz's AGENTS.md seven principles with Ponytail minimalism — so the executor finishes plans in fewer tokens and fewer detours:
The four fused rules (click to expand)
- Grow in layers — smallest end-to-end slice first, then stack each new capability on top of what already works.
- Simplest implementation — no speculative abstractions, configuration, or indirection; modular components with clearly separated concerns.
- Long-term architecture, no stopgaps — no backward-compatibility layers, fallbacks, or migrations; remove the obsolete paths a change obsoletes.
- Library discipline — prefer established, well-maintained libraries; check the project's existing dependencies (docs and types) before writing your own or adding a package.
The rules cost four lines per turn and buy back far more: fewer wrong turns, shorter implementation paths, plans that finish in fewer tokens.
Invoked via resources_discover, callable as /skill:<name>, directly as /<name> (e.g. /planning, /plan-small — extension aliases that forward to the skill), or picked automatically from the task description.
| Skill | Use it when |
|---|---|
planning |
General router; selects the narrowest specialist skill before planning starts |
plan-small |
Small scoped change; 1–3 questions; one criticizer round |
plan-normal |
Broad or risky change; 5–10 questions; reviewer + criticizer rounds |
plan-big |
Open-ended/high-risk effort; 10+ questions; three concurrent reviewers |
debug-and-plan |
Bug, CI failure, regression, incident — diagnose before planning |
plan-with-refs |
External projects/papers/docs must be analyzed before planning |
Dev / quick test against a local checkout:
pi -e /path/to/pi-plansPermanent (global), via symlink into the auto-discovered extensions dir:
mkdir -p ~/.pi/agent/extensions/pi-plans
ln -s "$(pwd)"/index.ts "$(pwd)"/tools "$(pwd)"/src "$(pwd)"/skills "$(pwd)"/references "$(pwd)"/agents ~/.pi/agent/extensions/pi-plans/or register the absolute path in ~/.pi/agent/settings.json:
{ "extensions": ["/absolute/path/to/pi-plans"] }pi-plans/
├── index.ts # Extension entry: tools, commands, guard, execution loop
├── tools/ # plans, ask-choice, refine, execute-plan
├── src/ # state, guard, plan parsing, subagent runner, exec loop
├── skills/ # The planning router plus five specialist planning skills
├── references/ # Shared workflow, state/config, plan template (normative)
├── agents/ # reviewer.md / criticizer.md subagent prompts
├── scripts/validate.ts # Structure validator
└── tests/ # node:test suite (state, guard, plan parsing, execution)
Before the approved handoff the workflow writes only .git/pi_plans/ state, the run's artifact directory, and ~/.cache/pi-plans/ — the extension blocks edit/write elsewhere while a run is planning/accepted (bash stays discipline-bound: inspection, git init, downloads into the cache). Reviewer/criticizer subagents run with read-only tools. Auto-complete may answer planning and refinement questions only; it is never offered for execution, installs, publishing, deployment, merge, push, or credential use, and non-interactive sessions stop instead of auto-approving those.
npm run validate # structure validator
npm test # node:test suite (stdlib only, no deps)Both run on Node ≥ 22.6 via --experimental-strip-types; no npm dependencies.
Why do I have to approve before any code changes?
The plan is the contract. Refinement converges on scope while nothing is writable yet; the merged accept/execute question is an explicit, never-auto-completed approval that also lifts the write guard. You always see — and can veto — what will happen before it happens.
What can Auto-complete decide on my behalf?
Planning and refinement choices only (the recommended option). It is never offered for execution approval, installs, publishing, deployment, merge, push, or credentials — those questions stop and wait for you.
Where does all the state live?
Preferences and run ledgers in .git/pi_plans/ inside your workspace's git directory (never tracked, never published); plan artifacts under the configured artifact root (default ./docs/pi-plans/); large downloaded references outside the repo under ~/.cache/pi-plans/.
How is this different from just prompting an AI to make changes?
Prompts produce one-shot diffs with no recorded reasoning. pi-plans produces versioned artifacts — decisions, references, reviewer findings, dispositions, a verifier checklist — that are auditable, resumable across sessions, and enforced by tooling rather than goodwill.
Doesn't injecting execution rules every turn cost extra tokens?
The injected rule set is four compressed lines. It buys back more than it costs: the executor stops re-deriving discipline (no speculative abstractions, no compatibility detours, no reinvented helpers), so finished items converge in fewer turns and fewer tokens overall.
MIT.