pi-plans

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.

Benchmarked: 6× more tasks solved

On Terminal-Bench 2.0 (36-task stratified sample, GLM-5.3-Flash), a paired A/B per task found: 50.0% of tasks solved with pi-plans vs 8.3% with stock pi (McNemar exact p = 0.0003) at 7.6× fewer tokens per solved task.

[!NOTE] Exploratory result: single model, single seed, forced /plan-big variant, eval-only auto-approve. Full methodology and disclosures: docs/benchmarks/tech-note.md.

Contents

• How it works
• Quick start
• What it does
• Interface overview
• Skills
• Installation details
• Benchmarks
• Layout
• Safety model
• Verification
• FAQ
• Contributing
• License

How it works

        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
                 |
                 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.

Quick start

Install from npm:

pi install npm:pi-plans
# or try it without installing:
pi -e npm:pi-plans

Then 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.

What it does

Interface overview

VCC compact

Pi core remains the owner of compaction scheduling: manual /compact, threshold, and overflow events are emitted by Pi as usual. During an active pi-plans planning or execution run, pi-plans handles session_before_compact with a deterministic VCC-style compiler instead of calling a model for a summary.

• Summary shape. The summary contains exactly five bracket sections: [Session Goal], [Files And Changes], [Commits], [Outstanding Context], and [User Preferences], followed by --- and a ranked brief transcript. Execution contributes plan path, current I-###, implementation IDs, and remaining verifier IDs; planning contributes run ID, artifact directory, latest plan path from session entries, and any observed current-I marker.
• Session-only input. Compact summaries are built from the event's branch entries, previous summary, file ops, pi-plans custom session entries, and live phase state. The compiler does not read plan files, git history, or the worktree to invent context.
• Tail policy. The default keep is one recent user turn; smart keep may retain more turns when the tail is still small. Explicit keep:N is honored, while no-anchor and oversized-tail cases use a deterministic token-budget cut that avoids starting retained context with an orphan tool result.
• Manual matrix. Plain /compact and /compact keep:N compact and show stats without continuing. /compact <text> and /compact keep:N <text> compact, then send the text once as the follow-up prompt. Internal pi-plans compaction markers are never reused as user follow-up prompts.
• Fallbacks and stats. Unsafe manual/threshold cuts cancel with a warning; overflow or retrying unsafe cuts return control to Pi core. Successful VCC compactions notify with kept-tail and summarized-message stats. Threshold/overflow compactions may queue one hidden continuation only when the running Pi version still needs it and continueAfterThresholdCompact is enabled.
• Pre-plan compaction. When plans start-run creates a new planning run, pi-plans proactively requests one VCC compaction (internal hint pi-plans planning pre-plan compact) right after the run is created and before the first planning question, then resumes the planning turn with a hidden message — so each new plan starts on a lean context (LLM reasoning degrades with longer input). Small sessions, already-compacted sessions, and failures skip silently and still resume. prePlanCompact:false in the repo-private config restores the old behavior.
• Repo-private config. Defaults are scaffolded in .git/pi_plans/pi-vcc-config.json under the resolved git common dir: overrideDefaultCompaction:true, smartKeepTail:true, continueAfterThresholdCompact:true, prePlanCompact:true, debug:false. Global pi-vcc config and PI_VCC_CONFIG_PATH are intentionally ignored.

Visible Refiner overlay

Delegated refine rounds (reviewer or criticizer) and analyze_refs rounds (titled Refs) show their progress directly inside the Pi TUI instead of disappearing into the child process's terminal. The overlay is a public, named panel so users always know who is doing what:

• Pi-btw-aligned geometry. Each round uses width: "78%", minWidth: 72, maxHeight: "78%", anchor: "top-center", and { top: 1, left: 2, right: 2 } margins (no dependency on pi-btw; the renderer is built on Pi's public pi-tui primitives).
• Complete streaming transcript. Assistant text, thinking blocks, tool calls, tool results, and stderr are merged per turn/content block into lane entries without overlay-facing truncation; only the viewport slices them. Final message_end / tool_execution_end overwrite the live snapshot with the authoritative content.
• No input row. The overlay has no composer, no submit path, and no printable input forwarding. Only Esc, Tab/Shift+Tab, ↑/↓, PgUp/PgDn, and SGR mouse wheel are consumed; everything else is ignored by design.
• Equal-height panes for reviewers: 3. Concurrent reviewer rounds render one reviewer lane per subagent as three independent equal-height panes inside the same top-center overlay; each pane keeps its own scroll offset and follow-bottom state. Tab/Shift+Tab switches the focused pane and scroll keys only affect it.
• Lifecycle. The overlay opens at round start, advances via the JSONL progress feed emitted by pi --mode json, and is dismissed by Esc. Esc is close-only — it never aborts the refiner child; the child keeps running to natural completion and its result still flows back through the tool result path. A new refinement round replaces any retained finished overlay to avoid overlay stacking. Cancelled and timed-out children render as terminal states with the original error message — never as silent drops.
• Tool-only progress. The overlay only consumes tool and message lifecycle events from the child; unrelated pi events are ignored, so a noisy upstream release does not desync the panel.

The execution rules

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:

1. Grow in layers — smallest end-to-end slice first, then stack each new capability on top of what already works.
2. Simplest implementation — no speculative abstractions, configuration, or indirection; modular components with clearly separated concerns.
3. Long-term architecture, no stopgaps — no backward-compatibility layers, fallbacks, or migrations; remove the obsolete paths a change obsoletes.
4. 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.

Waiting for subprocess-backed verification: For subprocess-backed verification, when a step starts a subprocess and needs its result before verifying, use literal waiting for with backoff 5s -> 10s -> 20s -> 40s -> 80s, then keep polling at 80s; restart at 5s for each new subprocess.

Skills

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.

Installation details

Dev / quick test against a local checkout:

pi -e /path/to/pi-plans

Permanent (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"] }

Benchmarks

First full A/B run complete (36-task stratified TB2.0 sample, GLM-5.3-Flash, seed 1) — headline numbers above; full methodology and disclosures in docs/benchmarks/tech-note.md.

We evaluate pi-plans with a controlled A/B: vanilla pi vs pi + pi-plans (planning entry injected at the adapter level; task instructions verbatim in both arms) on Terminal-Bench 2.0 (89 tasks) through the harbor framework, paired per task and analyzed with a pre-registered McNemar exact test plus paired bootstrap CIs. Cost accounting includes parent and subagent usage.

Scope of any published claim (strictly limited): pi-plans (forced-/plan-big variant) on Terminal-Bench 2.0 / single model / single seed — an exploratory paired difference, not a general claim about pi-plans. Human-approval gates are bypassed by an eval-only PI_PLANS_AUTO_APPROVE=1 env (lifecycle questions only, default off), so results do not represent the interactive experience.

Reproduce:

node --experimental-strip-types scripts/bench/run-ab.ts --prepare
node --experimental-strip-types scripts/bench/run-ab.ts --arm both --full   # requires docker + harbor
node --experimental-strip-types scripts/bench/analyze.ts --results-dir scripts/bench/results/<date>

Methodology, preregistered statistics, and disclosures: docs/benchmarks/tech-note.md.

Layout

pi-plans/
├── index.ts               # Extension entry: tools, commands, guard, execution loop
├── tools/                 # plans, ask-choice, refine, execute-plan, code-graph
├── src/                   # state, guard, plan parsing, subagent runner, refine overlay, exec loop
│   └── code-graph/        # SQLite schema/store, parsers, indexer, summary, materialize
├── 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 + package artifact guard
└── tests/                 # node:test suite (state, guard, plan parsing, execution, refine progress, code-graph)

Safety model

Before the approved handoff the workflow writes only .git/pi_plans/ state, the run's artifact directory, ~/.cache/pi-plans/, and the configured refs root (set via plans set-refs-root or /config-pi-plans; the recommended .git/pi-plans/refs/ lives inside the git dir and needs no extra guard) — 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/ref-analyst 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.

Delegated executor children (0.6.0) write natively with the approval already recorded — the planning guard no-ops for PI_PLANS_EXECUTOR=1 children and honors a PI_PLANS_RUN_ID pin, so another session's concurrent planning run can never block an executing child; graph-aware file tools bypass DB-first staging for executor children so edits always land on disk. The child inherits pi's project-trust model (built-in write tools are always available; pi has no permission popups) and never loads run bookkeeping beyond its pinned id. ask_choice refuses to run inside an executor child (no interactive user — decide autonomously).

Verification

npm run validate   # structure + package artifact guard
npm test           # node:test suite (stdlib only, no deps)

Both run on Node ≥ 22.6 via --experimental-strip-types. The graph extension additionally requires node:sqlite (Node ≥ 22.13 unflagged, or any Node ≥ 22.6 with --experimental-sqlite) and the four parser dependencies listed in dependencies.

FAQ

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). Choosing Auto-complete enables the recommended answer for later eligible planning questions in the current run and the extension continues the planning turn when the model stops early. Use /plans-autocomplete-stop to take back control. It is never offered for execution approval, installs, publishing, deployment, merge, push, or credentials — those questions stop and wait for you. After execution completes, interactive sessions enter goal-running review mode automatically and ask only for the implementation-review loop's termination condition; the loop then continues until that condition or the 5-round cap. Headless sessions stay silent.

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/); reference downloads under the configured refs root — asked once per workspace (recommended .git/pi-plans/refs/), changeable via plans set-refs-root or /config-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.

Contributing

Contributions are welcome — see CONTRIBUTING.md for the full workflow (setup, checks, commit style, and PR expectations). Small fixes can go straight to a pull request; for larger changes, open an issue first. Look for issues labeled good first issue to get started.

License

MIT.