pi-soly 0.6.0 → 0.7.0

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,34 +27,73 @@ 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). */
+/** 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 userAgentsDir(): string {
 	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
 	return path.join(home, ".pi", "agent", "agents");
 }
 
+/** 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", "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[];
 }
 
+/** 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 `~/.pi/agent/agents/`. Idempotent. */
 export function installSolyAgents(extensionRoot: string): InstallResult {
 	const result: InstallResult = { installed: [], skipped: [], errors: [] };
-	const src = shippedDir(extensionRoot);
+	const src = shippedAgentsDir(extensionRoot);
 	const dst = userAgentsDir();
 
-	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 });
@@ -62,26 +105,46 @@ export function installSolyAgents(extensionRoot: string): InstallResult {
 	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;
 }
 
+/** 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 in the user dir. Used by doctor. */
 export function checkSolyAgentsInstalled(extensionRoot: string): {
 	installed: string[];
@@ -99,3 +162,21 @@ export function checkSolyAgentsInstalled(extensionRoot: string): {
 	}
 	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);
+		}
+	}
+	return { installed, missing };
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "0.6.0",
+  "version": "0.7.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,320 @@
+---
+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>/
+├── .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. Create `ROADMAP.md` with phase table
+4. `/plan 1` to start phase 1
+
+### 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.