@the-bearded-bear/claude-craft 8.23.3 → 8.26.0-next.2a54921

package/Project/i18n/en/commands/trace.md

@@ -1,104 +1,96 @@
 ---
 name: trace
-description: Display bidirectional traceability matrix from requirements to code and tests
-arguments:
-  - name: scope
-    description: Scope of tracing (all, requirement, story, code)
-    required: false
-  - name: id
-    description: Specific ID to trace (e.g., FR-001, US-001)
-    required: false
-  - name: format
-    description: Output format (table, mermaid, json)
-    required: false
+description: "Bidirectional traceability matrix (requirement → story → code → tests); --gaps lists uncovered requirements, --by-priority groups by MoSCoW"
+argument-hint: "[all|requirement|story|code] [ID] [--gaps] [--by-priority] [--level=story|code|test|all] [--format=table|mermaid|json]"
 ---
 
 # /project:trace
 
 ## Mission
 
-Generate a bidirectional traceability matrix that maps every requirement from the PRD through user stories, code implementation, and test coverage. This provides full visibility into what is implemented, what is tested, and what gaps exist.
+Map every requirement of the PRD through user stories, code and tests. The default view is the full bidirectional matrix; `--gaps` turns it into a coverage report that lists only what is not covered (this is the former `/project:trace --gaps`); `--by-priority` groups the result by MoSCoW priority.
+
+## Usage
+
+| Invocation | What it does | Replaces |
+|------------|--------------|----------|
+| `/project:trace` or `/project:trace all` | Full matrix: requirement → story → code → tests | `/project:trace` |
+| `/project:trace requirement FR-001` | Trace one requirement downwards | `/project:trace --scope requirement --id FR-001` |
+| `/project:trace story US-001` | Trace one story upwards (requirements) and downwards (code, tests) | `/project:trace --scope story` |
+| `/project:trace code` | Code files with and without story reference | `/project:trace --scope code` |
+| `/project:trace --gaps` | Coverage report: requirements not covered by stories, code or tests, with recommended actions | `/project:trace --gaps` |
+| `/project:trace --gaps --level test` | Same, limited to one coverage level (`story`, `code`, `test`, `all`; default `all`) | `/project:trace --gaps --level test` |
+| `/project:trace --by-priority` | Group requirements and coverage percentages by MoSCoW priority | new (was a section of coverage-map) |
+
+Flags combine: `/project:trace --gaps --by-priority` gives the coverage report with the per-priority breakdown.
+
+## Arguments
+
+Parse `$ARGUMENTS`:
+- First positional token in `all|requirement|story|code` → scope (default `all`).
+- Next positional token matching `FR-\d+` or `US-\d+` → ID to trace (required to be meaningful for `requirement` and `story`).
+- `--gaps` → coverage mode. `--level` is only read in this mode.
+- `--by-priority` → group by priority: P0 = Must have, P1 = Should have, P2 = Could have / Nice to have.
+- `--format` → `table` (default), `mermaid`, `json`.
 
 ## Prerequisites
 
 - `project-management/prd.md` exists with FR-xxx requirement IDs
 - `project-management/backlog/` contains user stories with `Implements:` references
-- Codebase with `// Story: US-xxx` or `# Story: US-xxx` comments
+- Codebase with `// Story: US-xxx` or `# Story: US-xxx` comments (optional for `--gaps --level story`)
 - Test files with story/requirement references
 
 ## Plan Mode
 
 > **Plan mode is mandatory.** Before executing, Claude activates plan mode to analyze impacted code, propose an implementation plan, and wait for your validation before making any changes.
 
-## Workflow
+## Shared scans
 
-### Step 1: Scan PRD Requirements
+Both modes run the same four scans once; the results feed either the matrix or the coverage report. Story **status** always comes from `.bmad/sprint-status.yaml` (single source of truth); markdown files only provide content.
 
-```
-╔══════════════════════════════════════════════════════════╗
-║              TRACEABILITY SCAN - REQUIREMENTS             ║
-╠══════════════════════════════════════════════════════════╣
-║ Scanning project-management/prd.md...                     ║
-╚══════════════════════════════════════════════════════════╝
-```
+### Scan 1: Requirements
 
-Parse the PRD for all functional requirements:
 1. Read `project-management/prd.md`
-2. Extract all FR-xxx IDs from section 5 (Functional Requirements)
-3. Record requirement text, priority (P0/P1/P2), and acceptance criteria
-4. Build a requirements registry: `{FR-001: {text, priority, status}}`
-
-### Step 2: Scan User Stories
-
-Search for user stories referencing requirements:
-1. Scan `project-management/backlog/` for `US-*.md` or `user-stories/` files
-2. In each story, look for `Implements:` or `Traceability` section
-3. Extract mappings: `{US-001: [FR-001, FR-003]}`
-4. Record story status, sprint, and acceptance criteria count
+2. Extract all FR-xxx IDs from the Functional Requirements section
+3. Record text, priority (P0/P1/P2) and acceptance criteria
+4. Registry: `{FR-001: {text, priority}}`; count requirements per priority
 
-### Step 3: Scan Codebase
+### Scan 2: User stories
 
-Search for code files referencing stories:
-1. Grep codebase for patterns: `// Story: US-xxx`, `# Story: US-xxx`, `@story US-xxx`
-2. Record file paths and line numbers for each reference
-3. Build mapping: `{US-001: [src/Service/OrderService.php:42, src/Controller/OrderController.php:15]}`
-4. Identify code files with no story reference
+1. Scan `project-management/backlog/` for `US-*.md` (or `user-stories/` files)
+2. In each story, read the `Implements:` line or the `Traceability` section
+3. Mapping: `{US-001: [FR-001, FR-003]}`; read status and sprint from `.bmad/sprint-status.yaml`
+4. A requirement with no story referencing it is "No Story"
 
-### Step 4: Scan Tests
+### Scan 3: Code
 
-Search for test files referencing stories or requirements:
-1. Grep test directories for `US-xxx` or `FR-xxx` references
-2. Check test names for story/requirement patterns
-3. Build mapping: `{US-001: [tests/OrderServiceTest.php, tests/OrderControllerTest.php]}`
-4. Identify stories with no test coverage
+1. Grep the codebase for `// Story: US-xxx`, `# Story: US-xxx`, `@story US-xxx`
+2. Mapping with file and line: `{US-001: [src/Service/OrderService.php:42]}`
+3. A story with no reference is "No Code"; list code files with no story reference
 
-### Step 5: Generate Traceability Matrix
+### Scan 4: Tests
 
-Combine all mappings into a comprehensive matrix:
+1. Grep test directories for `US-xxx` / `FR-xxx` references and check test names
+2. Mapping: `{US-001: [tests/OrderServiceTest.php]}`
+3. A story with code but no test reference is "No Tests"
 
 ```
 ╔══════════════════════════════════════════════════════════╗
-║              TRACEABILITY MATRIX GENERATED                ║
-╠══════════════════════════════════════════════════════════╣
 ║ Requirements: {n} | Stories: {n} | Files: {n} | Tests: {n}║
 ╚══════════════════════════════════════════════════════════╝
 ```
 
-## Output Format
+## Matrix mode (default)
 
-### Table Format (default)
+Combine the four mappings. Output (table format):
 
 ```
 Bidirectional Traceability Matrix
 =================================
 
-Requirement → Story → Code → Tests
-─────────────────────────────────────────────────────
-
 FR-001 (P0) User Authentication
   ├── US-001: Login with email/password
   │   ├── src/Service/AuthService.php:25
-  │   ├── src/Controller/AuthController.php:18
   │   ├── tests/AuthServiceTest.php ✅
   │   └── tests/AuthControllerTest.php ✅
   └── US-002: Password reset flow
@@ -115,7 +107,6 @@ FR-010 (P1) Export to CSV
 
 Coverage Summary
 ================
-
 | Level | Covered | Total | Percentage |
 |-------|---------|-------|------------|
 | Requirements → Stories | 8 | 10 | 80% |
@@ -125,145 +116,106 @@ Coverage Summary
 
 Gaps Identified
 ===============
-
 | Type | ID | Description | Action Needed |
 |------|----|-------------|---------------|
 | No Stories | FR-010 | Export to CSV | Create user story |
 | No Tests | US-003 | Register with email | Add test coverage |
-| No Code | US-005 | Bulk import | Implement feature |
 ```
 
-### Mermaid Format (--format mermaid)
-
-```mermaid
-graph LR
-    subgraph Requirements
-        FR001[FR-001 Auth]
-        FR002[FR-002 Registration]
-        FR010[FR-010 Export]
-    end
-
-    subgraph Stories
-        US001[US-001 Login]
-        US002[US-002 Password Reset]
-        US003[US-003 Register]
-    end
-
-    subgraph Code
-        AUTH[AuthService]
-        PWD[PasswordResetService]
-        REG[RegistrationService]
-    end
-
-    subgraph Tests
-        T1[AuthServiceTest ✅]
-        T2[PasswordResetTest ✅]
-        T3[❌ Missing]
-    end
-
-    FR001 --> US001
-    FR001 --> US002
-    FR002 --> US003
-    FR010 -.->|NO STORY| X1[Gap]
-
-    US001 --> AUTH
-    US002 --> PWD
-    US003 --> REG
-
-    AUTH --> T1
-    PWD --> T2
-    REG -.-> T3
-
-    style FR010 fill:#ff6b6b
-    style X1 fill:#ff6b6b
-    style T3 fill:#ff6b6b
-```
+With an ID, only that branch is printed, with story status and test counts (e.g. `US-001: Login [Done]`, `tests/AuthServiceTest.php ✅ (12 tests)`), then `Status: Fully covered (2/2 stories, 3/3 code files, 3/3 test files)`.
+
+### Mermaid (`--format mermaid`)
 
-### JSON Format (--format json)
+`graph LR` with four subgraphs (Requirements, Stories, Code, Tests); solid arrows for links, dotted arrows (`-.->|NO STORY|`) to a gap node for missing links; gaps styled `fill:#ff6b6b`.
+
+### JSON (`--format json`)
 
 ```json
 {
   "generated_at": "2026-02-19T10:00:00Z",
-  "requirements": {
-    "FR-001": {
-      "text": "User Authentication",
-      "priority": "P0",
-      "stories": ["US-001", "US-002"],
-      "covered": true
-    }
-  },
-  "stories": {
-    "US-001": {
-      "title": "Login with email/password",
-      "implements": ["FR-001"],
-      "code_files": ["src/Service/AuthService.php"],
-      "test_files": ["tests/AuthServiceTest.php"],
-      "covered": true
-    }
-  },
-  "coverage": {
-    "requirements_to_stories": 0.80,
-    "stories_to_code": 0.87,
-    "stories_to_tests": 0.75,
-    "end_to_end": 0.60
-  },
-  "gaps": [
-    {"type": "no_stories", "id": "FR-010", "description": "Export to CSV"},
-    {"type": "no_tests", "id": "US-003", "description": "Register with email"}
-  ]
+  "requirements": {"FR-001": {"text": "User Authentication", "priority": "P0", "stories": ["US-001"], "covered": true}},
+  "stories": {"US-001": {"title": "Login", "implements": ["FR-001"], "code_files": ["src/Service/AuthService.php"], "test_files": ["tests/AuthServiceTest.php"], "covered": true}},
+  "coverage": {"requirements_to_stories": 0.80, "stories_to_code": 0.87, "stories_to_tests": 0.75, "end_to_end": 0.60},
+  "gaps": [{"type": "no_stories", "id": "FR-010", "description": "Export to CSV"}]
 }
 ```
 
-## Example Session
+## Gaps mode (`--gaps`)
 
-```
-User: /project:trace
+Reuses the shared scans, computes coverage per layer and lists only what is missing. `--level` restricts the layers computed: `story` (scan 1-2), `code` (1-3), `test` (1-4), `all` (default).
 
-Claude: Starting traceability scan...
+```
+Requirement Coverage Map
+========================
+| Layer | Covered | Total | Coverage | Status |
+|-------|---------|-------|----------|--------|
+| Stories | 8 | 10 | 80% | ⚠️ |
+| Code | 7 | 8 | 87% | ⚠️ |
+| Tests | 6 | 8 | 75% | ❌ |
+| End-to-End | 6 | 10 | 60% | ❌ |
+
+Uncovered Requirements
+| ID | Requirement | Priority | Missing |
+|----|-------------|----------|---------|
+| FR-005 | Bulk export | P0 | Tests |
+| FR-010 | CSV import | P1 | Story, Code, Tests |
+
+Recommended Actions
+1. 🔴 CRITICAL: FR-005 (P0) has code but no tests — add test coverage
+2. ⚠️ HIGH: FR-010 (P1) has no story — create a user story
+3. 📝 LOW: FR-020 (P2) not started — plan for future sprints
+
+Next Commands
+- /project:trace requirement FR-005   → deep trace of one requirement
+- /project:backlog add story         → create missing user stories
+- /workflow:plan --only=backlog          → regenerate backlog with gaps
+```
 
-📋 Scanning PRD requirements...
-Found 10 requirements (5 P0, 3 P1, 2 P2)
+With `--level test`, print one row per story: `US-003 | ❌ | 0 files | 0 tests` and the action (e.g. "Create tests/RegistrationServiceTest.php").
 
-📖 Scanning user stories...
-Found 8 stories with requirement references
+Mermaid (`--format mermaid`): `graph TD` with one subgraph per priority; nodes `FR-001 ✅`, `FR-005 ⚠️ No Tests`, `FR-010 ❌ No Story`; styles `#4caf50` (covered), `#ff9800` (partial), `#f44336` (missing).
 
-💻 Scanning codebase...
-Found 24 code files with story references
+### Coverage thresholds
 
-🧪 Scanning tests...
-Found 18 test files with story references
+| Threshold | Status | Action |
+|-----------|--------|--------|
+| >= 90% | ✅ Excellent | Maintain |
+| 80-89% | ⚠️ Good | Review gaps |
+| 60-79% | ⚠️ Needs Work | Prioritize coverage |
+| < 60% | ❌ Critical | Immediate action required |
 
-Bidirectional Traceability Matrix
-=================================
-[... full matrix output ...]
+## Priority grouping (`--by-priority`)
 
-Coverage: 60% end-to-end
-Gaps: 2 requirements without stories, 1 story without tests
+Works in both modes. In matrix mode, requirements are listed under `P0 Must have`, `P1 Should have`, `P2 Could have` headings. In gaps mode, add:
 
-User: /project:trace --scope requirement --id FR-001
+```
+Coverage by Priority
+| Priority | Requirements | Story Coverage | Code Coverage | Test Coverage |
+|----------|-------------|----------------|---------------|---------------|
+| P0 (Must Have) | 5 | 100% ✅ | 100% ✅ | 80% ⚠️ |
+| P1 (Should Have) | 3 | 66% ⚠️ | 50% ❌ | 33% ❌ |
+| P2 (Could Have) | 2 | 0% ❌ | 0% ❌ | 0% ❌ |
+```
 
-Claude: Tracing FR-001: User Authentication
+Recommended actions are then ordered P0 first.
 
-FR-001 (P0) User Authentication
-├── US-001: Login with email/password [Done]
-│   ├── src/Service/AuthService.php:25
-│   ├── src/Controller/AuthController.php:18
-│   ├── tests/AuthServiceTest.php ✅ (12 tests)
-│   └── tests/AuthControllerTest.php ✅ (8 tests)
-└── US-002: Password reset flow [In Progress]
-    ├── src/Service/PasswordResetService.php:10
-    └── tests/PasswordResetServiceTest.php ✅ (6 tests)
+## Example session
 
-Status: Fully covered (2/2 stories, 3/3 code files, 3/3 test files)
+```
+User: /project:trace
+Claude: Found 10 requirements (5 P0, 3 P1, 2 P2), 8 stories, 24 code files, 18 test files.
+        [full matrix] Coverage: 60% end-to-end
 
-User: /project:trace --format mermaid
+User: /project:trace requirement FR-001
+Claude: [FR-001 branch only]
 
-Claude: [generates Mermaid diagram]
+User: /project:trace --gaps --by-priority
+Claude: [coverage report with per-priority table, 2 P0 requirements need attention]
 ```
 
 ## Related Commands
 
-- `/project:coverage-map` - Identify uncovered requirements
-- `/project:generate-prd` - Generate PRD with requirement IDs
-- `/project:generate-backlog` - Create backlog from PRD
-- `/project:generate-tech-spec` - Generate technical specification
+- `/workflow:plan --only=prd` - Generate PRD with requirement IDs
+- `/workflow:plan --only=backlog` - Create backlog from PRD
+- `/workflow:design` - Generate technical specification
+- `/project:migrate --stories` - Add missing fields (such as `Implements:`) to stories

package/Project/i18n/en/commands/update-epic.md

@@ -1,105 +1,9 @@
 ---
-description: Update an EPIC
-argument-hint: [arguments]
+description: "Deprecated (removed in 9.0): use /project:backlog edit epic"
+deprecated: true
+replaced-by: /project:backlog
 ---
 
-# Update an EPIC
+> ⚠️ `/project:update-epic` is deprecated and will be removed in 9.0. Use `/project:backlog edit epic`.
 
-Modify information of an existing EPIC.
-
-## Arguments
-
-$ARGUMENTS (format: EPIC-XXX [field] [value])
-- **EPIC-ID** (required): EPIC ID (e.g., EPIC-001)
-- **Field** (optional): Field to modify
-- **Value** (optional): New value
-
-## Plan Mode
-
-> **Plan mode is mandatory.** Before executing, Claude activates plan mode to analyze impacted code, propose an implementation plan, and wait for your validation before making any changes.
-
-## Modifiable Fields
-
-| Field | Description | Example |
-|-------|-------------|---------|
-| `name` | EPIC name | "New name" |
-| `priority` | Priority | High, Medium, Low |
-| `mmf` | Minimum Marketable Feature | "MMF description" |
-| `description` | Description | "New description" |
-
-## Process
-
-### Interactive Mode (without field arguments)
-
-If only ID is provided:
-
-```
-/project:update-epic EPIC-001
-```
-
-Display current information and offer modifications:
-
-```
-📋 EPIC-001: Authentication system
-
-Current fields:
-1. Name: Authentication system
-2. Priority: High
-3. MMF: Allow users to log in
-4. Description: [...]
-
-Which field to modify? (1-4, or 'q' to quit)
->
-```
-
-### Direct Mode (with arguments)
-
-```
-/project:update-epic EPIC-001 priority Medium
-```
-
-Directly modify the specified field.
-
-### Steps
-
-1. Validate that EPIC exists
-2. Read current file
-3. Modify requested field
-4. Update modification date
-5. Save file
-6. Update index if necessary
-
-## Output Format
-
-```
-✅ EPIC updated!
-
-📋 EPIC-001: Authentication system
-
-Modification:
-  Priority: High → Medium
-
-File: project-management/backlog/epics/EPIC-001-authentication-system.md
-```
-
-## Examples
-
-```
-# Interactive mode
-/project:update-epic EPIC-001
-
-# Change name
-/project:update-epic EPIC-001 name "Authentication and Authorization"
-
-# Change priority
-/project:update-epic EPIC-001 priority Low
-
-# Change MMF
-/project:update-epic EPIC-001 mmf "Allow SSO and 2FA"
-```
-
-## Validation
-
-- Field must be modifiable
-- Priority must be High, Medium or Low
-- Name cannot be empty
+Run `/project:backlog edit epic $ARGUMENTS`: read `.claude/commands/project/backlog.md` and follow it with these arguments.

package/Project/i18n/en/commands/update-stories.md

@@ -1,194 +1,9 @@
 ---
-description: "Update stories to BMAD v6 format with missing fields"
-argument-hint: "[--dry-run] [story-id]"
+description: "Deprecated (removed in 9.0): use /project:migrate --stories"
+deprecated: true
+replaced-by: /project:migrate
 ---
 
-# Update Stories
+> ⚠️ `/project:update-stories` is deprecated and will be removed in 9.0. Use `/project:migrate --stories`.
 
-Add missing BMAD v6 fields to existing user stories.
-
-## Arguments
-
-$ARGUMENTS (format: [--dry-run] [story-id])
-- **--dry-run** (optional): Preview changes without applying
-- **story-id** (optional): Specific story to update (e.g., US-001). If omitted, updates all.
-
-## Plan Mode
-
-> **Plan mode is mandatory.** Before executing, Claude activates plan mode to analyze impacted code, propose an implementation plan, and wait for your validation before making any changes.
-
-## Process
-
-### Step 1: Load current state
-
-1. Read `.bmad/sprint-status.yaml`
-2. Load story files from backlog
-3. Compare fields between file and sprint-status
-
-### Step 2: Identify missing fields
-
-For each story, check for:
-
-| Field | Required | Default if Missing |
-|-------|----------|-------------------|
-| tdd_phase | Yes | "red" if in-progress, "" otherwise |
-| tasks.list | Yes | Extract from ## Tasks section |
-| tasks.total | Yes | Count from list |
-| tasks.completed | Yes | Count done tasks |
-| current_task | No | First in-progress task |
-| history | Yes | Initialize with current status |
-| acceptance_criteria.total | Yes | Count from AC section |
-| acceptance_criteria.validated | Yes | 0 (default) |
-| story_points | Yes | Prompt if missing |
-| epic_id | No | Extract from file |
-
-### Step 3: Parse task list from markdown
-
-Extract tasks from story file format:
-```markdown
-## Tasks
-
-| ID | Description | Status |
-|----|-------------|--------|
-| TASK-001 | Backend endpoint | 🟢 Done |
-| TASK-002 | Frontend form | 🟡 In Progress |
-```
-
-Convert to BMAD format:
-```yaml
-tasks:
-  list:
-    - id: "TASK-001"
-      title: "Backend endpoint"
-      status: "done"
-    - id: "TASK-002"
-      title: "Frontend form"
-      status: "in-progress"
-```
-
-### Step 4: Parse acceptance criteria
-
-Extract from Gherkin format:
-```markdown
-## Acceptance Criteria
-
-### AC1: Valid login
-Given a registered user
-When they enter valid credentials
-Then they are logged in
-Status: ✅ Validated
-
-### AC2: Invalid login
-Given a user
-When they enter invalid credentials
-Then they see an error message
-Status: ⏳ Pending
-```
-
-Convert to BMAD format:
-```yaml
-acceptance_criteria:
-  total: 2
-  validated: 1
-  list:
-    - id: "AC1"
-      title: "Valid login"
-      status: "validated"
-    - id: "AC2"
-      title: "Invalid login"
-      status: "pending"
-```
-
-### Step 5: Initialize history
-
-If no history exists, create initial entry:
-```yaml
-history:
-  - timestamp: "2026-01-29T10:00:00Z"
-    from: ""
-    to: "{current_status}"
-    by: "update-stories"
-    reason: "History initialized"
-```
-
-### Step 6: Validate INVEST compliance
-
-Run INVEST checks and add score:
-```yaml
-invest_score:
-  independent: true
-  negotiable: true
-  valuable: true
-  estimable: true   # false if no story_points
-  small: true       # false if > 8 points
-  testable: true    # false if no AC
-  total: 6
-```
-
-### Step 7: Update sprint-status.yaml
-
-Merge updated fields into sprint-status.yaml.
-
-### Step 8: Update story files (optional)
-
-Add BMAD metadata comment to story files:
-```markdown
-<!-- BMAD v6 Metadata
-tdd_phase: green
-invest_score: 6/6
-last_sync: 2026-01-29T10:00:00Z
--->
-```
-
-## Output Format
-
-```
-📝 Update Stories to BMAD v6
-============================
-
-## Stories Updated: {COUNT}
-
-| Story | Fields Added | INVEST Score |
-|-------|--------------|--------------|
-| US-001 | tdd_phase, history | 6/6 ✅ |
-| US-002 | tasks.list, history | 5/6 ⚠️ |
-| US-003 | story_points required | 4/6 ❌ |
-
-## Fields Summary
-
-| Field | Added To | Skipped |
-|-------|----------|---------|
-| tdd_phase | 10 | 2 (already set) |
-| tasks.list | 8 | 4 (already set) |
-| history | 12 | 0 |
-| invest_score | 12 | 0 |
-
-## Warnings
-
-⚠️ US-003: Missing story points - please estimate
-⚠️ US-007: No acceptance criteria - add before development
-
-## Files Modified
-- .bmad/sprint-status.yaml
-- project-management/backlog/user-stories/US-001-*.md (metadata comment)
-
-## Next Steps
-1. Fix warnings: add missing story_points and AC
-2. Run `/project:sync-backlog` to verify consistency
-3. Run `/gate:validate-backlog` for full validation
-```
-
-## Example
-
-```
-/project:update-stories --dry-run
-/project:update-stories
-/project:update-stories US-001
-```
-
-## Validation
-
-After update, all stories should pass:
-```
-/gate:validate-backlog
-```
+Run `/project:migrate --stories $ARGUMENTS`: read `.claude/commands/project/migrate.md` and follow it with these arguments.