minor udpates to prd, architecture, and create epics and stories flows.

2025-11-26 00:28:49 -06:00 · 2025-11-26 00:28:49 -06:00 · d6b98afd2b
parent 24e952c511
commit d6b98afd2b
6 changed files with 564 additions and 746 deletions
--- a/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md
+++ b/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md
@ -35,11 +35,6 @@ After discovery completes, the following content variables will be available:
  <action>Check status of "product-brief" workflow</action>
  <action>Get project_level from YAML metadata</action>
  <action>Find first non-completed workflow (next expected workflow)</action>
  <check if="project_level < 2">
    <output>**Note: Level {{project_level}} Project**
 Product Brief is most valuable for Level 2+ projects, but can help clarify vision for any project.</output>
 </check>
  <check if="product-brief status is file path (already completed)">
@ -71,18 +66,14 @@ Product Brief is most valuable for Level 2+ projects, but can help clarify visio
 <step n="1" goal="Begin the journey and understand context">
 <action>Welcome {user_name} warmly in {communication_language}
 Adapt your tone to {user_skill_level}:
 - Expert: "Let's define your product vision. What are you building?"
 - Intermediate: "I'm here to help shape your product vision. Tell me about your idea."
 - Beginner: "Hi! I'm going to help you figure out exactly what you want to build. Let's start with your idea - what got you excited about this?"
 Start with open exploration:
 - What sparked this idea?
 - What are you hoping to build?
 - Who is this for - yourself, a business, users you know?
 - "I'm here to help shape your product vision. Tell me about your idea and what got you excited about this? The more detail you can give me here the better I can help you further craft the idea."
 CRITICAL: Listen for context clues that reveal their situation:
 - Personal/hobby project (fun, learning, small audience)
@ -99,7 +90,7 @@ Based on their initial response, sense:
 - If they have existing materials to share
 - Their confidence level with the domain</action>
-<ask>What's the project name, and what got you excited about building this?</ask>
+<ask if="user has not given the project name already">What's the project name?</ask>
 <action>From even this first exchange, create initial document sections</action>
 <template-output>project_name</template-output>
--- a/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md
@ -1,16 +1,17 @@
 # PRD Workflow - Intent-Driven Product Planning
-<critical>The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml</critical>
+<critical-rules>
-<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+- <critical>The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml</critical>
-<critical>This workflow uses INTENT-DRIVEN PLANNING - adapt organically to product type and context</critical>
+- <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-<critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
+- <critical>This workflow uses INTENT-DRIVEN PLANNING - adapt organically to product type and context</critical>
-<critical>Generate all documents in {document_output_language}</critical>
+- <critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
-<critical>LIVING DOCUMENT: Write to PRD.md continuously as you discover - never wait until the end</critical>
+- <critical>Generate all documents in {document_output_language}</critical>
-<critical>GUIDING PRINCIPLE: Identify what makes this product special and ensure it's reflected throughout the PRD</critical>
+- <critical>LIVING DOCUMENT: Write to PRD.md continuously as you discover - never wait until the end</critical>
-<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
+- <critical>GUIDING PRINCIPLE: Identify what makes this product special and ensure it's reflected throughout the PRD</critical>
-<critical>⚠️ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever.</critical>
+- <critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
-<critical>⚠️ CHECKPOINT PROTOCOL: After EVERY <template-output> tag, you MUST follow workflow.xml substep 2c: SAVE content to file immediately → SHOW checkpoint separator (━━━━━━━━━━━━━━━━━━━━━━━) → DISPLAY generated content → PRESENT options [a]Advanced Elicitation/[c]Continue/[p]Party-Mode/[y]YOLO → WAIT for user response. Never batch saves or skip checkpoints.</critical>
+- <critical>⚠️ CHECKPOINT PROTOCOL: After EVERY template-output tag, you MUST follow workflow.xml substep 2c. </critical>
-
+- <critical>YOU ARE FACILITATING A CONVERSATION With a user to produce a final document step by step. The whole process is meant to be collaborative helping the user flesh out their ideas</critical>
 </critical-rules>
 <workflow>
 <step n="0" goal="Validate workflow readiness" tag="workflow-status">
@ -24,13 +25,7 @@
  <action>Check status of "prd" workflow</action>
  <action>Get project_track from YAML metadata</action>
  <action>Find first non-completed workflow (next expected workflow)</action>
-
+</output>
  <check if="project_track is Quick Flow">
    <output>**Quick Flow Track - Redirecting**
 Quick Flow projects use tech-spec workflow for implementation-focused planning.
 PRD is for BMad Method and Enterprise Method tracks that need comprehensive requirements.</output>
 <action>Exit and suggest tech-spec workflow</action>
 </check>
  <check if="prd status is file path (already completed)">
@ -145,40 +140,63 @@ Capture this differentiator - it becomes a thread connecting throughout the PRD.
 <template-output>product_brief_path</template-output>
 <template-output>domain_brief_path</template-output>
 <template-output>research_documents</template-output>
 <critical>You MUST display the checkpoint display and HALT for user input, unless the user enabled YOLO mode.</critical>
  <checkpoint title="Discovery Complete">
    <display>[a] Advanced Elicitation [c] Continue [p] Party Mode</display>
    <checkpoint-handlers>
      <on-select key="a">Load and execute {advanced_elicitation} task, then return to this checkpoint</on-select>
      <on-select key="p">Load and execute {party_mode}, then return to this checkpoint</on-select>
      <on-select key="c"> Ensure all content is written to {default_output_file}</on-select>
    </checkpoint-handlers>
  </checkpoint>
 </step>
 <step n="2" goal="Success Definition">
  <action>Define what winning looks like for THIS specific product
-INTENT: Meaningful success criteria, not generic metrics
+**User Success First**
 Ask:
-Adapt to context:
+- "What would make a user say 'this was worth it'?"
 - "What moment makes them tell a friend about this?"
 - "After [key journey], what outcome are they walking away with?"
 **Business Success Second**
 Ask:
 - "What does success look like for your business at 3 months? 12 months?"
 - "Is this about revenue, user growth, engagement, something else?"
 - "What metric would make you say 'this is working'?"
 **Make It Specific**
 Challenge vague metrics:
 - NOT: "10,000 users" → "What kind of users? Doing what?"
 - NOT: "99.9% uptime" → "What's the real concern - data loss? Failed payments?"
 - NOT: "Fast" → "How fast, and what specifically needs to be fast?"
 Ask: "Can we measure this? How would you know if you hit it?"
 **Connect to Differentiator**
 Bring it back to the core:
 "So success means users experience [differentiator] and achieve [outcome] - does that capture it?"
 Adapt success criteria to context:
 - Consumer: User love, engagement, retention
 - B2B: ROI, efficiency, adoption
 - Developer tools: Developer experience, community
- Regulated: Compliance, safety, validation
+- Regulated: Compliance, safety, validation</action>
 Make it specific:
 - NOT: "10,000 users"
 - BUT: "100 power users who rely on it daily"
 - NOT: "99.9% uptime"
 - BUT: "Zero data loss during critical operations"
 Connect to what makes the product special:
 - "Success means users experience [key value moment] and achieve [desired outcome]"</action>
  <template-output>success_criteria</template-output>
  <check if="business focus">
  <template-output>business_metrics</template-output>
  </check>
 </step>
-<step n="3" goal="Scope Definition">
+  <action>Smart scope negotiation - find the sweet spot based on success:
 <action>Smart scope negotiation - find the sweet spot
 The Scoping Game:
@ -199,11 +217,140 @@ For complex domains:
  <template-output>mvp_scope</template-output>
  <template-output>growth_features</template-output>
  <template-output>vision_features</template-output>
  <critical>You MUST display the checkpoint display and HALT for user input, unless the user enabled YOLO mode.</critical>
    <checkpoint title="Success and Scope Complete">
      <display>[a] Advanced Elicitation [c] Continue [p] Party Mode [u] User Interview</display>
      <checkpoint-handlers>
        <on-select key="a">Load and execute {advanced_elicitation} task, then return to this checkpoint</on-select>
        <on-select key="p">Load and execute {party_mode}, then return to this checkpoint</on-select>
        <on-select key="u">Load and execute {party_mode} but the party will include the users from the User Journeys section. The discussion can start with each user saying hello and giving their initial thoughts, then return to this checkpoint.</on-select>
        <on-select key="c"> Ensure all content is written to {default_output_file}</on-select>
      </checkpoint-handlers>
    </checkpoint>
  </step>
-<step n="4" goal="Domain-Specific Exploration" optional="true">
+<step n="3" goal="User Journeys">
-<critical>This step is DATA-DRIVEN using domain_complexity_data CSV loaded in Step 1</critical>
+<critical>This step covers ALL user types - end users, admins, moderators, support, API consumers. If a human interacts with the system, there's a journey. No journey = no FRs = doesn't exist.</critical>
-<action>Execute only if complexity_level = "high" OR domain-brief exists</action>
+
 <action>Identify all user types first:
 Before exploring journeys, ask the user:
 "Besides the primary user, who else interacts with this system?"
 Consider these common user types:
 - End users (primary)
 - Admins - manage users, settings, content
 - Moderators - review flagged content, enforce rules
 - Support staff - help users, investigate issues
 - API consumers - if dev tool or platform
 - Internal ops - analytics, monitoring, billing
 List all user types before proceeding.</action>
 <action>Create detailed narrative user journeys with personas:
 For each user type identified, create rich, detailed journeys following this pattern:
 **Journey Creation Process:**
 **1. Develop the Persona**
 Give them a name, context, and motivation:
 - **Name**: Realistic name (Maria, Marcus, Jordan, etc.)
 - **Backstory**: Who they are, what they want, why they need this
 - **Motivation**: Core problem they're trying to solve
 - **Emotional state**: How they feel about solving this problem
 Example: "Maria is a working parent who wants to cook healthy meals for her family but struggles with meal planning and limited evening time. She's tired of the same rotating dishes and wants inspiration that fits her schedule."
 **2. Map Their Complete Journey**
 Document their end-to-end experience:
 - **Entry point**: How they discover and access the product
 - **Key steps**: Each touchpoint in sequence (use arrows →)
 - **Critical actions**: What they do at each step
 - **Decision points**: Choices they make
 - **Success moment**: Where they achieve their goal
 - **Exit point**: How the journey concludes
 **3. Use This Exact Format for Each Journey:**
 **Journey [Number]: [Persona Name] - [Journey Theme]**
 [Persona description with backstory and motivation]
 - [Entry point] → [step 1] → [step 2] → [step 3] → [critical moment] → [step N] → [completion]
 **4. Explore Journey Details Conversationally**
 For each journey, ask:
 - "What happens at each step specifically?"
 - "What could go wrong here? What's the recovery path?"
 - "What information do they need to see/hear?"
 - "What's their emotional state at each point?"
 - "Where does this journey succeed or fail?"
 **5. Connect Journeys to Requirements**
 After each journey, explicitly state:
 "This journey reveals requirements for:"
 - List specific capability areas (e.g., onboarding, meal planning, admin dashboard)
 - Help user see how different journeys create different feature sets
 **Example Output Structure:**
 **Journey 1: Maria - First Recipe Discovery**
 Maria is a working parent who wants to cook healthy meals for her family but struggles with meal planning...
 - Discovers via search → lands on recipe page → signs up → completes preferences → browses recommendations → saves first recipe → adds to meal plan
 **Journey 2: [Persona] - [Theme]**
 [Persona description with context]
 - [Step sequence] → [critical moment] → [completion]
 **Journey 3: [Admin/Support Persona] - [Admin Theme]**
 [Admin persona description]
 - [Admin workflow] → [decision point] → [system outcome]</action>
 <action>Guide journey exploration to cover all key areas:
 **Aim for 3-4 journeys minimum:**
 1. Primary user - happy path (core experience)
 2. Primary user - edge case (different goal, error recovery)
 3. Secondary user (admin, moderator, support, etc.)
 4. API consumer (if applicable)
 **Ask after each:** "Another journey? We should cover [suggest uncovered user type]"
 **Use journeys to reveal requirements:**
 Each journey reveals different capabilities needed:
 - Admin journey → admin dashboard, user management
 - Support journey → ticket system, user lookup tools
 - API journey → documentation, rate limiting, keys
 - Error recovery → retry mechanisms, help content</action>
 <template-output>user_journeys</template-output>
 <critical>You MUST display the checkpoint display and HALT for user input, unless the user enabled YOLO mode.</critical>
 <checkpoint title="User Journeys Complete">
  <display>[a] Advanced Elicitation [c] Continue [p] Party Mode [u] User Interview</display>
  <checkpoint-handlers>
    <on-select key="a">Load and execute {advanced_elicitation} task, then return to this checkpoint</on-select>
    <on-select key="p">Load and execute {party_mode}, then return to this checkpoint</on-select>
    <on-select key="u">Load and execute {party_mode} but the party will include the users from the User Journeys section. The discussion can start with each user saying hello and giving their initial thoughts, then return to this checkpoint.</on-select>
    <on-select key="c"> Ensure all content is written to {default_output_file}</on-select>
  </checkpoint-handlers>
 </checkpoint>
 </step>
 <step n="5" goal="Domain-Specific Exploration" optional="true">
 <critical>This step is DATA-DRIVEN using {domain_complexity_data} CSV loaded in Step 1</critical>
 <action>Retrieve domain-specific configuration from CSV:
@ -253,7 +400,6 @@ These inform:
 - What validation is required
  </action>
 <check if="complexity_level == 'high'">
  <template-output>domain_considerations</template-output>
 <action>Generate domain-specific special sections if defined:
@ -268,9 +414,20 @@ Example mappings from CSV:
 - "compliance_matrix" → <template-output>compliance_matrix</template-output>
  </action>
  </check>
  <critical>You MUST display the checkpoint display and HALT for user input, unless the user enabled YOLO mode.</critical>
 <checkpoint title="Domain Exploration Complete">
  <display>[a] Advanced Elicitation [c] Continue [p] Party Mode [u] User Interview</display>
  <checkpoint-handlers>
    <on-select key="a">Load and execute {advanced_elicitation} task, then return to this checkpoint</on-select>
    <on-select key="p">Load and execute {party_mode}, then return to this checkpoint</on-select>
    <on-select key="u">Load and execute {party_mode} but the party will include the users from the User Journeys section. The discussion can start with each user saying hello and giving their initial thoughts, then return to this checkpoint.</on-select>
    <on-select key="c"> Ensure all content is written to {default_output_file}</on-select>
  </checkpoint-handlers>
 </checkpoint>
  </step>
-<step n="5" goal="Innovation Discovery" optional="true">
+<step n="6" goal="Innovation Discovery" optional="true">
 <critical>This step uses innovation_signals from project_types_data CSV loaded in Step 1</critical>
 <action>Check for innovation in this product:
@ -323,9 +480,20 @@ Use web_search_triggers from project_types_data CSV if relevant:
  <template-output>innovation_patterns</template-output>
  <template-output>validation_approach</template-output>
 </check>
 <critical>You MUST display the checkpoint display and HALT for user input, unless the user enabled YOLO mode.</critical>
 <checkpoint title="Innovation Discovery Complete">
  <display>[a] Advanced Elicitation [c] Continue [p] Party Mode [u] User Interview</display>
  <checkpoint-handlers>
    <on-select key="a">Load and execute {advanced_elicitation} task, then return to this checkpoint</on-select>
    <on-select key="p">Load and execute {party_mode}, then return to this checkpoint</on-select>
    <on-select key="u">Load and execute {party_mode} but the party will include the users from the User Journeys section. The discussion can start with each user saying hello and giving their initial thoughts, then return to this checkpoint.</on-select>
    <on-select key="c"> Ensure all content is written to {default_output_file}</on-select>
  </checkpoint-handlers>
 </checkpoint>
 </step>
-<step n="6" goal="Project-Specific Deep Dive">
+<step n="7" goal="Project-Specific Deep Dive">
 <critical>This step is DATA-DRIVEN using project_types_data CSV loaded in Step 1</critical>
 <action>Retrieve project-specific configuration from CSV:
@ -421,30 +589,20 @@ For required_sections that DON'T have matching template variables:
 This hybrid approach balances template structure with CSV-driven flexibility.
 </note>
 <critical>You MUST display the checkpoint display and HALT for user input, unless the user enabled YOLO mode.</critical>
 <checkpoint title="Project-Specific Deep Dive Complete">
  <display>[a] Advanced Elicitation [c] Continue [p] Party Mode [u] User Interview</display>
  <checkpoint-handlers>
    <on-select key="a">Load and execute {advanced_elicitation} task, then return to this checkpoint</on-select>
    <on-select key="p">Load and execute {party_mode}, then return to this checkpoint</on-select>
    <on-select key="u">Load and execute {party_mode} but the party will include the users from the User Journeys section. The discussion can start with each user saying hello and giving their initial thoughts, then return to this checkpoint.</on-select>
    <on-select key="c"> Ensure all content is written to {default_output_file}</on-select>
  </checkpoint-handlers>
 </checkpoint>
 </step>
-<step n="7" goal="UX Principles" if="project has UI or UX">
+<step n="9" goal="Functional Requirements Synthesis">
  <action>Only if product has a UI
 Light touch on UX - not full design:
 - Visual personality
 - Key interaction patterns
 - Critical user flows
 "How should this feel to use?"
 "What's the vibe - professional, playful, minimal?"
 Connect UX to product vision:
 "The UI should reinforce [core value proposition] through [design approach]"</action>
  <check if="has UI">
    <template-output>ux_principles</template-output>
    <template-output>key_interactions</template-output>
  </check>
 </step>
 <step n="8" goal="Functional Requirements Synthesis">
 <critical>This section is THE CAPABILITY CONTRACT for all downstream work</critical>
 <critical>UX designers will ONLY design what's listed here</critical>
 <critical>Architects will ONLY support what's listed here</critical>
@ -457,12 +615,18 @@ Connect UX to product vision:
 FRs define WHAT capabilities the product must have. They are the complete inventory
 of user-facing and system capabilities that deliver the product vision.
 **Notice:**
 ✅ Each FR is a testable capability
 ✅ Each FR is implementation-agnostic (could be built many ways)
 ✅ Each FR specifies WHO and WHAT, not HOW
 ✅ No UI details, no performance numbers, no technology choices
 ✅ Comprehensive coverage of capability areas
 **How They Will Be Used:**
 1. UX Designer reads FRs → designs interactions for each capability
 2. Architect reads FRs → designs systems to support each capability
 3. PM reads FRs → creates epics and stories to implement each capability
 4. Dev Agent reads assembled context → implements stories based on FRs
 **Critical Property - COMPLETENESS:**
 Every capability discussed in vision, scope, domain requirements, and project-specific
@ -475,15 +639,6 @@ specific UI/UX details. Those come later from UX and Architecture.
 <action>Transform everything discovered into comprehensive functional requirements:
 **Coverage - Pull from EVERYWHERE:**
 - Core features from MVP scope → FRs
 - Growth features → FRs (marked as post-MVP if needed)
 - Domain-mandated features → FRs
 - Project-type specific needs → FRs
 - Innovation requirements → FRs
 - Anti-patterns (explicitly NOT doing) → Note in FR section if needed
 **Organization - Group by CAPABILITY AREA:**
 Don't organize by technology or layer. Group by what users/system can DO:
@ -515,45 +670,23 @@ The second example belongs in Epic Breakdown, not PRD.
 - FR1: Users can create accounts with email or social authentication
 - FR2: Users can log in securely and maintain sessions across devices
 - FR3: Users can reset passwords via email verification
- FR4: Users can update profile information and preferences
+- ...
 - FR5: Administrators can manage user roles and permissions
 **Content Management:**
 - FR6: Users can create, edit, and delete content items
 - FR7: Users can organize content with tags and categories
 - FR8: Users can search content by keyword, tag, or date range
 - FR9: Users can export content in multiple formats
 **Data Ownership (local-first products):**
 - FR10: All user data stored locally on user's device
 - FR11: Users can export complete data at any time
- FR12: Users can import previously exported data
+- ...
 - FR13: System monitors storage usage and warns before limits
 **Collaboration:**
 - FR14: Users can share content with specific users or teams
 - FR15: Users can comment on shared content
- FR16: Users can track content change history
+- ...
 - FR17: Users receive notifications for relevant updates
 **Notice:**
 ✅ Each FR is a testable capability
 ✅ Each FR is implementation-agnostic (could be built many ways)
 ✅ Each FR specifies WHO and WHAT, not HOW
 ✅ No UI details, no performance numbers, no technology choices
 ✅ Comprehensive coverage of capability areas
 </example>
-<action>Generate the complete FR list by systematically extracting capabilities:
+<action>Generate the complete FR list by systematically extracting capabilities from all discussed so far for all that is in scope.
 1. MVP scope → extract all capabilities → write as FRs
 2. Growth features → extract capabilities → write as FRs (note if post-MVP)
 3. Domain requirements → extract mandatory capabilities → write as FRs
 4. Project-type specifics → extract type-specific capabilities → write as FRs
 5. Innovation patterns → extract novel capabilities → write as FRs
 Organize FRs by logical capability groups (5-8 groups typically).
 Number sequentially across all groups (FR1, FR2... FR47).
@ -586,9 +719,20 @@ COMPLETENESS GATE: Review your FR list against the entire PRD written so far and
 </action>
 <template-output>functional_requirements_complete</template-output>
 <critical>You MUST display the checkpoint display and HALT for user input, unless the user enabled YOLO mode.</critical>
 <checkpoint title="Functional Requirements Complete">
  <display>[a] Advanced Elicitation [c] Continue [p] Party Mode [u] User Interview</display>
  <checkpoint-handlers>
    <on-select key="a">Load and execute {advanced_elicitation} task, then return to this checkpoint</on-select>
    <on-select key="p">Load and execute {party_mode}, then return to this checkpoint</on-select>
    <on-select key="u">Load and execute {party_mode} but the party will include the users from the User Journeys section. The discussion can start with each user saying hello and giving their initial thoughts, then return to this checkpoint.</on-select>
    <on-select key="c"> Ensure all content is written to {default_output_file}</on-select>
  </checkpoint-handlers>
 </checkpoint>
 </step>
-<step n="9" goal="Non-Functional Requirements Discovery">
+<step n="10" goal="Non-Functional Requirements Discovery">
 <action>Only document NFRs that matter for THIS product
 Performance: Only if user-facing impact
@ -623,26 +767,26 @@ Skip categories that don't apply!</action>
 </check>
 </step>
-<step n="10" goal="Complete PRD and determine next steps">
+<step n="11" goal="Complete PRD and determine next steps">
-<action>Quick review of captured requirements:
+<action>Announce that the PRD is complete and the unused sections will be cleaned up from the output document!</action>
-"We've captured:
+<action>CRITICAL: Clean up the PRD document before validation:
- {{fr_count}} functional requirements
+Before running validation, you MUST remove any empty sections from the generated PRD:
 - {{nfr_count}} non-functional requirements
 - MVP scope defined
  {{if domain_complexity == 'high'}}
 - Domain-specific requirements addressed
  {{/if}}
  {{if innovation_detected}}
 - Innovation patterns documented
  {{/if}}
-Your PRD is complete!"
+1. **Scan for empty sections** - Look for sections with no meaningful content (just whitespace or placeholder text)
-</action>
+2. **Remove entire empty sections** - Delete the section header and any empty content
 3. **Keep relevant sections only** - If a project type doesn't need certain sections (e.g., API specs for a mobile app), remove those sections entirely
 4. **Ensure document flows logically** - The final PRD should only contain sections with actual content
-<template-output>prd_summary</template-output>
+**This cleanup step is essential because:**
-<template-output>product_value_summary</template-output>
+
 - The template includes all possible sections for maximum flexibility
 - Not all sections apply to every project type
 - Empty sections make the PRD look incomplete and unprofessional
 - Validation expects meaningful content in all included sections
 **Example:** If building a CLI tool, you'd typically remove: API Specification, Platform Support, Device Capabilities, Multi-Tenancy Architecture, User Experience Principles sections.</action>
 <check if="standalone_mode != true">
  <action>Load the FULL file: {status_file}</action>
@ -660,43 +804,16 @@ Your PRD is complete!"
 <output>**✅ PRD Complete, {user_name}!**
 **Created:** PRD.md with {{fr_count}} FRs and NFRs
 **Next Steps:**
 <check if="standalone_mode != true">
 Based on your {{project_track}} workflow path, you can:
 **Option A: Create Epic Breakdown Now** (Optional)
 `workflow create-epics-and-stories`
 - Creates basic epic structure from PRD
 - Can be enhanced later with UX/Architecture context
 <check if="UI_exists">
 **Option B: UX Design First** (Recommended if UI)
   `workflow create-ux-design`
   - Design user experience and interactions
   - Epic breakdown can incorporate UX details later
 </check>
 **Option C: Skip to Architecture**
 `workflow create-architecture`
 - Define technical decisions
 - Epic breakdown created after with full context
 **Recommendation:** {{if UI_exists}}Do UX Design first, then Architecture, then create epics with full context{{else}}Go straight to Architecture, then create epics{{/if}}
 </check>
 <check if="standalone_mode == true">
 **Typical next workflows:**
 1. `workflow create-ux-design` - UX Design (if UI exists)
 2. `workflow create-architecture` - Technical architecture
 3. `workflow create-epics-and-stories` - Epic breakdown
 **Note:** Epics can be created at any point but have richer detail when created after UX/Architecture.
-</check>
+
 </output>
 </step>
--- a/src/modules/bmm/workflows/2-plan-workflows/prd/prd-template.md
+++ b/src/modules/bmm/workflows/2-plan-workflows/prd/prd-template.md
@ -16,6 +16,12 @@
 ---
 ## User Journeys
 {{user_journeys}}
 ---
 ## Project Classification
 **Technical Type:** {{project_type}}
@ -24,12 +30,9 @@
 {{project_classification}}
 {{#if domain_context_summary}}
 ### Domain Context
 {{domain_context_summary}}
 {{/if}}
 ---
@ -37,13 +40,6 @@
 {{success_criteria}}
 {{#if business_metrics}}
 ### Business Metrics
 {{business_metrics}}
 {{/if}}
 ---
 ## Product Scope
@ -62,19 +58,14 @@
 ---
 {{#if domain_considerations}}
 ## Domain-Specific Requirements
 {{domain_considerations}}
 This section shapes all functional and non-functional requirements below.
 {{/if}}
 ---
 {{#if innovation_patterns}}
 ## Innovation & Novel Patterns
 {{innovation_patterns}}
@ -82,63 +73,39 @@ This section shapes all functional and non-functional requirements below.
 ### Validation Approach
 {{validation_approach}}
 {{/if}}
 ---
 {{#if project_type_requirements}}
 ## {{project_type}} Specific Requirements
 {{project_type_requirements}}
 {{#if endpoint_specification}}
 ### API Specification
 {{endpoint_specification}}
 {{/if}}
 {{#if authentication_model}}
 ### Authentication & Authorization
 {{authentication_model}}
 {{/if}}
 {{#if platform_requirements}}
 ### Platform Support
 {{platform_requirements}}
 {{/if}}
 {{#if device_features}}
 ### Device Capabilities
 {{device_features}}
 {{/if}}
 {{#if tenant_model}}
 ### Multi-Tenancy Architecture
 {{tenant_model}}
 {{/if}}
 {{#if permission_matrix}}
 ### Permissions & Roles
 {{permission_matrix}}
 {{/if}}
 {{/if}}
 ---
 {{#if ux_principles}}
 ## User Experience Principles
 {{ux_principles}}
@ -146,7 +113,6 @@ This section shapes all functional and non-functional requirements below.
 ### Key Interactions
 {{key_interactions}}
 {{/if}}
 ---
@ -158,44 +124,25 @@ This section shapes all functional and non-functional requirements below.
 ## Non-Functional Requirements
 {{#if performance_requirements}}
 ### Performance
 {{performance_requirements}}
 {{/if}}
 {{#if security_requirements}}
 ### Security
 {{security_requirements}}
 {{/if}}
 {{#if scalability_requirements}}
 ### Scalability
 {{scalability_requirements}}
 {{/if}}
 {{#if accessibility_requirements}}
 ### Accessibility
 {{accessibility_requirements}}
 {{/if}}
 {{#if integration_requirements}}
 ### Integration
 {{integration_requirements}}
 {{/if}}
 {{#if no_nfrs}}
 _No specific non-functional requirements identified for this project type._
 {{/if}}
 ---
--- a/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml
+++ b/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml
@ -24,6 +24,10 @@ prd_template: "{installed_path}/prd-template.md"
 project_types_data: "{installed_path}/project-types.csv"
 domain_complexity_data: "{installed_path}/domain-complexity.csv"
 # External workflows for checkpoints
 advanced_elicitation: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.md"
 party_mode: "{project-root}/{bmad_folder}/core/workflows/party-mode.md"
 # Output files
 status_file: "{output_folder}/bmm-workflow-status.yaml"
 default_output_file: "{output_folder}/prd.md"
@ -37,13 +41,11 @@ input_file_patterns:
    whole: "{output_folder}/*brief*.md"
    sharded: "{output_folder}/*brief*/index.md"
    load_strategy: "FULL_LOAD"
  research:
    description: "Market or domain research (optional)"
    whole: "{output_folder}/*research*.md"
    sharded: "{output_folder}/*research*/index.md"
    load_strategy: "FULL_LOAD"
  document_project:
    description: "Brownfield project documentation (optional)"
    sharded: "{output_folder}/index.md"
--- a/src/modules/bmm/workflows/3-solutioning/create-epics-and-stories/instructions.md
+++ b/src/modules/bmm/workflows/3-solutioning/create-epics-and-stories/instructions.md
@ -1,13 +1,11 @@
-# Epic and Story Decomposition - Intent-Based Implementation Planning
+# Epic and Story Creation with Full Technical Context
 <critical>The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-<critical>This workflow transforms requirements into BITE-SIZED STORIES for development agents</critical>
+<critical>PREREQUISITES: PRD.md AND Architecture.md MUST be completed before running this workflow</critical>
 <critical>UX Design.md is highly recommended if the product has user interfaces</critical>
 <critical>EVERY story must be completable by a single dev agent in one focused session</critical>
-<critical>⚠️ EPIC STRUCTURE PRINCIPLE: Each epic MUST deliver USER VALUE, not just technical capability. Epics are NOT organized by technical layers (database, API, frontend). Each epic should result in something USERS can actually use or benefit from. Exception: Foundation/setup stories at the start of first epic are acceptable. Another valid exception: API-first epic ONLY when the API itself has standalone value (e.g., will be consumed by third parties or multiple frontends).</critical>
+<critical>⚠️ EPIC STRUCTURE PRINCIPLE: Each epic MUST deliver USER VALUE, not just technical capability. Epics are NOT organized by technical layers (database, API, frontend). Each epic should result in something USERS can actually use or benefit from. Exception: Foundation/setup stories at the start of first epic are acceptable.</critical>
 <critical>BMAD METHOD WORKFLOW POSITION: This workflow can be invoked at multiple points - after PRD only, after PRD+UX, after PRD+UX+Architecture, or to update existing epics. If epics.md already exists, ASK the user: (1) CONTINUING - previous run was incomplete, (2) REPLACING - starting fresh/discarding old, (3) UPDATING - new planning document created since last epic generation</critical>
 <critical>This is a LIVING DOCUMENT that evolves through the BMad Method workflow chain</critical>
 <critical>Phase 4 Implementation pulls context from: PRD + epics.md + UX + Architecture</critical>
 <critical>Communicate all responses in {communication_language} and adapt to {user_skill_level}</critical>
 <critical>Generate all documents in {document_output_language}</critical>
 <critical>LIVING DOCUMENT: Write to epics.md continuously as you work - never wait until the end</critical>
@ -17,600 +15,373 @@
 <workflow>
-<step n="0" goal="Detect workflow mode and available context">
+<step n="0" goal="Validate prerequisites and load all context">
-<action>Determine if this is initial creation or update mode
+<action>Welcome {user_name} to comprehensive epic and story creation</action>
-**Check for existing epics.md:**
+<action>**CRITICAL PREREQUISITE VALIDATION:**</action>
 </action>
-<action>Check if {default_output_file} exists (epics.md)</action>
+<action>Verify required documents exist and are complete:
-<check if="epics.md exists">
+1. **PRD.md** - Contains functional requirements (FRs) and product scope
-  <action>Load existing epics.md completely</action>
+2. **Architecture.md** - Contains technical decisions, API contracts, data models
-  <action>Extract existing:
+3. **UX Design.md** (if UI exists) - Contains interaction patterns, mockups, user flows
  - Epic structure and titles
  - Story breakdown
  - FR coverage mapping
  - Existing acceptance criteria
  </action>
-<output>📝 **Existing epics.md found!**
+Missing any required document means this workflow cannot proceed successfully.</action>
-Current structure:
+<check if="!prd_content">
 <output>❌ **PREREQUISITE FAILED: PRD.md not found**
- {{epic_count}} epics defined
+The PRD is required to define what functionality needs to be built.
 - {{story_count}} total stories
  </output>
-<ask>What would you like to do?
+Please complete the PRD workflow first, then run this workflow again.</output>
-1. **CONTINUING** - Previous run was incomplete, continue where we left off
+<exit workflow="Missing required PRD document"/>
 2. **REPLACING** - Start fresh, discard existing epic structure
 3. **UPDATING** - New planning document created (UX/Architecture), enhance existing epics
 Enter your choice (1-3):</ask>
 <action>Set mode based on user choice:
 - Choice 1: mode = "CONTINUE" (resume incomplete work)
 - Choice 2: mode = "CREATE" (start fresh, ignore existing)
 - Choice 3: mode = "UPDATE" (enhance with new context)
  </action>
 </check>
-<check if="epics.md does not exist">
+<check if="!architecture_content">
-  <action>Set mode = "CREATE"</action>
+<output>❌ **PREREQUISITE FAILED: Architecture.md not found**
  <output>🆕 **INITIAL CREATION MODE**
-No existing epics found - I'll create the initial epic breakdown.
+The Architecture document is required to provide technical implementation context for stories.
-</output>
+
 Please complete the Architecture workflow first, then run this workflow again.</output>
 <exit workflow="Missing required Architecture document"/>
 </check>
-<action>**Detect available context documents:**</action>
+<action>List the documents loaded</action>
-<action>Check which documents exist:
+<action>**LOAD ALL CONTEXT DOCUMENTS:**</action>
- UX Design specification ({ux_design_content})
+<action>Load and analyze PRD.md:
 - Architecture document ({architecture_content})
 - Domain brief ({domain_brief_content})
 - Product brief ({product_brief_content})
  </action>
-<check if="mode == 'UPDATE'">
+Extract ALL functional requirements:
  <action>Identify what's NEW since last epic update:
- If UX exists AND not previously incorporated:
+- Complete FR inventory (FR1, FR2, FR3...)
-  - Flag: "ADD_UX_DETAILS = true"
+- Non-functional requirements and constraints
-  - Note UX sections to extract (interaction patterns, mockup references, responsive breakpoints)
+- Project scope boundaries (MVP vs growth vs vision)
 - If Architecture exists AND not previously incorporated:
  - Flag: "ADD_ARCH_DETAILS = true"
  - Note Architecture sections to extract (tech stack, API contracts, data models)
    </action>
 <output>**Context Analysis:**
 {{if ADD_UX_DETAILS}}
 ✅ UX Design found - will add interaction details to stories
 {{/if}}
 {{if ADD_ARCH_DETAILS}}
 ✅ Architecture found - will add technical implementation notes
 {{/if}}
 {{if !ADD_UX_DETAILS && !ADD_ARCH_DETAILS}}
 ⚠️ No new context documents found - reviewing for any PRD changes
 {{/if}}
 </output>
 </check>
 <check if="mode == 'CREATE'">
  <output>**Available Context:**
  - ✅ PRD (required)
  {{if ux_design_content}}
  - ✅ UX Design (will incorporate interaction patterns)
  {{/if}}
  {{if architecture_content}}
  - ✅ Architecture (will incorporate technical decisions)
  {{/if}}
  {{if !ux_design_content && !architecture_content}}
  - ℹ️ Creating basic epic structure (can be enhanced later with UX/Architecture)
  {{/if}}
  </output>
 </check>
 <template-output>workflow_mode</template-output>
 <template-output>available_context</template-output>
 </step>
 <step n="1" goal="Load PRD and extract requirements">
 <action>
 <check if="mode == 'CREATE'">
 Welcome {user_name} to epic and story planning
 </check>
 <check if="mode == 'UPDATE'">
 Welcome back {user_name} - let's enhance your epic breakdown with new context
 </check>
 Load required documents (fuzzy match, handle both whole and sharded):
 - PRD.md (required)
 - domain-brief.md (if exists)
 - product-brief.md (if exists)
 **CRITICAL - PRD FRs Are Now Flat and Strategic:**
 The PRD contains FLAT, capability-level functional requirements (FR1, FR2, FR3...).
 These are STRATEGIC (WHAT capabilities exist), NOT tactical (HOW they're implemented).
 Example PRD FRs:
 - FR1: Users can create accounts with email or social authentication
 - FR2: Users can log in securely and maintain sessions
 - FR6: Users can create, edit, and delete content items
 **Your job in THIS workflow:**
 1. Map each FR to one or more epics
 2. Break each FR into stories with DETAILED acceptance criteria
 3. Add ALL the implementation details that were intentionally left out of PRD
 Extract from PRD:
 - ALL functional requirements (flat numbered list)
 - Non-functional requirements
 - Domain considerations and compliance needs
 - Project type and complexity
 - MVP vs growth vs vision scope boundaries
 - Product differentiator (what makes it special)
 - Technical constraints
 - User types and their goals
 - Success criteria
 - Technical constraints
 - Compliance requirements
-**Create FR Inventory:**
+**FR Inventory Creation:**
-
+List every functional requirement with description for coverage tracking.
 List all FRs to ensure coverage:
 - FR1: [description]
 - FR2: [description]
 - ...
 - FRN: [description]
 This inventory will be used to validate complete coverage in Step 4.
 </action>
 <action>Load and analyze Architecture.md:
 Extract ALL technical implementation context relevant to the PRD functional requirements and project needs:
 Scan comprehensively for any technical details needed to create complete user stories, including but not limited to:
 - Technology stack decisions and framework choices
 - API design, contracts, and integration patterns
 - Data models, schemas, and relationships
 - Authentication, authorization, and security patterns
 - Performance requirements and scaling approaches
 - Error handling, logging, and monitoring strategies
 - Deployment architecture and infrastructure considerations
 - Any other technical decisions, patterns, or constraints that impact implementation
 Focus on extracting whatever technical context exists in the Architecture document that will be needed to create comprehensive, actionable user stories for all PRD requirements.
 </action>
 <action if="UX Design Exists">
 Load and analyze UX Design.md:
 Extract ALL user experience context relevant to the PRD functional requirements and project needs:
 Scan comprehensively for any user experience details needed to create complete user stories, including but not limited to:
 - User flows, journey patterns, and interaction design
 - Screen layouts, components, and visual specifications
 - Interaction patterns, behaviors, and micro-interactions
 - Responsive design and mobile-first considerations
 - Accessibility requirements and inclusive design patterns
 - Animations, transitions, and feedback mechanisms
 - Error states, validation patterns, and user guidance
 - Any other UX/UI decisions, patterns, or specifications that impact implementation
 Focus on extracting whatever user experience context exists in the UX document that will be needed to create comprehensive, actionable user stories for all PRD requirements.
 </action>
 <template-output>context_validation</template-output>
 <template-output>fr_inventory</template-output>
 </step>
-<step n="2" goal="Propose epic structure from natural groupings">
+<step n="1" goal="Design epic structure with full technical context">
 <action>**STRATEGIC EPIC PLANNING WITH COMPLETE CONTEXT:**</action>
-<check if="mode == 'UPDATE'">
+<action>Now that you have ALL available context (PRD + Architecture + UX), design epics that deliver incremental user value while leveraging the technical design decisions.
  <action>**MAINTAIN existing epic structure:**
-Use the epic structure already defined in epics.md:
+**EPIC DESIGN PRINCIPLES:**
- Keep all existing epic titles and goals
+1. **User-Value First**: Each epic must enable users to accomplish something meaningful
- Preserve epic sequencing
+2. **Leverage Architecture**: Build upon the technical decisions already made
- Maintain FR coverage mapping
+3. **Incremental Delivery**: Each epic should be independently valuable
 4. **Logical Dependencies**: Dependencies should flow naturally, not artificially
-Note: We're enhancing stories within existing epics, not restructuring.
+**USE YOUR FULL CONTEXT:**
 </action>
-<output>**Using existing epic structure:**
+From PRD: Group related functional requirements that deliver user outcomes
-{{list_existing_epics_with_titles}}
+From Architecture: Respect technical boundaries and integration points
 From UX: Design around user journeys and interaction flows
-Will enhance stories within these epics using new context.
+**VALID EPIC EXAMPLES:**
 </output>
-<template-output>epics_summary</template-output>
+✅ **CORRECT - User Value with Technical Context:**
 <template-output>fr_coverage_map</template-output>
-<goto step="3">Skip to story enhancement</goto>
+- Epic 1: Foundation Setup (infrastructure, deployment, core services)
-</check>
+- Epic 2: User Authentication & Profile Management (register, login, profile management)
-
+- Epic 3: Content Creation & Management (create, edit, publish, organize content)
-<check if="mode == 'CREATE'">
+- Epic 4: Content Discovery & Interaction (browse, search, share, comment)
 <action>Analyze requirements and identify natural epic boundaries
 INTENT: Find organic groupings that make sense for THIS product
 Look for natural patterns:
 - Features that work together cohesively
 - User journeys that connect
 - Business capabilities that cluster
 - Domain requirements that relate (compliance, validation, security)
 - Technical systems that should be built together
 Name epics based on VALUE, not technical layers:
 - Good: "User Onboarding", "Content Discovery", "Compliance Framework"
 - Avoid: "Database Layer", "API Endpoints", "Frontend"
 **⚠️ ANTI-PATTERN EXAMPLES (DO NOT DO THIS):**
 ❌ **WRONG - Technical Layer Breakdown:**
 - Epic 1: Database Schema & Models
- Epic 2: API Layer / Backend Services
+- Epic 2: REST API Endpoints
- Epic 3: Frontend UI Components
+- Epic 3: Frontend Components
- Epic 4: Integration & Testing
+- Epic 4: Authentication Service
-WHY IT'S WRONG: User gets ZERO value until ALL epics complete. No incremental delivery.
+**PRESENT YOUR EPIC STRUCTURE:**
-✅ **CORRECT - User Value Breakdown:**
+For each proposed epic, provide:
- Epic 1: Foundation (project setup - necessary exception)
+- **Epic Title**: Value-based, not technical
- Epic 2: User Authentication (user can register/login - VALUE DELIVERED)
+- **User Value Statement**: What users can accomplish after this epic
- Epic 3: Content Management (user can create/edit content - VALUE DELIVERED)
+- **PRD Coverage**: Which FRs this epic addresses
- Epic 4: Social Features (user can share/interact - VALUE DELIVERED)
+- **Technical Context**: How this leverages Architecture decisions
 - **UX Integration**: How this incorporates user experience patterns (if available)
 - **Dependencies**: What must come before (natural dependencies only)
-WHY IT'S RIGHT: Each epic delivers something users can USE. Incremental value.
+**FOUNDATION EPIC GUIDELINES:**
-**Valid Exceptions:**
+For Epic 1, include technical foundation based on Architecture:
-1. **Foundation Epic**: First epic CAN be setup/infrastructure (greenfield projects need this)
+- Project setup and build system
-2. **API-First Epic**: ONLY valid if the API has standalone value (third-party consumers, multiple frontends, API-as-product). If it's just "backend for our frontend", that's the WRONG pattern.
+- Core infrastructure and deployment pipeline
 - Database schema setup
 - Basic authentication foundation
 - API framework setup
-Each epic should:
+This enables all subsequent user-facing epics.
 - Have clear business goal and user value
 - Be independently valuable
 - Contain 3-8 related capabilities
 - Be deliverable in cohesive phase
 For greenfield projects:
 - First epic MUST establish foundation (project setup, core infrastructure, deployment pipeline)
 - Foundation enables all subsequent work
 For complex domains:
 - Consider dedicated compliance/regulatory epics
 - Group validation and safety requirements logically
 - Note expertise requirements
 Present proposed epic structure showing:
 - Epic titles with clear value statements
 - High-level scope of each epic
 - **FR COVERAGE MAP: Which FRs does each epic address?**
  - Example: "Epic 1 (Foundation): Covers infrastructure needs for all FRs"
  - Example: "Epic 2 (User Management): FR1, FR2, FR3, FR4, FR5"
  - Example: "Epic 3 (Content System): FR6, FR7, FR8, FR9"
 - Suggested sequencing
 - Why this grouping makes sense
 **Validate FR Coverage:**
 Check that EVERY FR from Step 1 inventory is mapped to at least one epic.
 If any FRs are unmapped, add them now or explain why they're deferred.
 </action>
-<template-output>epics_summary</template-output>
+<template-output>epics_structure_plan</template-output>
-<template-output>fr_coverage_map</template-output>
+<template-output>epics_technical_context</template-output>
 </check>
 </step>
-<step n="3" goal="Decompose each epic into bite-sized stories with DETAILED AC" repeat="for-each-epic">
+<step n="2" goal="Create detailed stories with complete implementation context" repeat="for-each-epic">
 <action>**EPIC {{N}} - COMPREHENSIVE STORY CREATION:**</action>
-<check if="mode == 'UPDATE'">
+<action>For Epic {{N}}: {{epic_title}}, create bite-sized stories that incorporate ALL available context.
  <action>**ENHANCE Epic {{N}} stories with new context:**
-For each existing story in Epic {{N}}:
+**STORY CREATION WITH FULL CONTEXT:**
-1. Preserve core story structure (title, user story statement)
+For each story, you now have the complete picture:
 2. Add/enhance based on available NEW context:
-  <check if="ADD_UX_DETAILS">
+- **WHAT to build** (from PRD FRs)
-    **Add from UX Design:**
+- **HOW to build it** (from Architecture decisions)
-    - Specific mockup/wireframe references
+- **HOW users interact** (from UX patterns, if available)
    - Exact interaction patterns
    - Animation/transition specifications
    - Responsive breakpoints
    - Component specifications
    - Error states and feedback patterns
    - Accessibility requirements (WCAG compliance)
-    Example enhancement:
+**TRANSFORM STRATEGIC REQUIREMENTS INTO TACTICAL IMPLEMENTATION:**
    BEFORE: "User can log in"
    AFTER: "User can log in via modal (UX pg 12-15) with email/password fields,
            password visibility toggle, remember me checkbox,
            loading state during auth (spinner overlay),
            error messages below fields (red, 14px),
            success redirects to dashboard with fade transition"
-  </check>
+PRD says: "Users can create accounts"
 Architecture says: "Use PostgreSQL with bcrypt hashing, JWT tokens, rate limiting"
 UX says: "Modal dialog with email/password fields, real-time validation, loading states"
-  <check if="ADD_ARCH_DETAILS">
+Your story becomes: Specific implementation details with exact acceptance criteria
-    **Add from Architecture:**
+
-    - Specific API endpoints and contracts
+**STORY PATTERN FOR EACH EPIC {{N}}:**
-    - Data model references
+
-    - Tech stack implementation details
+**Epic Goal:** {{epic_goal}}
-    - Performance requirements
+
-    - Security implementation notes
+For each story M in Epic {{N}}:
-    - Cache strategies
+
 - **User Story**: As a [user type], I want [specific capability], So that [value/benefit]
 - **Acceptance Criteria**: BDD format with COMPLETE implementation details
 - **Technical Implementation**: Specific guidance from Architecture
 - **User Experience**: Exact interaction patterns from UX (if available)
 - **Prerequisites**: Only previous stories, never forward dependencies
 **DETAILED ACCEPTANCE CRITERIA GUIDELINES:**
 Include ALL implementation specifics:
 **From Architecture:**
 - Exact API endpoints and contracts
 - Database operations and validations
 - Authentication/authorization requirements
 - Error handling patterns
 - Performance requirements
 - Security considerations
 - Integration points with other systems
-    Example enhancement:
+**From UX (if available):**
    BEFORE: "System authenticates user"
    AFTER: "System authenticates user via POST /api/v1/auth/login,
            validates against users table (see Arch section 6.2),
            returns JWT token (expires 7d) + refresh token (30d),
            rate limited to 5 attempts/hour/IP,
            logs failures to security_events table"
-  </check>
+- Specific screen/page references
 - Interaction patterns and behaviors
 - Form validation rules and error messages
 - Responsive behavior
 - Accessibility requirements
 - Loading states and transitions
 - Success/error feedback patterns
-3. Update acceptance criteria with new details
+**From PRD:**
-4. Preserve existing prerequisites
+
-5. Enhance technical notes with new context
+- Business rules and constraints
 - User types and permissions
 - Compliance requirements
 - Success criteria
 **STORY SIZING PRINCIPLE:**
 Each story must be completable by a single dev agent in one focused session. If a story becomes too large, break it down further while maintaining user value.
 **EXAMPLE RICH STORY:**
 **Story:** User Registration with Email Verification
 As a new user, I want to create an account using my email address, So that I can access the platform's features.
 **Acceptance Criteria:**
 Given I am on the landing page
 When I click the "Sign Up" button
 Then the registration modal opens (UX Mockup 3.2)
 And I see email and password fields with proper labels
 And the email field validates RFC 5322 format in real-time
 And the password field shows strength meter (red→yellow→green)
 And I see "Password must be 8+ chars with 1 uppercase, 1 number, 1 special"
 When I submit valid registration data
 Then POST /api/v1/auth/register is called (Architecture section 4.1)
 And the user record is created in users table with bcrypt hash (Architecture 6.2)
 And a verification email is sent via SendGrid (Architecture 7.3)
 And I see "Check your email for verification link" message
 And I cannot log in until email is verified
 **Technical Notes:**
 - Use PostgreSQL users table (Architecture section 6.2)
 - Implement rate limiting: 3 attempts per hour per IP (Architecture 8.1)
 - Return JWT token on successful verification (Architecture 5.2)
 - Log registration events to audit_events table (Architecture 9.4)
 - Form validation follows UX Design patterns (UX section 4.1)
 **Prerequisites:** Epic 1.1 - Foundation Setup Complete
 </action>
   </check>
 <check if="mode == 'CREATE'">
 <action>Break down Epic {{N}} into small, implementable stories
 INTENT: Create stories sized for single dev agent completion
 **CRITICAL - ALTITUDE SHIFT FROM PRD:**
 PRD FRs are STRATEGIC (WHAT capabilities):
 - ✅ "Users can create accounts"
 Epic Stories are TACTICAL (HOW it's implemented):
 - Email field with RFC 5322 validation
 - Password requirements: 8+ chars, 1 uppercase, 1 number, 1 special
 - Password strength meter with visual feedback
 - Email verification within 15 minutes
 - reCAPTCHA v3 integration
 - Account creation completes in < 2 seconds
 - Mobile responsive with 44x44px touch targets
 - WCAG 2.1 AA compliant
 **THIS IS WHERE YOU ADD ALL THE DETAILS LEFT OUT OF PRD:**
 - UI specifics (exact field counts, validation rules, layout details)
 - Performance targets (< 2s, 60fps, etc.)
 - Technical implementation hints (libraries, patterns, APIs)
 - Edge cases (what happens when...)
 - Validation rules (regex patterns, constraints)
 - Error handling (specific error messages, retry logic)
 - Accessibility requirements (ARIA labels, keyboard nav, screen readers)
 - Platform specifics (mobile responsive, browser support)
 For each epic, generate:
 - Epic title as `epic_title_{{N}}`
 - Epic goal/value as `epic_goal_{{N}}`
 - All stories as repeated pattern `story_title_{{N}}_{{M}}` for each story M
 CRITICAL for Epic 1 (Foundation):
 - Story 1.1 MUST be project setup/infrastructure initialization
 - Sets up: repo structure, build system, deployment pipeline basics, core dependencies
 - Creates foundation for all subsequent stories
 - Note: Architecture workflow will flesh out technical details
 Each story should follow BDD-style acceptance criteria:
 **Story Pattern:**
 As a [user type],
 I want [specific capability],
 So that [clear value/benefit].
 **Acceptance Criteria using BDD:**
 Given [precondition or initial state]
 When [action or trigger]
 Then [expected outcome]
 And [additional criteria as needed]
 **Prerequisites:** Only previous stories (never forward dependencies)
 **Technical Notes:** Implementation guidance, affected components, compliance requirements
 Ensure stories are:
 - Vertically sliced (deliver complete functionality, not just one layer)
 - Sequentially ordered (logical progression, no forward dependencies)
 - Independently valuable when possible
 - Small enough for single-session completion
 - Clear enough for autonomous implementation
 For each story in epic {{N}}, output variables following this pattern:
 - story*title*{{N}}_1, story_title_{{N}}\*2, etc.
 - Each containing: user story, BDD acceptance criteria, prerequisites, technical notes</action>
 <action>**Generate all stories for Epic {{N}}**</action>
 <template-output>epic*title*{{N}}</template-output>
 <template-output>epic*goal*{{N}}</template-output>
 <action>For each story M in epic {{N}}, generate story content</action>
-<template-output>story-title-{{N}}-{{M}}</template-output>
+<template-output>story*{{N}}*{{M}}</template-output>
 </check>
-<action>**EPIC {{N}} REVIEW - Present for Checkpoint:**
+<action>**EPIC {{N}} COMPLETION REVIEW:**</action>
-Summarize the COMPLETE epic breakdown:
+<output>**Epic {{N}} Complete: {{epic_title}}**
-**Epic {{N}}: {{epic_title}}**
+Stories Created: {{count}}
 Goal: {{epic_goal}}
-Stories ({{count}} total):
+**FR Coverage:** {{list of FRs covered by this epic}}
 {{for each story, show:}}
- Story {{N}}.{{M}}: {{story_title}}
+**Technical Context Used:** {{Architecture sections referenced}}
  - User Story: As a... I want... So that...
  - Acceptance Criteria: (BDD format summary)
  - Prerequisites: {{list}}
-**Review Questions to Consider:**
+{{if ux_design_content}}
 **UX Patterns Incorporated:** {{UX sections referenced}}
 {{/if}}
- Is the story sequence logical?
+Ready for checkpoint validation.</output>
 - Are acceptance criteria clear and testable?
 - Are there any missing stories for the FRs this epic covers?
 - Are the stories sized appropriately (single dev agent session)?
 - FRs covered by this epic: {{FR_list}}
 **NOTE:** At the checkpoint prompt, select [a] for Advanced Elicitation if you want to refine stories, add missing ones, or reorder. Select [c] to approve this epic and continue to the next one.
 </action>
 <template-output>epic\_{{N}}\_complete_breakdown</template-output>
 <template-output>epic\_{{N}}\_complete</template-output>
 </step>
-<step n="4" goal="Review epic breakdown and completion">
+<step n="3" goal="Final validation and coverage matrix">
 <action>**COMPREHENSIVE VALIDATION WITH FULL CONTEXT:**</action>
-<check if="mode == 'UPDATE'">
+<action>Review the complete epic and story breakdown for quality and completeness using ALL available context.
  <action>Review the ENHANCED epic breakdown for completeness
-**Validate Enhancements:**
+**FR COVERAGE VALIDATION:**
- All stories now have context-appropriate details
+Create complete FR Coverage Matrix showing every PRD functional requirement mapped to specific stories:
 - UX references added where applicable
 - Architecture decisions incorporated where applicable
 - Acceptance criteria updated with new specifics
 - Technical notes enhanced with implementation details
-**Quality Check:**
+- **FR1:** [description] → Epic X, Story X.Y (with implementation details)
-
+- **FR2:** [description] → Epic Y, Story Y.A (with implementation details)
- Stories remain bite-sized for single dev agent sessions
+- **FR3:** [description] → Epic Z, Story Z.B (with implementation details)
 - No forward dependencies introduced
 - All new context properly integrated
  </action>
 <template-output>epic_breakdown_summary</template-output>
 <template-output>enhancement_summary</template-output>
 <output>✅ **Epic Enhancement Complete!**
 **Updated:** epics.md with enhanced context
 **Enhancements Applied:**
 {{if ADD_UX_DETAILS}}
 - ✅ UX interaction patterns and mockup references added
  {{/if}}
  {{if ADD_ARCH_DETAILS}}
 - ✅ Architecture technical decisions and API contracts added
  {{/if}}
 The epic breakdown now includes all available context for Phase 4 implementation.
 **Next Steps:**
 {{if !architecture_content}}
 - Run Architecture workflow for technical decisions
  {{/if}}
  {{if architecture_content}}
 - Ready for Phase 4: Sprint Planning
  {{/if}}
  </output>
  </check>
 <check if="mode == 'CREATE'">
 <action>Review the complete epic breakdown for quality and completeness
 **Validate Epic Structure (USER VALUE CHECK):**
 For each epic, answer: "What can USERS do after this epic is complete that they couldn't do before?"
 - Epic 1: [Must have clear user value OR be Foundation exception]
 - Epic 2: [Must deliver user-facing capability]
 - Epic N: [Must deliver user-facing capability]
 ⚠️ RED FLAG: If an epic only delivers technical infrastructure (database layer, API without users, component library without features), RESTRUCTURE IT. Each epic should enable users to accomplish something.
 Exception validation:
 - Foundation epic: Acceptable as first epic for greenfield projects
 - API-first epic: Acceptable ONLY if API has standalone consumers (third-party integrations, multiple frontends, API-as-product)
 If any epic fails this check, restructure before proceeding.
 **Validate FR Coverage:**
 Create FR Coverage Matrix showing each FR mapped to epic(s) and story(ies):
 - FR1: [description] → Epic X, Story X.Y
 - FR2: [description] → Epic X, Story X.Z
 - FR3: [description] → Epic Y, Story Y.A
 - ...
 - FRN: [description] → Epic Z, Story Z.B
-Confirm: EVERY FR from Step 1 inventory is covered by at least one story.
+**CRITICAL VALIDATION:** Every single FR from the PRD must be covered by at least one story with complete acceptance criteria.
 If any FRs are missing, add stories now.
-**Validate Story Quality:**
+**ARCHITECTURE INTEGRATION VALIDATION:**
- All functional requirements from PRD are covered by stories
+Verify that Architecture decisions are properly implemented:
 - Epic 1 establishes proper foundation (if greenfield)
 - All stories are vertically sliced (deliver complete functionality, not just one layer)
 - No forward dependencies exist (only backward references)
 - Story sizing is appropriate for single-session completion
 - BDD acceptance criteria are clear and testable
 - Details added (what was missing from PRD FRs: UI specifics, performance targets, etc.)
 - Domain/compliance requirements are properly distributed
 - Sequencing enables incremental value delivery
-Confirm with {user_name}:
+- All API endpoints from Architecture are covered in stories
 - Data models from Architecture are properly created and populated
 - Authentication/authorization patterns are consistently applied
 - Performance requirements are addressed in relevant stories
 - Security measures are implemented where required
 - Error handling follows Architecture patterns
 - Integration points between systems are properly handled
- Epic structure makes sense
+**UX INTEGRATION VALIDATION** {{if ux_design_content}}:
- All FRs covered by stories (validated via coverage matrix)
+
- Story breakdown is actionable
+Verify that UX design patterns are properly implemented:
-  <check if="ux_design_content && architecture_content">
+
- All available context has been incorporated (PRD + UX + Architecture)
+- User flows follow the designed journey
- Ready for Phase 4 Implementation
+- Screen layouts and components match specifications
-  </check>
+- Interaction patterns work as designed
-  <check if="ux_design_content && !architecture_content">
+- Responsive behavior matches breakpoints
- UX context has been incorporated
+- Accessibility requirements are met
- Ready for Architecture workflow (recommended next step)
+- Error states and feedback patterns are implemented
-  </check>
+- Form validation follows UX guidelines
-  <check if="!ux_design_content && architecture_content">
+- Loading states and transitions are implemented
- Architecture context has been incorporated
+  {{/if}}
- Consider running UX Design workflow if UI exists
+
-  </check>
+**STORY QUALITY VALIDATION:**
-  <check if="!ux_design_content && !architecture_content">
+
- Basic epic structure created from PRD
+- All stories are sized for single dev agent completion
- Ready for next planning phase (UX Design or Architecture)
+- Acceptance criteria are specific and testable
-  </check>
+- Technical implementation guidance is clear
 - User experience details are incorporated
 - No forward dependencies exist
 - Epic sequence delivers incremental value
 - Foundation epic properly enables subsequent work
 **FINAL QUALITY CHECK:**
 Answer these critical questions:
 1. **User Value:** Does each epic deliver something users can actually do/use?
 2. **Completeness:** Are ALL PRD functional requirements covered?
 3. **Technical Soundness:** Do stories properly implement Architecture decisions?
 4. **User Experience:** {{if ux_design_content}} Do stories follow UX design patterns? {{/if}}
 5. **Implementation Ready:** Can dev agents implement these stories autonomously?
   </action>
-<template-output>epic_breakdown_summary</template-output>
+<output>**✅ EPIC AND STORY CREATION COMPLETE**
 <template-output>fr_coverage_matrix</template-output>
-<check if="mode == 'CREATE'">
+**Output Generated:** epics.md with comprehensive implementation details
 <output>**✅ Epic Breakdown Complete**
-**Created:** epics.md with epic and story breakdown
+**Full Context Incorporated:**
-**FR Coverage:** All functional requirements from PRD mapped to stories
+- ✅ PRD functional requirements and scope
-
+- ✅ Architecture technical decisions and contracts
-**Context Incorporated:**
+  {{if ux_design_content}}
-{{if ux_design_content && architecture_content}}
+- ✅ UX Design interaction patterns and specifications
 - ✅ PRD requirements
 - ✅ UX interaction patterns
 - ✅ Architecture technical decisions
  **Status:** COMPLETE - Ready for Phase 4 Implementation!
  {{/if}}
  {{if ux_design_content && !architecture_content}}
 - ✅ PRD requirements
 - ✅ UX interaction patterns
  **Next:** Run Architecture workflow for technical decisions
  {{/if}}
  {{if !ux_design_content && architecture_content}}
 - ✅ PRD requirements
 - ✅ Architecture technical decisions
  **Next:** Consider UX Design workflow if UI needed
  {{/if}}
  {{if !ux_design_content && !architecture_content}}
 - ✅ PRD requirements (basic structure)
  **Next:** Run UX Design (if UI) or Architecture workflow
  **Note:** Epics will be enhanced with additional context later
  {{/if}}
 **FR Coverage:** {{count}} functional requirements mapped to {{story_count}} stories
 **Epic Structure:** {{epic_count}} epics delivering incremental user value
 **Ready for Phase 4:** Sprint Planning and Development Implementation
 </output>
-  </check>
+
-  </check>
+<template-output>final_validation</template-output>
 <template-output>fr_coverage_matrix</template-output>
 </step>
 </workflow>
--- a/src/modules/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.yaml
+++ b/src/modules/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.yaml
@ -1,6 +1,6 @@
 # Epic and Story Decomposition Workflow
 name: create-epics-and-stories
-description: "Transform PRD requirements into bite-sized stories organized into deliverable functional epics. This workflow takes a Product Requirements Document (PRD) and breaks it down into epics and user stories that can be easily assigned to development teams. It ensures that all functional requirements are captured in a structured format, making it easier for teams to understand and implement the necessary features."
+description: "Transform PRD requirements and Architecture decisions into comprehensive stories organized by user value. This workflow requires completed PRD + Architecture documents (UX recommended if UI exists) and breaks down requirements into implementation-ready epics and user stories that incorporate all available technical and design context. Creates detailed, actionable stories with complete acceptance criteria for development teams."
 author: "BMad"
 # Critical variables from config
@ -17,30 +17,20 @@ date: system-generated
 # Priority: Whole document first, then sharded version
 input_file_patterns:
  prd:
-    description: "Product Requirements Document with FRs and NFRs"
+    description: "Product Requirements Document with FRs and NFRs (required)"
    whole: "{output_folder}/*prd*.md"
    sharded: "{output_folder}/*prd*/index.md"
    load_strategy: "INDEX_GUIDED"
  product_brief:
    description: "Product vision and goals (optional)"
    whole: "{output_folder}/*product*brief*.md"
    sharded: "{output_folder}/*product*brief*/index.md"
    load_strategy: "INDEX_GUIDED"
  domain_brief:
    description: "Domain-specific requirements and context (optional)"
    whole: "{output_folder}/*domain*brief*.md"
    sharded: "{output_folder}/*domain*brief*/index.md"
    load_strategy: "INDEX_GUIDED"
  ux_design:
    description: "UX design specification for interaction patterns (optional)"
    whole: "{output_folder}/*ux*.md"
    sharded: "{output_folder}/*ux*/index.md"
    load_strategy: "FULL_LOAD"
  architecture:
-    description: "Architecture decisions and technical design (optional)"
+    description: "Architecture decisions and technical design (required)"
    whole: "{output_folder}/*architecture*.md"
    sharded: "{output_folder}/*architecture*/index.md"
    load_strategy: "FULL_LOAD"
  ux_design:
    description: "UX design specification for interaction patterns (recommended if UI exists)"
    whole: "{output_folder}/*ux*.md"
    sharded: "{output_folder}/*ux*/index.md"
    load_strategy: "FULL_LOAD"
 # Module path and component files
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/create-epics-and-stories"