claude-devkit-cli 1.3.5 → 1.4.0

package/README.md

@@ -109,7 +109,16 @@ cd my-project
 claude-devkit init .
 ```
 
-**Option C: Force re-install** (overwrites existing files)
+**Option C: Global skills install** (available in all projects without running `init` again)
+
+```bash
+claude-devkit init --global
+# or after per-project init, answer "yes" to the global prompt
+```
+
+Skills installed globally at `~/.claude/skills/` are available in every project. Per-project `.claude/skills/` always takes precedence over global — so projects can still override individual skills.
+
+**Option D: Force re-install** (overwrites existing files)
 
 ```bash
 npx claude-devkit-cli init --force .
@@ -118,7 +127,7 @@ npx claude-devkit-cli init --force .
 **Option D: Selective install** (only specific components)
 
 ```bash
-npx claude-devkit-cli init --only hooks,commands .
+npx claude-devkit-cli init --only hooks,skills .
 ```
 
 ### What Gets Installed
@@ -135,13 +144,13 @@ your-project/
 │   │   ├── comment-guard.js   ← Blocks placeholder comments
 │   │   ├── sensitive-guard.sh ← Blocks access to secrets
 │   │   └── self-review.sh     ← Quality checklist on stop
-│   └── commands/
-│       ├── mf-plan.md         ← /mf-plan command
-│       ├── mf-challenge.md    ← /mf-challenge command
-│       ├── mf-build.md        ← /mf-build command
-│       ├── mf-fix.md          ← /mf-fix command
-│       ├── mf-review.md       ← /mf-review command
-│       └── mf-commit.md       ← /mf-commit command
+│   └── skills/
+│       ├── mf-plan/SKILL.md         ← /mf-plan skill
+│       ├── mf-challenge/SKILL.md    ← /mf-challenge skill
+│       ├── mf-build/SKILL.md        ← /mf-build skill
+│       ├── mf-fix/SKILL.md          ← /mf-fix skill
+│       ├── mf-review/SKILL.md       ← /mf-review skill
+│       └── mf-commit/SKILL.md       ← /mf-commit skill
 ├── scripts/
 │   └── build-test.sh          ← Universal test runner
 └── docs/
@@ -187,7 +196,7 @@ npx claude-devkit-cli list
 npx claude-devkit-cli remove
 ```
 
-This removes hooks, commands, settings, and build-test.sh. It preserves `CLAUDE.md` (which you may have customized) and `docs/` (which contains your specs).
+This removes hooks, skills, settings, and build-test.sh. It preserves `CLAUDE.md` (which you may have customized) and `docs/` (which contains your specs).
 
 ---
 
@@ -836,12 +845,12 @@ Add project-specific rules to `.claude/CLAUDE.md`:
 - All strings must be localized via i18n keys
 ```
 
-### Adding Custom Commands
+### Adding Custom Skills
 
-Create new `.md` files in `.claude/commands/`:
+Create new skills in `.claude/skills/<name>/SKILL.md`:
 
 ```markdown
-# .claude/commands/deploy.md
+# .claude/skills/deploy/SKILL.md
 
 Run the deployment pipeline:
 1. /mf-review
@@ -948,8 +957,8 @@ A: This is intentionally not a command (it's expensive and rare). When needed, p
 **Q: What if my project uses multiple languages?**
 A: `build-test.sh` detects the first match. For monorepos, you may need to run it from each sub-project directory or customize the script.
 
-**Q: Can I add more commands?**
-A: Yes. Drop a `.md` file in `.claude/commands/` and it becomes available as a slash command. See [Customization](#9-customization).
+**Q: Can I add more skills?**
+A: Yes. Create a directory `.claude/skills/<name>/SKILL.md` and it becomes available as a slash command. See [Customization](#9-customization).
 
 **Q: How do I update the kit in existing projects?**
 A: Run `npx claude-devkit-cli upgrade`. It automatically detects which files you've customized and only updates unchanged files. Use `--force` to overwrite everything.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-devkit-cli",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "description": "CLI toolkit for spec-first development with Claude Code — hooks, commands, guards, and test runners",
   "bin": {
     "claude-devkit": "./bin/devkit.js",

package/src/cli.js

@@ -18,7 +18,8 @@ export function cli(argv) {
     .command('init [path]')
     .description('Initialize a project with the dev-kit')
     .option('-f, --force', 'Overwrite existing files')
-    .option('--only <components>', 'Install only specific components (comma-separated: hooks,commands,scripts,docs,config)')
+    .option('-g, --global', 'Install skills globally to ~/.claude/skills/ (available in all projects)')
+    .option('--only <components>', 'Install only specific components (comma-separated: hooks,skills,scripts,docs,config)')
     .option('--adopt', 'Adopt existing kit files without overwriting (migration from setup.sh)')
     .option('--dry-run', 'Show what would be done without making changes')
     .action(async (path, opts) => {
@@ -30,6 +31,7 @@ export function cli(argv) {
     .command('upgrade [path]')
     .description('Smart upgrade — preserves customized files')
     .option('-f, --force', 'Overwrite even customized files')
+    .option('-g, --global', 'Upgrade skills globally in ~/.claude/skills/')
     .option('--dry-run', 'Show what would be done without making changes')
     .action(async (path, opts) => {
       const { upgradeCommand } = await import('./commands/upgrade.js');
@@ -63,9 +65,10 @@ export function cli(argv) {
   program
     .command('remove [path]')
     .description('Uninstall dev-kit (preserves CLAUDE.md and docs/)')
-    .action(async (path) => {
+    .option('-g, --global', 'Remove global install (~/.claude/skills/, ~/.claude/hooks/, hook entries from ~/.claude/settings.json)')
+    .action(async (path, opts) => {
       const { removeCommand } = await import('./commands/remove.js');
-      await removeCommand(path || '.');
+      await removeCommand(path || '.', opts);
     });
 
   program.parse(argv);

package/src/commands/init.js

@@ -1,19 +1,96 @@
-import { resolve } from 'node:path';
+import { resolve, join, dirname } from 'node:path';
 import { existsSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
-import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { log } from '../lib/logger.js';
 import { detectProject } from '../lib/detector.js';
 import { readManifest, writeManifest, createManifest, setFileEntry } from '../lib/manifest.js';
 import { hashFile } from '../lib/hasher.js';
+import { homedir } from 'node:os';
+import { mkdir } from 'node:fs/promises';
 import {
   getAllFiles, getFilesForComponents, installFile,
   ensurePlaceholderDir, setPermissions, fillTemplate,
   verifySettingsJson, PLACEHOLDER_DIRS, COMPONENTS,
-  getTemplateDir,
+  getTemplateDir, installSkillGlobal, getGlobalSkillsDir,
+  installHookGlobal, getGlobalHooksDir, mergeGlobalSettings,
 } from '../lib/installer.js';
+import { readFile, writeFile } from 'node:fs/promises';
+
+const GLOBAL_MANIFEST = join(homedir(), '.claude', '.devkit-manifest.json');
+
+async function readGlobalManifest() {
+  try {
+    return JSON.parse(await readFile(GLOBAL_MANIFEST, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+async function writeGlobalManifest(data) {
+  await mkdir(join(homedir(), '.claude'), { recursive: true });
+  await writeFile(GLOBAL_MANIFEST, JSON.stringify(data, null, 2) + '\n');
+}
+
+export async function initGlobal({ force = false, hooks = false } = {}) {
+  const globalSkillsDir = getGlobalSkillsDir();
+  await mkdir(globalSkillsDir, { recursive: true });
+
+  log.blank();
+  console.log('--- Installing global skills ---');
+
+  let copied = 0; let skipped = 0; let identical = 0;
+  for (const relPath of COMPONENTS.skills) {
+    const result = await installSkillGlobal(relPath, globalSkillsDir, { force });
+    if (result === 'copied') copied++;
+    else if (result === 'identical') identical++;
+    else skipped++;
+  }
+
+  const parts = [`${copied} copied`];
+  if (identical > 0) parts.push(`${identical} identical`);
+  if (skipped > 0) parts.push(`${skipped} customized (use --force to overwrite)`);
+  log.pass(`Global skills: ${parts.join(', ')}`);
+  log.info('Skills available in all projects via ~/.claude/skills/');
+
+  if (hooks) {
+    await initGlobalHooks({ force });
+  }
+
+  // Write global manifest
+  const existing = await readGlobalManifest() || {};
+  await writeGlobalManifest({
+    ...existing,
+    globalInstalled: true,
+    globalHooksInstalled: hooks || existing.globalHooksInstalled || false,
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+export async function initGlobalHooks({ force = false } = {}) {
+  const globalHooksDir = getGlobalHooksDir();
+  await mkdir(globalHooksDir, { recursive: true });
+
+  log.blank();
+  console.log('--- Installing global hooks ---');
+
+  let copied = 0; let skipped = 0; let identical = 0;
+  for (const relPath of COMPONENTS.hooks) {
+    const result = await installHookGlobal(relPath, globalHooksDir, { force });
+    if (result === 'copied') copied++;
+    else if (result === 'identical') identical++;
+    else skipped++;
+  }
+
+  await mergeGlobalSettings(globalHooksDir);
+
+  const parts = [`${copied} copied`];
+  if (identical > 0) parts.push(`${identical} identical`);
+  if (skipped > 0) parts.push(`${skipped} customized (use --force to overwrite)`);
+  log.pass(`Global hooks: ${parts.join(', ')}`);
+  log.info('Hooks registered in ~/.claude/settings.json — active in all projects');
+}
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf-8'));
@@ -30,6 +107,12 @@ export async function initCommand(path, opts) {
   log.info(`Target: ${targetDir}`);
   log.blank();
 
+  // --- Global mode ---
+  if (opts.global) {
+    await initGlobal({ force: opts.force, hooks: true });
+    return;
+  }
+
   // --- Adopt mode ---
   if (opts.adopt) {
     await adoptExisting(targetDir);
@@ -164,7 +247,7 @@ export async function initCommand(path, opts) {
   console.log('  .claude/CLAUDE.md          — Project rules (review and customize)');
   console.log('  .claude/settings.json      — Hook configuration');
   console.log('  .claude/hooks/             — 6 guards (file, path, glob, comment, sensitive, self-review)');
-  console.log('  .claude/commands/          — /mf-plan, /mf-challenge, /mf-test, /mf-fix, /mf-review, /mf-commit');
+  console.log('  .claude/skills/            — /mf-plan, /mf-challenge, /mf-build, /mf-fix, /mf-review, /mf-commit');
   console.log('  scripts/build-test.sh      — Universal test runner');
   console.log('  docs/WORKFLOW.md           — Workflow reference');
   log.blank();
@@ -177,12 +260,84 @@ export async function initCommand(path, opts) {
   console.log('  1. Review .claude/CLAUDE.md — ensure project info is correct');
   console.log('  2. Write your first spec:   docs/specs/<feature>.md');
   console.log('  3. Generate test plan:      /mf-plan docs/specs/<feature>.md');
-  console.log('  4. Start coding + testing:  /mf-test');
+  console.log('  4. Start coding + testing:  /mf-build');
   log.blank();
 
   if (warnings > 0) {
     console.log(`⚠ ${warnings} warning(s) above — review before proceeding.`);
   }
+
+  // --- Global install prompt (first-time only) ---
+  if (!opts.global) {
+    const globalMeta = await readGlobalManifest();
+    if (globalMeta?.globalInstalled === undefined) {
+      await promptGlobalInstall(opts);
+    } else if (globalMeta?.globalInstalled === true) {
+      // Auto-upgrade global on init if previously installed
+      await initGlobal({ force: opts.force });
+    }
+  }
+}
+
+async function promptGlobalInstall(opts) {
+  log.blank();
+  console.log('─── Global Install ───');
+  console.log('');
+  console.log('Skills and hooks are installed per-project by default.');
+  console.log('You can install them globally so every project is covered without running init again.');
+  console.log('');
+  console.log('  ~/.claude/skills/   ← global skills (fallback when no per-project skills)');
+  console.log('  ~/.claude/hooks/    ← global hooks  (active in all projects)');
+  console.log('  .claude/skills/     ← per-project skills (takes precedence over global)');
+  console.log('  .claude/hooks/      ← per-project hooks  (takes precedence over global)');
+  console.log('');
+  console.log('To revert global hooks back to per-project later:');
+  console.log('  claude-devkit remove --global');
+  console.log('  then: claude-devkit init  (in each project)');
+  console.log('');
+  console.log('RECOMMENDATION: Choose A if you work across many projects.');
+  console.log('');
+
+  const answer = await askGlobalInstall();
+
+  if (answer === 'skills+hooks') {
+    await initGlobal({ force: opts.force, hooks: true });
+    await trackProjectPath(process.cwd());
+  } else if (answer === 'skills') {
+    await initGlobal({ force: opts.force, hooks: false });
+    await trackProjectPath(process.cwd());
+  } else if (answer === 'no') {
+    await writeGlobalManifest({ globalInstalled: false, updatedAt: new Date().toISOString() });
+    log.info('Skipping global install. Run `claude-devkit init --global` anytime.');
+  }
+  // 'later' = don't write anything, prompt again next time
+}
+
+async function askGlobalInstall() {
+  const { createInterface } = await import('node:readline');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    console.log('A) Skills + Hooks globally  (recommended)');
+    console.log('B) Skills only              (hooks stay per-project)');
+    console.log('C) No — keep everything per-project');
+    console.log('D) Ask me next time');
+    console.log('');
+    rl.question('Choice [A/B/C/D]: ', (answer) => {
+      rl.close();
+      const a = answer.trim().toUpperCase();
+      if (a === 'A') resolve('skills+hooks');
+      else if (a === 'B') resolve('skills');
+      else if (a === 'C') resolve('no');
+      else resolve('later');
+    });
+  });
+}
+
+async function trackProjectPath(projectPath) {
+  const meta = await readGlobalManifest() || {};
+  const projects = new Set(meta.projects || []);
+  projects.add(projectPath);
+  await writeGlobalManifest({ ...meta, projects: [...projects] });
 }
 
 /**

package/src/commands/remove.js

@@ -1,8 +1,10 @@
 import { resolve, join } from 'node:path';
 import { unlink, rmdir, rm } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { log } from '../lib/logger.js';
 import { readManifest } from '../lib/manifest.js';
+import { removeGlobalHooksFromSettings } from '../lib/installer.js';
 
 const PRESERVE = [
   '.claude/CLAUDE.md',
@@ -12,7 +14,50 @@ const PRESERVE_DIRS = [
   'docs/',
 ];
 
-export async function removeCommand(path) {
+export async function removeGlobal() {
+  log.info('Removing global claude-devkit install...');
+  log.blank();
+
+  // Remove ~/.claude/skills/
+  const globalSkillsDir = join(homedir(), '.claude', 'skills');
+  if (existsSync(globalSkillsDir)) {
+    await rm(globalSkillsDir, { recursive: true, force: true });
+    log.del('~/.claude/skills/');
+  } else {
+    log.skip('~/.claude/skills/ (not found)');
+  }
+
+  // Remove ~/.claude/hooks/
+  const globalHooksDir = join(homedir(), '.claude', 'hooks');
+  if (existsSync(globalHooksDir)) {
+    await rm(globalHooksDir, { recursive: true, force: true });
+    log.del('~/.claude/hooks/');
+  } else {
+    log.skip('~/.claude/hooks/ (not found)');
+  }
+
+  // Remove devkit hook entries from ~/.claude/settings.json
+  await removeGlobalHooksFromSettings();
+  log.del('hook entries from ~/.claude/settings.json');
+
+  // Remove global manifest
+  const globalManifest = join(homedir(), '.claude', '.devkit-manifest.json');
+  if (existsSync(globalManifest)) {
+    await unlink(globalManifest);
+    log.del('~/.claude/.devkit-manifest.json');
+  }
+
+  log.blank();
+  log.pass('Global install removed. Per-project installs are unaffected.');
+  log.info('Run `claude-devkit init` in each project to restore per-project hooks.');
+}
+
+export async function removeCommand(path, opts = {}) {
+  if (opts.global) {
+    await removeGlobal();
+    return;
+  }
+
   const targetDir = resolve(path);
   const manifest = await readManifest(targetDir);
 
@@ -56,7 +101,6 @@ export async function removeCommand(path) {
   // Clean up empty directories
   const dirsToClean = [
     '.claude/hooks',
-    '.claude/commands',
     'scripts',
   ];
 
@@ -69,6 +113,13 @@ export async function removeCommand(path) {
     }
   }
 
+  // Skills are nested dirs — use recursive rm
+  const skillsDir = join(targetDir, '.claude/skills');
+  if (existsSync(skillsDir)) {
+    await rm(skillsDir, { recursive: true, force: true });
+    log.del('.claude/skills/');
+  }
+
   log.blank();
   log.pass('Removed. CLAUDE.md and docs/ preserved.');
 }

package/src/commands/upgrade.js

@@ -1,18 +1,92 @@
-import { resolve } from 'node:path';
+import { resolve, dirname, join } from 'node:path';
 import { existsSync } from 'node:fs';
-import { copyFile as fsCopyFile, mkdir } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { copyFile as fsCopyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
 import { log } from '../lib/logger.js';
 import { hashFile } from '../lib/hasher.js';
 import { readManifest, writeManifest, setFileEntry, refreshCustomizationStatus } from '../lib/manifest.js';
-import { getAllFiles, getTemplateDir, setPermissions } from '../lib/installer.js';
+import { getAllFiles, getTemplateDir, setPermissions, COMPONENTS, installSkillGlobal, getGlobalSkillsDir, installHookGlobal, getGlobalHooksDir, mergeGlobalSettings } from '../lib/installer.js';
+
+const GLOBAL_MANIFEST = join(homedir(), '.claude', '.devkit-manifest.json');
+
+async function readGlobalManifest() {
+  try { return JSON.parse(await readFile(GLOBAL_MANIFEST, 'utf-8')); } catch { return null; }
+}
+async function writeGlobalManifest(data) {
+  await mkdir(join(homedir(), '.claude'), { recursive: true });
+  await writeFile(GLOBAL_MANIFEST, JSON.stringify(data, null, 2) + '\n');
+}
+
+export async function upgradeGlobal({ force = false } = {}) {
+  const globalSkillsDir = getGlobalSkillsDir();
+  await mkdir(globalSkillsDir, { recursive: true });
+
+  log.blank();
+  console.log('--- Upgrading global skills ---');
+  let updated = 0; let skipped = 0; let identical = 0;
+
+  for (const relPath of COMPONENTS.skills) {
+    const result = await installSkillGlobal(relPath, globalSkillsDir, { force });
+    if (result === 'copied') updated++;
+    else if (result === 'identical') identical++;
+    else skipped++;
+  }
+
+  let skillParts = [`${updated} updated`, `${identical} unchanged`];
+  if (skipped > 0) skillParts.push(`${skipped} customized (use --force to overwrite)`);
+  log.pass(`Global skills: ${skillParts.join(', ')}`);
+
+  const meta = await readGlobalManifest() || {};
+
+  // Upgrade hooks if previously installed globally
+  if (meta.globalHooksInstalled) {
+    const globalHooksDir = getGlobalHooksDir();
+    await mkdir(globalHooksDir, { recursive: true });
+
+    log.blank();
+    console.log('--- Upgrading global hooks ---');
+    let hUpdated = 0; let hSkipped = 0; let hIdentical = 0;
+
+    for (const relPath of COMPONENTS.hooks) {
+      const result = await installHookGlobal(relPath, globalHooksDir, { force });
+      if (result === 'copied') hUpdated++;
+      else if (result === 'identical') hIdentical++;
+      else hSkipped++;
+    }
+
+    await mergeGlobalSettings(globalHooksDir);
+
+    let hookParts = [`${hUpdated} updated`, `${hIdentical} unchanged`];
+    if (hSkipped > 0) hookParts.push(`${hSkipped} customized (use --force to overwrite)`);
+    log.pass(`Global hooks: ${hookParts.join(', ')}`);
+  }
+
+  await writeGlobalManifest({ ...meta, globalInstalled: true, updatedAt: new Date().toISOString() });
+
+  // Warn about per-project skills that shadow global
+  const projects = meta.projects || [];
+  const projectsWithSkills = projects.filter((p) => existsSync(join(p, '.claude/skills')));
+  if (projectsWithSkills.length > 0) {
+    log.blank();
+    log.info(`Found per-project skills in ${projectsWithSkills.length} project(s):`);
+    for (const p of projectsWithSkills) log.info(`  ${p}`);
+    log.info('Per-project skills take precedence over global. Remove them to use global instead.');
+    log.info('Run `claude-devkit remove <path>` in each project to remove per-project install.');
+  }
+}
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf-8'));
 
 export async function upgradeCommand(path, opts) {
+  // --- Global mode ---
+  if (opts.global) {
+    await upgradeGlobal({ force: opts.force });
+    return;
+  }
+
   const targetDir = resolve(path);
   const manifest = await readManifest(targetDir);
 
@@ -122,4 +196,10 @@ export async function upgradeCommand(path, opts) {
   if (skippedCustomized > 0) {
     log.warn(`${skippedCustomized} customized file(s) skipped. Run with --force to overwrite.`);
   }
+
+  // --- Auto-upgrade global if previously installed ---
+  const globalMeta = await readGlobalManifest();
+  if (globalMeta?.globalInstalled === true) {
+    await upgradeGlobal({ force: opts.force });
+  }
 }

package/src/lib/installer.js

@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { log } from './logger.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -19,13 +20,13 @@ export const COMPONENTS = {
     '.claude/hooks/self-review.sh',
     '.claude/hooks/sensitive-guard.sh',
   ],
-  commands: [
-    '.claude/commands/mf-plan.md',
-    '.claude/commands/mf-challenge.md',
-    '.claude/commands/mf-test.md',
-    '.claude/commands/mf-fix.md',
-    '.claude/commands/mf-review.md',
-    '.claude/commands/mf-commit.md',
+  skills: [
+    '.claude/skills/mf-plan/SKILL.md',
+    '.claude/skills/mf-build/SKILL.md',
+    '.claude/skills/mf-challenge/SKILL.md',
+    '.claude/skills/mf-fix/SKILL.md',
+    '.claude/skills/mf-review/SKILL.md',
+    '.claude/skills/mf-commit/SKILL.md',
   ],
   config: [
     '.claude/settings.json',
@@ -69,7 +70,7 @@ export function getTemplateDir() {
 
 /**
  * Get all files for the given component list.
- * @param {string[]} components - e.g. ['hooks', 'commands']
+ * @param {string[]} components - e.g. ['hooks', 'skills']
  * @returns {string[]} relative file paths
  */
 export function getFilesForComponents(components) {
@@ -183,3 +184,176 @@ export async function verifySettingsJson(targetDir) {
     return false;
   }
 }
+
+/**
+ * Global skills directory: ~/.claude/skills/
+ */
+export function getGlobalSkillsDir() {
+  return join(homedir(), '.claude', 'skills');
+}
+
+/**
+ * Global hooks directory: ~/.claude/hooks/
+ */
+export function getGlobalHooksDir() {
+  return join(homedir(), '.claude', 'hooks');
+}
+
+/**
+ * Copy a hook to the global ~/.claude/hooks/ directory.
+ * Strips the '.claude/hooks/' prefix so path-guard.sh lands at
+ * ~/.claude/hooks/path-guard.sh.
+ * @returns {string} 'copied' | 'skipped' | 'identical'
+ */
+export async function installHookGlobal(hookRelPath, globalHooksDir, { force = false } = {}) {
+  const stripped = hookRelPath.replace(/^\.claude\/hooks\//, '');
+  const src = join(getTemplateDir(), hookRelPath);
+  const dst = join(globalHooksDir, stripped);
+
+  if (existsSync(dst) && !force) {
+    try {
+      const { hashFile } = await import('./hasher.js');
+      const srcHash = await hashFile(src);
+      const dstHash = await hashFile(dst);
+      if (srcHash === dstHash) {
+        log.same(`~/.claude/hooks/${stripped} (identical)`);
+        return 'identical';
+      }
+      log.skip(`~/.claude/hooks/${stripped} (customized — use --force to overwrite)`);
+      return 'skipped';
+    } catch { /* hash failed */ }
+  }
+
+  await mkdir(dirname(dst), { recursive: true });
+  await fsCopyFile(src, dst);
+  await chmod(dst, 0o755);
+  log.copy(`~/.claude/hooks/${stripped}`);
+  return 'copied';
+}
+
+/**
+ * Build hook entries for ~/.claude/settings.json pointing to globalHooksDir.
+ */
+function buildGlobalHookEntries(globalHooksDir) {
+  // Normalize to forward slashes — bash on all platforms (WSL, Git Bash, macOS, Linux)
+  // requires forward slashes even when the host OS is Windows.
+  const dir = globalHooksDir.replace(/\\/g, '/');
+  const h = (file) => `"${dir}/${file}"`;
+  return {
+    PreToolUse: [
+      { matcher: 'Bash', hooks: [
+        { type: 'command', command: `bash ${h('path-guard.sh')}` },
+        { type: 'command', command: `bash ${h('sensitive-guard.sh')}` },
+      ]},
+      { matcher: 'Read|Write|Edit|MultiEdit|Grep', hooks: [
+        { type: 'command', command: `bash ${h('sensitive-guard.sh')}` },
+      ]},
+      { matcher: 'Edit|MultiEdit', hooks: [
+        { type: 'command', command: `node ${h('comment-guard.js')}` },
+      ]},
+      { matcher: 'Glob', hooks: [
+        { type: 'command', command: `node ${h('glob-guard.js')}` },
+      ]},
+    ],
+    PostToolUse: [
+      { matcher: 'Write|Edit|MultiEdit', hooks: [
+        { type: 'command', command: `node ${h('file-guard.js')}` },
+      ]},
+    ],
+    Stop: [
+      { matcher: '', hooks: [
+        { type: 'command', command: `bash ${h('self-review.sh')}` },
+      ]},
+    ],
+  };
+}
+
+function isDevkitHookCommand(command) {
+  return command.includes('/.claude/hooks/');
+}
+
+function stripDevkitHooks(existingHooks) {
+  if (!existingHooks || typeof existingHooks !== 'object') return {};
+  const result = {};
+  for (const [event, matchers] of Object.entries(existingHooks)) {
+    if (!Array.isArray(matchers)) continue;
+    const kept = [];
+    for (const group of matchers) {
+      const keptHooks = (group.hooks || []).filter((h) => !isDevkitHookCommand(h.command || ''));
+      if (keptHooks.length > 0) kept.push({ ...group, hooks: keptHooks });
+    }
+    if (kept.length > 0) result[event] = kept;
+  }
+  return result;
+}
+
+/**
+ * Merge devkit hook registrations into ~/.claude/settings.json.
+ * Preserves any existing non-devkit hooks the user may have.
+ */
+export async function mergeGlobalSettings(globalHooksDir) {
+  const settingsPath = join(homedir(), '.claude', 'settings.json');
+  let existing = {};
+  try {
+    existing = JSON.parse(await readFile(settingsPath, 'utf-8'));
+  } catch { /* file doesn't exist yet — start fresh */ }
+
+  // Remove old devkit entries (identified by /.claude/hooks/ in command path)
+  const cleanedHooks = stripDevkitHooks(existing.hooks);
+
+  // Append new devkit entries
+  const newEntries = buildGlobalHookEntries(globalHooksDir);
+  const mergedHooks = { ...cleanedHooks };
+  for (const [event, entries] of Object.entries(newEntries)) {
+    mergedHooks[event] = [...(mergedHooks[event] || []), ...entries];
+  }
+
+  await mkdir(dirname(settingsPath), { recursive: true });
+  await writeFile(settingsPath, JSON.stringify({ ...existing, hooks: mergedHooks }, null, 2) + '\n');
+}
+
+/**
+ * Remove devkit hook registrations from ~/.claude/settings.json.
+ * Leaves any non-devkit hooks untouched.
+ */
+export async function removeGlobalHooksFromSettings() {
+  const settingsPath = join(homedir(), '.claude', 'settings.json');
+  let existing = {};
+  try {
+    existing = JSON.parse(await readFile(settingsPath, 'utf-8'));
+  } catch { return; }
+
+  const cleanedHooks = stripDevkitHooks(existing.hooks || {});
+  await writeFile(settingsPath, JSON.stringify({ ...existing, hooks: cleanedHooks }, null, 2) + '\n');
+}
+
+/**
+ * Copy a skill to the global ~/.claude/skills/ directory.
+ * Strips the '.claude/skills/' prefix so mf-plan/SKILL.md lands at
+ * ~/.claude/skills/mf-plan/SKILL.md.
+ * @returns {string} 'copied' | 'skipped' | 'identical'
+ */
+export async function installSkillGlobal(skillRelPath, globalSkillsDir, { force = false } = {}) {
+  const stripped = skillRelPath.replace(/^\.claude\/skills\//, '');
+  const src = join(getTemplateDir(), skillRelPath);
+  const dst = join(globalSkillsDir, stripped);
+
+  if (existsSync(dst) && !force) {
+    try {
+      const { hashFile } = await import('./hasher.js');
+      const srcHash = await hashFile(src);
+      const dstHash = await hashFile(dst);
+      if (srcHash === dstHash) {
+        log.same(`~/.claude/skills/${stripped} (identical)`);
+        return 'identical';
+      }
+      log.skip(`~/.claude/skills/${stripped} (customized — use --force to overwrite)`);
+      return 'skipped';
+    } catch { /* hash failed, treat as conflict */ }
+  }
+
+  await mkdir(dirname(dst), { recursive: true });
+  await fsCopyFile(src, dst);
+  log.copy(`~/.claude/skills/${stripped}`);
+  return 'copied';
+}

package/src/lib/manifest.js

@@ -36,7 +36,7 @@ export function createManifest(version, projectType, components) {
     installedAt: now,
     updatedAt: now,
     projectType: projectType || null,
-    components: components || ['hooks', 'commands', 'scripts', 'docs'],
+    components: components || ['hooks', 'skills', 'scripts', 'docs'],
     files: {},
   };
 }

package/templates/.claude/hooks/comment-guard.js

@@ -34,7 +34,7 @@ function isCommentLine(line) {
   if (trimmed.startsWith("#") && !trimmed.startsWith("#!")) return true;
   if (trimmed.startsWith("/*") || trimmed.startsWith("*") || trimmed.endsWith("*/")) return true;
   if (trimmed.startsWith("<!--")) return true;
-  if (trimmed === "pass") return true; // Python pass statement as placeholder
+  if (trimmed === "pass" || /^pass\s*#/.test(trimmed)) return true; // Python pass / pass # comment
   return false;
 }
 

package/templates/.claude/hooks/glob-guard.js

@@ -33,6 +33,14 @@ const SCOPED_DIRS = [
   "Sources", "Tests", "cmd", "pkg", "internal",
 ];
 
+// Allow project-specific scoped dirs via env var
+// e.g. GLOB_GUARD_SCOPED_DIRS=Feature,Domain,Presentation
+const extraDirs = (process.env.GLOB_GUARD_SCOPED_DIRS || "")
+  .split(",")
+  .map((d) => d.trim())
+  .filter(Boolean);
+if (extraDirs.length > 0) SCOPED_DIRS.push(...extraDirs);
+
 function isBroadPattern(pattern) {
   if (!pattern) return false;
   return BROAD_PATTERNS.some((re) => re.test(pattern.trim()));

package/templates/.claude/hooks/path-guard.sh

@@ -14,6 +14,10 @@
 
 set -euo pipefail
 
+# Windows note: this hook requires bash (WSL or Git Bash).
+# On Windows without bash, Claude Code will fail to run this hook and skip it silently.
+# Install WSL or Git Bash and ensure `bash` is in PATH to activate protection.
+
 # ─── Read hook payload from stdin ───────────────────────────────────
 
 INPUT=$(cat)
@@ -41,40 +45,42 @@ COMMAND=$(extract_command "$INPUT") || exit 0
 
 # ─── Blocked directory patterns ─────────────────────────────────────
 
-# Use word boundaries (\b) and explicit path separators to avoid substring false positives
+# Use explicit path separators to avoid substring false positives.
+# [/\\] matches both forward slash (Unix/macOS) and backslash (Windows Git Bash).
 # e.g. "build/" should not match "rebuild/src" or "my-build-tool"
-BLOCKED="(^|[ /])node_modules(/|$| )"
+SEP="[/\\\\]"
+BLOCKED="(^|[ /\\\\])node_modules(${SEP}|$| )"
 BLOCKED+="|(__pycache__)"
-BLOCKED+="|\.git/(objects|refs)"
-BLOCKED+="|(^|[ /])dist/"
-BLOCKED+="|(^|[ /])build/"
-BLOCKED+="|\.next/"
-BLOCKED+="|(^|[ /])vendor(/|$| )"
-BLOCKED+="|(^|[ /])Pods(/|$| )"
-BLOCKED+="|\.build/"
+BLOCKED+="|\.git${SEP}(objects|refs)"
+BLOCKED+="|(^|[ /\\\\])dist${SEP}"
+BLOCKED+="|(^|[ /\\\\])build${SEP}"
+BLOCKED+="|\.next${SEP}"
+BLOCKED+="|(^|[ /\\\\])vendor(${SEP}|$| )"
+BLOCKED+="|(^|[ /\\\\])Pods(${SEP}|$| )"
+BLOCKED+="|\.build${SEP}"
 BLOCKED+="|DerivedData"
-BLOCKED+="|\.gradle/"
-BLOCKED+="|(^|[ /])target/"
+BLOCKED+="|\.gradle${SEP}"
+BLOCKED+="|(^|[ /\\\\])target${SEP}"
 BLOCKED+="|\.nuget"
-BLOCKED+="|\.cache(/|$| )"
+BLOCKED+="|\.cache(${SEP}|$| )"
 # Python
-BLOCKED+="|(^|[ /])\.venv/"
-BLOCKED+="|(^|[ /])venv/"
-BLOCKED+="|\.mypy_cache/"
-BLOCKED+="|\.pytest_cache/"
-BLOCKED+="|\.ruff_cache/"
-BLOCKED+="|\.egg-info(/|$| )"
+BLOCKED+="|(^|[ /\\\\])\.venv${SEP}"
+BLOCKED+="|(^|[ /\\\\])venv${SEP}"
+BLOCKED+="|\.mypy_cache${SEP}"
+BLOCKED+="|\.pytest_cache${SEP}"
+BLOCKED+="|\.ruff_cache${SEP}"
+BLOCKED+="|\.egg-info(${SEP}|$| )"
 # C# .NET (match .NET-specific subdirs to avoid false positives on generic bin/)
-BLOCKED+="|(^|[ /])bin/(Debug|Release|net|x64|x86)"
-BLOCKED+="|(^|[ /])obj/(Debug|Release|net)"
+BLOCKED+="|(^|[ /\\\\])bin${SEP}(Debug|Release|net|x64|x86)"
+BLOCKED+="|(^|[ /\\\\])obj${SEP}(Debug|Release|net)"
 # Node.js frameworks
-BLOCKED+="|\.nuxt/"
-BLOCKED+="|\.svelte-kit/"
-BLOCKED+="|\.parcel-cache/"
-BLOCKED+="|\.turbo/"
-BLOCKED+="|(^|[ /])out/(server|static|_next)"
+BLOCKED+="|\.nuxt${SEP}"
+BLOCKED+="|\.svelte-kit${SEP}"
+BLOCKED+="|\.parcel-cache${SEP}"
+BLOCKED+="|\.turbo${SEP}"
+BLOCKED+="|(^|[ /\\\\])out${SEP}(server|static|_next)"
 # Ruby
-BLOCKED+="|\.bundle/"
+BLOCKED+="|\.bundle${SEP}"
 
 # Append project-specific patterns from env
 if [[ -n "${PATH_GUARD_EXTRA:-}" ]]; then

package/templates/.claude/hooks/self-review.sh

@@ -8,6 +8,7 @@
 #   SELF_REVIEW_ENABLED — set to "false" to disable (default: true)
 
 # No set -euo pipefail — this hook must NEVER fail
+# Windows note: requires bash (WSL or Git Bash). Silently skipped on Windows native.
 
 # Check if disabled
 if [[ "${SELF_REVIEW_ENABLED:-true}" == "false" ]]; then

package/templates/.claude/hooks/sensitive-guard.sh

@@ -13,6 +13,10 @@
 
 set -euo pipefail
 
+# Windows note: this hook requires bash (WSL or Git Bash).
+# On Windows without bash, Claude Code will fail to run this hook and skip it silently.
+# Install WSL or Git Bash and ensure `bash` is in PATH to activate protection.
+
 # ─── Read hook payload from stdin ───────────────────────────────────
 
 INPUT=$(cat)
@@ -117,7 +121,11 @@ check_agentignore() {
 
     # Simple line-by-line match (not full gitignore glob, but covers common cases)
     local relpath
-    relpath=$(echo "$filepath" | sed "s|^$(pwd)/||") 2>/dev/null || relpath="$filepath"
+    # Normalize separators to forward slash before stripping prefix (handles Git Bash on Windows)
+    local normalized_fp normalized_pwd
+    normalized_fp=$(printf '%s' "$filepath" | tr '\\' '/')
+    normalized_pwd=$(pwd | tr '\\' '/')
+    relpath=$(printf '%s' "$normalized_fp" | sed "s|^${normalized_pwd}/||") 2>/dev/null || relpath="$filepath"
 
     while IFS= read -r pattern || [[ -n "$pattern" ]]; do
         # Skip comments and empty lines
@@ -214,14 +222,6 @@ if [[ -n "$COMMAND" ]]; then
     fi
 fi
 
-# ─── Check Grep pattern for sensitive file paths ───────────────────
-
-if [[ -n "$PATTERN" ]]; then
-    if is_sensitive "$PATTERN"; then
-        block_with_message "$PATTERN"
-    fi
-fi
-
 # ─── All checks passed ─────────────────────────────────────────────
 
 exit 0

package/templates/.claude/{commands/mf-build.md → skills/mf-build/SKILL.md}

@@ -1,3 +1,7 @@
+---
+description: TDD delivery loop — write failing tests from spec, implement story by story, drive to GREEN
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
 TDD delivery loop — write failing tests from spec AS, implement story by story, drive to GREEN.
 
 ## Phase 0: Build Context

package/templates/.claude/{commands/mf-challenge.md → skills/mf-challenge/SKILL.md}

@@ -1,3 +1,7 @@
+---
+description: Adversarial review — spawn hostile reviewers to break the plan before coding
+allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion, Agent
+---
 Adversarial review — spawn hostile reviewers to break the plan before coding.
 
 ## Input

package/templates/.claude/{commands/mf-commit.md → skills/mf-commit/SKILL.md}

@@ -1,3 +1,7 @@
+---
+description: Stage, scan secrets, generate conventional commit message
+allowed-tools: Bash, AskUserQuestion
+---
 Stage, scan secrets, generate conventional commit message.
 
 ## Step 1 — Analyze (single compound command)

package/templates/.claude/{commands/mf-fix.md → skills/mf-fix/SKILL.md}

@@ -1,3 +1,7 @@
+---
+description: Test-first bug fix — write failing test, fix code, verify green
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
 Test-first bug fix — write failing test, fix code, verify green.
 
 Bug: $ARGUMENTS

package/templates/.claude/{commands/mf-plan.md → skills/mf-plan/SKILL.md}

@@ -1,3 +1,7 @@
+---
+description: Generate spec with acceptance scenarios from description or existing spec
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
+---
 Generate spec with acceptance scenarios from description or existing spec.
 
 ## Question Format

package/templates/.claude/{commands/mf-review.md → skills/mf-review/SKILL.md}

@@ -1,3 +1,7 @@
+---
+description: Pre-merge code review — security, correctness, spec alignment
+allowed-tools: Read, Bash, Glob, Grep
+---
 Pre-merge code review — security, correctness, spec alignment.
 
 ## Phase 0: Understand Intent