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

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

@@ -1,62 +1,237 @@
-# {{project_name}} Product Requirements Document (PRD)
+# {{project_name}} - Product Requirements Document
 
 **Author:** {{user_name}}
 **Date:** {{date}}
-**Project Level:** {{project_level}}
-**Target Scale:** {{target_scale}}
+**Version:** 1.0
 
 ---
 
-## Goals and Background Context
+## Executive Summary
 
-### Goals
+{{vision_alignment}}
 
-{{goals}}
+### What Makes This Special
 
-### Background Context
+{{product_magic_essence}}
 
-{{background_context}}
+---
+
+## Project Classification
+
+**Technical Type:** {{project_type}}
+**Domain:** {{domain_type}}
+**Complexity:** {{complexity_level}}
+
+{{project_classification}}
+
+{{#if domain_context_summary}}
+
+### Domain Context
+
+{{domain_context_summary}}
+{{/if}}
+
+---
+
+## Success Criteria
+
+{{success_criteria}}
+
+{{#if business_metrics}}
+
+### Business Metrics
+
+{{business_metrics}}
+{{/if}}
+
+---
+
+## Product Scope
+
+### MVP - Minimum Viable Product
+
+{{mvp_scope}}
+
+### Growth Features (Post-MVP)
+
+{{growth_features}}
+
+### Vision (Future)
+
+{{vision_features}}
+
+---
+
+{{#if domain_considerations}}
+
+## Domain-Specific Requirements
+
+{{domain_considerations}}
+
+This section shapes all functional and non-functional requirements below.
+{{/if}}
 
 ---
 
-## Requirements
+{{#if innovation_patterns}}
 
-### Functional Requirements
+## Innovation & Novel Patterns
 
-{{functional_requirements}}
+{{innovation_patterns}}
 
-### Non-Functional Requirements
+### Validation Approach
 
-{{non_functional_requirements}}
+{{validation_approach}}
+{{/if}}
 
 ---
 
-## User Journeys
+{{#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}}
 
-{{user_journeys}}
+{{#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}}
 
 ---
 
-## UX Design Principles
+{{#if ux_principles}}
+
+## User Experience Principles
 
 {{ux_principles}}
 
+### Key Interactions
+
+{{key_interactions}}
+{{/if}}
+
+---
+
+## Functional Requirements
+
+{{functional_requirements_complete}}
+
+---
+
+## 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}}
+
 ---
 
-## User Interface Design Goals
+## Implementation Planning
+
+### Epic Breakdown Required
 
-{{ui_design_goals}}
+Requirements must be decomposed into epics and bite-sized stories (200k context limit).
+
+**Next Step:** Run `workflow epics-stories` to create the implementation breakdown.
 
 ---
 
-## Epic List
+## References
+
+{{#if product_brief_path}}
+
+- Product Brief: {{product_brief_path}}
+  {{/if}}
+  {{#if domain_brief_path}}
+- Domain Brief: {{domain_brief_path}}
+  {{/if}}
+  {{#if research_documents}}
+- Research: {{research_documents}}
+  {{/if}}
+
+---
 
-{{epic_list}}
+## Next Steps
 
-> **Note:** Detailed epic breakdown with full story specifications is available in [epics.md](./epics.md)
+1. **Epic & Story Breakdown** - Run: `workflow epics-stories`
+2. **UX Design** (if UI) - Run: `workflow ux-design`
+3. **Architecture** - Run: `workflow create-architecture`
 
 ---
 
-## Out of Scope
+_This PRD captures the essence of {{project_name}} - {{product_magic_summary}}_
 
-{{out_of_scope}}
+_Created through collaborative discovery between {{user_name}} and AI facilitator._

package/src/modules/bmm/workflows/2-plan-workflows/prd/project-types.csv

@@ -0,0 +1,11 @@
+project_type,detection_signals,key_questions,required_sections,skip_sections,web_search_triggers,innovation_signals
+api_backend,"API,REST,GraphQL,backend,service,endpoints","Endpoints needed?;Authentication method?;Data formats?;Rate limits?;Versioning?;SDK needed?","endpoint_specs;auth_model;data_schemas;error_codes;rate_limits;api_docs","ux_ui;visual_design;user_journeys","framework best practices;OpenAPI standards","API composition;New protocol"
+mobile_app,"iOS,Android,app,mobile,iPhone,iPad","Native or cross-platform?;Offline needed?;Push notifications?;Device features?;Store compliance?","platform_reqs;device_permissions;offline_mode;push_strategy;store_compliance","desktop_features;cli_commands","app store guidelines;platform requirements","Gesture innovation;AR/VR features"
+saas_b2b,"SaaS,B2B,platform,dashboard,teams,enterprise","Multi-tenant?;Permission model?;Subscription tiers?;Integrations?;Compliance?","tenant_model;rbac_matrix;subscription_tiers;integration_list;compliance_reqs","cli_interface;mobile_first","compliance requirements;integration guides","Workflow automation;AI agents"
+developer_tool,"SDK,library,package,npm,pip,framework","Language support?;Package managers?;IDE integration?;Documentation?;Examples?","language_matrix;installation_methods;api_surface;code_examples;migration_guide","visual_design;store_compliance","package manager best practices;API design patterns","New paradigm;DSL creation"
+cli_tool,"CLI,command,terminal,bash,script","Interactive or scriptable?;Output formats?;Config method?;Shell completion?","command_structure;output_formats;config_schema;scripting_support","visual_design;ux_principles;touch_interactions","CLI design patterns;shell integration","Natural language CLI;AI commands"
+web_app,"website,webapp,browser,SPA,PWA","SPA or MPA?;Browser support?;SEO needed?;Real-time?;Accessibility?","browser_matrix;responsive_design;performance_targets;seo_strategy;accessibility_level","native_features;cli_commands","web standards;WCAG guidelines","New interaction;WebAssembly use"
+game,"game,player,gameplay,level,character","REDIRECT TO GAME WORKFLOWS","game-brief;GDD","most_sections","game design patterns","Novel mechanics;Genre mixing"
+desktop_app,"desktop,Windows,Mac,Linux,native","Cross-platform?;Auto-update?;System integration?;Offline?","platform_support;system_integration;update_strategy;offline_capabilities","web_seo;mobile_features","desktop guidelines;platform requirements","Desktop AI;System automation"
+iot_embedded,"IoT,embedded,device,sensor,hardware","Hardware specs?;Connectivity?;Power constraints?;Security?;OTA updates?","hardware_reqs;connectivity_protocol;power_profile;security_model;update_mechanism","visual_ui;browser_support","IoT standards;protocol specs","Edge AI;New sensors"
+blockchain_web3,"blockchain,crypto,DeFi,NFT,smart contract","Chain selection?;Wallet integration?;Gas optimization?;Security audit?","chain_specs;wallet_support;smart_contracts;security_audit;gas_optimization","traditional_auth;centralized_db","blockchain standards;security patterns","Novel tokenomics;DAO structure"

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

@@ -19,20 +19,30 @@ instructions: "{installed_path}/instructions.md"
 
 # Templates
 prd_template: "{installed_path}/prd-template.md"
-epics_template: "{installed_path}/epics-template.md"
 
 # Output files
-status_file: "{output_folder}/bmm-workflow-status.md"
+status_file: "{output_folder}/bmm-workflow-status.yaml"
 default_output_file: "{output_folder}/PRD.md"
-epics_output_file: "{output_folder}/epics.md"
-technical_decisions_file: "{output_folder}/technical-decisions.md"
-technical_decisions_template: "{project-root}/bmad/bmm/_module-installer/assets/technical-decisions.md"
 
 # Recommended input documents
 recommended_inputs:
   - product_brief: "{output_folder}/product-brief.md"
   - market_research: "{output_folder}/market-research.md"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  product_brief:
+    whole: "{output_folder}/*brief*.md"
+    sharded: "{output_folder}/*brief*/index.md"
+
+  research:
+    whole: "{output_folder}/*research*.md"
+    sharded: "{output_folder}/*research*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 standalone: true
 
 web_bundle:
@@ -40,7 +50,15 @@ web_bundle:
   description: "Unified PRD workflow for project levels 2-4. Produces strategic PRD and tactical epic breakdown. Hands off to architecture workflow for technical design. Note: Level 0-1 use 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"
   web_bundle_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/epics-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/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"
+  child_workflows:
+    - create-epics-and-stories: "bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml"

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

@@ -1,11 +1,13 @@
 # Tech-Spec Workflow Validation Checklist
 
-**Purpose**: Validate tech-spec workflow outputs are definitive, complete, and implementation-ready.
+**Purpose**: Validate tech-spec workflow outputs are context-rich, definitive, complete, and implementation-ready.
 
 **Scope**: Levels 0-1 software projects
 
 **Expected Outputs**: tech-spec.md + story files (1 for Level 0, 2-3 for Level 1)
 
+**New Standard**: Tech-spec should be comprehensive enough to replace story-context for Level 0-1 projects
+
 ---
 
 ## 1. Output Files Exist
@@ -14,38 +16,107 @@
 - [ ] 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)
-- [ ] bmm-workflow-status.md updated to Phase 4
-- [ ] No unfilled {{template_variables}}
+- [ ] bmm-workflow-status.yaml updated (if not standalone mode)
+- [ ] No unfilled {{template_variables}} in any files
 
 ---
 
-## 2. Tech-Spec Definitiveness (CRITICAL)
+## 2. Context Gathering (NEW - CRITICAL)
+
+### Document Discovery
+
+- [ ] **Existing documents loaded**: Product brief, research docs found and incorporated (if they exist)
+- [ ] **Document-project output**: Checked for {output_folder}/docs/index.md (brownfield codebase map)
+- [ ] **Sharded documents**: If sharded versions found, ALL sections loaded and synthesized
+- [ ] **Context summary**: loaded_documents_summary lists all sources used
+
+### Project Stack Detection
+
+- [ ] **Setup files identified**: package.json, requirements.txt, or equivalent found and parsed
+- [ ] **Framework detected**: Exact framework name and version captured (e.g., "Express 4.18.2")
+- [ ] **Dependencies extracted**: All production dependencies with specific versions
+- [ ] **Dev tools identified**: TypeScript, Jest, ESLint, pytest, etc. with versions
+- [ ] **Scripts documented**: Available npm/pip/etc scripts identified
+- [ ] **Stack summary**: project_stack_summary is complete and accurate
+
+### Brownfield Analysis (if applicable)
+
+- [ ] **Directory structure**: Main code directories identified and documented
+- [ ] **Code patterns**: Dominant patterns identified (class-based, functional, MVC, etc.)
+- [ ] **Naming conventions**: Existing conventions documented (camelCase, snake_case, etc.)
+- [ ] **Key modules**: Important existing modules/services identified
+- [ ] **Testing patterns**: Test framework and patterns documented
+- [ ] **Structure summary**: existing_structure_summary is comprehensive
+
+---
+
+## 3. Tech-Spec Definitiveness (CRITICAL)
 
 ### No Ambiguity Allowed
 
 - [ ] **Zero "or" statements**: NO "use X or Y", "either A or B", "options include"
 - [ ] **Specific versions**: All frameworks, libraries, tools have EXACT versions
-  - ✅ GOOD: "Python 3.11", "React 18.2.0", "winston v3.8.2"
+  - ✅ GOOD: "Python 3.11", "React 18.2.0", "winston v3.8.2 (from package.json)"
   - ❌ BAD: "Python 2 or 3", "React 18+", "a logger like pino or winston"
 - [ ] **Definitive decisions**: Every technical choice is final, not a proposal
+- [ ] **Stack-aligned**: Decisions reference detected project stack
 
 ### Implementation Clarity
 
-- [ ] Source tree shows EXACT file paths (not "somewhere in src/")
-- [ ] Each file marked as create/modify/delete
-- [ ] Technical approach describes SPECIFIC implementation
-- [ ] Implementation stack has complete toolchain with versions
+- [ ] **Source tree changes**: EXACT file paths with CREATE/MODIFY/DELETE actions
+  - ✅ GOOD: "src/services/UserService.ts - MODIFY - Add validateEmail() method"
+  - ❌ BAD: "Update some files in the services folder"
+- [ ] **Technical approach**: Describes SPECIFIC implementation using detected stack
+- [ ] **Existing patterns**: Documents brownfield patterns to follow (if applicable)
+- [ ] **Integration points**: Specific modules, APIs, services identified
+
+---
+
+## 4. Context-Rich Content (NEW)
+
+### Context Section
+
+- [ ] **Available Documents**: Lists all loaded documents
+- [ ] **Project Stack**: Complete framework and dependency information
+- [ ] **Existing Codebase Structure**: Brownfield analysis or greenfield notation
+
+### The Change Section
+
+- [ ] **Problem Statement**: Clear, specific problem definition
+- [ ] **Proposed Solution**: Concrete solution approach
+- [ ] **Scope In/Out**: Clear boundaries defined
+
+### Development Context Section
+
+- [ ] **Relevant Existing Code**: References to specific files and line numbers (brownfield)
+- [ ] **Framework Dependencies**: Complete list with exact versions from project
+- [ ] **Internal Dependencies**: Internal modules listed
+- [ ] **Configuration Changes**: Specific config file updates identified
+
+### Developer Resources Section
+
+- [ ] **File Paths Reference**: Complete list of all files involved
+- [ ] **Key Code Locations**: Functions, classes, modules with file:line references
+- [ ] **Testing Locations**: Specific test directories and patterns
+- [ ] **Documentation Updates**: Docs that need updating identified
 
 ---
 
-## 3. Story Quality
+## 5. Story Quality
 
 ### Story Format
 
 - [ ] All stories use "As a [role], I want [capability], so that [benefit]" format
 - [ ] Each story has numbered acceptance criteria
 - [ ] Tasks reference AC numbers: (AC: #1), (AC: #2)
-- [ ] Dev Notes section links back to tech-spec.md
+- [ ] Dev Notes section links to tech-spec.md
+
+### Story Context Integration (NEW)
+
+- [ ] **Tech-Spec Reference**: Story explicitly references tech-spec.md as primary context
+- [ ] **Dev Agent Record**: Includes all required sections (Context Reference, Agent Model, etc.)
+- [ ] **Test Results section**: Placeholder ready for dev execution
+- [ ] **Review Notes section**: Placeholder ready for code review
 
 ### Story Sequencing (If Level 1)
 
@@ -56,38 +127,66 @@
 
 ### Coverage
 
-- [ ] Story acceptance criteria derived from tech-spec testing section
+- [ ] Story acceptance criteria derived from tech-spec
 - [ ] Story tasks map to tech-spec implementation guide
 - [ ] Files in stories match tech-spec source tree
+- [ ] Key code references align with tech-spec Developer Resources
 
 ---
 
-## 4. Workflow Status Integration
+## 6. Epic Quality (Level 1 Only)
 
-- [ ] bmm-workflow-status.md shows current_phase = "4-Implementation"
-- [ ] Phase 2 ("2-Plan") marked complete
-- [ ] First story in TODO section, others in BACKLOG (if Level 1)
-- [ ] Next action clear (review story, run story-ready)
+- [ ] **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
+- [ ] **Tech-spec reference**: Links back to tech-spec.md
 
 ---
 
-## 5. Readiness for Implementation
+## 7. Workflow Status Integration
 
-- [ ] Developer can start coding from tech-spec alone
-- [ ] All technical questions answered definitively
-- [ ] Testing approach clear and verifiable
-- [ ] Deployment strategy documented
+- [ ] bmm-workflow-status.yaml updated (if exists)
+- [ ] Current phase reflects tech-spec completion
+- [ ] Progress percentage updated appropriately
+- [ ] Next workflow clearly identified
 
 ---
 
-## 6. Critical Failures (Auto-Fail)
+## 8. Implementation Readiness (NEW - ENHANCED)
+
+### Can Developer Start Immediately?
+
+- [ ] **All context available**: Brownfield analysis + stack details + existing patterns
+- [ ] **No research needed**: Developer doesn't need to hunt for framework versions or patterns
+- [ ] **Specific file paths**: Developer knows exactly which files to create/modify
+- [ ] **Code references**: Can find similar code to reference (brownfield)
+- [ ] **Testing clear**: Knows what to test and how
+- [ ] **Deployment documented**: Knows how to deploy and rollback
+
+### Tech-Spec Replaces Story-Context?
+
+- [ ] **Comprehensive enough**: Contains all info typically in story-context XML
+- [ ] **Brownfield analysis**: If applicable, includes codebase reconnaissance
+- [ ] **Framework specifics**: Exact versions and usage patterns
+- [ ] **Pattern guidance**: Shows examples of existing patterns to follow
+
+---
+
+## 9. Critical Failures (Auto-Fail)
 
 - [ ] ❌ **Non-definitive technical decisions** (any "option A or B" or vague choices)
 - [ ] ❌ **Missing versions** (framework/library without specific version)
-- [ ] ❌ **Stories don't match template** (incompatible with story-context/dev-story workflows)
-- [ ] ❌ **Missing tech-spec sections** (required section missing from tech-spec.md)
+- [ ] ❌ **Context not gathered** (didn't check for document-project, setup files, etc.)
+- [ ] ❌ **Stack mismatch** (decisions don't align with detected project stack)
+- [ ] ❌ **Stories don't match template** (missing Dev Agent Record sections)
+- [ ] ❌ **Missing tech-spec sections** (required section missing from enhanced template)
 - [ ] ❌ **Stories have forward dependencies** (would break sequential implementation)
-- [ ] ❌ **Vague source tree** (file changes not specific)
+- [ ] ❌ **Vague source tree** (file changes not specific with actions)
+- [ ] ❌ **No brownfield analysis** (when document-project output exists but wasn't used)
 
 ---
 
@@ -95,13 +194,21 @@
 
 **Document any findings:**
 
-- Definitiveness score: [All definitive / Some ambiguity / Significant ambiguity]
-- Strengths:
-- Issues to address:
-- Recommended actions:
+- **Context Gathering Score**: [Comprehensive / Partial / Insufficient]
+- **Definitiveness Score**: [All definitive / Some ambiguity / Significant ambiguity]
+- **Brownfield Integration**: [N/A - Greenfield / Excellent / Partial / Missing]
+- **Stack Alignment**: [Perfect / Good / Partial / None]
+
+## **Strengths:**
+
+## **Issues to address:**
+
+## **Recommended actions:**
 
 **Ready for implementation?** [Yes / No - explain]
 
+**Can skip story-context?** [Yes - tech-spec is comprehensive / No - additional context needed / N/A]
+
 ---
 
-_Adapt based on Level 0 vs Level 1. Focus on definitiveness above all else._
+_The tech-spec should be a RICH CONTEXT DOCUMENT that gives developers everything they need without requiring separate context generation._

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

@@ -1,11 +1,58 @@
 # {{project_name}} - Epic Breakdown
 
-## Epic Overview
+**Date:** {{date}}
+**Project Level:** {{project_level}}
 
-{{epic_overview}}
+---
+
+## Epic: {{epic_title}}
+
+**Slug:** {{epic_slug}}
+
+### Goal
+
+{{epic_goal}}
+
+### Scope
+
+{{epic_scope}}
+
+### Success Criteria
+
+{{epic_success_criteria}}
+
+### Dependencies
+
+{{epic_dependencies}}
+
+---
+
+## Story Map
+
+{{story_map}}
+
+---
+
+## Story Summaries
+
+{{story_summaries}}
+
+---
+
+## Implementation Timeline
+
+**Total Story Points:** {{total_points}}
+
+**Estimated Timeline:** {{estimated_timeline}}
+
+---
+
+## Implementation Sequence
+
+{{implementation_sequence}}
 
 ---
 
-## Epic Details
+## Tech-Spec Reference
 
-{{epic_details}}
+See [tech-spec.md](../tech-spec.md) for complete technical implementation details.