@devshop/crew 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# [0.4.0](https://github.com/devshop-software/crew/compare/v0.3.0...v0.4.0) (2026-04-30)
+
+
+### Features
+
+* migrate to npmjs.com as @devshop/crew ([a2ea3c1](https://github.com/devshop-software/crew/commit/a2ea3c1d5454ead7dd16bde6916a708eca520946))
+
+# [0.3.0](https://github.com/devshop-software/crew/compare/v0.2.1...v0.3.0) (2026-04-30)
+
+
+### Features
+
+* prompt before absorbing foreign-collision skills on init ([e8a045c](https://github.com/devshop-software/crew/commit/e8a045c3339de9065269b9bd7cc8ae5aaa976eca))
+
+## [0.2.1](https://github.com/devshop-software/crew/compare/v0.2.0...v0.2.1) (2026-04-30)
+
+
+### Bug Fixes
+
+* don't print "Next: ... /adjust" line when init refused ([8175644](https://github.com/devshop-software/crew/commit/81756442a00e39955e0bebd2dd7f6687df2479a7))
+
+# [0.2.0](https://github.com/devshop-software/crew/compare/v0.1.0...v0.2.0) (2026-04-30)
+
+
+### Features
+
+* ship real skill content (12 skills incl. prep) ([b86bd9a](https://github.com/devshop-software/crew/commit/b86bd9abb361f973023a441d2c808917834c4e1b))
+
+# Changelog
+
+## 0.1.0 — 2026-04-30
+
+Initial release.
+
+- `crew init / update / uninstall / list / doctor` against `<cwd>/.claude/skills/` (default) or `~/.claude/skills/` (`--global`).
+- Per-skill SHA-256 manifest at `.claude/skills/.skills-manifest.json`.
+- Conflict matrix resolves `missing` / `managed-unchanged` / `managed-edited` / `foreign` states across all five commands and the `--force` / `--yes` flags.
+- Idempotent `## Workflow Config` append into project `CLAUDE.md`; never touched by `update` or `uninstall`.
+- Refuses project-scope install when cwd lacks any of `package.json`, `.git`, `CLAUDE.md`, `pyproject.toml`, `Cargo.toml`, `go.mod`.
+- Zero runtime dependencies. Node ≥ 20.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devshop-software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# crew
+
+Project-agnostic Claude Code skills for spec → implement → qa → review → ship.
+
+## Install
+
+Public on npmjs.com — no registry config or token needed.
+
+```sh
+npx @devshop/crew@latest init
+```
+
+Or as a project dev dependency:
+
+```sh
+pnpm add -D @devshop/crew
+pnpm exec crew init
+```
+
+This copies the skills into `./.claude/skills/`, writes a manifest, and appends a `## Workflow Config` block to `CLAUDE.md` (creating it if absent).
+
+## Commands
+
+```
+crew init      [--global] [--force] [--yes] [--dry-run] [--no-claude-md]
+crew update    [--global] [--force] [--yes] [--dry-run]
+crew uninstall [--global] [--dry-run]
+crew list      [--global]
+crew doctor    [--global]
+```
+
+| Flag | Effect |
+|---|---|
+| `--global` | Target `~/.claude/skills/` (no `CLAUDE.md` handling). |
+| `--force` | Override prompts and refusals (silently absorbs foreign collisions, replaces edits). |
+| `--yes` | Non-interactive (CI-safe). On `init`, refuses foreign collisions; on `update`, defaults edited skills to backup-and-replace. |
+| `--dry-run` | Print actions, write nothing. Exits 1 if errors *would have* occurred. |
+| `--no-claude-md` | On `init` only: skip the `CLAUDE.md` append. |
+
+## How conflicts are resolved
+
+The CLI tracks a per-skill SHA-256 in `.claude/skills/.skills-manifest.json`. Each skill folder is in one of four states:
+
+- **missing** — not at the target.
+- **managed-unchanged** — present, in manifest, hash matches.
+- **managed-edited** — present, in manifest, you've edited it.
+- **foreign** — present but not in the manifest.
+
+`update` will never touch foreign skills. On `init`, when foreign collisions are detected (a folder with the same name as a skill we ship, but not in our manifest), interactive runs prompt with the list and ask `[y/N]` to absorb them; `--force` absorbs silently; `--yes` refuses (CI-safe). Absorbed originals are backed up to `.claude/skills/.bak/<utc>/<skill>/`. This is the bright line that keeps `update` boring.
+
+For edited skills:
+
+- `update` (default) → prompts: backup-and-replace / keep / replace.
+- `update --yes` → backup-and-replace.
+- `update --force` → replace, no backup.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success. |
+| 1 | Refused due to a conflict you must resolve. |
+| 2 | Invalid usage (or no project markers in cwd). |
+| 3 | I/O error. |
+| 4 | Manifest corrupt. |
+
+## Maintainer publish
+
+Releases are automated. Push a conventional-commit message (`feat:`, `fix:`, `BREAKING CHANGE:`) to `main` and `.github/workflows/ci.yml` runs semantic-release: computes the next semver, bumps `package.json`, prepends a `CHANGELOG.md` entry, tags `vX.Y.Z`, publishes to npmjs.com, and creates a GitHub release. The `NPM_TOKEN` repo secret authenticates the npm publish.
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@devshop/crew",
+  "version": "0.4.1",
+  "description": "Project-agnostic Claude Code skills for spec → implement → qa → review → ship",
+  "bin": {
+    "crew": "scripts/cli.js"
+  },
+  "files": [
+    "skills/",
+    "templates/",
+    "scripts/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "skills",
+    "agentic",
+    "workflow",
+    "crew"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devshop-software/crew.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "semantic-release": "^24.2.0"
+  }
+}

package/scripts/cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+const path = require('path');
+
+const COMMANDS = ['init', 'update', 'uninstall', 'list', 'doctor'];
+
+function usage() {
+  return [
+    'Usage: crew <command> [flags]',
+    '',
+    'Commands:',
+    '  init       Install skills into the current project (or --global).',
+    '  update     Replace managed skills with newer package versions.',
+    '  uninstall  Remove managed skills and the manifest.',
+    '  list       Show installed skills.',
+    '  doctor     Report drift; never modifies anything.',
+    '',
+    'Flags:',
+    '  --global         Target ~/.claude/skills/ (no CLAUDE.md handling).',
+    '  --force          Override prompts and refusals.',
+    '  --yes            Non-interactive (CI-safe defaults).',
+    '  --dry-run        Print actions, write nothing.',
+    '  --no-claude-md   On init only: skip CLAUDE.md append.'
+  ].join('\n');
+}
+
+function parseArgs(argv) {
+  const flags = { global: false, force: false, yes: false, dryRun: false, noClaudeMd: false };
+  let command = null;
+  for (const a of argv) {
+    if (a.startsWith('--')) {
+      switch (a) {
+        case '--global': flags.global = true; break;
+        case '--force': flags.force = true; break;
+        case '--yes': flags.yes = true; break;
+        case '--dry-run': flags.dryRun = true; break;
+        case '--no-claude-md': flags.noClaudeMd = true; break;
+        case '--help': process.stdout.write(usage() + '\n'); process.exit(0);
+        default:
+          process.stderr.write(`Unknown flag: ${a}\n\n${usage()}\n`);
+          process.exit(2);
+      }
+    } else if (!command) {
+      command = a;
+    } else {
+      process.stderr.write(`Unexpected argument: ${a}\n\n${usage()}\n`);
+      process.exit(2);
+    }
+  }
+  if (!command || !COMMANDS.includes(command)) {
+    process.stderr.write(`${usage()}\n`);
+    process.exit(2);
+  }
+  return { command, flags };
+}
+
+(async () => {
+  const { command, flags } = parseArgs(process.argv.slice(2));
+  const cmd = require(path.join(__dirname, 'commands', `${command}.js`));
+  try {
+    const code = await cmd(flags);
+    process.exit(code || 0);
+  } catch (e) {
+    const log = require('./lib/log');
+    log.error(e.message);
+    process.exit(e.exitCode || 3);
+  }
+})();

package/scripts/commands/doctor.js

@@ -0,0 +1,51 @@
+const path = require('path');
+const { resolveTarget } = require('../lib/paths');
+const { readManifest, diffSkills } = require('../lib/manifest');
+const log = require('../lib/log');
+
+const PKG_ROOT = path.resolve(__dirname, '..', '..');
+const PKG_VERSION = require(path.join(PKG_ROOT, 'package.json')).version;
+const PKG_SKILLS = path.join(PKG_ROOT, 'skills');
+
+module.exports = async function doctor(flags) {
+  let target;
+  try { target = resolveTarget(flags); }
+  catch (e) { log.error(e.message); return e.exitCode || 2; }
+
+  const { skillsDir } = target;
+  let manifest;
+  try { manifest = readManifest(skillsDir); }
+  catch (e) { log.error(e.message); return 4; }
+  if (!manifest) {
+    log.plain(`No crew installation at ${skillsDir}. Run \`crew init\` to install.`);
+    return 0;
+  }
+
+  const diff = diffSkills(PKG_SKILLS, skillsDir, manifest);
+  log.plain(`Package version:  ${PKG_VERSION}`);
+  log.plain(`Manifest version: ${manifest.package_version}`);
+  log.plain(`Scope:            ${manifest.scope}`);
+  log.plain(`Skills dir:       ${skillsDir}`);
+  log.plain('');
+
+  const w = Math.max(4, ...diff.map(d => d.name.length));
+  log.plain(`${'name'.padEnd(w)}  state              mf-ver   pkg-ver`);
+  log.plain(`${'-'.repeat(w)}  -----              ------   -------`);
+  for (const d of diff) {
+    const mfVer = manifest.skills[d.name]?.version || '-';
+    const pkgVer = d.inPkg ? PKG_VERSION : '-';
+    log.plain(`${d.name.padEnd(w)}  ${d.state.padEnd(18)} ${mfVer.padEnd(8)} ${pkgVer}`);
+  }
+
+  const issues = diff.filter(d =>
+    d.state === 'managed-edited' ||
+    d.state === 'foreign' ||
+    (d.state === 'managed-unchanged' && d.diskHash !== d.pkgHash) ||
+    (d.state === 'missing' && d.inPkg)
+  );
+  if (issues.length > 0) {
+    log.plain('');
+    log.plain(`${issues.length} skill(s) need attention. Run \`crew update\` (or \`crew init --force\` for foreign).`);
+  }
+  return 0;
+};

package/scripts/commands/init.js

@@ -0,0 +1,131 @@
+const path = require('path');
+const { resolveTarget } = require('../lib/paths');
+const { readManifest, writeManifest, emptyManifest, diffSkills, PACKAGE_NAME, SCHEMA_VERSION } = require('../lib/manifest');
+const { copyFolder, backupFolder, backupRoot } = require('../lib/fsx');
+const { chooseEditAction, confirmAbsorbForeign } = require('../lib/prompt');
+const { ensureWorkflowConfig } = require('../lib/claude-md');
+const log = require('../lib/log');
+
+const PKG_ROOT = path.resolve(__dirname, '..', '..');
+const PKG_VERSION = require(path.join(PKG_ROOT, 'package.json')).version;
+const PKG_SKILLS = path.join(PKG_ROOT, 'skills');
+const TEMPLATE = path.join(PKG_ROOT, 'templates', 'workflow-config.md');
+
+module.exports = async function init(flags) {
+  let target;
+  try { target = resolveTarget(flags); }
+  catch (e) { log.error(e.message); return e.exitCode || 2; }
+
+  const { skillsDir, claudeMdPath, scope } = target;
+  let manifest;
+  try { manifest = readManifest(skillsDir); }
+  catch (e) { log.error(e.message); return 4; }
+  if (!manifest) manifest = emptyManifest(scope, PKG_VERSION);
+
+  const diff = diffSkills(PKG_SKILLS, skillsDir, manifest);
+  let bakBase = null;
+  let refused = false;
+  let ioError = false;
+  const now = new Date().toISOString();
+  const stamp = (name, hash) => { manifest.skills[name] = { version: PKG_VERSION, hash, installed_at: now }; };
+
+  // Foreign-collision handling: decide once for all such skills, up-front.
+  // --force: silent absorb. --yes: refuse (CI-safe). Otherwise prompt; default N.
+  let absorbForeign = false;
+  const foreignCollisions = diff.filter(s => s.state === 'foreign' && s.inPkg);
+  const interactive = process.stdin.isTTY || process.env.CREW_FAKE_TTY === '1';
+  if (foreignCollisions.length > 0) {
+    if (flags.force) {
+      absorbForeign = true;
+    } else if (!flags.yes && interactive) {
+      absorbForeign = await confirmAbsorbForeign(foreignCollisions.map(s => s.name));
+    }
+  }
+
+  for (const s of diff) {
+    if (!s.inPkg) continue;
+    try {
+      if (s.state === 'missing') {
+        if (flags.dryRun) log.dryRun('copy', s.name);
+        else { copyFolder(path.join(PKG_SKILLS, s.name), path.join(skillsDir, s.name)); log.action('copy', s.name); }
+        stamp(s.name, s.pkgHash);
+      } else if (s.state === 'managed-unchanged') {
+        if (flags.force) {
+          if (flags.dryRun) log.dryRun('replace', s.name);
+          else { copyFolder(path.join(PKG_SKILLS, s.name), path.join(skillsDir, s.name)); log.action('replace', s.name); }
+          stamp(s.name, s.pkgHash);
+        } else if (flags.dryRun) {
+          log.dryRun('skip', s.name);
+        }
+      } else if (s.state === 'managed-edited') {
+        let action;
+        if (flags.force) action = 'replace';
+        else if (flags.yes) action = 'backup';
+        else if (!interactive) {
+          log.error(`Edited skill detected ('${s.name}') and stdin is not a TTY. Re-run with --yes or --force.`);
+          refused = true;
+          continue;
+        } else {
+          action = await chooseEditAction(s.name);
+        }
+        if (action === 'keep') {
+          if (flags.dryRun) log.dryRun('keep', s.name);
+          else log.action('keep', s.name);
+          continue;
+        }
+        if (action === 'backup') {
+          bakBase = bakBase || backupRoot(skillsDir);
+          if (flags.dryRun) log.dryRun('backup', s.name);
+          else { backupFolder(path.join(skillsDir, s.name), bakBase); log.action('backup', s.name); }
+        }
+        if (flags.dryRun) log.dryRun('replace', s.name);
+        else { copyFolder(path.join(PKG_SKILLS, s.name), path.join(skillsDir, s.name)); log.action('replace', s.name); }
+        stamp(s.name, s.pkgHash);
+      } else if (s.state === 'foreign') {
+        if (absorbForeign) {
+          bakBase = bakBase || backupRoot(skillsDir);
+          if (flags.dryRun) { log.dryRun('backup', s.name); log.dryRun('copy', s.name); }
+          else {
+            backupFolder(path.join(skillsDir, s.name), bakBase);
+            copyFolder(path.join(PKG_SKILLS, s.name), path.join(skillsDir, s.name));
+            log.action('backup', s.name);
+            log.action('copy', s.name);
+          }
+          stamp(s.name, s.pkgHash);
+        } else {
+          log.warn(`foreign skill present, refusing: ${s.name} (use --force to absorb)`);
+          refused = true;
+        }
+      }
+    } catch (e) {
+      log.error(`I/O error on ${s.name}: ${e.message}`);
+      ioError = true;
+    }
+  }
+
+  if (!flags.dryRun && !ioError) {
+    manifest.package = PACKAGE_NAME;
+    manifest.package_version = PKG_VERSION;
+    manifest.schema_version = SCHEMA_VERSION;
+    manifest.scope = scope;
+    manifest.updated_at = now;
+    if (!manifest.installed_at) manifest.installed_at = now;
+    try { writeManifest(skillsDir, manifest); }
+    catch (e) { log.error(`Failed writing manifest: ${e.message}`); return 3; }
+  }
+
+  if (scope === 'project' && !flags.noClaudeMd) {
+    try {
+      const result = ensureWorkflowConfig(claudeMdPath, TEMPLATE, { dryRun: flags.dryRun });
+      if (flags.dryRun) log.dryRun(result, 'CLAUDE.md');
+      else log.action(result, 'CLAUDE.md');
+    } catch (e) { log.error(`CLAUDE.md: ${e.message}`); ioError = true; }
+  }
+
+  if (ioError) return 3;
+  if (refused) return 1;
+
+  log.plain('');
+  log.plain('Next: open this project in Claude Code and run /adjust.');
+  return 0;
+};

package/scripts/commands/list.js

@@ -0,0 +1,33 @@
+const { resolveTarget } = require('../lib/paths');
+const { readManifest } = require('../lib/manifest');
+const log = require('../lib/log');
+
+module.exports = async function list(flags) {
+  let target;
+  try { target = resolveTarget(flags); }
+  catch (e) { log.error(e.message); return e.exitCode || 2; }
+
+  const { skillsDir } = target;
+  let manifest;
+  try { manifest = readManifest(skillsDir); }
+  catch (e) { log.error(e.message); return 4; }
+  if (!manifest) {
+    log.plain(`No crew installation at ${skillsDir}.`);
+    return 0;
+  }
+
+  const names = Object.keys(manifest.skills).sort();
+  if (names.length === 0) {
+    log.plain(`No skills installed at ${skillsDir}.`);
+    return 0;
+  }
+
+  const w = Math.max(4, ...names.map(n => n.length));
+  log.plain(`${'name'.padEnd(w)}  version  installed_at`);
+  log.plain(`${'-'.repeat(w)}  -------  --------------------`);
+  for (const n of names) {
+    const e = manifest.skills[n];
+    log.plain(`${n.padEnd(w)}  ${(e.version || '').padEnd(7)}  ${e.installed_at || ''}`);
+  }
+  return 0;
+};

package/scripts/commands/uninstall.js

@@ -0,0 +1,57 @@
+const fs = require('fs');
+const path = require('path');
+const { resolveTarget } = require('../lib/paths');
+const { readManifest, manifestPath } = require('../lib/manifest');
+const { hashSkill } = require('../lib/hash');
+const { removeFolder } = require('../lib/fsx');
+const log = require('../lib/log');
+
+module.exports = async function uninstall(flags) {
+  let target;
+  try { target = resolveTarget(flags); }
+  catch (e) { log.error(e.message); return e.exitCode || 2; }
+
+  const { skillsDir, scope } = target;
+  let manifest;
+  try { manifest = readManifest(skillsDir); }
+  catch (e) { log.error(e.message); return 4; }
+  if (!manifest) {
+    log.error(`No installation found at ${skillsDir}.`);
+    return 1;
+  }
+
+  let ioError = false;
+  for (const name of Object.keys(manifest.skills).sort()) {
+    const folder = path.join(skillsDir, name);
+    try {
+      if (!fs.existsSync(folder)) {
+        log.info(`missing: ${name}`);
+        continue;
+      }
+      const onDisk = hashSkill(folder);
+      if (onDisk === manifest.skills[name].hash) {
+        if (flags.dryRun) log.dryRun('remove', name);
+        else { removeFolder(folder); log.action('remove', name); }
+      } else {
+        log.warn(`kept (edited): ${name}`);
+      }
+    } catch (e) {
+      log.error(`I/O error on ${name}: ${e.message}`);
+      ioError = true;
+    }
+  }
+
+  if (!flags.dryRun && !ioError) {
+    try {
+      const mp = manifestPath(skillsDir);
+      if (fs.existsSync(mp)) fs.unlinkSync(mp);
+    } catch (e) { log.error(`Failed removing manifest: ${e.message}`); return 3; }
+  }
+
+  if (scope === 'project') {
+    log.plain('');
+    log.info(`CLAUDE.md left untouched. Remove the '## Workflow Config' block manually if desired.`);
+  }
+
+  return ioError ? 3 : 0;
+};

package/scripts/commands/update.js

@@ -0,0 +1,92 @@
+const path = require('path');
+const { resolveTarget } = require('../lib/paths');
+const { readManifest, writeManifest, diffSkills, PACKAGE_NAME, SCHEMA_VERSION } = require('../lib/manifest');
+const { copyFolder, backupFolder, backupRoot } = require('../lib/fsx');
+const { chooseEditAction } = require('../lib/prompt');
+const log = require('../lib/log');
+
+const PKG_ROOT = path.resolve(__dirname, '..', '..');
+const PKG_VERSION = require(path.join(PKG_ROOT, 'package.json')).version;
+const PKG_SKILLS = path.join(PKG_ROOT, 'skills');
+
+module.exports = async function update(flags) {
+  let target;
+  try { target = resolveTarget(flags); }
+  catch (e) { log.error(e.message); return e.exitCode || 2; }
+
+  const { skillsDir, scope } = target;
+  let manifest;
+  try { manifest = readManifest(skillsDir); }
+  catch (e) { log.error(e.message); return 4; }
+  if (!manifest) {
+    log.error(`No installation found at ${skillsDir}. Run \`crew init\` first.`);
+    return 1;
+  }
+
+  const diff = diffSkills(PKG_SKILLS, skillsDir, manifest);
+  let bakBase = null;
+  let refused = false;
+  let ioError = false;
+  const now = new Date().toISOString();
+  const interactive = process.stdin.isTTY || process.env.CREW_FAKE_TTY === '1';
+  const stamp = (name, hash) => { manifest.skills[name] = { version: PKG_VERSION, hash, installed_at: now }; };
+
+  for (const s of diff) {
+    if (!s.inPkg) continue;
+    try {
+      if (s.state === 'missing') {
+        if (flags.dryRun) log.dryRun('copy', s.name);
+        else { copyFolder(path.join(PKG_SKILLS, s.name), path.join(skillsDir, s.name)); log.action('copy', s.name); }
+        stamp(s.name, s.pkgHash);
+      } else if (s.state === 'managed-unchanged') {
+        if (s.diskHash !== s.pkgHash) {
+          if (flags.dryRun) log.dryRun('replace', s.name);
+          else { copyFolder(path.join(PKG_SKILLS, s.name), path.join(skillsDir, s.name)); log.action('replace', s.name); }
+          stamp(s.name, s.pkgHash);
+        }
+      } else if (s.state === 'managed-edited') {
+        let action;
+        if (flags.force) action = 'replace';
+        else if (flags.yes) action = 'backup';
+        else if (!interactive) {
+          log.error(`Edited skill detected ('${s.name}') and stdin is not a TTY. Re-run with --yes or --force.`);
+          refused = true;
+          continue;
+        } else {
+          action = await chooseEditAction(s.name);
+        }
+        if (action === 'keep') {
+          if (flags.dryRun) log.dryRun('keep', s.name);
+          else log.action('keep', s.name);
+          continue;
+        }
+        if (action === 'backup') {
+          bakBase = bakBase || backupRoot(skillsDir);
+          if (flags.dryRun) log.dryRun('backup', s.name);
+          else { backupFolder(path.join(skillsDir, s.name), bakBase); log.action('backup', s.name); }
+        }
+        if (flags.dryRun) log.dryRun('replace', s.name);
+        else { copyFolder(path.join(PKG_SKILLS, s.name), path.join(skillsDir, s.name)); log.action('replace', s.name); }
+        stamp(s.name, s.pkgHash);
+      }
+      // foreign: leave (don't touch)
+    } catch (e) {
+      log.error(`I/O error on ${s.name}: ${e.message}`);
+      ioError = true;
+    }
+  }
+
+  if (!flags.dryRun && !ioError) {
+    manifest.package = PACKAGE_NAME;
+    manifest.package_version = PKG_VERSION;
+    manifest.schema_version = SCHEMA_VERSION;
+    manifest.scope = scope;
+    manifest.updated_at = now;
+    try { writeManifest(skillsDir, manifest); }
+    catch (e) { log.error(`Failed writing manifest: ${e.message}`); return 3; }
+  }
+
+  if (ioError) return 3;
+  if (refused) return 1;
+  return 0;
+};

package/scripts/lib/claude-md.js

@@ -0,0 +1,18 @@
+const fs = require('fs');
+
+const HEADING_RE = /^##\s+Workflow Config\s*$/m;
+
+function ensureWorkflowConfig(claudeMdPath, templatePath, { dryRun = false } = {}) {
+  const template = fs.readFileSync(templatePath, 'utf8');
+  if (!fs.existsSync(claudeMdPath)) {
+    if (!dryRun) fs.writeFileSync(claudeMdPath, '# Project\n\n' + template);
+    return 'created';
+  }
+  const existing = fs.readFileSync(claudeMdPath, 'utf8');
+  if (HEADING_RE.test(existing)) return 'present';
+  const sep = existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+  if (!dryRun) fs.appendFileSync(claudeMdPath, sep + template);
+  return 'appended';
+}
+
+module.exports = { ensureWorkflowConfig };

package/scripts/lib/fsx.js

@@ -0,0 +1,33 @@
+const fs = require('fs');
+const path = require('path');
+
+function copyFolder(src, dst, { dryRun = false } = {}) {
+  if (dryRun) return;
+  fs.mkdirSync(dst, { recursive: true });
+  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, e.name);
+    const d = path.join(dst, e.name);
+    if (e.isDirectory()) copyFolder(s, d);
+    else if (e.isFile()) fs.copyFileSync(s, d);
+  }
+}
+
+function backupFolder(src, bakBase, { dryRun = false } = {}) {
+  const dst = path.join(bakBase, path.basename(src));
+  if (dryRun) return dst;
+  fs.mkdirSync(bakBase, { recursive: true });
+  fs.renameSync(src, dst);
+  return dst;
+}
+
+function removeFolder(p, { dryRun = false } = {}) {
+  if (dryRun) return;
+  if (fs.existsSync(p)) fs.rmSync(p, { recursive: true, force: true });
+}
+
+function backupRoot(skillsDir) {
+  const ts = new Date().toISOString().slice(0, 19).replace(/:/g, '-');
+  return path.join(skillsDir, '.bak', ts);
+}
+
+module.exports = { copyFolder, backupFolder, removeFolder, backupRoot };