bmad-method 6.0.0-alpha.13 → 6.0.0-alpha.15

package/src/modules/bmm/workflows/3-solutioning/implementation-readiness/steps/step-05-epic-quality-review.md

@@ -0,0 +1,251 @@
+---
+name: 'step-05-epic-quality-review'
+description: 'Validate epics and stories against create-epics-and-stories best practices'
+
+# Path Definitions
+workflow_path: '{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/implementation-readiness'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-05-epic-quality-review.md'
+nextStepFile: '{workflow_path}/steps/step-06-final-assessment.md'
+workflowFile: '{workflow_path}/workflow.md'
+outputFile: '{output_folder}/implementation-readiness-report-{{date}}.md'
+epicsBestPractices: '{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/create-epics-and-stories'
+---
+
+# Step 5: Epic Quality Review
+
+## STEP GOAL:
+
+To validate epics and stories against the best practices defined in create-epics-and-stories workflow, focusing on user value, independence, dependencies, and implementation readiness.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are an EPIC QUALITY ENFORCER
+- ✅ You know what good epics look like - challenge anything deviating
+- ✅ Technical epics are wrong - find them
+- ✅ Forward dependencies are forbidden - catch them
+- ✅ Stories must be independently completable
+
+### Step-Specific Rules:
+
+- 🎯 Apply create-epics-and-stories standards rigorously
+- 🚫 Don't accept "technical milestones" as epics
+- 💬 Challenge every dependency on future work
+- 🚪 Verify proper story sizing and structure
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Systematically validate each epic and story
+- 💾 Document all violations of best practices
+- 📖 Check every dependency relationship
+- 🚫 FORBIDDEN to accept structural problems
+
+## EPIC QUALITY REVIEW PROCESS:
+
+### 1. Initialize Best Practices Validation
+
+"Beginning **Epic Quality Review** against create-epics-and-stories standards.
+
+I will rigorously validate:
+
+- Epics deliver user value (not technical milestones)
+- Epic independence (Epic 2 doesn't need Epic 3)
+- Story dependencies (no forward references)
+- Proper story sizing and completeness
+
+Any deviation from best practices will be flagged as a defect."
+
+### 2. Epic Structure Validation
+
+#### A. User Value Focus Check
+
+For each epic:
+
+- **Epic Title:** Is it user-centric (what user can do)?
+- **Epic Goal:** Does it describe user outcome?
+- **Value Proposition:** Can users benefit from this epic alone?
+
+**Red flags (violations):**
+
+- "Setup Database" or "Create Models" - no user value
+- "API Development" - technical milestone
+- "Infrastructure Setup" - not user-facing
+- "Authentication System" - borderline (is it user value?)
+
+#### B. Epic Independence Validation
+
+Test epic independence:
+
+- **Epic 1:** Must stand alone completely
+- **Epic 2:** Can function using only Epic 1 output
+- **Epic 3:** Can function using Epic 1 & 2 outputs
+- **Rule:** Epic N cannot require Epic N+1 to work
+
+**Document failures:**
+
+- "Epic 2 requires Epic 3 features to function"
+- Stories in Epic 2 referencing Epic 3 components
+- Circular dependencies between epics
+
+### 3. Story Quality Assessment
+
+#### A. Story Sizing Validation
+
+Check each story:
+
+- **Clear User Value:** Does the story deliver something meaningful?
+- **Independent:** Can it be completed without future stories?
+
+**Common violations:**
+
+- "Setup all models" - not a USER story
+- "Create login UI (depends on Story 1.3)" - forward dependency
+
+#### B. Acceptance Criteria Review
+
+For each story's ACs:
+
+- **Given/When/Then Format:** Proper BDD structure?
+- **Testable:** Each AC can be verified independently?
+- **Complete:** Covers all scenarios including errors?
+- **Specific:** Clear expected outcomes?
+
+**Issues to find:**
+
+- Vague criteria like "user can login"
+- Missing error conditions
+- Incomplete happy path
+- Non-measurable outcomes
+
+### 4. Dependency Analysis
+
+#### A. Within-Epic Dependencies
+
+Map story dependencies within each epic:
+
+- Story 1.1 must be completable alone
+- Story 1.2 can use Story 1.1 output
+- Story 1.3 can use Story 1.1 & 1.2 outputs
+
+**Critical violations:**
+
+- "This story depends on Story 1.4"
+- "Wait for future story to work"
+- Stories referencing features not yet implemented
+
+#### B. Database/Entity Creation Timing
+
+Validate database creation approach:
+
+- **Wrong:** Epic 1 Story 1 creates all tables upfront
+- **Right:** Each story creates tables it needs
+- **Check:** Are tables created only when first needed?
+
+### 5. Special Implementation Checks
+
+#### A. Starter Template Requirement
+
+Check if Architecture specifies starter template:
+
+- If YES: Epic 1 Story 1 must be "Set up initial project from starter template"
+- Verify story includes cloning, dependencies, initial configuration
+
+#### B. Greenfield vs Brownfield Indicators
+
+Greenfield projects should have:
+
+- Initial project setup story
+- Development environment configuration
+- CI/CD pipeline setup early
+
+Brownfield projects should have:
+
+- Integration points with existing systems
+- Migration or compatibility stories
+
+### 6. Best Practices Compliance Checklist
+
+For each epic, verify:
+
+- [ ] Epic delivers user value
+- [ ] Epic can function independently
+- [ ] Stories appropriately sized
+- [ ] No forward dependencies
+- [ ] Database tables created when needed
+- [ ] Clear acceptance criteria
+- [ ] Traceability to FRs maintained
+
+### 7. Quality Assessment Documentation
+
+Document all findings by severity:
+
+#### 🔴 Critical Violations
+
+- Technical epics with no user value
+- Forward dependencies breaking independence
+- Epic-sized stories that cannot be completed
+
+#### 🟠 Major Issues
+
+- Vague acceptance criteria
+- Stories requiring future stories
+- Database creation violations
+
+#### 🟡 Minor Concerns
+
+- Formatting inconsistencies
+- Minor structure deviations
+- Documentation gaps
+
+### 8. Autonomous Review Execution
+
+This review runs autonomously to maintain standards:
+
+- Apply best practices without compromise
+- Document every violation with specific examples
+- Provide clear remediation guidance
+- Prepare recommendations for each issue
+
+## REVIEW COMPLETION:
+
+After completing epic quality review:
+
+- Update {outputFile} with all quality findings
+- Document specific best practices violations
+- Provide actionable recommendations
+- Load {nextStepFile} for final readiness assessment
+
+## CRITICAL STEP COMPLETION NOTE
+
+This step executes autonomously. Load {nextStepFile} only after complete epic quality review is documented.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All epics validated against best practices
+- Every dependency checked and verified
+- Quality violations documented with examples
+- Clear remediation guidance provided
+- No compromise on standards enforcement
+
+### ❌ SYSTEM FAILURE:
+
+- Accepting technical epics as valid
+- Ignoring forward dependencies
+- Not verifying story sizing
+- Overlooking obvious violations
+
+**Master Rule:** Enforce best practices rigorously. Find all violations.

package/src/modules/bmm/workflows/3-solutioning/implementation-readiness/steps/step-06-final-assessment.md

@@ -0,0 +1,132 @@
+---
+name: 'step-06-final-assessment'
+description: 'Compile final assessment and polish the readiness report'
+
+# Path Definitions
+workflow_path: '{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/implementation-readiness'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-06-final-assessment.md'
+workflowFile: '{workflow_path}/workflow.md'
+outputFile: '{output_folder}/implementation-readiness-report-{{date}}.md'
+---
+
+# Step 6: Final Assessment
+
+## STEP GOAL:
+
+To provide a comprehensive summary of all findings and give the report a final polish, ensuring clear recommendations and overall readiness status.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 📖 You are at the final step - complete the assessment
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are delivering the FINAL ASSESSMENT
+- ✅ Your findings are objective and backed by evidence
+- ✅ Provide clear, actionable recommendations
+- ✅ Success is measured by value of findings
+
+### Step-Specific Rules:
+
+- 🎯 Compile and summarize all findings
+- 🚫 Don't soften the message - be direct
+- 💬 Provide specific examples for problems
+- 🚪 Add final section to the report
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Review all findings from previous steps
+- 💾 Add summary and recommendations
+- 📖 Determine overall readiness status
+- 🚫 Complete and present final report
+
+## FINAL ASSESSMENT PROCESS:
+
+### 1. Initialize Final Assessment
+
+"Completing **Final Assessment**.
+
+I will now:
+
+1. Review all findings from previous steps
+2. Provide a comprehensive summary
+3. Add specific recommendations
+4. Determine overall readiness status"
+
+### 2. Review Previous Findings
+
+Check the {outputFile} for sections added by previous steps:
+
+- File and FR Validation findings
+- UX Alignment issues
+- Epic Quality violations
+
+### 3. Add Final Assessment Section
+
+Append to {outputFile}:
+
+```markdown
+## Summary and Recommendations
+
+### Overall Readiness Status
+
+[READY/NEEDS WORK/NOT READY]
+
+### Critical Issues Requiring Immediate Action
+
+[List most critical issues that must be addressed]
+
+### Recommended Next Steps
+
+1. [Specific action item 1]
+2. [Specific action item 2]
+3. [Specific action item 3]
+
+### Final Note
+
+This assessment identified [X] issues across [Y] categories. Address the critical issues before proceeding to implementation. These findings can be used to improve the artifacts or you may choose to proceed as-is.
+```
+
+### 4. Complete the Report
+
+- Ensure all findings are clearly documented
+- Verify recommendations are actionable
+- Add date and assessor information
+- Save the final report
+
+### 5. Present Completion
+
+Display:
+"**Implementation Readiness Assessment Complete**
+
+Report generated: {outputFile}
+
+The assessment found [number] issues requiring attention. Review the detailed report for specific findings and recommendations."
+
+## WORKFLOW COMPLETE
+
+The implementation readiness workflow is now complete. The report contains all findings and recommendations for the user to consider.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All findings compiled and summarized
+- Clear recommendations provided
+- Readiness status determined
+- Final report saved
+
+### ❌ SYSTEM FAILURE:
+
+- Not reviewing previous findings
+- Incomplete summary
+- No clear recommendations

package/src/modules/bmm/workflows/3-solutioning/implementation-readiness/templates/readiness-report-template.md

@@ -0,0 +1,4 @@
+# Implementation Readiness Assessment Report
+
+**Date:** {{date}}
+**Project:** {{project_name}}

package/src/modules/bmm/workflows/3-solutioning/implementation-readiness/workflow.md

@@ -0,0 +1,54 @@
+---
+name: check-implementation-readiness
+description: 'Critical validation workflow that assesses PRD, Architecture, and Epics & Stories for completeness and alignment before implementation. Uses adversarial review approach to find gaps and issues.'
+web_bundle: false
+---
+
+# Implementation Readiness
+
+**Goal:** Validate that PRD, Architecture, Epics and Stories are complete and aligned before Phase 4 implementation starts, with a focus on ensuring epics and stories are logical and have accounted for all requirements and planning.
+
+**Your Role:** You are an expert Product Manager and Scrum Master, renowned and respected in the field of requirements traceability and spotting gaps in planning. Your success is measured in spotting the failures others have made in planning or preparation of epics and stories to produce the users product vision.
+
+## WORKFLOW ARCHITECTURE
+
+### Core Principles
+
+- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time
+- **Just-In-Time Loading**: Only 1 current step file will be loaded, read, and executed to completion - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full config from {project-root}/{bmad_folder}/bmm/config.yaml and resolve:
+
+- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
+
+### 2. First Step EXECUTION
+
+Load, read the full file and then execute `{workflow_path}/steps/step-01-document-discovery.md` to begin the workflow.

package/src/modules/{bmgd/workflows/4-production → bmm/workflows/4-implementation}/code-review/checklist.md

@@ -1,7 +1,7 @@
 # Senior Developer Review - Validation Checklist
 
 - [ ] Story file loaded from `{{story_path}}`
-- [ ] Story Status verified as one of: {{allow_status_values}}
+- [ ] Story Status verified as reviewable (review)
 - [ ] Epic and Story IDs resolved ({{epic_num}}.{{story_num}})
 - [ ] Story Context located or warning recorded
 - [ ] Epic Tech Spec located or warning recorded
@@ -17,6 +17,7 @@
 - [ ] Review notes appended under "Senior Developer Review (AI)"
 - [ ] Change Log updated with review entry
 - [ ] Status updated according to settings (if enabled)
+- [ ] Sprint status synced (if sprint tracking enabled)
 - [ ] Story saved successfully
 
 _Reviewer: {{user_name}} on {{date}}_

package/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml

@@ -16,6 +16,7 @@
   <step n="1" goal="Load story and discover changes">
     <action>Use provided {{story_path}} or ask user which story file to review</action>
     <action>Read COMPLETE story file</action>
+    <action>Set {{story_key}} = extracted key from filename (e.g., "1-2-user-authentication.md" → "1-2-user-authentication") or story metadata</action>
     <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Agent Record → File List, Change Log</action>
 
     <!-- Discover actual changes via git -->
@@ -106,6 +107,8 @@
 
   <step n="4" goal="Present findings and fix them">
     <action>Categorize findings: HIGH (must fix), MEDIUM (should fix), LOW (nice to fix)</action>
+    <action>Set {{fixed_count}} = 0</action>
+    <action>Set {{action_count}} = 0</action>
 
     <output>**🔥 CODE REVIEW FINDINGS, {user_name}!**
 
@@ -145,11 +148,15 @@
       <action>Add/update tests as needed</action>
       <action>Update File List in story if files changed</action>
       <action>Update story Dev Agent Record with fixes applied</action>
+      <action>Set {{fixed_count}} = number of HIGH and MEDIUM issues fixed</action>
+      <action>Set {{action_count}} = 0</action>
     </check>
 
     <check if="user chooses 2">
       <action>Add "Review Follow-ups (AI)" subsection to Tasks/Subtasks</action>
       <action>For each issue: `- [ ] [AI-Review][Severity] Description [file:line]`</action>
+      <action>Set {{action_count}} = number of action items created</action>
+      <action>Set {{fixed_count}} = 0</action>
     </check>
 
     <check if="user chooses 3">
@@ -158,11 +165,52 @@
     </check>
   </step>
 
-  <step n="5" goal="Update story status">
-    <action>If all HIGH issues fixed and ACs implemented → Update story Status to "done"</action>
-    <action>If issues remain → Update story Status to "in-progress"</action>
+  <step n="5" goal="Update story status and sync sprint tracking">
+    <!-- Determine new status based on review outcome -->
+    <check if="all HIGH and MEDIUM issues fixed AND all ACs implemented">
+      <action>Set {{new_status}} = "done"</action>
+      <action>Update story Status field to "done"</action>
+    </check>
+    <check if="HIGH or MEDIUM issues remain OR ACs not fully implemented">
+      <action>Set {{new_status}} = "in-progress"</action>
+      <action>Update story Status field to "in-progress"</action>
+    </check>
     <action>Save story file</action>
 
+    <!-- Determine sprint tracking status -->
+    <check if="{sprint_status} file exists">
+      <action>Set {{current_sprint_status}} = "enabled"</action>
+    </check>
+    <check if="{sprint_status} file does NOT exist">
+      <action>Set {{current_sprint_status}} = "no-sprint-tracking"</action>
+    </check>
+
+    <!-- Sync sprint-status.yaml when story status changes (only if sprint tracking enabled) -->
+    <check if="{{current_sprint_status}} != 'no-sprint-tracking'">
+      <action>Load the FULL file: {sprint_status}</action>
+      <action>Find development_status key matching {{story_key}}</action>
+
+      <check if="{{new_status}} == 'done'">
+        <action>Update development_status[{{story_key}}] = "done"</action>
+        <action>Save file, preserving ALL comments and structure</action>
+        <output>✅ Sprint status synced: {{story_key}} → done</output>
+      </check>
+
+      <check if="{{new_status}} == 'in-progress'">
+        <action>Update development_status[{{story_key}}] = "in-progress"</action>
+        <action>Save file, preserving ALL comments and structure</action>
+        <output>🔄 Sprint status synced: {{story_key}} → in-progress</output>
+      </check>
+
+      <check if="story key not found in sprint status">
+        <output>⚠️ Story file updated, but sprint-status sync failed: {{story_key}} not found in sprint-status.yaml</output>
+      </check>
+    </check>
+
+    <check if="{{current_sprint_status}} == 'no-sprint-tracking'">
+      <output>ℹ️ Story status updated (no sprint tracking configured)</output>
+    </check>
+
     <output>**✅ Review Complete!**
 
       **Story Status:** {{new_status}}

package/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml

@@ -1,6 +1,6 @@
 # Review Story Workflow
 name: code-review
-description: "Perform an ADVERSARIAL Senior Developer code review that finds 3-10 specific problems in every story. Challenges everything: code quality, test coverage, architecture compliance, security, performance. NEVER accepts 'looks good' - must find minimum issues and can auto-fix with user approval."
+description: "Perform an ADVERSARIAL Senior Developer code review that finds 3-10 specific problems in every story. Challenges everything: code quality, test coverage, architecture compliance, security, performance. NEVER accepts `looks good` - must find minimum issues and can auto-fix with user approval."
 author: "BMad"
 
 # Critical variables from config

package/src/modules/bmm/workflows/4-implementation/create-story/instructions.xml

@@ -95,7 +95,22 @@
       <check if="this is first story in epic {{epic_num}}">
         <action>Load {{sprint_status}} and check epic-{{epic_num}} status</action>
         <action>If epic status is "backlog" → update to "in-progress"</action>
-        <action>If epic status is "contexted" → this means same as "in-progress", no change needed</action>
+        <action>If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility)</action>
+        <action>If epic status is "in-progress" → no change needed</action>
+        <check if="epic status is 'done'">
+          <output>🚫 ERROR: Cannot create story in completed epic</output>
+          <output>Epic {{epic_num}} is marked as 'done'. All stories are complete.</output>
+          <output>If you need to add more work, either:</output>
+          <output>1. Manually change epic status back to 'in-progress' in sprint-status.yaml</output>
+          <output>2. Create a new epic for additional work</output>
+          <action>HALT - Cannot proceed</action>
+        </check>
+        <check if="epic status is not one of: backlog, contexted, in-progress, done">
+          <output>🚫 ERROR: Invalid epic status '{{epic_status}}'</output>
+          <output>Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done</output>
+          <output>Please fix sprint-status.yaml manually or run sprint-planning to regenerate</output>
+          <action>HALT - Cannot proceed</action>
+        </check>
         <output>📊 Epic {{epic_num}} status updated to in-progress</output>
       </check>
 
@@ -137,7 +152,22 @@
     <check if="this is first story in epic {{epic_num}}">
       <action>Load {{sprint_status}} and check epic-{{epic_num}} status</action>
       <action>If epic status is "backlog" → update to "in-progress"</action>
-      <action>If epic status is "contexted" → this means same as "in-progress", no change needed</action>
+      <action>If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility)</action>
+      <action>If epic status is "in-progress" → no change needed</action>
+      <check if="epic status is 'done'">
+        <output>🚫 ERROR: Cannot create story in completed epic</output>
+        <output>Epic {{epic_num}} is marked as 'done'. All stories are complete.</output>
+        <output>If you need to add more work, either:</output>
+        <output>1. Manually change epic status back to 'in-progress' in sprint-status.yaml</output>
+        <output>2. Create a new epic for additional work</output>
+        <action>HALT - Cannot proceed</action>
+      </check>
+      <check if="epic status is not one of: backlog, contexted, in-progress, done">
+        <output>🚫 ERROR: Invalid epic status '{{epic_status}}'</output>
+        <output>Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done</output>
+        <output>Please fix sprint-status.yaml manually or run sprint-planning to regenerate</output>
+        <action>HALT - Cannot proceed</action>
+      </check>
       <output>📊 Epic {{epic_num}} status updated to in-progress</output>
     </check>
 

package/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md

@@ -1395,9 +1395,9 @@ Retrospective document was saved successfully, but {sprint_status_file} may need
 - Do NOT start Epic {{next_epic_num}} until review is complete
   {{else}}
 
-4. **Begin Epic {{next_epic_num}} planning when preparation complete**
-   - Load PM agent and run `epic-tech-context` for Epic {{next_epic_num}}
-   - Or continue with existing contexted epics
+4. **Begin Epic {{next_epic_num}} when ready**
+   - Start drafting stories with SM agent's `create-story`
+   - Epic will be marked as `in-progress` automatically when first story is created
    - Ensure all critical path items are done first
      {{/if}}