pi-do-always 0.3.0 → 0.4.0

package/README.md

@@ -5,17 +5,18 @@ repeated "do the usual" prompts.
 
 Type `/do-always` → a numbered list of tasks appears, grouped by category → press a number,
 type to filter, scroll or click, or navigate with arrows + Enter → the task's prompt is
-**filled into the input editor**. Review it, tweak it, press Enter to run.
+**filled into the input editor**. Review it, tweak it, press Enter to run. Tasks marked `⚡`
+(the `Plan` category by default) auto-run on selection instead — see `autoRun` below.
 
 ```text
   do-always — pick a task
 
   PLAN
-▸ 1. Review               Review code and double-check changes (Plan)
-  2. Cleanup              Clean up dead code and duplicates (Plan)
-  3. Security             Security audit (Plan)
-  4. Performance          Performance review (Plan)
-  5. Propose features     Propose new features (Plan)
+▸ 1. ⚡ Review             Review code and double-check changes (Plan)
+  2. ⚡ Cleanup            Clean up dead code and duplicates (Plan)
+  3. ⚡ Security           Security audit (Plan)
+  4. ⚡ Performance        Performance review (Plan)
+  5. ⚡ Propose features   Propose new features (Plan)
   DO
   6. Build                Test build is ok and fix issues
   7. Tests                Run tests and fix failures
@@ -25,7 +26,12 @@ type to filter, scroll or click, or navigate with arrows + Enter → the task's
   9. Release              Prepare a release (version, changelog, tag)
  10. Commit               Prepare a clean commit
 
-  1-9 pick by number  •  type to filter  •  ↑↓ navigate  •  enter select  •  esc cancel
+  Review — prompt:
+  Review the changes on branch fix/login-null (3 changed files: auth.ts, login.ts,
+  test/auth.test.ts). Last commit: Fix null check in login. Check `git status` and
+  `git diff` to see what changed, then double-check the changes for bugs, edge …
+
+  1-9 pick by number  •  type to filter  •  ↑↓ navigate  •  enter select  •  esc cancel  •  ⚡ auto-runs
 ```
 
 ![do-always — the numbered task selector](pi.image.png)
@@ -38,11 +44,16 @@ type to filter, scroll or click, or navigate with arrows + Enter → the task's
 |`/do-always 2`|Fill the prompt for task #2 directly|
 |`/do-always review`|Fill the prompt for the task named `review` (task names autocomplete after `/do-always`)|
 |`/do-always list`|Print the task list|
-|`/do-always list-details`|Show the full prompt text each task will inject|
+|`/do-always list-details`|Show the full rendered prompt text each task will inject|
 
 The selector supports direct number-pick (1-9), live type-to-filter, arrow/Enter navigation,
 mouse-wheel scrolling, and click-to-select. While a filter is active, typed digits refine the
 filter instead of picking by number; clear the filter (backspace) to use number-pick again.
+Pause on a task for two seconds and its full prompt is previewed below the list, so you can
+see exactly what will be injected before running it; moving the selection or typing hides it
+and restarts the delay. A task marked `⚡` runs immediately on selection (its prompt is sent,
+not filled): the `Plan` category does this by default, and any task can opt in or out via the
+`autoRun` field.
 
 In non-interactive modes (no TUI) there is no editor to fill, so the selected prompt is sent
 as a user message instead.
@@ -86,7 +97,7 @@ locations above to make it your own:
     "name": "review",
     "category": "Plan",
     "description": "Review code and double-check changes",
-    "prompt": "Review the recent code changes in this project. Check `git status` and `git diff` ..."
+    "prompt": "Review the changes on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}). Last commit: {{last_commit}}. Check `git status` and `git diff` ..."
   }
 ]
 ```
@@ -96,7 +107,8 @@ Fields:
 - `name` (required) — short unique id, used for `/do-always <name>`
 - `category` (optional) — group header the task is shown under in the selector (e.g. `"Plan"`, `"Do"`). Matching is case-insensitive and the header is title-cased, so `"plan"` and `"Plan"` land in the same `Plan` group. Tasks without a category fall under `Other`. The built-in defaults are grouped into `Plan`, `Do`, `Docs`, and `Ops`.
 - `description` (optional) — one-line label shown in the selector
-- `prompt` (required) — the text filled into the editor
+- `prompt` (required) — the text filled into the editor (supports `{{placeholders}}` — see [Prompt placeholders](#prompt-placeholders))
+- `autoRun` (optional) — when `true`, selecting the task sends its prompt immediately instead of filling the editor; when `false`, it always fills the editor. When omitted, the default is derived from the category: `Plan` tasks auto-run, everything else fills the editor. Auto-run tasks are marked `⚡` in the selector.
 
 In the object form you can also configure the selector shortcut:
 
@@ -104,6 +116,28 @@ In the object form you can also configure the selector shortcut:
 
 Reload Pi (or start a new session) after editing a config file.
 
+## Prompt placeholders
+
+Task prompts support `{{placeholders}}` that are filled in from the current
+directory when a task is selected — so `/do-always review` on a hotfix branch
+injects “Review the changes on branch `fix/login-null` (3 changed files:
+`auth.ts`, `login.ts`, `test/auth.test.ts`) …” instead of a generic nudge.
+
+|Placeholder|Value|
+|---|---|
+|`{{cwd}}`|Absolute path of the working directory|
+|`{{date}}`|Local date (`YYYY-MM-DD`)|
+|`{{branch}}`|Current git branch (`unknown` outside a git repo)|
+|`{{last_commit}}`|Subject of the latest commit (`unknown` if unavailable, e.g. empty repo)|
+|`{{files_changed}}`|Changed files from `git status` — comma-separated, capped at 20 entries (`none` when clean or not a git repo)|
+|`{{files_changed_count}}`|Number of changed files (`0` when clean or not a git repo)|
+|`{{user}}`|`git config user.name` (`unknown` when unset)|
+
+Unknown placeholders are left as-is, and a prompt without placeholders is
+injected unchanged, so existing configs keep working. The selector preview and
+`/do-always list-details` show the rendered prompt — what you see is what gets
+injected.
+
 ## Development
 
 ```bash
@@ -112,6 +146,6 @@ npm run typecheck  # tsc --noEmit
 npm test           # run the unit tests (node:test + tsx, in test/)
 ```
 
-The pure task logic (`parseConfig`, `mergeTasks`, `resolveTask`, `formatList`) lives in
+The pure task logic (`parseConfig`, `mergeTasks`, `renderPrompt`, `resolveTask`, `formatList`) lives in
 [`tasks.ts`](./tasks.ts) with no Pi dependencies, so it is unit-tested independently of the
 Pi runtime. The extension (`index.ts`) imports that logic and adds only the Pi UI.

package/do-always.json

@@ -5,11 +5,12 @@
 			"name": "Review",
 			"category": "Plan",
 			"description": "Review code and double-check changes (Plan)",
-			"prompt": "Review the recent code changes in this project. Check `git status` and `git diff` to see what changed, then double-check the changes for bugs, edge cases, security issues, and consistency with the rest of the codebase. Do a plan proposal for the fixes if needed. Do a summary of your findings"
+			"prompt": "Review the changes on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}). Last commit: {{last_commit}}. Check `git status` and `git diff` to see what changed, then double-check the changes for bugs, edge cases, security issues, and consistency with the rest of the codebase. Do a plan proposal for the fixes if needed. Do a summary of your findings"
 		},
 		{
 			"name": "Cleanup",
 			"category": "Plan",
+			"autoRun": false,
 			"description": "Clean up dead code and duplicates (Plan)",
 			"prompt": "Scan the project for dead code, unused imports, commented-out blocks, and duplicated logic. Do a plan proposal for the removals and consolidations, keeping behavior unchanged. Do not make any changes yet."
 		},
@@ -53,13 +54,13 @@
 			"name": "Release",
 			"category": "Ops",
 			"description": "Prepare a release (version, changelog, tag)",
-			"prompt": "Prepare a release for this project: check `git log` since the last tag, update the version in package.json (or the equivalent location), add a changelog entry summarizing the changes, and create a git tag if git present. Do not push."
+			"prompt": "Prepare a release for this project (branch {{branch}}): check `git log` since the last tag, update the version in package.json (or the equivalent location), add a changelog entry summarizing the changes, and create a git tag if git present. Do not push."
 		},
 		{
 			"name": "Commit",
 			"category": "Ops",
 			"description": "Prepare a clean commit",
-			"prompt": "Prepare the working tree for a clean commit: review `git status` and `git diff`, stage the relevant changes, and write a clear commit message describing what changed and why. Do not push."
+			"prompt": "Prepare the working tree on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}) for a clean commit: review `git status` and `git diff`, stage the relevant changes, and write a clear commit message describing what changed and why. Do not push."
 		}
 	]
 }

package/index.ts

@@ -33,6 +33,7 @@
  * If no config file exists, built-in default tasks are used.
  */
 
+import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -44,6 +45,7 @@ import {
 	getKeybindings,
 	truncateToWidth,
 	visibleWidth,
+	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
 import {
 	DEFAULT_SHORTCUT,
@@ -54,9 +56,12 @@ import {
 	mergeTasks,
 	parseConfig,
 	orderTasksByCategory,
+	renderPrompt,
 	resolveShortcut,
 	resolveTask,
+	shouldAutoRun,
 	type DoAlwaysTask,
+	type PromptContext,
 	type TaskGroup,
 } from "./tasks";
 
@@ -84,6 +89,71 @@ function loadConfig(cwd: string): { tasks: DoAlwaysTask[]; shortcut: string | nu
 	};
 }
 
+/**
+ * Run a git command in `cwd` and return its trimmed stdout.
+ * Returns undefined on any failure (not a git repo, git not installed,
+ * empty repo, …) so callers can fall back to a neutral value.
+ * No shell is involved (argument array), so file names cannot inject commands.
+ */
+function git(cwd: string, args: string[]): string | undefined {
+	try {
+		const out = execFileSync("git", args, {
+			cwd,
+			encoding: "utf-8",
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+		const trimmed = out.trim();
+		return trimmed === "" ? undefined : trimmed;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Max number of file paths listed in `files_changed` (the count stays exact). */
+const MAX_FILES_LISTED = 20;
+
+/**
+ * Build the prompt context for `renderPrompt`. Always contains every
+ * PROMPT_CONTEXT_KEYS entry: git facts fall back to neutral values when
+ * unavailable (non-git dir, no git, empty repo) so default prompts read
+ * cleanly in any directory.
+ */
+function buildContext(cwd: string): PromptContext {
+	const branch = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]) ?? "unknown";
+	const lastCommit = git(cwd, ["log", "-1", "--format=%s"]) ?? "unknown";
+	const user = git(cwd, ["config", "user.name"]) ?? "unknown";
+
+	const files: string[] = [];
+	const status = git(cwd, ["status", "--porcelain"]);
+	if (status) {
+		for (const line of status.split("\n")) {
+			// Porcelain v1 lines are "XY <path>" (X = index, Y = worktree).
+			if (line.length < 4) continue;
+			const path = line.slice(3);
+			if (path && !files.includes(path)) files.push(path);
+		}
+		files.sort();
+	}
+	let listed: string;
+	if (files.length === 0) {
+		listed = "none";
+	} else if (files.length > MAX_FILES_LISTED) {
+		listed = [...files.slice(0, MAX_FILES_LISTED), `… (+${files.length - MAX_FILES_LISTED} more)`].join(", ");
+	} else {
+		listed = files.join(", ");
+	}
+
+	return {
+		cwd,
+		date: new Date().toLocaleDateString("en-CA"), // local YYYY-MM-DD
+		branch,
+		last_commit: lastCommit,
+		files_changed: listed,
+		files_changed_count: String(files.length),
+		user,
+	};
+}
+
 /** Find the group (among `groups`) that contains a task. */
 function findGroupOf(task: DoAlwaysTask, groups: TaskGroup[]): TaskGroup | undefined {
 	return groups.find((g) => g.items.includes(task));
@@ -94,6 +164,11 @@ function isPrintable(data: string): boolean {
 	return data.length === 1 && data >= " " && data <= "~";
 }
 
+/** Delay before the selector reveals the selected task's prompt preview. */
+const PREVIEW_DELAY_MS = 2000;
+/** Max lines of the prompt shown in the selector preview. */
+const PREVIEW_MAX_LINES = 3;
+
 export default function doAlwaysExtension(pi: ExtensionAPI) {
 	let tasks: DoAlwaysTask[] = [];
 	let loadedCwd = ""; // cwd the cached `tasks` were loaded for
@@ -105,11 +180,19 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 
 	/** Put the task prompt into the editor (TUI) or send it as a user message (other modes). */
 	async function fillPrompt(task: DoAlwaysTask, ctx: ExtensionContext): Promise<void> {
+		// Render the prompt with the current context (branch, changed files, …)
+		// so the injected text matches this directory at this moment.
+		const prompt = renderPrompt(task.prompt, buildContext(ctx.cwd));
+		if (shouldAutoRun(task)) {
+			await pi.sendUserMessage(prompt);
+			ctx.ui.notify(`do-always: auto-ran "${task.name}"`, "info");
+			return;
+		}
 		if (ctx.mode === "tui") {
-			ctx.ui.setEditorText(task.prompt);
+			ctx.ui.setEditorText(prompt);
 			ctx.ui.notify(`do-always: prompt for "${task.name}" filled — press Enter to run`, "info");
 		} else {
-			await pi.sendUserMessage(task.prompt);
+			await pi.sendUserMessage(prompt);
 		}
 	}
 
@@ -118,14 +201,43 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 	 * number, type to filter, or navigate with arrows + Enter, Esc to cancel.
 	 */
 	async function showSelector(ctx: ExtensionContext): Promise<void> {
+		// Build the context once per selector session (never inside the render
+		// loop — no process spawning per frame). fillPrompt re-renders at
+		// selection time, so a few seconds of drift is acceptable.
+		const context = buildContext(ctx.cwd);
 		const selected = await ctx.ui.custom<number | null>((tui, theme, _kb, done) => {
 			let settled = false;
+			let previewVisible = false;
+			let previewTimer: ReturnType<typeof setTimeout> | null = null;
+
+			function clearPreviewTimer() {
+				if (previewTimer) {
+					clearTimeout(previewTimer);
+					previewTimer = null;
+				}
+			}
+
 			const finish = (value: number | null) => {
 				if (settled) return;
 				settled = true;
+				clearPreviewTimer();
 				done(value);
 			};
 
+			// The prompt preview appears only after the selection has been stable
+			// for PREVIEW_DELAY_MS; any change hides it and restarts the delay.
+			function resetPreview() {
+				previewVisible = false;
+				clearPreviewTimer();
+				previewTimer = setTimeout(() => {
+					previewTimer = null;
+					if (!settled) {
+						previewVisible = true;
+						tui.requestRender();
+					}
+				}, PREVIEW_DELAY_MS);
+			}
+
 			// Group tasks under category headers, in a stable order.
 			const groups = groupTasksByCategory(tasks);
 
@@ -135,6 +247,9 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 			let selectedIndex = 0;
 			let mousePressedIndex: number | null = null;
 
+			// Arm the preview timer for the initial selection.
+			resetPreview();
+
 			const matchesFilter = (t: DoAlwaysTask) => {
 				if (!filter) return true;
 				const f = filter.toLowerCase();
@@ -173,7 +288,8 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 
 			function renderLabel(task: DoAlwaysTask, globalIndex: number, isSelected: boolean, width: number): string {
 				const prefix = isSelected ? "▸ " : "  ";
-				const label = `${prefix}${globalIndex + 1}. ${task.name}`;
+				const marker = shouldAutoRun(task) ? "⚡ " : "";
+				const label = `${prefix}${globalIndex + 1}. ${marker}${task.name}`;
 				if (!task.description) {
 					const line = truncateToWidth(label, Math.max(1, width - 2), "");
 					return isSelected ? theme.fg("accent", theme.bold(line)) : line;
@@ -223,13 +339,31 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 						lines.push(theme.fg("dim", truncateToWidth(hint, width - 2, "")));
 					}
 				}
+				// Prompt preview: revealed after the selection has been stable for
+				// PREVIEW_DELAY_MS, showing exactly what will be injected.
+				if (previewVisible) {
+					const sel = itemRows[selectedIndex];
+					if (sel) {
+						const wrapWidth = Math.max(10, width - 4);
+						// Show the rendered prompt — exactly what will be injected.
+						const wrapped = wrapTextWithAnsi(renderPrompt(sel.task.prompt, context), wrapWidth);
+						const shown = wrapped.slice(0, PREVIEW_MAX_LINES);
+						const truncated = wrapped.length > PREVIEW_MAX_LINES;
+						lines.push("");
+						lines.push(theme.fg("dim", theme.bold(`  ${sel.task.name} — prompt:`)));
+						shown.forEach((ln, i) => {
+							const isLast = i === shown.length - 1;
+							const text = isLast && truncated ? truncateToWidth(`${ln} …`, wrapWidth, "") : ln;
+							lines.push(theme.fg("muted", `  ${text}`));
+						});
+					}
+				}
 				lines.push("");
-				lines.push(
-					theme.fg(
-						"dim",
-						truncateToWidth("  1-9 pick by number  •  type to filter  •  ↑↓ navigate  •  enter select  •  esc cancel", width - 2, ""),
-					),
-				);
+				const anyAutoRun = itemRows.some((r) => shouldAutoRun(r.task));
+				const footer = anyAutoRun
+					? "  1-9 pick by number  •  type to filter  •  ↑↓ navigate  •  enter select  •  esc cancel  •  ⚡ auto-runs"
+					: "  1-9 pick by number  •  type to filter  •  ↑↓ navigate  •  enter select  •  esc cancel";
+				lines.push(theme.fg("dim", truncateToWidth(footer, width - 2, "")));
 				return { lines, itemLine, itemRows };
 			}
 
@@ -249,12 +383,14 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 					if (kb.matches(data, "tui.editor.deleteCharBackward")) {
 						filter = filter.slice(0, -1);
 						selectedIndex = 0;
+						resetPreview();
 						tui.requestRender();
 						return;
 					}
 					if (isPrintable(data)) {
 						filter += data;
 						selectedIndex = 0;
+						resetPreview();
 						tui.requestRender();
 						return;
 					}
@@ -262,10 +398,12 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 					const { itemRows } = getVisible();
 					if (kb.matches(data, "tui.select.up")) {
 						selectedIndex = selectedIndex === 0 ? itemRows.length - 1 : selectedIndex - 1;
+						resetPreview();
 						tui.requestRender();
 					}
 					else if (kb.matches(data, "tui.select.down")) {
 						selectedIndex = selectedIndex === itemRows.length - 1 ? 0 : selectedIndex + 1;
+						resetPreview();
 						tui.requestRender();
 					}
 					else if (kb.matches(data, "tui.select.confirm")) {
@@ -283,6 +421,7 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 						const delta = event.wheelDelta < 0 ? -1 : 1;
 						const prev = selectedIndex;
 						selectedIndex = Math.max(0, Math.min(itemRows.length - 1, selectedIndex + delta));
+						if (selectedIndex !== prev) resetPreview();
 						return { handled: true, render: selectedIndex !== prev };
 					}
 					if (event.button !== "left" || (event.type !== "press" && event.type !== "click")) return undefined;
@@ -293,7 +432,10 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 					if (idx < 0) return undefined;
 					if (event.type === "press") {
 						mousePressedIndex = idx;
-						selectedIndex = idx;
+						if (selectedIndex !== idx) {
+							selectedIndex = idx;
+							resetPreview();
+						}
 						return { handled: true, focus: true, render: true };
 					}
 					const clicked = mousePressedIndex ?? idx;
@@ -369,12 +511,14 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 
 		if (arg.toLowerCase() === "list-details") {
 			// Display only — the description is metadata; selecting a task injects just its prompt.
+			// Render with the current context so what is shown is what gets injected.
+			const context = buildContext(ctx.cwd);
 			const details = tasks
 				.map((t, i) => {
 					const lines = [`${i + 1}. ${t.name}`];
 					if (t.description) lines.push(`   description: ${t.description}`);
 					lines.push("   prompt (this is what gets injected on select):");
-					for (const line of t.prompt.split("\n")) lines.push(`   ${line}`);
+					for (const line of renderPrompt(t.prompt, context).split("\n")) lines.push(`   ${line}`);
 					return lines.join("\n");
 				})
 				.join("\n\n");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-do-always",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"type": "module",
 	"description": "Pi extension: /do-always — pick a common task by number, it fills your prompt",
 	"author": {

package/tasks.ts

@@ -13,6 +13,12 @@ export interface DoAlwaysTask {
 	description?: string;
 	/** Prompt filled into the editor when the task is selected */
 	prompt: string;
+	/**
+	 * Whether selecting the task sends its prompt immediately (auto-run) instead
+	 * of filling the editor. When omitted, the default is derived from the
+	 * category: "Plan" tasks auto-run, everything else fills the editor.
+	 */
+	autoRun?: boolean;
 }
 
 /**
@@ -35,6 +41,25 @@ export interface ParsedDoAlwaysConfig {
 	shortcut: string | null | undefined;
 }
 
+/**
+ * The set of context keys the extension can inject into prompts (see
+ * `renderPrompt`). `index.ts` is responsible for supplying all of them (with
+ * neutral fallbacks when a fact is unavailable); tests use this to check that
+ * default prompts only reference known keys.
+ */
+export const PROMPT_CONTEXT_KEYS = [
+	"cwd",
+	"date",
+	"branch",
+	"last_commit",
+	"files_changed",
+	"files_changed_count",
+	"user",
+] as const;
+
+/** A fully populated prompt context: one entry per PROMPT_CONTEXT_KEYS. */
+export type PromptContext = Record<(typeof PROMPT_CONTEXT_KEYS)[number], string>;
+
 /** Used when neither config file defines any task. */
 export const DEFAULT_TASKS: DoAlwaysTask[] = [
 	{
@@ -42,7 +67,7 @@ export const DEFAULT_TASKS: DoAlwaysTask[] = [
 		category: "Plan",
 		description: "Review code and double-check changes (Plan)",
 		prompt:
-			"Review the recent code changes in this project. Check `git status` and `git diff` to see what changed, then double-check the changes for bugs, edge cases, security issues, and consistency with the rest of the codebase. Do a plan proposal for the fixes if needed. Do a summary of your findings",
+			"Review the changes on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}). Last commit: {{last_commit}}. Check `git status` and `git diff` to see what changed, then double-check the changes for bugs, edge cases, security issues, and consistency with the rest of the codebase. Do a plan proposal for the fixes if needed. Do a summary of your findings",
 	},
 	{
 		name: "Cleanup",
@@ -91,14 +116,14 @@ export const DEFAULT_TASKS: DoAlwaysTask[] = [
 		category: "Ops",
 		description: "Prepare a release (version, changelog, tag)",
 		prompt:
-			"Prepare a release for this project: check `git log` since the last tag, update the version in package.json (or the equivalent location), add a changelog entry summarizing the changes, and create a git tag if git present. Do not push.",
+			"Prepare a release for this project (branch {{branch}}): check `git log` since the last tag, update the version in package.json (or the equivalent location), add a changelog entry summarizing the changes, and create a git tag if git present. Do not push.",
 	},
 	{
 		name: "Commit",
 		category: "Ops",
 		description: "Prepare a clean commit",
 		prompt:
-			"Prepare the working tree for a clean commit: review `git status` and `git diff`, stage the relevant changes, and write a clear commit message describing what changed and why. Do not push.",
+			"Prepare the working tree on branch {{branch}} ({{files_changed_count}} changed files: {{files_changed}}) for a clean commit: stage the relevant changes, and write a clear commit message describing what changed and why. Do not push.",
 	},
 	{
 		name: "Propose features",
@@ -145,6 +170,7 @@ export function parseConfig(
 			};
 			if (typeof t.description === "string") task.description = t.description;
 			if (typeof t.category === "string" && t.category.trim() !== "") task.category = t.category.trim();
+			if (typeof t.autoRun === "boolean") task.autoRun = t.autoRun;
 			tasks.push(task);
 		} else {
 			onError(`do-always: skipping invalid task in ${path} (each task needs "name" and "prompt")`);
@@ -264,6 +290,17 @@ export function orderTasksByCategory(
 	return groupTasksByCategory(tasks, order).flatMap((g) => g.items);
 }
 
+/**
+ * Whether selecting a task should auto-run it (send its prompt immediately)
+ * instead of filling the editor. An explicit `autoRun` flag wins; otherwise the
+ * default is derived from the category — "Plan" tasks auto-run, everything else
+ * fills the editor.
+ */
+export function shouldAutoRun(task: DoAlwaysTask): boolean {
+	if (typeof task.autoRun === "boolean") return task.autoRun;
+	return (task.category ?? "").trim().toLowerCase() === "plan";
+}
+
 /**
  * Resolve a task from a command argument: by number (1-based) or by name (case-insensitive).
  */
@@ -277,6 +314,22 @@ export function resolveTask(tasks: DoAlwaysTask[], arg: string): DoAlwaysTask |
 	return tasks.find((t) => t.name.toLowerCase() === a.toLowerCase());
 }
 
+/** Matches a `{{key}}` placeholder: key is [A-Za-z0-9_]+, optional inner whitespace. */
+const PLACEHOLDER_RE = /\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g;
+
+/**
+ * Substitute `{{key}}` placeholders in `template` with values from `ctx`.
+ * A key that is not present in `ctx` is left as-is, so missing context stays
+ * visible instead of silently blanking the sentence; a key present with an
+ * empty-string value renders as empty. Templates without placeholders are
+ * returned unchanged, so existing plain prompts keep working.
+ */
+export function renderPrompt(template: string, ctx: Record<string, string>): string {
+	return template.replace(PLACEHOLDER_RE, (match, key: string) =>
+		Object.prototype.hasOwnProperty.call(ctx, key) ? ctx[key] : match,
+	);
+}
+
 /**
  * Render a numbered, one-line-per-task list. When tasks span more than one
  * category, a header line is emitted before each group (matching the selector).