skilldrop-cli 0.3.0 → 0.4.0

package/README.md

@@ -256,6 +256,17 @@ npx skilldrop-cli list | skilldrop info <skill> | skilldrop packs | skilldrop un
 
 `--with-related` also pulls each skill's companions. From a clone (or before the package is published): `node bin/skilldrop.js <same args>`. Scope and design: [RFC-0002](docs/rfcs/0002-skilldrop-cli.md), full command surface in [`docs/designs/skilldrop-cli-design.md`](docs/designs/skilldrop-cli-design.md).
 
+### Hooks (opt-in) — wire a skill to an event
+
+Some loop-shaped skills declare **hooks** — event-triggered nudges the CLI wires into your environment when you pass `--with-hooks` ([RFC-0006](docs/rfcs/0006-per-ide-hooks.md)). It's off by default, so a plain install never touches your git repo or editor settings.
+
+```bash
+npx skilldrop-cli install devils-advocate --with-hooks --project
+# → appends a marker-fenced reminder to .git/hooks/pre-commit: "run /devils-advocate on staged changes"
+```
+
+The CLI emits per target and **degrades gracefully** — a `pre-commit-review` hook becomes an IDE-agnostic git hook (needs a git repo); a `session-start` hook becomes a Claude Code `settings.json` entry, and is cleanly skipped where the target has no equivalent (Cursor, Kiro, plain `--dest`), printing what it did and where. Hooks are reminders/context, not autonomous execution — skilldrop skills are agent instructions, so the hook prompts *you* to run the review, it doesn't silently run an AI pass. `skilldrop uninstall` removes any hook artifacts it wrote. Vocabulary and the per-target mapping are in the RFC.
+
 ### Third-party catalogs — publish your own skills through the same CLI
 
 Any git repo or directory shaped like this one is a **catalog**: `skills/<name>/` folders each holding `SKILL.md` + `manifest.json`, optionally a root `packs.json`. That's the whole contract ([RFC-0003](docs/rfcs/0003-third-party-catalogs.md)):

package/bin/skilldrop.js

@@ -15,6 +15,8 @@ const { execFileSync } = require("child_process");
 const ROOT = path.resolve(__dirname, "..");
 const LEDGER = ".skilldrop.json";
 const BUNDLED = "bundled";
+// Neutral hook vocabulary (RFC-0006). Kept in sync with validate.py's HOOK_EVENTS.
+const HOOK_EVENTS = ["session-start", "pre-commit-review", "on-demand"];
 
 const HELP = `skilldrop — portable AI-agent skills for Claude Code, Cursor, Kiro, and more
 
@@ -44,6 +46,10 @@ Install/update/uninstall targets (pick one):
 
 Options:
   --with-related     also install each skill's related companions (one level)
+  --with-hooks       also wire any hooks a skill declares (RFC-0006) — git pre-commit
+                     reminders and Claude Code session-start context; degrades where the
+                     target has no hook mechanism. Off by default so installs never touch
+                     your git repo or settings unasked.
 `;
 
 function die(msg) { console.error("error: " + msg); process.exit(1); }
@@ -163,6 +169,106 @@ function writeWiring(ide, dest, s, desc) {
     fs.writeFileSync(p, `When the user requests the following, defer to the instructions in .kiro/skills/${s}/SKILL.md:\n\n${desc}\n`);
 }
 
+/* ---------- hooks (RFC-0006: emit per target, degrade where unsupported) ---------- */
+
+function gitRoot(startDir) {
+  let d = path.resolve(startDir);
+  for (;;) {
+    if (fs.existsSync(path.join(d, ".git"))) return d;
+    const up = path.dirname(d);
+    if (up === d) return null;
+    d = up;
+  }
+}
+
+// Append an idempotent, marker-fenced reminder to .git/hooks/pre-commit. IDE-agnostic.
+function writeGitPreCommitHook(root, skill, hook) {
+  const p = path.join(root, ".git", "hooks", "pre-commit");
+  const marker = `skilldrop-hook:${skill}:pre-commit-review`;
+  let body = fs.existsSync(p) ? fs.readFileSync(p, "utf8") : "";
+  if (!body.startsWith("#!")) body = "#!/bin/sh\n" + body;
+  if (body.includes(marker)) return p; // already wired
+  const line = `echo "skilldrop: run /${hook.action} on your staged changes before committing — ${hook.description}"`;
+  body += `\n# >>> ${marker} >>>\n${line}\n# <<< ${marker} <<<\n`;
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, body);
+  fs.chmodSync(p, 0o755);
+  return p;
+}
+
+// Merge a SessionStart command into Claude Code settings.json. Returns the path,
+// or null if the file exists but is malformed (we never clobber unparseable JSON).
+function writeClaudeSessionHook(settingsPath, skill, hook) {
+  let data = {};
+  if (fs.existsSync(settingsPath)) {
+    try { data = JSON.parse(fs.readFileSync(settingsPath, "utf8")); }
+    catch (e) { return null; }
+  }
+  data.hooks = data.hooks || {};
+  data.hooks.SessionStart = data.hooks.SessionStart || [];
+  const marker = `skilldrop-hook:${skill}:session-start`;
+  if (!JSON.stringify(data.hooks.SessionStart).includes(marker)) {
+    const cmd = `echo "skilldrop: /${hook.action} is available — ${hook.description}" # ${marker}`;
+    data.hooks.SessionStart.push({ hooks: [{ type: "command", command: cmd }] });
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(data, null, 2) + "\n");
+  }
+  return settingsPath;
+}
+
+// Wire one skill's declared hooks; returns human-readable status lines.
+function emitHooks(cat, skill, dest, ide) {
+  let hooks = [];
+  try { hooks = manifestOf(cat, skill).hooks || []; } catch (e) { return []; }
+  const lines = [];
+  for (const h of hooks) {
+    if (h.event === "pre-commit-review") {
+      const root = gitRoot(process.cwd());
+      if (root) lines.push(`  ${skill}: pre-commit reminder -> ${path.join(root, ".git/hooks/pre-commit")}`);
+      else lines.push(`  ${skill}: pre-commit-review skipped — no git repo at ${process.cwd()}`);
+      if (root) writeGitPreCommitHook(root, skill, h);
+    } else if (h.event === "session-start") {
+      if (ide === "claude") {
+        const sp = path.join(path.dirname(dest), "settings.json");
+        const written = writeClaudeSessionHook(sp, skill, h);
+        lines.push(written ? `  ${skill}: session-start context -> ${sp}`
+                           : `  ${skill}: session-start skipped — ${sp} is not valid JSON`);
+      } else {
+        lines.push(`  ${skill}: session-start skipped — no hook mechanism for ${ide}`);
+      }
+    } else if (h.event === "on-demand") {
+      lines.push(`  ${skill}: on-demand — invoke /${h.action} manually (no artifact needed)`);
+    }
+  }
+  return lines;
+}
+
+function removeHooksFor(skill, dest, ide) {
+  const root = gitRoot(process.cwd());
+  if (root) {
+    const p = path.join(root, ".git", "hooks", "pre-commit");
+    if (fs.existsSync(p)) {
+      const body = fs.readFileSync(p, "utf8");
+      const re = new RegExp(`\\n?# >>> skilldrop-hook:${skill}:[^\\n]* >>>[\\s\\S]*?# <<< skilldrop-hook:${skill}:[^\\n]* <<<\\n?`, "g");
+      const next = body.replace(re, "\n");
+      if (next !== body) fs.writeFileSync(p, next);
+    }
+  }
+  if (ide === "claude") {
+    const sp = path.join(path.dirname(dest), "settings.json");
+    if (fs.existsSync(sp)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(sp, "utf8"));
+        const arr = data.hooks && data.hooks.SessionStart;
+        if (Array.isArray(arr)) {
+          const kept = arr.filter((e) => !JSON.stringify(e).includes(`skilldrop-hook:${skill}:`));
+          if (kept.length !== arr.length) { data.hooks.SessionStart = kept; fs.writeFileSync(sp, JSON.stringify(data, null, 2) + "\n"); }
+        }
+      } catch (e) { /* leave malformed settings untouched */ }
+    }
+  }
+}
+
 /* ---------- commands ---------- */
 
 function expandNames(args, cat) {
@@ -211,6 +317,18 @@ function install(args) {
   }
   saveLedger(l);
   console.log(`\n${names.length} skill(s) installed (${ide}).`);
+
+  const withHooks = names.filter((s) => { try { return (manifestOf(cat, s).hooks || []).length; } catch (e) { return false; } });
+  if (withHooks.length && args.flags["with-hooks"]) {
+    const lines = withHooks.flatMap((s) => emitHooks(cat, s, dest, ide));
+    console.log(`\nHooks wired (RFC-0006):\n${lines.join("\n")}`);
+    if (cat.source !== BUNDLED)
+      console.log(`  NOTE: these hooks run commands from third-party catalog '${cat.source}' — read them before trusting them.`);
+    console.log(`  Undo any of these with: skilldrop uninstall <skill> ${ide === "claude" ? "" : "--ide " + ide}`.trimEnd());
+  } else if (withHooks.length) {
+    console.log(`\n${withHooks.join(", ")} declare hooks — re-run with --with-hooks to wire them (git pre-commit reminders / session-start context).`);
+  }
+
   if (cat.source !== BUNDLED)
     console.log(`\nWARNING: third-party catalog '${cat.source}'. Skills are instructions your AI agent will follow — review each installed SKILL.md under ${dest} before first use. Install copied files only; nothing was executed.`);
   if (ide === "generic")
@@ -269,6 +387,7 @@ function uninstall(args) {
     fs.rmSync(path.join(dest, s), { recursive: true, force: true });
     const w = wiringPath(ide, dest, s);
     if (w) fs.rmSync(w, { force: true });
+    removeHooksFor(s, dest, ide);
     delete l.data[s];
     console.log(`removed ${s} from ${dest}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Portable AI-agent skills for the deliverables knowledge workers ship — diagrams, ADRs, PRDs, runbooks, decks, reviews — installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "bin": {
     "skilldrop": "bin/skilldrop.js"

package/skills/devils-advocate/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["design-doc", "doc-critique"],
+  "hooks": [
+    { "event": "pre-commit-review", "action": "devils-advocate", "description": "adversarially review staged changes before they land" }
+  ],
   "tags": ["review", "code-review", "adversarial", "edge-cases", "future-proofing", "test-coverage", "dev-workflow"],
   "model": { "tier": "heavy", "rationale": "Adversarial code review across four lenses. Cheaper models miss edge cases and under-call severity. Never downgrade." }
 }