bmad-method 6.0.0-alpha.7 → 6.0.0-alpha.9

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

@@ -1,12 +1,12 @@
 # PRD Workflow - Intent-Driven Product Planning
 
-<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<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: Find and weave the product's magic throughout - what makes it special should inspire every section</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>
 
 <workflow>
@@ -44,10 +44,15 @@ PRD is for BMad Method and Enterprise Method tracks that need comprehensive requ
 </check>
 </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>
+</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. Look for existing documents (Product Brief, Domain Brief, research)
+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
 
 Load references:
@@ -69,9 +74,9 @@ B) Quick web search (basic)
 C) User provides context
 D) Continue with general knowledge
 
-CAPTURE THE MAGIC EARLY with a few questions such as for example: "What excites you most about this product?", "What would make users love this?", "What's the moment that will make people go 'wow'?"
+IDENTIFY WHAT MAKES IT SPECIAL early with questions such as: "What excites you most about this product?", "What would make users love this?", "What's the unique value or compelling moment?"
 
-This excitement becomes the thread woven throughout the PRD.</action>
+This becomes a thread that connects throughout the PRD.</action>
 
 <template-output>vision_alignment</template-output>
 <template-output>project_classification</template-output>
@@ -81,7 +86,7 @@ This excitement becomes the thread woven throughout the PRD.</action>
 <check if="complex domain">
 <template-output>domain_context_summary</template-output>
 </check>
-<template-output>product_magic_essence</template-output>
+<template-output>product_differentiator</template-output>
 <template-output>product_brief_path</template-output>
 <template-output>domain_brief_path</template-output>
 <template-output>research_documents</template-output>
@@ -107,15 +112,14 @@ Make it specific:
 - NOT: "99.9% uptime"
 - BUT: "Zero data loss during critical operations"
 
-Weave in the magic:
+Connect to what makes the product special:
 
-- "Success means users experience [that special moment] and [desired outcome]"</action>
+- "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>
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 </step>
 
 <step n="3" goal="Scope Definition">
@@ -140,7 +144,6 @@ For complex domains:
 <template-output>mvp_scope</template-output>
 <template-output>growth_features</template-output>
 <template-output>vision_features</template-output>
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 </step>
 
 <step n="4" goal="Domain-Specific Exploration" optional="true">
@@ -219,8 +222,8 @@ FOR SAAS B2B:
 
 [Continue for other types...]
 
-Always relate back to the product magic:
-"How does [requirement] enhance [the special thing]?"</action>
+Always connect requirements to product value:
+"How does [requirement] support the product's core value proposition?"</action>
 
 <template-output>project_type_requirements</template-output>
 
@@ -253,8 +256,8 @@ Light touch on UX - not full design:
 "How should this feel to use?"
 "What's the vibe - professional, playful, minimal?"
 
-Connect to the magic:
-"The UI should reinforce [the special moment] through [design approach]"</action>
+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>
@@ -263,33 +266,148 @@ Connect to the magic:
 </step>
 
 <step n="8" goal="Functional Requirements Synthesis">
-<action>Transform everything discovered into clear functional requirements
+<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>
+<critical>Epic breakdown will ONLY implement what's listed here</critical>
+<critical>If a capability is missing from FRs, it will NOT exist in the final product</critical>
+
+<action>Before writing FRs, understand their PURPOSE and USAGE:
+
+**Purpose:**
+FRs define WHAT capabilities the product must have. They are the complete inventory
+of user-facing and system capabilities that deliver the product vision.
+
+**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
+sections MUST be represented as an FR. Missing FRs = missing capabilities.
+
+**Critical Property - ALTITUDE:**
+FRs state WHAT capability exists and WHO it serves, NOT HOW it's implemented or
+specific UI/UX details. Those come later from UX and Architecture.
+</action>
+
+<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:
+
+- ✅ "User Management" (not "Authentication System")
+- ✅ "Content Discovery" (not "Search Algorithm")
+- ✅ "Team Collaboration" (not "WebSocket Infrastructure")
+
+**Format - Flat, Numbered List:**
+Each FR is one clear capability statement:
+
+- FR#: [Actor] can [capability] [context/constraint if needed]
+- Number sequentially (FR1, FR2, FR3...)
+- Aim for 20-50 FRs for typical projects (fewer for simple, more for complex)
+
+**Altitude Check:**
+Each FR should answer "WHAT capability exists?" NOT "HOW is it implemented?"
+
+- ✅ "Users can customize appearance settings"
+- ❌ "Users can toggle light/dark theme with 3 font size options stored in LocalStorage"
+
+The second example belongs in Epic Breakdown, not PRD.
+</action>
+
+<example>
+**Well-written FRs at the correct altitude:**
+
+**User Account & Access:**
+
+- 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
+
+Organize FRs by logical capability groups (5-8 groups typically).
+Number sequentially across all groups (FR1, FR2... FR47).
+</action>
+
+<action>SELF-VALIDATION - Before finalizing, ask yourself:
 
-Pull together:
+**Completeness Check:**
 
-- Core features from scope
-- Domain-mandated features
-- Project-type specific needs
-- Innovation requirements
+1. "Did I cover EVERY capability mentioned in the MVP scope section?"
+2. "Did I include domain-specific requirements as FRs?"
+3. "Did I cover the project-type specific needs (API/Mobile/SaaS/etc)?"
+4. "Could a UX designer read ONLY the FRs and know what to design?"
+5. "Could an Architect read ONLY the FRs and know what to support?"
+6. "Are there any user actions or system behaviors we discussed that have no FR?"
 
-Organize by capability, not technology:
+**Altitude Check:**
 
-- User Management (not "auth system")
-- Content Discovery (not "search algorithm")
-- Team Collaboration (not "websockets")
+1. "Am I stating capabilities (WHAT) or implementation (HOW)?"
+2. "Am I listing acceptance criteria or UI specifics?" (Remove if yes)
+3. "Could this FR be implemented 5 different ways?" (Good - means it's not prescriptive)
 
-Each requirement should:
+**Quality Check:**
 
-- Be specific and measurable
-- Connect to user value
-- Include acceptance criteria
-- Note domain constraints
+1. "Is each FR clear enough that someone could test whether it exists?"
+2. "Is each FR independent (not dependent on reading other FRs to understand)?"
+3. "Did I avoid vague terms like 'good', 'fast', 'easy'?" (Use NFRs for quality attributes)
 
-The magic thread:
-Highlight which requirements deliver the special experience</action>
+COMPLETENESS GATE: Review your FR list against the entire PRD written so far.
+Did you miss anything? Add it now before proceeding.
+</action>
 
 <template-output>functional_requirements_complete</template-output>
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 </step>
 
 <step n="9" goal="Non-Functional Requirements Discovery">
@@ -341,7 +459,6 @@ Skip categories that don't apply!</action>
 Does this capture your product vision?"</action>
 
 <template-output>prd_summary</template-output>
-<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
 
 <action>After PRD review and refinement complete:
 
@@ -374,7 +491,7 @@ Generate epic_details for the epics breakdown document</action>
 </step>
 
 <step n="11" goal="Complete PRD and suggest next steps">
-<template-output>product_magic_summary</template-output>
+<template-output>product_value_summary</template-output>
 
 <check if="standalone_mode != true">
   <action>Load the FULL file: {status_file}</action>
@@ -401,7 +518,7 @@ Your product requirements are documented and ready for implementation.
 3. **Architecture** (Recommended)
    Run: `workflow create-architecture` for technical architecture decisions
 
-The magic of your product - {product_magic_summary} - is woven throughout the PRD and will guide all subsequent work.
+What makes your product special - {product_value_summary} - is captured throughout the PRD and will guide all subsequent work.
 </output>
 </step>
 

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

@@ -12,7 +12,7 @@
 
 ### What Makes This Special
 
-{{product_magic_essence}}
+{{product_differentiator}}
 
 ---
 
@@ -232,6 +232,6 @@ Requirements must be decomposed into epics and bite-sized stories (200k context
 
 ---
 
-_This PRD captures the essence of {{project_name}} - {{product_magic_summary}}_
+_This PRD captures the essence of {{project_name}} - {{product_value_summary}}_
 
 _Created through collaborative discovery between {{user_name}} and AI facilitator._

package/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml

@@ -4,7 +4,7 @@ description: "Unified PRD workflow for BMad Method and Enterprise Method tracks.
 author: "BMad"
 
 # Critical variables from config
-config_source: "{project-root}/bmad/bmm/config.yaml"
+config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"
 project_name: "{config_source}:project_name"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
@@ -14,7 +14,7 @@ user_skill_level: "{config_source}:user_skill_level"
 date: system-generated
 
 # Workflow components
-installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd"
+installed_path: "{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd"
 instructions: "{installed_path}/instructions.md"
 
 # Templates
@@ -31,17 +31,21 @@ recommended_inputs:
 
 # Smart input file references - handles both whole docs and sharded docs
 # Priority: Whole document first, then sharded version
+# Strategy: How to load sharded documents (FULL_LOAD, SELECTIVE_LOAD, INDEX_GUIDED)
 input_file_patterns:
   product_brief:
     whole: "{output_folder}/*brief*.md"
     sharded: "{output_folder}/*brief*/index.md"
+    load_strategy: "FULL_LOAD"
 
   research:
     whole: "{output_folder}/*research*.md"
     sharded: "{output_folder}/*research*/index.md"
+    load_strategy: "FULL_LOAD"
 
   document_project:
     sharded: "{output_folder}/docs/index.md"
+    load_strategy: "INDEX_GUIDED"
 
 standalone: true
 
@@ -49,24 +53,24 @@ web_bundle:
   name: "prd"
   description: "Unified PRD workflow for BMad Method and Enterprise Method tracks. Produces strategic PRD and tactical epic breakdown. Hands off to architecture workflow for technical design. Note: Quick Flow track uses tech-spec workflow."
   author: "BMad"
-  instructions: "bmad/bmm/workflows/2-plan-workflows/prd/instructions.md"
-  validation: "bmad/bmm/workflows/2-plan-workflows/prd/checklist.md"
+  instructions: "{bmad_folder}/bmm/workflows/2-plan-workflows/prd/instructions.md"
+  validation: "{bmad_folder}/bmm/workflows/2-plan-workflows/prd/checklist.md"
   web_bundle_files:
     # Core workflow files
-    - "bmad/bmm/workflows/2-plan-workflows/prd/instructions.md"
-    - "bmad/bmm/workflows/2-plan-workflows/prd/prd-template.md"
-    - "bmad/bmm/workflows/2-plan-workflows/prd/project-types.csv"
-    - "bmad/bmm/workflows/2-plan-workflows/prd/domain-complexity.csv"
-    - "bmad/bmm/workflows/2-plan-workflows/prd/checklist.md"
+    - "{bmad_folder}/bmm/workflows/2-plan-workflows/prd/instructions.md"
+    - "{bmad_folder}/bmm/workflows/2-plan-workflows/prd/prd-template.md"
+    - "{bmad_folder}/bmm/workflows/2-plan-workflows/prd/project-types.csv"
+    - "{bmad_folder}/bmm/workflows/2-plan-workflows/prd/domain-complexity.csv"
+    - "{bmad_folder}/bmm/workflows/2-plan-workflows/prd/checklist.md"
 
     # Child workflow and its files
-    - "bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml"
-    - "bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/instructions.md"
-    - "bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/epics-template.md"
+    - "{bmad_folder}/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml"
+    - "{bmad_folder}/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/instructions.md"
+    - "{bmad_folder}/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/epics-template.md"
 
     # Task dependencies (referenced in instructions.md)
-    - "bmad/core/tasks/workflow.xml"
-    - "bmad/core/tasks/adv-elicit.xml"
-    - "bmad/core/tasks/adv-elicit-methods.csv"
+    - "{bmad_folder}/core/tasks/workflow.xml"
+    - "{bmad_folder}/core/tasks/advanced-elicitation.xml"
+    - "{bmad_folder}/core/tasks/advanced-elicitation-methods.csv"
   child_workflows:
-    - create-epics-and-stories: "bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml"
+    - create-epics-and-stories: "{bmad_folder}/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml"

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

@@ -2,20 +2,22 @@
 
 **Purpose**: Validate tech-spec workflow outputs are context-rich, definitive, complete, and implementation-ready.
 
-**Scope**: Levels 0-1 software projects
+**Scope**: Quick-flow software projects (1-5 stories)
 
-**Expected Outputs**: tech-spec.md + story files (1 for Level 0, 2-3 for Level 1)
+**Expected Outputs**: tech-spec.md + epics.md + story files (1-5 stories)
 
-**New Standard**: Tech-spec should be comprehensive enough to replace story-context for Level 0-1 projects
+**New Standard**: Tech-spec should be comprehensive enough to replace story-context for most quick-flow projects
 
 ---
 
 ## 1. Output Files Exist
 
 - [ ] tech-spec.md created in output folder
-- [ ] Story file(s) created in dev_story_location
-  - Level 0: 1 story file (story-{slug}.md)
-  - Level 1: epics.md + 2-3 story files (story-{epic-slug}-N.md)
+- [ ] epics.md created (minimal for 1 story, detailed for multiple)
+- [ ] Story file(s) created in sprint_artifacts
+  - Naming convention: story-{epic-slug}-N.md (where N = 1 to story_count)
+  - 1 story: story-{epic-slug}-1.md
+  - Multiple stories: story-{epic-slug}-1.md through story-{epic-slug}-N.md
 - [ ] bmm-workflow-status.yaml updated (if not standalone mode)
 - [ ] No unfilled {{template_variables}} in any files
 
@@ -134,16 +136,17 @@
 
 ---
 
-## 6. Epic Quality (Level 1 Only)
+## 6. Epic Quality (All Projects)
 
 - [ ] **Epic title**: User-focused outcome (not implementation detail)
 - [ ] **Epic slug**: Clean kebab-case slug (2-3 words)
 - [ ] **Epic goal**: Clear purpose and value statement
 - [ ] **Epic scope**: Boundaries clearly defined
 - [ ] **Success criteria**: Measurable outcomes
-- [ ] **Story map**: Visual representation of epic → stories
-- [ ] **Implementation sequence**: Logical story ordering with dependencies
+- [ ] **Story map** (if multiple stories): Visual representation of epic → stories
+- [ ] **Implementation sequence** (if multiple stories): Logical story ordering with dependencies
 - [ ] **Tech-spec reference**: Links back to tech-spec.md
+- [ ] **Detail level appropriate**: Minimal for 1 story, detailed for multiple
 
 ---
 

package/src/modules/bmm/workflows/2-plan-workflows/tech-spec/epics-template.md

@@ -72,9 +72,3 @@ So that {{value_benefit}}.
 ---
 
 <!-- End epic repeat -->
-
----
-
-## Tech-Spec Reference
-
-See [tech-spec.md](../tech-spec.md) for complete technical implementation details.