pi-plans 0.1.0

package/index.ts

@@ -0,0 +1,375 @@
+/**
+ * pi-plans — human-in-the-loop planning for the Pi coding agent.
+ *
+ * Researched, refined Markdown plans before any code changes. The five
+ * planning skills are contributed via resources_discover; the extension
+ * provides the supporting machinery:
+ *
+ *   - `plans` tool      — workspace state (config, runs, ledgers) in .git/pi_plans/
+ *   - `ask_choice` tool — the choice-prompt contract (Other / Auto-complete rules)
+ *   - `refine` tool     — reviewer/criticizer rounds via read-only pi subagents
+ *   - `execute_plan`    — execution handoff into the tracked execution loop
+ *   - write guard       — planning runs may only write planning artifacts
+ *   - execution loop    — checklist injection, [DONE:VC-xxx] tracking, progress widget
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	applyDoneMarkers,
+	completeExecution,
+	consumePendingPanelSync,
+	executionContextMessage,
+	getExecution,
+	isExecutionComplete,
+	recordExecutionCompletion,
+	recordTouchedPaths,
+	restoreFromSession,
+	stopExecution,
+	syncExecutionPanel,
+	toggleExecutionPanelView,
+	updateStatusWidget,
+} from "./src/exec.ts";
+import { planningWriteBlockReason } from "./src/guard.ts";
+import { latestPlanVersion, nextPlanVersionPath } from "./src/plan.ts";
+import { getRun, readActive, recordDecision, resolveStateRootOrNull, setRunStatus } from "./src/state.ts";
+import { registerAskChoiceTool } from "./tools/ask-choice.ts";
+import { executeHandoff, registerExecutePlanTool } from "./tools/execute-plan.ts";
+import { registerPlansTool } from "./tools/plans.ts";
+import { registerRefineTool } from "./tools/refine.ts";
+
+const baseDir = dirname(fileURLToPath(import.meta.url));
+
+function extractPathsFromBash(command: string): string[] {
+	const values = new Set<string>();
+	for (const token of command.split(/\s+/)) {
+		const cleaned = token.replace(/^["'`(<[{]+|["'`)>}\],;]+$/g, "");
+		if (!cleaned || cleaned === "." || cleaned === ".." || cleaned.startsWith("-") || cleaned.includes("=") ) continue;
+		const looksLikePath =
+			cleaned.includes("/") ||
+			cleaned.startsWith(".") ||
+			cleaned.startsWith("~") ||
+			/^[A-Za-z0-9._-]+\.[A-Za-z0-9._-]+$/.test(cleaned);
+		if (!looksLikePath) continue;
+		values.add(cleaned);
+	}
+	return [...values];
+}
+
+export default function piPlansExtension(pi: ExtensionAPI): void {
+	registerPlansTool(pi);
+	registerAskChoiceTool(pi);
+	registerRefineTool(pi, baseDir);
+	registerExecutePlanTool(pi);
+
+	// Contribute the router skill plus the five specialist planning skills.
+	pi.on("resources_discover", () => ({
+		skillPaths: [
+			join(baseDir, "skills", "planning"),
+			join(baseDir, "skills", "debug-and-plan"),
+			join(baseDir, "skills", "plan-small"),
+			join(baseDir, "skills", "plan-normal"),
+			join(baseDir, "skills", "plan-big"),
+			join(baseDir, "skills", "plan-with-refs"),
+		],
+	}));
+
+	// Direct slash aliases: /plan-small etc. forward to the skill commands
+	// (/skill:plan-small) so users can invoke skills without the prefix.
+	for (const name of [
+		"planning",
+		"debug-and-plan",
+		"plan-small",
+		"plan-normal",
+		"plan-big",
+		"plan-with-refs",
+	]) {
+		pi.registerCommand(name, {
+			description: `Run the ${name} planning skill (alias of /skill:${name})`,
+			handler: async (args, ctx) => {
+				const invocation = args.trim() ? `/skill:${name} ${args.trim()}` : `/skill:${name}`;
+				try {
+					pi.sendUserMessage(invocation, { expandPromptTemplates: true });
+				} catch {
+					ctx.ui.notify("Agent is busy; try again once the current turn finishes.", "error");
+				}
+			},
+		});
+	}
+
+	// -----------------------------------------------------------------------
+	// Planning write guard: while a planning run is active (and execution has
+	// not been approved), edit/write may only target planning artifacts.
+	// -----------------------------------------------------------------------
+	pi.on("tool_call", async (event, ctx) => {
+		const execution = getExecution();
+		if (execution) {
+			if (event.toolName === "edit" || event.toolName === "write") {
+				const rawPath = String((event.input as { path?: string }).path ?? "");
+				if (rawPath) recordTouchedPaths(ctx.cwd, [rawPath]);
+			}
+			if (event.toolName === "bash") {
+				const command = String((event.input as { command?: string }).command ?? "");
+				if (command) recordTouchedPaths(ctx.cwd, extractPathsFromBash(command));
+			}
+			return;
+		}
+		const rawPath = String((event.input as { path?: string }).path ?? "");
+		if (!rawPath) return;
+		const reason = planningWriteBlockReason({ workdir: ctx.cwd, toolName: event.toolName, rawPath });
+		if (!reason) return;
+		return { block: true, reason };
+	});
+
+	// -----------------------------------------------------------------------
+	// Execution loop: inject remaining checklist each turn, track markers.
+	// -----------------------------------------------------------------------
+	pi.on("before_agent_start", async () => {
+		const content = executionContextMessage();
+		if (!content) return;
+		return {
+			message: {
+				customType: "pi-plans-exec-context",
+				content,
+				display: false,
+			},
+		};
+	});
+
+	pi.on("turn_end", async (event, ctx) => {
+		const message = event.message as { role?: string; content?: Array<{ type: string; text?: string }> };
+		if (!message || message.role !== "assistant") {
+			updateStatusWidget(ctx);
+			return;
+		}
+		const text = (message.content ?? [])
+			.filter((part) => part.type === "text")
+			.map((part) => part.text ?? "")
+			.join("\n");
+		const changedIds = applyDoneMarkers(text);
+		if (changedIds.length > 0) {
+			recordExecutionCompletion(pi, ctx, changedIds);
+		}
+		if (getExecution() && isExecutionComplete()) {
+			completeExecution(pi, ctx);
+		}
+		// A busy-toggle during the previous turn deferred its re-render; the
+		// turn just ended, so this is the safe point to apply it.
+		if (consumePendingPanelSync()) syncExecutionPanel(ctx);
+		updateStatusWidget(ctx);
+	});
+
+	// -----------------------------------------------------------------------
+	// Commands and shortcuts
+	// -----------------------------------------------------------------------
+	pi.registerShortcut("alt+o", {
+		description: "Toggle pi-plans execution checklist widget",
+		handler: async (ctx) => {
+			const expanded = toggleExecutionPanelView(pi, ctx);
+			if (expanded === null) {
+				ctx.ui.notify("No execution in progress.", "info");
+				return;
+			}
+			ctx.ui.notify(expanded ? "Execution checklist expanded." : "Execution checklist collapsed.", "info");
+		},
+	});
+
+	pi.registerCommand("plans", {
+		description: "Show pi-plans state: config, active run, and execution progress",
+		handler: async (_args, ctx) => {
+			const lines: string[] = [];
+			const active = readActive(ctx.cwd);
+			const run = active ? getRun(ctx.cwd, active.run_id) : null;
+			if (!run) {
+				lines.push("No active planning run.");
+			} else {
+				lines.push(`Active run: ${run.run_id}`);
+				lines.push(`Skill: ${run.skill}  Status: ${run.status}`);
+				lines.push(`Artifacts: ${run.artifact_dir}`);
+				lines.push(`Language: ${run.language_tag ?? "(unset)"}`);
+				lines.push(`State: ${resolveStateRootOrNull(ctx.cwd) ?? "(no repo)"}`);
+			}
+			const execution = getExecution();
+			if (execution) {
+				const done = execution.items.filter((item) => item.done).length;
+				lines.push(`Execution: ${execution.planPath} — ${done}/${execution.items.length} verifier items done`);
+				for (const item of execution.items) {
+					lines.push(`  ${item.done ? "☑" : "☐"} ${item.id}`);
+				}
+			}
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+
+	pi.registerCommand("plans-list", {
+		description: "Toggle the pi-plans execution checklist widget",
+		handler: async (_args, ctx) => {
+			const expanded = toggleExecutionPanelView(pi, ctx);
+			if (expanded === null) {
+				ctx.ui.notify("No execution in progress.", "info");
+				return;
+			}
+			ctx.ui.notify(expanded ? "Execution checklist expanded." : "Execution checklist collapsed.", "info");
+		},
+	});
+
+	pi.registerCommand("plans-execute", {
+		description: "Execute handoff: enter tracked execution mode for an accepted plan",
+		handler: async (args, ctx) => {
+			const planPath = args.trim() || undefined;
+			const outcome = await executeHandoff(ctx, planPath);
+			ctx.ui.notify(outcome.message, outcome.status === "error" ? "error" : "info");
+		},
+	});
+
+	pi.registerCommand("update-plan", {
+		description: "Interrupt-and-refine: stop execution (if any) and revise the current plan into its next version",
+		handler: async (args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("/update-plan requires an interactive session.", "error");
+				return;
+			}
+
+			// Parse args: optional plan.md path first, remaining text is the refocus reason.
+			let planArg: string | undefined;
+			let focus = "";
+			const trimmed = args.trim();
+			if (trimmed) {
+				const [first, ...rest] = trimmed.split(/\s+/);
+				if (first && (/\.(md|markdown)$/i.test(first) || first.includes("/") || first.startsWith("@"))) {
+					planArg = first;
+					focus = rest.join(" ");
+				} else {
+					focus = trimmed;
+				}
+			}
+
+			const active = readActive(ctx.cwd);
+			const execution = getExecution();
+
+			// Resolve the plan to revise: explicit arg > running execution > latest in artifact dir.
+			let sourcePlanPath: string | null = planArg
+				? path.resolve(ctx.cwd, planArg.replace(/^@/, ""))
+				: null;
+			if (!sourcePlanPath && execution) sourcePlanPath = execution.planPath;
+			if (!sourcePlanPath && active) sourcePlanPath = latestPlanVersion(active.artifact_dir)?.path ?? null;
+			if (!sourcePlanPath || !fs.existsSync(sourcePlanPath)) {
+				ctx.ui.notify(
+					sourcePlanPath ? `Plan file not found: ${sourcePlanPath}` : "No plan to update. Pass plan.md or start a run first.",
+					"error",
+				);
+				return;
+			}
+
+			const artifactDir = active?.artifact_dir ?? path.dirname(sourcePlanPath);
+			const next = nextPlanVersionPath(artifactDir);
+
+			// Snapshot progress BEFORE stopping so the revision preserves finished work.
+			const doneIds = execution ? execution.items.filter((item) => item.done).map((item) => item.id) : [];
+			const pendingIds = execution ? execution.items.filter((item) => !item.done).map((item) => item.id) : [];
+
+			if (execution) {
+				const ok = await ctx.ui.confirm(
+					"Stop execution to update the plan?",
+					`${doneIds.length}/${execution.items.length} verifier item(s) already verified; their work stays. Remaining items return to planning.`,
+				);
+				if (!ok) return;
+				stopExecution(pi, ctx, "interrupted by /update-plan");
+			}
+
+			// Return the run to planning so refinement rules and guards apply again.
+			if (active) {
+				const run = getRun(ctx.cwd, active.run_id);
+				if (run && run.status !== "planning" && run.status !== "abandoned" && run.status !== "done") {
+					try {
+						setRunStatus(ctx.cwd, active.run_id, "planning");
+					} catch {
+						/* status bookkeeping is best-effort */
+					}
+				}
+				try {
+					recordDecision(ctx.cwd, active.run_id, {
+						question: "/update-plan requested",
+						options: ["stop execution and refine current plan"],
+						answer: focus ? `refocus: ${focus}` : "stop execution and refine current plan",
+						answer_source: "user",
+						artifact: next.path,
+					});
+				} catch {
+					/* best-effort audit trail */
+				}
+			}
+
+			const run = active ? getRun(ctx.cwd, active.run_id) : null;
+			const lines: string[] = [
+				"[PI-PLANS UPDATE] Revise the accepted plan for user-directed changes.",
+				"",
+				`Current plan: ${sourcePlanPath}`,
+				`Write the revised version as: ${next.path}`,
+				`Update the Status header and Plan version fields; keep every stable ID (G/R/I/C/VC-###); never recycle IDs of completed items; append to the Revision Ledger.`,
+			];
+			if (run) lines.push(``, `Run: ${run.run_id} (skill: ${run.skill})`, `Original request: ${run.request_text}`);
+			if (doneIds.length) {
+				lines.push(`Already verified during execution (preserve their scope unless the user says otherwise): ${doneIds.join(", ")}`);
+			}
+			if (pendingIds.length) lines.push(`Not yet verified: ${pendingIds.join(", ")}`);
+			lines.push(
+				"Execution was interrupted on purpose — do not continue implementing until the revised plan is approved again.",
+			);
+			if (focus) lines.push(`User-reported problems / refocus: ${focus}`);
+			lines.push(
+				"",
+				"Follow the original planning-skill contract for revisions: collect needed clarifications via ask_choice (one question at a time, recorded), apply evidence-based revisions only, then ask the next refinement-mode question, and finish with the execution handoff (ask_choice with autoComplete: false → execute_plan pointing at the new version).",
+			);
+
+			await pi.sendUserMessage(lines.join("\n"));
+		},
+	});
+
+	pi.registerCommand("plans-stop", {
+		description: "Stop plan execution mode (plan artifacts are kept)",
+		handler: async (_args, ctx) => {
+			if (!getExecution()) {
+				ctx.ui.notify("No execution in progress.", "info");
+				return;
+			}
+			const ok = await ctx.ui.confirm("Stop execution?", "Remaining verifier items will be left unfinished.");
+			if (!ok) return;
+			stopExecution(pi, ctx, "stopped by user via /plans-stop");
+			ctx.ui.notify("Execution stopped.", "info");
+		},
+	});
+
+	pi.registerCommand("plans-abandon", {
+		description: "Abandon the active planning run (lifts the read-only guard; artifacts are kept)",
+		handler: async (_args, ctx) => {
+			const active = readActive(ctx.cwd);
+			if (!active) {
+				ctx.ui.notify("No active planning run.", "info");
+				return;
+			}
+			const ok = await ctx.ui.confirm(
+				"Abandon planning run?",
+				`${active.run_id}\nThe read-only guard lifts; committed artifacts stay in place.`,
+			);
+			if (!ok) return;
+			try {
+				setRunStatus(ctx.cwd, active.run_id, "abandoned");
+				ctx.ui.notify(`Run ${active.run_id} abandoned.`, "info");
+			} catch (error) {
+				ctx.ui.notify(`Failed: ${(error as Error).message}`, "error");
+			}
+			updateStatusWidget(ctx);
+		},
+	});
+
+	// -----------------------------------------------------------------------
+	// Session lifecycle
+	// -----------------------------------------------------------------------
+	pi.on("session_start", async (_event, ctx) => {
+		restoreFromSession(pi, ctx, ctx.sessionManager.getEntries() as unknown as Parameters<typeof restoreFromSession>[2]);
+	});
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "pi-plans",
+  "version": "0.1.0",
+  "description": "Human-in-the-loop planning extension for the Pi coding agent: researched, refined Markdown plans before any code changes.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "planning",
+    "extension"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaxInGaussian/pi-plans.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MaxInGaussian/pi-plans/issues"
+  },
+  "homepage": "https://github.com/MaxInGaussian/pi-plans#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.6"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills",
+      "./skills/debug-and-plan",
+      "./skills/plan-small",
+      "./skills/plan-normal",
+      "./skills/plan-big",
+      "./skills/plan-with-refs"
+    ]
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "index.ts",
+    "agents/",
+    "docs/assets",
+    "references/",
+    "scripts/",
+    "skills/",
+    "src/",
+    "tests/",
+    "tools/"
+  ],
+  "scripts": {
+    "validate": "node --experimental-strip-types scripts/validate.ts",
+    "test": "node --experimental-strip-types scripts/run-tests.ts",
+    "prepack": "npm run validate && npm test"
+  }
+}

package/references/pi-planning-workflow.md

@@ -0,0 +1,154 @@
+# Pi Planning Workflow
+
+This reference is shared by the `pi-plans` skills. It is a planning workflow only. Implementation after acceptance runs in the extension-managed execution loop.
+
+## Required Pi Context
+
+This skill set is written for the Pi coding agent's documented behavior:
+
+- the five skills are contributed by the pi-plans extension and loaded as Pi skills (also invokable as `/skill:<name>`);
+- skill references and helper sources are resolved relative to the directory containing `SKILL.md`;
+- the extension provides these tools: `plans` (workspace state), `ask_choice` (choice prompts), `refine` (reviewer/criticizer subagents), and `execute_plan` (execution handoff);
+- `refine` spawns read-only Pi subagents (`pi --mode json -p --no-session --tools read,grep,find,ls`) with isolated context; their results return to the main session as tool output;
+- the execution loop is extension-managed: remaining verifier items are injected each turn and `[DONE:VC-xxx]` markers are tracked with a footer progress widget.
+
+## Planning Boundary
+
+- Treat the user's request as a planning target, not as write authorization.
+- Before the execution handoff, do not edit target source files, docs, configs, package metadata, generated assets, or tests outside the planning artifact directory and the pi-plans state under `.git/pi_plans/`. The extension enforces this for `edit` and `write` while a run is active: only `.git/pi_plans/`, the run's artifact directory, and `~/.cache/pi-plans/` are writable. Bash is not machine-guarded — keep it read-only by discipline (inspection, `git init`, downloads into the cache).
+- The normal pre-handoff writes are `.git/pi_plans/` state plus planning artifacts under the configured artifact root (default `./docs/pi-plans/...`).
+- Large downloaded references belong outside the target repo by default, under `~/.cache/pi-plans/refs/<repo-slug>/<topic>/`; record their paths and evidence in `REF_ANALYSIS.md`.
+- After the user explicitly approves the execution handoff, leave this planning workflow and execute in the extension-managed loop (see Execution Handoff).
+
+## State And Settings
+
+Before the first planning question, read `references/state-and-config.md` and initialize the target workspace state with the `plans` tool:
+
+```json
+{ "action": "init", "workdir": "<target-workdir>" }
+```
+
+State lives under the workspace's resolved git common dir as `.git/pi_plans/` (auto-ignored, no `.gitignore` entries; the tool auto-runs `git init` when the workdir safely has no repository). The target workspace is the current working directory unless the user explicitly names another repository.
+
+If `language.tag` is missing from `.git/pi_plans/config.json`, ask the language setting question (via `ask_choice`) before any product question. Persist it with `plans` (`set-language`); this question does not count against the planning-question limit.
+
+If `artifact_root_source` is missing from `.git/pi_plans/config.json` or is `unset`, ask the planning docs location question (via `ask_choice`) before any product question. Persist it with `plans` (`set-artifact-root`); this question does not count against the planning-question limit.
+
+Reviewer and criticizer settings also live in `config.json`. If a role's mode is missing/invalid or its `confirmed_at` is `null` when the role is about to run, ask the matching role-setting or model-confirmation question (via `ask_choice`), persist with `plans` (`set-role`), and then run the `refine` tool. The `refine` tool refuses to spawn until the gates pass.
+
+## First-Turn Contract
+
+1. Inspect the target Git repository read-only before asking product questions. Prefer `rg`/`grep` when available, then focused file reads, `git status`, `git log`, existing tests, and user-provided logs.
+2. If a question can be answered from the repo, answer it from evidence instead of asking the user.
+3. After required language and planning-docs-location setup, the first user-facing planning response must be one `ask_choice` question, not a completed plan or implementation.
+4. Ask one question per message. Do not batch multiple decisions into one prompt.
+
+## Evidence Ladder
+
+Resolve unknowns in this order:
+
+1. Codebase evidence.
+2. Cited web or reference evidence.
+3. User choice.
+
+When the recommended option depends on a web-verifiable claim, search first (websearch skill when installed; otherwise `curl`, `gh`, or other bash tools already available) and cite the source in the eventual plan. Do not present a recommendation backed only by an unchecked assumption.
+
+## Choice Prompt Format
+
+Every user-facing planning or refinement question goes through the `ask_choice` tool:
+
+- `options`: ordered options, recommended option first with `recommended: true` (exactly one), each with the tradeoff that matters in `description`;
+- do not add `Other` or `Auto-complete` yourself — the tool appends `Other…` second-last and `Auto-complete` last;
+- pass `autoComplete: false` for the execution handoff and for any install waiver, publishing, deployment, merge, push, credential, or external-state question. Auto-complete may choose the recommended planning or refinement option only.
+
+Answers are recorded automatically in the active run's `decisions.jsonl`. You must still maintain `DECISIONS.md` in the artifact directory (summary table of questions, options, answers, answer sources, open assumptions).
+
+## Required Artifact Directory
+
+Create a run only after initial read-only inspection makes the topic clear:
+
+```json
+{ "action": "start-run", "workdir": "<target-workdir>", "topic": "<short topic>", "skill": "<skill-name>", "requestText": "<original request>" }
+```
+
+The tool creates the configured artifact directory root (default `./docs/pi-plans/YYYY-MM-DD-<topic>/`) and the private run state `.git/pi_plans/runs/<run-id>/`, and stores the active run pointer. Use a short lowercase slug for the topic. Keep paths stable once written.
+
+`DECISIONS.md` records: original request; repository evidence inspected; each question, options, selected answer, and whether it came from the user or Auto-complete; assumptions still open; external sources consulted; language, reviewer, and criticizer settings used.
+
+## Final Scope Confirmation
+
+Before writing `PLAN_v1.md`, ask the mandatory final scope confirmation via `ask_choice` (it does not count against the skill's planning-question limit):
+
+1. `No more requirements` — the scope is ready for `PLAN_v1.md` (recommended).
+2. `Add more requirements` — capture additional constraints before drafting.
+3. `Other`.
+4. `Auto-complete`.
+
+If the user adds requirements, resolve only the necessary follow-up questions, then repeat the final scope confirmation.
+
+## Plan Artifact Requirements
+
+Every `PLAN_vN.md` must include stable IDs that are never recycled across revisions: goals and non-goals; requirements and constraints; implementation items; affected paths; dependencies and sequencing; risks and mitigations; acceptance criteria; verification steps; repo and external evidence; resolved decisions; revision ledger.
+
+Every plan version must include a dedicated `## Verifier Checklist` section. Each item is a Markdown checkbox of the exact shape:
+
+```markdown
+- [ ] `VC-001` covers `I-001`; pass condition: ...; evidence: ...; metric: <threshold or reason not quantified>.
+```
+
+The execution loop parses `- [ ] \`VC-###\`` items and tracks `[DONE:VC-###]` markers, so keep IDs on the checkbox line. Use `references/plan-artifact-template.md` when drafting.
+
+## Refinement
+
+After each plan version, ask one refinement-mode question via `ask_choice`. The recommended (first) option follows the skill level's default sequence; the user may always pick a different mode or keep refining:
+
+- `plan-small`: recommend `Criticizer` for the first (and only default) round; afterwards recommend `Accept plan for tracked execution`.
+- `plan-normal`: recommend `Reviewer` first, then `Criticizer`; afterwards recommend `Accept plan for tracked execution`.
+- `plan-big`: recommend `Reviewer` first as three concurrent independent reviewers (`refine` with `reviewers: 3`), then `Criticizer`; afterwards recommend `Accept plan for tracked execution`.
+
+Option list for the question: the recommended next step; the other refinement modes with their tradeoffs; `Accept plan for tracked execution`; `Other`; `Auto-complete`.
+
+If the user selects `Reviewer` or `Criticizer`, run the `refine` tool with the plan path and any focus. Reviewer output consolidates into `PLAN_vN_reviewer_comments.md` with findings IDs, severity, affected plan IDs, evidence, impact, recommended fix, and disposition. Revise the next plan only for findings accepted on evidence.
+
+### Concurrent Reviewers (big plans)
+
+A big-plan reviewer round runs three independent reviewer subagents (`reviewers: 3`); each gets its own emphasis lens but forms its own priorities. After they return, merge and dedupe their findings into one consolidated `PLAN_vN_reviewer_comments.md`, keeping each finding's source reviewer, severity, evidence, and disposition, and surface at most five high-priority comments to the user. Treat agreement between independent reviewers as stronger evidence, not as authority; every accepted finding still needs repo or reference evidence.
+
+### Criticizer Rounds
+
+Present each criticizer question with `ask_choice` (one call per question, in the configured language). Before each question, summarize the original criticism in at most three sentences and highlight the most important point. Do not revise the plan until every criticizer question has a recorded answer.
+
+### Round Lifecycle
+
+A refinement round is complete when all reviewer outputs have returned or all criticizer questions have answers. In the same turn: consolidate, accept or reject each finding on evidence (the user may override any disposition), revise to `PLAN_v(N+1).md` when accepted items require it (copy, edit only the new version, update the revision ledger and verifier checklist), then immediately ask the next refinement-mode question. Never end a turn merely because a round completed.
+
+## Execution Handoff
+
+After the plan is accepted or refinement converges, ask the explicit execution-handoff question via `ask_choice` with `autoComplete: false`:
+
+1. `Execute this plan now` — enter the tracked execution loop (recommended once refinement converged).
+2. `Stop after planning` — keep the plan artifact only.
+3. `Other`.
+
+On approval, call the `execute_plan` tool (or the user runs `/plans-execute`). It re-confirms with the user, then the extension enters execution mode:
+
+- every agent turn is injected with the remaining verifier checklist and execution rules (ponytail discipline, minimum tests);
+- the read-only guard lifts: full write access returns;
+- the run status moves to `executing`, then `done` when the last `[DONE:VC-xxx]` marker lands;
+- `/plans-stop` stops execution; `/plans` shows progress.
+
+If the user declines, stay in planning (or stop, per their choice). Never start implementation without the approved handoff.
+
+## Red Flags
+
+Stop and return to the workflow if any of these happen:
+
+- implementing before the approved execution handoff;
+- running `refine` without first asking the refinement-mode question, or before the role gates pass;
+- ending a turn after a completed refinement round without asking the next refinement-mode question;
+- storing planning settings outside the target workspace's `.git/pi_plans/` state directory;
+- asking multiple planning questions in one message, or asking them outside `ask_choice`;
+- writing `PLAN_v1.md` before final scope confirmation;
+- accepting vague answers that contradict repo or reference evidence;
+- treating a reviewer or criticizer as authority instead of evidence;
+- offering Auto-complete for execution, install, deploy, merge, push, or destructive cleanup approval.

package/references/plan-artifact-template.md

@@ -0,0 +1,77 @@
+# PLAN_vN - <topic>
+
+Status: draft | reviewed | accepted
+Plan version: N
+Artifact directory: `<artifact_root>/YYYY-MM-DD-topic/`
+State directory: `.git/pi_plans/runs/<run-id>/` (resolved git common dir)
+Language: `<BCP47 tag>`
+
+## Original Request
+
+Summarize the user's request in one paragraph.
+
+## Goals
+
+- `G-001`: Goal statement.
+
+## Non-Goals
+
+- `NG-001`: Explicitly excluded work.
+
+## Workspace State
+
+- `STATE-001`: `.git/pi_plans/config.json` language, reviewer, and criticizer settings used for this run.
+- `STATE-002`: `.git/pi_plans/runs/<run-id>/run.json` and linked decision/subagent/ref ledgers.
+
+## Repo Evidence
+
+- `E-REPO-001`: Path or command inspected, what it proves, and any uncertainty.
+
+## External Evidence
+
+- `E-EXT-001`: URL or local ref path, what it supports, and date accessed.
+
+## Resolved Decisions
+
+- `D-001`: Question, chosen answer, answer source (user | Auto-complete), and rationale.
+
+## Requirements
+
+- `R-001`: Requirement tied to goals and decisions.
+
+## Constraints
+
+- `C-001`: Compatibility, style, interface, performance, safety, or ownership constraint.
+
+## Implementation Items
+
+- `I-001`: Work item with affected paths, dependencies, and expected code or doc changes.
+
+## Acceptance Criteria
+
+- `AC-001`: Observable result tied to one or more requirements.
+
+## Verification Plan
+
+- `V-001`: Command, manual check, screenshot, log review, or static inspection required after implementation.
+
+## Verifier Checklist
+
+- [ ] `VC-001` covers `I-001`; pass condition: describe pass condition; evidence: describe expected evidence; metric: threshold or reason not quantified.
+
+## Risks And Mitigations
+
+- `Risk-001`: Risk and mitigation.
+
+## Refinement Settings
+
+- Reviewer mode: `delegated-subagent | current-session`; model selector: `inherit | <selector>`.
+- Criticizer mode: `delegated-subagent | current-session`; model selector: `inherit | <selector>`.
+
+## Execution Handoff Notes
+
+State anything the executor should know, including order of work, files to avoid, and verification commands. The execution handoff still requires explicit user approval (ask_choice with `autoComplete: false`, then the `execute_plan` tool) and must never be auto-completed. Once approved, the extension-managed execution loop injects the remaining checklist every turn and completes when every `[DONE:VC-xxx]` marker has landed — keep this section concise enough to serve as the executor's brief.
+
+## Revision Ledger
+
+- `PLAN_v1`: Initial plan from resolved questions and evidence.