refactor: restructure plan mode with shift+tab toggle and system prompt injection (#5)

* refactor(plan): restructure planning mode with shift+tab toggle and system prompt injection

* docs: update changelog

Author: kostyay

CHANGELOG.md

@@ -4,11 +4,19 @@ All notable changes to agent-stuff are documented here.
 
 
 
-## docs/update-readme-extensions
+
+
+
+
+## refactor/plan-mode-restructure
+
+Plan mode now supports two entry points: **Shift+Tab** for instant toggling with the planning system prompt injected via `before_agent_start` (#5), and the existing **/plan** command for one-shot planning flows. The restructuring separates the reusable `PLAN_SYSTEM_PROMPT` constant from command-specific logic, enabling seamless mode switching without prompting for input on toggle. Read-only tool restrictions and bash command filtering remain intact, maintaining the safety guarantees of planning mode while improving UX for users who frequently switch between exploratory and implementation phases.
+
+## [1.0.0](https://github.com/kostyay/agent-stuff/pull/4) - 2026-03-02
 
 Updated the README to document two new extensions and clarify project structure. Added [`git-rebase-master.ts`](#4) extension which automates rebasing against main/master branches with LLM-powered conflict resolution, and documented the new [`sandbox/`](#4) directory enabling OS-level sandboxing for bash commands via `sandbox-exec` on macOS and bubblewrap on Linux with configurable filesystem and network restrictions. Also clarified the `.github/` directory location in the project structure overview.
 
-## git-rebase-master
+## [1.0.0](https://github.com/kostyay/agent-stuff/pull/2) - 2026-03-02
 
 Added `/git-rebase-master` command that fetches the latest `main` or `master`
 from origin and rebases the current branch onto it. The extension auto-detects
@@ -22,7 +30,7 @@ new `autoBranch` option on `performCommit`.
 `/commit-push-pr` now creates PRs in ready mode by default instead of draft
 mode, streamlining the publish workflow for most use cases.
 
-## docs/update-readme-and-sandbox
+## [1.0.0](https://github.com/kostyay/agent-stuff/pull/3) - 2026-03-02
 
 The commit extension was overhauled to dramatically reduce token consumption by gathering changelog context deterministically through git/gh commands and calling the model once for summary generation, with the new `/merge-pr` command streamlining the full pre-merge workflow including changelog updates, incremental PR description refresh, and squash-merge with cleanup. The sandbox extension now supports runtime toggling via `/sandbox on` and `/sandbox off` commands with a visual status indicator, eliminating the need to restart. An auto-release workflow now replaces the npm-publish pipeline, automatically creating GitHub tags and releases on main merges when `package.json` version changes, with release notes extracted from `CHANGELOG.md` via a new Python script that falls back to the git commit log. (#3)
 

pi-extensions/plan.ts

@@ -1,13 +1,20 @@
 /**
- * /plan - One-shot planning mode
+ * Plan Mode Extension
  *
- * Usage: /plan <prompt>
+ * Provides two ways to enter planning mode:
  *
- * Enters a read-only planning flow:
- * 1. Restricts tools to read-only (read, bash safe-only, grep, find, ls, ask_question)
- * 2. Agent explores codebase, asks clarifying questions via ask_question
- * 3. Agent presents plan in sections, validates each with ask_question
- * 4. On completion, asks user where to save and whether to execute
+ * 1. **Shift+Tab** — Toggles plan mode on/off instantly. Tools are restricted
+ *    to read-only and the planning system prompt is injected via
+ *    `before_agent_start`. The user types their message normally in the editor.
+ *
+ * 2. **/plan <prompt>** — One-shot planning: enters plan mode and immediately
+ *    sends the prompt to the agent with planning instructions.
+ *
+ * In plan mode:
+ * - Tools are restricted to read-only (read, bash safe-only, grep, find, ls, ask_question)
+ * - Bash commands are filtered to a safe allowlist
+ * - The system prompt is augmented with planning instructions
+ * - On agent completion, the user is offered save/execute/refine options
  *
  * Depends on kbrainstorm extension for the ask_question tool.
  */
@@ -128,14 +135,12 @@ function getTextContent(message: AssistantMessage): string {
 
 // ── Planning prompt ──────────────────────────────────────────────────────
 
-function buildPlanPrompt(userPrompt: string): string {
-	return `[PLAN MODE ACTIVE - READ ONLY]
+/** System prompt appended via `before_agent_start` when plan mode is active. */
+const PLAN_SYSTEM_PROMPT = `[PLAN MODE ACTIVE - READ ONLY]
 
 You are in planning mode. You MUST NOT make any file changes.
 Your tools are restricted to read-only operations.
 
-Your task: ${userPrompt}
-
 Follow this process:
 1. Explore the codebase to understand the current state relevant to the task (read files, search, grep, etc.)
 2. Ask clarifying questions using ask_question (one question at a time, prefer multiple choice when possible)
@@ -154,6 +159,10 @@ Important:
 - Use ask_question for ALL questions to the user (never ask in plain text)
 - Be thorough in exploration before proposing the plan
 - Keep each plan section focused and concise`;
+
+/** Builds a user message for the /plan command's one-shot flow. */
+function buildPlanPrompt(userPrompt: string): string {
+	return `${PLAN_SYSTEM_PROMPT}\n\nYour task: ${userPrompt}`;
 }
 
 // ── Extension ────────────────────────────────────────────────────────────
@@ -230,27 +239,29 @@ export default function planExtension(pi: ExtensionAPI) {
 		},
 	});
 
-	// ── Ctrl+Tab shortcut to toggle modes ────────────────────────────────
+	// ── Shift+Tab shortcut to toggle modes ───────────────────────────────
 
 	pi.registerShortcut("shift+tab", {
 		description: "Toggle between agent and plan mode",
 		handler: async (ctx) => {
 			if (planActive) {
-				// Switch back to agent mode immediately
 				exitPlanMode(ctx);
 				ctx.ui.notify("Switched to agent mode.", "info");
-				return;
+			} else {
+				enterPlanMode(ctx);
+				ctx.ui.notify("Entered plan mode (read-only). Type your message below.", "info");
 			}
+		},
+	});
 
-			// Entering plan mode — ask for a prompt
-			const prompt = await ctx.ui.input("What do you want to plan?", "");
-			if (!prompt?.trim()) return;
+	// ── Inject planning system prompt ────────────────────────────────────
 
-			planPrompt = prompt.trim();
-			enterPlanMode(ctx);
-			ctx.ui.notify("Entered plan mode (read-only). Planning...", "info");
-			pi.sendUserMessage(buildPlanPrompt(planPrompt));
-		},
+	pi.on("before_agent_start", async (event) => {
+		if (!planActive) return;
+
+		return {
+			systemPrompt: event.systemPrompt + "\n\n" + PLAN_SYSTEM_PROMPT,
+		};
 	});
 
 	// ── Block unsafe bash commands ───────────────────────────────────────