@hank-warren/pi-plan-mode 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @hank-warren/pi-plan-mode
 
+## 1.7.0
+
+### Minor Changes
+
+- 1035138: Ship the craft documents by injected path instead of as skills.
+
+  The `pi-loop` and `pi-plan-mode` skills are gone. Their bodies now ship as
+  `docs/loop-craft.md` and `docs/plan-craft.md`, and the mode prompts inject the
+  file's absolute path (resolved from the installed package) at the moments the
+  guidance matters: while a loop is being drafted or completed, and while Plan
+  Mode is active. A skill's description line sits in every system prompt of every
+  session with the package loaded; across ~220 sessions after these two shipped,
+  every read of either file was triggered by the mode's own prompt and never by
+  the description, so the line was a tax on the ~95% of sessions that never
+  entered the mode. Same document, read at the same moments, at zero cost outside
+  them. Hosts that referenced the skills by name in settings should drop those
+  entries.
+
+### Patch Changes
+
+- 1035138: Report a waiting question to Herdr as `blocked`.
+
+  `ask_user_question` and Plan Mode's `plan_mode_question` now emit the same
+  `herdr:blocked` event pi-auto-permissions emits for an approval prompt, labelled
+  `question` / `plan question` and cleared in a `finally`, so Herdr's pi
+  integration shows a session waiting on a question as `blocked` rather than
+  `working`. A supervising agent in another pane can wait on that state and answer
+  the dialog. No-op outside Herdr.
+
 ## 1.6.0
 
 ### Minor Changes

package/README.md

@@ -17,7 +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.
+- A shipped **plan-craft doc** the prompt points at by path, carrying the plan-crafting craft the prompt itself only names.
 
 ## 📦 Install
 
@@ -118,11 +118,11 @@ 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.
 
-## 📚 The companion skill
+## 📚 The plan-craft doc
 
-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.
+The system prompt is the enforcement surface and stays deliberately short. 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 — is [`docs/plan-craft.md`](docs/plan-craft.md), shipped with the package. One line in the planning prompt names it by absolute path (resolved from the installed package, so it works under any install layout), and the model reads it when Plan Mode opens.
 
-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.
+It used to be a skill. A skill's description line is in every system prompt, which buys exactly one thing an injected pointer cannot: the model proposing planning unprompted. Across ~220 sessions after it shipped, every read of the file happened after the Plan Mode prompt was already active, never off the description, and the model never suggested `/plan` on its own — so the line was a tax on every session that never planned (about 95% of them) that bought nothing. A hard path injected only while the mode is active is the same document at zero cost outside it.
 
 ## 📊 Statusline and widget
 
@@ -145,7 +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
+├── docs/plan-craft.md    # Plan-crafting depth, injected by path while the mode is active
 ├── test/
 ├── README.md
 ├── NOTICE.md
@@ -153,6 +153,10 @@ packages/pi-plan-mode/
 └── package.json
 ```
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
 ## 📄 License
 
 MIT. See [`LICENSE`](./LICENSE).

package/{skills/pi-plan-mode/SKILL.md → docs/plan-craft.md}

@@ -1,9 +1,3 @@
----
-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.

package/package.json

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

package/src/plan-mode.ts

@@ -52,6 +52,20 @@ import { type PlanModeState, restorePlanModeState } from "./state.js";
 
 const STATE_ENTRY_TYPE = "plan-mode-state";
 const ASK_USER_AVAILABILITY_EVENT = "hank:ask-user:availability";
+/** Label Herdr shows while `plan_mode_question` waits; distinguishes it from an approval. */
+export const HERDR_BLOCKED_LABEL = "plan question";
+
+/**
+ * Tell Herdr this pane is waiting on a human, so a supervising agent in another
+ * pane sees the block instead of reading a stalled turn as progress. Same
+ * contract as pi-auto-permissions' `setHerdrBlocked`, duplicated rather than
+ * imported so Plan Mode has no dependency on the permissions engine. No-op
+ * outside Herdr.
+ */
+function setHerdrBlocked(pi: ExtensionAPI, active: boolean): void {
+	if (process.env.HERDR_ENV !== "1") return;
+	pi.events.emit("herdr:blocked", active ? { active: true, label: HERDR_BLOCKED_LABEL } : { active: false });
+}
 /**
  * Plan mode's entire enforcement surface. Everything else — bash, subagents,
  * MCP, and other extension tools — is left to the session's normal permission
@@ -221,7 +235,11 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			return answerPlanModeQuestions(
 				parsed.questions,
 				ctx,
-				{ isCurrent: menu.isCurrent, isEnabled: () => state.enabled },
+				{
+					isCurrent: menu.isCurrent,
+					isEnabled: () => state.enabled,
+					onBlocked: (active) => setHerdrBlocked(pi, active),
+				},
 				questionSignal,
 			);
 		},

package/src/prompt.ts

@@ -1,3 +1,25 @@
+import { join } from "node:path";
+
+/**
+ * The plan-craft document: what decision-complete means, why exploration comes
+ * before questions, what separates a question worth asking from one the
+ * repository already answers, and what a finished plan contains.
+ *
+ * It used to ship as a skill. A skill buys one thing an injected pointer
+ * cannot: a description line in every system prompt, so the model could
+ * propose planning unprompted. Across ~220 sessions after it shipped, every
+ * read of the file happened after the Plan Mode prompt was already active —
+ * never off the description — and the model never suggested `/plan` on its
+ * own. So the line was a tax on every session that never planned (~95% of
+ * them) and bought nothing. An absolute path, injected only while Plan Mode
+ * is active, is the same document at zero cost outside it, and a hard path
+ * beats "if it is available".
+ *
+ * Resolved from this module's own location so it survives every install
+ * layout (git, npm, workspace symlink, `npm link`).
+ */
+export const PLAN_CRAFT_DOC = join(import.meta.dirname, "..", "docs", "plan-craft.md");
+
 const PLAN_CONTEXT_MARKER = "[PLAN MODE ACTIVE]";
 
 /** The built-in question tool. Used whenever nothing better is installed. */
@@ -71,7 +93,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.
+- Before planning, read ${PLAN_CRAFT_DOC}: 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/question-tool.ts

@@ -151,15 +151,32 @@ export function normalizePlanModeQuestionParams(
 export async function answerPlanModeQuestions(
 	questions: PlanModeQuestion[],
 	ctx: ExtensionContext,
-	lifecycle: { isCurrent(): boolean; isEnabled(): boolean },
+	lifecycle: {
+		isCurrent(): boolean;
+		isEnabled(): boolean;
+		/**
+		 * Called with `true` while a selector is open and `false` once it closes,
+		 * however it closes. plan-mode.ts forwards this to Herdr so a supervising
+		 * agent in another pane sees "blocked on a human", not "working".
+		 */
+		onBlocked?(active: boolean): void;
+	},
 	signal?: AbortSignal,
 ) {
-	const answers = await askPlanModeQuestions(
-		questions,
-		ctx,
-		() => lifecycle.isCurrent() && lifecycle.isEnabled() && !signal?.aborted,
-		signal,
-	);
+	lifecycle.onBlocked?.(true);
+	let answers: PlanModeQuestionAnswer[] | undefined;
+	try {
+		answers = await askPlanModeQuestions(
+			questions,
+			ctx,
+			() => lifecycle.isCurrent() && lifecycle.isEnabled() && !signal?.aborted,
+			signal,
+		);
+	} finally {
+		// In `finally` so a throw or a session replacement never leaves Herdr
+		// believing this pane is still waiting on someone.
+		lifecycle.onBlocked?.(false);
+	}
 	if (!lifecycle.isCurrent()) {
 		return planModeQuestionCancelled(
 			questions,