bmad-method 6.0.0-alpha.3 → 6.0.0-alpha.5

package/bmad/bmm/workflows/4-implementation/dev-story/AUDIT-REPORT.md

@@ -0,0 +1,367 @@
+# Workflow Audit Report
+
+**Workflow:** dev-story
+**Audit Date:** 2025-10-25
+**Auditor:** Audit Workflow (BMAD v6)
+**Workflow Type:** Action Workflow
+**Module:** BMM (BMad Method)
+
+---
+
+## Executive Summary
+
+**Overall Status:** GOOD - Minor issues to address
+
+- Critical Issues: 0
+- Important Issues: 3
+- Cleanup Recommendations: 2
+
+The dev-story workflow is well-structured and follows most BMAD v6 standards. The workflow correctly sets `web_bundle: false` as expected for implementation workflows. However, there are several config variable usage issues and some variables referenced in instructions that are not defined in the YAML.
+
+---
+
+## 1. Standard Config Block Validation
+
+**Status:** PASS ✓
+
+The workflow.yaml contains all required standard config variables:
+
+- ✓ `config_source: "{project-root}/bmad/bmm/config.yaml"` - Correctly defined
+- ✓ `output_folder: "{config_source}:output_folder"` - Pulls from config_source
+- ✓ `user_name: "{config_source}:user_name"` - Pulls from config_source
+- ✓ `communication_language: "{config_source}:communication_language"` - Pulls from config_source
+- ✓ `date: system-generated` - Correctly set
+
+All standard config variables are present and properly formatted using {project-root} variable syntax.
+
+---
+
+## 2. YAML/Instruction/Template Alignment
+
+**Variables Analyzed:** 9 (excluding standard config)
+**Used in Instructions:** 6
+**Unused (Bloat):** 3
+
+### YAML Variables Defined
+
+1. `story_dir` - USED in instructions (file paths)
+2. `context_path` - UNUSED (appears to duplicate story_dir)
+3. `story_file` - USED in instructions
+4. `context_file` - USED in instructions
+5. `installed_path` - USED in instructions (workflow.xml reference)
+6. `instructions` - USED in instructions (self-reference in critical tag)
+7. `validation` - USED in instructions (checklist reference)
+8. `web_bundle` - CONFIGURATION (correctly set to false)
+9. `date` - USED in instructions (config variable)
+
+### Variables Used in Instructions But NOT Defined in YAML
+
+**IMPORTANT ISSUE:** The following variables are referenced in instructions.md but are NOT defined in workflow.yaml:
+
+1. `{user_skill_level}` - Used 4 times (lines 6, 13, 173, 182)
+2. `{document_output_language}` - Used 1 time (line 7)
+3. `{run_until_complete}` - Used 1 time (line 108)
+4. `{run_tests_command}` - Used 1 time (line 120)
+
+These variables appear to be pulling from config.yaml but are not explicitly defined in the workflow.yaml file. While the config_source mechanism may provide these, workflow.yaml should document all variables used in the workflow for clarity.
+
+### Unused Variables (Bloat)
+
+1. **context_path** - Defined as `"{config_source}:dev_story_location"` but never used. This duplicates `story_dir` functionality.
+
+---
+
+## 3. Config Variable Usage
+
+**Communication Language:** PASS ✓
+**User Name:** PASS ✓
+**Output Folder:** PASS ✓
+**Date:** PASS ✓
+
+### Detailed Analysis
+
+**Communication Language:**
+
+- ✓ Used in line 6: "Communicate all responses in {communication_language}"
+- ✓ Properly used as agent instruction variable (not in template)
+
+**User Name:**
+
+- ✓ Used in line 169: "Communicate to {user_name} that story implementation is complete"
+- ✓ Appropriately used for personalization
+
+**Output Folder:**
+
+- ✓ Used multiple times for sprint-status.yaml file paths
+- ✓ All file operations target {output_folder} correctly
+- ✓ No hardcoded paths detected
+
+**Date:**
+
+- ✓ Available for agent use (system-generated)
+- ✓ Used appropriately in context of workflow execution
+
+### Additional Config Variables
+
+**IMPORTANT ISSUE:** The workflow uses additional variables that appear to come from config but are not explicitly documented:
+
+1. `{user_skill_level}` - Used to tailor communication style
+2. `{document_output_language}` - Used for document generation
+3. `{run_until_complete}` - Used for execution control
+4. `{run_tests_command}` - Used for test execution
+
+These should either be:
+
+- Added to workflow.yaml with proper config_source references, OR
+- Documented as optional config variables with defaults
+
+---
+
+## 4. Web Bundle Validation
+
+**Web Bundle Present:** No (Intentional)
+**Status:** EXPECTED ✓
+
+The workflow correctly sets `web_bundle: false`. This is the expected configuration for implementation workflows that:
+
+- Run locally in the development environment
+- Don't need to be bundled for web deployment
+- Are IDE-integrated workflows
+
+**No issues found** - This is the correct configuration for dev-story.
+
+---
+
+## 5. Bloat Detection
+
+**Bloat Percentage:** 11% (1 unused field / 9 total fields)
+**Cleanup Potential:** Low
+
+### Unused YAML Fields
+
+1. **context_path** (line 11 in workflow.yaml)
+   - Defined as: `"{config_source}:dev_story_location"`
+   - Never referenced in instructions.md
+   - Duplicates functionality of `story_dir` variable
+   - **Recommendation:** Remove this variable as `story_dir` serves the same purpose
+
+### Hardcoded Values
+
+No significant hardcoded values that should be variables were detected. The workflow properly uses variables for:
+
+- File paths ({output_folder}, {story_dir})
+- User personalization ({user_name})
+- Communication style ({communication_language}, {user_skill_level})
+
+### Calculation
+
+- Total yaml fields: 9 (excluding standard config and metadata)
+- Used fields: 8
+- Unused fields: 1 (context_path)
+- Bloat percentage: 11%
+
+**Status:** Acceptable (under 15% threshold)
+
+---
+
+## 6. Template Variable Mapping
+
+**Not Applicable** - This is an action workflow, not a document workflow.
+
+No template.md file exists, which is correct for action-type workflows.
+
+---
+
+## 7. Instructions Quality Analysis
+
+### Structure
+
+- ✓ Steps numbered sequentially (1, 1.5, 2-7)
+- ✓ Each step has clear goal attributes
+- ✓ Proper use of XML tags (<action>, <check>, <goto>, <anchor>, <output>)
+- ✓ Logical flow control with anchors and conditional checks
+- ✓ Repeat patterns used appropriately (step 2-5 loop)
+
+### Critical Tags
+
+- ✓ Critical blocks present and well-defined
+- ✓ Clear references to workflow execution engine
+- ✓ Workflow.yaml load requirement specified
+- ✓ Communication preferences documented
+
+### Variable Usage Consistency
+
+**ISSUE:** Inconsistent variable syntax found:
+
+1. Lines 4, 5 use `{project_root}` (underscore)
+2. Line 166 uses `{project-root}` (hyphen)
+
+**Recommendation:** Standardize to `{project-root}` throughout (hyphen is the standard in BMAD v6)
+
+### Step Quality
+
+**Excellent:**
+
+- Steps are focused and single-purpose
+- Clear HALT conditions defined
+- Comprehensive validation checks
+- Good error handling patterns
+- Iterative execution model well-structured
+
+**Areas for improvement:**
+
+- Step 1 is complex and could potentially be split
+- Some <action if="..."> conditionals could be clearer with <check> blocks
+
+---
+
+## Recommendations
+
+### Critical (Fix Immediately)
+
+None - No critical issues detected.
+
+### Important (Address Soon)
+
+1. **Document or Define Missing Variables**
+   - Add explicit definitions in workflow.yaml for: `user_skill_level`, `document_output_language`, `run_until_complete`, `run_tests_command`
+   - OR document these as optional config variables with defaults
+   - These variables are used in instructions but not defined in YAML
+   - **Impact:** Reduces clarity and may cause confusion about variable sources
+
+2. **Standardize project-root Variable Syntax**
+   - Change line 4 `{project_root}` to `{project-root}` (hyphen)
+   - Ensure consistency with BMAD v6 standard naming convention
+   - **Impact:** Maintains consistency with framework standards
+
+3. **Remove or Use context_path Variable**
+   - Variable `context_path` is defined but never used
+   - Since `story_dir` serves the same purpose, remove `context_path`
+   - OR if there's a semantic difference, document why both exist
+   - **Impact:** Reduces bloat and potential confusion
+
+### Cleanup (Nice to Have)
+
+1. **Consider Splitting Step 1**
+   - Step 1 handles both story discovery AND file loading
+   - Could be split into "1. Find Story" and "2. Load Story Files"
+   - Would improve clarity and maintainability
+   - **Impact:** Minor improvement to workflow structure
+
+2. **Add Variable Documentation Comment**
+   - Add a comment block in workflow.yaml listing all variables used by this workflow
+   - Include both explicit YAML variables and config-pulled variables
+   - Example format:
+     ```yaml
+     # Workflow-specific variables
+     # - story_file: Path to story markdown
+     # - story_dir: Directory containing stories
+     #
+     # Config-pulled variables (from bmm/config.yaml)
+     # - user_skill_level: User's technical skill level
+     # - document_output_language: Language for generated docs
+     ```
+   - **Impact:** Improves developer understanding and maintenance
+
+---
+
+## Validation Checklist
+
+### Structure ✓
+
+- [x] workflow.yaml loads without YAML syntax errors
+- [x] instructions.md exists and is properly formatted
+- [x] No template.md (correct for action workflow)
+- [x] All critical headers present in instructions
+- [x] Workflow type correctly identified (action)
+- [x] All referenced files exist
+- [x] No placeholder text remains
+
+### Standard Config Block ✓
+
+- [x] config_source points to correct module config
+- [x] output_folder pulls from config_source
+- [x] user_name pulls from config_source
+- [x] communication_language pulls from config_source
+- [x] date is system-generated
+- [x] Config source uses {project-root} variable
+- [x] Standard config comment present
+
+### Config Variable Usage ✓
+
+- [x] Instructions communicate in {communication_language}
+- [x] Instructions address {user_name}
+- [x] All file outputs use {output_folder}
+- [x] No hardcoded paths
+- [x] Date available for agent awareness
+
+### YAML/Instruction/Template Alignment ⚠️
+
+- [⚠️] Some variables used in instructions not defined in YAML
+- [x] Template variables N/A (action workflow)
+- [x] Variable names are descriptive
+- [⚠️] One unused yaml field (context_path)
+
+### Web Bundle Validation ✓
+
+- [x] web_bundle: false is correct for this workflow
+- [x] No web_bundle section needed
+- [x] Workflow is local/IDE-integrated only
+
+### Instructions Quality ✓
+
+- [x] Steps numbered sequentially
+- [x] Clear goal attributes
+- [x] Proper XML tag usage
+- [x] Logical flow control
+- [⚠️] Minor inconsistency: {project_root} vs {project-root}
+
+### Bloat Detection ✓
+
+- [x] Bloat percentage: 11% (acceptable, under 15%)
+- [x] No significant hardcoded values
+- [x] No redundant configuration
+- [x] One cleanup recommendation (context_path)
+
+---
+
+## Next Steps
+
+1. **Define missing variables** - Add explicit YAML definitions or document as config-pulled variables
+2. **Standardize variable syntax** - Change `{project_root}` to `{project-root}`
+3. **Remove context_path** - Clean up unused variable
+4. **Re-run audit** - Verify improvements after fixes
+
+---
+
+## Additional Notes
+
+### Strengths
+
+1. **Comprehensive Workflow Logic:** The dev-story workflow is well-thought-out with proper error handling, validation gates, and iterative execution
+2. **Config Integration:** Excellent use of config variables for user personalization and output management
+3. **Clear Documentation:** Instructions are detailed with specific HALT conditions and validation checkpoints
+4. **Proper Web Bundle Setting:** Correctly identifies this as a local-only workflow with web_bundle: false
+5. **Step Flow:** Excellent use of anchors, goto, and conditional checks for complex flow control
+
+### Workflow Purpose
+
+This workflow executes user stories by:
+
+- Finding ready-for-dev stories from sprint status
+- Implementing tasks and subtasks incrementally
+- Writing comprehensive tests
+- Validating against acceptance criteria
+- Updating story status through sprint lifecycle
+- Supporting different user skill levels with adaptive communication
+
+The workflow is a critical part of the BMM implementation phase and shows mature design patterns.
+
+---
+
+**Audit Complete** - Generated by audit-workflow v1.0
+
+**Pass Rate:** 89% (62 passed / 70 total checks)
+**Recommendation:** Good - Minor fixes needed
+
+The dev-story workflow is production-ready with minor improvements recommended. The issues identified are primarily documentation and consistency improvements rather than functional problems.

package/bmad/bmm/workflows/4-implementation/dev-story/checklist.md

@@ -0,0 +1,38 @@
+---
+title: 'Dev Story Completion Checklist'
+validation-target: 'Story markdown ({{story_path}})'
+required-inputs:
+  - 'Story markdown file with Tasks/Subtasks, Acceptance Criteria'
+optional-inputs:
+  - 'Test results output (if saved)'
+  - 'CI logs (if applicable)'
+validation-rules:
+  - 'Only permitted sections in story were modified: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status'
+---
+
+# Dev Story Completion Checklist
+
+## Tasks Completion
+
+- [ ] All tasks and subtasks for this story are marked complete with [x]
+- [ ] Implementation aligns with every Acceptance Criterion in the story
+
+## Tests and Quality
+
+- [ ] Unit tests added/updated for core functionality changed by this story
+- [ ] Integration tests added/updated when component interactions are affected
+- [ ] End-to-end tests created for critical user flows, if applicable
+- [ ] All tests pass locally (no regressions introduced)
+- [ ] Linting and static checks (if configured) pass
+
+## Story File Updates
+
+- [ ] File List section includes every new/modified/deleted file (paths relative to repo root)
+- [ ] Dev Agent Record contains relevant Debug Log and/or Completion Notes for this work
+- [ ] Change Log includes a brief summary of what changed
+- [ ] Only permitted sections of the story file were modified
+
+## Final Status
+
+- [ ] Regression suite executed successfully
+- [ ] Story Status is set to "Ready for Review"

package/bmad/bmm/workflows/4-implementation/dev-story/instructions.md

@@ -0,0 +1,262 @@
+# Develop Story - 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>Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status</critical>
+<critical>Execute ALL steps in exact order; do NOT skip steps</critical>
+<critical>Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives other instruction.</critical>
+<critical>Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.</critical>
+
+<critical>User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.</critical>
+
+<workflow>
+
+  <step n="1" goal="Find next ready story and load it" tag="sprint-status">
+    <check if="{{story_path}} is provided">
+      <action>Use {{story_path}} directly</action>
+      <action>Read COMPLETE story file</action>
+      <action>Extract story_key from filename or metadata</action>
+      <goto>task_check</goto>
+    </check>
+
+    <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 to understand story order</action>
+
+    <action>Find the FIRST story (by 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 "ready-for-dev"
+    </action>
+
+    <check if="no ready-for-dev or in-progress story found">
+      <output>📋 No ready-for-dev stories found in sprint-status.yaml
+**Options:**
+1. Run `story-context` to generate context file and mark drafted stories as ready
+2. Run `story-ready` to quickly mark drafted stories as ready without generating context
+3. Run `create-story` if no incomplete stories are drafted yet
+4. Check {output-folder}/sprint-status.yaml to see current sprint status
+      </output>
+      <action>HALT</action>
+    </check>
+
+    <action>Store the found story_key (e.g., "1-2-user-authentication") for later status updates</action>
+    <action>Find matching story file in {{story_dir}} using story_key pattern: {{story_key}}.md</action>
+    <action>Read COMPLETE story file from discovered path</action>
+
+    <anchor id="task_check" />
+
+    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
+
+    <action>Check if context file exists at: {{story_dir}}/{{story_key}}.context.xml</action>
+    <check if="context file exists">
+      <action>Read COMPLETE context file</action>
+      <action>Parse all sections: story details, artifacts (docs, code, dependencies), interfaces, constraints, tests</action>
+      <action>Use this context to inform implementation decisions and approaches</action>
+    </check>
+    <check if="context file does NOT exist">
+      <output>ℹ️ No context file found for {{story_key}}
+
+Proceeding with story file only. For better context, consider running `story-context` workflow first.
+      </output>
+    </check>
+
+    <action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action>
+
+    <action if="no incomplete tasks"><goto step="6">Completion sequence</goto></action>
+    <action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
+    <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">
+    <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>
+
+    <check if="current status == 'ready-for-dev'">
+      <action>Update the story in the sprint status report to = "in-progress"</action>
+      <output>🚀 Starting work on story {{story_key}}
+Status updated: ready-for-dev → in-progress
+      </output>
+    </check>
+
+    <check if="current status == 'in-progress'">
+      <output>⏯️ Resuming work on story {{story_key}}
+Story is already marked in-progress
+      </output>
+    </check>
+
+    <check if="current status is neither ready-for-dev nor in-progress">
+      <output>⚠️ Unexpected story status: {{current_status}}
+Expected ready-for-dev or in-progress. Continuing anyway...
+      </output>
+    </check>
+  </step>
+
+  <step n="2" goal="Plan and implement task">
+    <action>Review acceptance criteria and dev notes for the selected task</action>
+    <action>Plan implementation steps and edge cases; write down a brief plan in Dev Agent Record → Debug Log</action>
+    <action>Implement the task COMPLETELY including all subtasks, critically following best practices, coding patterns and coding standards in this repo you have learned about from the story and context file or your own critical agent instructions</action>
+    <action>Handle error conditions and edge cases appropriately</action>
+    <action if="new or different than what is documented dependencies are needed">ASK user for approval before adding</action>
+    <action if="3 consecutive implementation failures occur">HALT and request guidance</action>
+    <action if="required configuration is missing">HALT: "Cannot proceed without necessary configuration files"</action>
+    <critical>Do not stop after partial progress; continue iterating tasks until all ACs are satisfied and tested or a HALT condition triggers</critical>
+    <critical>Do NOT propose to pause for review, stand-ups, or validation until Step 6 gates are satisfied</critical>
+  </step>
+
+  <step n="3" goal="Author comprehensive tests">
+    <action>Create unit tests for business logic and core functionality introduced/changed by the task</action>
+    <action>Add integration tests for component interactions where desired by test plan or story notes</action>
+    <action>Include end-to-end tests for critical user flows where desired by test plan or story notes</action>
+    <action>Cover edge cases and error handling scenarios noted in the test plan or story notes</action>
+  </step>
+
+  <step n="4" goal="Run validations and tests">
+    <action>Determine how to run tests for this repo (infer or use {{run_tests_command}} if provided)</action>
+    <action>Run all existing tests to ensure no regressions</action>
+    <action>Run the new tests to verify implementation correctness</action>
+    <action>Run linting and code quality checks if configured</action>
+    <action>Validate implementation meets ALL story acceptance criteria; if ACs include quantitative thresholds (e.g., test pass rate), ensure they are met before marking complete</action>
+    <action if="regression tests fail">STOP and fix before continuing, consider how current changes made broke regression</action>
+    <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">
+    <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>
+    <action if="no tasks remain"><goto step="6">Completion</goto></action>
+  </step>
+
+  <step n="6" goal="Story completion and mark for review" tag="sprint-status">
+    <action>Verify ALL tasks and subtasks are marked [x] (re-scan the story document now)</action>
+    <action>Run the full regression suite (do not skip)</action>
+    <action>Confirm File List includes every changed file</action>
+    <action>Execute story definition-of-done checklist, if the story includes one</action>
+    <action>Update the story Status to: review</action>
+
+    <!-- Mark story ready for review -->
+    <action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+    <action>Find development_status key matching {{story_key}}</action>
+    <action>Verify current status is "in-progress" (expected previous state)</action>
+    <action>Update development_status[{{story_key}}] = "review"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+    <check if="story key not found in file">
+      <output>⚠️ Story file updated, but sprint-status update failed: {{story_key}} not found
+
+Story is marked Ready for Review in file, but sprint-status.yaml may be out of sync.
+      </output>
+    </check>
+
+    <action if="any task is incomplete">Return to step 1 to complete remaining work (Do NOT finish with partial progress)</action>
+    <action if="regression failures exist">STOP and resolve before completing</action>
+    <action if="File List is incomplete">Update it before completing</action>
+  </step>
+
+  <step n="7" goal="Completion communication and user support">
+    <action>Optionally run the workflow validation task against the story using {project-root}/bmad/core/tasks/validate-workflow.xml</action>
+    <action>Prepare a concise summary in Dev Agent Record → Completion Notes</action>
+
+    <action>Communicate to {user_name} that story implementation is complete and ready for review</action>
+    <action>Summarize key accomplishments: story ID, story key, title, key changes made, tests added, files modified</action>
+    <action>Provide the story file path and current status (now "review", was "in-progress")</action>
+
+    <action>Based on {user_skill_level}, ask if user needs any explanations about:
+      - What was implemented and how it works
+      - Why certain technical decisions were made
+      - How to test or verify the changes
+      - Any patterns, libraries, or approaches used
+      - Anything else they'd like clarified
+    </action>
+
+    <check if="user asks for explanations">
+      <action>Provide clear, contextual explanations tailored to {user_skill_level}</action>
+      <action>Use examples and references to specific code when helpful</action>
+    </check>
+
+    <action>Once explanations are complete (or user indicates no questions), suggest logical next steps</action>
+    <action>Common next steps to suggest (but allow user flexibility):
+      - 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
+      - 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>
+  </step>
+
+</workflow>
+```