claude-devkit-cli 1.3.3 → 1.4.0

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/CLAUDE.md

@@ -13,8 +13,8 @@ Every change follows this cycle: **SPEC (with acceptance scenarios) → CODE + T
 
 | Trigger | Commands | Details |
 |---------|----------|---------|
-| New feature | `/mf-plan` → `/mf-challenge` (optional) → code in chunks → `/mf-test` each chunk | Start with spec or description |
-| Update feature | `/mf-plan <spec-path> "changes"` → code → `/mf-test` | Do NOT manually edit spec before /mf-plan |
+| New feature | `/mf-plan` → `/mf-challenge` (optional) → code in chunks → `/mf-build` each chunk | Start with spec or description |
+| Update feature | `/mf-plan <spec-path> "changes"` → code → `/mf-build` | Do NOT manually edit spec before /mf-plan |
 | Bug fix | `/mf-fix "description"` | Test-first: write failing test → fix → green |
 | Remove feature | `/mf-plan <spec-path> "remove stories"` → delete code + tests → build pass | /mf-plan handles snapshot before removal |
 | Pre-merge check | `/mf-review` | Diff-based quality gate |

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-test.md → skills/mf-build/SKILL.md}

@@ -1,4 +1,8 @@
-Write tests from spec acceptance scenarios, compile, run, fix until green.
+---
+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
 
@@ -70,7 +74,23 @@ If `scripts/build-test.sh` doesn't exist, detect and run directly:
 
 If tests fail:
 1. Read error output. Is the test wrong or the production code wrong?
-2. If production code seems wrong → **ASK the user:** "Test expects X but code does Y. Fix production code or adjust test?"
+2. If production code seems wrong → use `AskUserQuestion`:
+
+```json
+{
+  "questions": [
+    {
+      "question": "Test expects <X> but code does <Y>. Which is correct?",
+      "header": "Test vs Code Mismatch",
+      "multiSelect": false,
+      "options": [
+        {"label": "Fix production code — the test is correct"},
+        {"label": "Adjust the test — the code behavior is intentional"}
+      ]
+    }
+  ]
+}
+```
 3. Fix test code only. Re-run. Max 3 attempts, then stop and report.
 
 **NEVER:**
@@ -99,7 +119,7 @@ If a test fails due to an edge case, error path, or boundary condition that is N
 
 1. State explicitly: **"This failure suggests a missing acceptance scenario."**
 2. Describe the gap: what behavior was tested, which story it belongs to, why no AS covers it.
-3. Prompt: **"Run `/mf-plan <spec-path> 'Add AS for <description>'` to add the missing scenario."**
+3. Prompt: **"Run `/mf-plan <spec-path> 'Add AS for <description>'` to add the missing scenario, then re-run `/mf-build`."**
 
 Do not silently fix the test and move on. A test that has no corresponding AS means the spec is incomplete — the spec must be updated first.
 

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
@@ -173,32 +177,43 @@ Include 1-sentence rationale for each disposition. Be honest — don't reject va
 
 Show adjudicated findings using the reviewer output format plus Disposition and Rationale fields.
 
-Then present the decision:
-
-```
-How to proceed with N accepted findings?
-
-  A) Apply all accepted — bulk-apply all fixes at once
-     Fit: N/10  |  Trade-off: fast vs. no per-finding control
-
-  B) Review each — walk through one by one, accept/reject/modify
-     Fit: N/10  |  Trade-off: precise control vs. slower
-
-  RECOMMENDATION: [A or B] — <reason based on finding count and severity>
-```
-
-Score Fit based on context: if most findings are High/Critical, recommend B (review each). If mostly Medium with clear fixes, recommend A.
-
-If user picks B: for each finding, present:
-
-```
-Finding [C-1]: <title>
-
-  A) Accept — apply the suggested fix
-  B) Modify — accept with changes (describe your modification)
-  C) Reject — skip this finding
-
-  RECOMMENDATION: [A/B/C] — <based on your adjudication>
+Then present the decision using the `AskUserQuestion` tool:
+
+```json
+{
+  "questions": [
+    {
+      "question": "How to proceed with N accepted findings? RECOMMENDATION: Choose A if mostly Medium fixes, B if any Critical/High findings.",
+      "header": "Apply Findings",
+      "multiSelect": false,
+      "options": [
+        {"label": "A) Apply all accepted — bulk-apply all fixes at once | Trade-off: fast vs. no per-finding control"},
+        {"label": "B) Review each — walk through one by one, accept/reject/modify | Trade-off: precise control vs. slower"}
+      ]
+    }
+  ]
+}
+```
+
+Score: if most findings are High/Critical, recommend B. If mostly Medium with clear fixes, recommend A.
+
+If user picks B: for each finding, use `AskUserQuestion`:
+
+```json
+{
+  "questions": [
+    {
+      "question": "Finding [C-1]: <title>\n<flaw summary>\nRECOMMENDATION: Choose A — <adjudication rationale>.",
+      "header": "Finding C-1",
+      "multiSelect": false,
+      "options": [
+        {"label": "A) Accept — apply the suggested fix"},
+        {"label": "B) Modify — accept with changes (describe your modification)"},
+        {"label": "C) Reject — skip this finding"}
+      ]
+    }
+  ]
+}
 ```
 
 ## Phase 7: Apply
@@ -215,7 +230,7 @@ Reviewers: N lenses
 Findings: X total → Y accepted, Z rejected
 Severity: N Critical, N High, N Medium
 Files modified: [list]
-Next: /mf-test to implement, or /mf-plan to regenerate if major changes.
+Next: /mf-build to implement, or /mf-plan to regenerate if major changes.
 ```
 
 If a reviewer returns > 7 findings, take only top 7 by severity. If a reviewer fails, proceed with remaining reviewers.

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)
@@ -22,9 +26,41 @@ echo "=== DEBUG ===" && \
 
 **Secrets (hard block):** If count > 0, show matched lines and STOP. Do not commit.
 
-**Debug code (soft warn):** If count > 0, show matched lines. Proceed only after user confirms they're intentional.
+**Debug code (soft warn):** If count > 0, show matched lines. Use `AskUserQuestion` to confirm:
+
+```json
+{
+  "questions": [
+    {
+      "question": "Found <N> debug statements (console.log, debugger, etc.) in the diff. Are these intentional?",
+      "header": "Debug Code",
+      "multiSelect": false,
+      "options": [
+        {"label": "Yes, intentional — proceed with commit"},
+        {"label": "No, remove them first"}
+      ]
+    }
+  ]
+}
+```
 
-**Large diff:** If > 10 files or > 300 lines, note: "Large commit — consider splitting for easier review." Continue unless user says to split.
+**Large diff:** If > 10 files or > 300 lines, use `AskUserQuestion` to confirm:
+
+```json
+{
+  "questions": [
+    {
+      "question": "Large commit detected (<N> files, <M> lines). Large commits are harder to review and revert.",
+      "header": "Large Commit",
+      "multiSelect": false,
+      "options": [
+        {"label": "Proceed — commit everything as one"},
+        {"label": "Split — I'll stage specific files myself"}
+      ]
+    }
+  ]
+}
+```
 
 ---
 
@@ -67,12 +103,7 @@ Never stage: `.env`, credentials, build artifacts, generated files, binaries > 1
 ## Step 5 — Commit
 
 ```bash
-git commit -m "$(cat <<'EOF'
-type(scope): description
-
-Co-Authored-By: Claude <noreply@anthropic.com>
-EOF
-)"
+git commit -m "type(scope): description"
 ```
 
 **Do NOT push** unless user explicitly asks.

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
@@ -29,7 +33,24 @@ bash scripts/build-test.sh --filter "<test name>"
 ```
 
 - **FAILS** → reproduced. Continue.
-- **PASSES** → hypothesis may be wrong. Ask: "Test passes — need different repro steps or environment details."
+- **PASSES** → hypothesis may be wrong. Use `AskUserQuestion`:
+
+```json
+{
+  "questions": [
+    {
+      "question": "The test passes with current code — the bug isn't reproduced yet. How to proceed?",
+      "header": "Test Passes Unexpectedly",
+      "multiSelect": false,
+      "options": [
+        {"label": "Provide different repro steps or environment details"},
+        {"label": "The bug may be environment-specific — describe the setup"},
+        {"label": "Skip test-first for this bug — fix directly"}
+      ]
+    }
+  ]
+}
+```
 
 ---