23 changed files with 284 additions and 869 deletions
--- a/docs/bmad-brownfield-guide.md
+++ b/docs/bmad-brownfield-guide.md
@ -451,7 +451,7 @@ Phase Transition → sprint-planning
    ┌──────────────────┴──────────────────┐
    │                                      │
    ↓                                      ↓
-create-story → story-context → dev-story → code-review
+create-story → story-context → dev-story → review-story
    │              │               │            │
    ↓              ↓               ↓            ↓
 drafted    ready-for-dev    in-progress     review
@ -488,7 +488,7 @@ backlog → drafted → ready-for-dev → in-progress → review → done
 | `create-story`      | SM    | Draft individual story          | Story: backlog → drafted                    |
 | `story-context`     | SM    | Generate implementation context | Story: drafted → ready-for-dev              |
 | `dev-story`         | DEV   | Implement story                 | Story: ready-for-dev → in-progress → review |
-| `code-review`       | SM/SR | Quality validation              | Manual state management                     |
+| `review-story`      | SM/SR | Quality validation              | Manual state management                     |
 | `retrospective`     | SM    | Capture epic learnings          | Retrospective: optional → completed         |
 | `correct-course`    | SM    | Handle issues/scope changes     | Adaptive based on situation                 |
@ -832,7 +832,7 @@ Use the Test Architect (TEA) workflows:
 3. `tech-spec` → analyzes bug, plans fix, creates single story
 4. `sprint-planning` → creates sprint status
 5. `dev-story` → implement fix
-6. `code-review` → validate fix + test regression
+6. `review-story` → validate fix + test regression
 **Time:** ~2-4 hours total
@ -1006,7 +1006,7 @@ Use the Test Architect (TEA) workflows:
 1. Ensure `document-project` captured existing patterns
 2. Review architecture documentation before Phase 4
 3. Use `story-context` to inject pattern guidance
-4. Include pattern adherence in `code-review` checklist
+4. Include pattern adherence in `review-story` checklist
 5. Run retrospectives to identify pattern deviations
 ## Test Architect Integration
@ -1094,7 +1094,7 @@ bmad sm epic-tech-context      # Create epic context
 bmad sm create-story           # Draft story
 bmad sm story-context          # Create story context
 bmad dev dev-story             # Implement story
-bmad sm code-review           # Review implementation
+bmad sm review-story           # Review implementation
 # (Manually update sprint-status.yaml to 'done')
 bmad sm retrospective          # After epic completion
 bmad sm correct-course         # If issues arise
--- a/src/modules/bmm/README.md
+++ b/src/modules/bmm/README.md
@ -53,7 +53,7 @@ The heart of BMM - structured workflows for the four development phases:
   - `story-context` - Expertise injection (SM agent)
   - `dev-story` - Implementation (DEV agent)
   - `story-done` - Mark story done (DEV agent)
-   - `code-review` - Quality validation (DEV/SR agent)
+   - `review-story` - Quality validation (DEV/SR agent)
   - `correct-course` - Issue resolution
   - `retrospective` - Continuous improvement
--- a/src/modules/bmm/agents/dev.agent.yaml
+++ b/src/modules/bmm/agents/dev.agent.yaml
@ -38,6 +38,6 @@ agent:
      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/story-done/workflow.yaml"
      description: Mark story done after DoD complete
-    - trigger: code-review
+    - trigger: review
-      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/code-review/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/review-story/workflow.yaml"
      description: "Perform a thorough clean context review on a story flagged Ready for Review, and appends review notes to story file"
--- a/src/modules/bmm/agents/game-dev.agent.yaml
+++ b/src/modules/bmm/agents/game-dev.agent.yaml
@ -30,8 +30,8 @@ agent:
      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml"
      description: Implement Story with Context
-    - trigger: code-review
+    - trigger: review-story
-      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/code-review/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/review-story/workflow.yaml"
      description: Review Story Implementation
    - trigger: retro
--- a/src/modules/bmm/agents/sm.agent.yaml
+++ b/src/modules/bmm/agents/sm.agent.yaml
@ -29,6 +29,31 @@ agent:
      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml"
      description: Generate or update sprint-status.yaml from epic files
    - trigger: create-story
      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml"
      description: Create a Draft Story with Context
    - trigger: story-ready
      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/story-ready/workflow.yaml"
      description: Mark drafted story ready for development
    - trigger: story-context
      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/story-context/workflow.yaml"
      description: Assemble dynamic Story Context (XML) from latest docs and code
    - trigger: validate-story-context
      validate-workflow: "{project-root}/bmad/bmm/workflows/4-implementation/story-context/workflow.yaml"
      description: Validate latest Story Context XML against checklist
    - trigger: retrospective
      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml"
      data: "{project-root}/bmad/_cfg/agent-manifest.csv"
      description: Facilitate team retrospective after epic/sprint
    - trigger: correct-course
      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
      description: Execute correct-course task
    - trigger: epic-tech-context
      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml"
      description: Use the PRD and Architecture to create a Tech-Spec for a specific epic
@ -36,32 +61,3 @@ agent:
    - trigger: validate-epic-tech-context
      validate-workflow: "{project-root}/bmad/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml"
      description: Validate latest Tech Spec against checklist
    - trigger: create-story
      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml"
      description: Create a Draft Story
    - trigger: validate-create-story
      validate-workflow: "{project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml"
      description: Validate Story Draft with Independent Review
    - trigger: story-context
      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/story-context/workflow.yaml"
      description: Assemble dynamic Story Context (XML) from latest docs and code and mark story ready for dev
    - trigger: validate-story-context
      validate-workflow: "{project-root}/bmad/bmm/workflows/4-implementation/story-context/workflow.yaml"
      description: Validate latest Story Context XML against checklist
    - trigger: story-ready-for-dev
      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/story-ready/workflow.yaml"
      description: Mark drafted story ready for dev without generating Story Context
    - trigger: epic-retrospective
      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml"
      data: "{project-root}/bmad/_cfg/agent-manifest.csv"
      description: Facilitate team retrospective after an epic is completed
    - trigger: correct-course
      workflow: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
      description: Execute correct-course task
--- a/src/modules/bmm/workflows/4-implementation/README.md
+++ b/src/modules/bmm/workflows/4-implementation/README.md
@ -30,7 +30,7 @@ Stories progress through a six-state flow representing their journey from idea t
 | **drafted**       | Story file has been created via `create-story` workflow                            | SM Agent      | ready-for-dev |
 | **ready-for-dev** | Story has been drafted, approved, and context created via `story-context` workflow | SM Agent      | in-progress   |
 | **in-progress**   | Developer is actively implementing the story                                       | Dev Agent     | review        |
-| **review**        | Implementation complete, under SM review via `code-review` workflow                | Dev Agent     | done          |
+| **review**        | Implementation complete, under SM review via `review-story` workflow               | Dev Agent     | done          |
 | **done**          | Story has been reviewed and completed                                              | Dev Agent     | -             |
 **File Indicators:**
@ -65,7 +65,7 @@ graph LR
    backlog --> drafted[drafted via create-story]
    drafted --> ready[ready-for-dev via story-context]
    ready --> progress[in-progress - dev starts]
-    progress --> review[review via code-review]
+    progress --> review[review via review-story]
    review --> done[done - dev completes]
 ```
@ -110,7 +110,7 @@ development_status:
 | **create-story**      | Draft a story from epics/PRD                       | story: backlog → drafted            |
 | **story-context**     | Add implementation context to story                | story: drafted → ready-for-dev      |
 | **dev-story**         | Developer implements the story                     | story: ready-for-dev → in-progress  |
-| **code-review**       | SM reviews implementation                          | story: in-progress → review         |
+| **review-story**      | SM reviews implementation                          | story: in-progress → review         |
 | **retrospective**     | Conduct epic retrospective                         | retrospective: optional → completed |
 | **correct-course**    | Course correction when needed                      | Various status updates              |
@ -150,7 +150,7 @@ Run this workflow:
 - Create epic contexts (`epic-tech-context`)
 - Draft stories (`create-story`)
 - Create story contexts (`story-context`)
- Review completed work (`code-review`)
+- Review completed work (`review-story`)
 - Update status in sprint-status.yaml
 ### Developer Agent
--- a/src/modules/bmm/workflows/4-implementation/code-review/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/code-review/instructions.md
@ -1,391 +0,0 @@
 # Senior Developer Review - Workflow Instructions
 ````xml
 <critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
 <critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
 <critical>Generate all documents in {document_output_language}</critical>
 <critical>This workflow performs a SYSTEMATIC Senior Developer Review on a story with status "review", validates EVERY acceptance criterion and EVERY completed task, appends structured review notes with evidence, and updates the story status based on outcome.</critical>
 <critical>If story_path is provided, use it. Otherwise, find the first story in sprint-status.yaml with status "review". If none found, offer ad-hoc review option.</critical>
 <critical>Ad-hoc review mode: User can specify any files to review and what to review for (quality, security, requirements, etc.). Creates standalone review report.</critical>
 <critical>SYSTEMATIC VALIDATION REQUIREMENT: For EVERY acceptance criterion, verify implementation with evidence (file:line). For EVERY task marked complete, verify it was actually done. Tasks marked complete but not done = HIGH SEVERITY finding.</critical>
 <critical>⚠️ ZERO TOLERANCE FOR LAZY VALIDATION ⚠️</critical>
 <critical>If you FAIL to catch even ONE task marked complete that was NOT actually implemented, or ONE acceptance criterion marked done that is NOT in the code with evidence, you have FAILED YOUR ONLY PURPOSE. This is an IMMEDIATE DISQUALIFICATION. No shortcuts. No assumptions. No "looks good enough." You WILL read every file. You WILL verify every claim. You WILL provide evidence (file:line) for EVERY validation. Failure to catch false completions = you failed humanity and the project. Your job is to be the uncompromising gatekeeper. DO YOUR JOB COMPLETELY OR YOU WILL BE REPLACED.</critical>
 <critical>Only modify the story file in these areas: Status, Dev Agent Record (Completion Notes), File List (if corrections needed), Change Log, and the appended "Senior Developer Review (AI)" section.</critical>
 <critical>Execute ALL steps in exact order; do NOT skip steps</critical>
 <critical>DOCUMENT OUTPUT: Technical review reports. Structured findings with severity levels and action items. User skill level ({user_skill_level}) affects conversation style ONLY, not review content.</critical>
 <workflow>
  <step n="1" goal="Find story ready for review" tag="sprint-status">
    <check if="{{story_path}} is provided">
      <action>Use {{story_path}} directly</action>
      <action>Read COMPLETE story file and parse sections</action>
      <action>Extract story_key from filename or story metadata</action>
      <action>Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to proceed"</action>
    </check>
    <check if="{{story_path}} is NOT provided">
      <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
      <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
      <action>Read ALL lines from beginning to end - do not skip any content</action>
      <action>Parse the development_status section completely</action>
      <action>Find FIRST story (reading in order from top to bottom) where:
        - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
        - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
        - Status value equals "review"
      </action>
      <check if="no story with status 'review' found">
        <output>📋 No stories with status "review" found
 **What would you like to do?**
 1. Run `dev-story` to implement and mark a story ready for review
 2. Check sprint-status.yaml for current story states
 3. Tell me what code to review and what to review it for
        </output>
        <ask>Select an option (1/2/3):</ask>
        <check if="option 3 selected">
          <ask>What code would you like me to review?
 Provide:
 - File path(s) or directory to review
 - What to review for:
  • General quality and standards
  • Requirements compliance
  • Security concerns
  • Performance issues
  • Architecture alignment
  • Something else (specify)
 Your input:</ask>
          <action>Parse user input to extract:
            - {{review_files}}: file paths or directories to review
            - {{review_focus}}: what aspects to focus on
            - {{review_context}}: any additional context provided
          </action>
          <action>Set ad_hoc_review_mode = true</action>
          <action>Skip to step 4 with custom scope</action>
        </check>
        <check if="option 1 or 2 or no option 3">
          <action>HALT</action>
        </check>
      </check>
      <action>Use the first story found with status "review"</action>
      <action>Resolve story file path in {{story_dir}}</action>
      <action>Read the COMPLETE story file</action>
    </check>
    <action>Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata</action>
    <action>Parse sections: Status, Story, Acceptance Criteria, Tasks/Subtasks (and completion states), Dev Notes, Dev Agent Record (Context Reference, Completion Notes, File List), Change Log</action>
    <action if="story cannot be read">HALT with message: "Unable to read story file"</action>
  </step>
  <step n="2" goal="Resolve story context file and specification inputs">
    <action>Locate story context file: Under Dev Agent Record → Context Reference, read referenced path(s). If missing, search {{output_folder}} for files matching pattern "story-{{epic_num}}.{{story_num}}*.context.xml" and use the most recent.</action>
    <action if="no story context file found">Continue but record a WARNING in review notes: "No story context file found"</action>
    <action>Locate Epic Tech Spec: Search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}})</action>
    <action if="no tech spec found">Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}"</action>
    <action>Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect testing, coding standards, security, and architectural patterns.</action>
  </step>
  <step n="3" goal="Detect tech stack and establish best-practice reference set">
    <action>Detect primary ecosystem(s) by scanning for manifests (e.g., package.json, pyproject.toml, go.mod, Dockerfile). Record key frameworks (e.g., Node/Express, React/Vue, Python/FastAPI, etc.).</action>
    <action>Synthesize a concise "Best-Practices and References" note capturing any updates or considerations that should influence the review (cite links and versions if available).</action>
  </step>
  <step n="4" goal="Systematic validation of implementation against acceptance criteria and tasks">
    <check if="ad_hoc_review_mode == true">
      <action>Use {{review_files}} as the file list to review</action>
      <action>Focus review on {{review_focus}} aspects specified by user</action>
      <action>Use {{review_context}} for additional guidance</action>
      <action>Skip acceptance criteria checking (no story context)</action>
      <action>If architecture docs exist, verify alignment with architectural constraints</action>
    </check>
    <check if="ad_hoc_review_mode != true">
      <critical>SYSTEMATIC VALIDATION - Check EVERY AC and EVERY task marked complete</critical>
      <action>From the story, read Acceptance Criteria section completely - parse into numbered list</action>
      <action>From the story, read Tasks/Subtasks section completely - parse ALL tasks and subtasks with their completion state ([x] = completed, [ ] = incomplete)</action>
      <action>From Dev Agent Record → File List, compile list of changed/added files. If File List is missing or clearly incomplete, search repo for recent changes relevant to the story scope (heuristics: filenames matching components/services/routes/tests inferred from ACs/tasks).</action>
      <critical>Step 4A: SYSTEMATIC ACCEPTANCE CRITERIA VALIDATION</critical>
      <action>Create AC validation checklist with one entry per AC</action>
      <action>For EACH acceptance criterion (AC1, AC2, AC3, etc.):
        1. Read the AC requirement completely
        2. Search changed files for evidence of implementation
        3. Determine: IMPLEMENTED, PARTIAL, or MISSING
        4. Record specific evidence (file:line references where AC is satisfied)
        5. Check for corresponding tests (unit/integration/E2E as applicable)
        6. If PARTIAL or MISSING: Flag as finding with severity based on AC criticality
        7. Document in AC validation checklist
      </action>
      <action>Generate AC Coverage Summary: "X of Y acceptance criteria fully implemented"</action>
      <critical>Step 4B: SYSTEMATIC TASK COMPLETION VALIDATION</critical>
      <action>Create task validation checklist with one entry per task/subtask</action>
      <action>For EACH task/subtask marked as COMPLETED ([x]):
        1. Read the task description completely
        2. Search changed files for evidence the task was actually done
        3. Determine: VERIFIED COMPLETE, QUESTIONABLE, or NOT DONE
        4. Record specific evidence (file:line references proving task completion)
        5. **CRITICAL**: If marked complete but NOT DONE → Flag as HIGH SEVERITY finding with message: "Task marked complete but implementation not found: [task description]"
        6. If QUESTIONABLE → Flag as MEDIUM SEVERITY finding: "Task completion unclear: [task description]"
        7. Document in task validation checklist
      </action>
      <action>For EACH task/subtask marked as INCOMPLETE ([ ]):
        1. Note it was not claimed to be complete
        2. Check if it was actually done anyway (sometimes devs forget to check boxes)
        3. If done but not marked: Note in review (helpful correction, not a finding)
      </action>
      <action>Generate Task Completion Summary: "X of Y completed tasks verified, Z questionable, W falsely marked complete"</action>
      <critical>Step 4C: CROSS-CHECK EPIC TECH-SPEC REQUIREMENTS</critical>
      <action>Cross-check epic tech-spec requirements and architecture constraints against the implementation intent in files.</action>
      <action if="critical architecture constraints are violated (e.g., layering, dependency rules)">flag as High Severity finding.</action>
      <critical>Step 4D: COMPILE VALIDATION FINDINGS</critical>
      <action>Compile all validation findings into structured list:
        - Missing AC implementations (severity based on AC importance)
        - Partial AC implementations (MEDIUM severity)
        - Tasks falsely marked complete (HIGH severity - this is critical)
        - Questionable task completions (MEDIUM severity)
        - Missing tests for ACs (severity based on AC criticality)
        - Architecture violations (HIGH severity)
      </action>
    </check>
  </step>
  <step n="5" goal="Perform code quality and risk review">
    <action>For each changed file, skim for common issues appropriate to the stack: error handling, input validation, logging, dependency injection, thread-safety/async correctness, resource cleanup, performance anti-patterns.</action>
    <action>Perform security review: injection risks, authZ/authN handling, secret management, unsafe defaults, un-validated redirects, CORS misconfigured, dependency vulnerabilities (based on manifests).</action>
    <action>Check tests quality: assertions are meaningful, edge cases covered, deterministic behavior, proper fixtures, no flakiness patterns.</action>
    <action>Capture concrete, actionable suggestions with severity (High/Med/Low) and rationale. When possible, suggest specific code-level changes (filenames + line ranges) without rewriting large sections.</action>
  </step>
  <step n="6" goal="Decide review outcome and prepare comprehensive notes">
    <action>Determine outcome based on validation results:
      - BLOCKED: Any HIGH severity finding (AC missing, task falsely marked complete, critical architecture violation)
      - CHANGES REQUESTED: Any MEDIUM severity findings or multiple LOW severity issues
      - APPROVE: All ACs implemented, all completed tasks verified, no significant issues
    </action>
    <action>Prepare a structured review report with sections:
      1. **Summary**: Brief overview of review outcome and key concerns
      2. **Outcome**: Approve | Changes Requested | Blocked (with justification)
      3. **Key Findings** (by severity):
         - HIGH severity issues first (especially falsely marked complete tasks)
         - MEDIUM severity issues
         - LOW severity issues
      4. **Acceptance Criteria Coverage**:
         - Include complete AC validation checklist from Step 4A
         - Show: AC# | Description | Status (IMPLEMENTED/PARTIAL/MISSING) | Evidence (file:line)
         - Summary: "X of Y acceptance criteria fully implemented"
         - List any missing or partial ACs with severity
      5. **Task Completion Validation**:
         - Include complete task validation checklist from Step 4B
         - Show: Task | Marked As | Verified As | Evidence (file:line)
         - **CRITICAL**: Highlight any tasks marked complete but not done in RED/bold
         - Summary: "X of Y completed tasks verified, Z questionable, W falsely marked complete"
      6. **Test Coverage and Gaps**:
         - Which ACs have tests, which don't
         - Test quality issues found
      7. **Architectural Alignment**:
         - Tech-spec compliance
         - Architecture violations if any
      8. **Security Notes**: Security findings if any
      9. **Best-Practices and References**: With links
      10. **Action Items**:
          - CRITICAL: ALL action items requiring code changes MUST have checkboxes for tracking
          - Format for actionable items: `- [ ] [Severity] Description (AC #X) [file: path:line]`
          - Format for informational notes: `- Note: Description (no action required)`
          - Imperative phrasing for action items
          - Map to related ACs or files with specific line references
          - Include suggested owners if clear
          - Example format:
            ```
            ### Action Items
            **Code Changes Required:**
            - [ ] [High] Add input validation on login endpoint (AC #1) [file: src/routes/auth.js:23-45]
            - [ ] [Med] Add unit test for invalid email format [file: tests/unit/auth.test.js]
            **Advisory Notes:**
            - Note: Consider adding rate limiting for production deployment
            - Note: Document the JWT expiration policy in README
            ```
    </action>
    <critical>The AC validation checklist and task validation checklist MUST be included in the review - this is the evidence trail</critical>
  </step>
  <step n="7" goal="Append review to story and update metadata">
    <check if="ad_hoc_review_mode == true">
      <action>Generate review report as a standalone document</action>
      <action>Save to {{output_folder}}/code-review-{{date}}.md</action>
      <action>Include sections:
        - Review Type: Ad-Hoc Code Review
        - Reviewer: {{user_name}}
        - Date: {{date}}
        - Files Reviewed: {{review_files}}
        - Review Focus: {{review_focus}}
        - Outcome: (Approve | Changes Requested | Blocked)
        - Summary
        - Key Findings
        - Test Coverage and Gaps
        - Architectural Alignment
        - Security Notes
        - Best-Practices and References (with links)
        - Action Items
      </action>
      <output>Review saved to: {{output_folder}}/code-review-{{date}}.md</output>
    </check>
    <check if="ad_hoc_review_mode != true">
      <action>Open {{story_path}} and append a new section at the end titled exactly: "Senior Developer Review (AI)".</action>
      <action>Insert subsections:
        - Reviewer: {{user_name}}
        - Date: {{date}}
        - Outcome: (Approve | Changes Requested | Blocked) with justification
        - Summary
        - Key Findings (by severity - HIGH/MEDIUM/LOW)
        - **Acceptance Criteria Coverage**:
          * Include complete AC validation checklist with table format
          * AC# | Description | Status | Evidence
          * Summary: X of Y ACs implemented
        - **Task Completion Validation**:
          * Include complete task validation checklist with table format
          * Task | Marked As | Verified As | Evidence
          * **Highlight falsely marked complete tasks prominently**
          * Summary: X of Y tasks verified, Z questionable, W false completions
        - Test Coverage and Gaps
        - Architectural Alignment
        - Security Notes
        - Best-Practices and References (with links)
        - Action Items:
          * CRITICAL: Format with checkboxes for tracking resolution
          * Code changes required: `- [ ] [Severity] Description [file: path:line]`
          * Advisory notes: `- Note: Description (no action required)`
          * Group by type: "Code Changes Required" and "Advisory Notes"
      </action>
      <action>Add a Change Log entry with date, version bump if applicable, and description: "Senior Developer Review notes appended".</action>
      <action>If {{update_status_on_result}} is true: update Status to {{status_on_approve}} when approved; to {{status_on_changes_requested}} when changes requested; otherwise leave unchanged.</action>
      <action>Save the story file.</action>
      <critical>MUST include the complete validation checklists - this is the evidence that systematic review was performed</critical>
    </check>
  </step>
  <step n="8" goal="Update sprint status based on review outcome" tag="sprint-status">
    <check if="ad_hoc_review_mode == true">
      <action>Skip sprint status update (no story context)</action>
      <output>📋 Ad-hoc review complete - no sprint status to update</output>
    </check>
    <check if="ad_hoc_review_mode != true">
      <action>Determine target status based on review outcome:
        - If {{outcome}} == "Approve" → target_status = "done"
        - If {{outcome}} == "Changes Requested" → target_status = "in-progress"
        - If {{outcome}} == "Blocked" → target_status = "review" (stay in review)
      </action>
      <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
      <action>Read all development_status entries to find {{story_key}}</action>
      <action>Verify current status is "review" (expected previous state)</action>
      <action>Update development_status[{{story_key}}] = {{target_status}}</action>
      <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
      <check if="update successful">
        <output>✅ Sprint status updated: review → {{target_status}}</output>
      </check>
      <check if="story key not found">
        <output>⚠️ Could not update sprint-status: {{story_key}} not found
 Review was saved to story file, but sprint-status.yaml may be out of sync.
        </output>
      </check>
    </check>
  </step>
  <step n="9" goal="Persist action items to tasks/backlog/epic">
    <check if="ad_hoc_review_mode == true">
      <action>All action items are included in the standalone review report</action>
      <ask if="action items exist">Would you like me to create tracking items for these action items? (backlog/tasks)</ask>
      <action if="user confirms">
        If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location.
        Append a row per action item with Date={{date}}, Story="Ad-Hoc Review", Epic="N/A", Type, Severity, Owner (or "TBD"), Status="Open", Notes with file refs and context.
      </action>
    </check>
    <check if="ad_hoc_review_mode != true">
      <action>Normalize Action Items into a structured list: description, severity (High/Med/Low), type (Bug/TechDebt/Enhancement), suggested owner (if known), related AC/file references.</action>
      <ask if="action items exist and 'story_tasks' in {{persist_targets}}">Add {{action_item_count}} follow-up items to story Tasks/Subtasks?</ask>
      <action if="user confirms or no ask needed">
        Append under the story's "Tasks / Subtasks" a new subsection titled "Review Follow-ups (AI)", adding each item as an unchecked checkbox in imperative form, prefixed with "[AI-Review]" and severity. Example: "- [ ] [AI-Review][High] Add input validation on server route /api/x (AC #2)".
      </action>
      <action if="{{persist_action_items}} == true and 'backlog_file' in {{persist_targets}}">
        If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location.
        Append a row per action item with Date={{date}}, Story={{epic_num}}.{{story_num}}, Epic={{epic_num}}, Type, Severity, Owner (or "TBD"), Status="Open", Notes with short context and file refs.
      </action>
      <action if="{{persist_action_items}} == true and ('epic_followups' in {{persist_targets}} or {{update_epic_followups}} == true)">
        If an epic Tech Spec was found: open it and create (if missing) a section titled "{{epic_followups_section_title}}". Append a bullet list of action items scoped to this epic with references back to Story {{epic_num}}.{{story_num}}.
      </action>
      <action>Save modified files.</action>
      <action>Optionally invoke tests or linters to verify quick fixes if any were applied as part of review (requires user approval for any dependency changes).</action>
    </check>
  </step>
  <step n="10" goal="Validation and completion">
    <invoke-task>Run validation checklist at {installed_path}/checklist.md using {project-root}/bmad/core/tasks/validate-workflow.xml</invoke-task>
    <action>Report workflow completion.</action>
    <check if="ad_hoc_review_mode == true">
      <output>**✅ Ad-Hoc Code Review Complete, {user_name}!**
 **Review Details:**
 - Files Reviewed: {{review_files}}
 - Review Focus: {{review_focus}}
 - Review Outcome: {{outcome}}
 - Action Items: {{action_item_count}}
 - Review Report: {{output_folder}}/code-review-{{date}}.md
 **Next Steps:**
 1. Review the detailed findings in the review report
 2. If changes requested: Address action items in the code
 3. If blocked: Resolve blockers before proceeding
 4. Re-run review on updated code if needed
      </output>
    </check>
    <check if="ad_hoc_review_mode != true">
      <output>**✅ Story Review Complete, {user_name}!**
 **Story Details:**
 - Story: {{epic_num}}.{{story_num}}
 - Story Key: {{story_key}}
 - Review Outcome: {{outcome}}
 - Sprint Status: {{target_status}}
 - Action Items: {{action_item_count}}
 **Next Steps:**
 1. Review the Senior Developer Review notes appended to story
 2. If approved: Story is marked done, continue with next story
 3. If changes requested: Address action items and re-run `dev-story`
 4. If blocked: Resolve blockers before proceeding
      </output>
    </check>
  </step>
 </workflow>
 ````
--- a/src/modules/bmm/workflows/4-implementation/create-story/README.md
+++ b/src/modules/bmm/workflows/4-implementation/create-story/README.md
@ -85,7 +85,7 @@ The create-story workflow is step 1 in the v6 implementation cycle:
 1. **SM: create-story** ← You are here
 2. SM: story-context (adds JIT technical expertise)
 3. DEV: dev-story (implements with generated context)
-4. DEV/SR: code-review (validates completion)
+4. DEV/SR: review-story (validates completion)
 5. If needed: correct-course (adjusts direction)
 6. After epic: retrospective (captures learnings)
--- a/src/modules/bmm/workflows/4-implementation/create-story/checklist.md
+++ b/src/modules/bmm/workflows/4-implementation/create-story/checklist.md
@ -1,240 +1,39 @@
-# Create Story Quality Validation Checklist
+---
 title: 'Create Story Checklist'
 validation-target: 'Newly generated story markdown file'
 required-inputs:
  - 'epics.md (preferred) or PRD'
 optional-inputs:
  - 'architecture document for architecture context'
 validation-rules:
  - 'Story structure matches sections: Status, Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Change Log, Dev Agent Record'
  - 'Dev Notes include Project Structure Notes and References subsections'
  - 'All non-trivial technical notes include a source citation'
  - 'Tasks include explicit testing subtasks based on testing strategy'
 ---
-```xml
+# Create Story Checklist
 <critical>This validation runs in a FRESH CONTEXT by an independent validator agent</critical>
 <critical>The validator audits story quality and offers to improve if issues are found</critical>
 <critical>Load only the story file and necessary source documents - do NOT load workflow instructions</critical>
-<validation-checklist>
+## Document Structure
-<expectations>
+- [ ] Title includes story id and title
-**What create-story workflow should have accomplished:**
+- [ ] Status set to Draft
 - [ ] Story section present with As a / I want / so that
 - [ ] Acceptance Criteria is a numbered list
 - [ ] Tasks/Subtasks present with checkboxes
 - [ ] Dev Notes includes architecture/testing context
 - [ ] Change Log table initialized
 - [ ] Dev Agent Record sections present (Context Reference, Agent Model Used, Debug Log References, Completion Notes, File List)
-1. **Previous Story Continuity:** If a previous story exists (status: done/review/in-progress), current story should have "Learnings from Previous Story" subsection in Dev Notes that references: new files created, completion notes, architectural decisions, unresolved review items
+## Content Quality
 2. **Source Document Coverage:** Story should cite tech spec (if exists), epics, PRD, and relevant architecture docs (architecture.md, testing-strategy.md, coding-standards.md, unified-project-structure.md)
 3. **Requirements Traceability:** ACs sourced from tech spec (preferred) or epics, not invented
 4. **Dev Notes Quality:** Specific guidance with citations, not generic advice
 5. **Task-AC Mapping:** Every AC has tasks, every task references AC, testing subtasks present
 6. **Structure:** Status="drafted", proper story statement, Dev Agent Record sections initialized
 </expectations>
-## Validation Steps
+- [ ] Acceptance Criteria sourced from epics/PRD (or explicitly confirmed by user)
 - [ ] Tasks reference AC numbers where applicable
 - [ ] Dev Notes do not invent details; cite sources where possible
 - [ ] File saved to stories directory from config (dev_story_location)
 - [ ] If creating a new story number, epics.md explicitly enumerates this story under the target epic; otherwise generation HALTED with instruction to run PM/SM `*correct-course` (open `{project-root}/bmad/bmm/agents/pm.md` or `{project-root}/bmad/bmm/agents/sm.md` and execute `*correct-course`)
-### 1. Load Story and Extract Metadata
+## Optional Post-Generation
 - [ ] Load story file: {{story_file_path}}
 - [ ] Parse sections: Status, Story, ACs, Tasks, Dev Notes, Dev Agent Record, Change Log
 - [ ] Extract: epic_num, story_num, story_key, story_title
 - [ ] Initialize issue tracker (Critical/Major/Minor)
-### 2. Previous Story Continuity Check
+- [ ] Story Context generation run (if auto_run_context)
-
+- [ ] Context Reference recorded in story
 **Find previous story:**
 - [ ] Load {output_folder}/sprint-status.yaml
 - [ ] Find current {{story_key}} in development_status
 - [ ] Identify story entry immediately above (previous story)
 - [ ] Check previous story status
 **If previous story status is done/review/in-progress:**
 - [ ] Load previous story file: {story_dir}/{{previous_story_key}}.md
 - [ ] Extract: Dev Agent Record (Completion Notes, File List with NEW/MODIFIED)
 - [ ] Extract: Senior Developer Review section if present
 - [ ] Count unchecked [ ] items in Review Action Items
 - [ ] Count unchecked [ ] items in Review Follow-ups (AI)
 **Validate current story captured continuity:**
 - [ ] Check: "Learnings from Previous Story" subsection exists in Dev Notes
  - If MISSING and previous story has content → **CRITICAL ISSUE**
 - [ ] If subsection exists, verify it includes:
  - [ ] References to NEW files from previous story → If missing → **MAJOR ISSUE**
  - [ ] Mentions completion notes/warnings → If missing → **MAJOR ISSUE**
  - [ ] Calls out unresolved review items (if any exist) → If missing → **CRITICAL ISSUE**
  - [ ] Cites previous story: [Source: stories/{{previous_story_key}}.md]
 **If previous story status is backlog/drafted:**
 - [ ] No continuity expected (note this)
 **If no previous story exists:**
 - [ ] First story in epic, no continuity expected
 ### 3. Source Document Coverage Check
 **Build available docs list:**
 - [ ] Check exists: tech-spec-epic-{{epic_num}}*.md in {tech_spec_search_dir}
 - [ ] Check exists: {output_folder}/epics.md
 - [ ] Check exists: {output_folder}/PRD.md
 - [ ] Check exists in {output_folder}/ or {project-root}/docs/:
  - architecture.md, testing-strategy.md, coding-standards.md
  - unified-project-structure.md, tech-stack.md
  - backend-architecture.md, frontend-architecture.md, data-models.md
 **Validate story references available docs:**
 - [ ] Extract all [Source: ...] citations from story Dev Notes
 - [ ] Tech spec exists but not cited → **CRITICAL ISSUE**
 - [ ] Epics exists but not cited → **CRITICAL ISSUE**
 - [ ] Architecture.md exists → Read for relevance → If relevant but not cited → **MAJOR ISSUE**
 - [ ] Testing-strategy.md exists → Check Dev Notes mentions testing standards → If not → **MAJOR ISSUE**
 - [ ] Testing-strategy.md exists → Check Tasks have testing subtasks → If not → **MAJOR ISSUE**
 - [ ] Coding-standards.md exists → Check Dev Notes references standards → If not → **MAJOR ISSUE**
 - [ ] Unified-project-structure.md exists → Check Dev Notes has "Project Structure Notes" subsection → If not → **MAJOR ISSUE**
 **Validate citation quality:**
 - [ ] Verify cited file paths are correct and files exist → Bad citations → **MAJOR ISSUE**
 - [ ] Check citations include section names, not just file paths → Vague citations → **MINOR ISSUE**
 ### 4. Acceptance Criteria Quality Check
 - [ ] Extract Acceptance Criteria from story
 - [ ] Count ACs: {{ac_count}} (if 0 → **CRITICAL ISSUE** and halt)
 - [ ] Check story indicates AC source (tech spec, epics, PRD)
 **If tech spec exists:**
 - [ ] Load tech spec
 - [ ] Search for this story number
 - [ ] Extract tech spec ACs for this story
 - [ ] Compare story ACs vs tech spec ACs → If mismatch → **MAJOR ISSUE**
 **If no tech spec but epics.md exists:**
 - [ ] Load epics.md
 - [ ] Search for Epic {{epic_num}}, Story {{story_num}}
 - [ ] Story not found in epics → **CRITICAL ISSUE** (should have halted)
 - [ ] Extract epics ACs
 - [ ] Compare story ACs vs epics ACs → If mismatch without justification → **MAJOR ISSUE**
 **Validate AC quality:**
 - [ ] Each AC is testable (measurable outcome)
 - [ ] Each AC is specific (not vague)
 - [ ] Each AC is atomic (single concern)
 - [ ] Vague ACs found → **MINOR ISSUE**
 ### 5. Task-AC Mapping Check
 - [ ] Extract Tasks/Subtasks from story
 - [ ] For each AC: Search tasks for "(AC: #{{ac_num}})" reference
  - [ ] AC has no tasks → **MAJOR ISSUE**
 - [ ] For each task: Check if references an AC number
  - [ ] Tasks without AC refs (and not testing/setup) → **MINOR ISSUE**
 - [ ] Count tasks with testing subtasks
  - [ ] Testing subtasks < ac_count → **MAJOR ISSUE**
 ### 6. Dev Notes Quality Check
 **Check required subsections exist:**
 - [ ] Architecture patterns and constraints
 - [ ] References (with citations)
 - [ ] Project Structure Notes (if unified-project-structure.md exists)
 - [ ] Learnings from Previous Story (if previous story has content)
 - [ ] Missing required subsections → **MAJOR ISSUE**
 **Validate content quality:**
 - [ ] Architecture guidance is specific (not generic "follow architecture docs") → If generic → **MAJOR ISSUE**
 - [ ] Count citations in References subsection
  - [ ] No citations → **MAJOR ISSUE**
  - [ ] < 3 citations and multiple arch docs exist → **MINOR ISSUE**
 - [ ] Scan for suspicious specifics without citations:
  - API endpoints, schema details, business rules, tech choices
  - [ ] Likely invented details found → **MAJOR ISSUE**
 ### 7. Story Structure Check
 - [ ] Status = "drafted" → If not → **MAJOR ISSUE**
 - [ ] Story section has "As a / I want / so that" format → If malformed → **MAJOR ISSUE**
 - [ ] Dev Agent Record has required sections:
  - Context Reference, Agent Model Used, Debug Log References, Completion Notes List, File List
  - [ ] Missing sections → **MAJOR ISSUE**
 - [ ] Change Log initialized → If missing → **MINOR ISSUE**
 - [ ] File in correct location: {story_dir}/{{story_key}}.md → If not → **MAJOR ISSUE**
 ### 8. Unresolved Review Items Alert
 **CRITICAL CHECK for incomplete review items from previous story:**
 - [ ] If previous story has "Senior Developer Review (AI)" section:
  - [ ] Count unchecked [ ] items in "Action Items"
  - [ ] Count unchecked [ ] items in "Review Follow-ups (AI)"
  - [ ] If unchecked items > 0:
    - [ ] Check current story "Learnings from Previous Story" mentions these
    - [ ] If NOT mentioned → **CRITICAL ISSUE** with details:
      - List all unchecked items with severity
      - Note: "These may represent epic-wide concerns"
      - Required: Add to Learnings section with note about pending items
 ## Validation Report Generation
 **Calculate severity counts:**
 - Critical: {{critical_count}}
 - Major: {{major_count}}
 - Minor: {{minor_count}}
 **Determine outcome:**
 - Critical > 0 OR Major > 3 → **FAIL**
 - Major ≤ 3 and Critical = 0 → **PASS with issues**
 - All = 0 → **PASS**
 **Generate report:**
 ```
 # Story Quality Validation Report
 Story: {{story_key}} - {{story_title}}
 Outcome: {{outcome}} (Critical: {{critical_count}}, Major: {{major_count}}, Minor: {{minor_count}})
 ## Critical Issues (Blockers)
 {{list_each_with_description_and_evidence}}
 ## Major Issues (Should Fix)
 {{list_each_with_description_and_evidence}}
 ## Minor Issues (Nice to Have)
 {{list_each_with_description}}
 ## Successes
 {{list_what_was_done_well}}
 ```
 ## User Alert and Remediation
 **If FAIL:**
 - Show issues summary and top 3 issues
 - Offer options: (1) Auto-improve story, (2) Show detailed findings, (3) Fix manually, (4) Accept as-is
 - If option 1: Re-load source docs, regenerate affected sections, re-run validation
 **If PASS with issues:**
 - Show issues list
 - Ask: "Improve story? (y/n)"
 - If yes: Enhance story with missing items
 **If PASS:**
 - Confirm: All quality standards met
 - List successes
 - Ready for story-context generation
 </validation-checklist>
 ```
 ## Quick Reference
 **Validation runs in fresh context and checks:**
 1. ✅ Previous story continuity captured (files, notes, **unresolved review items**)
 2. ✅ All relevant source docs discovered and cited
 3. ✅ ACs match tech spec/epics exactly
 4. ✅ Tasks cover all ACs with testing
 5. ✅ Dev Notes have specific guidance with citations (not generic)
 6. ✅ Structure and metadata complete
 **Severity Levels:**
 - **CRITICAL** = Missing previous story reference, missing tech spec cite, unresolved review items not called out, story not in epics
 - **MAJOR** = Missing arch docs, missing files from previous story, vague Dev Notes, ACs don't match source, no testing subtasks
 - **MINOR** = Vague citations, orphan tasks, missing Change Log
 **Outcome Triggers:**
 - **FAIL** = Any critical OR >3 major issues
 - **PASS with issues** = ≤3 major issues, no critical
 - **PASS** = All checks passed
--- a/src/modules/bmm/workflows/4-implementation/create-story/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/create-story/instructions.md
@ -1,6 +1,6 @@
 # Create Story - Workflow Instructions (Spec-compliant, non-interactive by default)
-````xml
+```xml
 <critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
 <critical>Generate all documents in {document_output_language}</critical>
@ -17,74 +17,6 @@
  </step>
  <step n="2" goal="Discover and load source documents">
    <critical>PREVIOUS STORY CONTINUITY: Essential for maintaining context and learning from prior development</critical>
    <action>Find the previous completed story to extract dev agent learnings and review findings:
      1. Load {{output_folder}}/sprint-status.yaml COMPLETELY
      2. Find current {{story_key}} in development_status section
      3. Identify the story entry IMMEDIATELY ABOVE current story (previous row in file order)
      4. If previous story exists:
         - Extract {{previous_story_key}}
         - Check previous story status (done, in-progress, review, etc.)
         - If status is "done", "review", or "in-progress" (has some completion):
           * Construct path: {{story_dir}}/{{previous_story_key}}.md
           * Load the COMPLETE previous story file
           * Parse ALL sections comprehensively:
             A) Dev Agent Record → Completion Notes List:
                - New patterns/services created (to reuse, not recreate)
                - Architectural deviations or decisions made
                - Technical debt deferred to future stories
                - Warnings or recommendations for next story
                - Interfaces/methods created for reuse
             B) Dev Agent Record → Debug Log References:
                - Issues encountered and solutions
                - Gotchas or unexpected challenges
                - Workarounds applied
             C) Dev Agent Record → File List:
                - Files created (NEW) - understand new capabilities
                - Files modified (MODIFIED) - track evolving components
                - Files deleted (DELETED) - removed functionality
             D) Dev Notes:
                - Any "future story" notes or TODOs
                - Patterns established
                - Constraints discovered
             E) Senior Developer Review (AI) section (if present):
                - Review outcome (Approve/Changes Requested/Blocked)
                - Unresolved action items (unchecked [ ] items)
                - Key findings that might affect this story
                - Architectural concerns raised
             F) Senior Developer Review → Action Items (if present):
                - Check for unchecked [ ] items still pending
                - Note any systemic issues that apply to multiple stories
             G) Review Follow-ups (AI) tasks (if present):
                - Check for unchecked [ ] review tasks still pending
                - Determine if they're epic-wide concerns
             H) Story Status:
                - If "review" or "in-progress" - incomplete, note what's pending
                - If "done" - confirmed complete
           * Store ALL findings as {{previous_story_learnings}} with structure:
             - new_files: [list]
             - modified_files: [list]
             - new_services: [list with descriptions]
             - architectural_decisions: [list]
             - technical_debt: [list]
             - warnings_for_next: [list]
             - review_findings: [list if review exists]
             - pending_items: [list of unchecked action items]
         - If status is "backlog" or "drafted":
           * Set {{previous_story_learnings}} = "Previous story not yet implemented"
      5. If no previous story exists (first story in epic):
         - Set {{previous_story_learnings}} = "First story in epic - no predecessor context"
    </action>
    <action>If {{tech_spec_file}} empty: derive from {{tech_spec_glob_template}} with {{epic_num}} and search {{tech_spec_search_dir}} recursively. If multiple, pick most recent by modified time.</action>
    <action>Build a prioritized document set for this epic:
      1) tech_spec_file (epic-scoped)
@ -150,20 +82,8 @@ Will update existing story file rather than creating new one.
  </step>
  <step n="5" goal="Project structure alignment and lessons learned">
-    <action>Review {{previous_story_learnings}} and extract actionable intelligence:
+    <action>If a previous story exists, scan its "Dev Agent Record" for completion notes and known deviations; summarize any carry-overs relevant to this story.</action>
      - New patterns/services created → Note for reuse (DO NOT recreate)
      - Architectural deviations → Understand and maintain consistency
      - Technical debt items → Assess if this story should address them
      - Files modified → Understand current state of evolving components
      - Warnings/recommendations → Apply to this story's approach
      - Review findings → Learn from issues found in previous story
      - Pending action items → Determine if epic-wide concerns affect this story
    </action>
    <action>If unified-project-structure.md present: align expected file paths, module names, and component locations; note any potential conflicts.</action>
    <action>Cross-reference {{previous_story_learnings}}.new_files with project structure to understand where new capabilities are located.</action>
    <template-output file="{default_output_file}">structure_alignment_summary</template-output>
  </step>
@ -181,32 +101,6 @@ Will update existing story file rather than creating new one.
    <template-output file="{default_output_file}">story_header</template-output>
    <template-output file="{default_output_file}">story_body</template-output>
    <template-output file="{default_output_file}">dev_notes_with_citations</template-output>
    <action>If {{previous_story_learnings}} contains actionable items (not "First story" or "not yet implemented"):
      - Add "Learnings from Previous Story" subsection to Dev Notes
      - Include relevant completion notes, new files/patterns, deviations
      - Cite previous story file as reference [Source: stories/{{previous_story_key}}.md]
      - Highlight interfaces/services to REUSE (not recreate)
      - Note any technical debt to address in this story
      - List pending review items that affect this story (if any)
      - Reference specific files created: "Use {{file_path}} for {{purpose}}"
      - Format example:
        ```
        ### Learnings from Previous Story
        **From Story {{previous_story_key}} (Status: {{previous_status}})**
        - **New Service Created**: `AuthService` base class available at `src/services/AuthService.js` - use `AuthService.register()` method
        - **Architectural Change**: Switched from session-based to JWT authentication
        - **Schema Changes**: User model now includes `passwordHash` field, migration applied
        - **Technical Debt**: Email verification skipped, should be included in this or subsequent story
        - **Testing Setup**: Auth test suite initialized at `tests/integration/auth.test.js` - follow patterns established there
        - **Pending Review Items**: Rate limiting mentioned in review - consider for this story
        [Source: stories/{{previous_story_key}}.md#Dev-Agent-Record]
        ```
    </action>
    <template-output file="{default_output_file}">change_log</template-output>
  </step>
@ -226,10 +120,11 @@ Will update existing story file rather than creating new one.
      <output>⚠️ Could not update story status: {{story_key}} not found in sprint-status.yaml
 Story file was created successfully, but sprint-status.yaml was not updated.
-You may need to run sprint-planning to refresh tracking, or manually set the story row status to `drafted`.
+You may need to run sprint-planning to refresh tracking.
      </output>
    </check>
    <check>If {{auto_run_context}} == true → <invoke-workflow path="{project-root}/bmad/bmm/workflows/4-implementation/story-context/workflow.yaml">Pass {{story_path}} = {default_output_file}</invoke-workflow></check>
    <action>Report created/updated story path</action>
    <output>**✅ Story Created Successfully, {user_name}!**
@ -249,4 +144,4 @@ You may need to run sprint-planning to refresh tracking, or manually set the sto
  </step>
 </workflow>
-````
+```
--- a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml
@ -33,6 +33,7 @@ variables:
  story_title: "" # Will be elicited if not derivable
  epic_num: 1
  story_num: 1
  auto_run_context: true # Optionally run story-context after creation
  non_interactive: true # Generate without elicitation; avoid interactive prompts
 # Output configuration
--- a/src/modules/bmm/workflows/4-implementation/dev-story/README.md
+++ b/src/modules/bmm/workflows/4-implementation/dev-story/README.md
@ -4,7 +4,7 @@ The dev-story workflow is where v6's just-in-time context approach delivers its
 The workflow operates with two critical inputs: the story file (created by SM's create-story) containing acceptance criteria, tasks, and requirements; and the story-context XML (generated by SM's story-context) providing just-in-time expertise injection tailored to the story's technical needs. This dual-input approach ensures the developer has both the "what" (from the story) and the "how" (from the context) needed for successful implementation. The workflow iterates through tasks sequentially, implementing code, writing tests, and updating the story document's allowed sections until all tasks are complete.
-A critical aspect of v6 flow is that dev-story may be run multiple times for the same story. Initially run to implement the story, it may be run again after code-review identifies issues that need correction. The workflow intelligently resumes from incomplete tasks, making it ideal for both initial implementation and post-review fixes. The DEV agent maintains strict boundaries on what can be modified in the story file—only Tasks/Subtasks checkboxes, Dev Agent Record, File List, Change Log, and Status may be updated, preserving the story's requirements integrity.
+A critical aspect of v6 flow is that dev-story may be run multiple times for the same story. Initially run to implement the story, it may be run again after review-story identifies issues that need correction. The workflow intelligently resumes from incomplete tasks, making it ideal for both initial implementation and post-review fixes. The DEV agent maintains strict boundaries on what can be modified in the story file—only Tasks/Subtasks checkboxes, Dev Agent Record, File List, Change Log, and Status may be updated, preserving the story's requirements integrity.
 ## Usage
@ -20,7 +20,7 @@ The DEV runs this workflow:
 - After SM completes both create-story and story-context
 - When a story status is "Draft" or "Approved" (ready for development)
- After code-review identifies issues requiring fixes
+- After review-story identifies issues requiring fixes
 - To resume work on a partially completed story
 ## Inputs
@ -82,7 +82,7 @@ The DEV runs this workflow:
 **Test-Driven Approach**: For each task, the workflow emphasizes writing tests that verify acceptance criteria before or alongside implementation, ensuring requirements are actually met.
-**Resumable Implementation**: If the workflow is run again on a story with incomplete tasks (e.g., after code-review finds issues), it intelligently resumes from where it left off rather than starting over.
+**Resumable Implementation**: If the workflow is run again on a story with incomplete tasks (e.g., after review-story finds issues), it intelligently resumes from where it left off rather than starting over.
 ## Integration with v6 Flow
@ -91,7 +91,7 @@ The dev-story workflow is step 3 in the v6 implementation cycle:
 1. SM: create-story (generates the story specification)
 2. SM: story-context (adds JIT technical expertise)
 3. **DEV: dev-story** ← You are here (initial implementation)
-4. DEV/SR: code-review (validates completion)
+4. DEV/SR: review-story (validates completion)
 5. If issues found: **DEV: dev-story** ← May return here for fixes
 6. After epic: retrospective (captures learnings)
@ -182,7 +182,7 @@ As a {role}, I want to {action} so that {benefit}
 **Update Incrementally**: Update the story file after each task completion rather than batching updates at the end.
-**Respect Boundaries**: Never modify acceptance criteria or story description. If they seem wrong, that's a code-review or correct-course issue, not a dev-story fix.
+**Respect Boundaries**: Never modify acceptance criteria or story description. If they seem wrong, that's a review-story or correct-course issue, not a dev-story fix.
 **Use Context Guidance**: Actively reference the story-context for patterns, gotchas, and best practices. It's there to help you succeed.
@ -196,11 +196,11 @@ As a {role}, I want to {action} so that {benefit}
 **Can't Modify Story Section**: Remember only Tasks, Dev Agent Record, File List, Change Log, and Status can be modified. Other sections are immutable.
-**Resuming After Review**: If code-review found issues, the workflow automatically picks up from incomplete tasks when run again.
+**Resuming After Review**: If review-story found issues, the workflow automatically picks up from incomplete tasks when run again.
 ## Related Workflows
 - **create-story**: Creates the story specification (run by SM)
 - **story-context**: Generates the context XML (run by SM)
- **code-review**: Validates implementation (run by SR/DEV)
+- **review-story**: Validates implementation (run by SR/DEV)
 - **correct-course**: Handles major issues or scope changes (run by SM)
--- a/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/dev-story/instructions.md
@ -72,47 +72,7 @@ Proceeding with story file only. For better context, consider running `story-con
    <action if="incomplete task or subtask requirements ambiguous">ASK user to clarify or HALT</action>
  </step>
-  <step n="1.5" goal="Detect review continuation and extract review context">
+  <step n="1.5" goal="Mark story in-progress" tag="sprint-status">
    <critical>Determine if this is a fresh start or continuation after code review</critical>
    <action>Check if "Senior Developer Review (AI)" section exists in the story file</action>
    <action>Check if "Review Follow-ups (AI)" subsection exists under Tasks/Subtasks</action>
    <check if="Senior Developer Review section exists">
      <action>Set review_continuation = true</action>
      <action>Extract from "Senior Developer Review (AI)" section:
        - Review outcome (Approve/Changes Requested/Blocked)
        - Review date
        - Total action items with checkboxes (count checked vs unchecked)
        - Severity breakdown (High/Med/Low counts)
      </action>
      <action>Count unchecked [ ] review follow-up tasks in "Review Follow-ups (AI)" subsection</action>
      <action>Store list of unchecked review items as {{pending_review_items}}</action>
      <output>⏯️ **Resuming Story After Code Review** ({{review_date}})
 **Review Outcome:** {{review_outcome}}
 **Action Items:** {{unchecked_review_count}} remaining to address
 **Priorities:** {{high_count}} High, {{med_count}} Medium, {{low_count}} Low
 **Strategy:** Will prioritize review follow-up tasks (marked [AI-Review]) before continuing with regular tasks.
      </output>
    </check>
    <check if="Senior Developer Review section does NOT exist">
      <action>Set review_continuation = false</action>
      <action>Set {{pending_review_items}} = empty</action>
      <output>🚀 **Starting Fresh Implementation**
 Story: {{story_key}}
 Context file: {{context_available}}
 First incomplete task: {{first_task_description}}
      </output>
    </check>
  </step>
  <step n="1.6" goal="Mark story in-progress" tag="sprint-status">
    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
    <action>Read all development_status entries to find {{story_key}}</action>
    <action>Get current status value for development_status[{{story_key}}]</action>
@ -166,34 +126,10 @@ Expected ready-for-dev or in-progress. Continuing anyway...
    <action if="new tests fail">STOP and fix before continuing</action>
  </step>
-  <step n="5" goal="Mark task complete, track review resolutions, and update story">
+  <step n="5" goal="Mark task complete and update story">
    <critical>If task is a review follow-up, must mark BOTH the task checkbox AND the corresponding action item in the review section</critical>
    <action>Check if completed task has [AI-Review] prefix (indicates review follow-up task)</action>
    <check if="task is review follow-up">
      <action>Extract review item details (severity, description, related AC/file)</action>
      <action>Add to resolution tracking list: {{resolved_review_items}}</action>
      <!-- Mark task in Review Follow-ups section -->
      <action>Mark task checkbox [x] in "Tasks/Subtasks → Review Follow-ups (AI)" section</action>
      <!-- CRITICAL: Also mark corresponding action item in review section -->
      <action>Find matching action item in "Senior Developer Review (AI) → Action Items" section by matching description</action>
      <action>Mark that action item checkbox [x] as resolved</action>
      <action>Add to Dev Agent Record → Completion Notes: "✅ Resolved review finding [{{severity}}]: {{description}}"</action>
    </check>
    <action>ONLY mark the task (and subtasks) checkbox with [x] if ALL tests pass and validation succeeds</action>
    <action>Update File List section with any new, modified, or deleted files (paths relative to repo root)</action>
    <action>Add completion notes to Dev Agent Record if significant changes were made (summarize intent, approach, and any follow-ups)</action>
    <check if="review_continuation == true and {{resolved_review_items}} is not empty">
      <action>Count total resolved review items in this session</action>
      <action>Add Change Log entry: "Addressed code review findings - {{resolved_count}} items resolved (Date: {{date}})"</action>
    </check>
    <action>Save the story file</action>
    <action>Determine if more incomplete tasks remain</action>
    <action if="more tasks remain"><goto step="2">Next task</goto></action>
@ -252,7 +188,7 @@ Story is marked Ready for Review in file, but sprint-status.yaml may be out of s
      - Review the implemented story yourself and test the changes
      - Verify all acceptance criteria are met
      - Ensure deployment readiness if applicable
-      - Run `code-review` workflow for peer review
+      - Run `review-story` workflow for peer review
      - Check sprint-status.yaml to see project progress
    </action>
    <action>Remain flexible - allow user to choose their own path or ask for other assistance</action>
--- a/src/modules/bmm/workflows/4-implementation/review-story/README.md
+++ b/src/modules/bmm/workflows/4-implementation/review-story/README.md
@ -1,6 +1,6 @@
-# Review Story (Senior Developer Code Review)
+# Review Story (Senior Developer Review)
-Perform an AI-driven Senior Developer Code Review on a story flagged "Ready for Review". The workflow ingests the story, its Story Context, and the epic’s Tech Spec, consults local docs, uses enabled MCP servers for up-to-date best practices (with web search fallback), and appends structured review notes to the story.
+Perform an AI-driven Senior Developer Review on a story flagged "Ready for Review". The workflow ingests the story, its Story Context, and the epic’s Tech Spec, consults local docs, uses enabled MCP servers for up-to-date best practices (with web search fallback), and appends structured review notes to the story.
 ## What It Does
@ -16,7 +16,10 @@ Perform an AI-driven Senior Developer Code Review on a story flagged "Ready for
 ## How to Invoke
- Tell the Dev Agent to perform a \*code-review after loading the dev agent. This is a context intensive operation so this should not be done in the same context as a just completed dev session - clear the context, reload the dev, then run code-review!
+- By workflow name (if supported):
  - `workflow review-story`
 - By path:
  - `workflow {project-root}/bmad/bmm/workflows/4-implementation/review-story/workflow.yaml`
 ## Inputs and Variables
--- a/src/modules/bmm/workflows/4-implementation/review-story/backlog_template.md
+++ b/src/modules/bmm/workflows/4-implementation/review-story/backlog_template.md
--- a/src/modules/bmm/workflows/4-implementation/review-story/checklist.md
+++ b/src/modules/bmm/workflows/4-implementation/review-story/checklist.md
--- a/src/modules/bmm/workflows/4-implementation/review-story/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/review-story/instructions.md
@ -0,0 +1,176 @@
 # Senior Developer Review - Workflow Instructions
 ```xml
 <critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
 <critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
 <critical>Generate all documents in {document_output_language}</critical>
 <critical>This workflow performs a Senior Developer Review on a story with status "review", appends structured review notes, and updates the story status based on outcome.</critical>
 <critical>If story_path is provided, use it. Otherwise, find the first story in sprint-status.yaml with status "review". If none found, HALT and ask for clarification.</critical>
 <critical>Only modify the story file in these areas: Status, Dev Agent Record (Completion Notes), File List (if corrections needed), Change Log, and the appended "Senior Developer Review (AI)" section.</critical>
 <critical>Execute ALL steps in exact order; do NOT skip steps</critical>
 <critical>DOCUMENT OUTPUT: Technical review reports. Structured findings with severity levels and action items. User skill level ({user_skill_level}) affects conversation style ONLY, not review content.</critical>
 <workflow>
  <step n="1" goal="Find story ready for review" tag="sprint-status">
    <check if="{{story_path}} is provided">
      <action>Use {{story_path}} directly</action>
      <action>Read COMPLETE story file and parse sections</action>
      <action>Extract story_key from filename or story metadata</action>
      <action>Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to proceed"</action>
    </check>
    <check if="{{story_path}} is NOT provided">
      <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
      <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
      <action>Read ALL lines from beginning to end - do not skip any content</action>
      <action>Parse the development_status section completely</action>
      <action>Find FIRST story (reading in order from top to bottom) where:
        - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
        - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
        - Status value equals "review"
      </action>
      <check if="no story with status 'review' found">
        <output>📋 No stories with status "review" found
 **Next Steps:**
 1. Run `dev-story` to implement and mark a story ready for review
 2. Check sprint-status.yaml for current story states
        </output>
        <action>HALT</action>
      </check>
      <action>Use the first story found with status "review"</action>
      <action>Resolve story file path in {{story_dir}}</action>
      <action>Read the COMPLETE story file</action>
    </check>
    <action>Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata</action>
    <action>Parse sections: Status, Story, Acceptance Criteria, Tasks/Subtasks (and completion states), Dev Notes, Dev Agent Record (Context Reference, Completion Notes, File List), Change Log</action>
    <action if="story cannot be read">HALT with message: "Unable to read story file"</action>
  </step>
  <step n="2" goal="Resolve story context file and specification inputs">
    <action>Locate story context file: Under Dev Agent Record → Context Reference, read referenced path(s). If missing, search {{output_folder}} for files matching pattern "story-{{epic_num}}.{{story_num}}*.context.xml" and use the most recent.</action>
    <action if="no story context file found">Continue but record a WARNING in review notes: "No story context file found"</action>
    <action>Locate Epic Tech Spec: Search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}})</action>
    <action if="no tech spec found">Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}"</action>
    <action>Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect testing, coding standards, security, and architectural patterns.</action>
  </step>
  <step n="3" goal="Detect tech stack and establish best-practice reference set">
    <action>Detect primary ecosystem(s) by scanning for manifests (e.g., package.json, pyproject.toml, go.mod, Dockerfile). Record key frameworks (e.g., Node/Express, React/Vue, Python/FastAPI, etc.).</action>
    <action>Synthesize a concise "Best-Practices and References" note capturing any updates or considerations that should influence the review (cite links and versions if available).</action>
  </step>
  <step n="4" goal="Assess implementation against acceptance criteria and specs">
    <action>From the story, read Acceptance Criteria and Tasks/Subtasks with their completion state.</action>
    <action>From Dev Agent Record → File List, compile list of changed/added files. If File List is missing or clearly incomplete, search repo for recent changes relevant to the story scope (heuristics: filenames matching components/services/routes/tests inferred from ACs/tasks).</action>
    <action>Cross-check epic tech-spec requirements and architecture constraints against the implementation intent in files.</action>
    <action>For each acceptance criterion, verify there is evidence of implementation and corresponding tests (unit/integration/E2E as applicable). Note any gaps explicitly.</action>
    <action if="critical architecture constraints are violated (e.g., layering, dependency rules)">flag as High Severity finding.</action>
  </step>
  <step n="5" goal="Perform code quality and risk review">
    <action>For each changed file, skim for common issues appropriate to the stack: error handling, input validation, logging, dependency injection, thread-safety/async correctness, resource cleanup, performance anti-patterns.</action>
    <action>Perform security review: injection risks, authZ/authN handling, secret management, unsafe defaults, un-validated redirects, CORS misconfigured, dependency vulnerabilities (based on manifests).</action>
    <action>Check tests quality: assertions are meaningful, edge cases covered, deterministic behavior, proper fixtures, no flakiness patterns.</action>
    <action>Capture concrete, actionable suggestions with severity (High/Med/Low) and rationale. When possible, suggest specific code-level changes (filenames + line ranges) without rewriting large sections.</action>
  </step>
  <step n="6" goal="Decide review outcome and prepare notes">
    <action>Determine outcome: Approve, Changes Requested, or Blocked.</action>
    <action>Prepare a structured review report with sections: Summary, Outcome, Key Findings (by severity), Acceptance Criteria Coverage, Test Coverage and Gaps, Architectural Alignment, Security Notes, Best-Practices and References, Action Items.</action>
    <action>For Action Items, use imperative phrasing and map each to related ACs or files. Include suggested owners if clear.</action>
  </step>
  <step n="7" goal="Append review to story and update metadata">
    <action>Open {{story_path}} and append a new section at the end titled exactly: "Senior Developer Review (AI)".</action>
    <action>Insert subsections:
      - Reviewer: {{user_name}}
      - Date: {{date}}
      - Outcome: (Approve | Changes Requested | Blocked)
      - Summary
      - Key Findings
      - Acceptance Criteria Coverage
      - Test Coverage and Gaps
      - Architectural Alignment
      - Security Notes
      - Best-Practices and References (with links)
      - Action Items
    </action>
    <action>Add a Change Log entry with date, version bump if applicable, and description: "Senior Developer Review notes appended".</action>
    <action>If {{update_status_on_result}} is true: update Status to {{status_on_approve}} when approved; to {{status_on_changes_requested}} when changes requested; otherwise leave unchanged.</action>
    <action>Save the story file.</action>
  </step>
  <step n="8" goal="Update sprint status based on review outcome" tag="sprint-status">
    <action>Determine target status based on review outcome:
      - If {{outcome}} == "Approve" → target_status = "done"
      - If {{outcome}} == "Changes Requested" → target_status = "in-progress"
      - If {{outcome}} == "Blocked" → target_status = "review" (stay in review)
    </action>
    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
    <action>Read all development_status entries to find {{story_key}}</action>
    <action>Verify current status is "review" (expected previous state)</action>
    <action>Update development_status[{{story_key}}] = {{target_status}}</action>
    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
    <check if="update successful">
      <output>✅ Sprint status updated: review → {{target_status}}</output>
    </check>
    <check if="story key not found">
      <output>⚠️ Could not update sprint-status: {{story_key}} not found
 Review was saved to story file, but sprint-status.yaml may be out of sync.
      </output>
    </check>
  </step>
  <step n="9" goal="Persist action items to tasks/backlog/epic">
    <action>Normalize Action Items into a structured list: description, severity (High/Med/Low), type (Bug/TechDebt/Enhancement), suggested owner (if known), related AC/file references.</action>
    <ask if="action items exist and 'story_tasks' in {{persist_targets}}">Add {{action_item_count}} follow-up items to story Tasks/Subtasks?</ask>
    <action if="user confirms or no ask needed">
      Append under the story's "Tasks / Subtasks" a new subsection titled "Review Follow-ups (AI)", adding each item as an unchecked checkbox in imperative form, prefixed with "[AI-Review]" and severity. Example: "- [ ] [AI-Review][High] Add input validation on server route /api/x (AC #2)".
    </action>
    <action if="{{persist_action_items}} == true and 'backlog_file' in {{persist_targets}}">
      If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location.
      Append a row per action item with Date={{date}}, Story={{epic_num}}.{{story_num}}, Epic={{epic_num}}, Type, Severity, Owner (or "TBD"), Status="Open", Notes with short context and file refs.
    </action>
    <action if="{{persist_action_items}} == true and ('epic_followups' in {{persist_targets}} or {{update_epic_followups}} == true)">
      If an epic Tech Spec was found: open it and create (if missing) a section titled "{{epic_followups_section_title}}". Append a bullet list of action items scoped to this epic with references back to Story {{epic_num}}.{{story_num}}.
    </action>
    <action>Save modified files.</action>
    <action>Optionally invoke tests or linters to verify quick fixes if any were applied as part of review (requires user approval for any dependency changes).</action>
  </step>
  <step n="10" goal="Validation and completion">
    <invoke-task>Run validation checklist at {installed_path}/checklist.md using {project-root}/bmad/core/tasks/validate-workflow.xml</invoke-task>
    <action>Report workflow completion.</action>
    <output>**✅ Story Review Complete, {user_name}!**
 **Story Details:**
 - Story: {{epic_num}}.{{story_num}}
 - Story Key: {{story_key}}
 - Review Outcome: {{outcome}}
 - Sprint Status: {{target_status}}
 - Action Items: {{action_item_count}}
 **Next Steps:**
 1. Review the Senior Developer Review notes appended to story
 2. If approved: Story is marked done, continue with next story
 3. If changes requested: Address action items and re-run `dev-story`
 4. If blocked: Resolve blockers before proceeding
    </output>
  </step>
 </workflow>
 ```
--- a/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml
@ -1,6 +1,6 @@
 # Review Story Workflow
-name: code-review
+name: review-story
-description: "Perform a Senior Developer code review on a completed story flagged Ready for Review, leveraging story-context, epic tech-spec, repo docs, MCP servers for latest best-practices, and web search as fallback. Appends structured review notes to the story."
+description: "Perform a Senior Developer Review on a completed story flagged Ready for Review, leveraging story-context, epic tech-spec, repo docs, MCP servers for latest best-practices, and web search as fallback. Appends structured review notes to the story."
 author: "BMad"
 # Critical variables from config
@ -13,7 +13,7 @@ document_output_language: "{config_source}:document_output_language"
 date: system-generated
 # Workflow components
-installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/code-review"
+installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/review-story"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
--- a/src/modules/bmm/workflows/4-implementation/sprint-planning/README.md
+++ b/src/modules/bmm/workflows/4-implementation/sprint-planning/README.md
@ -136,7 +136,7 @@ This workflow is part of Phase 4 (Implementation) and integrates with:
 2. **create-story** - Drafts individual story files
 3. **story-context** - Adds implementation context to stories
 4. **dev-story** - Developer implements the story
-5. **code-review** - SM reviews implementation
+5. **review-story** - SM reviews implementation
 6. **retrospective** - Optional epic retrospective
 ## Benefits
--- a/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md
@ -99,7 +99,7 @@ development_status:
 #   - drafted: Story file created in stories folder
 #   - ready-for-dev: Draft approved and story context created
 #   - in-progress: Developer actively working on implementation
-#   - review: Under SM review (via code-review workflow)
+#   - review: Under SM review (via review-story workflow)
 #   - done: Story completed
 #
 # Retrospective Status:
@ -193,7 +193,7 @@ backlog → drafted → ready-for-dev → in-progress → review → done
 - **drafted**: Story file created (e.g., `stories/1-3-plant-naming.md`)
 - **ready-for-dev**: Draft approved + story context created
 - **in-progress**: Developer actively working
- **review**: Under SM review (via code-review workflow)
+- **review**: Under SM review (via review-story workflow)
 - **done**: Completed
 **Retrospective Status:**
--- a/src/modules/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml
+++ b/src/modules/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml
@ -19,7 +19,7 @@
 #   - drafted: Story file created in stories folder by *create-story
 #   - ready-for-dev: Draft approved and story context created by *story-ready
 #   - in-progress: Developer actively working on implementation by *dev-story
-#   - review: Implementation complete, ready for review by *code-review
+#   - review: Implementation complete, ready for review by *review-story
 #   - done: Story completed by *story-done
 #
 # Retrospective Status:
--- a/src/modules/bmm/workflows/4-implementation/story-done/instructions.md
+++ b/src/modules/bmm/workflows/4-implementation/story-done/instructions.md
@ -35,7 +35,7 @@ All stories are either still in development or already done.
 **Next Steps:**
 1. Run `dev-story` to implement stories
-2. Run `code-review` if stories need review first
+2. Run `review-story` if stories need review first
 3. Check sprint-status.yaml for current story states
   </output>
   <action>HALT</action>
--- a/src/modules/bmm/workflows/README.md
+++ b/src/modules/bmm/workflows/README.md
@ -66,7 +66,7 @@ The BMM (BMAD Method Module) orchestrates software development through four dist
 │  │   ↓                                                       │
 │  │   create-story ──→ story-context ──→ dev-story ─┐         │
 │  │                                                 ↓         │
-│  │   retrospective ←── [epic done] ←─── code-review         │
+│  │   retrospective ←── [epic done] ←─── review-story         │
 │  │                                                 ↓         │
 │  └──────────── correct-course ←──[if issues]───────┘         │
 └──────────────────────────────────────────────────────────────┘
@ -245,7 +245,7 @@ optional ↔ completed
 - **drafted**: Story file created (e.g., `stories/1-3-plant-naming.md`)
 - **ready-for-dev**: Draft approved + story context created
 - **in-progress**: Developer actively working on implementation
- **review**: Under SM review (via code-review workflow)
+- **review**: Under SM review (via review-story workflow)
 - **done**: Story completed and deployed
 **Retrospective Statuses:**
@ -290,7 +290,7 @@ Phase Transition (Phase 2 or 3 → Phase 4)
 └───────────────────┬─────────────────────────────┘
                    ↓
 ┌─────────────────────────────────────────────────┐
-│  DEV: code-review (validates implementation)     │
+│  SM: review-story (validates implementation)     │
 │  Reviews: Code changes against DoD               │
 │  Feedback: Iteration or approval                 │
 └───────────────────┬─────────────────────────────┘
@ -324,7 +324,7 @@ Phase Transition (Phase 2 or 3 → Phase 4)
 | **create-story**      | SM    | Draft individual story files           | Story: backlog → drafted                    |
 | **story-context**     | SM    | Generate implementation context/XML    | Story: drafted → ready-for-dev              |
 | **dev-story**         | DEV   | Implement story                        | Story: ready-for-dev → in-progress → review |
-| **code-review**       | SM/SR | Quality validation and feedback        | (No automatic state change)                 |
+| **review-story**      | SM/SR | Quality validation and feedback        | (No automatic state change)                 |
 | **retrospective**     | SM    | Capture epic learnings                 | Retrospective: optional → completed         |
 | **correct-course**    | SM    | Handle issues/scope changes            | (Adaptive based on situation)               |
@ -380,7 +380,7 @@ workflow-status/workflow-init
 | **1: Analysis**       | Analyst, Game Designer | PM, Researcher       | brainstorm-_, research, _-brief             |
 | **2: Planning**       | PM                     | UX Designer, Analyst | prd, tech-spec, gdd, narrative              |
 | **3: Solutioning**    | Architect              | PM, Tech Lead        | create-architecture, solutioning-gate-check |
-| **4: Implementation** | SM, DEV                | SR (code-review)     | sprint-planning, create-story, dev-story    |
+| **4: Implementation** | SM, DEV                | SR (review-story)    | sprint-planning, create-story, dev-story    |
 ## Key Files and Artifacts
@ -509,7 +509,7 @@ bmad sm epic-tech-context    # Create epic context (per epic)
 bmad sm create-story         # Draft story file
 bmad sm story-context        # Create story context
 bmad dev dev-story           # Implement story
-bmad sm code-review         # Quality validation
+bmad sm review-story         # Quality validation
 # (Update sprint-status.yaml to 'done' manually or via workflow)
 bmad sm retrospective        # After epic complete
 bmad sm correct-course       # If issues arise