@phuc1403/musketeer 0.1.0

package/INSTALLATION.md

@@ -0,0 +1,22 @@
+# Prerequisites & Auto-Install
+
+`musketeer` auto-installs the external prerequisites required by your selected company
+(announced before each install, never silent). When no OS package manager is available — or
+an elevation prompt is refused — it falls back to printing the exact manual command below.
+
+> Filled in detail during Phase 06 (provisioner) / Phase 08 (publish).
+
+## Per-prerequisite matrix
+
+| Prereq | Needed by | Windows | macOS | Linux |
+|--------|-----------|---------|-------|-------|
+| Node 18+ | core | `winget install OpenJS.NodeJS.LTS` | `brew install node` | NodeSource / distro |
+| git | core, code-review | `winget install Git.Git` | `brew install git` | `apt/dnf/pacman install git` |
+| Python 3.8+ | core (skill-creator) | `winget install Python.Python.3.12` | `brew install python@3.12` | `apt install python3 python3-pip` |
+| Java 8+ | architecture (context-map) | `winget install Microsoft.OpenJDK` | `brew install --cask temurin` | `apt install openjdk-17-jdk` |
+| gh | code-review (PR mode) | `winget install GitHub.cli` | `brew install gh` | `apt install gh` |
+
+## Secrets (never auto-installed)
+
+- `ANTHROPIC_API_KEY` — needed only by skill-creator's improve/loop scripts. You will be
+  prompted / shown how to set it; musketeer never writes it to the repo.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phuc Pham (phamhongphuc1403)
+
+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,38 @@
+# musketeer
+
+> Distributable custom Claude Code harness. One declarative command scaffolds a curated
+> **company** of **musketeers** (skills + agents + hooks) into any project's `./.claude/`.
+
+## Install
+
+```bash
+npm i -g @phuc1403/musketeer
+```
+
+## Use
+
+```bash
+musketeer                 # open the muster (interactive picker) → reconcile your company
+musketeer --with a,b,c    # non-interactive: set company to EXACTLY {core,a,b,c}
+musketeer --list          # print current company + available musketeers
+musketeer --help          # usage
+```
+
+`musketeer` is **idempotent**: the picker pre-checks your current company (from `.musketeer.json`),
+and confirming applies the diff — install newly-checked, remove newly-unchecked, regenerate
+`settings.json`, and auto-install any missing prerequisites.
+
+## Musketeers (v1)
+
+| Musketeer | Default | What it adds |
+|-----------|---------|--------------|
+| **core** | always (locked) | research, handoff, skill-creator · statusline, usage-context, format-json hooks |
+| **architecture** | checked | adr-writer, architecture-characteristic-writer, context-map · CML validation hook |
+| **hallmark** | checked | hallmark, hallmark-explore, hallmark-loop · auditor/explorer agents |
+| **code-review** | checked | code-review skill + code-reviewer agent |
+| **dotnet** | opt-in | tdd, knowledge-crunching · EF migration guard hook |
+| **design-docs** | opt-in | inject-design-docs SessionStart hook |
+
+Vocabulary: **musketeer** = a selectable unit · **muster** = the picker · **company** = your recruited set.
+
+See [INSTALLATION.md](INSTALLATION.md) for prerequisites and auto-install behavior.

package/bin/musketeer.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+'use strict';
+
+const { parseArgs } = require('node:util');
+
+const USAGE = `musketeer — scaffold a curated company of Claude Code musketeers into ./.claude
+
+Usage:
+  musketeer                 Open the muster (interactive picker), reconcile your company
+  musketeer --with a,b,c    Non-interactive: set company to EXACTLY {core,a,b,c} (CI/scriptable)
+  musketeer --list          Print current company + all available musketeers
+  musketeer --help          Show this help
+
+Notes:
+  * "core" is always installed and locked — it cannot be removed.
+  * Re-running is idempotent: the picker shows your current state, confirm applies the diff.
+  * settings.json is GENERATED per-selection; missing prereqs are auto-installed (announced).`;
+
+function parse(argv) {
+  return parseArgs({
+    args: argv,
+    options: {
+      with: { type: 'string' },
+      list: { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+    allowPositionals: false,
+  });
+}
+
+async function main(argv = process.argv.slice(2)) {
+  let parsed;
+  try {
+    parsed = parse(argv);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n\n${USAGE}\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const { values } = parsed;
+
+  if (values.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+
+  // Lazy-require so --help never pays the cost of loading the engine/manifest.
+  const reconcile = require('../src/reconcile');
+
+  if (values.list) {
+    await reconcile.list();
+    return;
+  }
+
+  if (typeof values.with === 'string') {
+    const ids = values.with
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    await reconcile.run({ desiredIds: ids, interactive: false });
+    return;
+  }
+
+  // No flags → open the muster (interactive).
+  await reconcile.run({ desiredIds: null, interactive: true });
+}
+
+main().catch((err) => {
+  process.stderr.write(`musketeer: ${err && err.message ? err.message : err}\n`);
+  process.exitCode = 1;
+});

package/manifest.json

@@ -0,0 +1,238 @@
+{
+  "version": 1,
+  "musketeers": {
+    "core": {
+      "label": "core",
+      "description": "Always-on foundation: research, handoff, skill-creator + statusline, usage-context & format-json hooks.",
+      "locked": true,
+      "defaultChecked": true,
+      "deps": [],
+      "files": [
+        "skills/research/**",
+        "skills/handoff/**",
+        "skills/skill-creator/**",
+        "skills/install.ps1",
+        "skills/install.sh",
+        "agents/researcher.md",
+        "statusline.cjs",
+        "hooks/usage-context-awareness.cjs",
+        "hooks/lib/**",
+        "hooks/format-json-hook.js"
+      ],
+      "settings": [
+        {
+          "event": "statusLine",
+          "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/statusline.cjs\"",
+          "padding": 0
+        },
+        {
+          "event": "UserPromptSubmit",
+          "matcher": null,
+          "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/usage-context-awareness.cjs\"",
+          "order": 1
+        },
+        {
+          "event": "PostToolUse",
+          "matcher": null,
+          "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/usage-context-awareness.cjs\"",
+          "order": 1
+        },
+        {
+          "event": "PostToolUse",
+          "matcher": "Write|Edit|MultiEdit",
+          "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/format-json-hook.js\"",
+          "order": 2
+        }
+      ],
+      "prereqs": ["node", "git", "python", "venv-anthropic", "claude-cli"]
+    },
+    "architecture": {
+      "label": "architecture",
+      "description": "DDD architecture authoring: adr-writer, architecture-characteristic-writer, context-map (CML) + validation hook.",
+      "locked": false,
+      "defaultChecked": true,
+      "deps": [],
+      "files": [
+        "skills/adr-writer/**",
+        "skills/architecture-characteristic-writer/**",
+        "skills/context-map/**",
+        "hooks/validate-cml-hook.js"
+      ],
+      "settings": [
+        {
+          "event": "PostToolUse",
+          "matcher": "Write|Edit|MultiEdit",
+          "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/validate-cml-hook.js\"",
+          "order": 1
+        }
+      ],
+      "prereqs": ["java", "cm-cli"]
+    },
+    "hallmark": {
+      "label": "hallmark",
+      "description": "Hallmark design system: hallmark rubric, hallmark-explore, hallmark-loop + auditor/explorer agents.",
+      "locked": false,
+      "defaultChecked": true,
+      "deps": [],
+      "files": [
+        "skills/hallmark/**",
+        "skills/hallmark-explore/**",
+        "skills/hallmark-loop/**",
+        "agents/hallmark-auditor.md",
+        "agents/hallmark-explorer.md"
+      ],
+      "settings": [],
+      "prereqs": ["python", "playwright-mcp"]
+    },
+    "code-review": {
+      "label": "code-review",
+      "description": "Adversarial code review skill + code-reviewer agent (commit / pending / PR modes).",
+      "locked": false,
+      "defaultChecked": true,
+      "deps": [],
+      "files": [
+        "skills/code-review/**",
+        "agents/code-reviewer.md"
+      ],
+      "settings": [],
+      "prereqs": ["git", "gh"]
+    },
+    "dotnet": {
+      "label": "dotnet",
+      "description": "Opt-in .NET extras: tdd, knowledge-crunching + EF migration-guard hook.",
+      "locked": false,
+      "defaultChecked": false,
+      "deps": [],
+      "files": [
+        "skills/tdd/**",
+        "skills/knowledge-crunching/**",
+        "hooks/block-migration-edits.cjs"
+      ],
+      "settings": [
+        {
+          "event": "PreToolUse",
+          "matcher": "Write|Edit|MultiEdit",
+          "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/block-migration-edits.cjs\"",
+          "order": 1,
+          "statusMessage": "Checking for EF migration edits"
+        }
+      ],
+      "prereqs": []
+    },
+    "design-docs": {
+      "label": "design-docs",
+      "description": "Opt-in SessionStart hook that injects architecture/context-map/adr docs/ outputs into context.",
+      "locked": false,
+      "defaultChecked": false,
+      "deps": [],
+      "files": [
+        "hooks/inject-design-docs.cjs"
+      ],
+      "settings": [
+        {
+          "event": "SessionStart",
+          "matcher": "startup|resume|clear|compact",
+          "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/inject-design-docs.cjs\"",
+          "order": 1,
+          "statusMessage": "Injecting design artifacts"
+        }
+      ],
+      "prereqs": []
+    }
+  },
+  "prereqs": {
+    "node": {
+      "detect": "node --version",
+      "minVersion": "18",
+      "kind": "package",
+      "install": {
+        "win": "winget install -e --id OpenJS.NodeJS.LTS",
+        "mac": "brew install node",
+        "linux": {
+          "apt": "sudo apt-get install -y nodejs npm",
+          "dnf": "sudo dnf install -y nodejs",
+          "pacman": "sudo pacman -S --noconfirm nodejs npm"
+        }
+      }
+    },
+    "git": {
+      "detect": "git --version",
+      "kind": "package",
+      "install": {
+        "win": "winget install -e --id Git.Git",
+        "mac": "brew install git",
+        "linux": {
+          "apt": "sudo apt-get install -y git",
+          "dnf": "sudo dnf install -y git",
+          "pacman": "sudo pacman -S --noconfirm git"
+        }
+      }
+    },
+    "python": {
+      "detect": "python --version",
+      "minVersion": "3.8",
+      "kind": "package",
+      "install": {
+        "win": "winget install -e --id Python.Python.3.12",
+        "mac": "brew install python@3.12",
+        "linux": {
+          "apt": "sudo apt-get install -y python3 python3-pip python3-venv",
+          "dnf": "sudo dnf install -y python3 python3-pip",
+          "pacman": "sudo pacman -S --noconfirm python python-pip"
+        }
+      }
+    },
+    "venv-anthropic": {
+      "kind": "venv",
+      "needs": ["python"]
+    },
+    "claude-cli": {
+      "detect": "claude --version",
+      "kind": "package",
+      "install": {
+        "win": "powershell -NoProfile -Command \"irm https://claude.ai/install.ps1 | iex\"",
+        "mac": "brew install --cask claude-code",
+        "linux": "curl -fsSL https://claude.ai/install.sh | bash"
+      }
+    },
+    "java": {
+      "detect": "java -version",
+      "minVersion": "8",
+      "kind": "package",
+      "install": {
+        "win": "winget install -e --id Microsoft.OpenJDK.17",
+        "mac": "brew install --cask temurin",
+        "linux": {
+          "apt": "sudo apt-get install -y openjdk-17-jdk",
+          "dnf": "sudo dnf install -y java-17-openjdk",
+          "pacman": "sudo pacman -S --noconfirm jdk-openjdk"
+        }
+      }
+    },
+    "cm-cli": {
+      "kind": "note",
+      "needs": ["java"]
+    },
+    "gh": {
+      "detect": "gh --version",
+      "kind": "package",
+      "install": {
+        "win": "winget install -e --id GitHub.cli",
+        "mac": "brew install gh",
+        "linux": {
+          "apt": "sudo apt-get install -y gh",
+          "dnf": "sudo dnf install -y gh",
+          "pacman": "sudo pacman -S --noconfirm github-cli"
+        }
+      }
+    },
+    "playwright-mcp": {
+      "kind": "mcp",
+      "needs": ["node", "claude-cli"]
+    },
+    "anthropic-api-key": {
+      "kind": "secret",
+      "guideOnly": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@phuc1403/musketeer",
+  "version": "0.1.0",
+  "description": "Distributable custom Claude Code harness — one declarative command scaffolds a curated company of musketeers (skills/agents/hooks) into any project's .claude/.",
+  "type": "commonjs",
+  "bin": {
+    "musketeer": "bin/musketeer.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "bin",
+    "src",
+    "manifest.json",
+    "template",
+    "README.md",
+    "INSTALLATION.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "harness",
+    "scaffolder",
+    "cli",
+    "skills",
+    "agents",
+    "hooks"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phamhongphuc1403/musketeer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/phamhongphuc1403/musketeer/issues"
+  },
+  "homepage": "https://github.com/phamhongphuc1403/musketeer#readme",
+  "dependencies": {
+    "@clack/prompts": "^0.7.0"
+  }
+}

package/src/copier.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Guard against operating on a `.claude` that is a symlink pointing outside the
+ * project (would let copy/remove escape the project tree).
+ * @param {string} projectClaudeDir
+ * @param {string} projectDir
+ */
+function guardClaudeDir(projectClaudeDir, projectDir) {
+  let st;
+  try {
+    st = fs.lstatSync(projectClaudeDir);
+  } catch {
+    return; // doesn't exist yet — fine
+  }
+  if (st.isSymbolicLink()) {
+    const real = fs.realpathSync(projectClaudeDir);
+    const realProject = fs.realpathSync(projectDir);
+    if (!real.startsWith(realProject + path.sep) && real !== realProject) {
+      throw new Error(`.claude is a symlink pointing outside the project (${real}); refusing to operate.`);
+    }
+  }
+}
+
+/**
+ * Compute the reconcile file plan.
+ * Force-update model: every desired file is (re)copied; only files the lockfile
+ * recorded that are no longer desired get removed.
+ * @param {string[]} prevFiles
+ * @param {string[]} desiredFiles
+ * @returns {{copy:string[], remove:string[]}}
+ */
+function planFiles(prevFiles, desiredFiles) {
+  const desiredSet = new Set(desiredFiles);
+  const remove = prevFiles.filter((f) => !desiredSet.has(f));
+  return { copy: [...desiredFiles], remove };
+}
+
+/**
+ * Resolve `rel` under `base`, returning an absolute path ONLY if it stays
+ * contained within `base`. Defends against traversal (`../../x`) from
+ * lockfile-supplied paths — upholds "never touch files outside .claude/".
+ * @returns {?string} contained absolute path, or null if it would escape
+ */
+function containedPath(base, rel) {
+  const root = path.resolve(base);
+  const abs = path.resolve(root, rel);
+  if (abs !== root && !abs.startsWith(root + path.sep)) return null;
+  return abs;
+}
+
+function copyOne(rel, templateClaudeDir, projectClaudeDir) {
+  const dest = containedPath(projectClaudeDir, rel);
+  const src = containedPath(templateClaudeDir, rel);
+  if (!dest || !src) {
+    process.stderr.write(`musketeer: skipping out-of-tree path "${rel}"\n`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+function removeOne(rel, projectClaudeDir) {
+  const dest = containedPath(projectClaudeDir, rel);
+  if (!dest) {
+    process.stderr.write(`musketeer: refusing to remove out-of-tree path "${rel}"\n`);
+    return;
+  }
+  try {
+    fs.rmSync(dest, { force: true });
+  } catch {
+    /* already gone */
+  }
+  pruneEmptyParents(path.dirname(dest), projectClaudeDir);
+}
+
+/**
+ * Remove now-empty directories walking up from `dir` to (but not including)
+ * `stopAt`. Never deletes a non-empty directory (preserves user files).
+ */
+function pruneEmptyParents(dir, stopAt) {
+  let cur = dir;
+  const stop = path.resolve(stopAt);
+  while (path.resolve(cur) !== stop && path.resolve(cur).startsWith(stop + path.sep)) {
+    let entries;
+    try {
+      entries = fs.readdirSync(cur);
+    } catch {
+      break;
+    }
+    if (entries.length > 0) break;
+    try {
+      fs.rmdirSync(cur);
+    } catch {
+      break;
+    }
+    cur = path.dirname(cur);
+  }
+}
+
+/**
+ * Apply a file plan to the project's `.claude` directory.
+ * @param {{copy:string[], remove:string[]}} plan
+ * @param {string} templateClaudeDir absolute path to packaged template/.claude
+ * @param {string} projectDir absolute path to the target project
+ */
+function apply(plan, templateClaudeDir, projectDir) {
+  const projectClaudeDir = path.join(projectDir, '.claude');
+  guardClaudeDir(projectClaudeDir, projectDir);
+  fs.mkdirSync(projectClaudeDir, { recursive: true });
+
+  for (const rel of plan.remove) removeOne(rel, projectClaudeDir);
+  for (const rel of plan.copy) copyOne(rel, templateClaudeDir, projectClaudeDir);
+}
+
+module.exports = { apply, planFiles, guardClaudeDir, pruneEmptyParents, containedPath };

package/src/lockfile.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const LOCKFILE_NAME = '.musketeer.json';
+const LOCKFILE_VERSION = 1;
+
+function lockfilePath(projectDir) {
+  return path.join(projectDir, LOCKFILE_NAME);
+}
+
+/**
+ * Read the current company from `.musketeer.json`.
+ * Missing / unreadable / malformed → empty company (first-run semantics).
+ * @param {string} projectDir
+ * @returns {{version:number, musketeers:string[], files:string[], updatedAt?:string}}
+ */
+function readLockfile(projectDir) {
+  const file = lockfilePath(projectDir);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return { version: LOCKFILE_VERSION, musketeers: [], files: [] };
+  }
+  try {
+    const obj = JSON.parse(raw);
+    return {
+      version: typeof obj.version === 'number' ? obj.version : LOCKFILE_VERSION,
+      musketeers: Array.isArray(obj.musketeers) ? obj.musketeers : [],
+      files: Array.isArray(obj.files) ? obj.files : [],
+      updatedAt: obj.updatedAt,
+    };
+  } catch {
+    return { version: LOCKFILE_VERSION, musketeers: [], files: [] };
+  }
+}
+
+/**
+ * Atomically write the lockfile. `updatedAt` is provided by the caller
+ * (kept out of the pure core so output is deterministic in tests).
+ * @param {string} projectDir
+ * @param {{musketeers:string[], files:string[], updatedAt?:string}} data
+ */
+function writeLockfile(projectDir, data) {
+  const out = {
+    version: LOCKFILE_VERSION,
+    musketeers: [...(data.musketeers || [])].sort(),
+    files: [...(data.files || [])].sort(),
+  };
+  if (data.updatedAt) out.updatedAt = data.updatedAt;
+
+  const file = lockfilePath(projectDir);
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(out, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, file);
+  return out;
+}
+
+module.exports = { readLockfile, writeLockfile, lockfilePath, LOCKFILE_NAME, LOCKFILE_VERSION };

package/src/manifest-loader.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { validateManifest } = require('./schema');
+
+const MANIFEST_FILENAME = 'manifest.json';
+
+/**
+ * Resolve the path to the packaged manifest.json (sibling of src/).
+ * @returns {string}
+ */
+function manifestPath() {
+  return path.join(__dirname, '..', MANIFEST_FILENAME);
+}
+
+/**
+ * Load + validate the packaged manifest.
+ * @param {string} [file] override path (tests)
+ * @returns {object} validated manifest
+ */
+function loadManifest(file = manifestPath()) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    throw new Error(`Cannot read manifest at ${file}: ${err.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`manifest.json is not valid JSON: ${err.message}`);
+  }
+  return validateManifest(parsed);
+}
+
+/**
+ * Absolute path to the packaged template/.claude directory.
+ * @returns {string}
+ */
+function templateClaudeDir() {
+  return path.join(__dirname, '..', 'template', '.claude');
+}
+
+module.exports = { loadManifest, manifestPath, templateClaudeDir, MANIFEST_FILENAME };