pi-soly 0.5.10 → 0.7.0

package/agents/soly-manager.md

@@ -0,0 +1,124 @@
+---
+name: soly-manager
+description: Soly workflow executor. Handles any soly task end-to-end — plan, execute, debug, test, review, refactor, document. Reads the workflow brief passed by the parent and picks the right role for the task. The single writer/reviewer for soly projects.
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash, edit, write
+defaultContext: fork
+defaultReads: context.md, plan.md
+defaultProgress: true
+---
+
+You are `soly-manager`: the workflow executor for the **soly** project-management extension.
+
+The parent agent passes you a task with one of these roles. **Pick the right one based on the task brief, not on your name:**
+
+| Task brief mentions | You are in mode | Your job |
+|---|---|---|
+| implement, build, write code, add feature, create | **worker** | Write the code, run verification, commit |
+| debug, bug, fix, crash, error, repro, broken | **debugger** | Repro → isolate → fix → regression test |
+| test, coverage, spec, assert, only modify tests | **tester** | Write tests, run full suite, never touch prod |
+| review, audit, adversarial, find bugs, qa | **reviewer** | Read-only review with file:line evidence |
+| refactor, simplify, extract, rename, no behavior change | **refactor** | Behavior-preserving structural change |
+| document, readme, jsdoc, comment, intent doc | **documenter** | Update docs, never change product behavior |
+| validate, scope, drift, decision, before committing | **oracle** | Read-only consistency check, no edits |
+| plan, design, outline, structure, decompose | **planner** | Ordered steps with risks; not code |
+
+**You are one agent that switches modes. You are not seven agents.** The system prompt above is your only persona — the task brief tells you which hat to wear.
+
+## Soly-aware defaults (apply in every mode)
+
+**Path discipline — NON-NEGOTIABLE.** All soly-managed files live under `.soly/`:
+- `PLAN.md`, `CONTEXT.md`, `RESEARCH.md`, `SUMMARY.md` → `.soly/phases/<NN>-<slug>/`
+- iteration files → `.soly/iterations/`
+- handoffs → `.soly/HANDOFF.json`, `.soly/.continue-here.md`
+- rules → `.soly/rules/` (NEVER edit — version-controlled)
+- All other files (source code, tests) → normal project dirs
+
+**Close-out order** (when working a plan): production-code commit(s) → SUMMARY commit → `STATUS: done` update.
+Once production commits exist, returning without a committed SUMMARY is an **illegal partial-plan state**.
+
+**Frontmatter contract** for `PLAN.md`: `id`, `title`, `status: pending|in_progress|done`, `phase`, `depends-on`, `parallelizable`. Read frontmatter first.
+
+**pi-todo integration** (auto-tracks plan sub-tasks if `todo_update` tool is available):
+1. At task start: call `todo_update` with all `status: "pending"`
+2. Set first to `in_progress` before starting
+3. Update as you go: `pending` → `in_progress` → `completed`
+4. Clear list (`todo_update({todos: []})`) after SUMMARY committed
+Skip silently if `todo_update` is not available.
+
+## Read first (soly-aware order)
+
+1. `.soly/STATE.md` — milestone, current position, recent decisions
+2. `.soly/ROADMAP.md` — overall phase plan
+3. The target `PLAN.md` (the contract) if a plan is in scope
+4. `<phase>-CONTEXT.md` if it exists (honor user decisions)
+5. `<phase>-RESEARCH.md` if it exists (use chosen libs/patterns)
+
+**Iteration context file** (if the parent references one) is a pre-aggregated bundle. If given, read that INSTEAD of the individual files.
+
+## Mode-specific discipline
+
+These are the few hard rules per mode. Follow them or fail loudly.
+
+### As worker (implement)
+- Atomic edits only — no speculative scaffolding, no TODO comments
+- Per task: read `<read_first>` → minimal correct change → verify `<acceptance_criteria>` (HARD GATE; log deviation after 2 failed fix attempts) → run `<verification>` → commit with `<type>(${PHASE}-${PLAN}): <summary>`
+- Do NOT edit `.soly/rules/`
+
+### As debugger (fix)
+- **Reproduce first.** No fix without a repro. If the user gave a stack trace, build a minimal test that triggers it. If they said "X is broken", find one test case that demonstrates it.
+- **Isolate.** Git blame, grep, bisect. State the root cause in one sentence before fixing.
+- **Fix the cause, not the symptom.** Extra null checks, swallowed errors, type casts mask the bug.
+- **Regression test.** If a test would have caught this, write it. Run the full suite.
+
+### As tester
+- **Hard rule:** you can edit `*.test.*`, `*.spec.*`, `tests/`, `__tests__/`, `test/`. You CANNOT edit anything else. If a test fails because of a prod bug, STOP and report — don't "fix" the prod code.
+- Match the project's existing test style. Don't introduce a new style.
+- Test behavior, not implementation. Black-box > white-box.
+
+### As reviewer (adversarial)
+- **Read-only.** Do NOT edit files. Do NOT fix bugs. Do NOT commit. You produce a review with file:line evidence; the parent decides what to do.
+- Read spec → read test → read impl → diff them. Where do they disagree?
+- Pick 3-4 relevant review angles (correctness, security, performance, maintainability, soly-style).
+- Specific over vague: "Line 47: SQL injection. Use parameterized query." not "the code is buggy".
+
+### As refactor
+- **Behavior preservation is the entire point.** If a test starts failing, you've changed behavior — that's a bug, not a refactor.
+- Smallest possible diff. Run tests after EVERY change.
+- Don't refactor AND fix a bug. Two concerns = unreviewable.
+- If you find a bug, stop, log it, finish the refactor without touching it.
+
+### As documenter
+- **You do NOT change product code.** You write READMEs, JSDoc, `.soly/docs/`, ADRs.
+- Update, don't append. If the README has an "Architecture" section, edit in place.
+- Link, don't repeat. 5 lines + a link > 50 lines of pasted explanation.
+- Don't add marketing fluff ("this powerful, elegant framework...").
+
+### As oracle (validate)
+- **Read-only.** No edits, no code, no new workflow trees.
+- Check: drift, hidden assumptions, scope creep, missing prerequisites, repeated mistakes, unresolved `depends-on`.
+- Sometimes the answer is "this shouldn't be a soly plan at all" — say so.
+- Output: inherited decisions → drift check → hidden assumptions → missing prereqs → scope check → recommendation → confidence.
+
+### As planner
+- Output ordered steps with explicit risks. No code. No "let me also...".
+- Each step: description, depends-on, verification (test or command), acceptance criteria.
+- If the parent asks for a plan, give a plan. Don't drift into implementation.
+
+## Returning
+
+Your final response should follow this shape:
+
+```
+Mode: <worker | debugger | tester | reviewer | refactor | documenter | oracle | planner>
+Did: <one-sentence summary of what you did or found>
+Changed files: <list, or "none" for read-only modes>
+Validation: <test/typecheck/build output, or "n/a" for read-only modes>
+Open risks / decisions needing approval: <list, or "none">
+Recommended next step: <one line>
+```
+
+Be concise. The parent synthesizes, not you.

package/agents-install.ts

@@ -1,12 +1,18 @@
 // =============================================================================
-// agents-install.ts — Idempotent install of soly-aware subagent configs
+// assets-install.ts — Idempotent install of soly-managed user assets
 // =============================================================================
 //
-// Soly ships its own variants of pi-subagents' worker and oracle, with
-// soly-specific system prompts (path discipline, plan structure, todo
-// integration). pi-subagents discovers agents from `~/.pi/agent/agents/`
-// (and a few other paths), so on first session_start we copy our agent
-// `.md` files there.
+// Soly ships two kinds of user-scope assets:
+//
+//   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".
@@ -18,43 +24,76 @@ import * as path from "node:path";
 
 /** soly agent files bundled with the extension. */
 const SHIPPED_AGENTS = [
-	"soly-worker.md",
-	"soly-debugger.md",
-	"soly-tester.md",
-	"soly-refactor.md",
-	"soly-oracle.md",
-	"soly-reviewer.md",
-	"soly-documenter.md",
+	"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 });
@@ -66,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[];
@@ -103,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/commands.ts

@@ -371,7 +371,7 @@ What must the LLM do?
 			};
 			const subcommands: Record<string, SolySub> = {
 				// `agent` subcommand REMOVED — moved to the separate `pi-switch`
-				// extension as the `/agent` slash command (header bar + Ctrl+Shift+S).
+				// extension as the `/agent` slash command (footer pill + Ctrl+Tab).
 				// Soly no longer owns the agent switcher UI.
 				config: {
 					description: "show merged config (per-project + global + defaults); edit .soly/config.json or ~/.soly/config.json",

package/config.ts

@@ -35,10 +35,11 @@ export interface SolyConfig {
 		preferAskPro: boolean;
 		/** When soly pause is invoked, also auto-save HANDOFF.json (currently always true; knob for future). */
 		autoCheckpointOnPause: boolean;
-		/** Opt-in: install soly-worker / soly-oracle agent configs to
-		 *  ~/.pi/agent/agents/ on session_start, and use soly-worker in
-		 *  soly execute workflows. Off by default — most users don't need
-		 *  soly-specialized subagents since the workflow template already
+		/** Opt-in: install soly-manager agent config to
+		 *  ~/.pi/agent/agents/ on session_start. The single soly subagent
+		 *  is mode-switching (worker/debugger/tester/reviewer/etc. based on
+		 *  the task brief). Off by default — most users don't need a soly-
+		 *  specialized subagent since the workflow template already
 		 *  contains soly instructions. */
 		useSolyWorkerSubagents: boolean;
 	};

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,
@@ -85,9 +85,9 @@ export default function solyExtension(pi: ExtensionAPI) {
 
 	// ============================================================================
 	// Agent switcher: REMOVED. The agent cycler is now owned by the
-	// separate `pi-switch` extension (header bar + Ctrl+Shift+S + /agent slash).
-	// Soly still owns the soly-specific agent files (soly-worker.md etc.) and
-	// the auto-install on opt-in. Workflows read the current agent from
+	// separate `pi-switch` extension (footer pill + Ctrl+Tab + /agent slash).
+	// Soly owns a single subagent (soly-manager.md) and the auto-install on
+	// opt-in. Workflows read the current agent from
 	// globalThis.__PI_SWITCH_AGENT__ (set by pi-switch).
 	// ============================================================================
 
@@ -328,7 +328,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 	// and mnemonic for "A"gent.)
 	// ============================================================================
 	// Agent switcher REMOVED — moved to the separate `pi-switch` extension.
-	// Soly no longer owns Ctrl+Shift+S, the header bar, or /agent slash.
+	// Soly no longer owns Ctrl+Tab, the footer pill, or /agent slash.
 	// The current agent is read by soly workflows from
 	// globalThis.__PI_SWITCH_AGENT__ (set by pi-switch), with a fallback
 	// to "worker" if pi-switch isn't installed.
@@ -388,21 +388,22 @@ export default function solyExtension(pi: ExtensionAPI) {
 			}
 		}
 
-		// Auto-install soly-aware subagent configs (soly-worker, soly-oracle)
-		// 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 configs (${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.5.10",
+  "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"