claude-devkit-cli 1.2.5 → 1.3.1

package/templates/.claude/commands/mf-review.md

@@ -7,7 +7,7 @@ Pre-merge code review — security, correctness, spec alignment.
    BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||') || BASE="main"
    git log --oneline "$BASE"...HEAD
    ```
-2. Check for spec in `docs/specs/` and test plan in `docs/test-plans/` — review against INTENT.
+2. Check for spec in `docs/specs/<feature>/<feature>.md` — review against INTENT.
 3. Read the diff: `git diff "$BASE"...HEAD`
 
 If `$ARGUMENTS` provided → scope to those files only.
@@ -50,11 +50,15 @@ Spend 60% of analysis on the primary focus. Cover all categories, but proportion
 - **Null safety:** Optionals used without guards? `object!.property` without nil check?
 
 ### Spec-Test Alignment (Medium)
-- Source changed but no spec update in `docs/specs/`? → flag
+- Source changed but no spec update in `docs/specs/<feature>/`? → flag
 - Source changed but no test update? → flag
-- Spec changed but tests not updated? → flag
+- Spec changed but acceptance scenarios or tests not updated? → flag
 - Code removed but dead tests remain? → flag
 - Spec contains vague requirements without metrics ("fast", "secure", "easy", "scalable")? → flag with suggestion to add SC-NNN with concrete numbers
+- **AS-to-test name check:** Read the spec's `## Stories` section. For each AS-NNN, check if a test file contains a test named or described with that AS ID or its short description. Flag:
+  - AS in spec with no matching test → "AS-NNN: \<description\> has no corresponding test"
+  - Test referencing an AS-NNN that no longer exists in the spec → "Test references removed AS-NNN"
+  Keep this lightweight — match on AS-NNN identifiers and story name substrings, not semantic analysis.
 
 ### Code Quality (Medium)
 - Dead code: removed functions still imported elsewhere?

package/templates/.claude/commands/mf-test.md

@@ -1,4 +1,4 @@
-Write tests from test plan, compile, run, fix until green.
+Write tests from spec acceptance scenarios, compile, run, fix until green.
 
 ## Phase 0: Build Context
 
@@ -10,8 +10,7 @@ Write tests from test plan, compile, run, fix until green.
    If `$ARGUMENTS` provided → scope to that file or feature only.
    If no changes → "No source changes found. Specify a file or feature."
 
-2. **Read the test plan** in `docs/test-plans/` if it exists — this is your roadmap.
-3. **Read the spec** in `docs/specs/` if it exists — understand the INTENT behind the code.
+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.
 4. **Read existing tests** for the changed files — find patterns, fixtures, naming conventions. Don't duplicate.
 
 ---
@@ -86,14 +85,25 @@ If tests fail:
 
 ```
 Tests: X added, Y modified, Z unchanged
-Result: All passing ✓
+Result: All passing ✓ / N failing ✗
 Coverage: [critical uncovered paths if any]
 Files: [test files touched]
-Plan: [TC-001 ✓, TC-002 ✓, TC-005 new]
+Stories: [AS-001 ✓, AS-002 ✓, AS-005 new]
 ```
 
-If behavior changed: "Consider updating the spec in docs/specs/."
+If behavior changed: "Consider updating the spec in docs/specs/<feature>/<feature>.md."
+
+### Spec Gap Detection
+
+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:
+
+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."**
+
+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.
 
 ## 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.

package/templates/docs/WORKFLOW.md

@@ -1,6 +1,6 @@
 # Development Workflow Reference
 
-> Spec-first development: every change follows SPEC → TEST PLAN → CODE + TESTS → BUILD PASS.
+> Spec-first development: every change follows SPEC (with acceptance scenarios) → CODE + TESTS → BUILD PASS.
 
 ---
 
@@ -12,12 +12,11 @@ When: Building something that doesn't exist yet (no code, no spec).
 
 ```
 Step 1 → /mf-plan "description of feature"
-          Generates: docs/specs/<feature>.md (spec)
-                     docs/test-plans/<feature>.md (test plan)
+          Generates: docs/specs/<feature>/<feature>.md (spec with acceptance scenarios)
           Answers validation questions about assumptions.
-          Review both before proceeding.
+          Review before proceeding.
 
-Step 2 → (Optional) /mf-challenge docs/test-plans/<feature>.md
+Step 2 → (Optional) /mf-challenge docs/specs/<feature>/<feature>.md
           Adversarial review: spawns hostile reviewers to find flaws.
           Recommended for complex features, auth, data pipelines.
           Skip for simple CRUD or small features.
@@ -36,13 +35,12 @@ Step 5 → /mf-commit
 When: Changing behavior, adding options, refactoring logic.
 
 ```
-Step 1 → Update spec FIRST: docs/specs/<feature>.md
-          Describe what's changing and why.
+Step 1 → /mf-plan docs/specs/<feature>/<feature>.md "description of changes"
+          Mode C handles everything: snapshot → classification → change report → apply.
+          Do NOT manually edit the spec before running /mf-plan — it creates the
+          snapshot first, then applies changes. Manual edits bypass snapshot protection.
 
-Step 2 → /mf-plan docs/specs/<feature>.md
-          Updates the test plan with new/modified/removed test cases.
-
-Step 3 → Implement code changes.
+Step 2 → Implement code changes.
           /mf-test
           Fix until green.
 
@@ -67,8 +65,10 @@ Optional → If the bug reveals an undocumented edge case, update the spec.
 When: Deleting a feature, removing deprecated code.
 
 ```
-Step 1 → Mark spec sections as removed in docs/specs/<feature>.md
-          (Or archive the entire file if the feature is fully removed.)
+Step 1 → /mf-plan docs/specs/<feature>/<feature>.md "remove stories S-XXX"
+          Mode C creates a snapshot (removing stories = M2 = Major),
+          then marks stories and AS as removed in the spec.
+          (Or if removing the entire feature: archive the directory.)
 
 Step 2 → Delete production code and related test code.
 
@@ -96,7 +96,7 @@ Is this a brand new feature (no existing spec or code)?
     │   └─ No
     │       ├─ Are you removing/deprecating code?
     │       │   ├─ Yes → Remove Feature workflow.
-    │       │   └─ No → Update Feature workflow. Start by editing the spec.
+    │       │   └─ No → Update Feature workflow. Start with /mf-plan.
     │       │
     │       └─ Is the change very small (< 5 lines, behavior unchanged)?
     │           └─ Yes → Skip spec update. Just /mf-test and /mf-commit.
@@ -115,8 +115,8 @@ I just implemented [brief description].
 Files changed: [list files]
 
 Based on:
-- Spec: docs/specs/<feature>.md (section §X)
-- Test plan: docs/test-plans/<feature>.md
+- Spec: docs/specs/<feature>/<feature>.md (section §X)
+- Acceptance scenarios: docs/specs/<feature>/<feature>.md (section ## Stories)
 
 Write tests for the part I just implemented.
 Only tests related to this change — not the entire feature.
@@ -130,11 +130,11 @@ If the spec seems incomplete, note what's missing but don't change it.
 I'm about to change [description of change].
 Affected files: [list]
 
-1. Update the spec: docs/specs/<feature>.md
-2. Update the test plan: docs/test-plans/<feature>.md (only affected test cases)
-3. Implement the code change
-4. Update tests to match
-5. Build and run → fix until green
+1. /mf-plan docs/specs/<feature>/<feature>.md "description of changes"
+   (handles snapshot + spec update + acceptance scenarios)
+2. Implement the code change
+3. Update tests to match
+4. Build and run → fix until green
 ```
 
 ### Template C — Test-First Bug Fix
@@ -157,11 +157,11 @@ Actual: [broken behavior]
 Removing: [feature name]
 Files to delete: [list]
 
-1. Mark relevant spec sections as removed
-2. Mark related test plan entries as removed
-3. Delete production code
-4. Delete test code
-5. Run full test suite → fix cascading breaks
+1. /mf-plan docs/specs/<feature>/<feature>.md "remove stories S-XXX, S-YYY"
+   (handles snapshot + marks stories and AS as removed)
+2. Delete production code
+3. Delete test code
+4. Run full test suite → fix cascading breaks
 ```
 
 ---
@@ -178,7 +178,7 @@ Files to delete: [list]
 | `/mf-challenge` (adversarial) | 15–30k | After /mf-plan, for complex features |
 | Full audit (manual) | 100k+ | Before release, quarterly |
 
-**Rule of thumb:** Daily work uses templates + `/test` → low token cost.
+**Rule of thumb:** Daily work uses templates + `/mf-test` → low token cost.
 Save `/mf-plan` and full audits for significant milestones.
 
 ---
@@ -187,8 +187,8 @@ Save `/mf-plan` and full audits for significant milestones.
 
 Use this as a PR review checklist (enforce manually or via CI):
 
-- [ ] **Spec updated?** If production behavior changed, `docs/specs/` should have changes.
-- [ ] **Test plan updated?** If spec changed, `docs/test-plans/` should have changes.
+- [ ] **Spec updated?** If production behavior changed, `docs/specs/<feature>/` should have changes.
+- [ ] **Acceptance scenarios updated?** If spec behavior changed, AS in spec should reflect it.
 - [ ] **Tests pass?** `bash scripts/build-test.sh` exits 0.
 - [ ] **No dead tests?** Removed production code → removed corresponding tests.
 - [ ] **Coverage not decreased?** (Optional, per-team decision.)
@@ -201,16 +201,15 @@ Use this as a PR review checklist (enforce manually or via CI):
 
 | Change | Must Also Update |
 |--------|-----------------|
-| Production code behavior changed | Spec + test plan + tests |
-| Spec updated | Test plan + tests (if behavior changed) |
-| Test plan updated | Tests (implement new/modified test cases) |
-| Code removed | Remove related tests. Mark spec as removed. |
+| Production code behavior changed | Spec (including acceptance scenarios) + tests |
+| Spec updated | Acceptance scenarios + tests (if behavior changed) |
+| Code removed | Remove related tests. Mark spec and AS as removed. |
 | Bug fix | Add test. Update spec if edge case was undocumented. |
 
 **Never acceptable:**
 - Code changed, spec not updated (spec drift)
 - Code changed, tests not updated (untested code)
-- Spec changed, tests not updated (plan drift)
+- Spec changed, acceptance scenarios or tests not updated (AS drift)
 - Code removed, dead tests remain (orphaned tests)
 
 **Acceptable shortcut** for changes under 5 lines with no behavior change: