bmad-method 5.1.2 → 6.0.0-alpha.0

package/src/modules/bmm/workflows/2-plan/README.md

@@ -0,0 +1,203 @@
+# Project Planning Workflow
+
+## Overview
+
+Scale-adaptive project planning workflow that automatically adjusts outputs based on project scope - from single atomic changes (Level 0: tech-spec only) to enterprise platforms (Level 4: full PRD + epics). Generates appropriate planning artifacts for each level with intelligent routing and continuation support.
+
+## Key Features
+
+- **Scale-adaptive planning** - Automatically determines output based on project complexity
+- **Intelligent routing** - Uses router system to load appropriate instruction sets
+- **Continuation support** - Can resume from previous sessions and handle incremental work
+- **Multi-level outputs** - Supports 5 project levels (0-4) with appropriate artifacts
+- **Input integration** - Leverages product briefs and market research when available
+- **Template-driven** - Uses validated templates for consistent output structure
+
+## Usage
+
+### Basic Invocation
+
+```bash
+workflow plan-project
+```
+
+### With Input Documents
+
+```bash
+# With product brief as input
+workflow plan-project --input /path/to/product-brief.md
+
+# With multiple inputs
+workflow plan-project --input product-brief.md --input market-research.md
+```
+
+### Configuration
+
+The workflow adapts automatically based on project assessment, but key configuration options include:
+
+- **scale_parameters**: Defines story/epic counts for each project level
+- **output_folder**: Where all generated documents are stored
+- **project_name**: Used in document names and templates
+
+## Workflow Structure
+
+### Files Included
+
+```
+plan-project/
+├── workflow.yaml              # Configuration and metadata
+├── instructions-router.md     # Initial assessment and routing logic
+├── instructions-sm.md         # Level 0 instructions (tech-spec only)
+├── instructions-med.md        # Level 1-2 instructions (PRD + tech-spec)
+├── instructions-lg.md         # Level 3-4 instructions (full PRD + epics)
+├── analysis-template.md       # Project assessment template
+├── prd-template.md           # Product Requirements Document template
+├── tech-spec-template.md     # Technical Specification template
+├── epics-template.md         # Epic breakdown template
+├── checklist.md              # Validation criteria
+└── README.md                 # This file
+```
+
+## Workflow Process
+
+### Phase 1: Assessment and Routing (Steps 1-5)
+
+- **Project Analysis**: Determines project type (greenfield/brownfield/legacy)
+- **Scope Assessment**: Classifies into 5 levels based on complexity
+- **Document Discovery**: Identifies existing inputs and documentation
+- **Workflow Routing**: Loads appropriate instruction set based on level
+- **Continuation Handling**: Resumes from previous work when applicable
+
+### Phase 2: Level-Specific Planning (Steps vary by level)
+
+**Level 0 (Single Atomic Change)**:
+
+- Creates technical specification only
+- Focuses on implementation details for small changes
+
+**Level 1-2 (Features and Small Systems)**:
+
+- Generates minimal PRD with core sections
+- Creates comprehensive tech-spec
+- Includes basic epic breakdown
+
+**Level 3-4 (Full Products and Platforms)**:
+
+- Produces complete PRD with all sections
+- Generates detailed epic breakdown
+- Includes architect handoff materials
+- Creates traceability mapping
+
+### Phase 3: Validation and Handoff (Final steps)
+
+- **Document Review**: Validates outputs against checklists
+- **Architect Preparation**: For Level 3-4, prepares handoff materials
+- **Next Steps**: Provides guidance for development phase
+
+## Output
+
+### Generated Files
+
+- **Primary output**: PRD.md (except Level 0), tech-spec.md, project-workflow-analysis.md
+- **Supporting files**: epics.md (Level 3-4), PRD-validation-report.md (if validation run)
+
+### Output Structure by Level
+
+**Level 0 - Tech Spec Only**:
+
+1. **Technical Overview** - Implementation approach
+2. **Detailed Design** - Code-level specifications
+3. **Testing Strategy** - Validation approach
+
+**Level 1-2 - Minimal PRD + Tech Spec**:
+
+1. **Problem Statement** - Core issue definition
+2. **Solution Overview** - High-level approach
+3. **Requirements** - Functional and non-functional
+4. **Technical Specification** - Implementation details
+5. **Success Criteria** - Acceptance criteria
+
+**Level 3-4 - Full PRD + Epics**:
+
+1. **Executive Summary** - Project overview
+2. **Problem Definition** - Detailed problem analysis
+3. **Solution Architecture** - Comprehensive solution design
+4. **User Experience** - Journey mapping and wireframes
+5. **Requirements** - Complete functional/non-functional specs
+6. **Epic Breakdown** - Development phases and stories
+7. **Technical Handoff** - Architecture and implementation guidance
+
+## Requirements
+
+- **Input Documents**: Product brief and/or market research (recommended but not required)
+- **Project Configuration**: Valid config.yaml with project_name and output_folder
+- **Assessment Readiness**: Clear understanding of project scope and objectives
+
+## Best Practices
+
+### Before Starting
+
+1. **Gather Context**: Collect any existing product briefs, market research, or requirements
+2. **Define Scope**: Have a clear sense of project boundaries and complexity
+3. **Prepare Stakeholders**: Ensure key stakeholders are available for input if needed
+
+### During Execution
+
+1. **Be Honest About Scope**: Accurate assessment ensures appropriate planning depth
+2. **Leverage Existing Work**: Reference previous documents and avoid duplication
+3. **Think Incrementally**: Remember that planning can evolve - start with what you know
+
+### After Completion
+
+1. **Validate Against Checklist**: Use included validation criteria to ensure completeness
+2. **Share with Stakeholders**: Distribute appropriate documents to relevant team members
+3. **Prepare for Architecture**: For Level 3-4 projects, ensure architect has complete context
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Workflow creates wrong level of documentation
+
+- **Solution**: Review project assessment and restart with correct scope classification
+- **Check**: Verify the project-workflow-analysis.md reflects actual project complexity
+
+**Issue**: Missing input documents cause incomplete planning
+
+- **Solution**: Gather recommended inputs or proceed with manual context gathering
+- **Check**: Ensure critical business context is captured even without formal documents
+
+**Issue**: Continuation from previous session fails
+
+- **Solution**: Check for existing project-workflow-analysis.md and ensure output folder is correct
+- **Check**: Verify previous session completed at a valid checkpoint
+
+## Customization
+
+To customize this workflow:
+
+1. **Modify Assessment Logic**: Update instructions-router.md to adjust level classification
+2. **Adjust Templates**: Customize PRD, tech-spec, or epic templates for organizational needs
+3. **Add Validation**: Extend checklist.md with organization-specific quality criteria
+4. **Configure Outputs**: Modify workflow.yaml to change file naming or structure
+
+## Version History
+
+- **v6.0.0** - Scale-adaptive architecture with intelligent routing
+  - Multi-level project support (0-4)
+  - Continuation and resumption capabilities
+  - Template-driven output generation
+  - Input document integration
+
+## Support
+
+For issues or questions:
+
+- Review the workflow creation guide at `/bmad/bmb/workflows/build-workflow/workflow-creation-guide.md`
+- Validate output using `checklist.md`
+- Consult project assessment in `project-workflow-analysis.md`
+- Check continuation status in existing output documents
+
+---
+
+_Part of the BMad Method v6 - BMM (Method) Module_

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

@@ -0,0 +1,369 @@
+# Project Planning Validation Checklist (Adaptive: All Levels)
+
+**Scope**: This checklist adapts based on project level (0-4) and field type (greenfield/brownfield)
+
+- **Level 0**: Tech-spec only validation
+- **Level 1-2**: PRD + Tech-spec + Epics validation
+- **Level 3-4**: PRD + Epics validation (no tech-spec)
+- **Greenfield**: Focus on setup sequencing and dependencies
+- **Brownfield**: Focus on integration risks and backward compatibility
+
+## User Intent Validation (Critical First Check)
+
+### Input Sources and User Need
+
+- [ ] Product brief or initial context was properly gathered (not just project name)
+- [ ] User's actual problem/need was identified through conversation (not assumed)
+- [ ] Technical preferences mentioned by user were captured separately
+- [ ] User confirmed the description accurately reflects their vision
+- [ ] The PRD addresses what the user asked for, not what we think they need
+
+### Alignment with User Goals
+
+- [ ] Goals directly address the user's stated problem
+- [ ] Context reflects actual user-provided information (not invented)
+- [ ] Requirements map to explicit user needs discussed
+- [ ] Nothing critical the user mentioned is missing
+
+## Document Structure
+
+- [ ] All required sections are present
+- [ ] No placeholder text remains (all {{variables}} replaced)
+- [ ] Proper formatting and organization throughout
+
+## Section 1: Description
+
+- [ ] Clear, concise description of what's being built
+- [ ] Matches user's actual request (not extrapolated)
+- [ ] Sets proper scope and expectations
+
+## Section 2: Goals (Step 2)
+
+- [ ] Level 3: Contains 3-5 primary goals
+- [ ] Level 4: Contains 5-7 strategic goals
+- [ ] Each goal is specific and measurable where possible
+- [ ] Goals focus on user and project outcomes
+- [ ] Goals represent what success looks like
+- [ ] Strategic objectives align with product scale
+
+## Section 3: Context (Step 3)
+
+- [ ] 1-2 short paragraphs explaining why this matters now
+- [ ] Context was gathered from user (not invented)
+- [ ] Explains actual problem being solved
+- [ ] Describes current situation or pain point
+- [ ] Connects to real-world impact
+
+## Section 4: Functional Requirements (Step 4)
+
+- [ ] Level 3: Contains 12-20 FRs
+- [ ] Level 4: Contains 20-30 FRs
+- [ ] Each has unique FR identifier (FR001, FR002, etc.)
+- [ ] Requirements describe capabilities, not implementation
+- [ ] Related features grouped logically while maintaining granularity
+- [ ] All FRs are testable user actions
+- [ ] User provided feedback on proposed FRs
+- [ ] Missing capabilities user expected were added
+- [ ] Priority order reflects user input
+- [ ] Coverage comprehensive for target product scale
+
+## Section 5: Non-Functional Requirements (Step 5 - Optional)
+
+- [ ] Only included if truly needed (not arbitrary targets)
+- [ ] Each has unique NFR identifier
+- [ ] Business justification provided for each NFR
+- [ ] Compliance requirements noted if regulated industry
+- [ ] Performance constraints tied to business needs
+- [ ] Typically 0-5 for MVP (not invented)
+
+## Section 6: User Journeys (Step 6)
+
+- [ ] Level 3: 2-3 detailed user journeys documented
+- [ ] Level 4: 3-5 comprehensive journeys for major segments
+- [ ] Each journey has named persona with context
+- [ ] Journey shows complete path through system via FRs
+- [ ] Specific FR references included (e.g., "signs up (FR001)")
+- [ ] Success criteria and pain points identified
+- [ ] Edge cases and alternative paths considered
+- [ ] Journeys validate comprehensive value delivery
+
+## Section 7: UX Principles (Step 7 - Optional)
+
+- [ ] Target users and sophistication level defined
+- [ ] Design values stated (simple vs powerful, playful vs professional)
+- [ ] Platform strategy specified (mobile-first, web, native)
+- [ ] Accessibility requirements noted if applicable
+- [ ] Sets direction without prescribing specific solutions
+
+## Section 8: Epics (Step 8)
+
+- [ ] Level 3: 3-5 epics defined (targeting 12-40 stories)
+- [ ] Level 4: 5-8 epics defined (targeting 40+ stories)
+- [ ] Each epic represents significant, deployable functionality
+- [ ] Epic format includes: Title, Goal, Capabilities, Success Criteria, Dependencies
+- [ ] Related FRs grouped into coherent capabilities
+- [ ] Each epic references specific FR numbers
+- [ ] Post-MVP epics listed separately with their FRs
+- [ ] Dependencies between epics clearly noted
+- [ ] Phased delivery strategy apparent
+
+## Section 9: Out of Scope (Step 9)
+
+- [ ] Ideas preserved with FR/NFR references
+- [ ] Format: description followed by (FR###, NFR###)
+- [ ] Prevents scope creep while capturing future possibilities
+- [ ] Clear distinction from MVP scope
+
+## Section 10: Assumptions and Dependencies (Step 10)
+
+- [ ] Only ACTUAL assumptions from user discussion (not invented)
+- [ ] Technical choices user explicitly mentioned captured
+- [ ] Dependencies identified in FRs/NFRs listed
+- [ ] User-stated constraints documented
+- [ ] If none exist, states "No critical assumptions identified yet"
+
+## Cross-References and Consistency
+
+- [ ] All FRs trace back to at least one goal
+- [ ] User journeys reference actual FR numbers
+- [ ] Epic capabilities cover all FRs
+- [ ] Terminology consistent throughout
+- [ ] No contradictions between sections
+- [ ] Technical details saved to technical_preferences (not in PRD)
+
+## Quality Checks
+
+- [ ] Requirements are strategic, not implementation-focused
+- [ ] Document maintains appropriate abstraction level
+- [ ] No premature technical decisions
+- [ ] Focus on WHAT, not HOW
+
+## Readiness for Next Phase
+
+- [ ] Sufficient detail for comprehensive architecture design
+- [ ] Clear enough for detailed solution design
+- [ ] Ready for epic breakdown into 12-40+ stories
+- [ ] Value delivery path supports phased releases
+- [ ] If UI exists, ready for UX expert collaboration
+- [ ] Scale and complexity match Level 3-4 requirements
+
+## Scale Validation
+
+- [ ] Project scope justifies PRD
+- [ ] Complexity matches Level 1-4 designation
+- [ ] Story estimate aligns with epic structure (12-40+)
+- [ ] Not over-engineered for actual needs
+
+## Final Validation
+
+- [ ] Document addresses user's original request completely
+- [ ] All user feedback incorporated
+- [ ] No critical user requirements missing
+- [ ] Ready for user final review and approval
+- [ ] File saved in correct location: {{output_folder}}/PRD.md
+
+---
+
+# Cohesion Validation (All Levels)
+
+**Purpose**: Validate alignment between planning artifacts and readiness for implementation
+
+## Project Context Detection
+
+- [ ] Project level confirmed (0, 1, 2, 3, or 4)
+- [ ] Field type identified (greenfield or brownfield)
+- [ ] Appropriate validation sections applied based on context
+
+## Section A: Tech Spec Validation (Levels 0, 1, 2 only)
+
+### A.1 Tech Spec Completeness
+
+- [ ] All technical decisions are DEFINITIVE (no "Option A or B")
+- [ ] Specific versions specified for all frameworks/libraries
+- [ ] Source tree structure clearly defined
+- [ ] Technical approach precisely described
+- [ ] Implementation stack complete with exact tools
+- [ ] Testing approach clearly defined
+- [ ] Deployment strategy documented
+
+### A.2 Tech Spec - PRD Alignment (Levels 1-2 only)
+
+- [ ] Every functional requirement has technical solution
+- [ ] Non-functional requirements addressed in tech spec
+- [ ] Tech stack aligns with PRD constraints
+- [ ] Performance requirements achievable with chosen stack
+- [ ] Technical preferences from user incorporated
+
+## Section B: Greenfield-Specific Validation (if greenfield)
+
+### B.1 Project Setup Sequencing
+
+- [ ] Epic 0 or 1 includes project initialization steps
+- [ ] Repository setup precedes feature development
+- [ ] Development environment configuration included early
+- [ ] Core dependencies installed before use
+- [ ] Testing infrastructure set up before tests written
+
+### B.2 Infrastructure Before Features
+
+- [ ] Database setup before data operations
+- [ ] API framework before endpoint implementation
+- [ ] Authentication setup before protected features
+- [ ] CI/CD pipeline before deployment
+- [ ] Monitoring setup included
+
+### B.3 External Dependencies
+
+- [ ] Third-party account creation assigned to user
+- [ ] API keys acquisition process defined
+- [ ] Credential storage approach specified
+- [ ] External service setup sequenced properly
+- [ ] Fallback strategies for external failures
+
+## Section C: Brownfield-Specific Validation (if brownfield)
+
+### C.1 Existing System Integration
+
+- [ ] Current architecture analyzed and documented
+- [ ] Integration points with existing system identified
+- [ ] Existing functionality preservation validated
+- [ ] Database schema compatibility assessed
+- [ ] API contract compatibility verified
+
+### C.2 Risk Management
+
+- [ ] Breaking change risks identified and mitigated
+- [ ] Rollback procedures defined for each integration
+- [ ] Feature flags or toggles included where appropriate
+- [ ] Performance degradation risks assessed
+- [ ] User impact analysis completed
+
+### C.3 Backward Compatibility
+
+- [ ] Database migrations maintain backward compatibility
+- [ ] API changes don't break existing consumers
+- [ ] Authentication/authorization integration safe
+- [ ] Configuration changes non-breaking
+- [ ] Existing monitoring preserved or enhanced
+
+### C.4 Dependency Conflicts
+
+- [ ] New dependencies compatible with existing versions
+- [ ] No version conflicts introduced
+- [ ] Security vulnerabilities not introduced
+- [ ] License compatibility verified
+- [ ] Bundle size impact acceptable
+
+## Section D: Feature Sequencing (All Levels)
+
+### D.1 Functional Dependencies
+
+- [ ] Features depending on others sequenced correctly
+- [ ] Shared components built before consumers
+- [ ] User flows follow logical progression
+- [ ] Authentication precedes protected features
+
+### D.2 Technical Dependencies
+
+- [ ] Lower-level services before higher-level ones
+- [ ] Utilities and libraries created before use
+- [ ] Data models defined before operations
+- [ ] API endpoints before client consumption
+
+### D.3 Epic Dependencies
+
+- [ ] Later epics build on earlier epic functionality
+- [ ] No circular dependencies between epics
+- [ ] Infrastructure from early epics reused
+- [ ] Incremental value delivery maintained
+
+## Section E: UI/UX Cohesion (if UI components exist)
+
+### E.1 Design System (Greenfield)
+
+- [ ] UI framework selected and installed early
+- [ ] Design system or component library established
+- [ ] Styling approach defined
+- [ ] Responsive design strategy clear
+- [ ] Accessibility requirements defined
+
+### E.2 Design Consistency (Brownfield)
+
+- [ ] UI consistent with existing system
+- [ ] Component library updates non-breaking
+- [ ] Styling approach matches existing
+- [ ] Accessibility standards maintained
+- [ ] Existing user workflows preserved
+
+### E.3 UX Flow Validation
+
+- [ ] User journeys mapped completely
+- [ ] Navigation patterns defined
+- [ ] Error and loading states planned
+- [ ] Form validation patterns established
+
+## Section F: Responsibility Assignment (All Levels)
+
+### F.1 User vs Agent Clarity
+
+- [ ] Human-only tasks assigned to user
+- [ ] Account creation on external services → user
+- [ ] Payment/purchasing actions → user
+- [ ] All code tasks → developer agent
+- [ ] Configuration management properly assigned
+
+## Section G: Documentation Readiness (All Levels)
+
+### G.1 Developer Documentation
+
+- [ ] Setup instructions comprehensive
+- [ ] Technical decisions documented
+- [ ] Patterns and conventions clear
+- [ ] API documentation plan exists (if applicable)
+
+### G.2 Deployment Documentation (Brownfield)
+
+- [ ] Runbook updates planned
+- [ ] Incident response procedures updated
+- [ ] Rollback procedures documented and tested
+- [ ] Monitoring dashboard updates planned
+
+## Section H: Future-Proofing (All Levels)
+
+### H.1 Extensibility
+
+- [ ] Current scope vs future features clearly separated
+- [ ] Architecture supports planned enhancements
+- [ ] Technical debt considerations documented
+- [ ] Extensibility points identified
+
+### H.2 Observability
+
+- [ ] Monitoring strategy defined
+- [ ] Success metrics from planning captured
+- [ ] Analytics or tracking included if needed
+- [ ] Performance measurement approach clear
+
+## Cohesion Summary
+
+### Overall Readiness Assessment
+
+- [ ] **Ready for Development** - All critical items pass
+- [ ] **Needs Alignment** - Some gaps need addressing
+- [ ] **Too Risky** (brownfield only) - Integration risks too high
+
+### Critical Gaps Identified
+
+_List any blocking issues or unacceptable risks:_
+
+### Integration Risk Level (brownfield only)
+
+- [ ] Low - well-understood integration with good rollback
+- [ ] Medium - some unknowns but manageable
+- [ ] High - significant risks require mitigation
+
+### Recommendations
+
+_Specific actions to improve cohesion before development:_
+
+---