@bacnh85/pi-plan 0.1.1

package/README.md

@@ -0,0 +1,74 @@
+# pi-plan
+
+Pi extension that adds a lightweight plan mode inspired by Codex and Claude Code:
+
+- Toggle plan mode with `/plan`, `/plan on`, `/plan off`, or `Ctrl+Alt+P`.
+- Pick separate thinking/reasoning levels for planning and normal execution with `/plan levels`.
+- Keeps planning read-only by disabling built-in `edit`/`write` and blocking destructive shell commands.
+- Provides a `write_plan` tool so the agent writes reviewable Markdown plans into `.agents/plans/` in the current workspace.
+- Prompts after a plan is written so you can approve execution, approve only, keep planning, or refine with feedback.
+
+## Install
+
+From npm after the package is published:
+
+```bash
+pi install npm:@bacnh85/pi-plan
+```
+
+From this repository checkout:
+
+```bash
+pi install ./extensions/pi-plan
+```
+
+For local development without installing:
+
+```bash
+pi -e ./extensions/pi-plan
+```
+
+Start directly in planning mode:
+
+```bash
+pi --plan
+```
+
+## Commands and shortcuts
+
+| Command / shortcut | Description |
+| --- | --- |
+| `/plan` | Toggle plan mode. |
+| `/plan on` / `/plan off` | Explicitly enter or exit plan mode. |
+| `/plan levels` | Select planning and normal/execution thinking levels. |
+| `/plan status` | Show current mode, thinking levels, and last plan file. |
+| `/plan high` | Set the plan-mode thinking level directly (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`). |
+| `Ctrl+Alt+P` | Toggle plan mode. |
+
+## Workflow
+
+1. Enter plan mode.
+2. Ask pi to research the task and propose an implementation.
+3. The model explores read-only context and calls `write_plan`.
+4. The plan is saved under `.agents/plans/<timestamp>-<title>.md`.
+5. Choose one of the approval options:
+   - **Approve and execute**: exits plan mode, restores tools, applies normal thinking level, and sends a follow-up execution prompt.
+   - **Approve only**: exits plan mode without starting work.
+   - **Keep planning**: remains in plan mode.
+   - **Refine with feedback**: sends your feedback as a follow-up planning prompt.
+
+## Design notes
+
+Research findings used for this extension:
+
+- Pi has no built-in plan mode by design, but extensions can implement it with commands, shortcuts, tool gating, status widgets, and prompt injection.
+- Claude Code plan mode emphasizes read-only exploration, writing a Markdown plan, and an approval flow before edits.
+- Codex guidance recommends plan mode for complex or ambiguous tasks and using higher reasoning levels for harder planning/debugging work.
+
+This extension deliberately writes visible workspace plans instead of hidden internal state so you can review, edit, commit, or discard them like any other project artifact.
+
+## Packaging and release
+
+`package.json` declares this as a Pi package with the `pi-package` keyword and a `pi.extensions` entry for `./index.ts`. Runtime Pi imports are listed as peer dependencies per Pi package guidance.
+
+The repository publish workflow includes `extensions/pi-plan`. Bump the package version in `package.json` when publishing a new npm release; the CI workflow only publishes packages whose versions changed, or the selected package from manual `workflow_dispatch`.

package/index.ts

@@ -0,0 +1,364 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isToolCallEventType, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const STATUS_KEY = "pi-plan";
+const PLAN_DIR = path.join(".agents", "plans");
+const PLAN_TOOL = "write_plan";
+const PLAN_MODE_DISABLED_TOOLS = new Set(["edit", "write"]);
+const DEFAULT_PLAN_TOOLS = ["read", "bash", "grep", "find", "ls", PLAN_TOOL];
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+
+type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+type PlanStatus = "draft" | "approved" | "executing";
+
+interface PlanState {
+	enabled: boolean;
+	executing: boolean;
+	planThinking: ThinkingLevel;
+	normalThinking: ThinkingLevel;
+	toolsBeforePlan?: string[];
+	lastPlanPath?: string;
+	lastPlanTitle?: string;
+	lastPlanStatus?: PlanStatus;
+}
+
+interface WritePlanParams {
+	title: string;
+	content: string;
+	status?: PlanStatus;
+}
+
+const DESTRUCTIVE_BASH_PATTERNS = [
+	/\brm\b/i,
+	/\brmdir\b/i,
+	/\bmv\b/i,
+	/\bcp\b/i,
+	/\bmkdir\b/i,
+	/\btouch\b/i,
+	/\bchmod\b/i,
+	/\bchown\b/i,
+	/\btee\b/i,
+	/(^|[^<])>(?!>)/,
+	/>>/,
+	/\bnpm\s+(install|uninstall|update|ci|link|publish)/i,
+	/\b(yarn|pnpm)\s+(add|remove|install|publish)/i,
+	/\bpip\s+(install|uninstall)/i,
+	/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|stash|cherry-pick|revert|tag|init|clone)/i,
+	/\bsudo\b/i,
+	/\bkill(all)?\b/i,
+	/\b(pk|re)?kill\b/i,
+	/\b(vim?|nano|emacs|code|subl)\b/i,
+];
+
+function isThinkingLevel(value: string): value is ThinkingLevel {
+	return (THINKING_LEVELS as readonly string[]).includes(value);
+}
+
+function isPlanStatus(value: string | undefined): value is PlanStatus {
+	return value === "draft" || value === "approved" || value === "executing";
+}
+
+function unique(values: string[]): string[] {
+	return [...new Set(values)];
+}
+
+function slugify(value: string): string {
+	const slug = value
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, 60);
+	return slug || "plan";
+}
+
+function normalizePlanContent(params: WritePlanParams): string {
+	const title = params.title.trim() || "Plan";
+	const body = params.content.trim();
+	if (/^#\s+/m.test(body)) return `${body}\n`;
+	return `# ${title}\n\n${body}\n`;
+}
+
+function planPath(cwd: string, title: string): string {
+	const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+	return path.join(cwd, PLAN_DIR, `${stamp}-${slugify(title)}.md`);
+}
+
+function relativeToCwd(cwd: string, absolutePath: string): string {
+	return path.relative(cwd, absolutePath).split(path.sep).join("/");
+}
+
+function isDestructiveBash(command: string): boolean {
+	return DESTRUCTIVE_BASH_PATTERNS.some((pattern) => pattern.test(command));
+}
+
+export default function piPlanExtension(pi: ExtensionAPI): void {
+	let planModeEnabled = false;
+	let executionMode = false;
+	let toolsBeforePlan: string[] | undefined;
+	let planThinking: ThinkingLevel = "high";
+	let normalThinking: ThinkingLevel = "medium";
+	let lastPlanPath: string | undefined;
+	let lastPlanTitle: string | undefined;
+	let lastPlanStatus: PlanStatus | undefined;
+
+	function setStatus(ctx: ExtensionContext): void {
+		if (planModeEnabled) {
+			ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg("warning", `plan:${planThinking}`));
+			return;
+		}
+		if (executionMode) {
+			ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg("accent", `exec:${normalThinking}`));
+			return;
+		}
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+	}
+
+	function setPlanWidget(ctx: ExtensionContext): void {
+		if (!planModeEnabled) {
+			ctx.ui.setWidget(STATUS_KEY, undefined);
+			return;
+		}
+		ctx.ui.setWidget(STATUS_KEY, [
+			ctx.ui.theme.fg("warning", "Plan mode: read-only exploration"),
+			`Plan file target: ${PLAN_DIR}/`,
+			`Plan thinking: ${planThinking}; normal thinking: ${normalThinking}`,
+			"Use write_plan when the plan is ready for approval.",
+		]);
+	}
+
+	function persistState(): void {
+		pi.appendEntry("pi-plan", {
+			enabled: planModeEnabled,
+			executing: executionMode,
+			planThinking,
+			normalThinking,
+			toolsBeforePlan,
+			lastPlanPath,
+			lastPlanTitle,
+			lastPlanStatus,
+		} satisfies PlanState);
+	}
+
+	function enablePlanTools(): void {
+		const baseline = toolsBeforePlan ?? pi.getActiveTools();
+		toolsBeforePlan = baseline;
+		pi.setActiveTools(unique([...baseline.filter((tool) => !PLAN_MODE_DISABLED_TOOLS.has(tool)), ...DEFAULT_PLAN_TOOLS]));
+	}
+
+	function restoreTools(): void {
+		if (toolsBeforePlan) pi.setActiveTools(toolsBeforePlan);
+		toolsBeforePlan = undefined;
+	}
+
+	function applyThinking(level: ThinkingLevel): void {
+		pi.setThinkingLevel(level);
+	}
+
+	function enterPlanMode(ctx: ExtensionContext): void {
+		planModeEnabled = true;
+		executionMode = false;
+		enablePlanTools();
+		applyThinking(planThinking);
+		setStatus(ctx);
+		setPlanWidget(ctx);
+		persistState();
+		ctx.ui.notify(`Plan mode enabled. Thinking=${planThinking}. Plans will be written to ${PLAN_DIR}/`, "info");
+	}
+
+	function leavePlanMode(ctx: ExtensionContext, restoreThinking = true): void {
+		planModeEnabled = false;
+		executionMode = false;
+		restoreTools();
+		if (restoreThinking) applyThinking(normalThinking);
+		setStatus(ctx);
+		setPlanWidget(ctx);
+		persistState();
+		ctx.ui.notify(`Plan mode disabled. Thinking=${pi.getThinkingLevel()}.`, "info");
+	}
+
+	async function chooseThinkingLevels(ctx: ExtensionContext): Promise<void> {
+		const plan = await ctx.ui.select("Plan mode reasoning level", [...THINKING_LEVELS]);
+		if (plan && isThinkingLevel(plan)) planThinking = plan;
+		const normal = await ctx.ui.select("Normal/execution reasoning level", [...THINKING_LEVELS]);
+		if (normal && isThinkingLevel(normal)) normalThinking = normal;
+		if (planModeEnabled) applyThinking(planThinking);
+		else applyThinking(normalThinking);
+		setStatus(ctx);
+		setPlanWidget(ctx);
+		persistState();
+		ctx.ui.notify(`pi-plan levels: plan=${planThinking}, normal=${normalThinking}`, "info");
+	}
+
+	async function handlePlanCommand(args: string, ctx: ExtensionContext): Promise<void> {
+		const subcommand = args.trim();
+		if (subcommand === "levels") return chooseThinkingLevels(ctx);
+		if (subcommand === "on" || subcommand === "start") return enterPlanMode(ctx);
+		if (subcommand === "off" || subcommand === "stop") return leavePlanMode(ctx);
+		if (subcommand === "status") {
+			ctx.ui.notify(
+				[`Mode: ${planModeEnabled ? "planning" : executionMode ? "executing" : "normal"}`, `Plan thinking: ${planThinking}`, `Normal thinking: ${normalThinking}`, `Last plan: ${lastPlanPath ? relativeToCwd(ctx.cwd, lastPlanPath) : "none"}`].join("\n"),
+				"info",
+			);
+			return;
+		}
+		if (subcommand.length > 0 && isThinkingLevel(subcommand)) {
+			planThinking = subcommand;
+			if (planModeEnabled) applyThinking(planThinking);
+			setStatus(ctx);
+			setPlanWidget(ctx);
+			persistState();
+			ctx.ui.notify(`Plan thinking set to ${planThinking}`, "info");
+			return;
+		}
+		if (planModeEnabled) leavePlanMode(ctx);
+		else enterPlanMode(ctx);
+	}
+
+	pi.registerFlag("plan", {
+		description: "Start in pi-plan read-only planning mode",
+		type: "boolean",
+		default: false,
+	});
+
+	pi.registerTool({
+		name: PLAN_TOOL,
+		label: "Write Plan",
+		description: `Write or replace the current implementation plan as Markdown under ${PLAN_DIR}/. Use in plan mode when the plan is ready for user review.`,
+		promptSnippet: `Write the implementation plan to ${PLAN_DIR}/ as a Markdown file for user review`,
+		promptGuidelines: [`Use ${PLAN_TOOL} in plan mode after repository exploration; do not use edit/write for implementation until the user approves the plan.`],
+		parameters: Type.Object({
+			title: Type.String({ description: "Short human-readable title for the plan" }),
+			content: Type.String({ description: "Complete Markdown plan content" }),
+			status: Type.Optional(Type.String({ description: "Plan status: draft, approved, or executing" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const typedParams = params as WritePlanParams;
+			const destination = lastPlanPath ?? planPath(ctx.cwd, typedParams.title);
+			const content = normalizePlanContent(typedParams);
+			await withFileMutationQueue(destination, async () => {
+				await mkdir(path.dirname(destination), { recursive: true });
+				await writeFile(destination, content, "utf8");
+			});
+			lastPlanPath = destination;
+			lastPlanTitle = typedParams.title.trim() || "Plan";
+			lastPlanStatus = isPlanStatus(typedParams.status) ? typedParams.status : "draft";
+			persistState();
+			return {
+				content: [{ type: "text", text: `Plan written to ${relativeToCwd(ctx.cwd, destination)}. Ask the user to approve, refine, or keep planning.` }],
+				details: { path: destination, title: lastPlanTitle, status: lastPlanStatus },
+			};
+		},
+	});
+
+	pi.registerCommand("plan", {
+		description: "Toggle pi-plan mode; subcommands: on, off, levels, status, or a thinking level",
+		getArgumentCompletions: (prefix) => {
+			const values = ["on", "off", "levels", "status", ...THINKING_LEVELS].filter((value) => value.startsWith(prefix));
+			return values.length ? values.map((value) => ({ label: value, value })) : null;
+		},
+		handler: async (args, ctx) => handlePlanCommand(args, ctx),
+	});
+
+	pi.registerShortcut("ctrl+alt+p", {
+		description: "Toggle pi-plan mode",
+		handler: async (ctx) => {
+			if (planModeEnabled) leavePlanMode(ctx);
+			else enterPlanMode(ctx);
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		const entries = ctx.sessionManager.getEntries();
+		const saved = entries
+			.filter((entry: { type: string; customType?: string }) => entry.type === "custom" && entry.customType === "pi-plan")
+			.pop() as { data?: PlanState } | undefined;
+		if (saved?.data) {
+			planModeEnabled = saved.data.enabled ?? planModeEnabled;
+			executionMode = saved.data.executing ?? executionMode;
+			planThinking = saved.data.planThinking ?? planThinking;
+			normalThinking = saved.data.normalThinking ?? normalThinking;
+			toolsBeforePlan = saved.data.toolsBeforePlan ?? toolsBeforePlan;
+			lastPlanPath = saved.data.lastPlanPath ?? lastPlanPath;
+			lastPlanTitle = saved.data.lastPlanTitle ?? lastPlanTitle;
+			lastPlanStatus = saved.data.lastPlanStatus ?? lastPlanStatus;
+		}
+		if (pi.getFlag("plan") === true) planModeEnabled = true;
+		if (planModeEnabled) {
+			enablePlanTools();
+			applyThinking(planThinking);
+		}
+		setStatus(ctx);
+		setPlanWidget(ctx);
+	});
+
+	pi.on("tool_call", async (event) => {
+		if (!planModeEnabled) return;
+		if (event.toolName === "edit" || event.toolName === "write") {
+			return { block: true, reason: `pi-plan: ${event.toolName} is disabled until the plan is approved. Use ${PLAN_TOOL} to write the plan file.` };
+		}
+		if (!isToolCallEventType("bash", event)) return;
+		if (isDestructiveBash(event.input.command)) {
+			return { block: true, reason: `pi-plan: bash command blocked in plan mode because it may modify state.\nCommand: ${event.input.command}` };
+		}
+	});
+
+	pi.on("before_agent_start", async (_event, ctx) => {
+		if (planModeEnabled) {
+			const relativePlan = lastPlanPath ? relativeToCwd(ctx.cwd, lastPlanPath) : `${PLAN_DIR}/<timestamp>-<title>.md`;
+			return {
+				message: {
+					customType: "pi-plan-context",
+					content: `[PI-PLAN MODE ACTIVE]\nYou are in read-only planning mode. Research the codebase and produce a reviewable implementation plan before making changes.\n\nRules:\n- Do not edit source files, configs, lockfiles, or git state.\n- You may read files, search, inspect git state, and run read-only shell commands.\n- Ask concise clarifying questions if requirements are ambiguous.\n- When the plan is ready, call ${PLAN_TOOL} with a complete Markdown plan.\n- The plan file must live in ${PLAN_DIR}/. Current/next plan path: ${relativePlan}\n\nPlan content should include:\n1. Goal and assumptions.\n2. Key findings with durable file/symbol paths.\n3. Proposed implementation steps.\n4. Verification plan.\n5. Risks, open questions, and rejected alternatives if relevant.`,
+					display: false,
+				},
+			};
+		}
+
+		if (executionMode && lastPlanPath) {
+			let content = "";
+			try {
+				content = await readFile(lastPlanPath, "utf8");
+			} catch {
+				content = `Plan file unavailable at ${lastPlanPath}`;
+			}
+			return {
+				message: {
+					customType: "pi-plan-execution-context",
+					content: `[PI-PLAN EXECUTION]\nExecute the approved plan at ${relativeToCwd(ctx.cwd, lastPlanPath)}. Use normal mode thinking=${normalThinking}. Keep changes scoped to the plan and verify the result.\n\n${content}`,
+					display: false,
+				},
+			};
+		}
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		if (!planModeEnabled || !lastPlanPath || !ctx.hasUI) return;
+		const relativePlan = relativeToCwd(ctx.cwd, lastPlanPath);
+		const choice = await ctx.ui.select(`Plan written: ${relativePlan}`, [
+			"Approve and execute",
+			"Approve only (exit plan mode)",
+			"Keep planning",
+			"Refine with feedback",
+		]);
+		if (choice === "Approve and execute") {
+			planModeEnabled = false;
+			executionMode = true;
+			lastPlanStatus = "approved";
+			restoreTools();
+			applyThinking(normalThinking);
+			setStatus(ctx);
+			setPlanWidget(ctx);
+			persistState();
+			pi.sendUserMessage(`Execute the approved plan in ${relativePlan}. Keep the implementation scoped to the plan, update the plan if reality differs materially, and run the verification described there.`, { deliverAs: "followUp" });
+		} else if (choice === "Approve only (exit plan mode)") {
+			lastPlanStatus = "approved";
+			leavePlanMode(ctx);
+		} else if (choice === "Refine with feedback") {
+			const feedback = await ctx.ui.editor("Plan feedback", "");
+			if (feedback?.trim()) pi.sendUserMessage(`Refine the plan in ${relativePlan} with this feedback:\n\n${feedback.trim()}`, { deliverAs: "followUp" });
+		}
+	});
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@bacnh85/pi-plan",
+  "version": "0.1.1",
+  "description": "Pi extension that adds a plan mode with workspace markdown plans and thinking-level presets.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/bacnh85/skills#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bacnh85/skills.git",
+    "directory": "extensions/pi-plan"
+  },
+  "bugs": {
+    "url": "https://github.com/bacnh85/skills/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "plan-mode",
+    "planning",
+    "reasoning"
+  ],
+  "files": [
+    "README.md",
+    "index.ts"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}