bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.4

package/src/modules/bmm/workflows/2-plan-workflows/narrative/instructions-narrative.md

@@ -10,20 +10,40 @@
 <critical>If users mention gameplay mechanics, note them but keep focus on narrative</critical>
 <critical>Facilitate good brainstorming techniques throughout with the user, pushing them to come up with much of the narrative you will help weave together. The goal is for the user to feel that they crafted the narrative and story arc unless they push you to do it all or indicate YOLO</critical>
 
-<step n="0" goal="Check for workflow status">
+<step n="0" goal="Check for workflow status" tag="workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-  <param>mode: init-check</param>
-</invoke-workflow>
-
-<check if="status_exists == true">
-  <action>Store {{status_file_path}} for later updates</action>
-  <action>Set tracking_mode = true</action>
+<check if="status file not found">
+  <output>No workflow status file found. Narrative workflow is optional - you can continue without status tracking.</output>
+  <action>Set standalone_mode = true</action>
 </check>
 
-<check if="status_exists == false">
-  <action>Set tracking_mode = false</action>
-  <output>Note: Running without workflow tracking. Run `workflow-init` to enable progress tracking.</output>
+<check if="status file found">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "narrative" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
+
+  <check if="narrative status is file path (already completed)">
+    <output>⚠️ Narrative Design Document already completed: {{narrative status}}</output>
+    <ask>Re-running will overwrite the existing narrative document. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+  <check if="narrative is not the next expected workflow (latter items are completed already in the list)">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Narrative is out of sequence.</output>
+    <ask>Continue with Narrative Design anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+<action>Set standalone_mode = false</action>
 </check>
 </step>
 
@@ -539,19 +559,50 @@ Which would you like?</ask>
 
 </step>
 
-<step n="17" goal="Update status if tracking enabled">
+<step n="17" goal="Update status if tracking enabled" tag="workflow-status">
 
-<check if="tracking_mode == true">
-  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-    <param>mode: update</param>
-    <param>action: complete_workflow</param>
-    <param>workflow_name: narrative</param>
-  </invoke-workflow>
+<check if="standalone_mode != true">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "narrative"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["narrative"] = "{output_folder}/bmm-narrative-{{game_name}}-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-  <check if="success == true">
-    <output>✅ Status updated! Next: {{next_workflow}}</output>
-  </check>
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
+<action>Determine next agent from path file based on next workflow</action>
 </check>
-</step>
+
+<output>**✅ Narrative Design Complete, {user_name}!**
+
+**Narrative Document:**
+
+- Narrative design saved to {output_folder}/bmm-narrative-{{game_name}}-{{date}}.md
+
+{{#if standalone_mode != true}}
+**Status Updated:**
+
+- Progress tracking updated: narrative marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
+
+**Next Steps:**
+
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
+- **Optional:** Review narrative with writing team or stakeholders
+
+Check status anytime with: `workflow-status`
+{{else}}
+Since no workflow is in progress:
+
+- Review narrative design with team
+- Refer to the BMM workflow guide if unsure what to do next
+- Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
+  </output>
+  </step>
 
 </workflow>

package/src/modules/bmm/workflows/2-plan-workflows/prd/checklist.md

@@ -1,117 +1,349 @@
-# PRD Workflow Validation Checklist
+# PRD + Epics + Stories Validation Checklist
 
-**Purpose**: Validate PRD workflow outputs are complete, consistent, and ready for next phase.
+**Purpose**: Comprehensive validation that PRD, epics, and stories form a complete, implementable product plan.
 
-**Scope**: Levels 2-4 software projects
+**Scope**: Validates the complete planning output (PRD.md + epics.md) for Levels 2-4 software projects
 
-**Expected Outputs**: PRD.md, epics.md, updated bmm-workflow-status.md
+**Expected Outputs**:
+
+- PRD.md with complete requirements
+- epics.md with detailed epic and story breakdown
+- Updated bmm-workflow-status.yaml
 
 ---
 
-## 1. Output Files Exist
+## 1. PRD Document Completeness
+
+### Core Sections Present
+
+- [ ] Executive Summary with vision alignment
+- [ ] Product magic essence clearly articulated
+- [ ] Project classification (type, domain, complexity)
+- [ ] Success criteria defined
+- [ ] Product scope (MVP, Growth, Vision) clearly delineated
+- [ ] Functional requirements comprehensive and numbered
+- [ ] Non-functional requirements (when applicable)
+- [ ] References section with source documents
+
+### Project-Specific Sections
 
-- [ ] PRD.md created in output folder
-- [ ] epics.md created in output folder (separate file)
-- [ ] bmm-workflow-status.md updated
-- [ ] No unfilled {{template_variables}}
+- [ ] **If complex domain:** Domain context and considerations documented
+- [ ] **If innovation:** Innovation patterns and validation approach documented
+- [ ] **If API/Backend:** Endpoint specification and authentication model included
+- [ ] **If Mobile:** Platform requirements and device features documented
+- [ ] **If SaaS B2B:** Tenant model and permission matrix included
+- [ ] **If UI exists:** UX principles and key interactions documented
+
+### Quality Checks
+
+- [ ] No unfilled template variables ({{variable}})
+- [ ] All variables properly populated with meaningful content
+- [ ] Product magic woven throughout (not just stated once)
+- [ ] Language is clear, specific, and measurable
+- [ ] Project type correctly identified and sections match
+- [ ] Domain complexity appropriately addressed
 
 ---
 
-## 2. PRD.md Core Quality
+## 2. Functional Requirements Quality
 
-### Requirements Coverage
+### FR Format and Structure
 
-- [ ] Functional requirements describe WHAT capabilities (not HOW to implement)
-- [ ] Each FR has unique identifier (FR001, FR002, etc.)
-- [ ] Non-functional requirements (if any) have business justification
-- [ ] Requirements are testable and verifiable
+- [ ] Each FR has unique identifier (FR-001, FR-002, etc.)
+- [ ] FRs describe WHAT capabilities, not HOW to implement
+- [ ] FRs are specific and measurable
+- [ ] FRs are testable and verifiable
+- [ ] FRs focus on user/business value
+- [ ] No technical implementation details in FRs (those belong in architecture)
 
-### User Journeys
+### FR Completeness
 
-- [ ] User journeys reference specific FR numbers
-- [ ] Journeys show complete user paths through system
-- [ ] Success outcomes are clear
+- [ ] All MVP scope features have corresponding FRs
+- [ ] Growth features documented (even if deferred)
+- [ ] Vision features captured for future reference
+- [ ] Domain-mandated requirements included
+- [ ] Innovation requirements captured with validation needs
+- [ ] Project-type specific requirements complete
 
-### Strategic Focus
+### FR Organization
 
-- [ ] PRD focuses on WHAT and WHY (not technical HOW)
-- [ ] No specific technology choices in PRD (those belong in technical-decisions.md)
-- [ ] Goals are outcome-focused, not implementation-focused
+- [ ] FRs organized by capability/feature area (not by tech stack)
+- [ ] Related FRs grouped logically
+- [ ] Dependencies between FRs noted when critical
+- [ ] Priority/phase indicated (MVP vs Growth vs Vision)
 
 ---
 
-## 3. epics.md Story Quality
+## 3. Epics Document Completeness
+
+### Required Files
+
+- [ ] epics.md exists in output folder
+- [ ] Epic list in PRD.md matches epics in epics.md (titles and count)
+- [ ] All epics have detailed breakdown sections
 
-### Story Format
+### Epic Quality
 
-- [ ] All stories follow user story format: "As a [role], I want [capability], so that [benefit]"
+- [ ] Each epic has clear goal and value proposition
+- [ ] Each epic includes complete story breakdown
+- [ ] Stories follow proper user story format: "As a [role], I want [goal], so that [benefit]"
 - [ ] Each story has numbered acceptance criteria
-- [ ] Prerequisites/dependencies explicitly stated
+- [ ] Prerequisites/dependencies explicitly stated per story
+- [ ] Stories are AI-agent sized (completable in 2-4 hour session)
+
+---
 
-### Story Sequencing (CRITICAL)
+## 4. FR Coverage Validation (CRITICAL)
 
-- [ ] **Epic 1 establishes foundation** (infrastructure, initial deployable functionality)
-  - Exception noted if adding to existing app
-- [ ] **Vertical slices**: Each story delivers complete, testable functionality (not horizontal layers)
-- [ ] **No forward dependencies**: No story depends on work from a LATER story or epic
-- [ ] Stories are sequentially ordered within each epic
-- [ ] Each story leaves system in working state
+### Complete Traceability
 
-### Coverage
+- [ ] **Every FR from PRD.md is covered by at least one story in epics.md**
+- [ ] Each story references relevant FR numbers
+- [ ] No orphaned FRs (requirements without stories)
+- [ ] No orphaned stories (stories without FR connection)
+- [ ] Coverage matrix verified (can trace FR → Epic → Stories)
 
-- [ ] All FRs from PRD.md are covered by stories in epics.md
-- [ ] Epic list in PRD.md matches epics in epics.md (titles and count)
+### Coverage Quality
+
+- [ ] Stories sufficiently decompose FRs into implementable units
+- [ ] Complex FRs broken into multiple stories appropriately
+- [ ] Simple FRs have appropriately scoped single stories
+- [ ] Non-functional requirements reflected in story acceptance criteria
+- [ ] Domain requirements embedded in relevant stories
+
+---
+
+## 5. Story Sequencing Validation (CRITICAL)
+
+### Epic 1 Foundation Check
+
+- [ ] **Epic 1 establishes foundational infrastructure**
+- [ ] Epic 1 delivers initial deployable functionality
+- [ ] Epic 1 creates baseline for subsequent epics
+- [ ] Exception: If adding to existing app, foundation requirement adapted appropriately
+
+### Vertical Slicing
+
+- [ ] **Each story delivers complete, testable functionality** (not horizontal layers)
+- [ ] No "build database" or "create UI" stories in isolation
+- [ ] Stories integrate across stack (data + logic + presentation when applicable)
+- [ ] Each story leaves system in working/deployable state
+
+### No Forward Dependencies
+
+- [ ] **No story depends on work from a LATER story or epic**
+- [ ] Stories within each epic are sequentially ordered
+- [ ] Each story builds only on previous work
+- [ ] Dependencies flow backward only (can reference earlier stories)
+- [ ] Parallel tracks clearly indicated if stories are independent
+
+### Value Delivery Path
+
+- [ ] Each epic delivers significant end-to-end value
+- [ ] Epic sequence shows logical product evolution
+- [ ] User can see value after each epic completion
+- [ ] MVP scope clearly achieved by end of designated epics
+
+---
+
+## 6. Scope Management
+
+### MVP Discipline
+
+- [ ] MVP scope is genuinely minimal and viable
+- [ ] Core features list contains only true must-haves
+- [ ] Each MVP feature has clear rationale for inclusion
+- [ ] No obvious scope creep in "must-have" list
+
+### Future Work Captured
+
+- [ ] Growth features documented for post-MVP
+- [ ] Vision features captured to maintain long-term direction
+- [ ] Out-of-scope items explicitly listed
+- [ ] Deferred features have clear reasoning for deferral
+
+### Clear Boundaries
+
+- [ ] Stories marked as MVP vs Growth vs Vision
+- [ ] Epic sequencing aligns with MVP → Growth progression
+- [ ] No confusion about what's in vs out of initial scope
+
+---
+
+## 7. Research and Context Integration
+
+### Source Document Integration
+
+- [ ] **If product brief exists:** Key insights incorporated into PRD
+- [ ] **If domain brief exists:** Domain requirements reflected in FRs and stories
+- [ ] **If research documents exist:** Research findings inform requirements
+- [ ] **If competitive analysis exists:** Differentiation strategy clear in PRD
+- [ ] All source documents referenced in PRD References section
+
+### Research Continuity to Architecture
+
+- [ ] Domain complexity considerations documented for architects
+- [ ] Technical constraints from research captured
+- [ ] Regulatory/compliance requirements clearly stated
+- [ ] Integration requirements with existing systems documented
+- [ ] Performance/scale requirements informed by research data
+
+### Information Completeness for Next Phase
+
+- [ ] PRD provides sufficient context for architecture decisions
+- [ ] Epics provide sufficient detail for technical design
+- [ ] Stories have enough acceptance criteria for implementation
+- [ ] Non-obvious business rules documented
+- [ ] Edge cases and special scenarios captured
 
 ---
 
-## 4. Cross-Document Consistency
+## 8. Cross-Document Consistency
 
-- [ ] Epic titles consistent between PRD.md and epics.md
-- [ ] FR references in user journeys exist in requirements section
-- [ ] Terminology consistent across documents
+### Terminology Consistency
+
+- [ ] Same terms used across PRD and epics for concepts
+- [ ] Feature names consistent between documents
+- [ ] Epic titles match between PRD and epics.md
 - [ ] No contradictions between PRD and epics
 
+### Alignment Checks
+
+- [ ] Success metrics in PRD align with story outcomes
+- [ ] Product magic articulated in PRD reflected in epic goals
+- [ ] Technical preferences in PRD align with story implementation hints
+- [ ] Scope boundaries consistent across all documents
+
+---
+
+## 9. Readiness for Implementation
+
+### Architecture Readiness (Next Phase)
+
+- [ ] PRD provides sufficient context for architecture workflow
+- [ ] Technical constraints and preferences documented
+- [ ] Integration points identified
+- [ ] Performance/scale requirements specified
+- [ ] Security and compliance needs clear
+
+### Development Readiness
+
+- [ ] Stories are specific enough to estimate
+- [ ] Acceptance criteria are testable
+- [ ] Technical unknowns identified and flagged
+- [ ] Dependencies on external systems documented
+- [ ] Data requirements specified
+
+### Level-Appropriate Detail
+
+**If Level 2:**
+
+- [ ] PRD supports lightweight tech-spec workflow
+- [ ] 5-15 story scope reasonable for project size
+- [ ] Complexity appropriate for small team/solo dev
+
+**If Level 3-4:**
+
+- [ ] PRD supports full architecture workflow
+- [ ] Epic structure supports phased delivery
+- [ ] Scope appropriate for team-based development
+- [ ] Clear value delivery through epic sequence
+
 ---
 
-## 5. Readiness for Next Phase
+## 10. Quality and Polish
+
+### Writing Quality
 
-**Adapt based on project level from bmm-workflow-status.md:**
+- [ ] Language is clear and free of jargon (or jargon is defined)
+- [ ] Sentences are concise and specific
+- [ ] No vague statements ("should be fast", "user-friendly")
+- [ ] Measurable criteria used throughout
+- [ ] Professional tone appropriate for stakeholder review
 
-### If Level 2:
+### Document Structure
 
-- [ ] PRD provides sufficient context for tech-spec workflow (lightweight solutioning)
-- [ ] Epic structure supports 5-15 story implementation scope
+- [ ] Sections flow logically
+- [ ] Headers and numbering consistent
+- [ ] Cross-references accurate (FR numbers, section references)
+- [ ] Formatting consistent throughout
+- [ ] Tables/lists formatted properly
 
-### If Level 3-4:
+### Completeness Indicators
 
-- [ ] PRD provides sufficient context for create-architecture workflow
-- [ ] Epic structure supports phased delivery approach
-- [ ] Clear value delivery path through epic sequence
+- [ ] No [TODO] or [TBD] markers remain
+- [ ] No placeholder text
+- [ ] All sections have substantive content
+- [ ] Optional sections either complete or omitted (not half-done)
 
 ---
 
-## 6. Critical Failures (Auto-Fail)
+## Critical Failures (Auto-Fail)
 
-- [ ] ❌ **No epics.md file** (two-file output is required)
-- [ ] ❌ **Epic 1 doesn't establish foundation** (violates core principle)
-- [ ] ❌ **Stories have forward dependencies** (would break sequential implementation)
+If ANY of these are true, validation FAILS:
+
+- [ ] ❌ **No epics.md file exists** (two-file output required)
+- [ ] ❌ **Epic 1 doesn't establish foundation** (violates core sequencing principle)
+- [ ] ❌ **Stories have forward dependencies** (breaks sequential implementation)
 - [ ] ❌ **Stories not vertically sliced** (horizontal layers block value delivery)
-- [ ] ❌ **Technical decisions in PRD** (should be in technical-decisions.md)
 - [ ] ❌ **Epics don't cover all FRs** (orphaned requirements)
-- [ ] ❌ **User journeys don't reference FR numbers** (missing traceability)
+- [ ] ❌ **FRs contain technical implementation details** (should be in architecture)
+- [ ] ❌ **No FR traceability to stories** (can't validate coverage)
+- [ ] ❌ **Template variables unfilled** (incomplete document)
 
 ---
 
-## Validation Notes
+## Validation Summary
+
+**Total Validation Points:** ~85
 
-**Document any findings:**
+### Scoring Guide
 
-- Strengths:
-- Issues to address:
-- Recommended actions:
+- **Pass Rate ≥ 95% (81+/85):** ✅ EXCELLENT - Ready for architecture phase
+- **Pass Rate 85-94% (72-80/85):** ⚠️ GOOD - Minor fixes needed
+- **Pass Rate 70-84% (60-71/85):** ⚠️ FAIR - Important issues to address
+- **Pass Rate < 70% (<60/85):** ❌ POOR - Significant rework required
+
+### Critical Issue Threshold
+
+- **0 Critical Failures:** Proceed to fixes
+- **1+ Critical Failures:** STOP - Must fix critical issues first
+
+---
 
-**Ready for next phase?** [Yes / No - explain]
+## Validation Execution Notes
+
+**When validating:**
+
+1. **Load ALL documents:**
+   - PRD.md (required)
+   - epics.md (required)
+   - product-brief.md (if exists)
+   - domain-brief.md (if exists)
+   - research documents (if referenced)
+
+2. **Validate in order:**
+   - Check critical failures first (immediate stop if any found)
+   - Verify PRD completeness
+   - Verify epics completeness
+   - Cross-reference FR coverage (most important)
+   - Check sequencing (second most important)
+   - Validate research integration
+   - Check polish and quality
+
+3. **Report findings:**
+   - List critical failures prominently
+   - Group issues by severity
+   - Provide specific line numbers/sections
+   - Suggest concrete fixes
+   - Highlight what's working well
+
+4. **Provide actionable next steps:**
+   - If validation passes: "Ready for architecture workflow"
+   - If minor issues: "Fix [X] items then re-validate"
+   - If major issues: "Rework [sections] then re-validate"
+   - If critical failures: "Must fix critical items before proceeding"
 
 ---
 
-_Adapt this checklist based on actual outputs. Not all sections may apply to every project._
+**Remember:** This validation ensures the entire planning phase is complete and the implementation phase has everything needed to succeed. Be thorough but fair - the goal is quality, not perfection.

package/src/modules/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/epics-template.md

@@ -0,0 +1,63 @@
+# {{project_name}} - Epic Breakdown
+
+**Author:** {{user_name}}
+**Date:** {{date}}
+**Project Level:** {{project_level}}
+**Target Scale:** {{target_scale}}
+
+---
+
+## Overview
+
+This document provides the detailed epic breakdown for {{project_name}}, expanding on the high-level epic list in the [PRD](./PRD.md).
+
+Each epic includes:
+
+- Expanded goal and value proposition
+- Complete story breakdown with user stories
+- Acceptance criteria for each story
+- Story sequencing and dependencies
+
+**Epic Sequencing Principles:**
+
+- Epic 1 establishes foundational infrastructure and initial functionality
+- Subsequent epics build progressively, each delivering significant end-to-end value
+- Stories within epics are vertically sliced and sequentially ordered
+- No forward dependencies - each story builds only on previous work
+
+---
+
+{{epic_details}}
+
+---
+
+## Story Guidelines Reference
+
+**Story Format:**
+
+```
+**Story [EPIC.N]: [Story Title]**
+
+As a [user type],
+I want [goal/desire],
+So that [benefit/value].
+
+**Acceptance Criteria:**
+1. [Specific testable criterion]
+2. [Another specific criterion]
+3. [etc.]
+
+**Prerequisites:** [Dependencies on previous stories, if any]
+```
+
+**Story Requirements:**
+
+- **Vertical slices** - Complete, testable functionality delivery
+- **Sequential ordering** - Logical progression within epic
+- **No forward dependencies** - Only depend on previous work
+- **AI-agent sized** - Completable in 2-4 hour focused session
+- **Value-focused** - Integrate technical enablers into value-delivering stories
+
+---
+
+**For implementation:** Use the `create-story` workflow to generate individual story implementation plans from this epic breakdown.