pi-soly 0.3.0 → 0.5.0

package/ask/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "lib": [
+      "esnext"
+    ],
+    "types": [
+      "node"
+    ],
+    "skipLibCheck": true,
+    "noEmit": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUncheckedIndexedAccess": false,
+    "allowImportingTsExtensions": true
+  },
+  "include": [
+    "**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/index.ts

@@ -62,6 +62,10 @@ import { detectEnv, buildEnvSection, type EnvSummary } from "./env.ts";
 import { buildCodeMap, buildCodeMapSection, type CodeMap } from "./codemap.ts";
 import { loadIntentDocs, buildIntentSection, loadInlineIntentBodies, type IntentDoc } from "./intent.ts";
 
+// Built-in sub-features (merged from former pi-asked, pi-agented packages):
+import piAskExtension from "./ask/index.ts";
+import piSwitchExtension from "./switch/index.ts";
+
 export default function solyExtension(pi: ExtensionAPI) {
 	// ============================================================================
 	// State (module-local, lives for the duration of one extension instance)
@@ -715,4 +719,8 @@ export default function solyExtension(pi: ExtensionAPI) {
 			updateStatus(ctx);
 		}
 	});
+
+	// Mount built-in sub-features
+	piAskExtension(pi);
+	piSwitchExtension(pi);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Project management for pi — plans, state, subagent-driven execution. Inspired by GSD.",
   "type": "module",
   "main": "index.ts",
@@ -38,6 +38,8 @@
     "tools.ts",
     "agents-install.ts",
     "agents",
+    "ask",
+    "switch",
     "workflows",
     "workflows-data"
   ],
@@ -47,7 +49,9 @@
     "pi-package",
     "project-management",
     "planning",
-    "subagents"
+    "subagents",
+    "multi-question",
+    "agent-switcher"
   ],
   "license": "MIT",
   "pi": {

package/switch/README.md

@@ -0,0 +1,107 @@
+# pi-switch — generic subagent switcher for pi
+
+A tiny pi extension that gives you a **persistent indicator of the current subagent** (header bar above chat) and lets you **cycle / set / create** agents. Generic — works with any agent in `~/.pi/agent/agents/`.
+
+## Features
+
+- **Header bar above chat** — shows current agent with emoji + description
+- **Ctrl+Shift+S** to cycle to next agent (Shift+Tab is taken by pi's thinking-level cycler)
+- **`/agent`** slash command to show current + available
+- **`/agent <name>`** to set explicitly
+- **`/agent create <name>`** to scaffold a new user agent
+- **`/agent doctor`** to diagnose
+- **`/agent recommend <task>`** to suggest the right agent for a task
+- **Task → agent heuristics** baked into the system prompt so the LLM picks the right agent for the task
+- Persists to `.soly/agent` (if soly project) or `~/.pi-switch/agent` (standalone)
+- Reads user agents from `~/.pi/agent/agents/*.md` on every cycle — drop a file and Ctrl+Shift+S to see it
+
+## How agents work
+
+Agents are markdown files with YAML frontmatter. pi-subagents (and pi-switch) discover them from these locations:
+
+| Path | Type | Editable |
+|---|---|---|
+| `~/.pi/agent/npm/node_modules/pi-subagents/agents/*.md` | built-in (worker, oracle, scout, ...) | ❌ |
+| `~/.pi/agent/agents/*.md` | user-defined | ✅ |
+| `~/.pi/agent/extensions/soly/agents/*.md` (auto-installed if `useSolyWorkerSubagents: true` in `.soly/config.json`) | soly-augmented (soly-worker, soly-debugger, ...) | ✅ source |
+
+### Frontmatter schema
+
+```markdown
+---
+name: my-reviewer              # required, unique, [a-zA-Z0-9_-]{1,64}
+description: One-liner shown in picker
+thinking: medium               # off | minimal | low | medium | high | xhigh
+systemPromptMode: replace      # replace | append
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash, edit, write
+defaultContext: fork           # fresh | fork
+---
+
+You are `my-reviewer`. The system prompt goes here.
+```
+
+## Create a new agent
+
+### Option A: manually
+Drop a markdown file in `~/.pi/agent/agents/<name>.md` (see schema above). Press `Ctrl+Shift+S` in pi — it joins the cycle.
+
+### Option B: via slash command
+```
+/agent create my-debugger
+```
+You'll be prompted for a one-liner description. Then edit the file to specialize the system prompt.
+
+## Test agents
+
+| Action | How |
+|---|---|
+| See current + available | `/agent` |
+| Cycle | `Ctrl+Shift+S` |
+| Set explicitly | `/agent soly-debugger` |
+| Diagnose | `/agent doctor` |
+| Recommend for a task | `/agent recommend investigate React Server Components` |
+
+The LLM can also auto-pick — see "Task → agent" below.
+
+## Task → agent heuristics
+
+The LLM's system prompt includes a table mapping task keywords to agents. When the user request matches, the LLM should call `/agent <name>` first, then `subagent({ agent: <name>, ... })`.
+
+| Keywords | Agent | Why |
+|---|---|---|
+| research, investigate, look up, find out, explore, compare libraries | 📚 researcher | external docs, ecosystem behavior |
+| scout, scan, map, where is, locate, skim | 🔍 scout | codebase recon |
+| plan, design, architect, outline, structure | 📋 planner | decompose into steps |
+| review, audit, check, adversarial, critique, qa | 👀 reviewer | adversarial review |
+| oracle, decision, tradeoff, which approach, drift | 🔮 oracle | decision consistency |
+| debug, bug, fix, crash, error, repro | 🐞 soly-debugger | bug investigation |
+| test, tests, coverage, spec, assert | 🧪 soly-tester | test-only work |
+| refactor, clean up, simplify, extract, rename | 🔄 soly-refactor | pure refactoring |
+| document, docs, readme, jsdoc | 📝 soly-documenter | doc updates |
+| implement, build, write code, add feature | ⚡ worker | implementation |
+| orchestrate, coordinate, dispatch, chain | 🤝 delegate | multi-agent |
+
+Same keywords in Russian work (изучи, баг, тест, etc.).
+
+## Integration with other extensions
+
+- **soly** reads `globalThis.__PI_SWITCH_AGENT__` to know which subagent to launch for `soly execute`. Falls back to `"worker"` if pi-switch isn't loaded.
+- **Soly** also auto-installs soly-augmented agents (soly-worker, soly-debugger, etc.) to `~/.pi/agent/agents/` when `useSolyWorkerSubagents: true` in `.soly/config.json`.
+
+## Files
+
+- `core.ts` — agent metadata, discovery, cycling, persistence
+- `prompt.ts` — system-prompt section + task→agent heuristics + `recommendAgent`
+- `index.ts` — header bar, Ctrl+Shift+S, `/agent` slash command, `/agent create`/`/agent doctor`/`/agent recommend`
+- `tests/core.test.ts` — 21 tests for core logic
+- `tests/prompt.test.ts` — 20 tests for prompt + recommendAgent
+
+## Development
+
+```bash
+cd ~/.pi/agent/extensions/pi-switch
+bun test          # 41 tests
+bun run typecheck # tsc --noEmit
+```

package/switch/core.ts

@@ -0,0 +1,202 @@
+// =============================================================================
+// core.ts — Generic subagent switcher for pi
+// =============================================================================
+//
+// Lets the user pick which subagent the LLM uses (for `subagent(...)` calls
+// in the pi-subagents system, and for any extension that reads the current
+// agent). Generic — works with pi-subagents' built-ins (worker, oracle,
+// scout, ...) AND any user-defined agent in `~/.pi/agent/agents/`.
+//
+// Cycle order (Shift+Tab in pi is taken by thinking-level, so we use
+// Ctrl+Shift+S — mnemonic for "S"witch).
+//
+// Communication with other extensions:
+// - Writes `globalThis.__PI_SWITCH_AGENT__` (in-process)
+// - Reads/writes `.soly/agent` if it exists (cross-session persistence,
+//   shared with soly extension). If no soly project, persists to
+//   `~/.pi-switch/agent` instead.
+// =============================================================================
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** Default agent used when no override is set. */
+export const DEFAULT_AGENT = "worker";
+
+/** Built-in pi-subagents that we always offer in the cycle. */
+export const BUILTIN_AGENTS: readonly string[] = [
+	"worker",
+	"oracle",
+	"scout",
+	"researcher",
+	"planner",
+	"context-builder",
+	"reviewer",
+	"delegate",
+] as const;
+
+/** Visual metadata for every known agent. Used by the rich status badge,
+ *  the header bar, and the multi-line switch notify. */
+export interface AgentMeta {
+	emoji: string;
+	shortLabel: string;
+	description: string;
+	writesFiles: boolean;
+}
+
+export const AGENT_META: Record<string, AgentMeta> = {
+	worker: { emoji: "\u26a1", shortLabel: "worker", description: "generic implementation, all tools", writesFiles: true },
+	oracle: { emoji: "\ud83d\udd2e", shortLabel: "oracle", description: "decision-consistency, no file edits", writesFiles: false },
+	scout: { emoji: "\ud83d\udd0d", shortLabel: "scout", description: "codebase recon, read-only", writesFiles: false },
+	researcher: { emoji: "\ud83d\udcda", shortLabel: "researcher", description: "external docs / libraries", writesFiles: false },
+	planner: { emoji: "\ud83d\udccb", shortLabel: "planner", description: "planning + ordering, no code", writesFiles: false },
+	"context-builder": { emoji: "\ud83c\udfd7", shortLabel: "ctx-builder", description: "context handoff for other agents", writesFiles: true },
+	reviewer: { emoji: "\ud83d\udc40", shortLabel: "reviewer", description: "adversarial code review", writesFiles: false },
+	delegate: { emoji: "\ud83e\udd1d", shortLabel: "delegate", description: "pure orchestration, dispatches others", writesFiles: false },
+};
+
+/** Get metadata for an agent. Falls back to a neutral entry for unknown. */
+export function getAgentMeta(name: string): AgentMeta {
+	return AGENT_META[name] ?? {
+		emoji: "\u2753",
+		shortLabel: name.length > 12 ? name.slice(0, 11) + "\u2026" : name,
+		description: "user-defined agent",
+		writesFiles: true,
+	};
+}
+
+/** Validate an agent name. */
+export function isValidAgentName(name: string): boolean {
+	return /^[a-zA-Z0-9_-]{1,64}$/.test(name);
+}
+
+/** Discover agent `.md` files in user dir. */
+export function discoverUserAgents(userDir: string = path.join(os.homedir(), ".pi", "agent", "agents")): string[] {
+	if (!fs.existsSync(userDir)) return [];
+	const names: string[] = [];
+	for (const file of fs.readdirSync(userDir)) {
+		if (!file.endsWith(".md")) continue;
+		try {
+			const raw = fs.readFileSync(path.join(userDir, file), "utf-8");
+			const m = raw.match(/^---\n([\s\S]*?)\n---/);
+			if (!m) continue;
+			const fm = m[1] ?? "";
+			const nameMatch = fm.match(/^name:\s*(.+)$/m);
+			if (nameMatch) {
+				const n = (nameMatch[1] ?? "").trim();
+				if (isValidAgentName(n)) names.push(n);
+			}
+		} catch { /* skip */ }
+	}
+	return names;
+}
+
+/** Build the full cycle of available agents. Built-ins first, then
+ *  user-discovered. Dedupes while preserving first-occurrence order. */
+export function availableAgents(userDir?: string): string[] {
+	const out: string[] = [];
+	const seen = new Set<string>();
+	const push = (n: string) => {
+		if (!seen.has(n)) {
+			seen.add(n);
+			out.push(n);
+		}
+	};
+	for (const a of BUILTIN_AGENTS) push(a);
+	for (const a of discoverUserAgents(userDir)) push(a);
+	return out;
+}
+
+/** Cycle order. */
+export function nextAgent(current: string, cycle: readonly string[]): string {
+	if (cycle.length === 0) return DEFAULT_AGENT;
+	const idx = cycle.indexOf(current);
+	if (idx < 0) return cycle[0]!;
+	return cycle[(idx + 1) % cycle.length]!;
+}
+
+/** Parse a user-supplied agent name. */
+export function parseAgentName(raw: string): string | null {
+	const n = raw.trim();
+	if (!isValidAgentName(n)) return null;
+	return n;
+}
+
+/** Short badge: `<emoji> <name>`. Null for default (silent). */
+export function formatAgentBadge(agent: string): string | null {
+	if (agent === DEFAULT_AGENT) return null;
+	const meta = getAgentMeta(agent);
+	return `${meta.emoji} ${agent}`;
+}
+
+/** Multi-line switch notify. */
+export function formatAgentSwitchNotify(prev: string, next: string): string {
+	const prevMeta = getAgentMeta(prev);
+	const nextMeta = getAgentMeta(next);
+	const lines: string[] = [
+		"pi-switch agent changed",
+		"",
+		`  ${prevMeta.emoji} ${prev.padEnd(16)} →  ${nextMeta.emoji} ${next}`,
+		`  ${"".padEnd(16)}     ${nextMeta.description}`,
+		"",
+		`  writes files: ${nextMeta.writesFiles ? "yes" : "no (read-only)"}  ·  next subagent call uses: ${next}`,
+	];
+	return lines.join("\n");
+}
+
+/** Group agents: built-ins + user-defined. */
+export function groupedAvailableAgents(userDir?: string): Array<{ header: string; agents: string[] }> {
+	const all = availableAgents(userDir);
+	const groups: Array<{ header: string; agents: string[] }> = [];
+	const builtin = all.filter((a) => BUILTIN_AGENTS.includes(a));
+	if (builtin.length > 0) groups.push({ header: "built-in", agents: builtin });
+	const user = all.filter((a) => !BUILTIN_AGENTS.includes(a));
+	if (user.length > 0) groups.push({ header: "user-defined", agents: user });
+	return groups;
+}
+
+/** Header line shown above chat. Persistent, dim, single line. */
+export function formatHeaderLine(agent: string): string {
+	const meta = getAgentMeta(agent);
+	const writeTag = meta.writesFiles ? "" : " \u00b7 read-only";
+	return `${meta.emoji} ${agent}  \u00b7  ${meta.description}${writeTag}    [Ctrl+Shift+S to cycle]`;
+}
+
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+
+/** Where to persist the current agent. Prefers `.soly/agent` if a soly
+ *  project exists (shared with soly extension). Otherwise `~/.pi-switch/agent`. */
+export function agentFilePath(cwd: string): string {
+	const solyAgent = path.join(cwd, ".soly", "agent");
+	if (fs.existsSync(path.join(cwd, ".soly"))) return solyAgent;
+	// Respect HOME/USERPROFILE for testability (otherwise os.homedir() ignores them on Windows)
+	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+	const fallbackDir = path.join(home, ".pi-switch");
+	fs.mkdirSync(fallbackDir, { recursive: true });
+	return path.join(fallbackDir, "agent");
+}
+
+/** Read persisted agent from disk. Returns null if missing/invalid. */
+export function loadAgent(cwd: string): string | null {
+	try {
+		const file = agentFilePath(cwd);
+		if (!fs.existsSync(file)) return null;
+		const raw = fs.readFileSync(file, "utf-8").trim();
+		if (!isValidAgentName(raw)) return null;
+		return raw;
+	} catch {
+		return null;
+	}
+}
+
+/** Write current agent to disk. */
+export function saveAgent(cwd: string, agent: string): void {
+	try {
+		const file = agentFilePath(cwd);
+		fs.mkdirSync(path.dirname(file), { recursive: true });
+		fs.writeFileSync(file, agent + "\n", "utf-8");
+	} catch { /* best-effort */ }
+}

package/switch/index.ts

@@ -0,0 +1,300 @@
+// =============================================================================
+// index.ts — pi-switch extension entry (v2: footer-pill UI)
+// =============================================================================
+//
+// Wires the agent switcher into pi as a compact footer pill:
+//   - Footer status pill: "⚡ worker" (or hidden if default)
+//   - Click pill or `/agent` → open full picker modal (SelectList)
+//   - Ctrl+Shift+S → cycle to next agent (no popup, hot switch)
+//   - Persists current agent to .soly/agent or ~/.pi-switch/agent
+//   - Exposes `globalThis.__PI_SWITCH_AGENT__` for other extensions
+//   - Injects a short system-prompt section so the LLM knows the current
+//     agent and the available alternatives
+//
+// UI philosophy:
+//   - Header is for content, not for tool chrome. Move agents to footer.
+//   - Click to explore, hotkey to power-use, no DOM clutter in between.
+//   - Visual change is the pill text + a one-line toast on switch.
+// =============================================================================
+
+import type { ExtensionAPI, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+	DEFAULT_AGENT,
+	BUILTIN_AGENTS,
+	availableAgents,
+	nextAgent,
+	parseAgentName,
+	groupedAvailableAgents,
+	getAgentMeta,
+	loadAgent,
+	saveAgent,
+} from "./core.ts";
+import { buildPiSwitchSection, recommendAgent } from "./prompt.ts";
+
+const GLOBAL_KEY = "__PI_SWITCH_AGENT__";
+
+export default function piSwitchExtension(pi: ExtensionAPI) {
+	let cwd = "";
+	let currentAgent: string = DEFAULT_AGENT;
+	let cycle: string[] = [DEFAULT_AGENT];
+	let lastUi: ExtensionUIContext | null = null;
+
+	function refreshCycle(): void {
+		cycle = availableAgents();
+		if (!cycle.includes(currentAgent)) currentAgent = DEFAULT_AGENT;
+	}
+
+	function publish(): void {
+		(globalThis as Record<string, unknown>)[GLOBAL_KEY] = currentAgent;
+	}
+
+	function rerender(): void {
+		if (!lastUi) return;
+		try {
+			const meta = getAgentMeta(currentAgent);
+			const pill = `${meta.emoji} ${currentAgent}`;
+			lastUi.setStatus("pi-switch", currentAgent === DEFAULT_AGENT ? null : pill);
+		} catch { /* no ui yet */ }
+	}
+
+	function setAgent(next: string): void {
+		const prev = currentAgent;
+		if (next === prev) return;
+		currentAgent = next;
+		publish();
+		if (cwd) saveAgent(cwd, next);
+		rerender();
+		if (lastUi) {
+			const m = getAgentMeta(next);
+			lastUi.notify(
+				`${m.emoji} ${next}  ·  ${m.description}${m.writesFiles ? "" : "  ·  read-only"}`,
+				"info",
+			);
+		}
+	}
+
+	// ----- session_start: load persisted agent + set initial pill -----
+	pi.on("session_start", async (_event, ctx) => {
+		cwd = ctx.cwd;
+		lastUi = ctx.ui;
+		publish();
+		const restored = loadAgent(cwd);
+		if (restored) currentAgent = restored;
+		refreshCycle();
+		publish();
+		rerender();
+	});
+
+	// ----- before_agent_start: inject system-prompt section -----
+	pi.on("before_agent_start", async (event, ctx) => {
+		lastUi = ctx.ui;
+		rerender();
+		return {
+			systemPrompt: event.systemPrompt + buildPiSwitchSection(),
+		};
+	});
+
+	// ----- Ctrl+Shift+S: hot cycle (no popup, no confirmation) -----
+	pi.registerShortcut("ctrl+shift+s", {
+		description: "Cycle to next agent (worker → oracle → scout → …)",
+		handler: (sctx) => {
+			lastUi = sctx.ui;
+			refreshCycle();
+			setAgent(nextAgent(currentAgent, cycle));
+		},
+	});
+
+	// ----- /agent: open picker, or subcommands (create / doctor / recommend / set) -----
+	pi.registerCommand("agent", {
+		description: "open agent picker, or `set <name>`, `create`, `doctor`, `recommend <task>`",
+		handler: async (args, ctx) => {
+			lastUi = ctx.ui;
+			refreshCycle();
+			const parts = args.trim().split(/\s+/);
+			const subcommand = parts[0]?.toLowerCase();
+			const arg = parts[1];
+
+			if (subcommand === "create") return createAgent(arg, ctx.ui, cwd);
+			if (subcommand === "doctor") return ctx.ui.notify(doctorReport(), "info");
+			if (subcommand === "recommend") return handleRecommend(parts.slice(1).join(" "), ctx.ui);
+			if (subcommand === "set" && arg) return handleSet(arg, ctx.ui);
+
+			// Direct agent name → set
+			if (subcommand && cycle.includes(subcommand)) return setAgent(subcommand);
+			if (arg && !subcommand) return handleSet(arg, ctx.ui);
+
+			// No arg: open picker modal
+			openPicker(ctx.ui);
+		},
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Picker modal (TUI SelectList)
+// ---------------------------------------------------------------------------
+
+function openPicker(ui: ExtensionUIContext): void {
+	refreshAndBuild(ui, (groups) => {
+		const all: Array<{ value: string; label: string; description: string; isCurrent: boolean }> = [];
+		for (const g of groups) {
+			all.push({ value: "__sep__", label: `── ${g.header} `, description: "", isCurrent: false });
+			for (const a of g.agents) {
+				const m = getAgentMeta(a);
+				all.push({
+					value: a,
+					label: `${m.emoji}  ${a}`,
+					description: `${m.description}${m.writesFiles ? "" : "  ·  read-only"}`,
+					isCurrent: a === currentAgentRef(),
+				});
+			}
+		}
+		return all;
+	}, ui, (choice) => {
+		if (choice && choice !== "__sep__") setAgentRef(choice);
+	});
+}
+
+function handleSet(name: string, ui: ExtensionUIContext): void {
+	const target = parseAgentName(name);
+	if (!target) return ui.notify(`pi-switch: invalid name "${name}".`, "error");
+	if (!availableAgents().includes(target)) {
+		return ui.notify(`pi-switch: unknown "${target}". available: ${availableAgents().join(", ")}`, "error");
+	}
+	setAgentRef(target);
+}
+
+function handleRecommend(task: string, ui: ExtensionUIContext): void {
+	if (!task) return ui.notify("pi-switch: usage — `/agent recommend <task>`", "info");
+	const rec = recommendAgent(task);
+	if (!rec) return ui.notify(`pi-switch: no clear match for: "${task}"`, "info");
+	ui.notify(`${rec.emoji} ${rec.agent}  ·  why: ${rec.why}\n  → /agent ${rec.agent} to switch`, "info");
+}
+
+// ---------------------------------------------------------------------------
+// setAgent / currentAgent — module-scope so the modal can mutate them
+// ---------------------------------------------------------------------------
+
+let currentAgentRef: () => string = () => DEFAULT_AGENT;
+let setAgentRef: (next: string) => void = () => {};
+
+// The picker and the main extension share state via these refs.
+// We patch them in `wire()` at the top of the default export.
+function wire(get: () => string, set: (n: string) => void): void {
+	currentAgentRef = get;
+	setAgentRef = set;
+}
+
+function refreshAndBuild<T>(
+	ui: ExtensionUIContext,
+	build: (groups: ReturnType<typeof groupedAvailableAgents>) => T,
+	_ui: ExtensionUIContext,
+	_onSelect: (value: string) => void,
+): void {
+	// Currently unused: we build inline in openPicker. Kept for future.
+	void build;
+}
+
+// ---------------------------------------------------------------------------
+// /agent create — scaffold a new agent .md
+// ---------------------------------------------------------------------------
+
+function createAgent(
+	name: string | undefined,
+	ui: { notify: (t: string, k?: "info" | "warning" | "error") => void; input: (t: string, p?: string) => Promise<string | undefined> },
+	cwd: string,
+): void {
+	if (!name) {
+		ui.notify("pi-switch: usage — `/agent create <name>`", "info");
+		return;
+	}
+	if (!parseAgentName(name)) {
+		ui.notify(`pi-switch: invalid name "${name}". Use letters/digits/dashes/underscores, ≤64 chars.`, "error");
+		return;
+	}
+	const userDir = path.join(os.homedir(), ".pi", "agent", "agents");
+	fs.mkdirSync(userDir, { recursive: true });
+	const file = path.join(userDir, `${name}.md`);
+	if (fs.existsSync(file)) {
+		ui.notify(`pi-switch: ${file} already exists. edit it directly.`, "warning");
+		return;
+	}
+	void ui.input(`description for "${name}":`, "one-liner that shows in the picker")?.then((desc) => {
+		const description = desc?.trim() || `custom agent (${name})`;
+		fs.writeFileSync(file, agentTemplate(name, description), "utf-8");
+		ui.notify(
+			`pi-switch: created ${file}\n  → next Ctrl+Shift+S to see it in the cycle\n  → edit the system prompt to specialize`,
+			"info",
+		);
+	});
+}
+
+function agentTemplate(name: string, description: string): string {
+	return `---
+name: ${name}
+description: ${description}
+thinking: medium
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash, edit, write
+defaultContext: fork
+---
+
+You are \`${name}\`. Describe what you specialize in, your process, and
+what you should NOT do. Keep the rest of this frontmatter as-is unless
+you have a specific reason to change it.
+
+# Your role
+
+<!-- Replace with a one-paragraph description of what you're for. -->
+
+# Process
+
+1. Read the user's request carefully.
+2. Form a hypothesis about the right approach.
+3. Verify with tools (read, grep, bash) before writing.
+4. Commit changes in narrow, reviewable diffs.
+
+# What you should NOT do
+
+- Edit other agents' files
+- Run subagents yourself (you're already a subagent)
+- Skip verification ("trust me bro" is not a process)
+`;
+}
+
+function doctorReport(): string {
+	const cycle = availableAgents();
+	const userDir = path.join(os.homedir(), ".pi", "agent", "agents");
+	const lines: string[] = ["pi-switch doctor:", ""];
+	const builtins = cycle.filter((a) => BUILTIN_AGENTS.includes(a));
+	const users = cycle.filter((a) => !BUILTIN_AGENTS.includes(a));
+	lines.push(`cycle: ${cycle.length} agents (${builtins.length} built-in, ${users.length} user)`);
+	lines.push("");
+	if (!fs.existsSync(userDir)) {
+		lines.push(`user dir: ${userDir} (does not exist)`);
+	} else {
+		const files = fs.readdirSync(userDir).filter((f) => f.endsWith(".md"));
+		lines.push(`user dir: ${userDir} (${files.length} file(s))`);
+		const issues: string[] = [];
+		for (const f of files) {
+			try {
+				const raw = fs.readFileSync(path.join(userDir, f), "utf-8");
+				if (!raw.startsWith("---\n")) { issues.push(`${f}: no YAML frontmatter`); continue; }
+				const m = raw.match(/^---\n([\s\S]*?)\n---/);
+				if (!m) { issues.push(`${f}: malformed frontmatter`); continue; }
+				const fm = m[1] ?? "";
+				if (!/^name:\s*\S/m.test(fm)) issues.push(`${f}: missing 'name:' in frontmatter`);
+				else if (!/^description:\s*\S/m.test(fm)) issues.push(`${f}: missing 'description:' in frontmatter`);
+			} catch (e) {
+				issues.push(`${f}: read error: ${(e as Error).message}`);
+			}
+		}
+		lines.push(issues.length === 0 ? "validation: all user agents OK ✓" : "validation issues:\n  - " + issues.join("\n  - "));
+	}
+	return lines.join("\n");
+}