swe-workflow-skills 0.4.0 → 0.5.0

package/README.md

@@ -1,5 +1,6 @@
 # SWE Workflow Skills for Claude Code
 
+[![npm](https://img.shields.io/npm/v/swe-workflow-skills)](https://www.npmjs.com/package/swe-workflow-skills)
 [![roles-check](https://github.com/SWEStash/swe-workflow-skills/actions/workflows/roles-check.yml/badge.svg)](https://github.com/SWEStash/swe-workflow-skills/actions/workflows/roles-check.yml)
 ![skills](https://img.shields.io/badge/skills-65-blue)
 [![license: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
@@ -59,12 +60,28 @@ web, claude.ai chat, and Cowork):
 /plugin install swe-workflow-pm@swe-workflow
 ```
 
-**Want the whole library with the orchestrator** (CLI) — no clone needed:
+**Want the whole library with the orchestrator** (CLI) — no clone needed. This is a
+**two-step** setup:
 
 ```bash
-npx swe-workflow-skills install --global   # all 65 skills + router + /role + the SessionStart hook
+# 1. Install all 65 skills + router + /role + the hook script, and apply the baseline
+npx swe-workflow-skills install --global
 ```
 
+```jsonc
+// 2. Wire the hook: merge the snippet the installer prints into your settings.json
+//    (the installer never edits settings.json for you — it just prints the block).
+//    Then start a new session; /doctor should show the hook registered.
+{ "hooks": { "SessionStart": [ /* ...the printed block... */ ] } }
+```
+
+> ⚠️ **Don't skip step 2.** Step 1 alone installs the skills and prevents cropping, but
+> the hook is what nudges Claude to consult `skill-router` first — **without it, skills
+> won't auto-route** (the whole point of the library) and the baseline isn't re-asserted
+> after `/compact`. If you deliberately want no hook, pass `--no-hook`; auto-routing stays
+> off until a hook is wired. The **per-role plugin** path above needs no hook — it's
+> self-contained.
+
 Or from a clone: `node install.mjs --global`.
 
 > **Prerequisite:** Node.js ≥ 18 (already present wherever Claude Code runs).
@@ -97,7 +114,9 @@ for every method × surface, and **[ROLES.md](docs/ROLES.md)** for the activatio
 On any non-trivial task, Claude consults **`skill-router`** first; it reads the full
 catalog and invokes the matching skill(s) by name, re-routing as the work changes phase.
 The default SessionStart hook nudges Claude to do this automatically; you can also route
-explicitly ("use the security-audit skill") or switch the promoted set with `/role`.
+explicitly ("use the security-audit skill") or switch the promoted set with `/role`. Don't
+want a particular skill routed at all? `npx swe-workflow-skills disable <skill>` opts it out
+durably — see [disable a skill from routing](docs/ROLES.md#advanced-disable-a-skill-from-routing).
 
 **A routed chain, by phase** — e.g. *"add OAuth login"*:
 

package/VERSION

@@ -1 +1 @@
-0.4.0
+0.5.0

package/bin/cli.mjs

@@ -5,6 +5,9 @@
 //
 //   npx swe-workflow-skills install [--global|--dir DIR|--role R|--no-hook|...]
 //   npx swe-workflow-skills uninstall [--global|--dir DIR|--dry-run|--yes]
+//   npx swe-workflow-skills disable <skill> [--off] [--global | --dir DIR]
+//   npx swe-workflow-skills enable  <skill> [--global | --dir DIR]
+//   npx swe-workflow-skills list-disabled   [--global | --dir DIR]
 
 import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
@@ -17,21 +20,34 @@ const [sub, ...rest] = process.argv.slice(2);
 const HELP = `swe-workflow-skills <command> [options]
 
 Commands:
-  install      Install skills into a Claude config dir (passes flags to install.mjs)
-  uninstall    Remove the library (passes flags to uninstall.mjs)
+  install         Install skills into a Claude config dir (passes flags to install.mjs)
+  uninstall       Remove the library (passes flags to uninstall.mjs)
+  disable <skill> Opt a skill out of routing/auto-trigger (advanced; --off to fully hide)
+  enable  <skill> Re-enable a previously disabled skill
+  list-disabled   List skills currently disabled
 
 Examples:
   npx swe-workflow-skills install --global
   npx swe-workflow-skills install --role pm
   npx swe-workflow-skills uninstall --global --dry-run
+  npx swe-workflow-skills disable data-modeling --global
+  npx swe-workflow-skills enable data-modeling --global
 
 Run a command with --help to see its full option list.`;
 
+// disable/enable/list-disabled all run through disable.mjs; map the CLI verb to
+// the action positional it expects (list-disabled -> list).
+const DISABLE_ACTIONS = { disable: "disable", enable: "enable", "list-disabled": "list" };
+
 if (sub === "install" || sub === "uninstall") {
   const script = join(ROOT, sub === "install" ? "install.mjs" : "uninstall.mjs");
   // stdio inherited so install output and uninstall's confirm prompt pass through.
   const res = spawnSync(process.execPath, [script, ...rest], { stdio: "inherit" });
   process.exit(res.status ?? 1);
+} else if (sub in DISABLE_ACTIONS) {
+  const script = join(ROOT, "disable.mjs");
+  const res = spawnSync(process.execPath, [script, DISABLE_ACTIONS[sub], ...rest], { stdio: "inherit" });
+  process.exit(res.status ?? 1);
 } else if (sub === "-v" || sub === "--version" || sub === "version") {
   process.stdout.write(readFileSync(join(ROOT, "VERSION"), "utf-8"));
   process.exit(0);

package/disable.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+// Disable / enable a single skill from routing and auto-trigger, durably.
+//
+// The library installs a name-only baseline: skills don't auto-trigger, they're
+// invoked by the skill-router. Disabling goes one step further — it hides a skill
+// from the router too, for users who don't want the whole corpus routed. This is
+// an ADVANCED opt-out of the routed SWE-methodology; most people don't need it.
+//
+// Why a command (not a manual settings edit): the SessionStart hook re-writes
+// every installed skill's skillOverrides entry each session, so a hand edit is
+// reverted. This records the choice in a `.disabled-skills` marker beside the
+// skills, which the hook folds into the baseline every time — so it persists.
+//
+// Runs on Linux, macOS, and Windows using only Node.
+//
+//   node disable.mjs disable <skill>          # -> user-invocable-only (default)
+//   node disable.mjs disable <skill> --off    # -> off (fully hidden)
+//   node disable.mjs enable  <skill>          # re-enable (back to the baseline)
+//   node disable.mjs list                     # show disabled skills
+//   node disable.mjs disable <skill> --global # target the user config dir
+
+import { existsSync, statSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import {
+  loadRoles,
+  applyBaseline,
+  installedSkills,
+  readDisabled,
+  writeDisabled,
+  DEFAULT_DISABLE_STATE,
+} from "./scripts/resolve.mjs";
+
+// Exit cleanly when stdout is closed early (e.g. piped to `head`/`grep`) instead
+// of throwing an EPIPE stack trace.
+process.stdout.on("error", (e) => {
+  if (e && e.code === "EPIPE") process.exit(0);
+  throw e;
+});
+
+const REPO_ROOT = dirname(fileURLToPath(import.meta.url));
+
+const USAGE = `Usage: disable.mjs <disable|enable|list> [skill] [options]
+
+Disable or re-enable a skill from routing/auto-trigger (advanced opt-out).
+
+Actions:
+  disable <skill>   Hide <skill> from the router. Default state: user-invocable-only
+                    (you can still run it manually as /<skill>). Add --off to hide
+                    it entirely (not even user-invocable).
+  enable  <skill>   Re-enable <skill> (return it to the name-only baseline).
+  list              List currently disabled skills.
+
+Options:
+  --off          With 'disable': set state to "off" instead of user-invocable-only
+  -g, --global   Target the user config dir: $CLAUDE_CONFIG_DIR if set, else
+                 ~/.claude/ (default without this flag: ./.claude/)
+  -d, --dir DIR  Target a custom Claude config directory DIR
+  -h, --help     Show this help`;
+
+function isDir(p) {
+  return existsSync(p) && statSync(p).isDirectory();
+}
+function fatal(msg) {
+  process.stderr.write(`Error: ${msg}\n`);
+  process.exit(1);
+}
+function log(msg) {
+  process.stdout.write(msg + "\n");
+}
+function expandTilde(p) {
+  if (p === "~" || p.startsWith("~/") || p.startsWith("~\\")) return homedir() + p.slice(1);
+  return p;
+}
+
+// ---- arg parsing -----------------------------------------------------------
+
+let global = false;
+let off = false;
+let configDir = "";
+const positional = [];
+
+const argv = process.argv.slice(2);
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === "-g" || a === "--global") global = true;
+  else if (a === "--off") off = true;
+  else if (a === "-d" || a === "--dir") {
+    configDir = argv[++i];
+    if (configDir === undefined) fatal("--dir requires a path");
+  } else if (a.startsWith("--dir=")) configDir = a.slice("--dir=".length);
+  else if (a === "-h" || a === "--help") {
+    log(USAGE);
+    process.exit(0);
+  } else if (a.startsWith("-")) {
+    process.stderr.write(`Unknown option: ${a}\n${USAGE}\n`);
+    process.exit(1);
+  } else positional.push(a);
+}
+
+const action = positional[0];
+const skill = positional[1];
+if (!action || !["disable", "enable", "list"].includes(action)) {
+  process.stderr.write(`${USAGE}\n`);
+  process.exit(1);
+}
+if ((action === "disable" || action === "enable") && !skill) {
+  fatal(`'${action}' requires a <skill> name`);
+}
+// Reject path-like / malformed names before any filesystem use.
+if (skill && !/^[a-z0-9][a-z0-9-]*$/.test(skill)) {
+  fatal(`invalid skill name '${skill}' (expected lowercase letters, digits, hyphens)`);
+}
+
+let claudeDir;
+if (configDir) {
+  if (global) fatal("--dir and --global are mutually exclusive");
+  claudeDir = resolve(expandTilde(configDir));
+} else if (global) {
+  claudeDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+} else {
+  claudeDir = join(process.cwd(), ".claude");
+}
+const dest = join(claudeDir, "skills");
+const settingsLocal = join(claudeDir, "settings.local.json");
+
+if (!isDir(dest)) fatal(`no skills found at ${dest} (is the library installed there? try --global or --dir)`);
+
+// Roles data: prefer the installed marker beside the skills, else the repo copy.
+function loadRolesData() {
+  for (const p of [join(dest, ".roles.json"), join(REPO_ROOT, "roles.json")]) {
+    if (existsSync(p)) return loadRoles(p);
+  }
+  return null;
+}
+
+// Active role, so re-applying the baseline preserves the user's promoted set.
+function activeRole(data) {
+  const f = join(dest, ".active-role");
+  if (!existsSync(f)) return null;
+  try {
+    const r = readFileSync(f, "utf-8").replace(/\s+/g, "");
+    return r && data && data.roles && r in data.roles ? r : null;
+  } catch {
+    return null;
+  }
+}
+
+// Re-assert the baseline now so the change hot-reloads in the current session
+// (like /role), instead of waiting for the next session boundary.
+function reapply() {
+  const data = loadRolesData();
+  if (!data) return; // no roles data (partial/plugin install): marker still written
+  try {
+    applyBaseline(data, settingsLocal, dest, activeRole(data));
+  } catch (e) {
+    process.stderr.write(`Warning: wrote the marker but could not re-apply the baseline (${e.message}).\n`);
+    process.stderr.write("It will take effect at the next session start.\n");
+  }
+}
+
+// ---- actions ---------------------------------------------------------------
+
+const disabled = readDisabled(dest);
+
+if (action === "list") {
+  if (disabled.size === 0) {
+    log("No skills are disabled.");
+  } else {
+    log("Disabled skills:");
+    for (const name of [...disabled.keys()].sort()) log(`  ${name}  (${disabled.get(name)})`);
+  }
+  process.exit(0);
+}
+
+const data = loadRolesData();
+const installed = new Set(installedSkills(dest));
+
+if (action === "disable") {
+  if (!installed.has(skill)) fatal(`unknown skill '${skill}' — not installed at ${dest}`);
+  const state = off ? "off" : DEFAULT_DISABLE_STATE;
+  disabled.set(skill, state);
+  writeDisabled(dest, disabled);
+  reapply();
+  log(`Disabled '${skill}' -> ${state}.`);
+  if (state === DEFAULT_DISABLE_STATE) {
+    log(`The router will no longer invoke it; you can still run it manually as /${skill}.`);
+  } else {
+    log("It is now fully hidden (not routable and not user-invocable).");
+  }
+  if (data && Array.isArray(data.pinned) && data.pinned.includes(skill)) {
+    log(`Note: '${skill}' is a pinned safety skill — disabling it opts out of that guardrail.`);
+  }
+  log("This persists across sessions (the hook re-asserts it). Re-enable with:");
+  log(`  node disable.mjs enable ${skill}${global ? " --global" : ""}`);
+} else {
+  // enable
+  if (!disabled.has(skill)) {
+    log(`'${skill}' is not disabled — nothing to do.`);
+    process.exit(0);
+  }
+  disabled.delete(skill);
+  writeDisabled(dest, disabled);
+  reapply();
+  log(`Enabled '${skill}' — back to the name-only baseline (routable again).`);
+}

package/install.mjs

@@ -369,14 +369,22 @@ if (hook) {
     hookPath = join(hookDestDir, "session-start.mjs");
     log(`Installed hook script -> ${hookPath}`);
     log("");
-    log("The name-only baseline is already applied. To have it re-asserted every");
-    log("session (and the router nudge injected), merge this into");
-    log(`${join(claudeDir, "settings.json")} (the installer does NOT edit settings for you):`);
+    log("========================================================================");
+    log("REQUIRED NEXT STEP — wire the router hook");
+    log("========================================================================");
+    log("Skills are installed and the name-only baseline is applied, so nothing");
+    log("will crop. But WITHOUT this step Claude won't be nudged to consult");
+    log("skill-router first, so skills won't auto-route — you lose the whole point");
+    log("of the library. The hook also re-asserts the baseline after /compact.");
+    log("");
+    log(`Merge this into ${join(claudeDir, "settings.json")}`);
+    log("(for your safety the installer does NOT edit settings.json for you):");
     log("");
     log(hookSnippet(hookPath));
     log("");
-    log("Start a new session and run /doctor to confirm the hook is registered.");
-    log("(Prefer no hook? Re-run with --no-hook; the baseline still applies.)");
+    log("Then start a new session and run /doctor to confirm the hook is registered.");
+    log("(Deliberately not using the hook? Re-run with --no-hook; the baseline still");
+    log(" applies, but auto-routing stays off until you wire a hook.)");
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swe-workflow-skills",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A curated library of Claude Code Agent Skills covering the full software lifecycle, with orchestrator-routed activation that scales past the skill-listing budget.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "bin/cli.mjs",
     "install.mjs",
     "uninstall.mjs",
+    "disable.mjs",
     "scripts/resolve.mjs",
     "hooks/session-start.mjs",
     "commands/role.md",

package/scripts/resolve.mjs

@@ -28,7 +28,7 @@
 //
 // roles.json is read from $ROLES_JSON if set, else ../roles.json relative to this file.
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, readdirSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, readdirSync, rmSync } from "node:fs";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -88,6 +88,73 @@ export function installedSkills(skillsDir) {
     .sort();
 }
 
+// ---- disabled-skills marker ------------------------------------------------
+//
+// Lets a user opt a skill OUT of routing/auto-trigger and have it *survive* the
+// SessionStart hook. A plain settings.local.json edit can't: applyBaseline owns
+// every installed skill's entry and rewrites it each session. Instead the choice
+// lives in a `.disabled-skills` marker beside the skills (like `.active-role`),
+// which applyBaseline folds in on every write — so the hook re-asserts the
+// disable rather than reverting it.
+//
+// Format: one skill per line, optional state after whitespace; `#` comments and
+// blank lines ignored. Valid states are the two that hide a skill from the model:
+//   data-modeling                 -> user-invocable-only (default; human /name still works)
+//   data-modeling off             -> off (fully hidden)
+
+export const DISABLE_STATES = new Set(["user-invocable-only", "off"]);
+export const DEFAULT_DISABLE_STATE = "user-invocable-only";
+
+export function disabledMarkerPath(skillsDir) {
+  return join(skillsDir, ".disabled-skills");
+}
+
+// Parse the marker into Map<skill, state>. Best-effort: a missing or unreadable
+// file yields an empty map (never throws — the hook must not fail on it).
+export function readDisabled(skillsDir) {
+  const path = disabledMarkerPath(skillsDir);
+  const map = new Map();
+  if (!(existsSync(path) && statSync(path).isFile())) return map;
+  let text = "";
+  try {
+    text = readFileSync(path, "utf-8");
+  } catch {
+    return map;
+  }
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const [name, state] = line.split(/\s+/);
+    if (!name) continue;
+    map.set(name, DISABLE_STATES.has(state) ? state : DEFAULT_DISABLE_STATE);
+  }
+  return map;
+}
+
+// Same, but restricted to skills actually installed here (stale names dropped).
+export function loadDisabled(skillsDir) {
+  const installed = new Set(installedSkills(skillsDir));
+  const map = new Map();
+  for (const [name, state] of readDisabled(skillsDir)) {
+    if (installed.has(name)) map.set(name, state);
+  }
+  return map;
+}
+
+// Persist Map<skill, state>, sorted. Removes the marker entirely when empty so an
+// enabled-everything state leaves no file behind (mirrors pruneSettings dropping
+// an empty skillOverrides).
+export function writeDisabled(skillsDir, map) {
+  const path = disabledMarkerPath(skillsDir);
+  const names = [...map.keys()].sort();
+  if (names.length === 0) {
+    if (existsSync(path)) rmSync(path);
+    return;
+  }
+  const lines = names.map((n) => (map.get(n) === DEFAULT_DISABLE_STATE ? n : `${n} ${map.get(n)}`));
+  writeFileSync(path, lines.join("\n") + "\n");
+}
+
 // ---- settings I/O ----------------------------------------------------------
 
 // Recursively sort object keys so output is deterministic (mirrors Python's
@@ -143,11 +210,19 @@ export function applyBaseline(data, settingsPath, skillsDir, role) {
   const merged = {};
   for (const [k, v] of Object.entries(existing)) if (!installedSet.has(k)) merged[k] = v;
   Object.assign(merged, desired);
+
+  // User-disabled skills override the baseline: an explicit opt-out wins over
+  // name-only AND over a pinned/role-promoted "on" (a pinned skill the user
+  // disabled becomes user-invocable-only, not on). Read from the marker each
+  // call so the hook re-asserts the disable instead of reverting it.
+  const disabled = loadDisabled(skillsDir);
+  for (const [s, state] of disabled) merged[s] = state;
+
   settings.skillOverrides = merged;
 
   writeSettings(settingsPath, settings);
   const nameOnly = Object.keys(desired).length;
-  return { nameOnly, on: installed.length - nameOnly, role };
+  return { nameOnly, on: installed.length - nameOnly, role, disabled: disabled.size };
 }
 
 // Remove the given skills from a settings file's skillOverrides. Returns removed count.

package/uninstall.mjs

@@ -127,6 +127,7 @@ for (const f of [
   join(dest, ".roles.json"),
   join(dest, ".catalog.json"),
   join(dest, ".active-role"),
+  join(dest, ".disabled-skills"),
   join(dest, ".swe-workflow-manifest.json"),
   join(claudeDir, "hooks", "resolve.mjs"),
   join(claudeDir, "hooks", "session-start.mjs"),