claude-devkit-cli 1.4.2 → 1.4.4

package/package.json

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

package/templates/.claude/skills/mf-build/SKILL.md

@@ -15,6 +15,9 @@ TDD delivery loop — write failing tests from spec AS, implement story by story
    If no changes → "No source changes found. Specify a file or feature."
 
 2. **Read the spec** at `docs/specs/<feature>/<feature>.md` — the `## Stories` section with acceptance scenarios is your roadmap. The `## Overview` and `## Constraints` sections tell you the INTENT behind the code.
+
+3. **Locate related code:** If `codebase-memory-mcp` is available, use `search_code` to find all files touching this feature, and `trace_call_path` to understand dependency chain before writing tests — faster and more accurate than manual grep. Fallback: Grep for the main function/type names in the changed files.
+
 4. **Read existing tests** for the changed files — find patterns, fixtures, naming conventions. Don't duplicate.
 
 ---
@@ -111,19 +114,32 @@ Files: [test files touched]
 Stories: [AS-001 ✓, AS-002 ✓, AS-005 new]
 ```
 
-If behavior changed: "Consider updating the spec in docs/specs/<feature>/<feature>.md."
+### Spec Update Signal
+
+After every build, check against these conditions. If ANY is true → **must** signal.
 
-### Spec Gap Detection
+**Signal when (MUST):**
 
-If a test fails due to an edge case, error path, or boundary condition that is NOT covered by any existing AS in the spec:
+| # | Condition |
+|---|-----------|
+| S1 | A new test covers behavior, edge case, or error path with no corresponding AS in the spec |
+| S2 | Code behavior no longer matches the Given/When/Then of an existing AS (spec is stale) |
+| S3 | Implementation adds a new constraint or guard not documented in any AS or Constraints section |
 
-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, then re-run `/mf-build`."**
+**Do not signal when:**
+- Pure refactor — behavior unchanged, all existing AS still map correctly
+- Performance fix — same output, just faster
+- Fix to match spec — code was wrong, spec was right, no new behavior added
+
+**Signal format:**
+```
+⚠️ Spec Update Needed — run `/mf-plan docs/specs/<feature>/<feature>.md '<describe change>'`
+Reason: [S1 | S2 | S3] — <one line: what is missing or mismatched>
+```
 
-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.
+If S1 applies to a failing test: state **"This failure suggests a missing acceptance scenario."** Describe the gap and prompt to run `/mf-plan` before re-running `/mf-build`. Do not silently add the test without the AS.
 
 ## Rules
 1. **Behavior over implementation.** Test what code DOES, not how.
 2. **Independent tests.** Each test sets up its own state, cleans up after.
-3. **Spec stays upstream.** If a test reveals a spec gap, update the spec before adding the test.
+3. **Spec stays upstream.** If a test reveals a spec gap (S1), signal and update the spec before adding the test. If code drifts from spec (S2), signal. If new constraint added (S3), signal.

package/templates/.claude/skills/mf-fix/SKILL.md

@@ -8,14 +8,35 @@ Bug: $ARGUMENTS
 
 ---
 
+## Iron Law
+
+**NEVER fix without finding the root cause first.**
+
+Fixing symptoms creates whack-a-mole debugging. Every fix that doesn't address the root cause makes the next bug harder to find.
+
+---
+
 ## Phase 0: Investigate
 
 Don't jump to code. Understand the bug first:
 
-1. **Parse the report.** Symptom? Expected vs actual? Repro steps?
-2. **Locate the code.** Grep for keywords from the bug (error messages, function names).
-3. **Check history.** `git log --oneline -5 -- <file>` and `git blame -L <range> <file>` — who changed this last and why?
-4. **Form a hypothesis:** "I believe the bug is caused by [X] in [file:function] because [evidence]."
+1. **Parse the report.** Symptom? Expected vs actual? Repro steps? If context is missing → ask ONE question via AskUserQuestion before proceeding.
+2. **Locate the code.** If `codebase-memory-mcp` is available, use `search_code("<error message or function name>")` to find related files faster, and `trace_call_path` to map callers and impact radius. Fallback: Grep for keywords from the bug (error messages, function names).
+3. **Check history.** `git log --oneline -20 -- <affected-files>` — was this working before? What changed? Regression = root cause is in the diff.
+4. **Pattern check.** Match the symptom against known bug patterns:
+
+| Pattern | Signature | Where to look |
+|---------|-----------|---------------|
+| Race condition | Intermittent, timing-dependent | Concurrent access to shared state |
+| Nil/null propagation | NoMethodError, TypeError, NullPointerException | Missing guards on optional values |
+| State corruption | Inconsistent data, partial updates | Transactions, callbacks, hooks |
+| Integration failure | Timeout, unexpected response | External API calls, service boundaries |
+| Config drift | Works locally, fails in staging/prod | Env vars, feature flags, DB state |
+| Stale cache | Shows old data, fixes on cache clear | Redis, CDN, browser cache |
+
+5. **Reproduce deterministically.** If you can't trigger the bug reliably → gather more evidence. Do NOT guess.
+
+**Required output:** `Root cause hypothesis: ...` — a specific, testable claim about what is wrong and why.
 
 If the bug is in a dependency/config/data (not project code), say so before proceeding.
 
@@ -52,6 +73,10 @@ bash scripts/build-test.sh --filter "<test name>"
 }
 ```
 
+**3-strike rule:** If 3 hypotheses all fail to reproduce the bug → STOP. Use AskUserQuestion:
+"3 hypotheses tested, none confirmed. This may be architectural — not a simple bug."
+Options: A) New hypothesis (describe new evidence), B) Escalate for human review, C) Instrument the area and catch it next time
+
 ---
 
 ## Phase 2: Fix
@@ -64,6 +89,9 @@ Make the **minimal change** needed.
 | Add a guard for the edge case | Rewrite the function |
 | Explain what and why before editing | Silently change code |
 
+**Blast radius check:** If the fix requires touching >5 files → stop and use AskUserQuestion before editing anything:
+"This fix touches N files — that's a large blast radius for a bug fix. A) Proceed — root cause genuinely spans these files, B) Split — fix critical path now, defer the rest, C) Rethink — there may be a more targeted approach"
+
 ---
 
 ## Phase 3: Verify
@@ -93,24 +121,54 @@ This is non-optional for serious bugs. For trivial bugs, the fix summary is enou
 ## Phase 5: Summary
 
 ```
-Bug: <description>
-Hypothesis: <what you predicted> → <confirmed or actual cause>
-Test added: <file>:<test name>
-Fix: <file>:<lines> — <what changed>
-Root cause: <1 sentence>
-Prevention: <suggestion>
-Full suite: All passing ✓
+DEBUG REPORT
+════════════════════════════════════════
+Bug:             <description>
+Hypothesis:      <what you predicted> → <confirmed or actual cause>
+Root cause:      <what was actually wrong>
+Fix:             <file:line — what changed>
+Evidence:        <test output>
+Regression test: <file:test name>
+Full suite:      All passing ✓
+Status:          DONE | DONE_WITH_CONCERNS | BLOCKED
+════════════════════════════════════════
 ```
 
-If the bug reveals an undocumented edge case: "Consider updating the spec at docs/specs/<feature>/<feature>.md."
+### Spec Update Signal
+
+After fixing, check these conditions. If ANY is true → **must** signal.
+
+**Signal when (MUST):**
+
+| # | Condition |
+|---|-----------|
+| S1 | Fix covers an edge case or error path with no corresponding AS in the spec |
+| S2 | Bug existed because an AS described wrong behavior — After fix, code and AS now conflict |
+| S3 | Fix adds a new constraint or guard (null check, balance guard, validation) not in spec |
+
+**Do not signal when:**
+- Fix is a clear typo/off-by-one — code was always wrong relative to spec, no new behavior
+- Performance-only fix — output unchanged
+
+**Signal format:**
+```
+⚠️ Spec Update Needed — run `/mf-plan docs/specs/<feature>/<feature>.md '<describe change>'`
+Reason: [S1 | S2 | S3] — <one line: what is missing or mismatched>
+```
 
 ## Multiple Bugs
 
 If `$ARGUMENTS` describes multiple bugs: triage by severity, fix one at a time, commit each separately.
 
 ## Rules
-1. **Investigate before coding.** Hypothesis before test. Evidence before fix.
+1. **Investigate before coding.** Root cause hypothesis before test. Evidence before fix.
 2. **Minimal fix.** One bug, one change. Don't improve the neighborhood.
 3. **Never weaken tests.** If existing tests break, the fix is wrong.
 4. **Ask before touching production code** if unsure.
 5. **One bug, one commit.** Each fix independently revertable.
+
+**Red flags — slow down if you see these:**
+- "Quick fix for now" — there is no "for now". Fix it right or escalate.
+- Proposing a fix before tracing data flow — you're guessing, not debugging.
+- Each fix reveals a new problem elsewhere — wrong layer, not wrong code.
+- Never say "this should fix it" — verify and prove it. Run the tests.

package/templates/.claude/skills/mf-review/SKILL.md

@@ -13,6 +13,7 @@ Pre-merge code review — security, correctness, spec alignment.
    ```
 2. Check for spec in `docs/specs/<feature>/<feature>.md` — review against INTENT.
 3. Read the diff: `git diff "$BASE"...HEAD`
+4. **Expand blast radius:** If `codebase-memory-mcp` is available, use `search_code("<changed function or type>")` to find files not in the diff that may be affected, and `get_architecture()` to check if changed files belong to a sensitive layer (auth, payment, core). Fallback: skip, review diff only.
 
 If `$ARGUMENTS` provided → scope to those files only.
 If diff > 500 lines → review file-by-file, prioritize by smart focus below.