pi-plans 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MaxInGaussian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+<h1 align="center">pi-plans</h1>
+
+<p align="center">
+  <img src="docs/assets/pi-plans-logo.svg?v=3" alt="pi-plans: Plan. Review. Execute." width="640" />
+</p>
+
+<h2 align="center"><b>Plan. Review. Execute.</b></h2>
+
+<p align="center">
+  <i>Versioned, reviewed Markdown plans land before any code changes.<br>Human-in-the-loop planning for the Pi coding agent.</i>
+</p>
+
+<p align="center">
+  <a href="https://github.com/MaxInGaussian/pi-plans/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/MaxInGaussian/pi-plans?style=square" /></a>
+  <a href="https://hits.sh/github.com/MaxInGaussian/pi-plans/"><img alt="Repo views" src="https://hits.sh/github.com/MaxInGaussian/pi-plans.svg?label=repo%20views" /></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=square" /></a>
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-TS-3178C6?style=square&logo=typescript&logoColor=white" />
+  <img alt="pi-package" src="https://img.shields.io/badge/pi--package-ready-7c3aed?style=square" />
+</p>
+
+---
+
+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.
+
+## Contents
+
+- [How it works](#how-it-works)
+- [Quick start](#quick-start)
+- [What it does](#what-it-does)
+- [Interface overview](#interface-overview)
+- [Skills](#skills)
+- [Installation details](#installation-details)
+- [Layout](#layout)
+- [Safety model](#safety-model)
+- [Verification](#verification)
+- [FAQ](#faq)
+- [License](#license)
+
+## How it works
+
+```text
+        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
+   checklist injected each turn, [DONE:VC-xxx]
+   markers tracked with a footer widget
+                 |
+                 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:
+
+```bash
+pi install npm:pi-plans
+# or try it without installing:
+pi -e npm:pi-plans
+```
+
+Then describe a change from any repository:
+
+```text
+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:  Next step for refining the plan?
+     1. Reviewer round (recommended)
+     2. Criticizer round
+     3. Accept plan for tracked execution
+     ...
+
+You: Accept plan for tracked execution.
+
+Pi:  Execute this plan now?
+     1. Execute this plan now (recommended)
+     2. Stop after planning
+```
+
+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
+
+| 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 progress |
+| Write guard | `edit`/`write` blocked outside planning artifacts while a run is active |
+
+## Interface overview
+
+| Tool / Command | Purpose |
+|---|---|
+| `plans` | State CLI: `init`, `show`, `set-language`, `set-artifact-root`, `set-role`, `start-run`, `set-status`, `record-decision`, `record-ref`, `record-subagent` |
+| `ask_choice` | Numbered choice prompt; `autoComplete: false` for execution handoff / 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, enters extension-managed execution mode |
+| `/plans` | Show config, active run, execution progress |
+| `/plans-execute [plan.md]` | Manual execution handoff (defaults to highest `PLAN_vN.md`) |
+| `/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) |
+
+## 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.
+
+| Skill | Use it when |
+|---|---|
+| [`planning`](skills/planning/SKILL.md) | General router; selects the narrowest specialist skill before planning starts |
+| [`plan-small`](skills/plan-small/SKILL.md) | Small scoped change; 1–3 questions; one criticizer round |
+| [`plan-normal`](skills/plan-normal/SKILL.md) | Broad or risky change; 5–10 questions; reviewer + criticizer rounds |
+| [`plan-big`](skills/plan-big/SKILL.md) | Open-ended/high-risk effort; 10+ questions; three concurrent reviewers |
+| [`debug-and-plan`](skills/debug-and-plan/SKILL.md) | Bug, CI failure, regression, incident — diagnose before planning |
+| [`plan-with-refs`](skills/plan-with-refs/SKILL.md) | External projects/papers/docs must be analyzed before planning |
+
+## Installation details
+
+Dev / quick test against a local checkout:
+
+```bash
+pi -e /path/to/pi-plans
+```
+
+Permanent (global), via symlink into the auto-discovered extensions dir:
+
+```bash
+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`:
+
+```json
+{ "extensions": ["/absolute/path/to/pi-plans"] }
+```
+
+## Layout
+
+```
+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)
+```
+
+## Safety model
+
+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.
+
+## Verification
+
+```bash
+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.
+
+## 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 execution handoff is a separate explicit 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.
+
+## License
+
+MIT.

package/agents/criticizer.md

@@ -0,0 +1,18 @@
+---
+name: pi-plans-criticizer
+description: Read-only adversarial questioner for pi-plans refinement rounds; stress-tests plan assumptions with adaptive questions.
+tools: read, grep, find, ls
+---
+
+You are a read-only criticizer in the pi-plans workflow.
+
+Rules:
+
+- Perform read-only analysis. Never edit, write, or delete any file.
+- Stress-test the plan's assumptions; do not rewrite the plan.
+- You may inspect the repository to ground your questions.
+
+Output Markdown in exactly this shape:
+
+1. A summary of your core criticism in at most three sentences, highlighting the single most important point.
+2. Then at most five adaptive questions, numbered, each with one line of why it matters. Questions must be concrete and answerable by a user with repo access — never rhetorical. Stop earlier if the plan genuinely holds.

package/agents/reviewer.md

@@ -0,0 +1,20 @@
+---
+name: pi-plans-reviewer
+description: Read-only plan reviewer for pi-plans refinement rounds; verifies plan claims against the repository.
+tools: read, grep, find, ls
+---
+
+You are a read-only plan reviewer in the pi-plans workflow.
+
+Rules:
+
+- Perform read-only analysis. Never edit, write, or delete any file.
+- Verify the plan's claims against the actual repository using your read tools before judging them.
+- Every finding needs evidence: a repo path, a command, or an external citation. No evidence, no finding.
+- You are evidence, not authority: state what you verified, not what you assume.
+
+Output findings as Markdown, highest severity first, in this shape per finding:
+
+- `F-###` — severity: high | medium | low; affected plan IDs; evidence: <repo path/command or source>; impact: <what breaks>; recommended fix: <concrete change>; suggested disposition: accept | reject | needs-discussion.
+
+Surface at most five high-priority findings first; list lower-severity findings after them. If the plan holds up, say so explicitly and list what you checked.

package/docs/assets/pi-plans-logo.svg

@@ -0,0 +1,66 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="720" height="180" viewBox="0 0 720 180" role="img" aria-label="pi-plans: Plan. Review. Execute.">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="720" y2="180" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#14102a"/>
+      <stop offset=".55" stop-color="#241b4d"/>
+      <stop offset="1" stop-color="#7c3aed"/>
+    </linearGradient>
+    <linearGradient id="bar" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#a78bfa"/>
+      <stop offset="1" stop-color="#f472b6"/>
+    </linearGradient>
+  </defs>
+
+  <!-- backdrop -->
+  <rect width="720" height="180" rx="20" fill="url(#bg)"/>
+  <rect x="14" y="14" width="692" height="152" rx="14" fill="none" stroke="#ffffff" stroke-opacity=".08"/>
+
+  <!-- plan document -->
+  <g transform="translate(52,37)">
+    <path d="M0 10 Q0 0 10 0 H52 L74 22 V96 Q74 106 64 106 H10 Q0 106 0 96 Z" fill="#ffffff" fill-opacity=".10" stroke="#c4b5fd" stroke-width="2.5"/>
+    <path d="M52 0 V22 H74" fill="none" stroke="#c4b5fd" stroke-width="2.5" stroke-linejoin="round"/>
+    <g stroke="#a7f3d0" stroke-width="3" fill="none" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M12 34 l5 5 l9 -10"/>
+      <path d="M12 56 l5 5 l9 -10"/>
+      <path d="M12 78 l5 5 l9 -10"/>
+    </g>
+    <g stroke="#e9d5ff" stroke-width="3" stroke-linecap="round" opacity=".85">
+      <line x1="36" y1="32" x2="62" y2="32"/>
+      <line x1="36" y1="54" x2="62" y2="54"/>
+      <line x1="36" y1="76" x2="56" y2="76"/>
+    </g>
+  </g>
+
+  <!-- wordmark -->
+  <text x="150" y="96" font-family="-apple-system,'Segoe UI',Helvetica,Arial,sans-serif" font-size="60" font-weight="700" fill="#ffffff">pi-plans</text>
+  <rect x="153" y="110" width="236" height="6" rx="3" fill="url(#bar)"/>
+  <text x="151" y="147" font-family="'SF Mono',Menlo,Consolas,monospace" font-size="16" letter-spacing="4" fill="#ddd6fe">PLAN·REVIEW·EXECUTE</text>
+
+  <!-- pipeline: plan -> review -> execute -->
+  <g>
+    <g stroke="#c4b5fd" stroke-width="3" stroke-linecap="round" opacity=".85">
+      <line x1="502" y1="90" x2="528" y2="90"/>
+      <line x1="598" y1="90" x2="624" y2="90"/>
+    </g>
+    <polygon points="528,84 538,90 528,96" fill="#c4b5fd"/>
+    <polygon points="624,84 634,90 624,96" fill="#c4b5fd"/>
+
+    <circle cx="470" cy="90" r="26" fill="#ffffff" fill-opacity=".07" stroke="#c4b5fd" stroke-width="2.5"/>
+    <circle cx="566" cy="90" r="26" fill="#ffffff" fill-opacity=".07" stroke="#c4b5fd" stroke-width="2.5"/>
+    <circle cx="662" cy="90" r="26" fill="#7c3aed" stroke="#e9d5ff" stroke-width="2.5"/>
+
+    <!-- list -->
+    <g stroke="#e9d5ff" stroke-width="3" stroke-linecap="round">
+      <line x1="458" y1="82" x2="482" y2="82"/>
+      <line x1="458" y1="90" x2="482" y2="90"/>
+      <line x1="458" y1="98" x2="474" y2="98"/>
+    </g>
+
+    <!-- magnifier -->
+    <circle cx="561" cy="85" r="9" fill="none" stroke="#e9d5ff" stroke-width="3"/>
+    <line x1="568" y1="92" x2="578" y2="102" stroke="#e9d5ff" stroke-width="3" stroke-linecap="round"/>
+
+    <!-- play -->
+    <polygon points="654,79 654,101 673,90" fill="#ffffff"/>
+  </g>
+</svg>