@spardutti/claude-skills 2.58.0 → 2.59.0

package/README.md

@@ -134,7 +134,8 @@ Portable slash commands installed to `.claude/commands/`. Some orchestrate paral
 |---------|--------------|
 | `/ship` | Unified delivery pipeline — commit → gate → PR → merge → release. The gate is the one enforcement moment: it checks the diff's file lengths and that new files sit in their kind folder, audits it against the skills installed in the project, mutation-tests the changed lines to prove the tests would catch a break, and runs one `/code-review` round for logic bugs — **fixing what it finds** rather than handing you a list. It runs before the **PR**, not before every commit: its scope is the whole branch, so gating each commit re-mutated every file the branch had ever touched. `--force` skips it. No argument steps through interactively; `/ship pr` runs through PR creation; `/ship release` runs the full pipeline |
 | `/discover` | Find the right problem before deciding what to build — diverges first: generates competing framings through blind subagents under forced constraints, stress-tests the winner with a blind critic, and refuses to converge until every open question is answered or deferred, then drafts scope, non-goals, edge cases and success criteria for you to correct. Run before `/plan-feature` |
-| `/plan-feature` | Integration-first feature planning, then building — one agent scans the repo for reusable code, patterns and touch points, grounded clarifying questions follow, the plan is written as type-checked stubs at the real paths, and on your go it fills them in |
+| `/plan-feature` | Integration-first feature planning, then building — one agent scans the repo for reusable code, patterns and touch points, grounded clarifying questions follow, the plan is written as type-checked stubs at the real paths, and on your go it fills them in. It reads every `*.registry.yaml` first and must mark each one reuse or skip |
+| `/registry` | Record the project's reusable systems — aiming methods, a state machine, an effect pipeline — as a small `<name>.registry.yaml` next to their code, so `/plan-feature` extends them instead of rebuilding them. You name the system, it drafts the entry for your yes. Nothing reads the registry outside planning |
 | `/optimize` | Make one measured job faster without changing what it proves — fixes a benchmark and a result that must not move, sends 4 read-only subagents to find suspects, then changes one thing per round with a prediction written first, keeping only what beats the noise. Profiles after every wrong prediction, reruns before judging a result that flipped, and ends by writing the cause as a skill rule for you |
 | `/handoff` | Write a handoff doc so a fresh session picks the work up — captures what auto-compaction loses: decisions made and rejected, dead ends already ruled out, why the tree is dirty, and the one next step |
 | `/lockdown` | Per-repo supply-chain hardening — detects the package managers, Dockerfiles, and CI in use, then guides you through and applies install-time, deploy, and pipeline hardening for npm/pnpm, pip/uv, Docker, and GitHub Actions |
@@ -199,6 +200,7 @@ scripts/       validate-skills.mjs — checks skill length caps and reference in
                skill-flags-record.sh — logs each /ship skills audit and /code-review; skill-report.mjs tallies them
                edit-check.sh — PostToolUse check on each edited file: line-limit.sh, lint-ratchet.mjs, .edit-rules.json
                diary-check.mjs — run at the end of /ship; says when the diaries hold enough for /add-rule
+               registry.mjs — the *.registry.yaml checks for /plan-feature and /registry
                line-limit.sh — the 200-line ratchet, shared by the edit check, the ship gate and preflight
                gauntlet-selftest.sh — behavioural tests for the hooks (runs in preflight)
                gauntlet-survey.sh — what the hook would do in every repo under a directory

package/hooks/registry-lib.mjs

@@ -0,0 +1,82 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { spawnSync } from "node:child_process";
+
+export const REGISTRY_SUFFIX = ".registry.yaml";
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".venv", "venv", "__pycache__"]);
+
+export function projectRoot() {
+  const dir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const top = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  return top.status === 0 ? top.stdout.trim() : dir;
+}
+
+function walk(dir, root, out) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.isDirectory() && !SKIP_DIRS.has(e.name)) walk(join(dir, e.name), root, out);
+    else if (e.isFile()) out.push(relative(root, join(dir, e.name)));
+  }
+  return out;
+}
+
+export function projectFiles(root) {
+  const git = spawnSync("git", ["-C", root, "ls-files", "--cached", "--others", "--exclude-standard"],
+    { encoding: "utf8", maxBuffer: 64 << 20 });
+  if (git.status !== 0) return walk(root, root, []);
+  return git.stdout.split("\n").filter((f) => f && existsSync(join(root, f)));
+}
+
+function value(raw) {
+  const v = raw.trim();
+  if (v.startsWith("[") && v.endsWith("]")) {
+    return v.slice(1, -1).split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+  }
+  return v.replace(/^["']|["']$/g, "");
+}
+
+export function parseEntry(text) {
+  const entry = {};
+  for (const line of text.split("\n")) {
+    const m = line.match(/^([a-z_]+):\s*(.*?)\s*(?:\s#.*)?$/);
+    if (m) entry[m[1]] = value(m[2]);
+  }
+  entry.triggers = [].concat(entry.triggers ?? []).filter(Boolean);
+  return entry;
+}
+
+export function loadRegistry(root, files) {
+  return files
+    .filter((f) => f.endsWith(REGISTRY_SUFFIX))
+    .sort()
+    .map((file) => {
+      const text = readFileSync(join(root, file), "utf8");
+      return { file, text, ...parseEntry(text) };
+    });
+}
+
+// Code-shaped words (AimStrategy, pick_target, aimRegistry) or `backticked` — never "implement".
+export function symbolsOf(extendBy = "") {
+  const ticked = [...extendBy.matchAll(/`([\w.]+)`/g)].map((m) => m[1]);
+  const shaped = extendBy.match(/\b(?:[A-Z][a-z0-9]+[A-Z]\w*|[a-z]\w*[A-Z]\w*|\w+_\w+)\b/g) ?? [];
+  return [...new Set([...ticked, ...shaped])];
+}
+
+export const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+export function triggerHits(entry, text) {
+  return entry.triggers.filter((t) => new RegExp(`\\b${escape(t)}\\b`, "i").test(text));
+}
+
+// A location is a folder or one file, like sim/aim.gd beside unrelated systems in sim/.
+export function insideLocation(entry, file) {
+  const loc = (entry.location ?? "").replace(/^\.\//, "");
+  return loc !== "" && (file === loc || file.startsWith(loc.replace(/\/?$/, "/")));
+}
+
+// Only what the stub added: an extended file's old code would trip triggers it never wrote.
+export function addedText(root, file) {
+  const tracked = spawnSync("git", ["-C", root, "ls-files", "--error-unmatch", file], { encoding: "utf8" });
+  if (tracked.status !== 0) return existsSync(join(root, file)) ? readFileSync(join(root, file), "utf8") : "";
+  const diff = spawnSync("git", ["-C", root, "diff", "HEAD", "--", file], { encoding: "utf8" }).stdout ?? "";
+  return diff.split("\n").filter((l) => l.startsWith("+") && !l.startsWith("+++")).map((l) => l.slice(1)).join("\n");
+}

package/hooks/registry.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import {
+  REGISTRY_SUFFIX, addedText, escape, insideLocation, loadRegistry, projectFiles, projectRoot, symbolsOf, triggerHits,
+} from "./registry-lib.mjs";
+
+const root = projectRoot();
+const files = projectFiles(root);
+const entries = loadRegistry(root, files);
+const uses = (text, word) => new RegExp(`\\b${escape(word)}\\b`).test(text);
+const fromCwd = (f) => relative(root, resolve(f));
+
+function list() {
+  if (!entries.length) return console.log(`registry none — no *${REGISTRY_SUFFIX} in this project`);
+  for (const e of entries) console.log(`== ${e.file} ==\n${e.text.trim()}\n`);
+  stale();
+}
+
+function planMarks(planPath) {
+  const text = existsSync(planPath) ? readFileSync(planPath, "utf8") : null;
+  if (text === null) return null;
+  const section = text.split(/^## /m).find((s) => /^Registry\s*$/m.test(s.split("\n")[0])) ?? "";
+  const marks = new Map();
+  for (const m of section.matchAll(/^[-*]\s*`?([\w.-]+)`?\s*:\s*(reuse|skip)\b/gim)) marks.set(m[1], m[2].toLowerCase());
+  return marks;
+}
+
+function checkPlan(planPath, stubs) {
+  if (!entries.length) return console.log("registry ok — no entries");
+  const marks = planMarks(planPath);
+  if (!marks) return fail([`registry FAIL ${planPath} not found — save the plan notes there first`]);
+  const added = stubs.map((f) => addedText(root, fromCwd(f))).join("\n");
+  const fails = [], asks = [];
+  for (const name of marks.keys()) {
+    if (!entries.some((e) => e.name === name)) fails.push(`registry FAIL ${name}: no such entry`);
+  }
+  for (const e of entries) {
+    const mark = marks.get(e.name);
+    if (!mark) fails.push(`registry FAIL ${e.name}: missing from ## Registry — mark it reuse or skip`);
+    else if (mark === "reuse" && !symbolsOf(e.extend_by).some((s) => uses(added, s))) {
+      fails.push(`registry FAIL ${e.name}: marked reuse, but no stub uses ${symbolsOf(e.extend_by).join(", ") || "a name from extend_by"}`);
+    } else if (mark === "skip") {
+      const hits = triggerHits(e, added);
+      if (hits.length) asks.push(`registry ASK ${e.name}: skipped, but the stubs mention ${hits.join(", ")} — ask the user before stopping`);
+    }
+  }
+  for (const line of asks) console.log(line);
+  if (fails.length) return fail(fails);
+  if (!asks.length) console.log("registry ok");
+}
+
+function stale() {
+  const problems = [];
+  const seen = new Set();
+  for (const e of entries) {
+    const say = (why) => problems.push(`registry stale ${e.file}: ${why}`);
+    for (const key of ["name", "summary", "location", "extend_by"]) {
+      if (!e[key]) say(`no ${key}`);
+      else if (/^[|>]/.test(e[key])) say(`${key} must sit on one line`);
+    }
+    if (e.name && !/^[\w.-]+$/.test(e.name)) say(`name ${e.name} may hold only letters, digits, dashes and dots`);
+    if (/^\s+-\s/m.test(e.text)) say("write lists on one line, like triggers: [aim, target]");
+    if (seen.has(e.name)) say(`name ${e.name} is used twice`);
+    seen.add(e.name);
+    const loc = join(root, e.location ?? "");
+    if (!e.location || !existsSync(loc)) { say(`location ${e.location} not found`); continue; }
+    const near = statSync(loc).isDirectory() ? loc : dirname(loc);
+    if (e.example && !existsSync(join(near, e.example)) && !existsSync(join(root, e.example))) say(`example ${e.example} not found`);
+    const syms = symbolsOf(e.extend_by);
+    if (!syms.length) say("extend_by names no symbol — write names like `AimStrategy`");
+    const code = files.filter((f) => insideLocation(e, f) && !f.endsWith(REGISTRY_SUFFIX))
+      .map((f) => readFileSync(join(root, f), "utf8")).join("\n");
+    for (const s of syms) if (!uses(code, s)) say(`${s} from extend_by is not found in ${e.location}`);
+  }
+  if (problems.length) fail(problems);
+}
+
+function fail(lines) {
+  for (const line of lines) console.log(line);
+  process.exitCode = 1;
+}
+
+const [mode, ...rest] = process.argv.slice(2);
+if (mode === undefined) list();
+else if (mode === "--plan" && rest[0]) checkPlan(resolve(rest[0]), rest.slice(1));
+else if (mode === "--stale") stale();
+else {
+  console.error("usage: registry.mjs [--plan PLAN.md <stub files…> | --stale]");
+  process.exit(2);
+}

package/lib/setup-hook.mjs

@@ -31,6 +31,7 @@ import { homedir } from "node:os";
 //                             and finding, one file per ship, in one folder
 //   edit-check.sh             PostToolUse — line-limit.sh, lint-ratchet.mjs and
 //                             text-rules.mjs on each edited file
+//   registry.mjs              run by /plan-feature and /registry — the *.registry.yaml checks
 
 const GATE_FILENAME = "skill-gate.sh";
 const AUTO_MARK_FILENAME = "skill-gate-automark.sh";
@@ -57,6 +58,7 @@ const SHIP_LOG_PARSE_FILENAME = "ship-log-parse.mjs";
 const SHIP_LOG_REPORT_FILENAME = "ship-log-report.mjs";
 const SHIP_MARK_FILENAME = "ship-mark.sh";
 const SHIP_PREP_FILENAME = "ship-prep.sh";
+const REGISTRY_FILENAMES = ["registry.mjs", "registry-lib.mjs"];
 const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
 const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
 
@@ -166,6 +168,7 @@ export async function setupHook(targetDir = process.cwd()) {
     SHIP_LOG_REPORT_FILENAME,
     SHIP_MARK_FILENAME,
     SHIP_PREP_FILENAME,
+    ...REGISTRY_FILENAMES,
   ]) {
     const dest = join(hooksDir, name);
     await writeFile(dest, await readHookSource(name), { mode: 0o755 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.58.0",
+  "version": "2.59.0",
   "description": "Guardrails for Claude Code — best-practice skills, planning commands, and delivery gates.",
   "type": "module",
   "repository": {
@@ -11,7 +11,7 @@
     "claude-skills": "bin/cli.mjs"
   },
   "scripts": {
-    "prepack": "cp ../README.md README.md && mkdir -p hooks && cp ../scripts/skill-gate.sh ../scripts/skill-gate-automark.sh ../scripts/skill-application-gate.sh ../scripts/gauntlet.sh ../scripts/ship-gate.sh ../scripts/gate-config.sh ../scripts/ship-gate-projects.sh ../scripts/ship-gate-structure.sh ../scripts/ship-gate-files.sh ../scripts/ship-gate-hook.sh ../scripts/version-check.sh ../scripts/skill-flags-record.sh ../scripts/skill-report.mjs ../scripts/edit-check.sh ../scripts/line-limit.sh ../scripts/lint-ratchet.mjs ../scripts/text-rules.mjs ../scripts/ratchet-baseline.mjs ../scripts/diary-check.mjs ../scripts/diary-lib.mjs ../scripts/ship-log.mjs ../scripts/ship-log-parse.mjs ../scripts/ship-log-report.mjs ../scripts/ship-mark.sh ../scripts/ship-prep.sh hooks/",
+    "prepack": "cp ../README.md README.md && mkdir -p hooks && cp ../scripts/skill-gate.sh ../scripts/skill-gate-automark.sh ../scripts/skill-application-gate.sh ../scripts/gauntlet.sh ../scripts/ship-gate.sh ../scripts/gate-config.sh ../scripts/ship-gate-projects.sh ../scripts/ship-gate-structure.sh ../scripts/ship-gate-files.sh ../scripts/ship-gate-hook.sh ../scripts/version-check.sh ../scripts/skill-flags-record.sh ../scripts/skill-report.mjs ../scripts/edit-check.sh ../scripts/line-limit.sh ../scripts/lint-ratchet.mjs ../scripts/text-rules.mjs ../scripts/ratchet-baseline.mjs ../scripts/diary-check.mjs ../scripts/diary-lib.mjs ../scripts/ship-log.mjs ../scripts/ship-log-parse.mjs ../scripts/ship-log-report.mjs ../scripts/ship-mark.sh ../scripts/ship-prep.sh ../scripts/registry.mjs ../scripts/registry-lib.mjs hooks/",
     "postpack": "git checkout -- README.md && rm -rf hooks"
   },
   "engines": {