@juicesharp/rpiv-pi 0.4.4 → 0.5.0

package/extensions/rpiv-core/agents.ts

@@ -57,12 +57,6 @@ export interface SyncResult {
 	pendingRemove: string[];
 	/** Per-file errors collected during sync. */
 	errors: SyncError[];
-
-	// -- Legacy aliases (backward compat for existing callers) --
-	/** Alias: added + updated (files written by this run). */
-	copied: string[];
-	/** Alias: unchanged + pendingUpdate + files that errored during read and were not written. */
-	skipped: string[];
 }
 
 /** Create an empty SyncResult with all arrays initialized. */
@@ -75,8 +69,6 @@ function emptySyncResult(): SyncResult {
 		pendingUpdate: [],
 		pendingRemove: [],
 		errors: [],
-		copied: [],
-		skipped: [],
 	};
 }
 
@@ -219,7 +211,6 @@ export function syncBundledAgents(cwd: string, apply: boolean): SyncResult {
 				op: "read-src",
 				message: e instanceof Error ? e.message : String(e),
 			});
-			result.skipped.push(entry);
 			continue;
 		}
 		try {
@@ -230,18 +221,15 @@ export function syncBundledAgents(cwd: string, apply: boolean): SyncResult {
 				op: "read-dest",
 				message: e instanceof Error ? e.message : String(e),
 			});
-			result.skipped.push(entry);
 			continue;
 		}
 
 		if (Buffer.compare(srcContent, destContent) === 0) {
 			result.unchanged.push(entry);
-			result.skipped.push(entry);
 		} else if (apply) {
 			try {
 				copyFileSync(src, dest);
 				result.updated.push(entry);
-				result.copied.push(entry);
 			} catch (e) {
 				result.errors.push({
 					file: entry,
@@ -251,7 +239,6 @@ export function syncBundledAgents(cwd: string, apply: boolean): SyncResult {
 			}
 		} else {
 			result.pendingUpdate.push(entry);
-			result.skipped.push(entry);
 		}
 	}
 
@@ -287,26 +274,5 @@ export function syncBundledAgents(cwd: string, apply: boolean): SyncResult {
 		: [...sourceEntries, ...result.pendingRemove];
 	writeManifest(targetDir, manifestEntries);
 
-	// 6. Populate legacy `copied` alias (added + updated)
-	for (const name of result.added) {
-		result.copied.push(name);
-	}
-	// updated files were pushed to `copied` inline in the loop above
-
 	return result;
 }
-
-// ---------------------------------------------------------------------------
-// Backward-compatible wrapper
-// ---------------------------------------------------------------------------
-
-/**
- * Legacy entry point — delegates to syncBundledAgents.
- * Kept for backward compatibility; prefer syncBundledAgents for new callers.
- */
-export function copyBundledAgents(cwd: string, overwrite: boolean): {
-	copied: string[];
-	skipped: string[];
-} {
-	return syncBundledAgents(cwd, overwrite);
-}

package/extensions/rpiv-core/constants.ts

@@ -0,0 +1,3 @@
+export const FLAG_DEBUG = "rpiv-debug";
+export const MSG_TYPE_GIT_CONTEXT = "rpiv-git-context";
+export const MSG_TYPE_GUIDANCE = "rpiv-guidance";

package/extensions/rpiv-core/guidance.ts

@@ -22,6 +22,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, relative, sep, isAbsolute, join } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { FLAG_DEBUG, MSG_TYPE_GUIDANCE } from "./constants.js";
 
 // ---------------------------------------------------------------------------
 // Guidance Resolution
@@ -145,9 +146,9 @@ export function injectRootGuidance(cwd: string, pi: ExtensionAPI): void {
 		kind: "architecture",
 	});
 	pi.sendMessage({
-		customType: "rpiv-guidance",
+		customType: MSG_TYPE_GUIDANCE,
 		content: `## Project Guidance: ${label}\n\n${content}`,
-		display: false,
+		display: !!pi.getFlag(FLAG_DEBUG),
 	});
 }
 
@@ -185,9 +186,9 @@ export function handleToolCallGuidance(
 	);
 
 	pi.sendMessage({
-		customType: "rpiv-guidance",
+		customType: MSG_TYPE_GUIDANCE,
 		content: contextParts.join("\n\n---\n\n"),
-		display: false,
+		display: !!pi.getFlag(FLAG_DEBUG),
 	});
 }
 

package/extensions/rpiv-core/index.ts

@@ -1,276 +1,25 @@
 /**
- * rpiv-core — Orchestrator extension for the rpiv-pi package
+ * rpiv-core — Pure-orchestrator extension for rpiv-pi.
  *
- * Provides:
- * - Guidance injection (replaces inject-guidance.js hook)
- * - Git context injection (replaces !`git ...` shell evaluation in skills)
- * - thoughts/ directory scaffolding on session start
- * - Bundled-agent auto-copy into <cwd>/.pi/agents/
- * - Aggregated session_start warning for missing sibling plugins
- * - /rpiv-update-agents, /rpiv-setup slash commands
+ * Composes session hooks and the two slash commands. All logic lives in the
+ * registrar modules; this file is the table of contents.
  *
- * Tool-owning plugins are siblings: @juicesharp/rpiv-ask-user-question,
- * @juicesharp/rpiv-todo, @juicesharp/rpiv-advisor, @juicesharp/rpiv-web-tools.
- * Install via /rpiv-setup.
+ * Tool-owning plugins are siblings (see siblings.ts); install via /rpiv-setup.
  */
 
-import { mkdirSync } from "node:fs";
-import { join } from "node:path";
-import { isToolCallEventType, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { clearInjectionState, handleToolCallGuidance, injectRootGuidance } from "./guidance.js";
-import {
-	clearGitContextCache,
-	isGitMutatingCommand,
-	resetInjectedMarker,
-	takeGitContextIfChanged,
-} from "./git-context.js";
-import { syncBundledAgents } from "./agents.js";
-import { spawnPiInstall } from "./pi-installer.js";
-import {
-	hasPiSubagentsInstalled,
-	hasRpivAskUserQuestionInstalled,
-	hasRpivTodoInstalled,
-	hasRpivAdvisorInstalled,
-	hasRpivWebToolsInstalled,
-} from "./package-checks.js";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { FLAG_DEBUG } from "./constants.js";
+import { registerSessionHooks } from "./session-hooks.js";
+import { registerSetupCommand } from "./setup-command.js";
+import { registerUpdateAgentsCommand } from "./update-agents-command.js";
 
 export default function (pi: ExtensionAPI) {
-	// ── Session Start ──────────────────────────────────────────────────────
-	pi.on("session_start", async (_event, ctx) => {
-		clearInjectionState();
-		injectRootGuidance(ctx.cwd, pi);
-
-		// Scaffold thoughts/ directory structure (artifact chain)
-		const dirs = [
-			"thoughts/shared/research",
-			"thoughts/shared/questions",
-			"thoughts/shared/designs",
-			"thoughts/shared/plans",
-			"thoughts/shared/handoffs",
-		];
-		for (const dir of dirs) {
-			mkdirSync(join(ctx.cwd, dir), { recursive: true });
-		}
-
-		// Inject git context once into the transcript
-		const gitMsg = await takeGitContextIfChanged(pi);
-		if (gitMsg) {
-			pi.sendMessage({ customType: "rpiv-git-context", content: gitMsg, display: false });
-		}
-
-		// Sync bundled agents into <cwd>/.pi/agents/
-		// Detect-only mode: adds new files, detects drift, does NOT overwrite or remove.
-		const agentResult = syncBundledAgents(ctx.cwd, false);
-		if (ctx.hasUI) {
-			if (agentResult.added.length > 0) {
-				ctx.ui.notify(
-					`Copied ${agentResult.added.length} rpiv-pi agent(s) to .pi/agents/`,
-					"info",
-				);
-			}
-			const driftCount = agentResult.pendingUpdate.length + agentResult.pendingRemove.length;
-			if (driftCount > 0) {
-				const parts: string[] = [];
-				if (agentResult.pendingUpdate.length > 0) {
-					parts.push(`${agentResult.pendingUpdate.length} outdated`);
-				}
-				if (agentResult.pendingRemove.length > 0) {
-					parts.push(`${agentResult.pendingRemove.length} removed from bundle`);
-				}
-				ctx.ui.notify(
-					`${parts.join(", ")} agent(s). Run /rpiv-update-agents to sync.`,
-					"info",
-				);
-			}
-		}
-
-		// Aggregated warning for any missing sibling plugins
-		if (ctx.hasUI) {
-			const missing: string[] = [];
-			if (!hasPiSubagentsInstalled()) missing.push("@tintinweb/pi-subagents");
-			if (!hasRpivAskUserQuestionInstalled()) missing.push("@juicesharp/rpiv-ask-user-question");
-			if (!hasRpivTodoInstalled()) missing.push("@juicesharp/rpiv-todo");
-			if (!hasRpivAdvisorInstalled()) missing.push("@juicesharp/rpiv-advisor");
-			if (!hasRpivWebToolsInstalled()) missing.push("@juicesharp/rpiv-web-tools");
-			if (missing.length > 0) {
-				ctx.ui.notify(
-					`rpiv-pi requires ${missing.length} sibling extension(s): ${missing.join(", ")}. Run /rpiv-setup to install them.`,
-					"warning",
-				);
-			}
-		}
-	});
-
-	// ── Session Compact — drop injection state, re-inject root guidance ────
-	pi.on("session_compact", async (_event, ctx) => {
-		clearInjectionState();
-		clearGitContextCache();
-		resetInjectedMarker();
-		injectRootGuidance(ctx.cwd, pi);
-		const gitMsg = await takeGitContextIfChanged(pi);
-		if (gitMsg) {
-			pi.sendMessage({ customType: "rpiv-git-context", content: gitMsg, display: false });
-		}
-	});
-
-	// ── Session Shutdown ───────────────────────────────────────────────────
-	pi.on("session_shutdown", async (_event, _ctx) => {
-		clearInjectionState();
-		clearGitContextCache();
-		resetInjectedMarker();
-	});
-
-	// ── Guidance Injection + Git Cache Invalidation ────────────────────────
-	pi.on("tool_call", async (event, ctx) => {
-		handleToolCallGuidance(event, ctx, pi);
-		if (isToolCallEventType("bash", event) && isGitMutatingCommand(event.input.command)) {
-			clearGitContextCache();
-		}
-	});
-
-	// ── Git Context Injection (only when cache diverges from transcript) ───
-	pi.on("before_agent_start", async (_event, _ctx) => {
-		const content = await takeGitContextIfChanged(pi);
-		if (!content) return;
-		return {
-			message: { customType: "rpiv-git-context", content, display: false },
-		};
-	});
-
-	// ── /rpiv-update-agents Command ────────────────────────────────────────
-	pi.registerCommand("rpiv-update-agents", {
-		description: "Sync rpiv-pi bundled agents into .pi/agents/: add new, update changed, remove stale",
-		handler: async (_args, ctx) => {
-			const result = syncBundledAgents(ctx.cwd, true);
-			if (!ctx.hasUI) return;
-
-			const totalSynced = result.added.length + result.updated.length + result.removed.length;
-			if (totalSynced === 0 && result.errors.length === 0) {
-				ctx.ui.notify("All agents already up-to-date.", "info");
-				return;
-			}
-
-			const parts: string[] = [];
-			if (result.added.length > 0) parts.push(`${result.added.length} added`);
-			if (result.updated.length > 0) parts.push(`${result.updated.length} updated`);
-			if (result.removed.length > 0) parts.push(`${result.removed.length} removed`);
-
-			const summary = parts.length > 0
-				? `Synced agents: ${parts.join(", ")}.`
-				: "No changes needed.";
-
-			if (result.errors.length > 0) {
-				ctx.ui.notify(
-					`${summary} ${result.errors.length} error(s): ${result.errors.map((e) => e.message).join("; ")}`,
-					"warning",
-				);
-			} else {
-				ctx.ui.notify(summary, "info");
-			}
-		},
-	});
-
-	// ── /rpiv-setup Command ────────────────────────────────────────────────
-	pi.registerCommand("rpiv-setup", {
-		description: "Install rpiv-pi's sibling extension plugins",
-		handler: async (_args, ctx) => {
-			if (!ctx.hasUI) {
-				ctx.ui.notify("/rpiv-setup requires interactive mode", "error");
-				return;
-			}
-
-			const missing: Array<{ pkg: string; reason: string }> = [];
-			if (!hasPiSubagentsInstalled()) {
-				missing.push({
-					pkg: "npm:@tintinweb/pi-subagents",
-					reason: "required — provides Agent / get_subagent_result / steer_subagent tools",
-				});
-			}
-			if (!hasRpivAskUserQuestionInstalled()) {
-				missing.push({
-					pkg: "npm:@juicesharp/rpiv-ask-user-question",
-					reason: "required — provides the ask_user_question tool",
-				});
-			}
-			if (!hasRpivTodoInstalled()) {
-				missing.push({
-					pkg: "npm:@juicesharp/rpiv-todo",
-					reason: "required — provides the todo tool + /todos command + overlay widget",
-				});
-			}
-			if (!hasRpivAdvisorInstalled()) {
-				missing.push({
-					pkg: "npm:@juicesharp/rpiv-advisor",
-					reason: "required — provides the advisor tool + /advisor command",
-				});
-			}
-			if (!hasRpivWebToolsInstalled()) {
-				missing.push({
-					pkg: "npm:@juicesharp/rpiv-web-tools",
-					reason: "required — provides web_search + web_fetch tools + /web-search-config",
-				});
-			}
-
-			if (missing.length === 0) {
-				ctx.ui.notify(
-					"All rpiv-pi sibling dependencies already installed.",
-					"info",
-				);
-				return;
-			}
-
-			const lines = [
-				"rpiv-pi will install the following Pi packages via `pi install`:",
-				"",
-				...missing.map((m) => `  • ${m.pkg}  (${m.reason})`),
-				"",
-				"Each install is a separate `pi install <pkg>` invocation. Your",
-				"~/.pi/agent/settings.json will be updated. Proceed?",
-			];
-
-			const confirmed = await ctx.ui.confirm("Install rpiv-pi dependencies?", lines.join("\n"));
-			if (!confirmed) {
-				ctx.ui.notify("/rpiv-setup cancelled", "info");
-				return;
-			}
-
-			const succeeded: string[] = [];
-			const failed: Array<{ pkg: string; error: string }> = [];
-			for (const { pkg } of missing) {
-				ctx.ui.notify(`Installing ${pkg}…`, "info");
-				try {
-					const result = await spawnPiInstall(pkg, 120_000);
-					if (result.code === 0) {
-						succeeded.push(pkg);
-					} else {
-						failed.push({
-							pkg,
-							error: (result.stderr || result.stdout || `exit ${result.code}`).trim().slice(0, 300),
-						});
-					}
-				} catch (err) {
-					failed.push({
-						pkg,
-						error: err instanceof Error ? err.message : String(err),
-					});
-				}
-			}
-
-			const report: string[] = [];
-			if (succeeded.length > 0) {
-				report.push(`✓ Installed: ${succeeded.join(", ")}`);
-			}
-			if (failed.length > 0) {
-				report.push(`✗ Failed:`);
-				for (const { pkg, error } of failed) {
-					report.push(`  ${pkg}: ${error}`);
-				}
-			}
-			if (succeeded.length > 0) {
-				report.push("");
-				report.push("Restart your Pi session to load the newly-installed extensions.");
-			}
-			ctx.ui.notify(report.join("\n"), failed.length > 0 ? "warning" : "info");
-		},
+	pi.registerFlag(FLAG_DEBUG, {
+		description: "Show injected guidance and git-context messages",
+		type: "boolean",
+		default: false,
 	});
+	registerSessionHooks(pi);
+	registerUpdateAgentsCommand(pi);
+	registerSetupCommand(pi);
 }

package/extensions/rpiv-core/package-checks.ts

@@ -1,24 +1,16 @@
 /**
- * Package presence checks — detects whether sibling pi packages are installed.
- *
- * Pure utility. No ExtensionAPI interactions.
+ * Detect which SIBLINGS are installed by reading ~/.pi/agent/settings.json.
+ * Pure utility — no ExtensionAPI.
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-
-// ---------------------------------------------------------------------------
-// Paths
-// ---------------------------------------------------------------------------
+import { SIBLINGS, type SiblingPlugin } from "./siblings.js";
 
 const PI_AGENT_SETTINGS = join(homedir(), ".pi", "agent", "settings.json");
 
-// ---------------------------------------------------------------------------
-// Package Detection
-// ---------------------------------------------------------------------------
-
-export function readInstalledPackages(): string[] {
+function readInstalledPackages(): string[] {
 	if (!existsSync(PI_AGENT_SETTINGS)) return [];
 	try {
 		const raw = readFileSync(PI_AGENT_SETTINGS, "utf-8");
@@ -30,22 +22,12 @@ export function readInstalledPackages(): string[] {
 	}
 }
 
-export function hasPiSubagentsInstalled(): boolean {
-	return readInstalledPackages().some((entry) => /@tintinweb\/pi-subagents/i.test(entry));
-}
-
-export function hasRpivAskUserQuestionInstalled(): boolean {
-	return readInstalledPackages().some((entry) => /rpiv-ask-user-question/i.test(entry));
-}
-
-export function hasRpivTodoInstalled(): boolean {
-	return readInstalledPackages().some((entry) => /rpiv-todo/i.test(entry));
-}
-
-export function hasRpivAdvisorInstalled(): boolean {
-	return readInstalledPackages().some((entry) => /rpiv-advisor/i.test(entry));
-}
-
-export function hasRpivWebToolsInstalled(): boolean {
-	return readInstalledPackages().some((entry) => /rpiv-web-tools/i.test(entry));
+/**
+ * Return the SIBLINGS not currently installed.
+ * Reads ~/.pi/agent/settings.json once per call — callers that need both the
+ * full snapshot and the missing subset should call this once and filter.
+ */
+export function findMissingSiblings(): SiblingPlugin[] {
+	const installed = readInstalledPackages();
+	return SIBLINGS.filter((s) => !installed.some((entry) => s.matches.test(entry)));
 }

package/extensions/rpiv-core/session-hooks.ts

@@ -0,0 +1,120 @@
+/**
+ * Session lifecycle wiring for rpiv-core.
+ *
+ * Each handler body is a named helper; pi.on(...) lines are pure wiring.
+ * Ordering and invariants preserved verbatim from the pre-refactor index.ts.
+ */
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { isToolCallEventType, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { clearInjectionState, handleToolCallGuidance, injectRootGuidance } from "./guidance.js";
+import {
+	clearGitContextCache,
+	isGitMutatingCommand,
+	resetInjectedMarker,
+	takeGitContextIfChanged,
+} from "./git-context.js";
+import { syncBundledAgents, type SyncResult } from "./agents.js";
+import { FLAG_DEBUG, MSG_TYPE_GIT_CONTEXT } from "./constants.js";
+import { findMissingSiblings } from "./package-checks.js";
+
+const THOUGHTS_DIRS = [
+	"thoughts/shared/research",
+	"thoughts/shared/questions",
+	"thoughts/shared/designs",
+	"thoughts/shared/plans",
+	"thoughts/shared/handoffs",
+] as const;
+
+const msgAgentsAdded = (n: number) => `Copied ${n} rpiv-pi agent(s) to .pi/agents/`;
+const msgAgentsDrift = (parts: string[]) =>
+	`${parts.join(", ")} agent(s). Run /rpiv-update-agents to sync.`;
+const msgMissingSiblings = (n: number, list: string) =>
+	`rpiv-pi requires ${n} sibling extension(s): ${list}. Run /rpiv-setup to install them.`;
+
+type UI = { notify: (msg: string, sev: "info" | "warning" | "error") => void };
+
+export function registerSessionHooks(pi: ExtensionAPI): void {
+	pi.on("session_start", async (_event, ctx) => {
+		resetInjectionState();
+		injectRootGuidance(ctx.cwd, pi);
+		scaffoldThoughtsDirs(ctx.cwd);
+		await injectGitContext(pi, (msg) =>
+			pi.sendMessage({ customType: MSG_TYPE_GIT_CONTEXT, content: msg, display: !!pi.getFlag(FLAG_DEBUG) }),
+		);
+		const agents = syncBundledAgents(ctx.cwd, false);
+		if (ctx.hasUI) {
+			notifyAgentSyncDrift(ctx.ui, agents);
+			warnMissingSiblings(ctx.ui);
+		}
+	});
+
+	pi.on("session_compact", async (_event, ctx) => {
+		resetInjectionState();
+		clearGitContextCache();
+		resetInjectedMarker();
+		injectRootGuidance(ctx.cwd, pi);
+		await injectGitContext(pi, (msg) =>
+			pi.sendMessage({ customType: MSG_TYPE_GIT_CONTEXT, content: msg, display: !!pi.getFlag(FLAG_DEBUG) }),
+		);
+	});
+
+	pi.on("session_shutdown", async () => {
+		resetInjectionState();
+		clearGitContextCache();
+		resetInjectedMarker();
+	});
+
+	pi.on("tool_call", async (event, ctx) => {
+		handleToolCallGuidance(event, ctx, pi);
+		if (isToolCallEventType("bash", event) && isGitMutatingCommand(event.input.command)) {
+			clearGitContextCache();
+		}
+	});
+
+	pi.on("before_agent_start", async () => {
+		const content = await takeGitContextIfChanged(pi);
+		if (!content) return;
+		return { message: { customType: MSG_TYPE_GIT_CONTEXT, content, display: !!pi.getFlag(FLAG_DEBUG) } };
+	});
+}
+
+function resetInjectionState(): void {
+	clearInjectionState();
+}
+
+function scaffoldThoughtsDirs(cwd: string): void {
+	for (const dir of THOUGHTS_DIRS) {
+		mkdirSync(join(cwd, dir), { recursive: true });
+	}
+}
+
+async function injectGitContext(
+	pi: ExtensionAPI,
+	send: (msg: string) => void,
+): Promise<void> {
+	const msg = await takeGitContextIfChanged(pi);
+	if (msg) send(msg);
+}
+
+function notifyAgentSyncDrift(ui: UI, result: SyncResult): void {
+	if (result.added.length > 0) {
+		ui.notify(msgAgentsAdded(result.added.length), "info");
+	}
+	const parts: string[] = [];
+	if (result.pendingUpdate.length > 0) parts.push(`${result.pendingUpdate.length} outdated`);
+	if (result.pendingRemove.length > 0) parts.push(`${result.pendingRemove.length} removed from bundle`);
+	if (parts.length > 0) {
+		ui.notify(msgAgentsDrift(parts), "info");
+	}
+}
+
+function warnMissingSiblings(ui: UI): void {
+	const missing = findMissingSiblings();
+	if (missing.length === 0) return;
+	ui.notify(
+		msgMissingSiblings(missing.length, missing.map((m) => m.pkg.replace(/^npm:/, "")).join(", ")),
+		"warning",
+	);
+}

package/extensions/rpiv-core/setup-command.ts

@@ -0,0 +1,109 @@
+/**
+ * /rpiv-setup — installs any SIBLINGS not present in ~/.pi/agent/settings.json.
+ *
+ * Serial `pi install <pkg>` loop via spawnPiInstall (Windows-safe).
+ * Reports succeeded/failed split; prompts the user to restart Pi on success.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { findMissingSiblings } from "./package-checks.js";
+import { spawnPiInstall } from "./pi-installer.js";
+import { type SiblingPlugin } from "./siblings.js";
+
+const INSTALL_TIMEOUT_MS = 120_000;
+const STDERR_SNIPPET_CHARS = 300;
+
+const MSG_INTERACTIVE_ONLY = "/rpiv-setup requires interactive mode";
+const MSG_ALL_INSTALLED = "All rpiv-pi sibling dependencies already installed.";
+const MSG_CANCELLED = "/rpiv-setup cancelled";
+const MSG_CONFIRM_TITLE = "Install rpiv-pi dependencies?";
+const MSG_RESTART = "Restart your Pi session to load the newly-installed extensions.";
+
+const msgInstalling = (pkg: string) => `Installing ${pkg}…`;
+const msgInstalledLine = (pkgs: string[]) => `✓ Installed: ${pkgs.join(", ")}`;
+const msgFailedHeader = () => `✗ Failed:`;
+const msgFailedLine = (pkg: string, err: string) => `  ${pkg}: ${err}`;
+
+type UI = {
+	notify: (msg: string, sev: "info" | "warning" | "error") => void;
+	confirm: (title: string, body: string) => Promise<boolean>;
+};
+
+function buildConfirmBody(missing: SiblingPlugin[]): string {
+	return [
+		"rpiv-pi will install the following Pi packages via `pi install`:",
+		"",
+		...missing.map((m) => `  • ${m.pkg}  (required — provides ${m.provides})`),
+		"",
+		"Each install is a separate `pi install <pkg>` invocation. Your",
+		"~/.pi/agent/settings.json will be updated. Proceed?",
+	].join("\n");
+}
+
+export function registerSetupCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("rpiv-setup", {
+		description: "Install rpiv-pi's sibling extension plugins",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify(MSG_INTERACTIVE_ONLY, "error");
+				return;
+			}
+
+			const missing = findMissingSiblings();
+			if (missing.length === 0) {
+				ctx.ui.notify(MSG_ALL_INSTALLED, "info");
+				return;
+			}
+
+			const confirmed = await ctx.ui.confirm(MSG_CONFIRM_TITLE, buildConfirmBody(missing));
+			if (!confirmed) {
+				ctx.ui.notify(MSG_CANCELLED, "info");
+				return;
+			}
+
+			const { succeeded, failed } = await installMissing(ctx.ui, missing);
+			ctx.ui.notify(buildReport(succeeded, failed), failed.length > 0 ? "warning" : "info");
+		},
+	});
+}
+
+async function installMissing(
+	ui: UI,
+	missing: SiblingPlugin[],
+): Promise<{ succeeded: string[]; failed: Array<{ pkg: string; error: string }> }> {
+	const succeeded: string[] = [];
+	const failed: Array<{ pkg: string; error: string }> = [];
+	for (const { pkg } of missing) {
+		ui.notify(msgInstalling(pkg), "info");
+		try {
+			const result = await spawnPiInstall(pkg, INSTALL_TIMEOUT_MS);
+			if (result.code === 0) {
+				succeeded.push(pkg);
+			} else {
+				failed.push({
+					pkg,
+					error: (result.stderr || result.stdout || `exit ${result.code}`)
+						.trim()
+						.slice(0, STDERR_SNIPPET_CHARS),
+				});
+			}
+		} catch (err) {
+			failed.push({ pkg, error: err instanceof Error ? err.message : String(err) });
+		}
+	}
+	return { succeeded, failed };
+}
+
+function buildReport(succeeded: string[], failed: Array<{ pkg: string; error: string }>): string {
+	const lines: string[] = [];
+	if (succeeded.length > 0) lines.push(msgInstalledLine(succeeded));
+	if (failed.length > 0) {
+		lines.push(msgFailedHeader());
+		for (const { pkg, error } of failed) lines.push(msgFailedLine(pkg, error));
+	}
+	if (succeeded.length > 0) {
+		lines.push("");
+		lines.push(MSG_RESTART);
+	}
+	return lines.join("\n");
+}

package/extensions/rpiv-core/siblings.ts

@@ -0,0 +1,48 @@
+/**
+ * Declarative registry of rpiv-pi's sibling Pi plugins.
+ *
+ * Single source of truth for: presence detection (package-checks.ts),
+ * session_start "missing plugins" warning (session-hooks.ts), and
+ * /rpiv-setup installer (setup-command.ts). Add a sibling here and every
+ * consumer picks it up automatically.
+ *
+ * Detection is filesystem-based via a regex over ~/.pi/agent/settings.json
+ * — no runtime import of sibling packages (keeps rpiv-core pure-orchestrator).
+ */
+
+export interface SiblingPlugin {
+	/** Install spec passed to `pi install`. Prefixed with `npm:` for Pi's installer. */
+	readonly pkg: string;
+	/** Case-insensitive regex that matches the package in ~/.pi/agent/settings.json. */
+	readonly matches: RegExp;
+	/** What the sibling provides — shown in /rpiv-setup confirmation and reports. */
+	readonly provides: string;
+}
+
+export const SIBLINGS: readonly SiblingPlugin[] = [
+	{
+		pkg: "npm:@tintinweb/pi-subagents",
+		matches: /@tintinweb\/pi-subagents/i,
+		provides: "Agent / get_subagent_result / steer_subagent tools",
+	},
+	{
+		pkg: "npm:@juicesharp/rpiv-ask-user-question",
+		matches: /rpiv-ask-user-question/i,
+		provides: "ask_user_question tool",
+	},
+	{
+		pkg: "npm:@juicesharp/rpiv-todo",
+		matches: /rpiv-todo/i,
+		provides: "todo tool + /todos command + overlay widget",
+	},
+	{
+		pkg: "npm:@juicesharp/rpiv-advisor",
+		matches: /rpiv-advisor/i,
+		provides: "advisor tool + /advisor command",
+	},
+	{
+		pkg: "npm:@juicesharp/rpiv-web-tools",
+		matches: /rpiv-web-tools/i,
+		provides: "web_search + web_fetch tools + /web-search-config",
+	},
+];

package/extensions/rpiv-core/update-agents-command.ts

@@ -0,0 +1,42 @@
+/**
+ * /rpiv-update-agents — apply-mode sync of bundled agents into <cwd>/.pi/agents/.
+ * Adds new, overwrites changed managed files, removes stale managed files.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { syncBundledAgents, type SyncResult } from "./agents.js";
+
+const MSG_UP_TO_DATE = "All agents already up-to-date.";
+const MSG_NO_CHANGES = "No changes needed.";
+
+const msgSynced = (parts: string[]) => `Synced agents: ${parts.join(", ")}.`;
+const msgSyncedWithErrors = (summary: string, errors: string[]) =>
+	`${summary} ${errors.length} error(s): ${errors.join("; ")}`;
+
+export function registerUpdateAgentsCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("rpiv-update-agents", {
+		description:
+			"Sync rpiv-pi bundled agents into .pi/agents/: add new, update changed, remove stale",
+		handler: async (_args, ctx) => {
+			const result = syncBundledAgents(ctx.cwd, true);
+			if (!ctx.hasUI) return;
+			ctx.ui.notify(formatSyncReport(result), result.errors.length > 0 ? "warning" : "info");
+		},
+	});
+}
+
+function formatSyncReport(result: SyncResult): string {
+	const totalSynced = result.added.length + result.updated.length + result.removed.length;
+	if (totalSynced === 0 && result.errors.length === 0) return MSG_UP_TO_DATE;
+
+	const parts: string[] = [];
+	if (result.added.length > 0) parts.push(`${result.added.length} added`);
+	if (result.updated.length > 0) parts.push(`${result.updated.length} updated`);
+	if (result.removed.length > 0) parts.push(`${result.removed.length} removed`);
+
+	const summary = parts.length > 0 ? msgSynced(parts) : MSG_NO_CHANGES;
+	if (result.errors.length > 0) {
+		return msgSyncedWithErrors(summary, result.errors.map((e) => e.message));
+	}
+	return summary;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Skill-based development workflow for Pi Agent — discover, research, design, plan, implement, validate",
   "keywords": ["pi-package", "pi-extension", "rpiv", "skills", "workflow"],
   "license": "MIT",
@@ -17,16 +17,13 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["extensions/", "skills/", "agents/", "scripts/", "README.md"],
+  "files": ["extensions/", "skills/", "agents/", "scripts/", "README.md", "LICENSE"],
   "pi": {
     "extensions": ["./extensions"],
     "skills": ["./skills"]
   },
   "peerDependencies": {
-    "@mariozechner/pi-ai": "*",
     "@mariozechner/pi-coding-agent": "*",
-    "@mariozechner/pi-tui": "*",
-    "@sinclair/typebox": "*",
     "@tintinweb/pi-subagents": "*",
     "@juicesharp/rpiv-ask-user-question": "*",
     "@juicesharp/rpiv-todo": "*",

package/skills/explore/SKILL.md

@@ -31,35 +31,91 @@ Then wait for the user's request.
    - Extract requirements, constraints, and goals
    - Identify what problem we're solving
 
-2. **Research current state and analyze requirements:**
-   - **ALWAYS spawn fresh research** - Never rely on old research docs as truth
-   - Old research can be read as historical context but validate against current code
-   - Think deeply about requirements, constraints, and integration points
-
-   **Spawn parallel research agents using the Agent tool:**
-   - Use the **codebase-locator** agent to find relevant components
-   - Use the **codebase-analyzer** agent to understand current implementation
-   - Use the **codebase-pattern-finder** agent to find similar patterns
-   - Use the **thoughts-locator** agent to find historical context in thoughts/
-   - Optional: Use the **web-search-researcher** agent for web research only if user requests
-
-3. **Generate and compare solution options:**
-   - Wait for ALL agents to complete
-   - Generate 2-4 viable approaches when possible
-   - If only 1 clear option exists, explain why alternatives aren't viable
-   - For each option, document:
-     - How it works and precedent in codebase
-     - Pros/cons with evidence
-     - Complexity and integration points
-     - Risk factors
-   - Cross-reference agent findings
-   - Compare options systematically
-
-4. **Make recommendation:**
-   - Choose best option based on requirements, codebase fit, and complexity
-   - Provide clear rationale with evidence
-   - Explain why alternatives were not chosen
-   - Identify conditions that would change recommendation
+2. **Generate candidates and dimensions:**
+
+   **Generate 2–4 named candidates** from three sources, then merge into one shortlist:
+
+   - **Ecosystem scan** — spawn `web-search-researcher` for any topic where the candidate space includes external libraries, frameworks, or services. Prompt it to return 2–4 named options with one-line "what it is" + canonical doc link per option. Skip only when the topic is wholly internal (e.g., "how to organize this service layer") and the orchestrator's design-space enumeration plus the user shortlist already cover the space.
+   - **Design-space enumeration** — orchestrator names abstract shapes from first principles when applicable (pub/sub vs direct-call vs event-bus; sync vs async; manual mapping vs auto-mapper). One-line "what it is" per shape.
+   - **User shortlist** — if the user pre-named candidates in the entry prompt ("compare TanStack Query vs SWR"), include those verbatim.
+
+   Merge to 2–4 candidates total. Name each with a short noun phrase ("TanStack Query", "Direct event bus"). Deduplicate.
+
+   **Default dimension list** (presented at Step 2.5; developer may drop irrelevant ones):
+
+   - **approach-shape** (hybrid) — what category of solution the candidate is, what core moving parts it requires.
+   - **precedent-fit** (codebase-anchored) — does the existing code already use this pattern; how many call sites would adopt the new option.
+   - **integration-risk** (codebase-anchored) — which existing seams the candidate would touch; what breaks if it lands.
+   - **migration-cost** (external-anchored for libraries; codebase-anchored for in-house code) — work to introduce the candidate plus work to remove the incumbent if there is one.
+   - **verification-cost** (codebase-anchored) — test/CI surface needed to make the candidate safe to adopt.
+   - **novelty** (external-anchored) — how recently the candidate emerged, ecosystem momentum, deprecation risk.
+
+   Hold the candidate set and default dimension list in working state for the Step 2.5 checkpoint. Do not dispatch fit agents yet.
+
+## Step 2.5: Candidate Checkpoint
+
+Present the candidate set and default dimensions to the developer before per-candidate fit dispatch.
+
+1. **Show candidates and dimensions:**
+
+   ```
+   ## Candidates for: [Topic]
+
+   1. [Candidate A] — [one-line what it is]
+   2. [Candidate B] — [one-line what it is]
+   ...
+
+   Dimensions (default 6; drop any that don't apply):
+   - approach-shape · precedent-fit · integration-risk
+   - migration-cost · verification-cost · novelty
+   ```
+
+2. **Confirm via the `ask_user_question` tool with the following question:** "[N] candidates, [D] dimensions. Begin per-candidate fit dispatch?". Header: "Candidates". Options: "Proceed (Recommended)" (Begin per-candidate fit dispatch with all [N] candidates and all [D] dimensions); "Adjust candidates or dimensions" (Rename, add, or drop candidates; drop dimensions that don't apply); "Re-generate candidates" (Candidates look wrong — re-run Step 2 with adjusted scope).
+
+3. **Handle developer input:**
+
+   **"Proceed"**: lock the candidate × dimension set; advance to Step 3.
+
+   **"Adjust candidates or dimensions"**: ask the follow-up free-text question with prefix `❓ Question:` — "Which candidates and dimensions should be added, dropped, or renamed?" — apply edits to the working set, re-present, and confirm again with the same three-option `ask_user_question`.
+
+   **"Re-generate candidates"**: ask the follow-up free-text question with prefix `❓ Question:` — "What should be different in candidate generation? (narrower/wider scope, different ecosystem, exclude approach X, …)" — return to Step 2 with the updated scope, then re-enter Step 2.5.
+
+   Loop until "Proceed" is selected.
+
+3. **Per-candidate fit dispatch (parallel agents):**
+
+   For each confirmed candidate, dispatch up to two agents in parallel — total ≤ 2 × N agents:
+
+   - **One `codebase-analyzer` per candidate** — when ≥1 kept dimension is codebase-anchored (precedent-fit, integration-risk, often migration-cost and verification-cost). The agent scores the candidate on every kept codebase-anchored dimension in a single pass, returning evidence per dimension with `file:line` references.
+   - **One `web-search-researcher` per candidate** — when ≥1 kept dimension is external-anchored (novelty, often migration-cost for libraries, approach-shape for ecosystem options). The agent scores the candidate on every kept external-anchored dimension in a single pass, returning evidence per dimension with doc/source links.
+
+   Skip either agent for a candidate when no dimension of that anchor-type was kept. Hybrid dimension `approach-shape` is scored by the orchestrator after both agents return, by combining their per-candidate findings.
+
+   **Per-candidate prompt shape** (use the same outer template, fill in candidate name and kept dimensions):
+
+   ```
+   Candidate: [name] — [one-line what it is]
+   Topic: [topic from Step 1]
+
+   Score this single candidate on the following dimensions, each with concrete evidence ([file:line] for codebase, doc/source link for external). Report findings as one section per dimension.
+
+   Dimensions for this run:
+   - [dimension name] — [one-line of what to look for]
+   - ...
+
+   Do NOT compare against other candidates; another agent handles each one separately. Focus on depth of evidence for THIS candidate.
+   ```
+
+   Wait for ALL agents to complete before proceeding.
+
+   **Coverage check**: every (candidate × kept-dimension) cell is filled — by an agent's evidence or by an explicit `null` ("does not apply to this candidate"). Cells silently dropped indicate a missing dispatch — re-run that candidate's agent.
+
+4. **Synthesize and recommend:**
+
+   - Cross-reference per-candidate findings — fill the candidate × dimension grid with evidence per cell.
+   - Apply the fit filter qualitatively per candidate: a candidate "clears" when no kept dimension surfaces a blocking concern (integration-risk that breaks load-bearing seams, migration-cost that exceeds the topic's scope, verification-cost with no path to coverage).
+   - **If ≥1 candidate clears the fit filter**: pick the strongest, document rationale with evidence, and explain why alternatives weren't chosen. Identify conditions that would change the recommendation.
+   - **If every candidate fails the fit filter**: produce a "no-fit" recommendation — list each candidate's blocking dimension with evidence, recommend re-scoping the question or expanding the candidate pool, and set Step 6 frontmatter `confidence: low` and `status: blocked`.
 
 5. **Determine metadata and filename:**
    - Filename format: `thoughts/shared/solutions/YYYY-MM-DD_HH-MM-SS_[topic].md`
@@ -166,6 +222,10 @@ Then wait for the user's request.
 
      ## Recommendation
 
+     <!-- Render exactly ONE of the two blocks below, based on Step 4's fit-filter outcome. -->
+
+     **(A) When ≥1 candidate clears the fit filter:**
+
      **Selected:** [Option N]
 
      **Rationale:**
@@ -193,6 +253,21 @@ Then wait for the user's request.
      **Risks:**
      - [Risk]: [Mitigation]
 
+     **(B) When every candidate fails the fit filter:**
+
+     **No-fit:** every candidate surfaced a blocking concern on at least one kept dimension.
+
+     **Per-candidate blockers:**
+     - [Option 1]: [blocking dimension] — [evidence with file:line or doc link]
+     - [Option 2]: [blocking dimension] — [evidence]
+     - ...
+
+     **Recommended next step:**
+     - [Re-scope the question] — [how the topic should narrow/widen so candidates can clear]
+     - OR [Expand the candidate pool] — [what new candidate sources to enumerate; e.g., named ecosystem option not surfaced by Step 2]
+
+     **Frontmatter overrides:** set `confidence: low` and `status: blocked`.
+
      ## Scope Boundaries
      - [What we're building]
      - [What we're NOT doing]
@@ -243,19 +318,21 @@ Then wait for the user's request.
 - Always use parallel Agent tool calls to maximize efficiency and minimize context usage
 - Always spawn fresh research to validate current state - never rely on old research docs as source of truth
 - Old research documents can provide historical context but must be validated against current code
-- Focus on generating 2-4 viable solution options with specific file:line references
+- Generate 2-4 named candidates in Step 2; confirm them with the developer at Step 2.5 before per-candidate fit dispatch
+- Web-search-researcher is a first-class Step 2 agent for ecosystem candidate-source — skip only when the topic is wholly internal and design-space enumeration plus user shortlist cover the space
+- Per-candidate fit dispatch caps at two agents per candidate (one codebase-analyzer, one web-search-researcher) — skip either when no dimension of its anchor-type was kept
 - Solutions documents should be self-contained with all necessary context
-- Each agent prompt should be specific and focused on targeted research questions
-- Quantify pattern precedent - count usage in codebase, don't just say "follows pattern"
+- Each agent prompt should be specific and focused on a single candidate scored on the kept dimensions
+- Quantify pattern precedent — count usage in codebase, don't just say "follows pattern"
 - Ground complexity estimates in actual similar work from git history
-- Think like a software architect - you're setting up design for success by landing on one chosen approach with evidence
+- Think like a software architect — option-shopping output is 2–4 comparable candidates plus an honest fit verdict
 - Keep the main agent focused on synthesis and comparison, not deep implementation details
 - Encourage agents to find existing patterns and examples, not just describe possibilities
-- Resolve technical unknowns during research - don't leave critical questions for design
+- Resolve technical unknowns during research — don't leave critical questions for design
 - **File reading**: Always read mentioned files FULLY (no limit/offset) before invoking skills
 - **Critical ordering**: Follow the numbered steps exactly
   - ALWAYS read mentioned files first before invoking skills (step 1)
-  - ALWAYS spawn fresh research to validate current state (step 2)
-  - ALWAYS wait for all agents to complete before synthesizing (step 3)
+  - ALWAYS generate candidates and run the Step 2.5 checkpoint before per-candidate dispatch (steps 2 → 2.5 → 3)
+  - ALWAYS wait for all per-candidate agents to complete before synthesizing (step 3)
   - ALWAYS gather metadata before writing the document (step 5 before step 6)
   - NEVER write the solutions document with placeholder values

package/scripts/types.js

@@ -1 +0,0 @@
-export {};