swe-workflow-skills 0.1.0

package/install.mjs

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+// Install Claude Code skills from this repo. Runs on Linux, macOS, and Windows
+// using only the Node that Claude Code already requires (no bash / python / sed).
+//
+//   node install.mjs                 # all skills + machinery + hook -> ./.claude/
+//   node install.mjs --global        # ...to the user config dir
+//   node install.mjs --role pm       # just the PM subset
+//   node install.mjs --help          # full usage
+
+import {
+  existsSync,
+  mkdirSync,
+  rmSync,
+  cpSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  statSync,
+  chmodSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import {
+  loadRoles,
+  resolvedSkills,
+  applyBaseline,
+} from "./scripts/resolve.mjs";
+
+const REPO_ROOT = dirname(fileURLToPath(import.meta.url));
+const SKILLS_DIR = join(REPO_ROOT, "skills");
+const RESOLVE_SRC = join(REPO_ROOT, "scripts", "resolve.mjs");
+
+if (!isDir(SKILLS_DIR)) {
+  fatal("must be run from the swe-workflow-skills repo root");
+}
+
+const USAGE = `Usage: install.mjs [options] [skill1 skill2 ...]
+
+Install Claude Code skills from this repo. By default installs ALL skills with a
+name-only activation baseline (only the skill-router orchestrator + safety skills
+auto-trigger; the rest are invoked on demand). Scope to a role at runtime with the
+/role command, or install a hard subset with --role.
+
+Options:
+  -g, --global     Install to the user config dir: $CLAUDE_CONFIG_DIR if set,
+                   else ~/.claude/ (default without this flag: ./.claude/)
+  -d, --dir DIR    Install to a custom Claude config directory DIR
+                   (mutually exclusive with --global)
+  -r, --role ROLE  Install only one role's skills (a lean, hard subset; see
+                   --list for roles). Without it, all skills are installed.
+  -p, --prune      After installing the selected set, remove previously-installed
+                   library skills that are NOT in the new selection (never touches
+                   your own custom skills). Use to narrow a prior all-skills install.
+  -k, --hook       (default) Install the SessionStart hook that re-asserts the
+                   name-only baseline each session + injects the router nudge
+                   (prints the settings snippet; never edits settings)
+      --no-hook    Skip the SessionStart hook. The name-only baseline is still
+                   applied at install time (persists in settings.local.json).
+  -l, --list       List available skills and roles
+  -h, --help       Show this help
+
+Arguments:
+  skill names      Install specific skills only (advanced; skips the role/
+                   orchestrator machinery unless skill-router is included)
+
+Examples:
+  install.mjs                          # all skills + machinery + hook -> ./.claude/
+  install.mjs --global                  # all skills + hook, to the user config dir
+  install.mjs --global --no-hook        # ...baseline applied, but no hook installed
+  install.mjs --role pm                 # just the PM subset
+  install.mjs --role pm --prune         # PM subset; drop other library skills
+  install.mjs --dir /etc/claude         # all skills to /etc/claude/
+  install.mjs feature-planning          # one skill, no machinery`;
+
+function isDir(p) {
+  return existsSync(p) && statSync(p).isDirectory();
+}
+function fatal(msg) {
+  process.stderr.write(`Error: ${msg}\n`);
+  process.exit(1);
+}
+function warn(msg) {
+  process.stderr.write(`Warning: ${msg}\n`);
+}
+function log(msg) {
+  process.stdout.write(msg + "\n");
+}
+function listSkillDirs() {
+  return readdirSync(SKILLS_DIR)
+    .filter((e) => isDir(join(SKILLS_DIR, e)))
+    .sort();
+}
+// Expand a leading ~ the way the bash installer did (manual, not shell-dependent).
+function expandTilde(p) {
+  if (p === "~" || p.startsWith("~/") || p.startsWith("~\\")) return homedir() + p.slice(1);
+  return p;
+}
+// Forward-slash form of a path (no-op on POSIX). Node accepts "/" on Windows too.
+function toPosix(p) {
+  return p.replaceAll("\\", "/");
+}
+
+// ---- arg parsing -----------------------------------------------------------
+
+let global = false;
+let hook = true;
+let prune = false;
+let configDir = "";
+let role = "";
+const selected = [];
+
+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 === "-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 === "-a" || a === "--all") {
+    /* accepted for back-compat; installing all is the default */
+  } else if (a === "-r" || a === "--role") {
+    role = argv[++i];
+    if (role === undefined) fatal("--role requires a role name");
+  } else if (a.startsWith("--role=")) role = a.slice("--role=".length);
+  else if (a === "-p" || a === "--prune") prune = true;
+  else if (a === "-k" || a === "--hook") hook = true;
+  else if (a === "--no-hook") hook = false;
+  else if (a === "-l" || a === "--list") {
+    log("Available skills:");
+    for (const s of listSkillDirs()) log("  " + s);
+    log("");
+    log("Roles (--role, or /role at runtime):");
+    try {
+      const data = loadRoles(join(REPO_ROOT, "roles.json"));
+      for (const [key, r] of Object.entries(data.roles || {})) log(`  ${key}\t${r.label || key}`);
+    } catch {
+      log("  (could not read roles.json)");
+    }
+    process.exit(0);
+  } 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 selected.push(a);
+}
+
+// Load + validate the role early (mirrors the bash `label` precheck).
+let rolesData = null;
+try {
+  rolesData = loadRoles(join(REPO_ROOT, "roles.json"));
+} catch {
+  rolesData = null;
+}
+if (role) {
+  if (!rolesData || !(rolesData.roles && role in rolesData.roles)) {
+    fatal(`unknown role '${role}'. Run 'install.mjs --list' to see roles.`);
+  }
+}
+
+// ---- resolve destination ---------------------------------------------------
+
+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");
+mkdirSync(dest, { recursive: true });
+
+// Resolve the skill set: explicit args > role subset > all (default).
+let skillSet = selected;
+if (skillSet.length === 0) {
+  skillSet = role ? resolvedSkills(rolesData, role) : listSkillDirs();
+}
+
+// ---- copy skills -----------------------------------------------------------
+
+let errors = 0;
+for (const skill of skillSet) {
+  const src = join(SKILLS_DIR, skill);
+  if (!isDir(src)) {
+    process.stderr.write(`Error: unknown skill '${skill}'\n`);
+    errors++;
+    continue;
+  }
+  // Clean copy: drop any prior version first so files removed upstream don't linger.
+  rmSync(join(dest, skill), { recursive: true, force: true });
+  cpSync(src, join(dest, skill), { recursive: true });
+  log(`Installed: ${skill} -> ${join(dest, skill)}`);
+}
+
+// --prune: narrow a prior install to the current selection. Only ever removes skills
+// that exist in our source tree (so the user's own custom skills are never touched).
+if (prune) {
+  const keep = new Set(skillSet);
+  for (const s of listSkillDirs()) {
+    if (!keep.has(s) && isDir(join(dest, s))) {
+      rmSync(join(dest, s), { recursive: true, force: true });
+      log(`Pruned: ${s} (not in selection)`);
+    }
+  }
+}
+
+// ---- orchestrator machinery (only when skill-router is in the set) ---------
+
+const hasRouter = skillSet.includes("skill-router");
+let hookPath = "";
+
+if (hasRouter) {
+  // Catalog + role map alongside the skills, for the orchestrator and resolve.mjs.
+  copyIfExists(join(REPO_ROOT, "roles.json"), join(dest, ".roles.json"));
+  copyIfExists(join(REPO_ROOT, "catalog.json"), join(dest, ".catalog.json"));
+
+  // resolve.mjs is the shared engine for the hook + /role command. Park it next to
+  // where the hook lives.
+  const toolsDir = join(claudeDir, "hooks");
+  mkdirSync(toolsDir, { recursive: true });
+  cpSync(RESOLVE_SRC, join(toolsDir, "resolve.mjs"));
+
+  if (role) {
+    writeFileSync(join(dest, ".active-role"), role + "\n");
+    log(`Wrote role marker -> ${join(dest, ".active-role")} (${role})`);
+  }
+
+  // Install the /role command, substituting absolute paths. The command body runs
+  // through Claude Code's Bash tool (Git Bash on Windows), so substitute forward-slash
+  // paths: Node accepts them on every OS and they avoid backslash-escaping pitfalls in
+  // the shell's double-quoted strings.
+  const cmdSrc = join(REPO_ROOT, "commands", "role.md");
+  if (existsSync(cmdSrc)) {
+    const cmdDestDir = join(claudeDir, "commands");
+    mkdirSync(cmdDestDir, { recursive: true });
+    const filled = readFileSync(cmdSrc, "utf-8")
+      .replaceAll("@@RESOLVE@@", toPosix(join(toolsDir, "resolve.mjs")))
+      .replaceAll("@@SKILLS@@", toPosix(dest))
+      .replaceAll("@@SETTINGS@@", toPosix(join(claudeDir, "settings.local.json")))
+      .replaceAll("@@ROLES@@", toPosix(join(dest, ".roles.json")))
+      .replaceAll("@@ACTIVE_ROLE@@", toPosix(join(dest, ".active-role")));
+    writeFileSync(join(cmdDestDir, "role.md"), filled);
+    log(`Installed /role command -> ${join(cmdDestDir, "role.md")}`);
+  }
+
+  // Apply the name-only baseline now, so a fresh install never overflows the skill
+  // listing (cropping). skillOverrides persists in settings.local.json, so this holds
+  // even before the hook is wired and with --no-hook; the hook just re-asserts it.
+  try {
+    const data = loadRoles(join(dest, ".roles.json"));
+    applyBaseline(data, join(claudeDir, "settings.local.json"), dest, role || null);
+    log(`Applied name-only baseline -> ${join(claudeDir, "settings.local.json")}`);
+  } catch {
+    warn("could not apply the name-only baseline (skills may crop until you run /role).");
+  }
+}
+
+// ---- hook ------------------------------------------------------------------
+
+if (hook) {
+  const hookSrc = join(REPO_ROOT, "hooks", "session-start.mjs");
+  if (!existsSync(hookSrc)) {
+    process.stderr.write(`Error: hook script not found at ${hookSrc}\n`);
+    errors++;
+  } else if (!hasRouter) {
+    warn("--hook needs the orchestrator; install includes no skill-router, skipping hook.");
+  } else {
+    const hookDestDir = join(claudeDir, "hooks");
+    mkdirSync(hookDestDir, { recursive: true });
+    cpSync(hookSrc, join(hookDestDir, "session-start.mjs"));
+    try {
+      chmodSync(join(hookDestDir, "session-start.mjs"), 0o755);
+    } catch {
+      /* chmod is a nicety; the hook is invoked via `node`, not executed directly */
+    }
+    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(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.)");
+  }
+}
+
+if (errors !== 0) process.exit(1);
+
+function copyIfExists(src, destPath) {
+  if (existsSync(src)) cpSync(src, destPath);
+}
+
+// The SessionStart block to merge into settings.json. JSON.stringify keeps the path
+// correctly escaped on every OS (Windows backslashes included).
+function hookSnippet(path) {
+  const block = {
+    hooks: {
+      SessionStart: [
+        {
+          matcher: "startup|resume|clear|compact",
+          hooks: [{ type: "command", command: `node ${JSON.stringify(path)}` }],
+        },
+      ],
+    },
+  };
+  return JSON.stringify(block, null, 2)
+    .split("\n")
+    .map((l) => "  " + l)
+    .join("\n");
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "swe-workflow-skills",
+  "version": "0.1.0",
+  "description": "A curated library of 44 Claude Code Agent Skills for the software lifecycle, with orchestrator-routed activation that scales past the skill-listing budget.",
+  "type": "module",
+  "bin": {
+    "swe-workflow-skills": "bin/cli.mjs"
+  },
+  "files": [
+    "bin/cli.mjs",
+    "install.mjs",
+    "uninstall.mjs",
+    "scripts/resolve.mjs",
+    "hooks/session-start.mjs",
+    "commands/role.md",
+    "skills/",
+    "roles.json",
+    "catalog.json",
+    "VERSION"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "verify": "node scripts/verify.mjs",
+    "prepublishOnly": "npm run verify"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "agent-skills",
+    "skills",
+    "sdlc",
+    "workflow",
+    "orchestrator"
+  ],
+  "license": "MIT",
+  "author": "SWEStash",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SWEStash/swe-workflow-skills.git"
+  },
+  "homepage": "https://github.com/SWEStash/swe-workflow-skills#readme",
+  "bugs": {
+    "url": "https://github.com/SWEStash/swe-workflow-skills/issues"
+  }
+}

package/roles.json

@@ -0,0 +1,194 @@
+{
+  "version": 1,
+  "_comment": "Single source of truth for role-based, window-aware skill activation. Consumed by install.mjs (via scripts/resolve.mjs), scripts/build-plugins.mjs, and skill-router. A role's working set = its core set UNION its skills. 'pinned' skills stay auto-triggerable (skillOverrides: on) regardless of role/window when installed; everything else is gated: on with a 1m window OR when in the active role, else name-only. See docs/ROLES.md.",
+
+  "pinned": [
+    "skill-router",
+    "tdd-workflow",
+    "verification-before-completion",
+    "bug-investigating",
+    "incident-response",
+    "code-reviewing"
+  ],
+
+  "core": {
+    "universal": [
+      "skill-router",
+      "feature-planning"
+    ],
+    "technical": [
+      "skill-router",
+      "feature-planning",
+      "git-workflow",
+      "code-reviewing",
+      "verification-before-completion",
+      "bug-investigating",
+      "project-documentation"
+    ]
+  },
+
+  "meta_only": [
+    "writing-skills"
+  ],
+
+  "roles": {
+    "backend": {
+      "label": "Backend / Full-stack Engineer",
+      "description": "Skills for service, API, and data work: design, test-first implementation, performance, and shipping.",
+      "core": "technical",
+      "skills": [
+        "api-design",
+        "data-modeling",
+        "architecture-design",
+        "tdd-workflow",
+        "test-suite-design",
+        "test-data-strategy",
+        "performance-optimization",
+        "dependency-management",
+        "configuration-strategy",
+        "security-audit",
+        "refactoring",
+        "deployment-checklist"
+      ]
+    },
+    "frontend": {
+      "label": "Frontend Engineer",
+      "description": "Skills for UI/UX, component architecture, accessibility, and client-side performance.",
+      "core": "technical",
+      "skills": [
+        "ui-ux-design",
+        "frontend-architecture",
+        "accessibility-design",
+        "api-design",
+        "tdd-workflow",
+        "test-suite-design",
+        "performance-optimization",
+        "refactoring"
+      ]
+    },
+    "devops": {
+      "label": "DevOps / SRE / Platform Engineer",
+      "description": "Skills for CI/CD, containers, infrastructure-as-code, delivery, observability, and incidents.",
+      "core": "technical",
+      "skills": [
+        "containerization",
+        "cicd-pipeline",
+        "infrastructure-as-code",
+        "deployment-repo",
+        "gitops-delivery",
+        "deployment-checklist",
+        "rollback-strategy",
+        "incident-response",
+        "observability-design",
+        "configuration-strategy",
+        "dependency-impact-analysis"
+      ]
+    },
+    "ml": {
+      "label": "ML Engineer / MLOps",
+      "description": "Skills for ML pipelines, experiment tracking, model deployment, and the data/observability around them.",
+      "core": "technical",
+      "skills": [
+        "ml-pipeline-design",
+        "ml-experiment-tracking",
+        "ml-model-deployment",
+        "data-modeling",
+        "test-data-strategy",
+        "observability-design"
+      ]
+    },
+    "security": {
+      "label": "Security Engineer",
+      "description": "Skills for security audits, dependency/CVE management, blast-radius analysis, and incident handling.",
+      "core": "technical",
+      "skills": [
+        "security-audit",
+        "dependency-management",
+        "dependency-impact-analysis",
+        "incident-response",
+        "rollback-strategy",
+        "configuration-strategy"
+      ]
+    },
+    "architect": {
+      "label": "Architect / Staff Engineer",
+      "description": "Skills for structural decisions, documentation, contracts, blast radius, and technical-debt strategy.",
+      "core": "technical",
+      "skills": [
+        "architecture-design",
+        "architecture-documentation",
+        "api-design",
+        "data-modeling",
+        "dependency-impact-analysis",
+        "technical-debt-review",
+        "project-review",
+        "configuration-strategy",
+        "performance-optimization"
+      ]
+    },
+    "em": {
+      "label": "Engineering Manager / Tech Lead",
+      "description": "Skills for planning, estimation, metrics, retros, proposals, reviews, and steering reviews and incidents.",
+      "core": "universal",
+      "skills": [
+        "technical-debt-review",
+        "retrospective",
+        "metrics-and-okrs",
+        "effort-estimation",
+        "project-proposal",
+        "prd-writing",
+        "project-review",
+        "strategic-review",
+        "code-reviewing",
+        "incident-response"
+      ]
+    },
+    "pm": {
+      "label": "Product / Project Manager",
+      "description": "Skills for proposals, PRDs/specs, estimation, OKRs/metrics, retrospectives, and strategic reviews.",
+      "core": "universal",
+      "skills": [
+        "project-proposal",
+        "prd-writing",
+        "effort-estimation",
+        "metrics-and-okrs",
+        "retrospective",
+        "strategic-review"
+      ]
+    },
+    "strategy": {
+      "label": "Strategy / Founder Review",
+      "description": "Skills for pre-public and strategic reviews: vision and positioning, market analysis, execution-vs-roadmap, and go/no-go synthesis.",
+      "core": "universal",
+      "skills": [
+        "strategic-review",
+        "project-review",
+        "project-proposal",
+        "metrics-and-okrs"
+      ]
+    },
+    "qa": {
+      "label": "QA / Test Engineer",
+      "description": "Skills for test-first development, coverage strategy, test data, review, and systematic debugging.",
+      "core": "technical",
+      "skills": [
+        "tdd-workflow",
+        "test-suite-design",
+        "test-data-strategy",
+        "code-reviewing",
+        "bug-investigating"
+      ]
+    },
+    "designer": {
+      "label": "Designer / UX",
+      "description": "Skills for user flows, accessibility, product requirements, and the frontend architecture that realizes them.",
+      "core": "universal",
+      "skills": [
+        "ui-ux-design",
+        "accessibility-design",
+        "prd-writing",
+        "frontend-architecture"
+      ]
+    }
+  }
+}