ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

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

This commit is contained in:
Brian Madison 2025-11-26 00:28:49 -06:00
parent 24e952c511
commit d6b98afd2b
6 changed files with 564 additions and 746 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
src/modules/bmm/workflows/1-analysis/product-brief/instructions.md
View File

@ -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>

439
src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md
View File

@ -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>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
<critical>This workflow uses INTENT-DRIVEN PLANNING - adapt organically to product type and context</critical>
<critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
<critical>Generate all documents in {document_output_language}</critical>
<critical>LIVING DOCUMENT: Write to PRD.md continuously as you discover - never wait until the end</critical>
<critical>GUIDING PRINCIPLE: Identify what makes this product special and ensure it's reflected throughout the PRD</critical>
<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</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>⚠️ 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-rules>
- <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 uses INTENT-DRIVEN PLANNING - adapt organically to product type and context</critical>
- <critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
- <critical>Generate all documents in {document_output_language}</critical>
- <critical>LIVING DOCUMENT: Write to PRD.md continuously as you discover - never wait until the end</critical>
- <critical>GUIDING PRINCIPLE: Identify what makes this product special and ensure it's reflected throughout the PRD</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. </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>
<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>
</output>
</check>
<check if="prd status is file path (already completed)">
@ -47,16 +42,16 @@ PRD is for BMad Method and Enterprise Method tracks that need comprehensive requ
</step>
<step n="0.5" goal="Discover and load input documents">
<invoke-protocol name="discover_inputs" />
<note>After discovery, these content variables are available: {product_brief_content}, {research_content}, {document_project_content}</note>
<invoke-protocol name="discover_inputs" />
<note>After discovery, these content variables are available: {product_brief_content}, {research_content}, {document_project_content}</note>
</step>
<step n="1" goal="Discovery - Project, Domain, and Vision">
<action>Welcome {user_name} and begin comprehensive discovery, and then start to GATHER ALL CONTEXT:
1. Check workflow-status.yaml for project_context (if exists)
2. Review loaded content: {product_brief_content}, {research_content}, {document_project_content} (auto-loaded in Step 0.5)
3. Detect project type AND domain complexity using data-driven classification
</action>
<action>Welcome {user_name} and begin comprehensive discovery, and then start to GATHER ALL CONTEXT:
1. Check workflow-status.yaml for project_context (if exists)
2. Review loaded content: {product_brief_content}, {research_content}, {document_project_content} (auto-loaded in Step 0.5)
3. Detect project type AND domain complexity using data-driven classification
</action>
<action>Load classification data files COMPLETELY:
@ -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
<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:
<template-output>success_criteria</template-output>
<check if="business focus">
<template-output>business_metrics</template-output>
</check>
- 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
<action>Smart scope negotiation - find the sweet spot based on success:
The Scoping Game:
@ -196,14 +214,143 @@ For complex domains:
- Include compliance minimums in MVP
- Note regulatory gates between phases</action>
<template-output>mvp_scope</template-output>
<template-output>growth_features</template-output>
<template-output>vision_features</template-output>
<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="3" goal="User Journeys">
<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>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="4" goal="Domain-Specific Exploration" optional="true">
<critical>This step is DATA-DRIVEN using domain_complexity_data CSV loaded in Step 1</critical>
<action>Execute only if complexity_level = "high" OR domain-brief exists</action>
<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">
<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">
<step n="9" 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:
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
<action>Generate the complete FR list by systematically extracting capabilities from all discussed so far for all that is in scope.
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">
<action>Quick review of captured requirements:
<step n="11" goal="Complete PRD and determine next steps">
<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
- {{nfr_count}} non-functional requirements
- MVP scope defined
{{if domain_complexity == 'high'}}
- Domain-specific requirements addressed
{{/if}}
{{if innovation_detected}}
- Innovation patterns documented
{{/if}}
Before running validation, you MUST remove any empty sections from the generated PRD:
Your PRD is complete!"
</action>
1. **Scan for empty sections** - Look for sections with no meaningful content (just whitespace or placeholder text)
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>
<template-output>product_value_summary</template-output>
**This cleanup step is essential because:**
- 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>

65
src/modules/bmm/workflows/2-plan-workflows/prd/prd-template.md
View File

@ -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}}
---

6
src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml
View File

@ -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"

759
src/modules/bmm/workflows/3-solutioning/create-epics-and-stories/instructions.md
View File

@ -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>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>⚠️ 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>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">
<action>Determine if this is initial creation or update mode
<step n="0" goal="Validate prerequisites and load all context">
<action>Welcome {user_name} to comprehensive epic and story creation</action>
**Check for existing epics.md:**
</action>
<action>**CRITICAL PREREQUISITE VALIDATION:**</action>
<action>Check if {default_output_file} exists (epics.md)</action>
<action>Verify required documents exist and are complete:
<check if="epics.md exists">
<action>Load existing epics.md completely</action>
<action>Extract existing:
- Epic structure and titles
- Story breakdown
- FR coverage mapping
- Existing acceptance criteria
</action>
1. **PRD.md** - Contains functional requirements (FRs) and product scope
2. **Architecture.md** - Contains technical decisions, API contracts, data models
3. **UX Design.md** (if UI exists) - Contains interaction patterns, mockups, user flows
<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
- {{story_count}} total stories
</output>
The PRD is required to define what functionality needs to be built.
<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
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">
<action>Set mode = "CREATE"</action>
<output>🆕 **INITIAL CREATION MODE**
No existing epics found - I'll create the initial epic breakdown.
</output>
<exit workflow="Missing required PRD document"/>
</check>
<action>**Detect available context documents:**</action>
<check if="!architecture_content">
<output>❌ **PREREQUISITE FAILED: Architecture.md not found**
<action>Check which documents exist:
The Architecture document is required to provide technical implementation context for stories.
- UX Design specification ({ux_design_content})
- Architecture document ({architecture_content})
- Domain brief ({domain_brief_content})
- Product brief ({product_brief_content})
</action>
Please complete the Architecture workflow first, then run this workflow again.</output>
<check if="mode == 'UPDATE'">
<action>Identify what's NEW since last epic update:
- If UX exists AND not previously incorporated:
- Flag: "ADD_UX_DETAILS = true"
- Note UX sections to extract (interaction patterns, mockup references, responsive breakpoints)
- 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>
<exit workflow="Missing required Architecture document"/>
</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>
<action>List the documents loaded</action>
<template-output>workflow_mode</template-output>
<template-output>available_context</template-output>
</step>
<action>**LOAD ALL CONTEXT DOCUMENTS:**</action>
<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>
<action>Load and analyze PRD.md:
Load required documents (fuzzy match, handle both whole and sharded):
Extract ALL functional requirements:
- 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
- Complete FR inventory (FR1, FR2, FR3...)
- Non-functional requirements and constraints
- Project scope boundaries (MVP vs growth vs vision)
- User types and their goals
- Success criteria
- Technical constraints
- Compliance requirements
**Create FR Inventory:**
List all FRs to ensure coverage:
- FR1: [description]
- FR2: [description]
- ...
- FRN: [description]
This inventory will be used to validate complete coverage in Step 4.
**FR Inventory Creation:**
List every functional requirement with description for coverage tracking.
</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>**MAINTAIN existing epic structure:**
<action>Now that you have ALL available context (PRD + Architecture + UX), design epics that deliver incremental user value while leveraging the technical design decisions.
Use the epic structure already defined in epics.md:
**EPIC DESIGN PRINCIPLES:**
- Keep all existing epic titles and goals
- Preserve epic sequencing
- Maintain FR coverage mapping
1. **User-Value First**: Each epic must enable users to accomplish something meaningful
2. **Leverage Architecture**: Build upon the technical decisions already made
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.
</action>
**USE YOUR FULL CONTEXT:**
<output>**Using existing epic structure:**
{{list_existing_epics_with_titles}}
From PRD: Group related functional requirements that deliver user outcomes
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.
</output>
**VALID EPIC EXAMPLES:**
<template-output>epics_summary</template-output>
<template-output>fr_coverage_map</template-output>
✅ **CORRECT - User Value with Technical Context:**
<goto step="3">Skip to story enhancement</goto>
</check>
<check if="mode == 'CREATE'">
<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):**
- Epic 1: Foundation Setup (infrastructure, deployment, core services)
- Epic 2: User Authentication & Profile Management (register, login, profile management)
- Epic 3: Content Creation & Management (create, edit, publish, organize content)
- Epic 4: Content Discovery & Interaction (browse, search, share, comment)
❌ **WRONG - Technical Layer Breakdown:**
- Epic 1: Database Schema & Models
- Epic 2: API Layer / Backend Services
- Epic 3: Frontend UI Components
- Epic 4: Integration & Testing
- Epic 2: REST API Endpoints
- Epic 3: Frontend Components
- 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 2: User Authentication (user can register/login - VALUE DELIVERED)
- Epic 3: Content Management (user can create/edit content - VALUE DELIVERED)
- Epic 4: Social Features (user can share/interact - VALUE DELIVERED)
- **Epic Title**: Value-based, not technical
- **User Value Statement**: What users can accomplish after this epic
- **PRD Coverage**: Which FRs this epic addresses
- **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)
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.
- Project setup and build system
- Core infrastructure and deployment pipeline
- Database schema setup
- Basic authentication foundation
- API framework setup
Each epic should:
- 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.
This enables all subsequent user-facing epics.
</action>
<template-output>epics_summary</template-output>
<template-output>fr_coverage_map</template-output>
</check>
<template-output>epics_structure_plan</template-output>
<template-output>epics_technical_context</template-output>
</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>**ENHANCE Epic {{N}} stories with new context:**
<action>For Epic {{N}}: {{epic_title}}, create bite-sized stories that incorporate ALL available context.
For each existing story in Epic {{N}}:
**STORY CREATION WITH FULL CONTEXT:**
1. Preserve core story structure (title, user story statement)
2. Add/enhance based on available NEW context:
For each story, you now have the complete picture:
<check if="ADD_UX_DETAILS">
**Add from UX Design:**
- Specific mockup/wireframe references
- Exact interaction patterns
- Animation/transition specifications
- Responsive breakpoints
- Component specifications
- Error states and feedback patterns
- Accessibility requirements (WCAG compliance)
- **WHAT to build** (from PRD FRs)
- **HOW to build it** (from Architecture decisions)
- **HOW users interact** (from UX patterns, if available)
Example enhancement:
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"
**TRANSFORM STRATEGIC REQUIREMENTS INTO TACTICAL IMPLEMENTATION:**
</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">
**Add from Architecture:**
- Specific API endpoints and contracts
- Data model references
- Tech stack implementation details
- Performance requirements
- Security implementation notes
- Cache strategies
- Error handling patterns
Your story becomes: Specific implementation details with exact acceptance criteria
Example enhancement:
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"
**STORY PATTERN FOR EACH EPIC {{N}}:**
</check>
**Epic Goal:** {{epic_goal}}
3. Update acceptance criteria with new details
4. Preserve existing prerequisites
5. Enhance technical notes with new context
</action>
</check>
For each story M in Epic {{N}}:
<check if="mode == 'CREATE'">
<action>Break down Epic {{N}} into small, implementable stories
- **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
INTENT: Create stories sized for single dev agent completion
**DETAILED ACCEPTANCE CRITERIA GUIDELINES:**
**CRITICAL - ALTITUDE SHIFT FROM PRD:**
Include ALL implementation specifics:
PRD FRs are STRATEGIC (WHAT capabilities):
**From Architecture:**
- ✅ "Users can create accounts"
- Exact API endpoints and contracts
- Database operations and validations
- Authentication/authorization requirements
- Error handling patterns
- Performance requirements
- Security considerations
- Integration points with other systems
Epic Stories are TACTICAL (HOW it's implemented):
**From UX (if available):**
- 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
- 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
**THIS IS WHERE YOU ADD ALL THE DETAILS LEFT OUT OF PRD:**
**From 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)
- Business rules and constraints
- User types and permissions
- Compliance requirements
- Success criteria
For each epic, generate:
**STORY SIZING PRINCIPLE:**
- 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
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.
CRITICAL for Epic 1 (Foundation):
**EXAMPLE RICH STORY:**
- 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
**Story:** User Registration with Email Verification
Each story should follow BDD-style acceptance criteria:
As a new user, I want to create an account using my email address, So that I can access the platform's features.
**Story Pattern:**
As a [user type],
I want [specific capability],
So that [clear value/benefit].
**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)
**Acceptance Criteria using BDD:**
Given [precondition or initial state]
When [action or trigger]
Then [expected outcome]
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"
And [additional criteria as needed]
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
**Prerequisites:** Only previous stories (never forward dependencies)
**Technical Notes:**
**Technical Notes:** Implementation guidance, affected components, compliance requirements
- 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)
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>
**Prerequisites:** Epic 1.1 - Foundation Setup Complete
</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>
</check>
<template-output>story*{{N}}*{{M}}</template-output>
<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}}**
Goal: {{epic_goal}}
Stories Created: {{count}}
Stories ({{count}} total):
{{for each story, show:}}
**FR Coverage:** {{list of FRs covered by this epic}}
- Story {{N}}.{{M}}: {{story_title}}
- User Story: As a... I want... So that...
- Acceptance Criteria: (BDD format summary)
- Prerequisites: {{list}}
**Technical Context Used:** {{Architecture sections referenced}}
**Review Questions to Consider:**
{{if ux_design_content}}
**UX Patterns Incorporated:** {{UX sections referenced}}
{{/if}}
- Is the story sequence logical?
- 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>
Ready for checkpoint validation.</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 ENHANCED epic breakdown for completeness
<action>Review the complete epic and story breakdown for quality and completeness using ALL available context.
**Validate Enhancements:**
**FR COVERAGE VALIDATION:**
- All stories now have context-appropriate details
- UX references added where applicable
- Architecture decisions incorporated where applicable
- Acceptance criteria updated with new specifics
- Technical notes enhanced with implementation details
Create complete FR Coverage Matrix showing every PRD functional requirement mapped to specific stories:
**Quality Check:**
- Stories remain bite-sized for single dev agent sessions
- 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
- **FR1:** [description] → Epic X, Story X.Y (with implementation details)
- **FR2:** [description] → Epic Y, Story Y.A (with implementation details)
- **FR3:** [description] → Epic Z, Story Z.B (with implementation details)
- ...
- FRN: [description] → Epic Z, Story Z.B
Confirm: EVERY FR from Step 1 inventory is covered by at least one story.
If any FRs are missing, add stories now.
**CRITICAL VALIDATION:** Every single FR from the PRD must be covered by at least one story with complete acceptance criteria.
**Validate Story Quality:**
**ARCHITECTURE INTEGRATION VALIDATION:**
- All functional requirements from PRD are covered by stories
- 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
Verify that Architecture decisions are properly implemented:
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
- All FRs covered by stories (validated via coverage matrix)
- Story breakdown is actionable
<check if="ux_design_content && architecture_content">
- All available context has been incorporated (PRD + UX + Architecture)
- Ready for Phase 4 Implementation
</check>
<check if="ux_design_content && !architecture_content">
- UX context has been incorporated
- Ready for Architecture workflow (recommended next step)
</check>
<check if="!ux_design_content && architecture_content">
- Architecture context has been incorporated
- Consider running UX Design workflow if UI exists
</check>
<check if="!ux_design_content && !architecture_content">
- Basic epic structure created from PRD
- Ready for next planning phase (UX Design or Architecture)
</check>
</action>
**UX INTEGRATION VALIDATION** {{if ux_design_content}}:
<template-output>epic_breakdown_summary</template-output>
Verify that UX design patterns are properly implemented:
- User flows follow the designed journey
- Screen layouts and components match specifications
- Interaction patterns work as designed
- Responsive behavior matches breakpoints
- Accessibility requirements are met
- Error states and feedback patterns are implemented
- Form validation follows UX guidelines
- Loading states and transitions are implemented
{{/if}}
**STORY QUALITY VALIDATION:**
- All stories are sized for single dev agent completion
- Acceptance criteria are specific and testable
- 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>
<output>**✅ EPIC AND STORY CREATION COMPLETE**
**Output Generated:** epics.md with comprehensive implementation details
**Full Context Incorporated:**
- ✅ PRD functional requirements and scope
- ✅ Architecture technical decisions and contracts
{{if ux_design_content}}
- ✅ UX Design interaction patterns and specifications
{{/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>
<template-output>final_validation</template-output>
<template-output>fr_coverage_matrix</template-output>
<check if="mode == 'CREATE'">
<output>**✅ Epic Breakdown Complete**
**Created:** epics.md with epic and story breakdown
**FR Coverage:** All functional requirements from PRD mapped to stories
**Context Incorporated:**
{{if ux_design_content && architecture_content}}
- ✅ 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}}
</output>
</check>
</check>
</step>
</step>
</workflow>

26
src/modules/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.yaml
View File

@ -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"