pi-soly 0.6.0 → 0.8.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

@@ -1,14 +1,18 @@
 // =============================================================================
-// agents-install.ts — Idempotent install of soly-aware subagent configs
+// assets-install.ts — Idempotent install of soly-managed user assets
 // =============================================================================
 //
-// Soly ships ONE subagent: `soly-manager`. It's a workflow executor that
-// switches modes (worker / debugger / tester / reviewer / refactor /
-// documenter / oracle / planner) based on the task brief the parent passes.
-// One agent, one system prompt, all roles.
+// Soly ships two kinds of user-scope assets:
 //
-// pi-subagents discovers agents from `~/.pi/agent/agents/`, so on first
-// session_start we copy our `soly-manager.md` there.
+//   1. Subagent configs → `~/.pi/agent/agents/`
+//      The single `soly-manager` subagent (mode-switching executor).
+//
+//   2. Skills → `~/.pi/agent/skills/<name>/`
+//      The `soly-framework` skill — framework documentation the LLM
+//      loads on demand via the read tool.
+//
+// pi discovers both from `~/.pi/agent/`, so on first session_start we
+// copy our shipped files there.
 //
 // IDEMPOTENT: if the target file already exists (user may have customized
 // it), we do NOT overwrite. This is one-way "first install wins".
@@ -23,75 +27,160 @@ const SHIPPED_AGENTS = [
 	"soly-manager.md",
 ] as const;
 
-/** Where pi-subagents looks for user agents. Respects HOME/USERPROFILE
- *  for testability (otherwise we'd always write to the real user home). */
-function userAgentsDir(): string {
+/** soly skills bundled with the extension. Each entry is a directory
+ *  under `skills/` containing a SKILL.md. */
+const SHIPPED_SKILLS = [
+	"soly-framework",
+] as const;
+
+/** Where pi looks for user agents. Respects HOME/USERPROFILE for
+ *  testability (otherwise we'd always write to the real user home). */
+function userAgentsDirs(): string[] {
+	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+	return [
+		path.join(home, ".agents"),                          // vendor-neutral (preferred)
+		path.join(home, ".pi", "agent", "agents"),           // pi's native
+	];
+}
+
+/** Where pi looks for user skills. */
+function userSkillsDir(): string {
 	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
-	return path.join(home, ".pi", "agent", "agents");
+	return path.join(home, ".pi", "agent", "skills");
 }
 
 /** Where this soly extension's `agents/` directory lives. */
-function shippedDir(extensionRoot: string): string {
+function shippedAgentsDir(extensionRoot: string): string {
 	return path.join(extensionRoot, "agents");
 }
 
+/** Where this soly extension's `skills/` directory lives. */
+function shippedSkillsDir(extensionRoot: string): string {
+	return path.join(extensionRoot, "skills");
+}
+
 export interface InstallResult {
 	installed: string[];
 	skipped: string[];
 	errors: string[];
 }
 
-/** Install shipped soly agents to `~/.pi/agent/agents/`. Idempotent. */
+/** Copy a single file if destination doesn't exist. Idempotent. */
+function copyIfMissing(from: string, to: string): "installed" | "skipped" | "error" {
+	if (!fs.existsSync(from)) return "error";
+	if (fs.existsSync(to)) return "skipped";
+	try {
+		fs.copyFileSync(from, to);
+		return "installed";
+	} catch {
+		return "error";
+	}
+}
+
+/** Recursively copy a directory tree if destination doesn't exist. Idempotent. */
+function copyDirIfMissing(from: string, to: string): "installed" | "skipped" | "error" {
+	if (!fs.existsSync(from)) return "error";
+	if (fs.existsSync(to)) return "skipped";
+	try {
+		fs.mkdirSync(path.dirname(to), { recursive: true });
+		fs.cpSync(from, to, { recursive: true });
+		return "installed";
+	} catch {
+		return "error";
+	}
+}
+
+/** 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 = shippedDir(extensionRoot);
-	const dst = userAgentsDir();
+	const src = shippedAgentsDir(extensionRoot);
 
-	if (!fs.existsSync(src)) {
-		// Development mode or partial install — silently no-op
-		return result;
-	}
+	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);
 		const to = path.join(dst, name);
-		if (!fs.existsSync(from)) {
-			result.errors.push(`missing source: ${from}`);
-			continue;
-		}
-		if (fs.existsSync(to)) {
-			// User already has this file (possibly customized) — respect it
-			result.skipped.push(name);
-			continue;
-		}
-		try {
-			fs.copyFileSync(from, to);
-			result.installed.push(name);
-		} catch (err) {
-			result.errors.push(`copy ${name}: ${(err as Error).message}`);
-		}
+		const r = copyIfMissing(from, to);
+		if (r === "installed") result.installed.push(name);
+		else if (r === "skipped") result.skipped.push(name);
+		else result.errors.push(`missing source: ${from}`);
+	}
+
+	return result;
+}
+
+/** Install shipped soly skills to `~/.pi/agent/skills/`. Idempotent. */
+export function installSolySkills(extensionRoot: string): InstallResult {
+	const result: InstallResult = { installed: [], skipped: [], errors: [] };
+	const src = shippedSkillsDir(extensionRoot);
+	const dst = userSkillsDir();
+
+	if (!fs.existsSync(src)) return result; // dev mode no-op
+
+	for (const name of SHIPPED_SKILLS) {
+		const from = path.join(src, name);
+		const to = path.join(dst, name);
+		const r = copyDirIfMissing(from, to);
+		if (r === "installed") result.installed.push(name);
+		else if (r === "skipped") result.skipped.push(name);
+		else result.errors.push(`missing source: ${from}`);
 	}
 
 	return result;
 }
 
-/** Check which shipped soly agents are present in the user dir. Used by doctor. */
+/** Install all soly assets (agents + skills). Combined for convenience. */
+export function installSolyAssets(extensionRoot: string): {
+	agents: InstallResult;
+	skills: InstallResult;
+} {
+	return {
+		agents: installSolyAgents(extensionRoot),
+		skills: installSolySkills(extensionRoot),
+	};
+}
+
+/** 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))) {
+		const present = userAgentsDirs().some((dir) => fs.existsSync(path.join(dir, name)));
+		if (present) installed.push(name);
+		else missing.push(name);
+	}
+	return { installed, missing };
+}
+
+/** Check which shipped soly skills are present in the user dir. */
+export function checkSolySkillsInstalled(extensionRoot: string): {
+	installed: string[];
+	missing: string[];
+} {
+	const dst = userSkillsDir();
+	const installed: string[] = [];
+	const missing: string[] = [];
+	for (const name of SHIPPED_SKILLS) {
+		if (fs.existsSync(path.join(dst, name, "SKILL.md"))) {
 			installed.push(name);
 		} else {
 			missing.push(name);

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

@@ -45,7 +45,7 @@ import {
 	type SourceSpec,
 } from "./core.ts";
 import { buildIntegrationsSection } from "./integrations.ts";
-import { installSolyAgents } from "./agents-install.ts";
+import { installSolyAssets } from "./agents-install.ts";
 import {
 	DEFAULT_CONFIG,
 	loadConfig,
@@ -388,21 +388,22 @@ export default function solyExtension(pi: ExtensionAPI) {
 			}
 		}
 
-		// Auto-install soly-manager subagent config to ~/.pi/agent/agents/
-		// on first run. Opt-in via config `agent.useSolyWorkerSubagents`
-		// (default false). Idempotent — respects any existing user-
-		// customized copies.
+		// Auto-install soly user-scope assets (soly-manager agent + soly-framework
+		// skill) to ~/.pi/agent/ on first run. Opt-in via config
+		// `agent.useSolyWorkerSubagents` (default false). Idempotent — respects
+		// any existing user-customized copies.
 		if (activeConfig.agent.useSolyWorkerSubagents) {
 			const extRoot = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1"));
-			const installResult = installSolyAgents(extRoot);
-			if (installResult.installed.length > 0) {
+			const assets = installSolyAssets(extRoot);
+			const installed = [...assets.agents.installed, ...assets.skills.installed.map((s) => `skill:${s}`)];
+			if (installed.length > 0) {
 				ctx.ui.notify(
-					`soly: installed subagent config (${installResult.installed.join(", ")}) — run \`/subagents-doctor\` to verify`,
+					`soly: installed (${installed.join(", ")}) — run \`/subagents-doctor\` to verify`,
 					"info",
 				);
 			}
-			for (const e of installResult.errors) {
-				ctx.ui.notify(`soly: agent install error — ${e}`, "warning");
+			for (const e of [...assets.agents.errors, ...assets.skills.errors]) {
+				ctx.ui.notify(`soly: install error — ${e}`, "warning");
 			}
 		}
 

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.6.0",
+  "version": "0.8.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",
@@ -40,6 +40,7 @@
     "agents-install.ts",
     "agents",
     "ask",
+    "skills",
     "switch",
     "workflows",
     "workflows-data"

package/skills/soly-framework/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: soly-framework
+description: Use when the user asks how to do anything with the soly framework for pi — start a new project, plan or execute a phase, pause and resume sessions, add rules, add intent docs, write PLAN.md or SUMMARY.md, troubleshoot issues. Triggers on "how do I", "what's the command for", "soly help", "soly framework", and any practical question about using the soly extension. NOT loaded for generic code questions — only when the user is working with the soly workflow.
+---
+
+# soly framework
+
+The **soly** extension adds project-management workflow to [pi-coding-agent](https://github.com/nicobailon/pi-coding-agent): intent docs, ROADMAP/STATE/PHASE state machine, and subagent-driven plan execution. This skill is your complete reference for using it.
+
+## Quick start (read first if new)
+
+**Mental model — three layers, always in system prompt, in this order:**
+
+1. **Project intent** (`.soly/docs/`) — the 0-point. What the user wants the app to be. Written BEFORE plans, by humans.
+2. **Project state** (`.soly/STATE.md`, `ROADMAP.md`) — where we are, current phase, recent decisions.
+3. **Project rules** (`.soly/rules/`, `~/.soly/rules/`) — how to behave in this project.
+
+**Workflow model — phases and plans:**
+
+- A **phase** is a milestone (e.g. "01-foundation"). Has one or more `PLAN.md` files.
+- A **plan** is one ordered execution unit. Has `<task>` blocks.
+- A **task** is the smallest unit. Has type, description, verify, accept.
+- **Close-out**: production code commits → `SUMMARY.md` → `STATE.md` updated → ROADMAP check.
+
+## Slash commands (interactive mode)
+
+| Command | What it does |
+|---|---|
+| `/plan [N]` | Generate or update `PLAN.md` for phase N (or current phase) |
+| `/execute [N[.MM]]` | Dispatch plan(s) to `soly-manager` subagent. `N` = all plans in phase. `N.MM` = specific plan. |
+| `/discuss N` | Discussion-driven scoping for phase N — capture decisions before planning |
+| `/inspect` | One-screen summary: position, phases, recent decisions |
+| `/pause` | Save handoff (`HANDOFF.json` + `.continue-here.md`) for later resume |
+| `/resume` | Restore from a paused handoff |
+| `/quick <task>` | One-shot task that doesn't need a full plan — direct dispatch |
+| `/soly` | Project state inspection (alias for `/inspect`) |
+| `/why` | Show what context the LLM's last turn was based on |
+| `/agent [name]` | Switch the current cycle agent (or open picker) |
+
+`/soly <verb>` plain-text aliases also work for some verbs (legacy compat).
+
+## File structure
+
+```
+<project-root>/
+├── AGENTS.md                      # vendor-neutral agent context (loaded by pi)
+├── agents.md                      # same as AGENTS.md, lowercase accepted
+├── .agents/                       # project-level agent definitions
+│   ├── project-reviewer.md
+│   └── data-scientist.md
+├── .soly/
+│   ├── 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)
+│   │   ├── code-style.md
+│   │   └── testing.md
+│   ├── phases/
+│   │   ├── 01-foundation/
+│   │   │   ├── 01-CONTEXT.md     # domain + decisions for phase 1
+│   │   │   ├── 01-RESEARCH.md    # what we looked up
+│   │   │   ├── 01-PLAN-01.md     # plan 1
+│   │   │   ├── 01-PLAN-01-SUMMARY.md
+│   │   │   ├── 01-PLAN-02.md
+│   │   │   └── 01-PLAN-02-SUMMARY.md
+│   │   └── 02-feature-x/
+│   │       └── ...
+│   ├── iterations/                # per-execution context bundles (auto)
+│   ├── HANDOFF.json               # pause snapshot
+│   └── .continue-here.md          # pause resume marker
+```
+
+## Frontmatter conventions
+
+### PLAN.md frontmatter (required)
+
+```markdown
+---
+id: 01-02                    # phase-plan, zero-padded
+title: Add OAuth flow
+status: pending              # pending | in_progress | done
+phase: 1
+depends-on: []               # other plan ids
+parallelizable: true         # can run alongside siblings
+---
+
+# Add OAuth flow
+
+## read_first
+- .soly/STATE.md
+- .soly/ROADMAP.md
+- .soly/rules/code-style.md
+
+## tasks
+- [ ] **type: implement**, description: Add token refresh logic
+  - files: src/auth/refresh.ts
+  - verify: bun test src/auth/refresh.test.ts
+  - accept: Refresh succeeds when token is expired; fails when refresh_token is also expired
+
+- [ ] **type: tdd**, description: Write integration test for the auth flow
+  - verify: bun test src/auth/
+
+- [ ] **type: checkpoint**, description: Pause for human review of UX
+
+## verification
+- bun test
+- bun run typecheck
+- bun run lint
+
+## risks
+- Token storage depends on the encryption scheme (see .soly/docs/architecture.md)
+```
+
+### SUMMARY.md frontmatter
+
+```markdown
+---
+plan: 01-02
+completed: 2026-06-15
+duration: 47min
+files-touched: 7
+---
+
+# Summary
+
+## Tasks
+- [x] Add token refresh logic
+- [x] Write integration test
+- [x] Pause for human review
+
+## Deviations
+- Refactored `auth/refresh.ts` to use singleton pattern (was factory). Documented in `architecture.md`.
+
+## Verification
+- `bun test`: 142 passing
+- `bun run typecheck`: clean
+- `bun run lint`: 0 warnings
+
+## Next
+- Phase 02 plan 01: User profile page
+```
+
+### Rules file frontmatter (optional)
+
+```markdown
+---
+applyTo: "src/**/*.ts"        # glob (optional, default: all)
+priority: 50                   # higher wins on conflict (default: 0)
+---
+
+# TypeScript style
+
+- Strict mode required
+- Never use `any` — use `unknown` and narrow
+```
+
+## Path discipline (NON-NEGOTIABLE)
+
+**All soly-managed files live under `.soly/`.** Source code lives in the project's normal source tree.
+
+| File kind | Goes to |
+|---|---|
+| `PLAN.md`, `SUMMARY.md`, `CONTEXT.md`, `RESEARCH.md` | `.soly/phases/<NN>-<slug>/` |
+| Intent docs (0-point) | `.soly/docs/` |
+| Rules | `.soly/rules/` (project) or `~/.soly/rules/` (user) |
+| Handoff | `.soly/HANDOFF.json`, `.soly/.continue-here.md` |
+| Iteration context | `.soly/iterations/` (auto-generated) |
+| Production code, tests | project's normal `src/`, `tests/`, `app/`, etc. |
+
+Use absolute paths (or paths starting with `$SOLY_DIR`) when calling tools. Never bare relative names that could land in cwd.
+
+## Close-out order
+
+The only legal sequence for finishing a plan:
+
+1. Production code commits (1+)
+2. `SUMMARY.md` committed
+3. `STATE.md` "Current Position" block updated
+4. `ROADMAP.md` phase checkbox updated
+5. `PLAN.md` frontmatter `status: done`
+
+Once production commits exist, returning without a committed `SUMMARY.md` is an **illegal partial-plan state** — the next `/execute` will detect it and refuse to start.
+
+## Cycle agents (4 built-in)
+
+| Agent | Writes | Use for |
+|---|---|---|
+| `worker` | ✅ | Generic implementation, full tools |
+| `oracle` | ❌ | Decision-consistency, no file edits |
+| `scout` | ❌ | Codebase recon, read-only |
+| `reviewer` | ❌ | Adversarial code review |
+
+Switch with `/agent <name>` or `Ctrl+Tab` (cycles through). Footer pill shows current: `· ⚡ worker` / `▶ 🐢 oracle`.
+
+## Subagent: soly-manager (single, mode-switching)
+
+Spawn via `subagent({ agent: "soly-manager", task: ... })`. The task brief tells it which mode to be in:
+
+| Task brief mentions | Mode |
+|---|---|
+| implement, build, write code, add feature, create | **worker** |
+| debug, bug, fix, crash, error, repro, broken | **debugger** |
+| test, coverage, spec, assert, only modify tests | **tester** |
+| review, audit, adversarial, find bugs, qa | **reviewer** |
+| refactor, simplify, extract, rename, no behavior change | **refactor** |
+| document, readme, jsdoc, comment, intent doc | **documenter** |
+| validate, scope, drift, decision, before committing | **oracle** |
+| plan, design, outline, structure, decompose | **planner** |
+
+**soly-manager is ONE agent that switches modes. Don't spawn soly-worker / soly-debugger / etc. — those don't exist anymore.**
+
+## Tools the LLM can call
+
+| Tool | Purpose |
+|---|---|
+| `soly_read(artifact, phase, taskId)` | Read soly artifacts: STATE, plan, context, research, ROADMAP, requirements, project, milestone, task |
+| `soly_log_decision(decision, rationale, phase)` | Append to STATE.md Decisions table |
+| `soly_list_phases()` | List all phases with plan counts, C/R markers |
+| `soly_list_tasks()` | List all tasks across features (kind, status, priority, deps) |
+| `soly_todos(paths, limit)` | Scan working tree for TODO/FIXME/HACK/XXX/NOTE |
+| `soly_env()` | Detect runtime (package manager, runtimes, services, scripts) |
+| `soly_snippet(path, offset, limit)` | Read bounded line range with line numbers |
+| `soly_doc_search(query, limit)` | Search .md/.html under cwd (prioritizes intent docs) |
+| `soly_intent()` | List 0-point intent docs from `.soly/docs/` |
+| `soly_scratchpad(limit)` | Recent conversation recap (one line per turn) |
+| `ask_pro(questions)` | Multi-question picker (tabbed, single/multi-select, ⭐, Other…) |
+| `todo_update(todos)` | Update task list rendered in footer |
+
+## Add a new rule (most common task)
+
+Three places, in priority order:
+
+1. **Project rule** — `~/.pi/agent/agents/soly/rules/<name>.md` (version-controlled, shared with team)
+2. **User rule** — `~/.soly/rules/<name>.md` (per-user, not committed)
+3. **Phase rule** — `<phase-dir>/<plan>.md.rules/<name>.md` (active only for that plan)
+
+Use `/rulewizard` slash command to scaffold a new rule with the right frontmatter.
+
+A rule file looks like:
+
+```markdown
+---
+applyTo: "src/**/*.ts"
+priority: 50
+---
+
+# TypeScript style
+
+- Strict mode required
+- Never use `any`
+- Prefer `type` over `interface`
+```
+
+## Add a new intent doc
+
+Create a file in `.soly/docs/`:
+
+```markdown
+# Architecture
+
+## Goal
+
+Build a CLI tool that...
+
+## Non-obvious constraints
+
+- Must work offline (no network calls)
+- Must be a single static binary
+- Must integrate with the existing `~/.config/x` schema
+```
+
+Intent docs are 0-point — written BEFORE any plan, by humans. They define the "why", not the "how".
+
+## Common workflows
+
+### Start a new project
+
+1. `soly init` (or manually create `.soly/`, `docs/`, `rules/`)
+2. Write 1-3 intent docs in `.soly/docs/`
+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/<name>.md` (project) or `~/.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. ...
+```
+
+Both `~/.agents/` and `~/.pi/agent/agents/` are read (vendor-neutral preferred). `Ctrl+Tab` to see them in the cycle.
+
+### Add a feature to an existing phase
+
+1. `/plan 1.05` (next plan number)
+2. Edit the generated `PLAN.md`
+3. `/execute 1.05`
+
+### Pause a long session
+
+1. `/pause` → writes `HANDOFF.json` + `.continue-here.md`
+2. Later, in a new session: `/resume`
+
+### Troubleshoot a partial plan
+
+If `/execute` complains about illegal partial state:
+
+1. `cat .soly/iterations/<latest>.md` — see what the last run did
+2. Check if `SUMMARY.md` exists for the last plan
+3. If yes, finish close-out: update `STATE.md` + `ROADMAP.md`
+4. If no, either commit the SUMMARY or revert the production commits
+
+## Where to look for answers
+
+- **"What command does X"** → this skill, Slash commands section
+- **"What does PLAN.md look like"** → this skill, Frontmatter section
+- **"How to add a rule"** → this skill, Add a new rule section
+- **"Why did the LLM do Y"** → `/why`
+- **"What context is loaded"** → `soly_read(artifact: "state")` + `soly_doc_search(...)`
+- **"What was the recent conversation"** → `soly_scratchpad()`
+
+## Don'ts
+
+- ❌ 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
+- ❌ Edit `.soly/phases/*/PLAN.md` after `status: in_progress` — create a new plan
+- ❌ Put intent docs anywhere other than `.soly/docs/`
+
+## When in doubt
+
+Call `soly_read(artifact: "state")` and `soly_read(artifact: "roadmap")` first. The system prompt has the layers, but `soly_read` gives you full content. Then check `soly_doc_search` for any other relevant docs.

package/switch/core.ts

@@ -65,29 +65,55 @@ 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;
+/** User agent home directories, in priority order. First existing one
+ *  wins for new agent creation; all are read and merged in the cycle.
+ *  Honors $HOME / $USERPROFILE so tests can redirect to a tmp dir. */
+export function userAgentDirs(): string[] {
+	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+	return [
+		path.join(home, ".agents"),                          // vendor-neutral (preferred)
+		path.join(home, ".pi", "agent", "agents"),           // pi's native
+	];
+}
+
+/** Read all user agent names from every registered home dir. Dedupes,
+ *  first-occurrence wins. */
+export function discoverUserAgents(): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const dir of userAgentDirs()) {
+		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[] {
+ *  user-discovered (from all user agent home dirs). Dedupes while
+ *  preserving first-occurrence order. */
+export function availableAgents(): string[] {
 	const out: string[] = [];
 	const seen = new Set<string>();
 	const push = (n: string) => {
@@ -97,7 +123,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()) push(a);
 	return out;
 }
 
@@ -139,8 +165,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(): Array<{ header: string; agents: string[] }> {
+	const all = availableAgents();
 	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

@@ -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");
+		}
 	});
 }
 

package/switch/tests/core.test.ts

@@ -123,11 +123,22 @@ 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/ 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");
+		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 });
 	});
 });

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