pi-soly 0.7.0 → 0.9.0

package/README.md

@@ -78,7 +78,7 @@ State lives in `.soly/` — portable, git-friendly, human-readable.
 
 ### 🎤 Multi-Question Picker
 
-Claude Code-style `ask_pro` for the LLM. Single-select, multi-select, recommended ⭐, free-text Other.
+Multi-question picker `ask_pro` for the LLM. Tabbed UI: single-select, multi-select, recommended ⭐, free-text Other.
 
 ```ts
 ask_pro({

package/agents-install.ts

@@ -34,10 +34,15 @@ const SHIPPED_SKILLS = [
 ] as const;
 
 /** Where pi looks for user agents. Respects HOME/USERPROFILE for
- *  testability (otherwise we'd always write to the real user home). */
-function userAgentsDir(): string {
+ *  testability (otherwise we'd always write to the real user home).
+ *  Path scheme: `<root>/.agents/agents/` (vendor-neutral) and
+ *  `<root>/.pi/agent/agents/` (pi native, legacy). */
+function userAgentsDirs(): string[] {
 	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
-	return path.join(home, ".pi", "agent", "agents");
+	return [
+		path.join(home, ".agents", "agents"),                // vendor-neutral (preferred)
+		path.join(home, ".pi", "agent", "agents"),           // pi native
+	];
 }
 
 /** Where pi looks for user skills. */
@@ -87,20 +92,27 @@ function copyDirIfMissing(from: string, to: string): "installed" | "skipped" | "
 	}
 }
 
-/** Install shipped soly agents to `~/.pi/agent/agents/`. Idempotent. */
+/** Install shipped soly agents to `~/.agents/` (vendor-neutral,
+ *  preferred). Legacy `~/.pi/agent/agents/` copies are left alone —
+ *  `discoverUserAgents` reads both, so old installs still work. */
 export function installSolyAgents(extensionRoot: string): InstallResult {
 	const result: InstallResult = { installed: [], skipped: [], errors: [] };
 	const src = shippedAgentsDir(extensionRoot);
-	const dst = userAgentsDir();
 
 	if (!fs.existsSync(src)) return result; // dev mode no-op
 
-	try {
-		fs.mkdirSync(dst, { recursive: true });
-	} catch (err) {
-		result.errors.push(`mkdir ${dst}: ${(err as Error).message}`);
-		return result;
+	// Try vendor-neutral first, then fall back to pi's native dir.
+	let dst: string | null = null;
+	for (const candidate of userAgentsDirs()) {
+		try {
+			fs.mkdirSync(candidate, { recursive: true });
+			dst = candidate;
+			break;
+		} catch (err) {
+			result.errors.push(`mkdir ${candidate}: ${(err as Error).message}`);
+		}
 	}
+	if (!dst) return result;
 
 	for (const name of SHIPPED_AGENTS) {
 		const from = path.join(src, name);
@@ -145,20 +157,18 @@ export function installSolyAssets(extensionRoot: string): {
 	};
 }
 
-/** Check which shipped soly agents are present in the user dir. Used by doctor. */
+/** Check which shipped soly agents are present across all user agent
+ *  homes. A file counts as "installed" if it's in ANY of the dirs. */
 export function checkSolyAgentsInstalled(extensionRoot: string): {
 	installed: string[];
 	missing: string[];
 } {
-	const dst = userAgentsDir();
 	const installed: string[] = [];
 	const missing: string[] = [];
 	for (const name of SHIPPED_AGENTS) {
-		if (fs.existsSync(path.join(dst, name))) {
-			installed.push(name);
-		} else {
-			missing.push(name);
-		}
+		const present = userAgentsDirs().some((dir) => fs.existsSync(path.join(dir, name)));
+		if (present) installed.push(name);
+		else missing.push(name);
 	}
 	return { installed, missing };
 }

package/ask/README.md

@@ -1,8 +1,7 @@
-# pi-ask — Claude Code-style multi-question picker for pi
+# pi-ask — multi-question picker for pi
 
 A small pi-coding-agent extension that registers one tool (`ask_pro`) for
-showing a **tabbed, multi-question picker** in pi's TUI. Inspired by Claude
-Code's `AskUserQuestion`.
+showing a **tabbed, multi-question picker** in pi's TUI.
 
 ## Features
 
@@ -88,10 +87,10 @@ Result:
 | `Enter` | **Single-select:** confirm + advance (or submit on last). **Multi-select:** advance to next question (or submit on last + all answered). Does NOT toggle. |
 | `Esc` | Cancel (returns `{cancelled: true}`) |
 
-Multi-select follows the Claude Code convention: **Space toggles, Enter
-advances/submits**. Single-select uses Enter as the universal action key
-(toggle/pick + advance). When you're on the last question and all
-questions are answered, the footer shows `⏎ submit` in accent color.
+Multi-select: **Space toggles, Enter advances/submits**. Single-select
+uses Enter as the universal action key (toggle/pick + advance). When
+you're on the last question and all questions are answered, the footer
+shows `⏎ submit` in accent color.
 
 ## Limits
 
@@ -101,30 +100,15 @@ questions are answered, the footer shows `⏎ submit` in accent color.
 - At most 1 `recommended: true` per question
 - TUI and RPC modes only (`hasUI: true`); print mode returns an error
 
-## Setup
-
-Drop the directory in `~/.pi/agent/extensions/`:
-
-```bash
-ls ~/.pi/agent/extensions/pi-ask/
-# index.ts picker.ts tests/ package.json tsconfig.json README.md
-```
-
-pi auto-discovers and loads it on next start. The `ask_pro` tool is then
-available to the LLM. No config required.
-
 ## Development
 
 ```bash
-cd ~/.pi/agent/extensions/pi-ask
+cd packages/pi-soly/ask
 bun test              # runs tests/picker.test.ts
 bun run typecheck     # tsc --noEmit
 ```
 
-CI: not configured (this is a single-file TUI component, low risk).
-Add `.github/workflows/ci.yml` if you want green-tick PRs.
-
-## Why a separate extension?
+## Why a separate module?
 
 The picker is **generic** — any pi extension (soly, your own tool, etc.) can
 use `ask_pro` to drive multi-question Q&A without re-implementing the TUI.

package/ask/index.ts

@@ -3,7 +3,7 @@
 // =============================================================================
 //
 // Registers one LLM tool: `ask_pro`. Lets the LLM ask the user a list of
-// questions at once via a Claude Code-style tabbed picker (tabs, numbered
+// questions at once via a tabbed picker (tabs, numbered
 // options, ⭐ recommended answer, optional multi-select). All answers
 // returned in a single call.
 //
@@ -39,7 +39,7 @@ export default function piAskExtension(pi: ExtensionAPI) {
 		name: "ask_pro",
 		label: "pi-ask ask_pro",
 		description:
-			"Ask the user multiple questions at once via a Claude Code-style tabbed picker. Each question is a tab at the top. Options are numbered (1-N instant-pick), the recommended answer is marked ⭐. Supports single-select (default, auto-advance on pick) and multi-select (Enter toggles, last question shows Submit). All answers returned in one call. Use for progressive Q&A flows like `soly discuss`.",
+			"Ask the user multiple questions at once via a tabbed picker. Each question is a tab at the top. Options are numbered (1-N instant-pick), the recommended answer is marked ⭐. Supports single-select (default, auto-advance on pick) and multi-select (Enter toggles, last question shows Submit). All answers returned in one call. Use for progressive Q&A flows like `soly discuss`.",
 		parameters: Type.Object({
 			questions: Type.Array(
 				Type.Object({

package/ask/picker.ts

@@ -1,5 +1,5 @@
 // =============================================================================
-// picker.ts — Claude Code-style multi-question picker TUI component
+// picker.ts — multi-question picker TUI component
 // =============================================================================
 //
 // Renders a tabbed multi-question flow inside pi's TUI. One `ask_pro` tool
@@ -493,7 +493,7 @@ export class AskProComponent extends Container {
 			return;
 		}
 
-		// Space — toggle in multi-select (Claude Code convention).
+		// Space — toggle in multi-select.
 		// On "Other…", opens the input dialog (or toggles existing custom string).
 		// In single-select, Space is a no-op (Enter is the action key there).
 		if (keyData === KEY_SPACE) {

package/ask/tests/picker.test.ts

@@ -247,7 +247,7 @@ describe("AskProComponent — multi-select", () => {
 		expect(picker.getAnswers().get(0)).toEqual([0]); // multi preserved
 	});
 
-	test("Space toggles current selection in multi-select (Claude Code style)", () => {
+	test("Space toggles current selection in multi-select", () => {
 		const { picker } = setup(multiQuestions);
 		picker.handleInput("j"); // selectedIndex = 1 (Tokens)
 		picker.handleInput(" "); // Space toggles

package/index.ts

@@ -353,10 +353,14 @@ export default function solyExtension(pi: ExtensionAPI) {
 		// Rules sources (priority order, higher wins on relPath collision).
 		// Project rules always beat global rules. .soly/rules.local/ is
 		// gitignored — for personal overrides on top of the project's rules.
+		// .agents/rules/ is the vendor-neutral project-level convention
+		// (same role as the old .claude/rules/).
 		ruleSources = [
 			{ dir: path.join(ctx.cwd, ".soly", "rules.local"), source: "project-soly", sourceLabel: "local", priority: 5 },
 			{ dir: path.join(ctx.cwd, ".soly", "rules"), source: "project-soly", sourceLabel: "soly", priority: 4 },
+			{ dir: path.join(ctx.cwd, ".agents", "rules"), source: "project-agents", sourceLabel: "agents", priority: 3 },
 			{ dir: path.join(os.homedir(), ".soly", "rules"), source: "global-soly", sourceLabel: "soly", priority: 2 },
+			{ dir: path.join(os.homedir(), ".agents", "rules"), source: "global-agents", sourceLabel: "agents", priority: 1 },
 		];
 		refreshRules();
 

package/integrations.ts

@@ -29,7 +29,7 @@ export const KNOWN_INTEGRATIONS: KnownIntegration[] = [
 	{
 		tool: "ask_pro",
 		extension: "pi-ask",
-		summary: "Multi-question tabbed picker (Claude Code style).",
+		summary: "Multi-question tabbed picker.",
 		whenToUse:
 			"Use instead of `soly_ask_user` for `soly discuss` flows when you have multiple related questions. PREFERRED in `soly discuss` when available.",
 	},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Project management framework for pi-coding-agent. Workflows, planning, multi-question picker, agent switcher, live task list — one npm install, zero config.",
   "type": "module",
   "main": "index.ts",

package/skills/soly-framework/SKILL.md

@@ -43,13 +43,15 @@ The **soly** extension adds project-management workflow to [pi-coding-agent](htt
 
 ```
 <project-root>/
-├── .soly/
+├── AGENTS.md                      # vendor-neutral agent context (loaded by pi)
+├── agents.md                      # same as AGENTS.md, lowercase accepted
+├── .soly/                         # soly state (phases, plans, summaries)
 │   ├── ROADMAP.md                 # phase table
 │   ├── STATE.md                   # current position + decisions log
 │   ├── docs/                      # 0-point intent docs (human-written, locked)
 │   │   ├── vision.md
 │   │   └── architecture.md
-│   ├── rules/                     # project rules (version-controlled)
+│   ├── rules/                     # soly project rules (version-controlled)
 │   │   ├── code-style.md
 │   │   └── testing.md
 │   ├── phases/
@@ -65,8 +67,26 @@ The **soly** extension adds project-management workflow to [pi-coding-agent](htt
 │   ├── iterations/                # per-execution context bundles (auto)
 │   ├── HANDOFF.json               # pause snapshot
 │   └── .continue-here.md          # pause resume marker
+├── .agents/                       # vendor-neutral agent config (per project)
+│   ├── rules/                     # agent rules (loaded with priority 3, after .soly/rules/)
+│   │   ├── code-style.md
+│   │   └── testing.md
+│   ├── skills/                    # project-scoped skills (pi auto-discovers)
+│   │   └── my-skill/
+│   │       └── SKILL.md
+│   ├── docs/                      # agent-specific docs (intent-style)
+│   │   └── architecture.md
+│   └── agents/                    # project-specific agent definitions
+│       ├── project-reviewer.md
+│       └── data-scientist.md
 ```
 
+**Two parallel conventions:** `.soly/` is soly-specific state (phases, plans). `.agents/` is vendor-neutral agent config (works with any AI tool that follows the AGENTS.md standard). The two coexist:
+
+- Use `.soly/` for soly workflow artifacts (PLAN.md, SUMMARY.md, etc.)
+- Use `.agents/` for things other AI tools should also see (rules, skills, agents)
+- Use `AGENTS.md` for top-level project-wide agent conventions
+
 ## Frontmatter conventions
 
 ### PLAN.md frontmatter (required)
@@ -274,8 +294,32 @@ Intent docs are 0-point — written BEFORE any plan, by humans. They define the
 
 1. `soly init` (or manually create `.soly/`, `docs/`, `rules/`)
 2. Write 1-3 intent docs in `.soly/docs/`
-3. Create `ROADMAP.md` with phase table
-4. `/plan 1` to start phase 1
+3. Optionally write `AGENTS.md` (or `agents.md`) at project root with project conventions
+4. Create `ROADMAP.md` with phase table
+5. `/plan 1` to start phase 1
+
+### Add project-specific agents
+
+Drop a markdown file in `.agents/agents/<name>.md` (project) or `~/.agents/agents/<name>.md` (user):
+
+```markdown
+---
+name: data-scientist
+description: Reads CSVs, runs pandas, plots results
+thinking: medium
+tools: read, bash
+---
+
+You are a data scientist. ...
+```
+
+**Discovered from 4 locations** (priority order):
+1. `<project>/.agents/agents/` — project vendor-neutral (preferred)
+2. `<project>/.pi/agent/agents/` — project pi native (legacy)
+3. `~/.agents/agents/` — user vendor-neutral (preferred)
+4. `~/.pi/agent/agents/` — user pi native (legacy)
+
+`Ctrl+Tab` to see them in the cycle.
 
 ### Add a feature to an existing phase
 
@@ -311,9 +355,9 @@ If `/execute` complains about illegal partial state:
 - ❌ Edit `.soly/rules/` files you didn't write — those are project invariants
 - ❌ Skip the SUMMARY — illegal partial state
 - ❌ Spawn `soly-worker` or `soly-debugger` — use `soly-manager` (mode-switches)
-- ❌ Write rules in code comments — use `.soly/rules/*.md` files
+- ❌ Write rules in code comments — use `.soly/rules/*.md` or `.agents/rules/*.md` files
 - ❌ Edit `.soly/phases/*/PLAN.md` after `status: in_progress` — create a new plan
-- ❌ Put intent docs anywhere other than `.soly/docs/`
+- ❌ Put intent docs anywhere other than `.soly/docs/` (or `.agents/docs/` for vendor-neutral)
 
 ## When in doubt
 

package/switch/core.ts

@@ -65,29 +65,61 @@ export function isValidAgentName(name: string): boolean {
 }
 
 /** 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;
+/** All known agent home directories, in priority order (project wins
+ *  over user-home; user-home `.agents/` wins over pi-native).
+ *  Project-level `.agents/agents/` is a vendor-neutral per-project
+ *  convention — same role as `.soly/` or the old `.claude/`.
+ *  Honors $HOME / $USERPROFILE for testability. */
+export function agentHomeDirs(cwd?: string): string[] {
+	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+	const dirs: string[] = [];
+	if (cwd) {
+		dirs.push(path.join(cwd, ".agents", "agents"));         // project (vendor-neutral, preferred)
+		dirs.push(path.join(cwd, ".pi", "agent", "agents"));    // project (pi native, legacy)
+	}
+	dirs.push(path.join(home, ".agents", "agents"));              // user (vendor-neutral)
+	dirs.push(path.join(home, ".pi", "agent", "agents"));         // user (pi native, legacy)
+	return dirs;
+}
+
+/** Read all agent names from every home dir. Dedupes, first-occurrence
+ *  wins. If cwd is provided, project dirs are scanned first. */
+export function discoverUserAgents(cwd?: string): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const dir of agentHomeDirs(cwd)) {
+		if (!fs.existsSync(dir)) continue;
+		let entries: string[];
 		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 */ }
+			entries = fs.readdirSync(dir);
+		} catch {
+			continue;
+		}
+		for (const file of entries) {
+			if (!file.endsWith(".md")) continue;
+			try {
+				const raw = fs.readFileSync(path.join(dir, 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) && !seen.has(n)) {
+						seen.add(n);
+						out.push(n);
+					}
+				}
+			} catch { /* skip unreadable */ }
+		}
 	}
-	return names;
+	return out;
 }
 
 /** 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[] {
+ *  project-level agents (if cwd given), then user-home agents.
+ *  Dedupes while preserving first-occurrence order. */
+export function availableAgents(cwd?: string): string[] {
 	const out: string[] = [];
 	const seen = new Set<string>();
 	const push = (n: string) => {
@@ -97,7 +129,7 @@ export function availableAgents(userDir?: string): string[] {
 		}
 	};
 	for (const a of BUILTIN_AGENTS) push(a);
-	for (const a of discoverUserAgents(userDir)) push(a);
+	for (const a of discoverUserAgents(cwd)) push(a);
 	return out;
 }
 
@@ -139,8 +171,8 @@ export function formatAgentSwitchNotify(prev: string, next: string): string {
 }
 
 /** Group agents: built-ins + user-defined. */
-export function groupedAvailableAgents(userDir?: string): Array<{ header: string; agents: string[] }> {
-	const all = availableAgents(userDir);
+export function groupedAvailableAgents(cwd?: string): Array<{ header: string; agents: string[] }> {
+	const all = availableAgents(cwd);
 	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 });

package/switch/index.ts

@@ -45,7 +45,7 @@ export default function piSwitchExtension(pi: ExtensionAPI) {
 	let lastUi: ExtensionUIContext | null = null;
 
 	function refreshCycle(): void {
-		cycle = availableAgents();
+		cycle = availableAgents(cwd);
 		if (!cycle.includes(currentAgent)) currentAgent = DEFAULT_AGENT;
 	}
 
@@ -177,8 +177,8 @@ function openPicker(ui: ExtensionUIContext): void {
 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");
+	if (!availableAgents(cwd).includes(target)) {
+		return ui.notify(`pi-switch: unknown "${target}". available: ${availableAgents(cwd).join(", ")}`, "error");
 	}
 	setAgentRef(target);
 }
@@ -231,20 +231,50 @@ function createAgent(
 		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`);
+	// Write to ~/.agents/ (vendor-neutral) first; fall back to ~/.pi/agent/agents/
+	// (pi's native) if .agents/ doesn't exist or is unwritable.
+	const home = os.homedir();
+	const candidates = [
+		path.join(home, ".agents"),
+		path.join(home, ".pi", "agent", "agents"),
+	];
+	const targetDir = candidates.find((d) => {
+		try {
+			if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+			// Probe write permission
+			const probe = path.join(d, ".pi-switch-write-probe");
+			fs.writeFileSync(probe, "");
+			fs.unlinkSync(probe);
+			return true;
+		} catch {
+			return false;
+		}
+	});
+	if (!targetDir) {
+		ui.notify(`pi-switch: could not find a writable agents dir (tried ${candidates.join(", ")}).`, "error");
+		return;
+	}
+	const file = path.join(targetDir, `${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+Tab to see it in the cycle\n  → edit the system prompt to specialize`,
-			"info",
-		);
+		try {
+			// Atomic write: tmp + rename. Avoids partial files and the
+			// race where two parallel createAgent calls would clobber each
+			// other's write after both pass the existsSync check.
+			const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+			fs.writeFileSync(tmp, agentTemplate(name, description), "utf-8");
+			fs.renameSync(tmp, file);
+			ui.notify(
+				`pi-switch: created ${file}\n  → next Ctrl+Tab to see it in the cycle\n  → edit the system prompt to specialize`,
+				"info",
+			);
+		} catch (err) {
+			ui.notify(`pi-switch: failed to write ${file}: ${(err as Error).message}`, "error");
+		}
 	});
 }
 
@@ -284,7 +314,7 @@ you have a specific reason to change it.
 }
 
 function doctorReport(): string {
-	const cycle = availableAgents();
+	const cycle = availableAgents(cwd);
 	const userDir = path.join(os.homedir(), ".pi", "agent", "agents");
 	const lines: string[] = ["pi-switch doctor:", ""];
 	const builtins = cycle.filter((a) => BUILTIN_AGENTS.includes(a));

package/switch/tests/core.test.ts

@@ -123,13 +123,35 @@ describe("groupedAvailableAgents", () => {
 		expect(groups[0]?.header).toBe("built-in");
 	});
 	test("includes user group when present", () => {
-		const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "pis-grp-"));
-		fs.writeFileSync(path.join(tmp, "my.md"), "---\nname: my-helper\n---\n# body\n");
-		const groups = groupedAvailableAgents(tmp);
+		// Use HOME override so the new ~.agents/agents/ scan picks up our fixture
+		const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+		const prevHome = process.env.HOME;
+		const prevUserProfile = process.env.USERPROFILE;
+		const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "pis-home-"));
+		process.env.HOME = tmp;
+		process.env.USERPROFILE = tmp;
+		const agentsDir = path.join(tmp, ".agents", "agents");
+		fs.mkdirSync(agentsDir, { recursive: true });
+		fs.writeFileSync(path.join(agentsDir, "my.md"), "---\nname: my-helper\n---\n# body\n");
+		const groups = groupedAvailableAgents();
 		const userGroup = groups.find((g) => g.header === "user-defined");
 		expect(userGroup?.agents).toContain("my-helper");
+		// restore
+		process.env.HOME = prevHome ?? home;
+		process.env.USERPROFILE = prevUserProfile ?? home;
 		fs.rmSync(tmp, { recursive: true, force: true });
 	});
+
+	test("includes project agent when present (cwd scope)", () => {
+		const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "pis-proj-"));
+		const agentsDir = path.join(projectDir, ".agents", "agents");
+		fs.mkdirSync(agentsDir, { recursive: true });
+		fs.writeFileSync(path.join(agentsDir, "proj.md"), "---\nname: project-helper\n---\n# body\n");
+		const groups = groupedAvailableAgents(projectDir);
+		const userGroup = groups.find((g) => g.header === "user-defined");
+		expect(userGroup?.agents).toContain("project-helper");
+		fs.rmSync(projectDir, { recursive: true, force: true });
+	});
 });
 
 // ---------------------------------------------------------------------------

package/workflows/execute.ts

@@ -309,18 +309,21 @@ When the subagent completes, synthesize the result. Do not re-execute its work.`
 		planNumber: isPlanLevel ? (target.plan ?? undefined) : undefined,
 	});
 
-	// For plan-level: also pull out the must_haves summary for inline cache.
-	const planFile = isPlanLevel
-		? path.join(phase.dir, `${phase.slug}-${String(target.plan).padStart(2, "0")}-${phase.slug.split("-").slice(1).join("-") || "plan"}-PLAN.md`)
-		: null;
-	// Fall back to findPlanFile if the conventional name didn't match.
-	let planFileResolved = planFile;
-	if (isPlanLevel && planFile && !fs.existsSync(planFile)) {
+	// For plan-level: find the PLAN.md. We always use the directory scan
+	// (the conventional name would require knowing the slug suffix, which
+	// is fragile and changed over time). Pattern: NN-MM-slug-PLAN.md.
+	let planFileResolved: string | null = null;
+	if (isPlanLevel && phase.dir) {
 		const padded = String(target.plan).padStart(2, "0");
-		const candidates = fs.readdirSync(phase.dir).filter((f) =>
-			new RegExp(`^\\d+-${padded}-.+-PLAN\\.md$`).test(f),
-		);
-		if (candidates.length > 0) planFileResolved = path.join(phase.dir, candidates[0]!);
+		let entries: string[];
+		try {
+			entries = fs.readdirSync(phase.dir);
+		} catch {
+			entries = [];
+		}
+		const re = new RegExp(`^\\d{2,}-${padded}-.+-PLAN\\.md$`);
+		const match = entries.find((f) => re.test(f));
+		if (match) planFileResolved = path.join(phase.dir, match);
 	}
 	const inlineSummary = isPlanLevel ? inlinePlanSummary(planFileResolved) : "_(phase-level exec — iterate all PLAN.md files; each iteration has its own bundle)_";
 

package/workflows/inspect.ts

@@ -124,13 +124,22 @@ export function showDoctor(_cmd: unknown, state: SolyState, ui: InspectUI, confi
 		if (fs.existsSync(phasesDir)) {
 			let totalPlans = 0;
 			let badPlans = 0;
+			// Tight match: "NN-something-PLAN.md" — phase number prefix, then
+			// slug, then -PLAN.md. Avoids matching "old-PLAN-PLAN.md" or
+			// "PLAN.md" without a phase prefix.
+			const planRe = /^\d{2,}-.+-PLAN\.md$/;
 			for (const p of fs.readdirSync(phasesDir, { withFileTypes: true })) {
 				if (!p.isDirectory() || p.name.startsWith(".")) continue;
 				for (const f of fs.readdirSync(path.join(phasesDir, p.name))) {
-					if (/-PLAN\.md$/.test(f)) {
+					if (planRe.test(f)) {
 						totalPlans++;
-						const raw = fs.readFileSync(path.join(phasesDir, p.name, f), "utf-8");
-						if (!raw.startsWith("---\n") && !raw.startsWith("---\r\n")) badPlans++;
+						try {
+							const raw = fs.readFileSync(path.join(phasesDir, p.name, f), "utf-8");
+							if (!raw.startsWith("---\n") && !raw.startsWith("---\r\n")) badPlans++;
+						} catch {
+							// Unreadable plan: count as bad so user notices
+							badPlans++;
+						}
 					}
 				}
 			}

package/workflows/planning.ts

@@ -284,6 +284,15 @@ When the subagent returns, summarize what was refined. Do not execute — planni
 			const featureReadme = path.join(featureDir, "README.md");
 			try {
 				fs.mkdirSync(path.join(featureDir, "tasks"), { recursive: true });
+			} catch (e) {
+				return {
+					handled: true,
+					transformedText:
+						`soly plan: could not create .soly/features/${target.feature}/tasks/ (${(e as Error).message}). ` +
+						`Create it manually: \`mkdir -p .soly/features/${target.feature}/tasks/\``,
+				};
+			}
+			try {
 				if (!fs.existsSync(featureReadme)) {
 					fs.writeFileSync(
 						featureReadme,
@@ -295,8 +304,8 @@ When the subagent returns, summarize what was refined. Do not execute — planni
 				return {
 					handled: true,
 					transformedText:
-						`soly plan: could not auto-create .soly/features/${target.feature}/ (${(e as Error).message}). ` +
-						`Create it manually: \`mkdir -p .soly/features/${target.feature}/tasks/\``,
+						`soly plan: created .soly/features/${target.feature}/tasks/ but failed to write README.md (${(e as Error).message}). ` +
+						`Continue manually: \`touch .soly/features/${target.feature}/README.md\``,
 				};
 			}
 			// Re-read state so the planner sees the new feature