pruff-skills 0.11.0 → 0.12.0

package/dist/cli.mjs

@@ -4026,6 +4026,78 @@ async function fetchAgentFile(source, name) {
 		return null;
 	}
 }
+async function listCatalogAgents(source) {
+	const toNames = (files) => files.filter((f) => f.endsWith(".md")).map((f) => f.slice(0, -3));
+	if (source.startsWith(".") || isAbsolute(source)) try {
+		return toNames(await readdir(join(source, "agents")));
+	} catch {
+		return null;
+	}
+	if (/^[^/]+\/[^/]+$/.test(source)) try {
+		const { stdout } = await execFileAsync$4("gh", [
+			"api",
+			`repos/${source}/contents/agents`,
+			"--jq",
+			".[].name"
+		], { env: {
+			...process.env,
+			GIT_TERMINAL_PROMPT: "0"
+		} });
+		return toNames(stdout.trim().split("\n").filter(Boolean));
+	} catch {
+		return null;
+	}
+	try {
+		return toNames(await readdir(join(await cloneRepo$1(source), "agents")));
+	} catch {
+		return null;
+	}
+}
+async function listInstalledAgents(targetDir) {
+	try {
+		return (await readdir(targetDir, { withFileTypes: true })).filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => e.name.slice(0, -3));
+	} catch {
+		return [];
+	}
+}
+async function updateAgents(options = {}) {
+	const source = PRUFF_CATALOG;
+	const targetDir = claudeAgentsDir(options.global ?? false);
+	const result = {
+		updated: [],
+		failed: [],
+		localOnly: [],
+		available: [],
+		catalogUnavailable: false
+	};
+	const installed = await listInstalledAgents(targetDir);
+	if (installed.length === 0) return result;
+	const catalog = await listCatalogAgents(source);
+	if (!catalog) {
+		result.catalogUnavailable = true;
+		return result;
+	}
+	const filter = options.names?.map((n) => n.toLowerCase());
+	const matches = (name) => !filter || filter.length === 0 || filter.includes(name.toLowerCase());
+	const catalogSet = new Set(catalog);
+	const installedSet = new Set(installed);
+	result.available = catalog.filter((n) => !installedSet.has(n) && matches(n));
+	for (const name of installed) {
+		if (!matches(name)) continue;
+		if (!catalogSet.has(name)) {
+			result.localOnly.push(name);
+			continue;
+		}
+		const content = await fetchAgentFile(source, name);
+		if (content === null) {
+			result.failed.push(name);
+			continue;
+		}
+		await writeFile(join(targetDir, `${sanitizeName(name)}.md`), content);
+		result.updated.push(name);
+	}
+	return result;
+}
 function parseAgentsOptions(args) {
 	const names = [];
 	const options = {};
@@ -5672,8 +5744,9 @@ async function updateProjectSkills(options = {}) {
 	}
 	for (const [source, skillsForSource] of bySource) {
 		const firstEntry = skillsForSource[0].entry;
-		const sourceUrl = firstEntry.source;
-		const ref = firstEntry.ref;
+		const parsedSource = parseSource(firstEntry.source);
+		const sourceUrl = parsedSource.url;
+		const ref = firstEntry.ref ?? parsedSource.ref;
 		const allLockedForSource = Object.entries(localLock.skills).filter(([_, entry]) => entry.source === source).map(([name, _]) => name);
 		let tempDir = null;
 		let deletedSkills = [];
@@ -5684,7 +5757,8 @@ async function updateProjectSkills(options = {}) {
 			});
 			deletedSkills = await checkAndPromptForDeletions(source, allLockedForSource, localLock.skills, false, options, discoveredPaths);
 		} catch (error) {
-			console.log(`${DIM$1}✗ Failed to check for deleted skills from ${source}${RESET$1}`);
+			const reason = error instanceof Error ? error.message : String(error);
+			console.log(`${DIM$1}✗ Failed to check for deleted skills from ${source}: ${sanitizeMetadata(reason)}${RESET$1}`);
 		} finally {
 			if (tempDir) await cleanupTempDir(tempDir);
 		}
@@ -5734,6 +5808,29 @@ function printLegacyProjectSkills(legacy) {
 		console.log(`    ${DIM$1}To refresh: ${TEXT$1}npx pruff-skills add ${reinstall} -y${RESET$1}`);
 	}
 }
+async function syncAgentsForScope(isGlobal, options) {
+	const result = await updateAgents({
+		global: isGlobal,
+		names: options.skills
+	});
+	const label = isGlobal ? "global" : "project";
+	if (result.catalogUnavailable) {
+		console.log(`  ${DIM$1}✗ Could not read the subagent catalog — skipped ${label} subagents${RESET$1}`);
+		return result;
+	}
+	for (const name of result.updated) console.log(`  ${TEXT$1}✓${RESET$1} Synced ${sanitizeMetadata(name)}`);
+	for (const name of result.failed) console.log(`  ${DIM$1}✗ Failed to sync ${sanitizeMetadata(name)}${RESET$1}`);
+	if (result.localOnly.length > 0) {
+		const names = result.localOnly.map((n) => sanitizeMetadata(n)).join(", ");
+		console.log(`  ${DIM$1}• Not in the catalog, left untouched: ${names}${RESET$1}`);
+	}
+	if (result.available.length > 0) {
+		const names = result.available.map((n) => sanitizeMetadata(n)).join(", ");
+		console.log(`  ${DIM$1}• Available but not installed: ${names}${RESET$1}`);
+		console.log(`    ${DIM$1}To install: ${TEXT$1}npx pruff-skills agents add <name>${isGlobal ? " -g" : ""}${RESET$1}`);
+	}
+	return result;
+}
 async function runUpdate(args = []) {
 	const options = parseUpdateOptions(args);
 	const scope = await resolveUpdateScope(options);
@@ -5758,10 +5855,25 @@ async function runUpdate(args = []) {
 		totalFail += failCount;
 		totalFound += foundCount;
 	}
+	console.log();
+	console.log(`${BOLD$1}Subagents${RESET$1}`);
+	console.log(`${DIM$1}ALL installed subagents will be updated and synced with the repo — local edits are overwritten.${RESET$1}`);
+	const agentScopes = scope === "both" ? [true, false] : scope === "global" ? [true] : [false];
+	let agentsSynced = 0;
+	let agentsFailed = 0;
+	for (const isGlobal of agentScopes) {
+		const agentResult = await syncAgentsForScope(isGlobal, options);
+		agentsSynced += agentResult.updated.length;
+		agentsFailed += agentResult.failed.length;
+	}
+	if (agentsSynced === 0 && agentsFailed === 0) console.log(`  ${DIM$1}No installed subagents to sync.${RESET$1}`);
+	totalSuccess += agentsSynced;
+	totalFail += agentsFailed;
+	totalFound += agentsSynced + agentsFailed;
 	if (options.skills && totalFound === 0) console.log(`${DIM$1}No installed skills found matching: ${options.skills.join(", ")}${RESET$1}`);
 	console.log();
-	if (totalSuccess > 0) console.log(`${TEXT$1}✓ Updated ${totalSuccess} skill(s)${RESET$1}`);
-	if (totalFail > 0) console.log(`${DIM$1}Failed to update ${totalFail} skill(s)${RESET$1}`);
+	if (totalSuccess > 0) console.log(`${TEXT$1}✓ Updated ${totalSuccess} item(s)${RESET$1}`);
+	if (totalFail > 0) console.log(`${DIM$1}Failed to update ${totalFail} item(s)${RESET$1}`);
 	String(totalSuccess + totalFail);
 	console.log();
 }
@@ -7896,9 +8008,7 @@ const TEAM_SKILLS = {
 		"pruff-logs",
 		"pruff-sgsi",
 		"infra-healthcheck",
-		"pr-visualizer-llm",
 		"pr-visualizer",
-		"create-pr-llm",
 		"prod-parity",
 		"review-pr-comments"
 	]
@@ -8734,7 +8844,7 @@ async function showBanner() {
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills agents add ${DIM}<name>${RESET} ${DIM}Add a Pruff subagent${RESET}`);
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills rules add ${DIM}<name>${RESET}  ${DIM}Add a Pruff rule (.claude/rules/)${RESET}`);
 	console.log();
-	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills update${RESET}            ${DIM}Update installed skills${RESET}`);
+	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills update${RESET}            ${DIM}Update installed skills + subagents${RESET}`);
 	console.log();
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills experimental_install${RESET} ${DIM}Restore from skills-lock.json${RESET}`);
 	console.log(`  ${DIM}$${RESET} ${TEXT}npx pruff-skills init ${DIM}[name]${RESET}       ${DIM}Create a new skill${RESET}`);
@@ -8789,6 +8899,8 @@ ${BOLD}Onboarding Options:${RESET}
 
 ${BOLD}Updates:${RESET}
   update [skills...]   Update skills to latest versions (alias: upgrade)
+                     Also syncs ALL installed subagents with the catalog,
+                     overwriting local edits.
 
 ${BOLD}Update Options:${RESET}
   -g, --global           Update global skills only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pruff-skills",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "The official Pruff agent skills CLI",
   "type": "module",
   "bin": {

package/packs/pruff-shared/agents/fixer-shared.persona.md

@@ -43,11 +43,12 @@ human directly. Your output is always a **draft PR** — never a merge, never a
    individual edit. Chain the repo's typecheck/lint/tests into a single command
    (`&&`) rather than separate calls. If the fix touches Prisma or raw SQL, run the
    `db-query-reviewer` subagent on your own diff before anyone else has to.
-5. **Commit and open the PR** using the `/commit` and `/create-pr-llm` skills — never a
-   raw `git commit`/`gh pr create`, and never the legacy `/create-pr` — your PRs always
-   go to `reviewer-shared` next, so the description needs `/create-pr-llm`'s anchored,
-   verifiable claims and authored "judge this" questions for that skill to work with.
-   The PR is **always a draft**; a human marks it ready.
+5. **Commit and open the PR** using the `/commit` and `/create-pr` skills — never a raw
+   `git commit`/`gh pr create`. Your PRs always go to `reviewer-shared` next, so anchor
+   every solution bullet to `file:symbol` and give every decision a real "judge this"
+   question: that is what the review artifact verifies against the diff and reuses as the
+   "after" pane of its before/after pairs. The PR is **always a draft**; a human marks it
+   ready.
 6. **Post the PR link to `#pr-review` — always, not optionally.** `reviewer-shared`
    only listens in `#pr-review`; it does not see `#fixer-queue` at all, so replying
    there, or having a human type `?reviewer` in a `#fixer-queue` thread, reaches no
@@ -78,4 +79,4 @@ human directly. Your output is always a **draft PR** — never a merge, never a
 | Review your own Prisma/SQL diff before opening the PR | the `db-query-reviewer` subagent |
 | Trace a request/cron to confirm a root cause | the `pruff-logs-investigator` subagent |
 | Commit | the `/commit` skill — never raw `git commit` |
-| Open the PR | the `/create-pr-llm` skill — never raw `gh pr create`, never legacy `/create-pr`; always draft |
+| Open the PR | the `/create-pr` skill — never raw `gh pr create`; always draft, always anchored |

package/packs/pruff-shared/agents/reviewer-shared.persona.md

@@ -29,21 +29,27 @@ don't guess which one they mean.
 2. **Read the touched repo's own rules** before judging anything —
    `~/Desktop/pruff/<repo>/CLAUDE.md` and `.claude/rules/*.md`. A finding that
    contradicts a rule you didn't read is not a finding, it's noise.
-3. **Run the `pr-visualizer-llm` skill** to generate the review artifact — it verifies
-   the PR description's anchored claims (`file:symbol`) directly against the diff and
-   lifts the author's own "judge this" questions for the human, rather than
-   rediscovering everything from scratch. This is the deliverable; don't hand-roll an
-   equivalent by reading the diff and writing prose. If the PR body isn't in that
-   format (no anchored claims, no ⚖️ column — i.e. it wasn't written by `fixer-shared`
-   with `/create-pr-llm`), fall back to the legacy `pr-visualizer` skill instead.
-   **Never let it run in `light` mode, regardless of how small the diff looks.**
-   `light` is 0-agents — it only reads exactly what the PR description anchors, and a
-   real review missed a confirmed blocker this way: the PR claimed "no backend changes
-   needed" for an autocomplete filter, and `light` mode has no mechanism to check
-   whether that claim is true, because it never traces the value into the actual
-   service layer. Always pass `--standard` explicitly. Go to `--deep` only if a human
-   asks for a deeper look in `#pr-review` — never on your own initiative, and never
-   drop back to `light` for a PR that "looks contained."
+3. **Run the `pr-visualizer` skill** to generate the review artifact — it builds the
+   change as before/after diagram pairs, consolidates the specialist findings you pass
+   it, and lifts the author's own "judge this" questions for the human. This is the
+   deliverable; don't hand-roll an equivalent by reading the diff and writing prose.
+   It handles both anchored and legacy PR bodies; an anchored body (one written with
+   `/create-pr`) just makes it cheaper and sharper.
+   **Pass a mode explicitly; let the diff choose which one.** `light` is 0-agents and
+   is the right call for a genuinely contained change — a copy fix, a config bump, one
+   component's internals. It still builds the before/after pairs (it reads the base
+   state with `git show <base>:<path>`); what it does not do is trace a value beyond
+   the files the diff touches.
+
+   That limit is the one that bit us, so escalate on **the shape of the claim, not the
+   size of the diff**: a real review missed a confirmed blocker when a PR claimed "no
+   backend changes needed" for an autocomplete filter and nothing checked whether that
+   was true — the param was validated in the Zod schema and never wired into
+   `buildWhere`. Whenever the description asserts something about code the diff does
+   **not** contain ("no backend changes", "no migration needed", "behavior unchanged"),
+   `light` structurally cannot check it. Pass `--standard` for those, and for anything
+   touching schema, auth, money, or concurrency. Go to `--deep` only if a human asks in
+   `#pr-review` — never on your own initiative.
 4. **Comment the dossier on the PR.** The skill reports a markdown dossier and a link to
    an interactive HTML version. **Post the markdown as the comment body** — that is the
    durable record. Then add the link on its own last line, with the absolute expiry date
@@ -88,7 +94,7 @@ worse than asking once.
 
 | Task | Reach for |
 |---|---|
-| Generate the review artifact | the `pr-visualizer-llm` skill — this is your primary tool, use it every time. Fall back to `pr-visualizer` only for a legacy (non-anchored) PR body |
+| Generate the review artifact | the `pr-visualizer` skill — this is your primary tool, use it every time |
 | Prisma / raw SQL in the diff | the `db-query-reviewer` subagent |
 | Find where a changed symbol is used elsewhere | the `codebase-navigator` subagent |
 | The full multi-dimension review pipeline (rules + db + react-doctor) | the `pruff-pr-review` skill, if the PR is large enough to warrant it |

package/packs/pruff-shared/instructions.md

@@ -9,7 +9,7 @@ belongs in that agent's own persona file.
 
 | Display name | Owns | What it does | Writes code? | Responds to |
 |---|---|---|---|---|
-| `reviewer-shared` | `#pr-review` | Runs `pr-visualizer-llm` on a PR, posts a summary, requests a human reviewer via `gh`. Never approves or merges. | No | allowlist |
+| `reviewer-shared` | `#pr-review` | Runs `pr-visualizer` on a PR, posts a summary, requests a human reviewer via `gh`. Never approves or merges. | No | allowlist |
 | `marketing-shared` | `#marketing` | Answers questions using Linear + GitHub history + the brand guide. Drafts newsletter/comms/campaign copy **in chat only**. | No | allowlist |
 | `investigator-shared` | `#triage` | Triages a bug report using CloudWatch, GitHub history and Linear. Hands confirmed root causes to `fixer-shared` via `#fixer-queue`. | No | allowlist |
 | `fixer-shared` | `#fixer-queue` | Takes a triaged job (from `investigator-shared` or a human) and opens a **draft PR**. Never merges, never pushes to `dev`/`main`. | Yes | allowlist |