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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @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
+
+- 9dd9833: Remove the plan-mode thinking level. Plan mode no longer mutates session-global state: `pi.setThinkingLevel` writes through to the user's real settings, so the "temporary" level was a durable change that needed three shadow state fields, a `thinking_level_select` listener and restore logic on every exit path to undo. Thinking level and model are session settings now, and whatever you choose while planning carries into implementation. The `thinkingLevel` setting is gone and `/plan settings` drops its row; an existing key in `pi-plan-mode.json` is ignored rather than rejected — preserved verbatim on save, and no longer validated, so even a garbage value keeps the file loading. A one-shot migration restores the level an interrupted pre-1.3.0 session left raised, but only while the live level still matches what plan mode applied.
+
 ## 1.2.1
 
 ### Patch 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
 
@@ -78,20 +79,17 @@ The file is read at session start and **re-read whenever it changes**, so a hand
 
 ```json
 {
-  "thinkingLevel": "inherit",
   "defaultPlanExportPath": "PLAN.md"
 }
 ```
 
-### Plan thinking
-
-`thinkingLevel` requests a fixed thinking level while Plan mode is active. Supported values are `inherit`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. The extension restores your previous level on exit unless you changed it manually during Plan mode. Saving applies to the next Plan workflow, never one already running.
-
 ### Export destination
 
 `defaultPlanExportPath` controls only exports that omit a path, and defaults to `PLAN.md`. Relative values resolve against the current working directory at export time. An explicit `/plan export <path>` always wins. Export never overwrites an existing file, directory, or symbolic link.
 
-Unknown keys are preserved. Settings removed in 1.0 (`defaultPlanTools`, `bashPolicy`, `safeSubcommands`, `implementationPlanRetention`) are ignored rather than treated as errors, so an existing settings file keeps working.
+Unknown keys are preserved. Settings removed in 1.0 (`defaultPlanTools`, `bashPolicy`, `safeSubcommands`, `implementationPlanRetention`) and in 1.3 (`thinkingLevel`) are ignored rather than treated as errors, so an existing settings file keeps working.
+
+Thinking level and model are **session** settings, and Plan mode never changes either one. Set them with Pi's own controls; whatever you choose while planning carries into implementation, because that is what session state does.
 
 A settings file that does not parse is reported at session start and the defaults are used. Mid-session it is ignored instead, leaving the last good settings in place: an edit is seen the moment your editor touches the file, so an unreadable one is usually a half-finished save rather than what you meant.
 
@@ -120,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
+
+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.
+
+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 mode publishes a compact status for statuslines that render extension statuses:
+- `◆ 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.
 
-- `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.
+The widget adds a dim second line naming what to do next.
 
 ## 🗂️ Package layout
 
@@ -138,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.2.1",
+  "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/extension-runtime.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { PlanModeFixedThinkingLevel } from "./settings.js";
+import type { LegacyThinkingCapture } from "./state.js";
 
 type AgentSettledHandler = (event: unknown, ctx: ExtensionContext) => unknown;
 
@@ -11,8 +11,14 @@ export function onAgentSettled(pi: ExtensionAPI, handler: AgentSettledHandler) {
 	).on("agent_settled", handler);
 }
 
-export function setPlanThinkingLevel(pi: ExtensionAPI, level: PlanModeFixedThinkingLevel) {
-	(pi.setThinkingLevel as unknown as (level: PlanModeFixedThinkingLevel) => void)(level);
+/**
+ * Only the one-shot migration that undoes a pre-1.3.0 thinking-level change
+ * still calls this. Plan mode never sets the thinking level otherwise.
+ *
+ * legacy: delete in 1.4.0
+ */
+export function setPlanThinkingLevel(pi: ExtensionAPI, level: LegacyThinkingCapture["previous"]) {
+	(pi.setThinkingLevel as unknown as (level: string) => void)(level);
 }
 
 export function isStaleExtensionContextError(error: unknown) {

package/src/plan-mode.ts

@@ -46,12 +46,11 @@ import {
 } from "./question-tool.js";
 import {
 	awaitPlanModeSettingsWrites,
-	configuredThinkingLevel,
 	type PlanModeSettings,
 	planModeSettingsPath,
 	readPlanModeSettings,
 } from "./settings.js";
-import { type PlanModeState, restorePlanModeState } from "./state.js";
+import { type PlanModeState, readLegacyThinkingCapture, restorePlanModeState } from "./state.js";
 
 const STATE_ENTRY_TYPE = "plan-mode-state";
 /**
@@ -128,7 +127,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		return interactiveUiPromise;
 	};
 	let state: PlanModeState = { enabled: false, awaitingAction: false };
-	let settings: PlanModeSettings = { thinkingLevel: "inherit" };
+	let settings: PlanModeSettings = {};
 	let sessionPlanPath: string | undefined;
 	let readyPresentationNonce = 0;
 	let pendingReadyNonce: number | undefined;
@@ -334,7 +333,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		const loaded = await readRuntimeSettings();
 		if (generation !== menuGeneration || menuController.signal.aborted) return;
 		if (loaded.kind === "invalid" && !ctx) return;
-		settings = loaded.kind === "loaded" ? loaded.settings : { thinkingLevel: "inherit" };
+		settings = loaded.kind === "loaded" ? loaded.settings : {};
 		if (!ctx) return;
 		if (loaded.kind === "invalid") {
 			ctx.ui.notify(`pi-plan-mode settings ignored: ${loaded.reason}`, "warning");
@@ -390,9 +389,10 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		menuController = new AbortController();
 		pendingReadyNonce = undefined;
 		latestCommandContext = undefined;
-		settings = { thinkingLevel: "inherit" };
+		settings = {};
 		sessionPlanPath = resolveSessionPlanPath(ctx);
 		restoreState(ctx);
+		repairLegacyThinkingLevel(ctx);
 		await loadPlanModeSettings(generation, ctx);
 		if (generation !== menuGeneration || menuController.signal.aborted) return;
 		startPlanModeSettingsWatch(generation);
@@ -400,24 +400,10 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		if (persistFlagActivation) {
 			state = { ...state, enabled: true, awaitingAction: state.planPath !== undefined };
 		}
-		const capturedThinkingLevel = state.enabled ? applyPlanThinkingLevel() : false;
-		if (persistFlagActivation || capturedThinkingLevel) persistState();
+		if (persistFlagActivation) persistState();
 		updateUi(ctx);
 	});
 
-	pi.on("thinking_level_select", (event) => {
-		if (!state.enabled || !state.appliedThinkingLevel) return;
-		if (event.level !== state.appliedThinkingLevel) {
-			state = {
-				...state,
-				manualThinkingLevel: event.level,
-				previousThinkingLevel: undefined,
-				appliedThinkingLevel: undefined,
-			};
-			persistState();
-		}
-	});
-
 	pi.on("session_shutdown", async (_event, ctx) => {
 		menuGeneration += 1;
 		stopPlanModeSettingsWatch();
@@ -426,9 +412,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		latestCommandContext = undefined;
 		refreshStateBeforeFirstAgentStart = false;
 		await awaitPlanModeSettingsWrites(dependencies.settingsPath);
-		captureManualThinkingLevel();
 		persistState();
-		if (state.enabled) restoreThinkingLevel();
 		clearUi(ctx);
 	});
 
@@ -449,7 +433,6 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		if (refreshStateBeforeFirstAgentStart) {
 			refreshStateBeforeFirstAgentStart = false;
 			restoreState(ctx);
-			if (state.enabled && applyPlanThinkingLevel()) persistState();
 			updateUi(ctx);
 		}
 		if (state.enabled && state.awaitingAction) {
@@ -494,7 +477,6 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	function enterPlanMode(ctx: ExtensionContext) {
 		workflowGeneration += 1;
 		state = { ...state, enabled: true, awaitingAction: false };
-		applyPlanThinkingLevel();
 		persistState();
 		updateUi(ctx);
 	}
@@ -507,7 +489,6 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			ctx.ui.notify("Plan mode enabled. I will explore and plan, but not modify files.", "info");
 		}
 		if (sendPlanModeUserMessage(prompt, ctx)) return;
-		if (!wasEnabled) restoreThinkingLevel();
 		state = previousState;
 		persistState();
 		updateUi(ctx);
@@ -515,7 +496,6 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 
 	async function exitPlanMode(ctx: ExtensionContext, options: { keepPlanFile?: boolean } = {}) {
 		workflowGeneration += 1;
-		const wasEnabled = state.enabled;
 		const planPath = state.planPath;
 		pendingReadyNonce = undefined;
 		state = {
@@ -523,12 +503,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			enabled: false,
 			planPath: undefined,
 			awaitingAction: false,
-			manualThinkingLevel: undefined,
 		};
-		if (wasEnabled) {
-			restoreThinkingLevel();
-			state = { ...state, manualThinkingLevel: undefined };
-		}
 		persistState();
 		updateUi(ctx);
 		if (planPath && !options.keepPlanFile) await deletePlanFile(planPath);
@@ -600,25 +575,18 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 
 		workflowGeneration += 1;
 		const previousState = state;
-		const wasEnabled = state.enabled;
 		pendingReadyNonce = undefined;
 		state = {
 			...state,
 			enabled: false,
 			awaitingAction: false,
 			planPath,
-			manualThinkingLevel: undefined,
 		};
-		if (wasEnabled) {
-			restoreThinkingLevel();
-			state = { ...state, manualThinkingLevel: undefined };
-		}
 		persistState();
 		updateUi(ctx);
 
 		if (!sendPlanModeUserMessage(formatImplementationHandoff(planPath), ctx)) {
 			state = previousState;
-			if (wasEnabled) applyPlanThinkingLevel();
 			persistState();
 			updateUi(ctx);
 		}
@@ -707,66 +675,21 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	}
 
 	/**
-	 * Returns true when the captured thinking levels changed, so the restore
-	 * paths can persist that capture. It is the only record of the user's level:
-	 * `setPlanThinkingLevel` goes through Pi's `setThinkingLevel`, which writes
-	 * the new level into the user's settings, so a capture left only in memory is
-	 * lost if the session ends without `session_shutdown`.
+	 * pi-plan-mode <= 1.2.1 raised the thinking level while planning, and because
+	 * `pi.setThinkingLevel` writes through to the user's real settings, a session
+	 * that died before its restore left that change durable. If the newest state
+	 * entry still carries the capture and the live level still equals what Plan
+	 * mode applied, put the user's level back — once. Persisting state in the new
+	 * shape drops the capture, so the next session finds nothing to repair. A
+	 * user who has already moved the level themselves is left alone.
+	 *
+	 * legacy: delete in 1.4.0
 	 */
-	function applyPlanThinkingLevel(): boolean {
-		if (state.manualThinkingLevel) {
-			if (pi.getThinkingLevel() !== state.manualThinkingLevel) {
-				setPlanThinkingLevel(pi, state.manualThinkingLevel);
-			}
-			return false;
-		}
-		const configured = configuredThinkingLevel(settings);
-		if (!configured) {
-			if (state.previousThinkingLevel === undefined && state.appliedThinkingLevel === undefined) {
-				return false;
-			}
-			state = {
-				...state,
-				previousThinkingLevel: undefined,
-				appliedThinkingLevel: undefined,
-			};
-			return true;
-		}
-		const current = pi.getThinkingLevel();
-		const capturedPrevious = state.previousThinkingLevel;
-		const capturedApplied = state.appliedThinkingLevel;
-		if (!state.appliedThinkingLevel) state.previousThinkingLevel = current;
-		if (current !== configured) setPlanThinkingLevel(pi, configured);
-		state.appliedThinkingLevel = pi.getThinkingLevel();
-		return (
-			state.previousThinkingLevel !== capturedPrevious ||
-			state.appliedThinkingLevel !== capturedApplied
-		);
-	}
-
-	function captureManualThinkingLevel() {
-		if (!state.appliedThinkingLevel) return;
-		const current = pi.getThinkingLevel();
-		if (current === state.appliedThinkingLevel) return;
-		state = {
-			...state,
-			manualThinkingLevel: current,
-			previousThinkingLevel: undefined,
-			appliedThinkingLevel: undefined,
-		};
-	}
-
-	function restoreThinkingLevel() {
-		captureManualThinkingLevel();
-		const { appliedThinkingLevel, previousThinkingLevel } = state;
-		if (
-			appliedThinkingLevel &&
-			previousThinkingLevel &&
-			pi.getThinkingLevel() === appliedThinkingLevel
-		) {
-			setPlanThinkingLevel(pi, previousThinkingLevel);
-		}
-		state = { ...state, appliedThinkingLevel: undefined, previousThinkingLevel: undefined };
+	function repairLegacyThinkingLevel(ctx: ExtensionContext) {
+		const legacy = readLegacyThinkingCapture(ctx.sessionManager.getBranch(), STATE_ENTRY_TYPE);
+		if (!legacy || pi.getThinkingLevel() !== legacy.applied) return;
+		setPlanThinkingLevel(pi, legacy.previous);
+		persistState();
 	}
 
 	function resolveSessionPlanPath(ctx: ExtensionContext) {

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.

package/src/settings-menu.ts

@@ -1,9 +1,9 @@
+import { readFile } from "node:fs/promises";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { defineMenu, type RunMenuResult, runMenu } from "@narumitw/pi-tui-kit";
 import { planExportDestination } from "./plan-export.js";
 import {
 	configuredPlanExportPath,
-	PLAN_MODE_THINKING_LEVELS,
 	type PlanModeSettings,
 	type PlanModeSettingsLoadResult,
 	type PlanModeSettingsPatch,
@@ -18,6 +18,8 @@ interface SettingsMenuState {
 	settings: PlanModeSettings;
 	notice?: string;
 	reason?: string;
+	/** The removed `thinkingLevel` key is still in the file. legacy: delete in 1.4.0 */
+	hasLegacyThinkingLevel?: boolean;
 }
 
 export interface PlanModeSettingsMenuOptions {
@@ -34,7 +36,7 @@ export interface PlanModeSettingsMenuOptions {
 }
 
 type Screen = "settings" | "export";
-type Action = "set-thinking" | "open-export" | "set-export";
+type Action = "open-export" | "set-export";
 
 export async function showPlanModeSettings(
 	ctx: ExtensionContext,
@@ -49,15 +51,16 @@ export async function showPlanModeSettings(
 		if (loaded.kind === "invalid") {
 			return {
 				kind: "invalid",
-				settings: { thinkingLevel: "inherit" },
+				settings: {},
 				notice: loaded.notice,
 				reason: loaded.reason,
 			};
 		}
 		return {
 			kind: "valid",
-			settings: loaded.kind === "loaded" ? loaded.settings : { thinkingLevel: "inherit" },
+			settings: loaded.kind === "loaded" ? loaded.settings : {},
 			notice: loaded.notice,
+			hasLegacyThinkingLevel: await hasLegacyThinkingLevel(settingsPath),
 		};
 	};
 
@@ -70,16 +73,8 @@ export async function showPlanModeSettings(
 					: {
 							kind: "settings",
 							title: "Plan Mode Settings",
-							lines: settingsLines(settingsPath, state.notice),
+							lines: settingsLines(settingsPath, state),
 							items: [
-								{
-									id: "thinkingLevel",
-									label: "Plan thinking",
-									description: "Set the thinking level when the next Plan workflow starts.",
-									currentValue: state.settings.thinkingLevel,
-									values: PLAN_MODE_THINKING_LEVELS,
-									action: "set-thinking",
-								},
 								{
 									id: "defaultPlanExportPath",
 									label: "Export destination",
@@ -107,19 +102,6 @@ export async function showPlanModeSettings(
 			},
 		},
 		actions: {
-			"set-thinking": async ({ ctx: actionCtx, value, signal }) => {
-				if (
-					!PLAN_MODE_THINKING_LEVELS.includes(value as (typeof PLAN_MODE_THINKING_LEVELS)[number])
-				) {
-					return { kind: "rejected" };
-				}
-				return savePatch(
-					actionCtx,
-					{ thinkingLevel: value as PlanModeSettings["thinkingLevel"] },
-					signal,
-					`Plan mode thinking level: ${value}. Applies to the next Plan workflow.`,
-				);
-			},
 			"open-export": async () => ({ kind: "to", screen: "export" }),
 			"set-export": async ({ ctx: actionCtx, value, signal }) => {
 				const defaultPlanExportPath = value?.trim() || null;
@@ -171,14 +153,35 @@ export async function showPlanModeSettings(
 	}
 }
 
-function settingsLines(settingsPath: string, notice: string | undefined) {
+function settingsLines(settingsPath: string, state: SettingsMenuState) {
 	return [
 		`User settings · ${safeTerminalText(settingsPath)}`,
-		"Plan thinking applies to the next workflow; the export destination applies to its next action.",
-		...(notice ? [safeTerminalText(notice)] : []),
+		"The export destination applies to its next action.",
+		// legacy: delete in 1.4.0
+		...(state.hasLegacyThinkingLevel
+			? [
+					"thinkingLevel is no longer used — thinking is a session setting and Plan mode never changes it.",
+				]
+			: []),
+		...(state.notice ? [safeTerminalText(state.notice)] : []),
 	];
 }
 
+/**
+ * The removed key is preserved verbatim on save, so the only way to know it is
+ * still there is to look at the file. A read failure simply hides the notice.
+ *
+ * legacy: delete in 1.4.0
+ */
+async function hasLegacyThinkingLevel(settingsPath: string) {
+	try {
+		const parsed: unknown = JSON.parse(await readFile(settingsPath, "utf8"));
+		return typeof parsed === "object" && parsed !== null && Object.hasOwn(parsed, "thinkingLevel");
+	} catch {
+		return false;
+	}
+}
+
 function invalidScreen(settingsPath: string, state: SettingsMenuState) {
 	return {
 		kind: "detail" as const,

package/src/settings.ts

@@ -7,27 +7,13 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 export const PLAN_MODE_SETTINGS_FILE = "pi-plan-mode.json";
 const LEGACY_PLAN_MODE_SETTINGS_FILE = "plan-mode.json";
 const MAX_SETTINGS_BYTES = 64 * 1024;
-export const PLAN_MODE_THINKING_LEVELS = [
-	"inherit",
-	"off",
-	"minimal",
-	"low",
-	"medium",
-	"high",
-	"xhigh",
-	"max",
-] as const;
 export const DEFAULT_PLAN_EXPORT_PATH = "PLAN.md";
 const MAX_PLAN_EXPORT_PATH_LENGTH = 4096;
 
-export type PlanModeThinkingLevel = (typeof PLAN_MODE_THINKING_LEVELS)[number];
-export type PlanModeFixedThinkingLevel = Exclude<PlanModeThinkingLevel, "inherit">;
 export interface PlanModeSettings {
-	thinkingLevel: PlanModeThinkingLevel;
 	defaultPlanExportPath?: string;
 }
 export interface PlanModeSettingsPatch {
-	thinkingLevel?: PlanModeThinkingLevel;
 	defaultPlanExportPath?: string | null;
 }
 export interface UpdatePlanModeSettingsOptions {
@@ -59,21 +45,13 @@ function legacyPlanModeSettingsPath() {
 
 /**
  * Unknown top-level keys are tolerated and preserved on save. Settings removed
- * in the plan-file rewrite (defaultPlanTools, bashPolicy, safeSubcommands,
- * implementationPlanRetention) therefore keep an existing file valid instead of
- * failing it closed on upgrade.
+ * over time (defaultPlanTools, bashPolicy, safeSubcommands,
+ * implementationPlanRetention, thinkingLevel) therefore keep an existing file
+ * valid instead of failing it closed on upgrade.
  */
 export function normalizePlanModeSettings(value: unknown): PlanModeSettings | undefined {
 	if (!isSettingsDocument(value)) return undefined;
-	const thinkingLevel = Object.hasOwn(value, "thinkingLevel")
-		? Reflect.get(value, "thinkingLevel")
-		: "inherit";
-	if (!PLAN_MODE_THINKING_LEVELS.includes(thinkingLevel as PlanModeThinkingLevel)) {
-		return undefined;
-	}
-	const settings: PlanModeSettings = {
-		thinkingLevel: thinkingLevel as PlanModeThinkingLevel,
-	};
+	const settings: PlanModeSettings = {};
 	if (Object.hasOwn(value, "defaultPlanExportPath")) {
 		const defaultPlanExportPath = normalizePlanExportPath(
 			Reflect.get(value, "defaultPlanExportPath"),
@@ -143,7 +121,6 @@ export function updatePlanModeSettings(
 		options.signal?.throwIfAborted();
 		const current = await readSettingsDocumentForUpdate(settingsPath, legacySettingsPath);
 		const updated: SettingsDocument = { ...current };
-		if (patch.thinkingLevel !== undefined) updated.thinkingLevel = patch.thinkingLevel;
 		if (patch.defaultPlanExportPath === null) delete updated.defaultPlanExportPath;
 		else if (patch.defaultPlanExportPath !== undefined) {
 			updated.defaultPlanExportPath = patch.defaultPlanExportPath;
@@ -310,12 +287,6 @@ function safeReadError(error: unknown) {
 	return error instanceof Error ? error.message : String(error);
 }
 
-export function configuredThinkingLevel(
-	settings: PlanModeSettings,
-): PlanModeFixedThinkingLevel | undefined {
-	return settings.thinkingLevel === "inherit" ? undefined : settings.thinkingLevel;
-}
-
 export function configuredPlanExportPath(settings: PlanModeSettings) {
 	return settings.defaultPlanExportPath ?? DEFAULT_PLAN_EXPORT_PATH;
 }

package/src/state.ts

@@ -1,8 +1,7 @@
-import { PLAN_MODE_THINKING_LEVELS, type PlanModeFixedThinkingLevel } from "./settings.js";
-
 /**
- * The plan lives on disk, so session state carries only a pointer to it plus
- * the thinking-level bookkeeping needed to restore the user's level on exit.
+ * The plan lives on disk, so session state carries only a pointer to it and
+ * the ready-for-action flag. Plan mode holds no session-global state of its
+ * own: thinking level and model are session settings it never touches.
  */
 export interface PlanModeState {
 	enabled: boolean;
@@ -10,9 +9,6 @@ export interface PlanModeState {
 	planPath?: string;
 	/** A completed plan is waiting for the user to choose how to proceed. */
 	awaitingAction: boolean;
-	previousThinkingLevel?: PlanModeFixedThinkingLevel;
-	appliedThinkingLevel?: PlanModeFixedThinkingLevel;
-	manualThinkingLevel?: PlanModeFixedThinkingLevel;
 }
 
 type SessionEntry = {
@@ -22,15 +18,7 @@ type SessionEntry = {
 };
 
 export function restorePlanModeState(entries: unknown[], stateEntryType: string): PlanModeState {
-	const branch = entries as SessionEntry[];
-	let entry: SessionEntry | undefined;
-	for (let index = branch.length - 1; index >= 0; index -= 1) {
-		const candidate = branch[index];
-		if (candidate?.type === "custom" && candidate.customType === stateEntryType) {
-			entry = candidate;
-			break;
-		}
-	}
+	const entry = newestStateEntry(entries, stateEntryType);
 	if (!isRecord(entry?.data)) return { enabled: false, awaitingAction: false };
 
 	const enabled = entry.data.enabled === true;
@@ -39,14 +27,54 @@ export function restorePlanModeState(entries: unknown[], stateEntryType: string)
 		enabled,
 		planPath,
 		awaitingAction: enabled && entry.data.awaitingAction === true && planPath !== undefined,
-		previousThinkingLevel: enabled
-			? fixedThinkingLevel(entry.data.previousThinkingLevel)
-			: undefined,
-		appliedThinkingLevel: enabled ? fixedThinkingLevel(entry.data.appliedThinkingLevel) : undefined,
-		manualThinkingLevel: enabled ? fixedThinkingLevel(entry.data.manualThinkingLevel) : undefined,
 	};
 }
 
+function newestStateEntry(entries: unknown[], stateEntryType: string): SessionEntry | undefined {
+	const branch = entries as SessionEntry[];
+	for (let index = branch.length - 1; index >= 0; index -= 1) {
+		const candidate = branch[index];
+		if (candidate?.type === "custom" && candidate.customType === stateEntryType) return candidate;
+	}
+	return undefined;
+}
+
+// legacy: delete in 1.4.0
+const LEGACY_THINKING_LEVELS = [
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max",
+] as const;
+
+// legacy: delete in 1.4.0
+export type LegacyThinkingCapture = {
+	previous: (typeof LEGACY_THINKING_LEVELS)[number];
+	applied: (typeof LEGACY_THINKING_LEVELS)[number];
+};
+
+/**
+ * Reads the thinking-level capture written by pi-plan-mode <= 1.2.1, so a
+ * session interrupted while Plan mode held a raised level can have the user's
+ * level put back once. Both halves must be present and valid: a partial or
+ * absent capture is nothing to repair.
+ *
+ * legacy: delete in 1.4.0
+ */
+export function readLegacyThinkingCapture(
+	entries: unknown[],
+	stateEntryType: string,
+): LegacyThinkingCapture | undefined {
+	const entry = newestStateEntry(entries, stateEntryType);
+	if (!isRecord(entry?.data)) return undefined;
+	const previous = legacyThinkingLevel(entry.data.previousThinkingLevel);
+	const applied = legacyThinkingLevel(entry.data.appliedThinkingLevel);
+	return previous && applied ? { previous, applied } : undefined;
+}
+
 /**
  * Persisted paths are only trusted when they are absolute and free of NUL, so
  * malformed state can never redirect a read or a delete to a relative target.
@@ -58,11 +86,11 @@ function absolutePath(value: unknown) {
 	return normalized;
 }
 
-function fixedThinkingLevel(value: unknown): PlanModeFixedThinkingLevel | undefined {
+// legacy: delete in 1.4.0
+function legacyThinkingLevel(value: unknown): (typeof LEGACY_THINKING_LEVELS)[number] | undefined {
 	return typeof value === "string" &&
-		value !== "inherit" &&
-		PLAN_MODE_THINKING_LEVELS.includes(value as (typeof PLAN_MODE_THINKING_LEVELS)[number])
-		? (value as PlanModeFixedThinkingLevel)
+		LEGACY_THINKING_LEVELS.includes(value as (typeof LEGACY_THINKING_LEVELS)[number])
+		? (value as (typeof LEGACY_THINKING_LEVELS)[number])
 		: undefined;
 }