pi-do-always 0.2.1 → 0.3.0

package/README.md

@@ -3,20 +3,29 @@
 A [Pi](https://github.com/earendil-works/pi) extension that gives you a `/do-always` command for your
 repeated "do the usual" prompts.
 
-Type `/do-always` → a numbered list of tasks appears → press a number (or arrows + Enter) →
-the task's prompt is **filled into the input editor**. Review it, tweak it, press Enter to run.
+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.
 
 ```text
-┌ do-always — pick a task                                           ┐
-│ 1. review   — Review code and double-check changes                │
-│ 2. readme   — Update the README                                   │
-│ 3. tests    — Run tests and fix failures                          │
-│ 4. commit   — Prepare a clean commit                              │
-│ 5. cleanup  — Propose a plan to clean up dead code and duplicates │
-│ 6. release  — Prepare a release (version, changelog, tag)         │
-│ 7. security — Security audit — plan proposal                      │
-│ 8. perf     — Performance review — plan proposal                  │
-└───────────────────────────────────────────────────────────────────┘
+  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)
+  DO
+  6. Build                Test build is ok and fix issues
+  7. Tests                Run tests and fix failures
+  DOCS
+  8. Readme               Update the README.md
+  OPS
+  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
 ```
 
 ![do-always — the numbered task selector](pi.image.png)
@@ -31,24 +40,26 @@ the task's prompt is **filled into the input editor**. Review it, tweak it, pres
 |`/do-always list`|Print the task list|
 |`/do-always list-details`|Show the full 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.
+
 In non-interactive modes (no TUI) there is no editor to fill, so the selected prompt is sent
 as a user message instead.
 
 ## Install
 
-Install it as a Pi package, which loads the bundled `index.ts` (and its `tasks.ts`) without
+Install it from npm as a Pi package, which loads the bundled `index.ts` (and its `tasks.ts`) without
 managing symlinks:
 
 ```bash
-pi install ./pi-always              # from a local copy of this repo
-pi install git:github.com/aginies/pi-always   # from the git repo
+pi install npm:pi-do-always
 ```
 
-(It is not on npm yet; once published it will be `pi install npm:pi-do-always`.)
-
 Manage it with `pi list` (to see installed sources) and `pi remove <source>` using the same
-source you installed with (e.g. `pi remove git:github.com/aginies/pi-always`). Alternatively, it is auto-discovered from
-the extensions directory, so you can symlink it instead:
+source you installed with (e.g. `pi remove npm:pi-do-always`).
+
+Alternatively, you can install from the git repo or symlink a local checkout for development:
 
 ```bash
 ln -s "$PWD" ~/.pi/agent/extensions/do-always   # uninstall with: rm that symlink
@@ -65,7 +76,7 @@ Tasks are read from JSON files (an array of tasks, or the object form `{"tasks":
 |`~/.pi/agent/do-always.json`|Global (all projects)|
 |`<project>/.pi/do-always.json`|Project-local; overrides global tasks with the same `name`|
 
-If neither file exists, the built-in defaults (review, readme, tests, commit, cleanup, release, security, perf) are used.
+If neither file exists, the built-in defaults (Review, Cleanup, Security, Performance, Propose features, Build, Tests, Readme, Release, Commit) are used.
 This repo ships a sample in [`do-always.json`](./do-always.json) — copy it to one of the
 locations above to make it your own:
 
@@ -73,6 +84,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` ..."
   }
@@ -82,6 +94,7 @@ locations above to make it your own:
 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
 
@@ -102,22 +115,3 @@ npm test           # run the unit tests (node:test + tsx, in test/)
 The pure task logic (`parseConfig`, `mergeTasks`, `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.
-
-No build step is needed — Pi loads the TypeScript directly via jiti.
-
-## Publishing
-
-To publish on npm:
-
-```bash
-npm login
-npm publish
-```
-
-`@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` are declared as `peerDependencies`
-with a `"*"` range and are **not** bundled — Pi supplies them to extensions. The `pi-package`
-keyword makes this package eligible for the [Pi package gallery](https://pi.dev/packages).
-
-The gallery page is built from `package.json` (name, description, author, version, license,
-repository, `pi` manifest) plus the README. Optional `pi.image` / `pi.video` fields in
-`package.json` add a gallery preview if you want one.

package/do-always.json

@@ -2,44 +2,64 @@
 	"shortcut": "f4",
 	"tasks": [
 		{
-			"name": "review",
-			"description": "Review code and double-check changes",
-			"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."
+			"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"
 		},
 		{
-			"name": "readme",
-			"description": "Update the README",
-			"prompt": "Update the README to match the current state of the project. Check the code, scripts, and configuration, then update the README sections that are now out of date (description, installation, usage, configuration). Keep it concise and accurate."
+			"name": "Cleanup",
+			"category": "Plan",
+			"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."
 		},
 		{
-			"name": "tests",
-			"description": "Run tests and fix failures",
-			"prompt": "Run the project's test suite (and type check / lint if available). If anything fails, diagnose and fix the failures, then re-run until green. Summarize the results."
+			"name": "Security",
+			"category": "Plan",
+			"description": "Security audit (Plan)",
+			"prompt": "Audit this project for security issues: hardcoded secrets or credentials, unsafe patterns (injection, path traversal, unsafe deserialization), and vulnerable or outdated dependencies. Do a plan proposal for the fixes. Do not make any changes yet."
 		},
 		{
-			"name": "commit",
-			"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."
+			"name": "Performance",
+			"category": "Plan",
+			"description": "Performance review (Plan)",
+			"prompt": "Review this project for likely performance bottlenecks: inefficient algorithms, redundant I/O or computation, missing caching, and memory leaks. Do a plan proposal for the optimizations, prioritized by impact. Do not make any changes yet."
 		},
 		{
-			"name": "cleanup",
-			"description": "Propose a plan to clean up dead code and duplicates",
-			"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."
+			"name": "Propose features",
+			"category": "Plan",
+			"description": "Propose new features (Plan)",
+			"prompt": "Review this project and propose new features that would add value. For each idea, describe the problem it solves, the user benefit, and a rough implementation approach. Prioritize by impact and effort. Do not make any changes yet."
 		},
 		{
-			"name": "release",
-			"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. Do not push."
+			"name": "Build",
+			"category": "Do",
+			"description": "Test build is ok and fix issues",
+			"prompt": "Build the project (run the build script, e.g. `npm run build`, plus type check if available). If the build fails, diagnose the errors and fix them, then re-build until it succeeds. Summarize what was broken and what you changed."
 		},
 		{
-			"name": "security",
-			"description": "Security audit — plan proposal",
-			"prompt": "Audit this project for security issues: hardcoded secrets or credentials, unsafe patterns (injection, path traversal, unsafe deserialization), and vulnerable or outdated dependencies. Do a plan proposal for the fixes. Do not make any changes yet."
+			"name": "Tests",
+			"category": "Do",
+			"description": "Run tests and fix failures",
+			"prompt": "Run the project's test suite (and type check / lint if available). If anything fails, diagnose and fix the failures, then re-run until green. Summarize the results."
 		},
 		{
-			"name": "perf",
-			"description": "Performance review — plan proposal",
-			"prompt": "Review this project for likely performance bottlenecks: inefficient algorithms, redundant I/O or computation, missing caching, and memory leaks. Do a plan proposal for the optimizations, prioritized by impact. Do not make any changes yet."
+			"name": "Readme",
+			"category": "Docs",
+			"description": "Update the README.md",
+			"prompt": "Update the README.md to match the current state of the project. Check the code, scripts, and configuration, then update the README.md sections that are now out of date (description, installation, usage, configuration). Keep it concise and accurate."
+		},
+		{
+			"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."
+		},
+		{
+			"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."
 		}
 	]
 }

package/index.ts

@@ -37,17 +37,27 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { Container, type KeyId, type SelectItem, SelectList, Text } from "@earendil-works/pi-tui";
+import {
+	type KeyId,
+	type TuiMouseEvent,
+	type TuiMouseEventResult,
+	getKeybindings,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
 import {
 	DEFAULT_SHORTCUT,
 	DEFAULT_TASKS,
 	formatList,
+	groupTasksByCategory,
 	isValidKeyId,
 	mergeTasks,
 	parseConfig,
+	orderTasksByCategory,
 	resolveShortcut,
 	resolveTask,
 	type DoAlwaysTask,
+	type TaskGroup,
 } from "./tasks";
 
 /**
@@ -67,11 +77,23 @@ function loadConfig(cwd: string): { tasks: DoAlwaysTask[]; shortcut: string | nu
 		: { tasks: [], shortcut: undefined };
 
 	return {
-		tasks: mergeTasks(global.tasks, project.tasks, DEFAULT_TASKS),
+		// Order the merged list by category so the selector numbers, digit-pick,
+		// `/do-always <n>`, and `list` all share one consistent order.
+		tasks: orderTasksByCategory(mergeTasks(global.tasks, project.tasks, DEFAULT_TASKS)),
 		shortcut: resolveShortcut(global.shortcut, project.shortcut),
 	};
 }
 
+/** 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));
+}
+
+/** True for a single printable ASCII character (used for filter typing). */
+function isPrintable(data: string): boolean {
+	return data.length === 1 && data >= " " && data <= "~";
+}
+
 export default function doAlwaysExtension(pi: ExtensionAPI) {
 	let tasks: DoAlwaysTask[] = [];
 	let loadedCwd = ""; // cwd the cached `tasks` were loaded for
@@ -91,14 +113,11 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 		}
 	}
 
-	/** Numbered selector: press 1-9 to pick, or arrows + Enter, Esc to cancel. */
+	/**
+	 * Numbered selector with categorized sections. Press 1-9 to pick by global
+	 * number, type to filter, or navigate with arrows + Enter, Esc to cancel.
+	 */
 	async function showSelector(ctx: ExtensionContext): Promise<void> {
-		const items: SelectItem[] = tasks.map((t, i) => ({
-			value: String(i),
-			label: `${i + 1}. ${t.name}`,
-			description: t.description,
-		}));
-
 		const selected = await ctx.ui.custom<number | null>((tui, theme, _kb, done) => {
 			let settled = false;
 			const finish = (value: number | null) => {
@@ -107,36 +126,181 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 				done(value);
 			};
 
-			const container = new Container();
-			container.addChild(new Text(theme.fg("accent", theme.bold("do-always — pick a task"))));
-
-			const selectList = new SelectList(items, Math.min(items.length, 10), {
-				selectedPrefix: (text) => theme.fg("accent", text),
-				selectedText: (text) => theme.fg("accent", text),
-				description: (text) => theme.fg("muted", text),
-				scrollInfo: (text) => theme.fg("dim", text),
-				noMatch: (text) => theme.fg("warning", text),
-			});
-			selectList.onSelect = (item) => finish(Number(item.value));
-			selectList.onCancel = () => finish(null);
-			container.addChild(selectList);
-			container.addChild(new Text(theme.fg("dim", "1-9 pick by number  •  ↑↓ navigate  •  enter select  •  esc cancel")));
+			// Group tasks under category headers, in a stable order.
+			const groups = groupTasksByCategory(tasks);
+
+			const kb = getKeybindings();
+			const maxVisible = 12;
+			let filter = "";
+			let selectedIndex = 0;
+			let mousePressedIndex: number | null = null;
+
+			const matchesFilter = (t: DoAlwaysTask) => {
+				if (!filter) return true;
+				const f = filter.toLowerCase();
+				return (
+					t.name.toLowerCase().includes(f) ||
+					(t.description ?? "").toLowerCase().includes(f) ||
+					(t.category ?? "").toLowerCase().includes(f)
+				);
+			};
+
+			// Recompute the visible (filtered, grouped) rows on every render so
+			// filter typing updates the list live.
+			function getVisible() {
+				const visibleGroups = groups
+					.map((g) => ({ name: g.name, items: g.items.filter(matchesFilter) }))
+					.filter((g) => g.items.length > 0);
+				const rows: Array<
+					| { kind: "header"; name: string }
+					| { kind: "item"; task: DoAlwaysTask; group: string }
+				> = [];
+				for (const g of visibleGroups) {
+					rows.push({ kind: "header", name: g.name });
+					for (const t of g.items) rows.push({ kind: "item", task: t, group: g.name });
+				}
+				const itemRows = rows.filter((r): r is (typeof rows)[number] & { kind: "item" } => r.kind === "item");
+				// Clamp selection to the visible item count.
+				selectedIndex = Math.max(0, Math.min(selectedIndex, Math.max(0, itemRows.length - 1)));
+				// Visible item window with scrolling.
+				const winStart = Math.max(0, Math.min(selectedIndex - Math.floor(maxVisible / 2), Math.max(0, itemRows.length - maxVisible)));
+				const visibleItemKeys = new Set(itemRows.slice(winStart, winStart + maxVisible).map((r) => r.task));
+				const visibleHeaderNames = new Set([...visibleItemKeys].map((t) => findGroupOf(t, visibleGroups)?.name ?? ""));
+				return { rows, itemRows, visibleItemKeys, visibleHeaderNames };
+			}
+
+			const labelCol = 26;
+
+			function renderLabel(task: DoAlwaysTask, globalIndex: number, isSelected: boolean, width: number): string {
+				const prefix = isSelected ? "▸ " : "  ";
+				const label = `${prefix}${globalIndex + 1}. ${task.name}`;
+				if (!task.description) {
+					const line = truncateToWidth(label, Math.max(1, width - 2), "");
+					return isSelected ? theme.fg("accent", theme.bold(line)) : line;
+				}
+				// Width-aware two-column layout; fall back to label-only when the
+				// terminal is too narrow to fit a description column.
+				const effCol = Math.max(1, Math.min(labelCol, width - 8));
+				const nameOnly = truncateToWidth(label, effCol, "");
+				const pad = " ".repeat(Math.max(1, effCol - visibleWidth(nameOnly)));
+				const remaining = width - visibleWidth(nameOnly) - pad.length - 2;
+				if (remaining < 10) {
+					const line = truncateToWidth(label, Math.max(1, width - 2), "");
+					return isSelected ? theme.fg("accent", theme.bold(line)) : line;
+				}
+				const desc = truncateToWidth(task.description, remaining, "");
+				if (isSelected) {
+					return theme.fg("accent", theme.bold(`${nameOnly}${pad}${desc}`));
+				}
+				return `${nameOnly}${pad}${theme.fg("muted", desc)}`;
+			}
+
+			// Build the full selector output for a width, plus a map from line
+			// index to task for the item rows (used by mouse handling).
+			function buildRender(width: number) {
+				const { rows, itemRows, visibleItemKeys, visibleHeaderNames } = getVisible();
+				const lines: string[] = [];
+				const itemLine = new Map<number, DoAlwaysTask>();
+				lines.push(theme.fg("accent", theme.bold("  do-always — pick a task")));
+				lines.push("");
+				if (itemRows.length === 0) {
+					lines.push(theme.fg("warning", "  No matching tasks"));
+				} else {
+					for (const row of rows) {
+						if (row.kind === "header") {
+							if (!visibleHeaderNames.has(row.name)) continue;
+							lines.push(theme.fg("accent", theme.bold(`  ${row.name.toUpperCase()}`)));
+							continue;
+						}
+						if (!visibleItemKeys.has(row.task)) continue;
+						const globalIndex = tasks.indexOf(row.task);
+						const isSelected = row.task === itemRows[selectedIndex].task;
+						lines.push(renderLabel(row.task, globalIndex, isSelected, width));
+						itemLine.set(lines.length - 1, row.task);
+					}
+					if (itemRows.length > maxVisible) {
+						const hint = `  (${selectedIndex + 1}/${itemRows.length})`;
+						lines.push(theme.fg("dim", truncateToWidth(hint, width - 2, "")));
+					}
+				}
+				lines.push("");
+				lines.push(
+					theme.fg(
+						"dim",
+						truncateToWidth("  1-9 pick by number  •  type to filter  •  ↑↓ navigate  •  enter select  •  esc cancel", width - 2, ""),
+					),
+				);
+				return { lines, itemLine, itemRows };
+			}
 
 			return {
 				render(width: number) {
-					return container.render(width);
-				},
-				invalidate() {
-					container.invalidate();
+					return buildRender(width).lines;
 				},
+				invalidate() {},
 				handleInput(data: string) {
-					// Direct pick by number (1-9)
-					if (/^[1-9]$/.test(data) && Number(data) <= tasks.length) {
+					// Direct pick by number (1-9) — only when not filtering, so
+					// digits can be typed into the filter otherwise.
+					if (!filter && /^[1-9]$/.test(data) && Number(data) <= tasks.length) {
 						finish(Number(data) - 1);
 						return;
 					}
-					selectList.handleInput(data);
-					tui.requestRender();
+					// Filter typing.
+					if (kb.matches(data, "tui.editor.deleteCharBackward")) {
+						filter = filter.slice(0, -1);
+						selectedIndex = 0;
+						tui.requestRender();
+						return;
+					}
+					if (isPrintable(data)) {
+						filter += data;
+						selectedIndex = 0;
+						tui.requestRender();
+						return;
+					}
+					// Navigation / confirmation.
+					const { itemRows } = getVisible();
+					if (kb.matches(data, "tui.select.up")) {
+						selectedIndex = selectedIndex === 0 ? itemRows.length - 1 : selectedIndex - 1;
+						tui.requestRender();
+					}
+					else if (kb.matches(data, "tui.select.down")) {
+						selectedIndex = selectedIndex === itemRows.length - 1 ? 0 : selectedIndex + 1;
+						tui.requestRender();
+					}
+					else if (kb.matches(data, "tui.select.confirm")) {
+						const chosen = itemRows[selectedIndex];
+						if (chosen) finish(tasks.indexOf(chosen.task));
+					}
+					else if (kb.matches(data, "tui.select.cancel")) {
+						finish(null);
+					}
+				},
+				handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+					if (event.type === "wheel" && event.wheelDelta) {
+						const { itemRows } = getVisible();
+						if (itemRows.length === 0) return undefined;
+						const delta = event.wheelDelta < 0 ? -1 : 1;
+						const prev = selectedIndex;
+						selectedIndex = Math.max(0, Math.min(itemRows.length - 1, selectedIndex + delta));
+						return { handled: true, render: selectedIndex !== prev };
+					}
+					if (event.button !== "left" || (event.type !== "press" && event.type !== "click")) return undefined;
+					const { itemLine, itemRows } = buildRender(event.width);
+					const task = itemLine.get(event.y);
+					if (!task) return undefined;
+					const idx = itemRows.findIndex((r) => r.task === task);
+					if (idx < 0) return undefined;
+					if (event.type === "press") {
+						mousePressedIndex = idx;
+						selectedIndex = idx;
+						return { handled: true, focus: true, render: true };
+					}
+					const clicked = mousePressedIndex ?? idx;
+					mousePressedIndex = null;
+					const chosen = itemRows[clicked];
+					if (chosen) finish(tasks.indexOf(chosen.task));
+					return { handled: true };
 				},
 			};
 		});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-do-always",
-	"version": "0.2.1",
+	"version": "0.3.0",
 	"type": "module",
 	"description": "Pi extension: /do-always — pick a common task by number, it fills your prompt",
 	"author": {
@@ -17,11 +17,11 @@
 	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/aginies/pi-always"
+		"url": "https://github.com/aginies/pi-do-always"
 	},
-	"homepage": "https://github.com/aginies/pi-always",
+	"homepage": "https://github.com/aginies/pi-do-always",
 	"bugs": {
-		"url": "https://github.com/aginies/pi-always/issues"
+		"url": "https://github.com/aginies/pi-do-always/issues"
 	},
 	"files": [
 		"index.ts",
@@ -39,7 +39,11 @@
 	"scripts": {
 		"dev": "pi --extension ./index.ts",
 		"typecheck": "tsc --noEmit",
-		"test": "node --import tsx --test test/**/*.test.ts"
+		"test": "node --import tsx --test test/*.test.ts",
+		"prepublishOnly": "npm run typecheck && npm test"
+	},
+	"publishConfig": {
+		"access": "public"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",

package/tasks.ts

@@ -7,6 +7,8 @@
 export interface DoAlwaysTask {
 	/** Short unique name, usable as /do-always <name> */
 	name: string;
+	/** Group header the task is shown under in the selector (e.g. "Plan", "Do"). */
+	category?: string;
 	/** Short one-line description shown next to the task in the selector */
 	description?: string;
 	/** Prompt filled into the editor when the task is selected */
@@ -36,52 +38,74 @@ export interface ParsedDoAlwaysConfig {
 /** Used when neither config file defines any task. */
 export const DEFAULT_TASKS: DoAlwaysTask[] = [
 	{
-		name: "review",
-		description: "Review code and double-check changes",
+		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.",
+			"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",
 	},
 	{
-		name: "readme",
-		description: "Update the README",
+		name: "Cleanup",
+		category: "Plan",
+		description: "Clean up dead code and duplicates (Plan)",
 		prompt:
-			"Update the README to match the current state of the project. Check the code, scripts, and configuration, then update the README sections that are now out of date (description, installation, usage, configuration). Keep it concise and accurate.",
+			"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.",
 	},
 	{
-		name: "tests",
-		description: "Run tests and fix failures",
+		name: "Readme",
+		category: "Docs",
+		description: "Update the README.md",
 		prompt:
-			"Run the project's test suite (and type check / lint if available). If anything fails, diagnose and fix the failures, then re-run until green. Summarize the results.",
+			"Update the README.md to match the current state of the project. Check the code, scripts, and configuration, then update the README.md sections that are now out of date (description, installation, usage, configuration). Keep it concise and accurate.",
 	},
 	{
-		name: "commit",
-		description: "Prepare a clean commit",
+		name: "Build",
+		category: "Do",
+		description: "Test build is ok and fix issues",
 		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.",
+			"Build the project (run the build script, e.g. `npm run build`, plus type check if available). If the build fails, diagnose the errors and fix them, then re-build until it succeeds. Summarize what was broken and what you changed.",
 	},
 	{
-		name: "cleanup",
-		description: "Propose a plan to clean up dead code and duplicates",
+		name: "Security",
+		category: "Plan",
+		description: "Security audit (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.",
+			"Audit this project for security issues: hardcoded secrets or credentials, unsafe patterns (injection, path traversal, unsafe deserialization), and vulnerable or outdated dependencies. Do a plan proposal for the fixes. Do not make any changes yet.",
+	},
+	{
+		name: "Performance",
+		category: "Plan",
+		description: "Performance review (Plan)",
+		prompt:
+			"Review this project for likely performance bottlenecks: inefficient algorithms, redundant I/O or computation, missing caching, and memory leaks. Do a plan proposal for the optimizations, prioritized by impact. Do not make any changes yet.",
+	},
+	{
+		name: "Tests",
+		category: "Do",
+		description: "Run tests and fix failures",
+		prompt:
+			"Run the project's test suite (and type check / lint if available). If anything fails, diagnose and fix the failures, then re-run until green. Summarize the results.",
 	},
 	{
-		name: "release",
+		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. Do not push.",
+			"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.",
 	},
 	{
-		name: "security",
-		description: "Security audit — plan proposal",
+		name: "Commit",
+		category: "Ops",
+		description: "Prepare a clean commit",
 		prompt:
-			"Audit this project for security issues: hardcoded secrets or credentials, unsafe patterns (injection, path traversal, unsafe deserialization), and vulnerable or outdated dependencies. Do a plan proposal for the fixes. Do not make any changes yet.",
+			"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.",
 	},
 	{
-		name: "perf",
-		description: "Performance review — plan proposal",
+		name: "Propose features",
+		category: "Plan",
+		description: "Propose new features (Plan)",
 		prompt:
-			"Review this project for likely performance bottlenecks: inefficient algorithms, redundant I/O or computation, missing caching, and memory leaks. Do a plan proposal for the optimizations, prioritized by impact. Do not make any changes yet.",
+			"Review this project and propose new features that would add value. For each idea, describe the problem it solves, the user benefit, and a rough implementation approach. Prioritize by impact and effort. Do not make any changes yet.",
 	},
 ];
 
@@ -115,11 +139,13 @@ export function parseConfig(
 	for (const entry of list) {
 		const t = entry as Partial<DoAlwaysTask> | null;
 		if (t && typeof t.name === "string" && t.name.length > 0 && typeof t.prompt === "string" && t.prompt.length > 0) {
-			tasks.push({
+			const task: DoAlwaysTask = {
 				name: t.name,
-				description: typeof t.description === "string" ? t.description : undefined,
 				prompt: t.prompt,
-			});
+			};
+			if (typeof t.description === "string") task.description = t.description;
+			if (typeof t.category === "string" && t.category.trim() !== "") task.category = t.category.trim();
+			tasks.push(task);
 		} else {
 			onError(`do-always: skipping invalid task in ${path} (each task needs "name" and "prompt")`);
 		}
@@ -187,6 +213,57 @@ export function mergeTasks(globalTasks: DoAlwaysTask[], projectTasks: DoAlwaysTa
 	return merged.length > 0 ? merged : fallback;
 }
 
+/** Default order for category headers in the selector. */
+export const DEFAULT_CATEGORY_ORDER = ["Plan", "Do", "Docs", "Ops", "Other"];
+
+/** A category group: a display name and the tasks that belong to it. */
+export interface TaskGroup {
+	name: string;
+	items: DoAlwaysTask[];
+}
+
+/** Capitalize the first letter of each word ("my-category" -> "My-Category"). */
+function titleCase(s: string): string {
+	return s.replace(/\b[a-z]/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Group tasks by category, case-insensitively. Categories are ordered by
+ * `order` (case-insensitive), then alphabetically; the original order within a
+ * group is preserved. The group `name` is the title-cased category. Tasks
+ * without a (non-empty) category fall under "Other".
+ */
+export function groupTasksByCategory(
+	tasks: DoAlwaysTask[],
+	order: string[] = DEFAULT_CATEGORY_ORDER,
+): TaskGroup[] {
+	const orderLower = order.map((o) => o.toLowerCase());
+	const groups = new Map<string, DoAlwaysTask[]>();
+	for (const t of tasks) {
+		const key = (t.category ?? "").trim().toLowerCase() || "other";
+		if (!groups.has(key)) groups.set(key, []);
+		groups.get(key)!.push(t);
+	}
+	const keys = [...groups.keys()].sort((a, b) => {
+		const na = orderLower.indexOf(a) === -1 ? order.length : orderLower.indexOf(a);
+		const nb = orderLower.indexOf(b) === -1 ? order.length : orderLower.indexOf(b);
+		return na - nb || a.localeCompare(b);
+	});
+	return keys.map((key) => ({ name: titleCase(key), items: groups.get(key)! }));
+}
+
+/**
+ * Return tasks in display order: grouped by category (see
+ * `groupTasksByCategory`), flattened. This is the canonical order the selector
+ * numbers, digit-pick, `/do-always <n>`, and `list` all share.
+ */
+export function orderTasksByCategory(
+	tasks: DoAlwaysTask[],
+	order: string[] = DEFAULT_CATEGORY_ORDER,
+): DoAlwaysTask[] {
+	return groupTasksByCategory(tasks, order).flatMap((g) => g.items);
+}
+
 /**
  * Resolve a task from a command argument: by number (1-based) or by name (case-insensitive).
  */
@@ -200,7 +277,21 @@ export function resolveTask(tasks: DoAlwaysTask[], arg: string): DoAlwaysTask |
 	return tasks.find((t) => t.name.toLowerCase() === a.toLowerCase());
 }
 
-/** Render a numbered, one-line-per-task list. */
+/**
+ * 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).
+ */
 export function formatList(tasks: DoAlwaysTask[]): string {
-	return tasks.map((t, i) => `${i + 1}. ${t.name} — ${t.description ?? ""}`).join("\n");
+	const groups = groupTasksByCategory(tasks);
+	const lines: string[] = [];
+	const showHeaders = groups.length > 1;
+	let n = 0;
+	for (const g of groups) {
+		if (showHeaders) lines.push(g.name.toUpperCase());
+		for (const t of g.items) {
+			n++;
+			lines.push(`${n}. ${t.name} — ${t.description ?? ""}`);
+		}
+	}
+	return lines.join("\n");
 }