@hank-warren/pi-plan-mode 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @hank-warren/pi-plan-mode
 
+## 1.4.0
+
+### Minor Changes
+
+- 449f989: Ships a companion `pi-plan-mode` skill, making this a hybrid package: the system prompt stays the short enforcement surface and points at the skill for the plan-crafting craft — what decision-complete means, exploring before asking, what separates a question worth asking from one the repository already answers, and what a finished plan contains.
+
+  The footer status and the editor widget now render from one formatter, so they cannot drift, in a glyph vocabulary shared with `pi-loop`: `◆ plan · drafting`, `◆ plan · revising`, `◆ plan · ready → /plan`, `▶ plan · implementing`, each with a dim hint line in the widget. Statuslines that render extension statuses will show the new strings in place of `plan active` / `plan ready` / `plan implementing`.
+
 ## 1.3.0
 
 ### Minor Changes

package/README.md

@@ -17,6 +17,7 @@ The plan is written to a **durable file** that survives compaction, survives res
 - Two ways to implement: continue in this conversation, or open a fresh session that reads the same file.
 - `/plan export [path]` copies the plan anywhere, never overwriting an existing target.
 - Hand-edit the plan file at any time; every command and both implementation paths read from disk.
+- A companion `pi-plan-mode` **skill**, loaded on demand, carrying the plan-crafting craft the prompt only points at.
 
 ## 📦 Install
 
@@ -117,13 +118,22 @@ Detection is by tool name at runtime, re-evaluated every turn — there is no de
 
 A standalone `pi-plan-mode` install loses nothing: `plan_mode_question` stays fully functional and the prompt reads exactly as it always has. It is a **legacy fallback** and is slated for removal in a future major.
 
-## 📊 Statusline
+## 📚 The companion skill
 
-Plan mode publishes a compact status for statuslines that render extension statuses:
+The package ships a `pi-plan-mode` skill (`skills/pi-plan-mode/SKILL.md`) alongside the extension. The system prompt is the enforcement surface and stays deliberately short; the skill is the depth layer it points at — what decision-complete actually means, why exploration comes before questions, what separates a question worth asking from one the repository already answered, and what belongs in a finished plan. One line in the planning prompt names it, and the model loads the body when it judges it needs it.
 
-- `plan active` — planning is under way.
-- `plan ready` — a completed plan is waiting for your choice.
-- `plan implementing` — a plan file is active and guiding implementation.
+Skill and extension version as one artifact: a skill describing a mode the installed extension does not have is a coupling failure waiting to happen.
+
+## 📊 Statusline and widget
+
+The footer status and the widget above the editor render from **one formatter**, so they cannot drift, and they share a glyph vocabulary with the sibling [`pi-loop`](../pi-loop): `◆` for a state wanting a decision, `▶` for work under way.
+
+- `◆ plan · drafting` — planning is under way.
+- `◆ plan · revising` — feedback superseded a completed plan; the stored one is not current.
+- `◆ plan · ready → /plan` — a completed plan is waiting for your choice.
+- `▶ plan · implementing` — a plan file is active and guiding implementation.
+
+The widget adds a dim second line naming what to do next.
 
 ## 🗂️ Package layout
 
@@ -135,6 +145,7 @@ packages/pi-plan-mode/
 │   ├── plan-file.ts      # Durable plan file read/write/delete
 │   ├── interactive-ui.ts # Lazily loaded interactive menus
 │   └── *.ts              # Prompt, question, export, settings modules
+├── skills/pi-plan-mode/  # Companion plan-crafting skill
 ├── test/
 ├── README.md
 ├── NOTICE.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-plan-mode",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Plan mode for Pi: research and design with a durable plan file that survives compaction.",
   "type": "module",
   "keywords": [
@@ -27,11 +27,15 @@
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "./skills/pi-plan-mode"
     ]
   },
   "files": [
     "index.ts",
     "src",
+    "skills",
     "README.md",
     "NOTICE.md",
     "LICENSE",

package/skills/pi-plan-mode/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: pi-plan-mode
+description: Craft decision-complete implementation plans in Plan mode — explore before asking, ask questions worth answering, and write a plan another agent can execute without guessing. Use while Plan mode is active, before calling plan_mode_complete, and when deciding whether a request needs a plan at all.
+license: MIT
+---
+
+# pi-plan-mode
+
+The extension enforces the mechanics: `edit` and `write` are blocked, the plan is written to a durable file, and `plan_mode_complete` is the only way out. It cannot enforce the thing that decides whether the plan was worth making: **whether a competent implementer could execute it without asking you anything.** That is this file.
+
+## What "decision-complete" means
+
+A plan is finished when every decision it depends on has been made — by discovery, by the user, or by an explicitly recorded assumption. It is not finished when it is long, well organised, or reads confidently.
+
+The test: hand the plan to someone who was not in the conversation. Every place they would have to stop and ask "which one?" is an unresolved decision, and every one of those is a defect. That includes:
+
+- which of two plausible approaches is being taken, and why the other was rejected;
+- the names and shapes of anything new — files, functions, types, settings keys, tool parameters;
+- what happens on failure, and what happens to state that already exists;
+- how the change is verified, in the form of the commands to run and what they should print;
+- what deliberately stays out of scope.
+
+An unresolved decision hidden behind a confident sentence is worse than an open question, because nobody will notice it until implementation stalls.
+
+## Phase 1: explore before asking
+
+Read the repository first, every time. Questions are expensive — they cost the user's attention and they interrupt — so spend them only on what the code cannot tell you.
+
+Facts the environment owns: what already exists, how the neighbours solve the same problem, what the tests cover, what conventions the repo files and `AGENTS.md` impose, what versions are pinned, what a command actually prints. **Never ask about any of them.** A question whose answer was one `rg` away tells the user you did not look, and it trains them to stop answering carefully.
+
+Facts the environment does not own, and only the user does: product intent, priorities and tradeoffs, what "good enough" means here, which of two acceptable designs they want to live with, whether a breaking change is acceptable, deadlines and blast-radius tolerance.
+
+Exploration also earns the right to disagree. A plan that says "this repo already does X three times, so the fourth should match" is grounded; one that invents a new pattern in a codebase that already has one is a plan the reviewer has to fight.
+
+## Phase 2: ask questions worth answering
+
+Use the question tool for the decisions that are genuinely the user's. Good questions share a shape:
+
+- **The options are real and mutually exclusive.** If one option is obviously right, it is not a question — it is a decision, and you should state it and move on.
+- **Each option says what happens if it is chosen**, not just what it is called. "Store it in the session entry (survives restart, costs a write per turn)" is a choice; "session entry" is a label.
+- **The recommendation comes first and is marked**, so a user who trusts you can answer in one keystroke and one who does not has the alternatives in front of them.
+- **The question is answerable without reading the codebase.** If answering it requires knowing what a function currently does, that is your job, not theirs.
+
+Batch decisions that belong to one choice into one call rather than dripping them out over several turns, and stop asking as soon as the remaining ambiguity is low-impact. When the user declines to answer, do not silently pick: state the default you are taking, mark it as an assumption in the plan, and keep the alternative visible.
+
+A high-impact ambiguity is a reason to keep planning, never a reason to write a plan that hedges. A plan with two branches in it is two plans and nobody's decision.
+
+## Phase 3: write the plan
+
+The plan is read by a human deciding whether to approve it and by an agent executing it. Both want the same thing: grouped, behaviour-level changes with the reasoning attached.
+
+Structure that works:
+
+- **Title and a short summary** — what changes and why, in a few sentences.
+- **The approach**, including the alternatives considered and why they lost. This is the part that survives contact with the implementation; the file list is not.
+- **Behaviour, interface, and data changes** — what a caller or user sees differently, and what the new names and shapes are.
+- **Edge cases and failure modes**, including what happens to existing state and how the change behaves on a host that has the old version.
+- **Verification** — the commands to run and what they should print, plus the manual checks that no command covers.
+- **Assumptions and defaults chosen** — every place you decided rather than asked, stated plainly so it can be corrected.
+
+What to leave out: file-by-file or symbol-by-symbol inventories, restatements of the conversation, and speculative future work. A plan is a decision record, not a diff written in prose.
+
+Prefer specifics over adjectives. "Add a `groundRules?: string[]` to the persisted state, normalized on read, dropped when empty" is a plan; "improve state handling" is a mood.
+
+## Ending a turn, and ending the mode
+
+Every planning turn ends in exactly one of two ways: a question, or `plan_mode_complete` called alone as the final action with the whole plan. Never end with prose announcing that a plan is coming — that costs a whole turn and produces nothing.
+
+On revision, the next `plan_mode_complete` carries a **complete replacement**, not a delta. If you cannot write a complete replacement yet, keep planning and ask instead.
+
+Once the plan is completed the user chooses what happens from the `/plan` menu: implement here, implement in a fresh session that reads the same file, export it, or discard it. The file is the source of truth from then on — it survives compaction, and the user may have hand-edited it, so re-read it before implementing rather than working from memory of what you wrote.
+
+## When a plan is the wrong tool
+
+Plan mode is for work whose *shape* is uncertain. It is overhead when it is not:
+
+- **A single obvious change** — make it. A plan for a one-line fix costs more than the fix.
+- **Pure investigation with no change in view** — investigate in the conversation. Plan mode blocks the tools that would let you experiment, and there is nothing to decide yet.
+- **Work whose difficulty is execution, not design** ("run this migration on 40 hosts") → the interesting part is a runbook and a rollout order, not a design decision.
+
+Say so in one line and offer the alternative rather than producing a plan nobody needed.

package/src/presentation.ts

@@ -1,3 +1,4 @@
+import { Text } from "@earendil-works/pi-tui";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { readPlanFile } from "./plan-file.js";
 import type { PlanModeState } from "./state.js";
@@ -5,25 +6,111 @@ import type { PlanModeState } from "./state.js";
 const STATUS_KEY = "plan-mode";
 const PLAN_WIDGET_KEY = "plan-mode-plan";
 
+/**
+ * The one thing both surfaces render.
+ *
+ * The footer and the widget say the same thing in two sizes, so they are
+ * formatted once. When each formatted its own they drifted — the sibling
+ * pi-loop shipped a loop that read as "waiting" in the footer and "running"
+ * above the editor for exactly that reason, and this is the same shape of
+ * bug waiting to happen with "ready" and "implementing".
+ *
+ * The glyphs are the family vocabulary shared with pi-loop by convention
+ * rather than by import: `◆` planning or ready, `▶` implementing. Six
+ * characters do not justify a shared package; a user reading a footer
+ * justifies the consistency.
+ */
+export type PlanModePhase = "drafting" | "revising" | "ready" | "implementing";
+
+export interface PlanModeView {
+	phase: PlanModePhase;
+	/** The footer line: plain text with a glyph, no colour. */
+	footer: string;
+	/** The widget's headline, rendered bold and themed. */
+	headline: string;
+	/** The dim second line: what to do next. */
+	hint: string;
+	/** Accent while the plan wants a decision; normal once it is being built. */
+	tone: "accent" | "normal";
+}
+
+export function planModeView(state: PlanModeState): PlanModeView | undefined {
+	if (state.enabled) {
+		if (state.awaitingAction) {
+			return {
+				phase: "ready",
+				footer: "◆ plan · ready → /plan",
+				headline: "◆ plan · proposed plan ready",
+				hint: "/plan to implement, export, or exit — or type feedback to revise.",
+				tone: "accent",
+			};
+		}
+		// A stored plan with no pending action means feedback superseded it: the
+		// plan on disk is no longer what is being offered, and saying "drafting"
+		// would hide that a completed plan is being replaced.
+		if (state.planPath) {
+			return {
+				phase: "revising",
+				footer: "◆ plan · revising",
+				headline: "◆ plan · revising the proposed plan",
+				hint: "The stored plan is superseded until the next plan_mode_complete.",
+				tone: "accent",
+			};
+		}
+		return {
+			phase: "drafting",
+			footer: "◆ plan · drafting",
+			headline: "◆ plan · drafting",
+			hint: "Explore and ask; finish with plan_mode_complete when decision-ready.",
+			tone: "accent",
+		};
+	}
+	if (state.planPath) {
+		return {
+			phase: "implementing",
+			footer: "▶ plan · implementing",
+			headline: "▶ plan · implementing",
+			hint: "/plan to show, replace, or clear the active plan.",
+			tone: "normal",
+		};
+	}
+	return undefined;
+}
+
+/**
+ * The slice of Pi's theme this widget uses. Structural rather than imported so
+ * the renderer keeps working against a host whose theme carries neither
+ * helper: both are optional, and an absent one degrades to plain text.
+ */
+interface WidgetTheme {
+	bold?: (text: string) => string;
+	fg?: (color: string, text: string) => string;
+}
+
+type WidgetFactory = Parameters<ExtensionContext["ui"]["setWidget"]>[1];
+
 export function updatePlanModeUi(ctx: ExtensionContext, state: PlanModeState) {
-	ctx.ui.setStatus(STATUS_KEY, formatStatus(state));
-	if (state.enabled && state.awaitingAction) {
-		ctx.ui.setWidget(PLAN_WIDGET_KEY, [
-			"Proposed plan ready",
-			"Use /plan to implement, export, or exit — or type feedback to revise.",
-		]);
-	} else if (state.enabled) {
-		ctx.ui.setWidget(PLAN_WIDGET_KEY, [
-			"Plan mode: planning",
-			"Finish with plan_mode_complete when decision-ready.",
-		]);
-	} else if (state.planPath) {
-		ctx.ui.setWidget(PLAN_WIDGET_KEY, [
-			"Implementation plan active",
-			"Use /plan to show, replace, or clear it.",
-		]);
-	} else {
+	const view = planModeView(state);
+	ctx.ui.setStatus(STATUS_KEY, view?.footer);
+	if (!view) {
 		ctx.ui.setWidget(PLAN_WIDGET_KEY, undefined);
+		return;
+	}
+	try {
+		const render = (_tui: unknown, rawTheme: unknown) => {
+			const theme = (rawTheme ?? {}) as WidgetTheme;
+			const bold = theme.bold ?? ((text: string) => text);
+			const headline =
+				view.tone === "accent"
+					? (theme.fg?.("accent", bold(view.headline)) ?? bold(view.headline))
+					: bold(view.headline);
+			const hint = theme.fg?.("dim", `  ${view.hint}`) ?? `  ${view.hint}`;
+			return new Text(`${headline}\n${hint}`);
+		};
+		ctx.ui.setWidget(PLAN_WIDGET_KEY, render as WidgetFactory);
+	} catch {
+		// Presentation only: a host without the component form of setWidget (or a
+		// render failure) must never take Plan mode's state transitions with it.
 	}
 }
 
@@ -79,6 +166,7 @@ export function showPlanModePlan(
 	}
 }
 
+/** The sentence form, for menus, notifications, and non-TUI modes. */
 export function planModeStatusText(state: PlanModeState) {
 	if (state.enabled) {
 		if (state.awaitingAction) return "Plan mode is active and a proposed plan is ready.";
@@ -90,9 +178,3 @@ export function planModeStatusText(state: PlanModeState) {
 	if (state.planPath) return "An implementation plan is active.";
 	return "Plan mode is off.";
 }
-
-function formatStatus(state: PlanModeState) {
-	if (state.enabled) return state.awaitingAction ? "plan ready" : "plan active";
-	if (state.planPath) return "plan implementing";
-	return undefined;
-}

package/src/prompt.ts

@@ -51,6 +51,7 @@ You are in Plan Mode, a collaboration mode for producing a decision-complete imp
 
 ## Mode rules
 
+- Read the pi-plan-mode skill before planning if it is available: it carries the plan-crafting craft — decision-completeness, exploring before asking, question quality, and what a finished plan contains.
 - Stay in Plan Mode until a developer or extension explicitly exits it.
 - Treat requests to implement as requests to plan the implementation; do not edit files or carry out the plan.
 - Do not use todo/checklist tooling to track execution progress in Plan Mode; Plan Mode is conversational planning, and the plan itself belongs in plan_mode_complete.