mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
docs: massive documentation overhaul + introduce Paige (Documentation Guide agent)
## 📚 Complete Documentation Restructure **BMM Documentation Hub Created:** - New centralized documentation system at `src/modules/bmm/docs/` - 18 comprehensive guides organized by topic (7000+ lines total) - Clear learning paths for greenfield, brownfield, and quick spec flows - Professional technical writing standards throughout **New Documentation:** - `README.md` - Complete documentation hub with navigation - `quick-start.md` - 15-minute getting started guide - `agents-guide.md` - Comprehensive 12-agent reference (45 min read) - `party-mode.md` - Multi-agent collaboration guide (20 min read) - `scale-adaptive-system.md` - Deep dive on Levels 0-4 (42 min read) - `brownfield-guide.md` - Existing codebase development (53 min read) - `quick-spec-flow.md` - Rapid Level 0-1 development (26 min read) - `workflows-analysis.md` - Phase 1 workflows (12 min read) - `workflows-planning.md` - Phase 2 workflows (19 min read) - `workflows-solutioning.md` - Phase 3 workflows (13 min read) - `workflows-implementation.md` - Phase 4 workflows (33 min read) - `workflows-testing.md` - Testing & QA workflows (29 min read) - `workflow-architecture-reference.md` - Architecture workflow deep-dive - `workflow-document-project-reference.md` - Document-project workflow reference - `enterprise-agentic-development.md` - Team collaboration patterns - `faq.md` - Comprehensive Q&A covering all topics - `glossary.md` - Complete terminology reference - `troubleshooting.md` - Common issues and solutions **Documentation Improvements:** - Removed all version/date footers (git handles versioning) - Agent customization docs now include full rebuild process - Cross-referenced links between all guides - Reading time estimates for all major docs - Consistent professional formatting and structure **Consolidated & Streamlined:** - Module README (`src/modules/bmm/README.md`) streamlined to lean signpost - Root README polished with better hierarchy and clear CTAs - Moved docs from root `docs/` to module-specific locations - Better separation of user docs vs. developer reference ## 🤖 New Agent: Paige (Documentation Guide) **Role:** Technical documentation specialist and information architect **Expertise:** - Professional technical writing standards - Documentation structure and organization - Information architecture and navigation - User-focused content design - Style guide enforcement **Status:** Work in progress - Paige will evolve as documentation needs grow **Integration:** - Listed in agents-guide.md, glossary.md, FAQ - Available for all phases (documentation is continuous) - Can be customized like all BMM agents ## 🔧 Additional Changes - Updated agent manifest with Paige - Updated workflow manifest with new documentation workflows - Fixed workflow-to-agent mappings across all guides - Improved root README with clearer Quick Start section - Better module structure explanations - Enhanced community links with Discord channel names **Total Impact:** - 18 new/restructured documentation files - 7000+ lines of professional technical documentation - Complete navigation system with cross-references - Clear learning paths for all user types - Foundation for knowledge base (coming in beta) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Brian Madison
258
bmad/bmm/workflows/2-plan-workflows/README.md
Normal file
258
bmad/bmm/workflows/2-plan-workflows/README.md
Normal file
@@ -0,0 +1,258 @@
|
||||
---
|
||||
last-redoc-date: 2025-10-01
|
||||
---
|
||||
|
||||
# Project Planning Workflow (Phase 2)
|
||||
|
||||
The Phase 2 Planning workflow is **scale-adaptive**, meaning it automatically determines the right level of planning documentation based on project complexity (Levels 0-4). This ensures planning overhead matches project value—from minimal tech specs for bug fixes to comprehensive PRDs for enterprise platforms.
|
||||
|
||||
## Scale-Adaptive Flow (Levels 0-4)
|
||||
|
||||
The workflow routes to different planning approaches based on project level:
|
||||
|
||||
### Level 0 - Single File Change / Bug Fix
|
||||
|
||||
**Planning:** Tech-spec only (lightweight implementation plan)
|
||||
**Output:** `tech-spec.md` with single story
|
||||
**Next Phase:** Direct to implementation (Phase 4)
|
||||
|
||||
### Level 1 - Small Feature (1-3 files, 2-5 stories)
|
||||
|
||||
**Planning:** Tech-spec only (implementation-focused)
|
||||
**Output:** `tech-spec.md` with epic breakdown and stories
|
||||
**Next Phase:** Direct to implementation (Phase 4)
|
||||
|
||||
### Level 2 - Feature Set / Small Project (5-15 stories, 1-2 epics)
|
||||
|
||||
**Planning:** PRD (product-focused) + Tech-spec (technical planning)
|
||||
**Output:** `PRD.md`, `epics.md`, `tech-spec.md`
|
||||
**Next Phase:** Tech-spec workflow (lightweight solutioning), then implementation (Phase 4)
|
||||
**Note:** Level 2 uses tech-spec instead of full architecture to keep planning lightweight
|
||||
|
||||
### Level 3 - Medium Project (15-40 stories, 2-5 epics)
|
||||
|
||||
**Planning:** PRD (strategic product document)
|
||||
**Output:** `PRD.md`, `epics.md`
|
||||
**Next Phase:** create-architecture workflow (Phase 3), then implementation (Phase 4)
|
||||
|
||||
### Level 4 - Large/Enterprise Project (40-100+ stories, 5-10 epics)
|
||||
|
||||
**Planning:** PRD (comprehensive product specification)
|
||||
**Output:** `PRD.md`, `epics.md`
|
||||
**Next Phase:** create-architecture workflow (Phase 3), then implementation (Phase 4)
|
||||
|
||||
**Critical Distinction:**
|
||||
|
||||
- **Levels 0-1:** No PRD, tech-spec only
|
||||
- **Level 2:** PRD + tech-spec (skips full architecture)
|
||||
- **Levels 3-4:** PRD → full create-architecture workflow
|
||||
|
||||
Critical to v6's flow improvement is this workflow's integration with the bmm-workflow-status.md tracking document, which maintains project state across sessions, tracks which agents participate in each phase, and provides continuity for multi-session planning efforts. The workflow can resume from any point, intelligently detecting existing artifacts and determining next steps without redundant work. For UX-heavy projects, it can generate standalone UX specifications or AI frontend prompts from existing specs.
|
||||
|
||||
## 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
|
||||
|
||||
### 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
|
||||
|
||||
```
|
||||
2-plan-workflows/
|
||||
├── README.md # Overview and usage details
|
||||
├── checklist.md # Shared validation criteria
|
||||
├── prd/
|
||||
│ ├── epics-template.md # Epic breakdown template
|
||||
│ ├── instructions.md # Level 2-4 PRD instructions
|
||||
│ ├── prd-template.md # Product Requirements Document template
|
||||
│ └── workflow.yaml
|
||||
├── tech-spec/
|
||||
│ ├── epics-template.md # Epic-to-story handoff template
|
||||
│ ├── instructions-level0-story.md
|
||||
│ ├── instructions-level1-stories.md
|
||||
│ ├── instructions.md # Level 0-1 tech-spec instructions
|
||||
│ ├── tech-spec-template.md # Technical Specification template
|
||||
│ ├── user-story-template.md # Story template for Level 0/1
|
||||
│ └── workflow.yaml
|
||||
├── gdd/
|
||||
│ ├── instructions-gdd.md # Game Design Document instructions
|
||||
│ ├── gdd-template.md # GDD template
|
||||
│ ├── game-types.csv # Genre catalog
|
||||
│ ├── game-types/ # Genre-specific templates
|
||||
│ └── workflow.yaml
|
||||
├── narrative/
|
||||
│ ├── instructions-narrative.md # Narrative design instructions
|
||||
│ ├── narrative-template.md # Narrative planning template
|
||||
│ └── workflow.yaml
|
||||
└── create-ux-design/
|
||||
├── instructions.md # UX design instructions
|
||||
├── ux-design-template.md # UX design template
|
||||
├── checklist.md # UX design validation checklist
|
||||
└── workflow.yaml
|
||||
```
|
||||
|
||||
## 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 File Change / Bug Fix)**:
|
||||
|
||||
- Tech-spec only workflow
|
||||
- Single story implementation plan
|
||||
- Direct to Phase 4 (implementation)
|
||||
|
||||
**Level 1 (Small Feature)**:
|
||||
|
||||
- Tech-spec only workflow
|
||||
- Epic breakdown with 2-5 stories
|
||||
- Direct to Phase 4 (implementation)
|
||||
|
||||
**Level 2 (Feature Set / Small Project)**:
|
||||
|
||||
- PRD workflow (strategic product document)
|
||||
- Generates `PRD.md` and `epics.md`
|
||||
- Then runs tech-spec workflow (lightweight solutioning)
|
||||
- Then to Phase 4 (implementation)
|
||||
|
||||
**Level 3-4 (Medium to Enterprise Projects)**:
|
||||
|
||||
- PRD workflow (comprehensive product specification)
|
||||
- Generates `PRD.md` and `epics.md`
|
||||
- Hands off to Phase 3 (create-architecture workflow)
|
||||
- Full architecture design before implementation
|
||||
|
||||
### 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, bmm-workflow-status.md
|
||||
- **Supporting files**: epics.md (Level 2-4), PRD-validation-report.md (if validation run)
|
||||
|
||||
### Output Structure by Level
|
||||
|
||||
**Level 0 - Tech Spec Only**:
|
||||
|
||||
- `tech-spec.md` - Single story implementation plan
|
||||
- Direct to implementation
|
||||
|
||||
**Level 1 - Tech Spec with Epic Breakdown**:
|
||||
|
||||
- `tech-spec.md` - Epic breakdown with 2-5 stories
|
||||
- Direct to implementation
|
||||
|
||||
**Level 2 - PRD + Tech Spec**:
|
||||
|
||||
- `PRD.md` - Strategic product document (goals, requirements, user journeys, UX principles, UI goals, epic list, scope)
|
||||
- `epics.md` - Tactical implementation roadmap (detailed story breakdown)
|
||||
- `tech-spec.md` - Lightweight technical planning (generated after PRD)
|
||||
- Then to implementation
|
||||
|
||||
**Level 3-4 - PRD + Full Architecture**:
|
||||
|
||||
- `PRD.md` - Comprehensive product specification
|
||||
- `epics.md` - Complete epic/story breakdown
|
||||
- Hands off to create-architecture workflow (Phase 3)
|
||||
- `architecture.md` - Generated by architect workflow
|
||||
- Then to implementation
|
||||
|
||||
## 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 bmm-workflow-status.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 bmm-workflow-status.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/create-workflow/workflow-creation-guide.md`
|
||||
- Validate output using `checklist.md`
|
||||
- Consult project assessment in `bmm-workflow-status.md`
|
||||
- Check continuation status in existing output documents
|
||||
|
||||
---
|
||||
|
||||
_Part of the BMad Method v6 - BMM (Method) Module_
|
||||
@@ -0,0 +1,310 @@
|
||||
# Create UX Design Workflow Validation Checklist
|
||||
|
||||
**Purpose**: Validate UX Design Specification is complete, collaborative, and implementation-ready.
|
||||
|
||||
**Paradigm**: Visual collaboration-driven, not template generation
|
||||
|
||||
**Expected Outputs**:
|
||||
|
||||
- ux-design-specification.md
|
||||
- ux-color-themes.html (color theme visualizer)
|
||||
- ux-design-directions.html (design mockups)
|
||||
- Optional: ux-prototype.html, ux-component-showcase.html, ai-frontend-prompt.md
|
||||
|
||||
---
|
||||
|
||||
## 1. Output Files Exist
|
||||
|
||||
- [ ] **ux-design-specification.md** created in output folder
|
||||
- [ ] **ux-color-themes.html** generated (interactive color exploration)
|
||||
- [ ] **ux-design-directions.html** generated (6-8 design mockups)
|
||||
- [ ] No unfilled {{template_variables}} in specification
|
||||
- [ ] All sections have content (not placeholder text)
|
||||
|
||||
---
|
||||
|
||||
## 2. Collaborative Process Validation
|
||||
|
||||
**The workflow should facilitate decisions WITH the user, not FOR them**
|
||||
|
||||
- [ ] **Design system chosen by user** (not auto-selected)
|
||||
- [ ] **Color theme selected from options** (user saw visualizations and chose)
|
||||
- [ ] **Design direction chosen from mockups** (user explored 6-8 options)
|
||||
- [ ] **User journey flows designed collaboratively** (options presented, user decided)
|
||||
- [ ] **UX patterns decided with user input** (not just generated)
|
||||
- [ ] **Decisions documented WITH rationale** (why each choice was made)
|
||||
|
||||
---
|
||||
|
||||
## 3. Visual Collaboration Artifacts
|
||||
|
||||
### Color Theme Visualizer
|
||||
|
||||
- [ ] **HTML file exists and is valid** (ux-color-themes.html)
|
||||
- [ ] **Shows 3-4 theme options** (or documented existing brand)
|
||||
- [ ] **Each theme has complete palette** (primary, secondary, semantic colors)
|
||||
- [ ] **Live UI component examples** in each theme (buttons, forms, cards)
|
||||
- [ ] **Side-by-side comparison** enabled
|
||||
- [ ] **User's selection documented** in specification
|
||||
|
||||
### Design Direction Mockups
|
||||
|
||||
- [ ] **HTML file exists and is valid** (ux-design-directions.html)
|
||||
- [ ] **6-8 different design approaches** shown
|
||||
- [ ] **Full-screen mockups** of key screens
|
||||
- [ ] **Design philosophy labeled** for each direction (e.g., "Dense Dashboard", "Spacious Explorer")
|
||||
- [ ] **Interactive navigation** between directions
|
||||
- [ ] **Responsive preview** toggle available
|
||||
- [ ] **User's choice documented WITH reasoning** (what they liked, why it fits)
|
||||
|
||||
---
|
||||
|
||||
## 4. Design System Foundation
|
||||
|
||||
- [ ] **Design system chosen** (or custom design decision documented)
|
||||
- [ ] **Current version identified** (if using established system)
|
||||
- [ ] **Components provided by system documented**
|
||||
- [ ] **Custom components needed identified**
|
||||
- [ ] **Decision rationale clear** (why this system for this project)
|
||||
|
||||
---
|
||||
|
||||
## 5. Core Experience Definition
|
||||
|
||||
- [ ] **Defining experience articulated** (the ONE thing that makes this app unique)
|
||||
- [ ] **Novel UX patterns identified** (if applicable)
|
||||
- [ ] **Novel patterns fully designed** (interaction model, states, feedback)
|
||||
- [ ] **Core experience principles defined** (speed, guidance, flexibility, feedback)
|
||||
|
||||
---
|
||||
|
||||
## 6. Visual Foundation
|
||||
|
||||
### Color System
|
||||
|
||||
- [ ] **Complete color palette** (primary, secondary, accent, semantic, neutrals)
|
||||
- [ ] **Semantic color usage defined** (success, warning, error, info)
|
||||
- [ ] **Color accessibility considered** (contrast ratios for text)
|
||||
- [ ] **Brand alignment** (follows existing brand or establishes new identity)
|
||||
|
||||
### Typography
|
||||
|
||||
- [ ] **Font families selected** (heading, body, monospace if needed)
|
||||
- [ ] **Type scale defined** (h1-h6, body, small, etc.)
|
||||
- [ ] **Font weights documented** (when to use each)
|
||||
- [ ] **Line heights specified** for readability
|
||||
|
||||
### Spacing & Layout
|
||||
|
||||
- [ ] **Spacing system defined** (base unit, scale)
|
||||
- [ ] **Layout grid approach** (columns, gutters)
|
||||
- [ ] **Container widths** for different breakpoints
|
||||
|
||||
---
|
||||
|
||||
## 7. Design Direction
|
||||
|
||||
- [ ] **Specific direction chosen** from mockups (not generic)
|
||||
- [ ] **Layout pattern documented** (navigation, content structure)
|
||||
- [ ] **Visual hierarchy defined** (density, emphasis, focus)
|
||||
- [ ] **Interaction patterns specified** (modal vs inline, disclosure approach)
|
||||
- [ ] **Visual style documented** (minimal, balanced, rich, maximalist)
|
||||
- [ ] **User's reasoning captured** (why this direction fits their vision)
|
||||
|
||||
---
|
||||
|
||||
## 8. User Journey Flows
|
||||
|
||||
- [ ] **All critical journeys from PRD designed** (no missing flows)
|
||||
- [ ] **Each flow has clear goal** (what user accomplishes)
|
||||
- [ ] **Flow approach chosen collaboratively** (user picked from options)
|
||||
- [ ] **Step-by-step documentation** (screens, actions, feedback)
|
||||
- [ ] **Decision points and branching** defined
|
||||
- [ ] **Error states and recovery** addressed
|
||||
- [ ] **Success states specified** (completion feedback)
|
||||
- [ ] **Mermaid diagrams or clear flow descriptions** included
|
||||
|
||||
---
|
||||
|
||||
## 9. Component Library Strategy
|
||||
|
||||
- [ ] **All required components identified** (from design system + custom)
|
||||
- [ ] **Custom components fully specified**:
|
||||
- Purpose and user-facing value
|
||||
- Content/data displayed
|
||||
- User actions available
|
||||
- All states (default, hover, active, loading, error, disabled)
|
||||
- Variants (sizes, styles, layouts)
|
||||
- Behavior on interaction
|
||||
- Accessibility considerations
|
||||
- [ ] **Design system components customization needs** documented
|
||||
|
||||
---
|
||||
|
||||
## 10. UX Pattern Consistency Rules
|
||||
|
||||
**These patterns ensure consistent UX across the entire app**
|
||||
|
||||
- [ ] **Button hierarchy defined** (primary, secondary, tertiary, destructive)
|
||||
- [ ] **Feedback patterns established** (success, error, warning, info, loading)
|
||||
- [ ] **Form patterns specified** (labels, validation, errors, help text)
|
||||
- [ ] **Modal patterns defined** (sizes, dismiss behavior, focus, stacking)
|
||||
- [ ] **Navigation patterns documented** (active state, breadcrumbs, back button)
|
||||
- [ ] **Empty state patterns** (first use, no results, cleared content)
|
||||
- [ ] **Confirmation patterns** (when to confirm destructive actions)
|
||||
- [ ] **Notification patterns** (placement, duration, stacking, priority)
|
||||
- [ ] **Search patterns** (trigger, results, filters, no results)
|
||||
- [ ] **Date/time patterns** (format, timezone, pickers)
|
||||
|
||||
**Each pattern should have:**
|
||||
|
||||
- [ ] Clear specification (how it works)
|
||||
- [ ] Usage guidance (when to use)
|
||||
- [ ] Examples (concrete implementations)
|
||||
|
||||
---
|
||||
|
||||
## 11. Responsive Design
|
||||
|
||||
- [ ] **Breakpoints defined** for target devices (mobile, tablet, desktop)
|
||||
- [ ] **Adaptation patterns documented** (how layouts change)
|
||||
- [ ] **Navigation adaptation** (how nav changes on small screens)
|
||||
- [ ] **Content organization changes** (multi-column to single, grid to list)
|
||||
- [ ] **Touch targets adequate** on mobile (minimum size specified)
|
||||
- [ ] **Responsive strategy aligned** with chosen design direction
|
||||
|
||||
---
|
||||
|
||||
## 12. Accessibility
|
||||
|
||||
- [ ] **WCAG compliance level specified** (A, AA, or AAA)
|
||||
- [ ] **Color contrast requirements** documented (ratios for text)
|
||||
- [ ] **Keyboard navigation** addressed (all interactive elements accessible)
|
||||
- [ ] **Focus indicators** specified (visible focus states)
|
||||
- [ ] **ARIA requirements** noted (roles, labels, announcements)
|
||||
- [ ] **Screen reader considerations** (meaningful labels, structure)
|
||||
- [ ] **Alt text strategy** for images
|
||||
- [ ] **Form accessibility** (label associations, error identification)
|
||||
- [ ] **Testing strategy** defined (automated tools, manual testing)
|
||||
|
||||
---
|
||||
|
||||
## 13. Coherence and Integration
|
||||
|
||||
- [ ] **Design system and custom components visually consistent**
|
||||
- [ ] **All screens follow chosen design direction**
|
||||
- [ ] **Color usage consistent with semantic meanings**
|
||||
- [ ] **Typography hierarchy clear and consistent**
|
||||
- [ ] **Similar actions handled the same way** (pattern consistency)
|
||||
- [ ] **All PRD user journeys have UX design**
|
||||
- [ ] **All entry points designed**
|
||||
- [ ] **Error and edge cases handled**
|
||||
- [ ] **Every interactive element meets accessibility requirements**
|
||||
- [ ] **All flows keyboard-navigable**
|
||||
- [ ] **Colors meet contrast requirements**
|
||||
|
||||
---
|
||||
|
||||
## 14. Cross-Workflow Alignment (Epics File Update)
|
||||
|
||||
**As UX design progresses, you discover implementation details that affect the story breakdown**
|
||||
|
||||
### Stories Discovered During UX Design
|
||||
|
||||
- [ ] **Review epics.md file** for alignment with UX design
|
||||
- [ ] **New stories identified** during UX design that weren't in epics.md:
|
||||
- [ ] Custom component build stories (if significant)
|
||||
- [ ] UX pattern implementation stories
|
||||
- [ ] Animation/transition stories
|
||||
- [ ] Responsive adaptation stories
|
||||
- [ ] Accessibility implementation stories
|
||||
- [ ] Edge case handling stories discovered during journey design
|
||||
- [ ] Onboarding/empty state stories
|
||||
- [ ] Error state handling stories
|
||||
|
||||
### Story Complexity Adjustments
|
||||
|
||||
- [ ] **Existing stories complexity reassessed** based on UX design:
|
||||
- [ ] Stories that are now more complex (UX revealed additional requirements)
|
||||
- [ ] Stories that are simpler (design system handles more than expected)
|
||||
- [ ] Stories that should be split (UX design shows multiple components/flows)
|
||||
- [ ] Stories that can be combined (UX design shows they're tightly coupled)
|
||||
|
||||
### Epic Alignment
|
||||
|
||||
- [ ] **Epic scope still accurate** after UX design
|
||||
- [ ] **New epic needed** for discovered work (if significant)
|
||||
- [ ] **Epic ordering might change** based on UX dependencies
|
||||
|
||||
### Action Items for Epics File Update
|
||||
|
||||
- [ ] **List of new stories to add** to epics.md documented
|
||||
- [ ] **Complexity adjustments noted** for existing stories
|
||||
- [ ] **Update epics.md** OR flag for architecture review first
|
||||
- [ ] **Rationale documented** for why new stories/changes are needed
|
||||
|
||||
**Note:** If significant story changes are identified, consider running architecture workflow BEFORE updating epics.md, since architecture decisions might reveal additional adjustments needed.
|
||||
|
||||
---
|
||||
|
||||
## 15. Decision Rationale
|
||||
|
||||
**Unlike template-driven workflows, this workflow should document WHY**
|
||||
|
||||
- [ ] **Design system choice has rationale** (why this fits the project)
|
||||
- [ ] **Color theme selection has reasoning** (why this emotional impact)
|
||||
- [ ] **Design direction choice explained** (what user liked, how it fits vision)
|
||||
- [ ] **User journey approaches justified** (why this flow pattern)
|
||||
- [ ] **UX pattern decisions have context** (why these patterns for this app)
|
||||
- [ ] **Responsive strategy aligned with user priorities**
|
||||
- [ ] **Accessibility level appropriate for deployment intent**
|
||||
|
||||
---
|
||||
|
||||
## 16. Implementation Readiness
|
||||
|
||||
- [ ] **Designers can create high-fidelity mockups** from this spec
|
||||
- [ ] **Developers can implement** with clear UX guidance
|
||||
- [ ] **Sufficient detail** for frontend development
|
||||
- [ ] **Component specifications actionable** (states, variants, behaviors)
|
||||
- [ ] **Flows implementable** (clear steps, decision logic, error handling)
|
||||
- [ ] **Visual foundation complete** (colors, typography, spacing all defined)
|
||||
- [ ] **Pattern consistency enforceable** (clear rules for implementation)
|
||||
|
||||
---
|
||||
|
||||
## 17. Critical Failures (Auto-Fail)
|
||||
|
||||
- [ ] ❌ **No visual collaboration** (color themes or design mockups not generated)
|
||||
- [ ] ❌ **User not involved in decisions** (auto-generated without collaboration)
|
||||
- [ ] ❌ **No design direction chosen** (missing key visual decisions)
|
||||
- [ ] ❌ **No user journey designs** (critical flows not documented)
|
||||
- [ ] ❌ **No UX pattern consistency rules** (implementation will be inconsistent)
|
||||
- [ ] ❌ **Missing core experience definition** (no clarity on what makes app unique)
|
||||
- [ ] ❌ **No component specifications** (components not actionable)
|
||||
- [ ] ❌ **Responsive strategy missing** (for multi-platform projects)
|
||||
- [ ] ❌ **Accessibility ignored** (no compliance target or requirements)
|
||||
- [ ] ❌ **Generic/templated content** (not specific to this project)
|
||||
|
||||
---
|
||||
|
||||
## Validation Notes
|
||||
|
||||
**Document findings:**
|
||||
|
||||
- UX Design Quality: [Exceptional / Strong / Adequate / Needs Work / Incomplete]
|
||||
- Collaboration Level: [Highly Collaborative / Collaborative / Somewhat Collaborative / Generated]
|
||||
- Visual Artifacts: [Complete & Interactive / Partial / Missing]
|
||||
- Implementation Readiness: [Ready / Needs Design Phase / Not Ready]
|
||||
|
||||
## **Strengths:**
|
||||
|
||||
## **Areas for Improvement:**
|
||||
|
||||
## **Recommended Actions:**
|
||||
|
||||
**Ready for next phase?** [Yes - Proceed to Design / Yes - Proceed to Development / Needs Refinement]
|
||||
|
||||
---
|
||||
|
||||
_This checklist validates collaborative UX design facilitation, not template generation. A successful UX workflow creates design decisions WITH the user through visual exploration and informed choices._
|
||||
1319
bmad/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md
Normal file
1319
bmad/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,145 @@
|
||||
# {{project_name}} UX Design Specification
|
||||
|
||||
_Created on {{date}} by {{user_name}}_
|
||||
_Generated using BMad Method - Create UX Design Workflow v1.0_
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{project_vision}}
|
||||
|
||||
---
|
||||
|
||||
## 1. Design System Foundation
|
||||
|
||||
### 1.1 Design System Choice
|
||||
|
||||
{{design_system_decision}}
|
||||
|
||||
---
|
||||
|
||||
## 2. Core User Experience
|
||||
|
||||
### 2.1 Defining Experience
|
||||
|
||||
{{core_experience}}
|
||||
|
||||
### 2.2 Novel UX Patterns
|
||||
|
||||
{{novel_ux_patterns}}
|
||||
|
||||
---
|
||||
|
||||
## 3. Visual Foundation
|
||||
|
||||
### 3.1 Color System
|
||||
|
||||
{{visual_foundation}}
|
||||
|
||||
**Interactive Visualizations:**
|
||||
|
||||
- Color Theme Explorer: [ux-color-themes.html](./ux-color-themes.html)
|
||||
|
||||
---
|
||||
|
||||
## 4. Design Direction
|
||||
|
||||
### 4.1 Chosen Design Approach
|
||||
|
||||
{{design_direction_decision}}
|
||||
|
||||
**Interactive Mockups:**
|
||||
|
||||
- Design Direction Showcase: [ux-design-directions.html](./ux-design-directions.html)
|
||||
|
||||
---
|
||||
|
||||
## 5. User Journey Flows
|
||||
|
||||
### 5.1 Critical User Paths
|
||||
|
||||
{{user_journey_flows}}
|
||||
|
||||
---
|
||||
|
||||
## 6. Component Library
|
||||
|
||||
### 6.1 Component Strategy
|
||||
|
||||
{{component_library_strategy}}
|
||||
|
||||
---
|
||||
|
||||
## 7. UX Pattern Decisions
|
||||
|
||||
### 7.1 Consistency Rules
|
||||
|
||||
{{ux_pattern_decisions}}
|
||||
|
||||
---
|
||||
|
||||
## 8. Responsive Design & Accessibility
|
||||
|
||||
### 8.1 Responsive Strategy
|
||||
|
||||
{{responsive_accessibility_strategy}}
|
||||
|
||||
---
|
||||
|
||||
## 9. Implementation Guidance
|
||||
|
||||
### 9.1 Completion Summary
|
||||
|
||||
{{completion_summary}}
|
||||
|
||||
---
|
||||
|
||||
## Appendix
|
||||
|
||||
### Related Documents
|
||||
|
||||
- Product Requirements: `{{prd_file}}`
|
||||
- Product Brief: `{{brief_file}}`
|
||||
- Brainstorming: `{{brainstorm_file}}`
|
||||
|
||||
### Core Interactive Deliverables
|
||||
|
||||
This UX Design Specification was created through visual collaboration:
|
||||
|
||||
- **Color Theme Visualizer**: {{color_themes_html}}
|
||||
- Interactive HTML showing all color theme options explored
|
||||
- Live UI component examples in each theme
|
||||
- Side-by-side comparison and semantic color usage
|
||||
|
||||
- **Design Direction Mockups**: {{design_directions_html}}
|
||||
- Interactive HTML with 6-8 complete design approaches
|
||||
- Full-screen mockups of key screens
|
||||
- Design philosophy and rationale for each direction
|
||||
|
||||
### Optional Enhancement Deliverables
|
||||
|
||||
_This section will be populated if additional UX artifacts are generated through follow-up workflows._
|
||||
|
||||
<!-- Additional deliverables added here by other workflows -->
|
||||
|
||||
### Next Steps & Follow-Up Workflows
|
||||
|
||||
This UX Design Specification can serve as input to:
|
||||
|
||||
- **Wireframe Generation Workflow** - Create detailed wireframes from user flows
|
||||
- **Figma Design Workflow** - Generate Figma files via MCP integration
|
||||
- **Interactive Prototype Workflow** - Build clickable HTML prototypes
|
||||
- **Component Showcase Workflow** - Create interactive component library
|
||||
- **AI Frontend Prompt Workflow** - Generate prompts for v0, Lovable, Bolt, etc.
|
||||
- **Solution Architecture Workflow** - Define technical architecture with UX context
|
||||
|
||||
### Version History
|
||||
|
||||
| Date | Version | Changes | Author |
|
||||
| -------- | ------- | ------------------------------- | ------------- |
|
||||
| {{date}} | 1.0 | Initial UX Design Specification | {{user_name}} |
|
||||
|
||||
---
|
||||
|
||||
_This UX Design Specification was created through collaborative design facilitation, not template generation. All decisions were made with user input and are documented with rationale._
|
||||
@@ -0,0 +1,64 @@
|
||||
# Create UX Design Workflow Configuration
|
||||
name: create-ux-design
|
||||
description: "Collaborative UX design facilitation workflow that creates exceptional user experiences through visual exploration and informed decision-making. Unlike template-driven approaches, this workflow facilitates discovery, generates visual options, and collaboratively designs the UX with the user at every step."
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
date: system-generated
|
||||
|
||||
# Input requirements - We work from PRD, Brief, or Brainstorming docs
|
||||
recommended_inputs:
|
||||
- prd: "Product Requirements Document with features and user journeys"
|
||||
- product_brief: "Product brief with vision and target users"
|
||||
- brainstorming: "Brainstorming documents with ideas and concepts"
|
||||
|
||||
# Input file references (fuzzy matched from output folder)
|
||||
prd_file: "{output_folder}/bmm-PRD.md or PRD.md or product-requirements.md"
|
||||
brief_file: "{output_folder}/product-brief.md or brief.md or project-brief.md"
|
||||
brainstorm_file: "{output_folder}/brainstorming.md or brainstorm.md or ideation.md"
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
input_file_patterns:
|
||||
prd:
|
||||
whole: "{output_folder}/*prd*.md"
|
||||
sharded: "{output_folder}/*prd*/index.md"
|
||||
|
||||
product_brief:
|
||||
whole: "{output_folder}/*brief*.md"
|
||||
sharded: "{output_folder}/*brief*/index.md"
|
||||
|
||||
epics:
|
||||
whole: "{output_folder}/*epic*.md"
|
||||
sharded: "{output_folder}/*epic*/index.md"
|
||||
|
||||
brainstorming:
|
||||
whole: "{output_folder}/*brainstorm*.md"
|
||||
sharded: "{output_folder}/*brainstorm*/index.md"
|
||||
|
||||
document_project:
|
||||
sharded: "{output_folder}/docs/index.md"
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
template: "{installed_path}/ux-design-template.md"
|
||||
|
||||
# Knowledge bases for intelligent UX decisions
|
||||
ux_pattern_catalog: "{installed_path}/ux-pattern-catalog.yaml"
|
||||
color_psychology: "{installed_path}/color-psychology.yaml"
|
||||
layout_patterns: "{installed_path}/layout-patterns.yaml"
|
||||
|
||||
# Output configuration - Progressive saves throughout workflow
|
||||
default_output_file: "{output_folder}/ux-design-specification.md"
|
||||
color_themes_html: "{output_folder}/ux-color-themes.html"
|
||||
design_directions_html: "{output_folder}/ux-design-directions.html"
|
||||
|
||||
standalone: true
|
||||
139
bmad/bmm/workflows/2-plan-workflows/narrative/checklist.md
Normal file
139
bmad/bmm/workflows/2-plan-workflows/narrative/checklist.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# Narrative Design Workflow Validation Checklist
|
||||
|
||||
**Purpose**: Validate narrative design outputs are complete, cohesive, and ready for implementation.
|
||||
|
||||
**Scope**: Story-driven games and applications (follows GDD workflow)
|
||||
|
||||
**Expected Output**: narrative-design.md
|
||||
|
||||
---
|
||||
|
||||
## 1. Output File Exists
|
||||
|
||||
- [ ] narrative-design.md created in output folder
|
||||
- [ ] GDD.md exists (narrative workflow requires GDD first)
|
||||
- [ ] No unfilled {{template_variables}}
|
||||
|
||||
---
|
||||
|
||||
## 2. Story Foundation
|
||||
|
||||
### Core Elements
|
||||
|
||||
- [ ] **Narrative premise** clearly stated (elevator pitch, 2-3 sentences)
|
||||
- [ ] **Core themes** identified (2-4 meaningful themes)
|
||||
- [ ] **Tone and atmosphere** established
|
||||
- [ ] Premise is compelling and fits game type
|
||||
|
||||
### Story Structure
|
||||
|
||||
- [ ] **Story structure chosen** (3-act, hero's journey, branching, etc.)
|
||||
- [ ] **Acts/sections broken down** with clear progression
|
||||
- [ ] **Major story beats** documented (key moments that drive narrative)
|
||||
- [ ] Structure fits narrative complexity level
|
||||
|
||||
---
|
||||
|
||||
## 3. Characters
|
||||
|
||||
### Protagonist(s)
|
||||
|
||||
- [ ] Background and motivation explained
|
||||
- [ ] Character arc defined (how they change)
|
||||
- [ ] Internal and external conflicts identified
|
||||
|
||||
### Antagonist(s)
|
||||
|
||||
- [ ] Motivation clear (why they oppose protagonist)
|
||||
- [ ] Goals and methods explained
|
||||
- [ ] Not one-dimensional
|
||||
|
||||
### Supporting Cast
|
||||
|
||||
- [ ] Major supporting characters documented
|
||||
- [ ] Each has distinct role in story
|
||||
- [ ] Character relationships mapped
|
||||
|
||||
### Character Arcs
|
||||
|
||||
- [ ] Major characters have starting → transformation → ending states
|
||||
- [ ] Arc progression makes sense
|
||||
|
||||
---
|
||||
|
||||
## 4. World and Lore
|
||||
|
||||
- [ ] **World setting** defined (time, place, world type)
|
||||
- [ ] **World rules** explained (magic, technology, society)
|
||||
- [ ] **History and backstory** documented
|
||||
- [ ] Key locations described with narrative significance
|
||||
|
||||
---
|
||||
|
||||
## 5. Dialogue and Delivery
|
||||
|
||||
### Dialogue Framework
|
||||
|
||||
- [ ] Dialogue style established
|
||||
- [ ] Key conversations identified
|
||||
- [ ] Branching dialogue system described (if applicable)
|
||||
|
||||
### Narrative Delivery
|
||||
|
||||
- [ ] Cutscenes/cinematics approach defined
|
||||
- [ ] In-game storytelling methods explained
|
||||
- [ ] Optional vs. required content distinguished
|
||||
- [ ] Multiple endings documented (if applicable)
|
||||
|
||||
---
|
||||
|
||||
## 6. Gameplay Integration
|
||||
|
||||
- [ ] **Narrative-gameplay harmony** addressed (how story and mechanics connect)
|
||||
- [ ] **Story gates** explained (how narrative controls progression)
|
||||
- [ ] **Player agency** level defined (can player affect story?)
|
||||
- [ ] Integration doesn't fight game design
|
||||
|
||||
---
|
||||
|
||||
## 7. Production Scope
|
||||
|
||||
- [ ] **Writing scope** estimated (word count, scene count, dialogue lines)
|
||||
- [ ] Scope realistic for project level
|
||||
- [ ] Localization considerations noted (if applicable)
|
||||
- [ ] Voice acting plans documented (if applicable)
|
||||
|
||||
---
|
||||
|
||||
## 8. Consistency with GDD
|
||||
|
||||
- [ ] Narrative aligns with GDD game design
|
||||
- [ ] Tone matches GDD art/audio direction
|
||||
- [ ] Story supports game mechanics (doesn't contradict)
|
||||
- [ ] No conflicts between narrative and gameplay
|
||||
|
||||
---
|
||||
|
||||
## 9. Critical Failures (Auto-Fail)
|
||||
|
||||
- [ ] ❌ **No GDD** (narrative workflow requires GDD first)
|
||||
- [ ] ❌ **No character arcs** (protagonist has no development)
|
||||
- [ ] ❌ **No story beats** (major moments not identified)
|
||||
- [ ] ❌ **Contradicts GDD** (narrative fights game design)
|
||||
|
||||
---
|
||||
|
||||
## Validation Notes
|
||||
|
||||
**Document any findings:**
|
||||
|
||||
- Narrative strength: [Compelling / Interesting / Adequate / Weak]
|
||||
- Strengths:
|
||||
- Issues to address:
|
||||
- Recommended actions:
|
||||
|
||||
**Ready for solutioning?** [Yes / No - explain]
|
||||
|
||||
---
|
||||
|
||||
_Adapt based on narrative complexity level (Critical/Heavy/Moderate/Light)._
|
||||
@@ -0,0 +1,608 @@
|
||||
# Narrative Design Workflow
|
||||
|
||||
<workflow>
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already completed the GDD workflow</critical>
|
||||
<critical>Communicate all responses in {communication_language}</critical>
|
||||
<critical>This workflow creates detailed narrative content for story-driven games</critical>
|
||||
<critical>Uses narrative_template for output</critical>
|
||||
<critical>If users mention gameplay mechanics, note them but keep focus on narrative</critical>
|
||||
<critical>Facilitate good brainstorming techniques throughout with the user, pushing them to come up with much of the narrative you will help weave together. The goal is for the user to feel that they crafted the narrative and story arc unless they push you to do it all or indicate YOLO</critical>
|
||||
|
||||
<step n="0" goal="Check for workflow status" tag="workflow-status">
|
||||
<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
|
||||
|
||||
<check if="status file not found">
|
||||
<output>No workflow status file found. Narrative workflow is optional - you can continue without status tracking.</output>
|
||||
<action>Set standalone_mode = true</action>
|
||||
</check>
|
||||
|
||||
<check if="status file found">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Parse workflow_status section</action>
|
||||
<action>Check status of "narrative" workflow</action>
|
||||
<action>Get project_level from YAML metadata</action>
|
||||
<action>Find first non-completed workflow (next expected workflow)</action>
|
||||
|
||||
<check if="narrative status is file path (already completed)">
|
||||
<output>⚠️ Narrative Design Document already completed: {{narrative status}}</output>
|
||||
<ask>Re-running will overwrite the existing narrative document. Continue? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Use workflow-status to see your next step.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="narrative is not the next expected workflow (latter items are completed already in the list)">
|
||||
<output>⚠️ Next expected workflow: {{next_workflow}}. Narrative is out of sequence.</output>
|
||||
<ask>Continue with Narrative Design anyway? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Run {{next_workflow}} instead.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Set standalone_mode = false</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Load GDD context and assess narrative complexity">
|
||||
|
||||
<action>Load GDD.md from {output_folder}</action>
|
||||
<action>Extract game_type, game_name, and any narrative mentions</action>
|
||||
|
||||
<ask>What level of narrative complexity does your game have?
|
||||
|
||||
**Narrative Complexity:**
|
||||
|
||||
1. **Critical** - Story IS the game (Visual Novel, Text-Based Adventure)
|
||||
2. **Heavy** - Story drives the experience (Story-driven RPG, Narrative Adventure)
|
||||
3. **Moderate** - Story enhances gameplay (Metroidvania, Tactics RPG, Horror)
|
||||
4. **Light** - Story provides context (most other genres)
|
||||
|
||||
Your game type ({{game_type}}) suggests **{{suggested_complexity}}**. Confirm or adjust:</ask>
|
||||
|
||||
<action>Set narrative_complexity</action>
|
||||
|
||||
<check if="complexity == Light">
|
||||
<ask>Light narrative games usually don't need a full Narrative Design Document. Are you sure you want to continue?
|
||||
|
||||
- GDD story sections may be sufficient
|
||||
- Consider just expanding GDD narrative notes
|
||||
- Proceed with full narrative workflow
|
||||
|
||||
Your choice:</ask>
|
||||
|
||||
<action>Load narrative_template from workflow.yaml</action>
|
||||
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Define narrative premise and themes">
|
||||
|
||||
<ask>Describe your narrative premise in 2-3 sentences.
|
||||
|
||||
This is the "elevator pitch" of your story.
|
||||
|
||||
Examples:
|
||||
|
||||
- "A young knight discovers they're the last hope to stop an ancient evil, but must choose between saving the kingdom or their own family."
|
||||
- "After a mysterious pandemic, survivors must navigate a world where telling the truth is deadly but lying corrupts your soul."
|
||||
|
||||
Your premise:</ask>
|
||||
|
||||
<template-output>narrative_premise</template-output>
|
||||
|
||||
<ask>What are the core themes of your narrative? (2-4 themes)
|
||||
|
||||
Themes are the underlying ideas/messages.
|
||||
|
||||
Examples: redemption, sacrifice, identity, corruption, hope vs. despair, nature vs. technology
|
||||
|
||||
Your themes:</ask>
|
||||
|
||||
<template-output>core_themes</template-output>
|
||||
|
||||
<ask>Describe the tone and atmosphere.
|
||||
|
||||
Consider: dark, hopeful, comedic, melancholic, mysterious, epic, intimate, etc.
|
||||
|
||||
Your tone:</ask>
|
||||
|
||||
<template-output>tone_atmosphere</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Define story structure">
|
||||
|
||||
<ask>What story structure are you using?
|
||||
|
||||
Common structures:
|
||||
|
||||
- **3-Act** (Setup, Confrontation, Resolution)
|
||||
- **Hero's Journey** (Campbell's monomyth)
|
||||
- **Kishōtenketsu** (4-act: Introduction, Development, Twist, Conclusion)
|
||||
- **Episodic** (Self-contained episodes with arc)
|
||||
- **Branching** (Multiple paths and endings)
|
||||
- **Freeform** (Player-driven narrative)
|
||||
|
||||
Your structure:</ask>
|
||||
|
||||
<template-output>story_type</template-output>
|
||||
|
||||
<ask>Break down your story into acts/sections.
|
||||
|
||||
For 3-Act:
|
||||
|
||||
- Act 1: Setup and inciting incident
|
||||
- Act 2: Rising action and midpoint
|
||||
- Act 3: Climax and resolution
|
||||
|
||||
Describe each act/section for your game:</ask>
|
||||
|
||||
<template-output>act_breakdown</template-output>
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Define major story beats">
|
||||
|
||||
<ask>List the major story beats (10-20 key moments).
|
||||
|
||||
Story beats are significant events that drive the narrative forward.
|
||||
|
||||
Format:
|
||||
|
||||
1. [Beat name] - Brief description
|
||||
2. [Beat name] - Brief description
|
||||
...
|
||||
|
||||
Your story beats:</ask>
|
||||
|
||||
<template-output>story_beats</template-output>
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
<ask>Describe the pacing and flow of your narrative.
|
||||
|
||||
Consider:
|
||||
|
||||
- Slow burn vs. fast-paced
|
||||
- Tension/release rhythm
|
||||
- Story-heavy vs. gameplay-heavy sections
|
||||
- Optional vs. required narrative content
|
||||
|
||||
Your pacing:</ask>
|
||||
|
||||
<template-output>pacing_flow</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Develop protagonist(s)">
|
||||
|
||||
<ask>Describe your protagonist(s).
|
||||
|
||||
For each protagonist include:
|
||||
|
||||
- Name and brief description
|
||||
- Background and motivation
|
||||
- Character arc (how they change)
|
||||
- Strengths and flaws
|
||||
- Relationships to other characters
|
||||
- Internal and external conflicts
|
||||
|
||||
Your protagonist(s):</ask>
|
||||
|
||||
<template-output>protagonists</template-output>
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Develop antagonist(s)">
|
||||
|
||||
<ask>Describe your antagonist(s).
|
||||
|
||||
For each antagonist include:
|
||||
|
||||
- Name and brief description
|
||||
- Background and motivation
|
||||
- Goals (what they want)
|
||||
- Methods (how they pursue goals)
|
||||
- Relationship to protagonist
|
||||
- Sympathetic elements (if any)
|
||||
|
||||
Your antagonist(s):</ask>
|
||||
|
||||
<template-output>antagonists</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Develop supporting characters">
|
||||
|
||||
<ask>Describe supporting characters (allies, mentors, companions, NPCs).
|
||||
|
||||
For each character include:
|
||||
|
||||
- Name and role
|
||||
- Personality and traits
|
||||
- Relationship to protagonist
|
||||
- Function in story (mentor, foil, comic relief, etc.)
|
||||
- Key scenes/moments
|
||||
|
||||
Your supporting characters:</ask>
|
||||
|
||||
<template-output>supporting_characters</template-output>
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Map character arcs">
|
||||
|
||||
<ask>Describe the character arcs for major characters.
|
||||
|
||||
Character arc: How does the character change from beginning to end?
|
||||
|
||||
For each arc:
|
||||
|
||||
- Starting state
|
||||
- Key transformation moments
|
||||
- Ending state
|
||||
- Lessons learned
|
||||
|
||||
Your character arcs:</ask>
|
||||
|
||||
<template-output>character_arcs</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Build world and lore">
|
||||
|
||||
<ask>Describe your world.
|
||||
|
||||
Include:
|
||||
|
||||
- Setting (time period, location, world type)
|
||||
- World rules (magic systems, technology level, societal norms)
|
||||
- Atmosphere and aesthetics
|
||||
- What makes this world unique
|
||||
|
||||
Your world:</ask>
|
||||
|
||||
<template-output>world_overview</template-output>
|
||||
|
||||
<ask>What is the history and backstory of your world?
|
||||
|
||||
- Major historical events
|
||||
- How did the world reach its current state?
|
||||
- Legends and myths
|
||||
- Past conflicts
|
||||
|
||||
Your history:</ask>
|
||||
|
||||
<template-output>history_backstory</template-output>
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Define factions and locations">
|
||||
|
||||
<ask optional="true">Describe factions, organizations, or groups (if applicable).
|
||||
|
||||
For each:
|
||||
|
||||
- Name and purpose
|
||||
- Leadership and structure
|
||||
- Goals and methods
|
||||
- Relationships with other factions
|
||||
|
||||
Your factions:</ask>
|
||||
|
||||
<template-output>factions_organizations</template-output>
|
||||
|
||||
<ask>Describe key locations in your world.
|
||||
|
||||
For each location:
|
||||
|
||||
- Name and description
|
||||
- Narrative significance
|
||||
- Atmosphere and mood
|
||||
- Key events that occur there
|
||||
|
||||
Your locations:</ask>
|
||||
|
||||
<template-output>locations</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="11" goal="Define dialogue framework">
|
||||
|
||||
<ask>Describe your dialogue style.
|
||||
|
||||
Consider:
|
||||
|
||||
- Formal vs. casual
|
||||
- Period-appropriate vs. modern
|
||||
- Verbose vs. concise
|
||||
- Humor level
|
||||
- Profanity/mature language
|
||||
|
||||
Your dialogue style:</ask>
|
||||
|
||||
<template-output>dialogue_style</template-output>
|
||||
|
||||
<ask>List key conversations/dialogue moments.
|
||||
|
||||
Include:
|
||||
|
||||
- Who is involved
|
||||
- When it occurs
|
||||
- What's discussed
|
||||
- Narrative purpose
|
||||
- Emotional tone
|
||||
|
||||
Your key conversations:</ask>
|
||||
|
||||
<template-output>key_conversations</template-output>
|
||||
|
||||
<check if="game has branching dialogue">
|
||||
<ask>Describe your branching dialogue system.
|
||||
|
||||
- How many branches/paths?
|
||||
- What determines branches? (stats, choices, flags)
|
||||
- Do branches converge?
|
||||
- How much unique dialogue?
|
||||
|
||||
Your branching system:</ask>
|
||||
|
||||
<template-output>branching_dialogue</template-output>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="12" goal="Environmental storytelling">
|
||||
|
||||
<ask>How will you tell story through the environment?
|
||||
|
||||
Visual storytelling:
|
||||
|
||||
- Set dressing and props
|
||||
- Environmental damage/aftermath
|
||||
- Visual symbolism
|
||||
- Color and lighting
|
||||
|
||||
Your visual storytelling:</ask>
|
||||
|
||||
<template-output>visual_storytelling</template-output>
|
||||
|
||||
<ask>How will audio contribute to storytelling?
|
||||
|
||||
- Ambient sounds
|
||||
- Music emotional cues
|
||||
- Voice acting
|
||||
- Audio logs/recordings
|
||||
|
||||
Your audio storytelling:</ask>
|
||||
|
||||
<template-output>audio_storytelling</template-output>
|
||||
|
||||
<ask optional="true">Will you have found documents (journals, notes, emails)?
|
||||
|
||||
If yes, describe:
|
||||
|
||||
- Types of documents
|
||||
- How many
|
||||
- What they reveal
|
||||
- Optional vs. required reading
|
||||
|
||||
Your found documents:</ask>
|
||||
|
||||
<template-output>found_documents</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="13" goal="Narrative delivery methods">
|
||||
|
||||
<ask>How will you deliver narrative content?
|
||||
|
||||
**Cutscenes/Cinematics:**
|
||||
|
||||
- How many?
|
||||
- Skippable?
|
||||
- Real-time or pre-rendered?
|
||||
- Average length
|
||||
|
||||
Your cutscenes:</ask>
|
||||
|
||||
<template-output>cutscenes</template-output>
|
||||
|
||||
<ask>How will you deliver story during gameplay?
|
||||
|
||||
- NPC conversations
|
||||
- Radio/comm chatter
|
||||
- Environmental cues
|
||||
- Player actions
|
||||
- Show vs. tell balance
|
||||
|
||||
Your in-game storytelling:</ask>
|
||||
|
||||
<template-output>ingame_storytelling</template-output>
|
||||
|
||||
<ask>What narrative content is optional?
|
||||
|
||||
- Side quests
|
||||
- Collectible lore
|
||||
- Optional conversations
|
||||
- Secret endings
|
||||
|
||||
Your optional content:</ask>
|
||||
|
||||
<template-output>optional_content</template-output>
|
||||
|
||||
<check if="multiple endings">
|
||||
<ask>Describe your ending structure.
|
||||
|
||||
- How many endings?
|
||||
- What determines ending? (choices, stats, completion)
|
||||
- Ending variety (minor variations vs. drastically different)
|
||||
- True/golden ending?
|
||||
|
||||
Your endings:</ask>
|
||||
|
||||
<template-output>multiple_endings</template-output>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="14" goal="Gameplay integration">
|
||||
|
||||
<ask>How does narrative integrate with gameplay?
|
||||
|
||||
- Does story unlock mechanics?
|
||||
- Do mechanics reflect themes?
|
||||
- Ludonarrative harmony or dissonance?
|
||||
- Balance of story vs. gameplay
|
||||
|
||||
Your narrative-gameplay integration:</ask>
|
||||
|
||||
<template-output>narrative_gameplay</template-output>
|
||||
|
||||
<ask>How does story gate progression?
|
||||
|
||||
- Story-locked areas
|
||||
- Cutscene triggers
|
||||
- Mandatory story beats
|
||||
- Optional vs. required narrative
|
||||
|
||||
Your story gates:</ask>
|
||||
|
||||
<template-output>story_gates</template-output>
|
||||
|
||||
<ask>How much agency does the player have?
|
||||
|
||||
- Can player affect story?
|
||||
- Meaningful choices?
|
||||
- Role-playing freedom?
|
||||
- Predetermined vs. dynamic narrative
|
||||
|
||||
Your player agency:</ask>
|
||||
|
||||
<template-output>player_agency</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="15" goal="Production planning">
|
||||
|
||||
<ask>Estimate your writing scope.
|
||||
|
||||
- Word count estimate
|
||||
- Number of scenes/chapters
|
||||
- Dialogue lines estimate
|
||||
- Branching complexity
|
||||
|
||||
Your scope:</ask>
|
||||
|
||||
<template-output>writing_scope</template-output>
|
||||
|
||||
<ask>Localization considerations?
|
||||
|
||||
- Target languages
|
||||
- Cultural adaptation needs
|
||||
- Text expansion concerns
|
||||
- Dialogue recording implications
|
||||
|
||||
Your localization:</ask>
|
||||
|
||||
<template-output>localization</template-output>
|
||||
|
||||
<ask>Voice acting plans?
|
||||
|
||||
- Fully voiced, partially voiced, or text-only?
|
||||
- Number of characters needing voices
|
||||
- Dialogue volume
|
||||
- Budget considerations
|
||||
|
||||
Your voice acting:</ask>
|
||||
|
||||
<template-output>voice_acting</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="16" goal="Completion and next steps">
|
||||
|
||||
<action>Generate character relationship map (text-based diagram)</action>
|
||||
<template-output>relationship_map</template-output>
|
||||
|
||||
<action>Generate story timeline</action>
|
||||
<template-output>timeline</template-output>
|
||||
|
||||
<ask optional="true">Any references or inspirations to note?
|
||||
|
||||
- Books, movies, games that inspired you
|
||||
- Reference materials
|
||||
- Tone/theme references
|
||||
|
||||
Your references:</ask>
|
||||
|
||||
<template-output>references</template-output>
|
||||
|
||||
<ask>**✅ Narrative Design Complete, {user_name}!**
|
||||
|
||||
Next steps:
|
||||
|
||||
1. Proceed to solutioning (technical architecture)
|
||||
2. Create detailed script/screenplay (outside workflow)
|
||||
3. Review narrative with team/stakeholders
|
||||
4. Exit workflow
|
||||
|
||||
Which would you like?</ask>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="17" goal="Update status if tracking enabled" tag="workflow-status">
|
||||
|
||||
<check if="standalone_mode != true">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Find workflow_status key "narrative"</action>
|
||||
<critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
|
||||
<action>Update workflow_status["narrative"] = "{output_folder}/bmm-narrative-{{game_name}}-{{date}}.md"</action>
|
||||
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||
|
||||
<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
|
||||
<action>Determine next agent from path file based on next workflow</action>
|
||||
</check>
|
||||
|
||||
<output>**✅ Narrative Design Complete, {user_name}!**
|
||||
|
||||
**Narrative Document:**
|
||||
|
||||
- Narrative design saved to {output_folder}/bmm-narrative-{{game_name}}-{{date}}.md
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
**Status Updated:**
|
||||
|
||||
- Progress tracking updated: narrative marked complete
|
||||
- Next workflow: {{next_workflow}}
|
||||
{{else}}
|
||||
**Note:** Running in standalone mode (no progress tracking)
|
||||
{{/if}}
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
|
||||
- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
|
||||
- **Optional:** Review narrative with writing team or stakeholders
|
||||
|
||||
Check status anytime with: `workflow-status`
|
||||
{{else}}
|
||||
Since no workflow is in progress:
|
||||
|
||||
- Review narrative design with team
|
||||
- Refer to the BMM workflow guide if unsure what to do next
|
||||
- Or run `workflow-init` to create a workflow path and get guided next steps
|
||||
{{/if}}
|
||||
</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
@@ -0,0 +1,195 @@
|
||||
# {{game_name}} - Narrative Design Document
|
||||
|
||||
**Author:** {{user_name}}
|
||||
**Game Type:** {{game_type}}
|
||||
**Narrative Complexity:** {{narrative_complexity}}
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
### Narrative Premise
|
||||
|
||||
{{narrative_premise}}
|
||||
|
||||
### Core Themes
|
||||
|
||||
{{core_themes}}
|
||||
|
||||
### Tone and Atmosphere
|
||||
|
||||
{{tone_atmosphere}}
|
||||
|
||||
---
|
||||
|
||||
## Story Structure
|
||||
|
||||
### Story Type
|
||||
|
||||
{{story_type}}
|
||||
|
||||
**Structure used:** (3-act, hero's journey, kishōtenketsu, episodic, branching, etc.)
|
||||
|
||||
### Act Breakdown
|
||||
|
||||
{{act_breakdown}}
|
||||
|
||||
### Story Beats
|
||||
|
||||
{{story_beats}}
|
||||
|
||||
### Pacing and Flow
|
||||
|
||||
{{pacing_flow}}
|
||||
|
||||
---
|
||||
|
||||
## Characters
|
||||
|
||||
### Protagonist(s)
|
||||
|
||||
{{protagonists}}
|
||||
|
||||
### Antagonist(s)
|
||||
|
||||
{{antagonists}}
|
||||
|
||||
### Supporting Characters
|
||||
|
||||
{{supporting_characters}}
|
||||
|
||||
### Character Arcs
|
||||
|
||||
{{character_arcs}}
|
||||
|
||||
---
|
||||
|
||||
## World and Lore
|
||||
|
||||
### World Overview
|
||||
|
||||
{{world_overview}}
|
||||
|
||||
### History and Backstory
|
||||
|
||||
{{history_backstory}}
|
||||
|
||||
### Factions and Organizations
|
||||
|
||||
{{factions_organizations}}
|
||||
|
||||
### Locations
|
||||
|
||||
{{locations}}
|
||||
|
||||
### Cultural Elements
|
||||
|
||||
{{cultural_elements}}
|
||||
|
||||
---
|
||||
|
||||
## Dialogue Framework
|
||||
|
||||
### Dialogue Style
|
||||
|
||||
{{dialogue_style}}
|
||||
|
||||
### Key Conversations
|
||||
|
||||
{{key_conversations}}
|
||||
|
||||
### Branching Dialogue
|
||||
|
||||
{{branching_dialogue}}
|
||||
|
||||
### Voice and Characterization
|
||||
|
||||
{{voice_characterization}}
|
||||
|
||||
---
|
||||
|
||||
## Environmental Storytelling
|
||||
|
||||
### Visual Storytelling
|
||||
|
||||
{{visual_storytelling}}
|
||||
|
||||
### Audio Storytelling
|
||||
|
||||
{{audio_storytelling}}
|
||||
|
||||
### Found Documents
|
||||
|
||||
{{found_documents}}
|
||||
|
||||
### Environmental Clues
|
||||
|
||||
{{environmental_clues}}
|
||||
|
||||
---
|
||||
|
||||
## Narrative Delivery
|
||||
|
||||
### Cutscenes and Cinematics
|
||||
|
||||
{{cutscenes}}
|
||||
|
||||
### In-Game Storytelling
|
||||
|
||||
{{ingame_storytelling}}
|
||||
|
||||
### Optional Content
|
||||
|
||||
{{optional_content}}
|
||||
|
||||
### Multiple Endings
|
||||
|
||||
{{multiple_endings}}
|
||||
|
||||
---
|
||||
|
||||
## Integration with Gameplay
|
||||
|
||||
### Narrative-Gameplay Harmony
|
||||
|
||||
{{narrative_gameplay}}
|
||||
|
||||
### Story Gates
|
||||
|
||||
{{story_gates}}
|
||||
|
||||
### Player Agency
|
||||
|
||||
{{player_agency}}
|
||||
|
||||
---
|
||||
|
||||
## Production Notes
|
||||
|
||||
### Writing Scope
|
||||
|
||||
{{writing_scope}}
|
||||
|
||||
### Localization Considerations
|
||||
|
||||
{{localization}}
|
||||
|
||||
### Voice Acting
|
||||
|
||||
{{voice_acting}}
|
||||
|
||||
---
|
||||
|
||||
## Appendix
|
||||
|
||||
### Character Relationship Map
|
||||
|
||||
{{relationship_map}}
|
||||
|
||||
### Timeline
|
||||
|
||||
{{timeline}}
|
||||
|
||||
### References and Inspirations
|
||||
|
||||
{{references}}
|
||||
29
bmad/bmm/workflows/2-plan-workflows/narrative/workflow.yaml
Normal file
29
bmad/bmm/workflows/2-plan-workflows/narrative/workflow.yaml
Normal file
@@ -0,0 +1,29 @@
|
||||
# Narrative Design Workflow
|
||||
name: narrative
|
||||
description: "Narrative design workflow for story-driven games and applications. Creates comprehensive narrative documentation including story structure, character arcs, dialogue systems, and narrative implementation guidance."
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
date: system-generated
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/narrative"
|
||||
instructions: "{installed_path}/instructions-narrative.md"
|
||||
template: "{installed_path}/narrative-template.md"
|
||||
|
||||
# Output configuration
|
||||
default_output_file: "{output_folder}/narrative-design.md"
|
||||
|
||||
# Recommended input documents
|
||||
recommended_inputs:
|
||||
- game_brief: "{output_folder}/game-brief.md"
|
||||
- gdd: "{output_folder}/GDD.md"
|
||||
- product_brief: "{output_folder}/product-brief.md"
|
||||
|
||||
standalone: true
|
||||
349
bmad/bmm/workflows/2-plan-workflows/prd/checklist.md
Normal file
349
bmad/bmm/workflows/2-plan-workflows/prd/checklist.md
Normal file
@@ -0,0 +1,349 @@
|
||||
# PRD + Epics + Stories Validation Checklist
|
||||
|
||||
**Purpose**: Comprehensive validation that PRD, epics, and stories form a complete, implementable product plan.
|
||||
|
||||
**Scope**: Validates the complete planning output (PRD.md + epics.md) for Levels 2-4 software projects
|
||||
|
||||
**Expected Outputs**:
|
||||
|
||||
- PRD.md with complete requirements
|
||||
- epics.md with detailed epic and story breakdown
|
||||
- Updated bmm-workflow-status.yaml
|
||||
|
||||
---
|
||||
|
||||
## 1. PRD Document Completeness
|
||||
|
||||
### Core Sections Present
|
||||
|
||||
- [ ] Executive Summary with vision alignment
|
||||
- [ ] Product magic essence clearly articulated
|
||||
- [ ] Project classification (type, domain, complexity)
|
||||
- [ ] Success criteria defined
|
||||
- [ ] Product scope (MVP, Growth, Vision) clearly delineated
|
||||
- [ ] Functional requirements comprehensive and numbered
|
||||
- [ ] Non-functional requirements (when applicable)
|
||||
- [ ] References section with source documents
|
||||
|
||||
### Project-Specific Sections
|
||||
|
||||
- [ ] **If complex domain:** Domain context and considerations documented
|
||||
- [ ] **If innovation:** Innovation patterns and validation approach documented
|
||||
- [ ] **If API/Backend:** Endpoint specification and authentication model included
|
||||
- [ ] **If Mobile:** Platform requirements and device features documented
|
||||
- [ ] **If SaaS B2B:** Tenant model and permission matrix included
|
||||
- [ ] **If UI exists:** UX principles and key interactions documented
|
||||
|
||||
### Quality Checks
|
||||
|
||||
- [ ] No unfilled template variables ({{variable}})
|
||||
- [ ] All variables properly populated with meaningful content
|
||||
- [ ] Product magic woven throughout (not just stated once)
|
||||
- [ ] Language is clear, specific, and measurable
|
||||
- [ ] Project type correctly identified and sections match
|
||||
- [ ] Domain complexity appropriately addressed
|
||||
|
||||
---
|
||||
|
||||
## 2. Functional Requirements Quality
|
||||
|
||||
### FR Format and Structure
|
||||
|
||||
- [ ] Each FR has unique identifier (FR-001, FR-002, etc.)
|
||||
- [ ] FRs describe WHAT capabilities, not HOW to implement
|
||||
- [ ] FRs are specific and measurable
|
||||
- [ ] FRs are testable and verifiable
|
||||
- [ ] FRs focus on user/business value
|
||||
- [ ] No technical implementation details in FRs (those belong in architecture)
|
||||
|
||||
### FR Completeness
|
||||
|
||||
- [ ] All MVP scope features have corresponding FRs
|
||||
- [ ] Growth features documented (even if deferred)
|
||||
- [ ] Vision features captured for future reference
|
||||
- [ ] Domain-mandated requirements included
|
||||
- [ ] Innovation requirements captured with validation needs
|
||||
- [ ] Project-type specific requirements complete
|
||||
|
||||
### FR Organization
|
||||
|
||||
- [ ] FRs organized by capability/feature area (not by tech stack)
|
||||
- [ ] Related FRs grouped logically
|
||||
- [ ] Dependencies between FRs noted when critical
|
||||
- [ ] Priority/phase indicated (MVP vs Growth vs Vision)
|
||||
|
||||
---
|
||||
|
||||
## 3. Epics Document Completeness
|
||||
|
||||
### Required Files
|
||||
|
||||
- [ ] epics.md exists in output folder
|
||||
- [ ] Epic list in PRD.md matches epics in epics.md (titles and count)
|
||||
- [ ] All epics have detailed breakdown sections
|
||||
|
||||
### Epic Quality
|
||||
|
||||
- [ ] Each epic has clear goal and value proposition
|
||||
- [ ] Each epic includes complete story breakdown
|
||||
- [ ] Stories follow proper user story format: "As a [role], I want [goal], so that [benefit]"
|
||||
- [ ] Each story has numbered acceptance criteria
|
||||
- [ ] Prerequisites/dependencies explicitly stated per story
|
||||
- [ ] Stories are AI-agent sized (completable in 2-4 hour session)
|
||||
|
||||
---
|
||||
|
||||
## 4. FR Coverage Validation (CRITICAL)
|
||||
|
||||
### Complete Traceability
|
||||
|
||||
- [ ] **Every FR from PRD.md is covered by at least one story in epics.md**
|
||||
- [ ] Each story references relevant FR numbers
|
||||
- [ ] No orphaned FRs (requirements without stories)
|
||||
- [ ] No orphaned stories (stories without FR connection)
|
||||
- [ ] Coverage matrix verified (can trace FR → Epic → Stories)
|
||||
|
||||
### Coverage Quality
|
||||
|
||||
- [ ] Stories sufficiently decompose FRs into implementable units
|
||||
- [ ] Complex FRs broken into multiple stories appropriately
|
||||
- [ ] Simple FRs have appropriately scoped single stories
|
||||
- [ ] Non-functional requirements reflected in story acceptance criteria
|
||||
- [ ] Domain requirements embedded in relevant stories
|
||||
|
||||
---
|
||||
|
||||
## 5. Story Sequencing Validation (CRITICAL)
|
||||
|
||||
### Epic 1 Foundation Check
|
||||
|
||||
- [ ] **Epic 1 establishes foundational infrastructure**
|
||||
- [ ] Epic 1 delivers initial deployable functionality
|
||||
- [ ] Epic 1 creates baseline for subsequent epics
|
||||
- [ ] Exception: If adding to existing app, foundation requirement adapted appropriately
|
||||
|
||||
### Vertical Slicing
|
||||
|
||||
- [ ] **Each story delivers complete, testable functionality** (not horizontal layers)
|
||||
- [ ] No "build database" or "create UI" stories in isolation
|
||||
- [ ] Stories integrate across stack (data + logic + presentation when applicable)
|
||||
- [ ] Each story leaves system in working/deployable state
|
||||
|
||||
### No Forward Dependencies
|
||||
|
||||
- [ ] **No story depends on work from a LATER story or epic**
|
||||
- [ ] Stories within each epic are sequentially ordered
|
||||
- [ ] Each story builds only on previous work
|
||||
- [ ] Dependencies flow backward only (can reference earlier stories)
|
||||
- [ ] Parallel tracks clearly indicated if stories are independent
|
||||
|
||||
### Value Delivery Path
|
||||
|
||||
- [ ] Each epic delivers significant end-to-end value
|
||||
- [ ] Epic sequence shows logical product evolution
|
||||
- [ ] User can see value after each epic completion
|
||||
- [ ] MVP scope clearly achieved by end of designated epics
|
||||
|
||||
---
|
||||
|
||||
## 6. Scope Management
|
||||
|
||||
### MVP Discipline
|
||||
|
||||
- [ ] MVP scope is genuinely minimal and viable
|
||||
- [ ] Core features list contains only true must-haves
|
||||
- [ ] Each MVP feature has clear rationale for inclusion
|
||||
- [ ] No obvious scope creep in "must-have" list
|
||||
|
||||
### Future Work Captured
|
||||
|
||||
- [ ] Growth features documented for post-MVP
|
||||
- [ ] Vision features captured to maintain long-term direction
|
||||
- [ ] Out-of-scope items explicitly listed
|
||||
- [ ] Deferred features have clear reasoning for deferral
|
||||
|
||||
### Clear Boundaries
|
||||
|
||||
- [ ] Stories marked as MVP vs Growth vs Vision
|
||||
- [ ] Epic sequencing aligns with MVP → Growth progression
|
||||
- [ ] No confusion about what's in vs out of initial scope
|
||||
|
||||
---
|
||||
|
||||
## 7. Research and Context Integration
|
||||
|
||||
### Source Document Integration
|
||||
|
||||
- [ ] **If product brief exists:** Key insights incorporated into PRD
|
||||
- [ ] **If domain brief exists:** Domain requirements reflected in FRs and stories
|
||||
- [ ] **If research documents exist:** Research findings inform requirements
|
||||
- [ ] **If competitive analysis exists:** Differentiation strategy clear in PRD
|
||||
- [ ] All source documents referenced in PRD References section
|
||||
|
||||
### Research Continuity to Architecture
|
||||
|
||||
- [ ] Domain complexity considerations documented for architects
|
||||
- [ ] Technical constraints from research captured
|
||||
- [ ] Regulatory/compliance requirements clearly stated
|
||||
- [ ] Integration requirements with existing systems documented
|
||||
- [ ] Performance/scale requirements informed by research data
|
||||
|
||||
### Information Completeness for Next Phase
|
||||
|
||||
- [ ] PRD provides sufficient context for architecture decisions
|
||||
- [ ] Epics provide sufficient detail for technical design
|
||||
- [ ] Stories have enough acceptance criteria for implementation
|
||||
- [ ] Non-obvious business rules documented
|
||||
- [ ] Edge cases and special scenarios captured
|
||||
|
||||
---
|
||||
|
||||
## 8. Cross-Document Consistency
|
||||
|
||||
### Terminology Consistency
|
||||
|
||||
- [ ] Same terms used across PRD and epics for concepts
|
||||
- [ ] Feature names consistent between documents
|
||||
- [ ] Epic titles match between PRD and epics.md
|
||||
- [ ] No contradictions between PRD and epics
|
||||
|
||||
### Alignment Checks
|
||||
|
||||
- [ ] Success metrics in PRD align with story outcomes
|
||||
- [ ] Product magic articulated in PRD reflected in epic goals
|
||||
- [ ] Technical preferences in PRD align with story implementation hints
|
||||
- [ ] Scope boundaries consistent across all documents
|
||||
|
||||
---
|
||||
|
||||
## 9. Readiness for Implementation
|
||||
|
||||
### Architecture Readiness (Next Phase)
|
||||
|
||||
- [ ] PRD provides sufficient context for architecture workflow
|
||||
- [ ] Technical constraints and preferences documented
|
||||
- [ ] Integration points identified
|
||||
- [ ] Performance/scale requirements specified
|
||||
- [ ] Security and compliance needs clear
|
||||
|
||||
### Development Readiness
|
||||
|
||||
- [ ] Stories are specific enough to estimate
|
||||
- [ ] Acceptance criteria are testable
|
||||
- [ ] Technical unknowns identified and flagged
|
||||
- [ ] Dependencies on external systems documented
|
||||
- [ ] Data requirements specified
|
||||
|
||||
### Level-Appropriate Detail
|
||||
|
||||
**If Level 2:**
|
||||
|
||||
- [ ] PRD supports lightweight tech-spec workflow
|
||||
- [ ] 5-15 story scope reasonable for project size
|
||||
- [ ] Complexity appropriate for small team/solo dev
|
||||
|
||||
**If Level 3-4:**
|
||||
|
||||
- [ ] PRD supports full architecture workflow
|
||||
- [ ] Epic structure supports phased delivery
|
||||
- [ ] Scope appropriate for team-based development
|
||||
- [ ] Clear value delivery through epic sequence
|
||||
|
||||
---
|
||||
|
||||
## 10. Quality and Polish
|
||||
|
||||
### Writing Quality
|
||||
|
||||
- [ ] Language is clear and free of jargon (or jargon is defined)
|
||||
- [ ] Sentences are concise and specific
|
||||
- [ ] No vague statements ("should be fast", "user-friendly")
|
||||
- [ ] Measurable criteria used throughout
|
||||
- [ ] Professional tone appropriate for stakeholder review
|
||||
|
||||
### Document Structure
|
||||
|
||||
- [ ] Sections flow logically
|
||||
- [ ] Headers and numbering consistent
|
||||
- [ ] Cross-references accurate (FR numbers, section references)
|
||||
- [ ] Formatting consistent throughout
|
||||
- [ ] Tables/lists formatted properly
|
||||
|
||||
### Completeness Indicators
|
||||
|
||||
- [ ] No [TODO] or [TBD] markers remain
|
||||
- [ ] No placeholder text
|
||||
- [ ] All sections have substantive content
|
||||
- [ ] Optional sections either complete or omitted (not half-done)
|
||||
|
||||
---
|
||||
|
||||
## Critical Failures (Auto-Fail)
|
||||
|
||||
If ANY of these are true, validation FAILS:
|
||||
|
||||
- [ ] ❌ **No epics.md file exists** (two-file output required)
|
||||
- [ ] ❌ **Epic 1 doesn't establish foundation** (violates core sequencing principle)
|
||||
- [ ] ❌ **Stories have forward dependencies** (breaks sequential implementation)
|
||||
- [ ] ❌ **Stories not vertically sliced** (horizontal layers block value delivery)
|
||||
- [ ] ❌ **Epics don't cover all FRs** (orphaned requirements)
|
||||
- [ ] ❌ **FRs contain technical implementation details** (should be in architecture)
|
||||
- [ ] ❌ **No FR traceability to stories** (can't validate coverage)
|
||||
- [ ] ❌ **Template variables unfilled** (incomplete document)
|
||||
|
||||
---
|
||||
|
||||
## Validation Summary
|
||||
|
||||
**Total Validation Points:** ~85
|
||||
|
||||
### Scoring Guide
|
||||
|
||||
- **Pass Rate ≥ 95% (81+/85):** ✅ EXCELLENT - Ready for architecture phase
|
||||
- **Pass Rate 85-94% (72-80/85):** ⚠️ GOOD - Minor fixes needed
|
||||
- **Pass Rate 70-84% (60-71/85):** ⚠️ FAIR - Important issues to address
|
||||
- **Pass Rate < 70% (<60/85):** ❌ POOR - Significant rework required
|
||||
|
||||
### Critical Issue Threshold
|
||||
|
||||
- **0 Critical Failures:** Proceed to fixes
|
||||
- **1+ Critical Failures:** STOP - Must fix critical issues first
|
||||
|
||||
---
|
||||
|
||||
## Validation Execution Notes
|
||||
|
||||
**When validating:**
|
||||
|
||||
1. **Load ALL documents:**
|
||||
- PRD.md (required)
|
||||
- epics.md (required)
|
||||
- product-brief.md (if exists)
|
||||
- domain-brief.md (if exists)
|
||||
- research documents (if referenced)
|
||||
|
||||
2. **Validate in order:**
|
||||
- Check critical failures first (immediate stop if any found)
|
||||
- Verify PRD completeness
|
||||
- Verify epics completeness
|
||||
- Cross-reference FR coverage (most important)
|
||||
- Check sequencing (second most important)
|
||||
- Validate research integration
|
||||
- Check polish and quality
|
||||
|
||||
3. **Report findings:**
|
||||
- List critical failures prominently
|
||||
- Group issues by severity
|
||||
- Provide specific line numbers/sections
|
||||
- Suggest concrete fixes
|
||||
- Highlight what's working well
|
||||
|
||||
4. **Provide actionable next steps:**
|
||||
- If validation passes: "Ready for architecture workflow"
|
||||
- If minor issues: "Fix [X] items then re-validate"
|
||||
- If major issues: "Rework [sections] then re-validate"
|
||||
- If critical failures: "Must fix critical items before proceeding"
|
||||
|
||||
---
|
||||
|
||||
**Remember:** This validation ensures the entire planning phase is complete and the implementation phase has everything needed to succeed. Be thorough but fair - the goal is quality, not perfection.
|
||||
@@ -0,0 +1,63 @@
|
||||
# {{project_name}} - Epic Breakdown
|
||||
|
||||
**Author:** {{user_name}}
|
||||
**Date:** {{date}}
|
||||
**Project Level:** {{project_level}}
|
||||
**Target Scale:** {{target_scale}}
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides the detailed epic breakdown for {{project_name}}, expanding on the high-level epic list in the [PRD](./PRD.md).
|
||||
|
||||
Each epic includes:
|
||||
|
||||
- Expanded goal and value proposition
|
||||
- Complete story breakdown with user stories
|
||||
- Acceptance criteria for each story
|
||||
- Story sequencing and dependencies
|
||||
|
||||
**Epic Sequencing Principles:**
|
||||
|
||||
- Epic 1 establishes foundational infrastructure and initial functionality
|
||||
- Subsequent epics build progressively, each delivering significant end-to-end value
|
||||
- Stories within epics are vertically sliced and sequentially ordered
|
||||
- No forward dependencies - each story builds only on previous work
|
||||
|
||||
---
|
||||
|
||||
{{epic_details}}
|
||||
|
||||
---
|
||||
|
||||
## Story Guidelines Reference
|
||||
|
||||
**Story Format:**
|
||||
|
||||
```
|
||||
**Story [EPIC.N]: [Story Title]**
|
||||
|
||||
As a [user type],
|
||||
I want [goal/desire],
|
||||
So that [benefit/value].
|
||||
|
||||
**Acceptance Criteria:**
|
||||
1. [Specific testable criterion]
|
||||
2. [Another specific criterion]
|
||||
3. [etc.]
|
||||
|
||||
**Prerequisites:** [Dependencies on previous stories, if any]
|
||||
```
|
||||
|
||||
**Story Requirements:**
|
||||
|
||||
- **Vertical slices** - Complete, testable functionality delivery
|
||||
- **Sequential ordering** - Logical progression within epic
|
||||
- **No forward dependencies** - Only depend on previous work
|
||||
- **AI-agent sized** - Completable in 2-4 hour focused session
|
||||
- **Value-focused** - Integrate technical enablers into value-delivering stories
|
||||
|
||||
---
|
||||
|
||||
**For implementation:** Use the `create-story` workflow to generate individual story implementation plans from this epic breakdown.
|
||||
@@ -0,0 +1,395 @@
|
||||
# Epic and Story Decomposition - Bite-Sized Implementation Planning
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/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 limited context agents</critical>
|
||||
<critical>EVERY story must be completable by a single limited context window dev agent in one session</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 epics.md continuously as you work - never wait until the end</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="0" goal="Load context and requirements">
|
||||
<action>Welcome the {user_name} to the project inception high level epic and story planning.
|
||||
|
||||
Load required documents:
|
||||
|
||||
1. PRD.md (must exist - fuzzy match on name, might be a folder with an index and smaller sharded files also)
|
||||
2. domain-brief.md (if exists)
|
||||
3. product-brief.md (if exists)
|
||||
|
||||
Extract from PRD:
|
||||
|
||||
- Functional requirements
|
||||
- Non-functional requirements
|
||||
- Domain considerations
|
||||
- Project type
|
||||
- MVP scope vs growth features
|
||||
|
||||
If continuing from PRD workflow:
|
||||
"Great! Now let's break down your requirements into actionable epics and bite-sized stories that development agents can implement independently."
|
||||
|
||||
If starting fresh:
|
||||
"I'll help you transform your PRD into organized epics with implementable stories. Each story will be small enough for a single dev agent to complete in one session."</action>
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Form epics from natural groupings">
|
||||
<action>Transform requirements into epics organically
|
||||
|
||||
INTENT: Find natural boundaries that make sense for THIS product
|
||||
|
||||
Look at the requirements and find patterns:
|
||||
|
||||
- Features that work together
|
||||
- User journeys that connect
|
||||
- Technical systems that relate
|
||||
- Business capabilities that group
|
||||
- Domain requirements that cluster (compliance, validation, etc.)
|
||||
|
||||
Examples of natural epic formation:
|
||||
|
||||
- Auth features → "User Management" epic
|
||||
- Payment features → "Monetization" epic
|
||||
- Social features → "Community" epic
|
||||
- Admin features → "Administration" epic
|
||||
- Compliance requirements → "Regulatory Compliance" epic
|
||||
- API endpoints → "API Infrastructure" epic
|
||||
|
||||
But let the product guide you - don't force standard patterns
|
||||
|
||||
Each epic should:
|
||||
|
||||
- Have a clear business goal
|
||||
- Be independently valuable
|
||||
- Contain 3-8 related features
|
||||
- Be completable in 1-2 sprints
|
||||
|
||||
Name epics based on value, not technical components:
|
||||
GOOD: "User Onboarding", "Content Discovery", "Team Collaboration"
|
||||
NOT: "Database", "Frontend", "API"
|
||||
|
||||
If domain considerations exist:
|
||||
|
||||
- Create dedicated compliance/validation epics
|
||||
- Note special expertise needed per epic
|
||||
- Flag epics with regulatory dependencies
|
||||
|
||||
Present epic groupings conversationally:
|
||||
"Based on your requirements, I see these natural epic groupings:
|
||||
|
||||
1. [Epic Name] - [Brief description]
|
||||
2. [Epic Name] - [Brief description]
|
||||
3. [Epic Name] - [Brief description]
|
||||
|
||||
Does this organization make sense for how you think about the product?"</action>
|
||||
|
||||
<template-output>epics_structure</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Decompose into bite-sized stories">
|
||||
<critical>Small vertical sliced small stories are best for agentic dumb developers to implement without forgetting things</critical>
|
||||
|
||||
<action>Break each epic into small, implementable stories
|
||||
|
||||
INTENT: Create stories that one dev agent can complete independently
|
||||
|
||||
For each epic, decompose into stories that are:
|
||||
|
||||
- Small enough for single context window
|
||||
- Clear enough for autonomous implementation
|
||||
- Independent enough to develop in parallel when possible
|
||||
- Specific enough to have clear acceptance criteria
|
||||
|
||||
GOOD story examples:
|
||||
|
||||
- "Create login API endpoint that accepts email/password and returns JWT"
|
||||
- "Build user profile component with avatar upload to S3"
|
||||
- "Add password reset email template and sending logic"
|
||||
- "Implement rate limiting on auth endpoints (5 attempts per minute)"
|
||||
- "Create HIPAA-compliant audit log for patient data access"
|
||||
- "Build FDA 21 CFR Part 11 electronic signature component"
|
||||
|
||||
BAD story examples:
|
||||
|
||||
- "Build complete authentication system" (too big)
|
||||
- "Handle user management" (too vague)
|
||||
- "Make it secure" (not specific)
|
||||
- "Integrate everything" (requires multiple contexts)
|
||||
|
||||
Story format:
|
||||
"As a [user type], I want [specific feature], so that [clear value]"
|
||||
|
||||
Technical notes to include:
|
||||
|
||||
- Affected files/components if known
|
||||
- Required endpoints/methods
|
||||
- Data structures needed
|
||||
- Specific validation rules
|
||||
- Compliance requirements if applicable
|
||||
- Dependencies on other stories
|
||||
|
||||
Domain-aware story creation:
|
||||
|
||||
- For healthcare: Include specific regulations per story
|
||||
- For fintech: Note PCI/security requirements per story
|
||||
- For govtech: Flag accessibility needs per story
|
||||
- For aerospace: Include safety/validation requirements
|
||||
|
||||
Check each story:
|
||||
|
||||
- Can this be explained in <1000 words?
|
||||
- Can one agent complete without another's output?
|
||||
- Is the scope crystal clear?
|
||||
- Are success criteria obvious?
|
||||
- Are domain requirements specified?
|
||||
|
||||
If too big → split into smaller stories
|
||||
If too vague → add specifics
|
||||
If dependent → note the dependency clearly
|
||||
If domain-critical → flag compliance needs</action>
|
||||
|
||||
<template-output>epic_1_stories</template-output>
|
||||
<template-output>epic_2_stories</template-output>
|
||||
<template-output>epic_3_stories</template-output>
|
||||
|
||||
<!-- Continue for each epic discovered -->
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Sequence for smart implementation">
|
||||
<action>Order stories for successful development
|
||||
|
||||
INTENT: Create a logical flow that minimizes blockers and maximizes progress
|
||||
|
||||
Consider dependencies:
|
||||
TECHNICAL:
|
||||
|
||||
- Authentication before protected features
|
||||
- Data models before business logic
|
||||
- Core features before enhancements
|
||||
- API before frontend that uses it
|
||||
|
||||
DOMAIN:
|
||||
|
||||
- Compliance infrastructure before features
|
||||
- Validation framework before clinical features
|
||||
- Audit logging before financial transactions
|
||||
- Safety systems before operational features
|
||||
|
||||
PRACTICAL:
|
||||
|
||||
- What gives visible progress early?
|
||||
- What reduces risk soonest?
|
||||
- What enables parallel work?
|
||||
- What delivers value fastest?
|
||||
|
||||
Create implementation phases:
|
||||
|
||||
Phase 1 - Foundation:
|
||||
|
||||
- Core data models
|
||||
- Authentication/authorization
|
||||
- Basic infrastructure
|
||||
- Essential APIs
|
||||
- Compliance foundation (if domain requires)
|
||||
|
||||
Phase 2 - Core Features:
|
||||
|
||||
- MVP functionality
|
||||
- Key user flows
|
||||
- Basic UI/UX
|
||||
- Critical integrations
|
||||
- Domain validations (if applicable)
|
||||
|
||||
Phase 3 - Enhancement:
|
||||
|
||||
- Polish and refinement
|
||||
- Additional features
|
||||
- Performance optimization
|
||||
- Extended functionality
|
||||
- Advanced compliance features
|
||||
|
||||
Phase 4 - Growth:
|
||||
|
||||
- Analytics and monitoring
|
||||
- Advanced features
|
||||
- Scaling preparations
|
||||
- Nice-to-have additions
|
||||
|
||||
For complex domains, add gates:
|
||||
|
||||
- "Gate: Security audit before payment processing"
|
||||
- "Gate: Clinical validation before patient features"
|
||||
- "Gate: Compliance review before launch"
|
||||
|
||||
Present the sequencing conversationally:
|
||||
"Here's a smart implementation order:
|
||||
|
||||
**Phase 1 (Foundation) - Week 1-2:**
|
||||
|
||||
- Story 1.1: [Description]
|
||||
- Story 1.2: [Description] (can parallel with 1.1)
|
||||
- Story 1.3: [Description] (depends on 1.1)
|
||||
|
||||
**Phase 2 (Core) - Week 3-4:**
|
||||
[Continue...]
|
||||
|
||||
This gives you something working by [milestone] and allows [X] stories to run in parallel."</action>
|
||||
|
||||
<template-output>implementation_sequence</template-output>
|
||||
<template-output>development_phases</template-output>
|
||||
<template-output>dependency_graph</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Validate story sizing and clarity">
|
||||
<action>Review all stories for dev agent compatibility
|
||||
|
||||
Run through each story and verify:
|
||||
|
||||
SIZE CHECK:
|
||||
|
||||
- Story description < 500 words
|
||||
- Clear inputs and outputs defined
|
||||
- Single responsibility principle
|
||||
- No hidden complexity
|
||||
|
||||
CLARITY CHECK:
|
||||
|
||||
- Acceptance criteria explicit
|
||||
- Technical approach clear
|
||||
- No ambiguous requirements
|
||||
- Success measurable
|
||||
|
||||
DEPENDENCY CHECK:
|
||||
|
||||
- Dependencies documented
|
||||
- Can start with clear inputs
|
||||
- Outputs well-defined
|
||||
- Parallel opportunities noted
|
||||
|
||||
DOMAIN CHECK (if applicable):
|
||||
|
||||
- Compliance requirements stated
|
||||
- Validation criteria defined
|
||||
- Regulatory references included
|
||||
- Special expertise noted
|
||||
|
||||
If any issues found:
|
||||
"Story [X] seems too large. Let me split it:
|
||||
|
||||
- [Smaller story 1]
|
||||
- [Smaller story 2]"
|
||||
|
||||
"Story [Y] needs clarification on [aspect]. How should we handle [specific question]?"
|
||||
|
||||
Final validation:
|
||||
"All stories are now sized for 200k context limits.
|
||||
|
||||
- Total stories: [count]
|
||||
- Can run in parallel: [count]
|
||||
- Sequential dependencies: [count]
|
||||
- Estimated completion: [timeframe]"</action>
|
||||
|
||||
<template-output>story_validation</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Create development guidance">
|
||||
<action>Add practical guidance for implementation teams
|
||||
|
||||
Create quick reference for development:
|
||||
|
||||
GETTING STARTED:
|
||||
"Start with Phase 1 stories - multiple can run in parallel.
|
||||
Key files to create first: [list]
|
||||
Recommended agent allocation: [suggestion]"
|
||||
|
||||
DOMAIN GUIDANCE (if applicable):
|
||||
"Critical compliance checkpoints:
|
||||
|
||||
- After story [X]: Run [validation]
|
||||
- Before story [Y]: Review [regulation]
|
||||
- Throughout: Maintain [audit trail]"
|
||||
|
||||
TECHNICAL NOTES:
|
||||
"Architecture decisions needed:
|
||||
|
||||
- [Decision 1] affects stories [A, B, C]
|
||||
- [Decision 2] blocks story [D]
|
||||
|
||||
Consider these patterns:
|
||||
|
||||
- [Pattern] for [epic]
|
||||
- [Pattern] for [requirement]"
|
||||
|
||||
RISK MITIGATION:
|
||||
"Watch out for:
|
||||
|
||||
- [Risk] in story [X]
|
||||
- [Complexity] in epic [Y]
|
||||
- [Dependency] between [A] and [B]"
|
||||
|
||||
SUCCESS METRICS:
|
||||
"You'll know Phase 1 is complete when:
|
||||
|
||||
- [Measurable outcome]
|
||||
- [Testable feature]
|
||||
- [Validation passed]"</action>
|
||||
|
||||
<template-output>implementation_guidance</template-output>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Finalize and prepare handoff">
|
||||
<action>Complete the epics document and prepare for development
|
||||
|
||||
Review what we've created:
|
||||
"We've successfully decomposed your requirements into:
|
||||
|
||||
- [x] epics
|
||||
- [Y] total stories
|
||||
- [Z] phases of development
|
||||
|
||||
Every story is sized for a single dev agent to complete independently."
|
||||
|
||||
Highlight key achievements:
|
||||
|
||||
- Stories respect 200k context limit
|
||||
- Dependencies clearly mapped
|
||||
- Domain requirements integrated
|
||||
- Parallel development enabled
|
||||
|
||||
Save completed epics.md with:
|
||||
|
||||
- Full epic descriptions
|
||||
- All stories with acceptance criteria
|
||||
- Implementation sequence
|
||||
- Development phases
|
||||
- Dependency notes
|
||||
- Domain compliance requirements (if applicable)</action>
|
||||
|
||||
<output>**✅ Epic Decomposition Complete, {user_name}!**
|
||||
|
||||
Your requirements are now organized into **{epic_count} epics** with **{story_count} bite-sized stories**.
|
||||
|
||||
**Created:**
|
||||
|
||||
- **epics.md** - Complete epic breakdown with implementable stories
|
||||
|
||||
**Key Stats:**
|
||||
|
||||
- Average story size: Fits in 200k context
|
||||
- Parallel stories: {parallel_count} can run simultaneously
|
||||
- Sequential chains: {sequential_count} dependency chains
|
||||
- Estimated velocity: {velocity_estimate}
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
1. Review epics.md for the complete breakdown
|
||||
2. Start Phase 1 implementation with parallel stories
|
||||
3. Use story IDs for tracking progress
|
||||
|
||||
Each story is crafted for a single dev agent to complete autonomously. No monoliths, no confusion, just clear implementation paths.
|
||||
|
||||
Ready to begin development with any story marked "can start immediately"!</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
@@ -0,0 +1,33 @@
|
||||
# Epic and Story Decomposition Workflow
|
||||
name: create-epics-and-stories
|
||||
description: "Transform PRD requirements into bite-sized stories organized in epics for 200k context dev agents"
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
project_name: "{config_source}:project_name"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
date: system-generated
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
template: "{installed_path}/epics-template.md"
|
||||
|
||||
# Input files (from parent PRD workflow)
|
||||
prd_file: "{output_folder}/PRD.md"
|
||||
|
||||
# Output files
|
||||
default_output_file: "{output_folder}/epics.md"
|
||||
|
||||
# Optional input documents
|
||||
recommended_inputs:
|
||||
- prd: "{output_folder}/PRD.md"
|
||||
- product_brief: "{output_folder}/product-brief.md"
|
||||
- domain_brief: "{output_folder}/domain-brief.md"
|
||||
|
||||
standalone: true
|
||||
@@ -0,0 +1,13 @@
|
||||
domain,signals,complexity,key_concerns,required_knowledge,suggested_workflow,web_searches,special_sections
|
||||
healthcare,"medical,diagnostic,clinical,FDA,patient,treatment,HIPAA,therapy,pharma,drug",high,"FDA approval;Clinical validation;HIPAA compliance;Patient safety;Medical device classification;Liability","Regulatory pathways;Clinical trial design;Medical standards;Data privacy;Integration requirements","domain-research","FDA software medical device guidance {date};HIPAA compliance software requirements;Medical software standards {date};Clinical validation software","clinical_requirements;regulatory_pathway;validation_methodology;safety_measures"
|
||||
fintech,"payment,banking,trading,investment,crypto,wallet,transaction,KYC,AML,funds,fintech",high,"Regional compliance;Security standards;Audit requirements;Fraud prevention;Data protection","KYC/AML requirements;PCI DSS;Open banking;Regional laws (US/EU/APAC);Crypto regulations","domain-research","fintech regulations {date};payment processing compliance {date};open banking API standards;cryptocurrency regulations {date}","compliance_matrix;security_architecture;audit_requirements;fraud_prevention"
|
||||
govtech,"government,federal,civic,public sector,citizen,municipal,voting",high,"Procurement rules;Security clearance;Accessibility (508);FedRAMP;Privacy;Transparency","Government procurement;Security frameworks;Accessibility standards;Privacy laws;Open data requirements","domain-research","government software procurement {date};FedRAMP compliance requirements;section 508 accessibility;government security standards","procurement_compliance;security_clearance;accessibility_standards;transparency_requirements"
|
||||
edtech,"education,learning,student,teacher,curriculum,assessment,K-12,university,LMS",medium,"Student privacy (COPPA/FERPA);Accessibility;Content moderation;Age verification;Curriculum standards","Educational privacy laws;Learning standards;Accessibility requirements;Content guidelines;Assessment validity","domain-research","educational software privacy {date};COPPA FERPA compliance;WCAG education requirements;learning management standards","privacy_compliance;content_guidelines;accessibility_features;curriculum_alignment"
|
||||
aerospace,"aircraft,spacecraft,aviation,drone,satellite,propulsion,flight,radar,navigation",high,"Safety certification;DO-178C compliance;Performance validation;Simulation accuracy;Export controls","Aviation standards;Safety analysis;Simulation validation;ITAR/export controls;Performance requirements","domain-research + technical-model","DO-178C software certification;aerospace simulation standards {date};ITAR export controls software;aviation safety requirements","safety_certification;simulation_validation;performance_requirements;export_compliance"
|
||||
automotive,"vehicle,car,autonomous,ADAS,automotive,driving,EV,charging",high,"Safety standards;ISO 26262;V2X communication;Real-time requirements;Certification","Automotive standards;Functional safety;V2X protocols;Real-time systems;Testing requirements","domain-research","ISO 26262 automotive software;automotive safety standards {date};V2X communication protocols;EV charging standards","safety_standards;functional_safety;communication_protocols;certification_requirements"
|
||||
scientific,"research,algorithm,simulation,modeling,computational,analysis,data science,ML,AI",medium,"Reproducibility;Validation methodology;Peer review;Performance;Accuracy;Computational resources","Scientific method;Statistical validity;Computational requirements;Domain expertise;Publication standards","technical-model","scientific computing best practices {date};research reproducibility standards;computational modeling validation;peer review software","validation_methodology;accuracy_metrics;reproducibility_plan;computational_requirements"
|
||||
legaltech,"legal,law,contract,compliance,litigation,patent,attorney,court",high,"Legal ethics;Bar regulations;Data retention;Attorney-client privilege;Court system integration","Legal practice rules;Ethics requirements;Court filing systems;Document standards;Confidentiality","domain-research","legal technology ethics {date};law practice management software requirements;court filing system standards;attorney client privilege technology","ethics_compliance;data_retention;confidentiality_measures;court_integration"
|
||||
insuretech,"insurance,claims,underwriting,actuarial,policy,risk,premium",high,"Insurance regulations;Actuarial standards;Data privacy;Fraud detection;State compliance","Insurance regulations by state;Actuarial methods;Risk modeling;Claims processing;Regulatory reporting","domain-research","insurance software regulations {date};actuarial standards software;insurance fraud detection;state insurance compliance","regulatory_requirements;risk_modeling;fraud_detection;reporting_compliance"
|
||||
energy,"energy,utility,grid,solar,wind,power,electricity,oil,gas",high,"Grid compliance;NERC standards;Environmental regulations;Safety requirements;Real-time operations","Energy regulations;Grid standards;Environmental compliance;Safety protocols;SCADA systems","domain-research","energy sector software compliance {date};NERC CIP standards;smart grid requirements;renewable energy software standards","grid_compliance;safety_protocols;environmental_compliance;operational_requirements"
|
||||
gaming,"game,player,gameplay,level,character,multiplayer,quest",redirect,"REDIRECT TO GAME WORKFLOWS","Game design","game-brief","NA","NA"
|
||||
general,"",low,"Standard requirements;Basic security;User experience;Performance","General software practices","continue","software development best practices {date}","standard_requirements"
|
||||
|
423
bmad/bmm/workflows/2-plan-workflows/prd/instructions.md
Normal file
423
bmad/bmm/workflows/2-plan-workflows/prd/instructions.md
Normal file
@@ -0,0 +1,423 @@
|
||||
# PRD Workflow - Intent-Driven Product Planning
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/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>
|
||||
|
||||
## 📚 Input Document Discovery
|
||||
|
||||
This workflow requires: product brief, and may reference market research or brownfield project documentation.
|
||||
|
||||
**Discovery Process** (execute for each referenced document):
|
||||
|
||||
1. **Search for whole document first** - Use fuzzy file matching to find the complete document
|
||||
2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
|
||||
3. **If sharded version found**:
|
||||
- Read `index.md` to understand the document structure
|
||||
- Read ALL section files listed in the index
|
||||
- Treat the combined content as if it were a single document
|
||||
4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
|
||||
|
||||
**Priority**: If both whole and sharded versions exist, use the whole document.
|
||||
|
||||
**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="0" goal="Validate workflow readiness" tag="workflow-status">
|
||||
<action>Check if {status_file} exists</action>
|
||||
|
||||
<action if="status file not found">Set standalone_mode = true</action>
|
||||
|
||||
<check if="status file found">
|
||||
<action>Load the FULL file: {status_file}</action>
|
||||
<action>Parse workflow_status section</action>
|
||||
<action>Check status of "prd" 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>**Level {{project_level}} Project - Redirecting**
|
||||
|
||||
Level 0-1 projects use tech-spec workflow for simpler planning.
|
||||
PRD is for Level 2-4 projects that need comprehensive requirements.</output>
|
||||
<action>Exit and suggest tech-spec workflow</action>
|
||||
</check>
|
||||
|
||||
<check if="prd status is file path (already completed)">
|
||||
<output>⚠️ PRD already completed: {{prd status}}</output>
|
||||
<ask>Re-running will overwrite the existing PRD. Continue? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Use workflow-status to see your next step.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Set standalone_mode = false</action>
|
||||
</check>
|
||||
</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)
|
||||
3. Detect project type AND domain complexity
|
||||
|
||||
Load references:
|
||||
{installed_path}/project-types.csv
|
||||
{installed_path}/domain-complexity.csv
|
||||
|
||||
Through natural conversation:
|
||||
"Tell me about what you want to build - what problem does it solve and for whom?"
|
||||
|
||||
DUAL DETECTION:
|
||||
Project type signals: API, mobile, web, CLI, SDK, SaaS
|
||||
Domain complexity signals: medical, finance, government, education, aerospace
|
||||
|
||||
SPECIAL ROUTING:
|
||||
If game detected → Suggest game-brief and GDD workflows
|
||||
If complex domain detected → Offer domain research options:
|
||||
A) Run domain-research workflow (thorough)
|
||||
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'?"
|
||||
|
||||
This excitement becomes the thread woven throughout the PRD.</action>
|
||||
|
||||
<template-output>vision_alignment</template-output>
|
||||
<template-output>project_classification</template-output>
|
||||
<template-output>project_type</template-output>
|
||||
<template-output>domain_type</template-output>
|
||||
<template-output>complexity_level</template-output>
|
||||
<check if="complex domain">
|
||||
<template-output>domain_context_summary</template-output>
|
||||
</check>
|
||||
<template-output>product_magic_essence</template-output>
|
||||
<template-output>product_brief_path</template-output>
|
||||
<template-output>domain_brief_path</template-output>
|
||||
<template-output>research_documents</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Success Definition">
|
||||
<action>Define what winning looks like for THIS specific product
|
||||
|
||||
INTENT: Meaningful success criteria, not generic metrics
|
||||
|
||||
Adapt to context:
|
||||
|
||||
- Consumer: User love, engagement, retention
|
||||
- B2B: ROI, efficiency, adoption
|
||||
- Developer tools: Developer experience, community
|
||||
- Regulated: Compliance, safety, validation
|
||||
|
||||
Make it specific:
|
||||
|
||||
- NOT: "10,000 users"
|
||||
- BUT: "100 power users who rely on it daily"
|
||||
|
||||
- NOT: "99.9% uptime"
|
||||
- BUT: "Zero data loss during critical operations"
|
||||
|
||||
Weave in the magic:
|
||||
|
||||
- "Success means users experience [that special moment] and [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
|
||||
|
||||
The Scoping Game:
|
||||
|
||||
1. "What must work for this to be useful?" → MVP
|
||||
2. "What makes it competitive?" → Growth
|
||||
3. "What's the dream version?" → Vision
|
||||
|
||||
Challenge scope creep conversationally:
|
||||
|
||||
- "Could that wait until after launch?"
|
||||
- "Is that essential for proving the concept?"
|
||||
|
||||
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>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Domain-Specific Exploration" optional="true">
|
||||
<action>Only if complex domain detected or domain-brief exists
|
||||
|
||||
Synthesize domain requirements that will shape everything:
|
||||
|
||||
- Regulatory requirements
|
||||
- Compliance needs
|
||||
- Industry standards
|
||||
- Safety/risk factors
|
||||
- Required validations
|
||||
- Special expertise needed
|
||||
|
||||
These inform:
|
||||
|
||||
- What features are mandatory
|
||||
- What NFRs are critical
|
||||
- How to sequence development
|
||||
- What validation is required</action>
|
||||
|
||||
<check if="complex domain">
|
||||
<template-output>domain_considerations</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Innovation Discovery" optional="true">
|
||||
<action>Identify truly novel patterns if applicable
|
||||
|
||||
Listen for innovation signals:
|
||||
|
||||
- "Nothing like this exists"
|
||||
- "We're rethinking how [X] works"
|
||||
- "Combining [A] with [B] for the first time"
|
||||
|
||||
Explore deeply:
|
||||
|
||||
- What makes it unique?
|
||||
- What assumption are you challenging?
|
||||
- How do we validate it?
|
||||
- What's the fallback?
|
||||
|
||||
<WebSearch if="novel">{concept} innovations {date}</WebSearch></action>
|
||||
|
||||
<check if="innovation detected">
|
||||
<template-output>innovation_patterns</template-output>
|
||||
<template-output>validation_approach</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Project-Specific Deep Dive">
|
||||
<action>Based on detected project type, dive deep into specific needs
|
||||
|
||||
Load project type requirements from CSV and expand naturally.
|
||||
|
||||
FOR API/BACKEND:
|
||||
|
||||
- Map out endpoints, methods, parameters
|
||||
- Define authentication and authorization
|
||||
- Specify error codes and rate limits
|
||||
- Document data schemas
|
||||
|
||||
FOR MOBILE:
|
||||
|
||||
- Platform requirements (iOS/Android/both)
|
||||
- Device features needed
|
||||
- Offline capabilities
|
||||
- Store compliance
|
||||
|
||||
FOR SAAS B2B:
|
||||
|
||||
- Multi-tenant architecture
|
||||
- Permission models
|
||||
- Subscription tiers
|
||||
- Critical integrations
|
||||
|
||||
[Continue for other types...]
|
||||
|
||||
Always relate back to the product magic:
|
||||
"How does [requirement] enhance [the special thing]?"</action>
|
||||
|
||||
<template-output>project_type_requirements</template-output>
|
||||
|
||||
<!-- Dynamic sections based on project type -->
|
||||
<check if="API/Backend project">
|
||||
<template-output>endpoint_specification</template-output>
|
||||
<template-output>authentication_model</template-output>
|
||||
</check>
|
||||
|
||||
<check if="Mobile project">
|
||||
<template-output>platform_requirements</template-output>
|
||||
<template-output>device_features</template-output>
|
||||
</check>
|
||||
|
||||
<check if="SaaS B2B project">
|
||||
<template-output>tenant_model</template-output>
|
||||
<template-output>permission_matrix</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="UX Principles" optional="true">
|
||||
<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 to the magic:
|
||||
"The UI should reinforce [the special moment] 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">
|
||||
<action>Transform everything discovered into clear functional requirements
|
||||
|
||||
Pull together:
|
||||
|
||||
- Core features from scope
|
||||
- Domain-mandated features
|
||||
- Project-type specific needs
|
||||
- Innovation requirements
|
||||
|
||||
Organize by capability, not technology:
|
||||
|
||||
- User Management (not "auth system")
|
||||
- Content Discovery (not "search algorithm")
|
||||
- Team Collaboration (not "websockets")
|
||||
|
||||
Each requirement should:
|
||||
|
||||
- Be specific and measurable
|
||||
- Connect to user value
|
||||
- Include acceptance criteria
|
||||
- Note domain constraints
|
||||
|
||||
The magic thread:
|
||||
Highlight which requirements deliver the special experience</action>
|
||||
|
||||
<template-output>functional_requirements_complete</template-output>
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Non-Functional Requirements Discovery">
|
||||
<action>Only document NFRs that matter for THIS product
|
||||
|
||||
Performance: Only if user-facing impact
|
||||
Security: Only if handling sensitive data
|
||||
Scale: Only if growth expected
|
||||
Accessibility: Only if broad audience
|
||||
Integration: Only if connecting systems
|
||||
|
||||
For each NFR:
|
||||
|
||||
- Why it matters for THIS product
|
||||
- Specific measurable criteria
|
||||
- Domain-driven requirements
|
||||
|
||||
Skip categories that don't apply!</action>
|
||||
|
||||
<!-- Only output sections that were discussed -->
|
||||
<check if="performance matters">
|
||||
<template-output>performance_requirements</template-output>
|
||||
</check>
|
||||
<check if="security matters">
|
||||
<template-output>security_requirements</template-output>
|
||||
</check>
|
||||
<check if="scale matters">
|
||||
<template-output>scalability_requirements</template-output>
|
||||
</check>
|
||||
<check if="accessibility matters">
|
||||
<template-output>accessibility_requirements</template-output>
|
||||
</check>
|
||||
<check if="integration matters">
|
||||
<template-output>integration_requirements</template-output>
|
||||
</check>
|
||||
<check if="no NFRs discussed">
|
||||
<template-output>no_nfrs</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Review PRD and transition to epics">
|
||||
<action>Review the PRD we've built together
|
||||
|
||||
"Let's review what we've captured:
|
||||
|
||||
- Vision: [summary]
|
||||
- Success: [key metrics]
|
||||
- Scope: [MVP highlights]
|
||||
- Requirements: [count] functional, [count] non-functional
|
||||
- Special considerations: [domain/innovation]
|
||||
|
||||
Does this capture your product vision?"
|
||||
|
||||
After confirmation:
|
||||
"Excellent! Now we need to break these requirements into implementable epics and stories.
|
||||
|
||||
For the epic breakdown, you have two options:
|
||||
|
||||
1. Start a new session focused on epics (recommended for complex projects)
|
||||
2. Continue here (I'll transform requirements into epics now)
|
||||
|
||||
Which would you prefer?"
|
||||
|
||||
If new session:
|
||||
"To start epic planning in a new session:
|
||||
|
||||
1. Save your work here
|
||||
2. Start fresh and run: workflow epics-stories
|
||||
3. It will load your PRD and create the epic breakdown
|
||||
|
||||
This keeps each session focused and manageable."
|
||||
|
||||
If continue:
|
||||
"Let's continue with epic breakdown here..."
|
||||
[Proceed with epics-stories subworkflow]
|
||||
Set project_level and target_scale based on project analysis
|
||||
Generate epic_details for the epics breakdown document</action>
|
||||
|
||||
<template-output>prd_summary</template-output>
|
||||
<template-output>project_level</template-output>
|
||||
<template-output>target_scale</template-output>
|
||||
<template-output>epic_details</template-output>
|
||||
</step>
|
||||
|
||||
<step n="11" goal="Complete PRD and suggest next steps">
|
||||
<template-output>product_magic_summary</template-output>
|
||||
|
||||
<check if="standalone_mode != true">
|
||||
<action>Load the FULL file: {status_file}</action>
|
||||
<action>Update workflow_status["prd"] = "{default_output_file}"</action>
|
||||
<action>Save file, preserving ALL comments and structure</action>
|
||||
</check>
|
||||
|
||||
<output>**✅ PRD Complete, {user_name}!**
|
||||
|
||||
Your product requirements are documented and ready for implementation.
|
||||
|
||||
**Created:**
|
||||
|
||||
- **PRD.md** - Complete requirements adapted to {project_type} and {domain}
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
1. **Epic Breakdown** (Required)
|
||||
Run: `workflow create-epics-and-stories` to decompose requirements into implementable stories
|
||||
|
||||
2. **UX Design** (If UI exists)
|
||||
Run: `workflow ux-design` for detailed user experience design
|
||||
|
||||
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.
|
||||
</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
237
bmad/bmm/workflows/2-plan-workflows/prd/prd-template.md
Normal file
237
bmad/bmm/workflows/2-plan-workflows/prd/prd-template.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# {{project_name}} - Product Requirements Document
|
||||
|
||||
**Author:** {{user_name}}
|
||||
**Date:** {{date}}
|
||||
**Version:** 1.0
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{vision_alignment}}
|
||||
|
||||
### What Makes This Special
|
||||
|
||||
{{product_magic_essence}}
|
||||
|
||||
---
|
||||
|
||||
## 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}}
|
||||
|
||||
---
|
||||
|
||||
{{#if innovation_patterns}}
|
||||
|
||||
## Innovation & Novel Patterns
|
||||
|
||||
{{innovation_patterns}}
|
||||
|
||||
### 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}}
|
||||
|
||||
### 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}}
|
||||
|
||||
---
|
||||
|
||||
## Implementation Planning
|
||||
|
||||
### Epic Breakdown Required
|
||||
|
||||
Requirements must be decomposed into epics and bite-sized stories (200k context limit).
|
||||
|
||||
**Next Step:** Run `workflow epics-stories` to create the implementation breakdown.
|
||||
|
||||
---
|
||||
|
||||
## 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}}
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Epic & Story Breakdown** - Run: `workflow epics-stories`
|
||||
2. **UX Design** (if UI) - Run: `workflow ux-design`
|
||||
3. **Architecture** - Run: `workflow create-architecture`
|
||||
|
||||
---
|
||||
|
||||
_This PRD captures the essence of {{project_name}} - {{product_magic_summary}}_
|
||||
|
||||
_Created through collaborative discovery between {{user_name}} and AI facilitator._
|
||||
11
bmad/bmm/workflows/2-plan-workflows/prd/project-types.csv
Normal file
11
bmad/bmm/workflows/2-plan-workflows/prd/project-types.csv
Normal file
@@ -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"
|
||||
|
46
bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml
Normal file
46
bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml
Normal file
@@ -0,0 +1,46 @@
|
||||
# Product Requirements Document (PRD) Workflow
|
||||
name: prd
|
||||
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"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
project_name: "{config_source}:project_name"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
date: system-generated
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
|
||||
# Templates
|
||||
prd_template: "{installed_path}/prd-template.md"
|
||||
|
||||
# Output files
|
||||
status_file: "{output_folder}/bmm-workflow-status.yaml"
|
||||
default_output_file: "{output_folder}/PRD.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
|
||||
214
bmad/bmm/workflows/2-plan-workflows/tech-spec/checklist.md
Normal file
214
bmad/bmm/workflows/2-plan-workflows/tech-spec/checklist.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# Tech-Spec Workflow Validation Checklist
|
||||
|
||||
**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
|
||||
|
||||
- [ ] 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)
|
||||
- [ ] bmm-workflow-status.yaml updated (if not standalone mode)
|
||||
- [ ] No unfilled {{template_variables}} in any files
|
||||
|
||||
---
|
||||
|
||||
## 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 (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 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
|
||||
|
||||
---
|
||||
|
||||
## 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 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)
|
||||
|
||||
- [ ] **Vertical slices**: Each story delivers complete, testable functionality
|
||||
- [ ] **Sequential ordering**: Stories in logical progression
|
||||
- [ ] **No forward dependencies**: No story depends on later work
|
||||
- [ ] Each story leaves system in working state
|
||||
|
||||
### Coverage
|
||||
|
||||
- [ ] 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
|
||||
|
||||
---
|
||||
|
||||
## 6. Epic Quality (Level 1 Only)
|
||||
|
||||
- [ ] **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
|
||||
|
||||
---
|
||||
|
||||
## 7. Workflow Status Integration
|
||||
|
||||
- [ ] bmm-workflow-status.yaml updated (if exists)
|
||||
- [ ] Current phase reflects tech-spec completion
|
||||
- [ ] Progress percentage updated appropriately
|
||||
- [ ] Next workflow clearly identified
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
- [ ] ❌ **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 with actions)
|
||||
- [ ] ❌ **No brownfield analysis** (when document-project output exists but wasn't used)
|
||||
|
||||
---
|
||||
|
||||
## Validation Notes
|
||||
|
||||
**Document any findings:**
|
||||
|
||||
- **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]
|
||||
|
||||
---
|
||||
|
||||
_The tech-spec should be a RICH CONTEXT DOCUMENT that gives developers everything they need without requiring separate context generation._
|
||||
@@ -0,0 +1,58 @@
|
||||
# {{project_name}} - Epic Breakdown
|
||||
|
||||
**Date:** {{date}}
|
||||
**Project Level:** {{project_level}}
|
||||
|
||||
---
|
||||
|
||||
## 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}}
|
||||
|
||||
---
|
||||
|
||||
## Tech-Spec Reference
|
||||
|
||||
See [tech-spec.md](../tech-spec.md) for complete technical implementation details.
|
||||
@@ -0,0 +1,200 @@
|
||||
# Level 0 - Minimal User Story Generation
|
||||
|
||||
<workflow>
|
||||
|
||||
<critical>This generates a single user story for Level 0 atomic changes</critical>
|
||||
<critical>Level 0 = single file change, bug fix, or small isolated task</critical>
|
||||
<critical>This workflow runs AFTER tech-spec.md has been completed</critical>
|
||||
<critical>Output format MUST match create-story template for compatibility with story-context and dev-story workflows</critical>
|
||||
|
||||
<step n="1" goal="Load tech spec and extract the change">
|
||||
|
||||
<action>Read the completed tech-spec.md file from {output_folder}/tech-spec.md</action>
|
||||
<action>Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists)</action>
|
||||
<action>Extract dev_story_location from config (where stories are stored)</action>
|
||||
|
||||
<action>Extract from the ENHANCED tech-spec structure:
|
||||
|
||||
- Problem statement from "The Change → Problem Statement" section
|
||||
- Solution overview from "The Change → Proposed Solution" section
|
||||
- Scope from "The Change → Scope" section
|
||||
- Source tree from "Implementation Details → Source Tree Changes" section
|
||||
- Time estimate from "Implementation Guide → Implementation Steps" section
|
||||
- Acceptance criteria from "Implementation Guide → Acceptance Criteria" section
|
||||
- Framework dependencies from "Development Context → Framework/Libraries" section
|
||||
- Existing code references from "Development Context → Relevant Existing Code" section
|
||||
- File paths from "Developer Resources → File Paths Reference" section
|
||||
- Key code locations from "Developer Resources → Key Code Locations" section
|
||||
- Testing locations from "Developer Resources → Testing Locations" section
|
||||
</action>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Generate story slug and filename">
|
||||
|
||||
<action>Derive a short URL-friendly slug from the feature/change name</action>
|
||||
<action>Max slug length: 3-5 words, kebab-case format</action>
|
||||
|
||||
<example>
|
||||
- "Migrate JS Library Icons" → "icon-migration"
|
||||
- "Fix Login Validation Bug" → "login-fix"
|
||||
- "Add OAuth Integration" → "oauth-integration"
|
||||
</example>
|
||||
|
||||
<action>Set story_filename = "story-{slug}.md"</action>
|
||||
<action>Set story_path = "{dev_story_location}/story-{slug}.md"</action>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Create user story in standard format">
|
||||
|
||||
<action>Create 1 story that describes the technical change as a deliverable</action>
|
||||
<action>Story MUST use create-story template format for compatibility</action>
|
||||
|
||||
<guidelines>
|
||||
**Story Point Estimation:**
|
||||
- 1 point = < 1 day (2-4 hours)
|
||||
- 2 points = 1-2 days
|
||||
- 3 points = 2-3 days
|
||||
- 5 points = 3-5 days (if this high, question if truly Level 0)
|
||||
|
||||
**Story Title Best Practices:**
|
||||
|
||||
- Use active, user-focused language
|
||||
- Describe WHAT is delivered, not HOW
|
||||
- Good: "Icon Migration to Internal CDN"
|
||||
- Bad: "Run curl commands to download PNGs"
|
||||
|
||||
**Story Description Format:**
|
||||
|
||||
- As a [role] (developer, user, admin, etc.)
|
||||
- I want [capability/change]
|
||||
- So that [benefit/value]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- Extract from tech-spec "Testing Approach" section
|
||||
- Must be specific, measurable, and testable
|
||||
- Include performance criteria if specified
|
||||
|
||||
**Tasks/Subtasks:**
|
||||
|
||||
- Map directly to tech-spec "Implementation Guide" tasks
|
||||
- Use checkboxes for tracking
|
||||
- Reference AC numbers: (AC: #1), (AC: #2)
|
||||
- Include explicit testing subtasks
|
||||
|
||||
**Dev Notes:**
|
||||
|
||||
- Extract technical constraints from tech-spec
|
||||
- Include file paths from "Developer Resources → File Paths Reference"
|
||||
- Include existing code references from "Development Context → Relevant Existing Code"
|
||||
- Reference architecture patterns if applicable
|
||||
- Cite tech-spec sections for implementation details
|
||||
- Note dependencies (internal and external)
|
||||
|
||||
**NEW: Comprehensive Context**
|
||||
|
||||
Since tech-spec is now context-rich, populate all new template fields:
|
||||
|
||||
- dependencies: Extract from "Development Context" and "Implementation Details → Integration Points"
|
||||
- existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations"
|
||||
</guidelines>
|
||||
|
||||
<action>Initialize story file using user_story_template</action>
|
||||
|
||||
<template-output file="{story_path}">story_title</template-output>
|
||||
<template-output file="{story_path}">role</template-output>
|
||||
<template-output file="{story_path}">capability</template-output>
|
||||
<template-output file="{story_path}">benefit</template-output>
|
||||
<template-output file="{story_path}">acceptance_criteria</template-output>
|
||||
<template-output file="{story_path}">tasks_subtasks</template-output>
|
||||
<template-output file="{story_path}">technical_summary</template-output>
|
||||
<template-output file="{story_path}">files_to_modify</template-output>
|
||||
<template-output file="{story_path}">test_locations</template-output>
|
||||
<template-output file="{story_path}">story_points</template-output>
|
||||
<template-output file="{story_path}">time_estimate</template-output>
|
||||
<template-output file="{story_path}">dependencies</template-output>
|
||||
<template-output file="{story_path}">existing_code_references</template-output>
|
||||
<template-output file="{story_path}">architecture_references</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Update status - Level 0 single story">
|
||||
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: update</param>
|
||||
<param>action: complete_workflow</param>
|
||||
<param>workflow_name: tech-spec</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="success == true">
|
||||
<output>✅ Tech-spec complete! Next: {{next_workflow}}</output>
|
||||
</check>
|
||||
|
||||
<action>Load {{status_file_path}}</action>
|
||||
<action>Set STORIES_SEQUENCE: [{slug}]</action>
|
||||
<action>Set TODO_STORY: {slug}</action>
|
||||
<action>Set TODO_TITLE: {{story_title}}</action>
|
||||
<action>Set IN_PROGRESS_STORY: (empty)</action>
|
||||
<action>Set STORIES_DONE: []</action>
|
||||
<action>Save {{status_file_path}}</action>
|
||||
|
||||
<output>Story queue initialized with single story: {slug}</output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Provide user guidance for next steps">
|
||||
|
||||
<action>Display completion summary</action>
|
||||
|
||||
**Level 0 Planning Complete!**
|
||||
|
||||
**Generated Artifacts:**
|
||||
|
||||
- `tech-spec.md` → Technical source of truth
|
||||
- `story-{slug}.md` → User story ready for implementation
|
||||
|
||||
**Story Location:** `{story_path}`
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
**🎯 RECOMMENDED - Direct to Development (Level 0):**
|
||||
|
||||
Since the tech-spec is now CONTEXT-RICH with:
|
||||
|
||||
- ✅ Brownfield codebase analysis (if applicable)
|
||||
- ✅ Framework and library details with exact versions
|
||||
- ✅ Existing patterns and code references
|
||||
- ✅ Complete file paths and integration points
|
||||
|
||||
**You can skip story-context and go straight to dev!**
|
||||
|
||||
1. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
|
||||
2. Run `dev-story` workflow
|
||||
3. Begin implementation immediately
|
||||
|
||||
**Option B - Generate Additional Context (optional):**
|
||||
|
||||
Only needed for extremely complex scenarios:
|
||||
|
||||
1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
|
||||
2. Run `story-context` workflow (generates additional XML context)
|
||||
3. Then load DEV agent and run `dev-story` workflow
|
||||
|
||||
**Progress Tracking:**
|
||||
|
||||
- All decisions logged in: `bmm-workflow-status.yaml`
|
||||
- Next action clearly identified
|
||||
|
||||
<ask>Ready to proceed? Choose your path:
|
||||
|
||||
1. Go directly to dev-story (RECOMMENDED - tech-spec has all context)
|
||||
2. Generate additional story context (for complex edge cases)
|
||||
3. Exit for now
|
||||
|
||||
Select option (1-3):</ask>
|
||||
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
@@ -0,0 +1,451 @@
|
||||
# Level 1 - Epic and Stories Generation
|
||||
|
||||
<workflow>
|
||||
|
||||
<critical>This generates epic and user stories for Level 1 projects after tech-spec completion</critical>
|
||||
<critical>This is a lightweight story breakdown - not a full PRD</critical>
|
||||
<critical>Level 1 = coherent feature, 1-10 stories (prefer 2-3), 1 epic</critical>
|
||||
<critical>This workflow runs AFTER tech-spec.md has been completed</critical>
|
||||
<critical>Story format MUST match create-story template for compatibility with story-context and dev-story workflows</critical>
|
||||
|
||||
<step n="1" goal="Load tech spec and extract implementation tasks">
|
||||
|
||||
<action>Read the completed tech-spec.md file from {output_folder}/tech-spec.md</action>
|
||||
<action>Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists)</action>
|
||||
<action>Extract dev_story_location from config (where stories are stored)</action>
|
||||
|
||||
<action>Extract from the ENHANCED tech-spec structure:
|
||||
|
||||
- Overall feature goal from "The Change → Problem Statement" and "Proposed Solution"
|
||||
- Implementation tasks from "Implementation Guide → Implementation Steps"
|
||||
- Time estimates from "Implementation Guide → Implementation Steps"
|
||||
- Dependencies from "Implementation Details → Integration Points" and "Development Context → Dependencies"
|
||||
- Source tree from "Implementation Details → Source Tree Changes"
|
||||
- Framework dependencies from "Development Context → Framework/Libraries"
|
||||
- Existing code references from "Development Context → Relevant Existing Code"
|
||||
- File paths from "Developer Resources → File Paths Reference"
|
||||
- Key code locations from "Developer Resources → Key Code Locations"
|
||||
- Testing locations from "Developer Resources → Testing Locations"
|
||||
- Acceptance criteria from "Implementation Guide → Acceptance Criteria"
|
||||
</action>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Create single epic">
|
||||
|
||||
<action>Create 1 epic that represents the entire feature</action>
|
||||
<action>Epic title should be user-facing value statement</action>
|
||||
<action>Epic goal should describe why this matters to users</action>
|
||||
|
||||
<guidelines>
|
||||
**Epic Best Practices:**
|
||||
- Title format: User-focused outcome (not implementation detail)
|
||||
- Good: "JS Library Icon Reliability"
|
||||
- Bad: "Update recommendedLibraries.ts file"
|
||||
- Scope: Clearly define what's included/excluded
|
||||
- Success criteria: Measurable outcomes that define "done"
|
||||
</guidelines>
|
||||
|
||||
<example>
|
||||
**Epic:** JS Library Icon Reliability
|
||||
|
||||
**Goal:** Eliminate external dependencies for JS library icons to ensure consistent, reliable display and improve application performance.
|
||||
|
||||
**Scope:** Migrate all 14 recommended JS library icons from third-party CDN URLs (GitHub, jsDelivr) to internal static asset hosting.
|
||||
|
||||
**Success Criteria:**
|
||||
|
||||
- All library icons load from internal paths
|
||||
- Zero external requests for library icons
|
||||
- Icons load 50-200ms faster than baseline
|
||||
- No broken icons in production
|
||||
</example>
|
||||
|
||||
<action>Derive epic slug from epic title (kebab-case, 2-3 words max)</action>
|
||||
<example>
|
||||
|
||||
- "JS Library Icon Reliability" → "icon-reliability"
|
||||
- "OAuth Integration" → "oauth-integration"
|
||||
- "Admin Dashboard" → "admin-dashboard"
|
||||
</example>
|
||||
|
||||
<action>Initialize epics.md summary document using epics_template</action>
|
||||
|
||||
<action>Also capture project_level for the epic template</action>
|
||||
|
||||
<template-output file="{output_folder}/epics.md">project_level</template-output>
|
||||
<template-output file="{output_folder}/epics.md">epic_title</template-output>
|
||||
<template-output file="{output_folder}/epics.md">epic_slug</template-output>
|
||||
<template-output file="{output_folder}/epics.md">epic_goal</template-output>
|
||||
<template-output file="{output_folder}/epics.md">epic_scope</template-output>
|
||||
<template-output file="{output_folder}/epics.md">epic_success_criteria</template-output>
|
||||
<template-output file="{output_folder}/epics.md">epic_dependencies</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Determine optimal story count">
|
||||
|
||||
<critical>Level 1 should have 2-3 stories maximum - prefer longer stories over more stories</critical>
|
||||
|
||||
<action>Analyze tech spec implementation tasks and time estimates</action>
|
||||
<action>Group related tasks into logical story boundaries</action>
|
||||
|
||||
<guidelines>
|
||||
**Story Count Decision Matrix:**
|
||||
|
||||
**2 Stories (preferred for most Level 1):**
|
||||
|
||||
- Use when: Feature has clear build/verify split
|
||||
- Example: Story 1 = Build feature, Story 2 = Test and deploy
|
||||
- Typical points: 3-5 points per story
|
||||
|
||||
**3 Stories (only if necessary):**
|
||||
|
||||
- Use when: Feature has distinct setup, build, verify phases
|
||||
- Example: Story 1 = Setup, Story 2 = Core implementation, Story 3 = Integration and testing
|
||||
- Typical points: 2-3 points per story
|
||||
|
||||
**Never exceed 3 stories for Level 1:**
|
||||
|
||||
- If more needed, consider if project should be Level 2
|
||||
- Better to have longer stories (5 points) than more stories (5x 1-point stories)
|
||||
</guidelines>
|
||||
|
||||
<action>Determine story_count = 2 or 3 based on tech spec complexity</action>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Generate user stories from tech spec tasks">
|
||||
|
||||
<action>For each story (2-3 total), generate separate story file</action>
|
||||
<action>Story filename format: "story-{epic_slug}-{n}.md" where n = 1, 2, or 3</action>
|
||||
|
||||
<guidelines>
|
||||
**Story Generation Guidelines:**
|
||||
- Each story = multiple implementation tasks from tech spec
|
||||
- Story title format: User-focused deliverable (not implementation steps)
|
||||
- Include technical acceptance criteria from tech spec tasks
|
||||
- Link back to tech spec sections for implementation details
|
||||
|
||||
**CRITICAL: Acceptance Criteria Must Be:**
|
||||
|
||||
1. **Numbered** - AC #1, AC #2, AC #3, etc.
|
||||
2. **Specific** - No vague statements like "works well" or "is fast"
|
||||
3. **Testable** - Can be verified objectively
|
||||
4. **Complete** - Covers all success conditions
|
||||
5. **Independent** - Each AC tests one thing
|
||||
6. **Format**: Use Given/When/Then when applicable
|
||||
|
||||
**Good AC Examples:**
|
||||
✅ AC #1: Given a valid email address, when user submits the form, then the account is created and user receives a confirmation email within 30 seconds
|
||||
✅ AC #2: Given an invalid email format, when user submits, then form displays "Invalid email format" error message
|
||||
✅ AC #3: All unit tests in UserService.test.ts pass with 100% coverage
|
||||
|
||||
**Bad AC Examples:**
|
||||
❌ "User can create account" (too vague)
|
||||
❌ "System performs well" (not measurable)
|
||||
❌ "Works correctly" (not specific)
|
||||
|
||||
**Story Point Estimation:**
|
||||
|
||||
- 1 point = < 1 day (2-4 hours)
|
||||
- 2 points = 1-2 days
|
||||
- 3 points = 2-3 days
|
||||
- 5 points = 3-5 days
|
||||
|
||||
**Level 1 Typical Totals:**
|
||||
|
||||
- Total story points: 5-10 points
|
||||
- 2 stories: 3-5 points each
|
||||
- 3 stories: 2-3 points each
|
||||
- If total > 15 points, consider if this should be Level 2
|
||||
|
||||
**Story Structure (MUST match create-story format):**
|
||||
|
||||
- Status: Draft
|
||||
- Story: As a [role], I want [capability], so that [benefit]
|
||||
- Acceptance Criteria: Numbered list from tech spec
|
||||
- Tasks / Subtasks: Checkboxes mapped to tech spec tasks (AC: #n references)
|
||||
- Dev Notes: Technical summary, project structure notes, references
|
||||
- Dev Agent Record: Empty sections (tech-spec provides context)
|
||||
|
||||
**NEW: Comprehensive Context Fields**
|
||||
|
||||
Since tech-spec is context-rich, populate ALL template fields:
|
||||
|
||||
- dependencies: Extract from tech-spec "Development Context → Dependencies" and "Integration Points"
|
||||
- existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations"
|
||||
</guidelines>
|
||||
|
||||
<for-each story="1 to story_count">
|
||||
<action>Set story_path_{n} = "{dev_story_location}/story-{epic_slug}-{n}.md"</action>
|
||||
<action>Create story file from user_story_template with the following content:</action>
|
||||
|
||||
<template-output file="{story_path_{n}}">
|
||||
- story_title: User-focused deliverable title
|
||||
- role: User role (e.g., developer, user, admin)
|
||||
- capability: What they want to do
|
||||
- benefit: Why it matters
|
||||
- acceptance_criteria: Specific, measurable criteria from tech spec
|
||||
- tasks_subtasks: Implementation tasks with AC references
|
||||
- technical_summary: High-level approach, key decisions
|
||||
- files_to_modify: List of files that will change (from tech-spec "Developer Resources → File Paths Reference")
|
||||
- test_locations: Where tests will be added (from tech-spec "Developer Resources → Testing Locations")
|
||||
- story_points: Estimated effort (1/2/3/5)
|
||||
- time_estimate: Days/hours estimate
|
||||
- dependencies: Internal/external dependencies (from tech-spec "Development Context" and "Integration Points")
|
||||
- existing_code_references: Code to reference (from tech-spec "Development Context → Relevant Existing Code" and "Key Code Locations")
|
||||
- architecture_references: Links to tech-spec.md sections
|
||||
</template-output>
|
||||
</for-each>
|
||||
|
||||
<critical>Generate exactly {story_count} story files (2 or 3 based on Step 3 decision)</critical>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Create story map and implementation sequence with dependency validation">
|
||||
|
||||
<critical>Stories MUST be ordered so earlier stories don't depend on later ones</critical>
|
||||
<critical>Each story must have CLEAR, TESTABLE acceptance criteria</critical>
|
||||
|
||||
<action>Analyze dependencies between stories:
|
||||
|
||||
**Dependency Rules:**
|
||||
|
||||
1. Infrastructure/setup → Feature implementation → Testing/polish
|
||||
2. Database changes → API changes → UI changes
|
||||
3. Backend services → Frontend components
|
||||
4. Core functionality → Enhancement features
|
||||
5. No story can depend on a later story!
|
||||
|
||||
**Validate Story Sequence:**
|
||||
For each story N, check:
|
||||
|
||||
- Does it require anything from Story N+1, N+2, etc.? ❌ INVALID
|
||||
- Does it only use things from Story 1...N-1? ✅ VALID
|
||||
- Can it be implemented independently or using only prior stories? ✅ VALID
|
||||
|
||||
If invalid dependencies found, REORDER stories!
|
||||
</action>
|
||||
|
||||
<action>Generate visual story map showing epic → stories hierarchy with dependencies</action>
|
||||
<action>Calculate total story points across all stories</action>
|
||||
<action>Estimate timeline based on total points (1-2 points per day typical)</action>
|
||||
<action>Define implementation sequence with explicit dependency notes</action>
|
||||
|
||||
<example>
|
||||
## Story Map
|
||||
|
||||
```
|
||||
Epic: Icon Reliability
|
||||
├── Story 1: Build Icon Infrastructure (3 points)
|
||||
│ Dependencies: None (foundational work)
|
||||
│
|
||||
└── Story 2: Test and Deploy Icons (2 points)
|
||||
Dependencies: Story 1 (requires infrastructure)
|
||||
```
|
||||
|
||||
**Total Story Points:** 5
|
||||
**Estimated Timeline:** 1 sprint (1 week)
|
||||
|
||||
## Implementation Sequence
|
||||
|
||||
1. **Story 1** → Build icon infrastructure (setup, download, configure)
|
||||
- Dependencies: None
|
||||
- Deliverable: Icon files downloaded, organized, accessible
|
||||
|
||||
2. **Story 2** → Test and deploy (depends on Story 1)
|
||||
- Dependencies: Story 1 must be complete
|
||||
- Deliverable: Icons verified, tested, deployed to production
|
||||
|
||||
**Dependency Validation:** ✅ Valid sequence - no forward dependencies
|
||||
</example>
|
||||
|
||||
<template-output file="{output_folder}/epics.md">story_summaries</template-output>
|
||||
<template-output file="{output_folder}/epics.md">story_map</template-output>
|
||||
<template-output file="{output_folder}/epics.md">total_points</template-output>
|
||||
<template-output file="{output_folder}/epics.md">estimated_timeline</template-output>
|
||||
<template-output file="{output_folder}/epics.md">implementation_sequence</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Update status and populate story backlog">
|
||||
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: update</param>
|
||||
<param>action: complete_workflow</param>
|
||||
<param>workflow_name: tech-spec</param>
|
||||
<param>populate_stories_from: {epics_output_file}</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="success == true">
|
||||
<output>✅ Status updated! Loaded {{total_stories}} stories from epics.</output>
|
||||
<output>Next: {{next_workflow}} ({{next_agent}} agent)</output>
|
||||
</check>
|
||||
|
||||
<check if="success == false">
|
||||
<output>⚠️ Status update failed: {{error}}</output>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Auto-validate story quality and sequence">
|
||||
|
||||
<critical>Auto-run validation - NOT optional!</critical>
|
||||
|
||||
<action>Running automatic story validation...</action>
|
||||
|
||||
<action>**Validate Story Sequence (CRITICAL):**
|
||||
|
||||
For each story, check:
|
||||
|
||||
1. Does Story N depend on Story N+1 or later? ❌ FAIL - Reorder required!
|
||||
2. Are dependencies clearly documented? ✅ PASS
|
||||
3. Can stories be implemented in order 1→2→3? ✅ PASS
|
||||
|
||||
If sequence validation FAILS:
|
||||
|
||||
- Identify the problem dependencies
|
||||
- Propose new ordering
|
||||
- Ask user to confirm reordering
|
||||
</action>
|
||||
|
||||
<action>**Validate Acceptance Criteria Quality:**
|
||||
|
||||
For each story's AC, check:
|
||||
|
||||
1. Is it numbered (AC #1, AC #2, etc.)? ✅ Required
|
||||
2. Is it specific and testable? ✅ Required
|
||||
3. Does it use Given/When/Then or equivalent? ✅ Recommended
|
||||
4. Are all success conditions covered? ✅ Required
|
||||
|
||||
Count vague AC (contains "works", "good", "fast", "well"):
|
||||
|
||||
- 0 vague AC: ✅ EXCELLENT
|
||||
- 1-2 vague AC: ⚠️ WARNING - Should improve
|
||||
- 3+ vague AC: ❌ FAIL - Must improve
|
||||
</action>
|
||||
|
||||
<action>**Validate Story Completeness:**
|
||||
|
||||
1. Do all stories map to tech spec tasks? ✅ Required
|
||||
2. Do story points align with tech spec estimates? ✅ Recommended
|
||||
3. Are dependencies clearly noted? ✅ Required
|
||||
4. Does each story have testable AC? ✅ Required
|
||||
</action>
|
||||
|
||||
<action>Generate validation report</action>
|
||||
|
||||
<check if="sequence validation fails OR AC quality fails">
|
||||
<output>❌ **Story Validation Failed:**
|
||||
|
||||
{{issues_found}}
|
||||
|
||||
**Recommended Fixes:**
|
||||
{{recommended_fixes}}
|
||||
|
||||
Shall I fix these issues? (yes/no)</output>
|
||||
|
||||
<ask>Apply fixes? (yes/no)</ask>
|
||||
|
||||
<check if="yes">
|
||||
<action>Apply fixes (reorder stories, rewrite vague AC, add missing details)</action>
|
||||
<action>Re-validate</action>
|
||||
<output>✅ Validation passed after fixes!</output>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="validation passes">
|
||||
<output>✅ **Story Validation Passed!**
|
||||
|
||||
**Sequence:** ✅ Valid (no forward dependencies)
|
||||
**AC Quality:** ✅ All specific and testable
|
||||
**Completeness:** ✅ All tech spec tasks covered
|
||||
**Dependencies:** ✅ Clearly documented
|
||||
|
||||
Stories are implementation-ready!</output>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Finalize and provide user guidance">
|
||||
|
||||
<action>Confirm all validation passed</action>
|
||||
<action>Verify total story points align with tech spec time estimates</action>
|
||||
<action>Confirm epic and stories are complete</action>
|
||||
|
||||
**Level 1 Planning Complete!**
|
||||
|
||||
**Epic:** {{epic_title}}
|
||||
**Total Stories:** {{story_count}}
|
||||
**Total Story Points:** {{total_points}}
|
||||
**Estimated Timeline:** {{estimated_timeline}}
|
||||
|
||||
**Generated Artifacts:**
|
||||
|
||||
- `tech-spec.md` → Technical source of truth
|
||||
- `epics.md` → Epic and story summary
|
||||
- `story-{epic_slug}-1.md` → First story (ready for implementation)
|
||||
- `story-{epic_slug}-2.md` → Second story
|
||||
{{#if story_3}}
|
||||
- `story-{epic_slug}-3.md` → Third story
|
||||
{{/if}}
|
||||
|
||||
**Story Location:** `{dev_story_location}/`
|
||||
|
||||
**Next Steps - Iterative Implementation:**
|
||||
|
||||
**🎯 RECOMMENDED - Direct to Development (Level 1):**
|
||||
|
||||
Since the tech-spec is now CONTEXT-RICH with:
|
||||
|
||||
- ✅ Brownfield codebase analysis (if applicable)
|
||||
- ✅ Framework and library details with exact versions
|
||||
- ✅ Existing patterns and code references
|
||||
- ✅ Complete file paths and integration points
|
||||
- ✅ Dependencies clearly mapped
|
||||
|
||||
**You can skip story-context for most Level 1 stories!**
|
||||
|
||||
**1. Start with Story 1:**
|
||||
a. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
|
||||
b. Run `dev-story` workflow (select story-{epic_slug}-1.md)
|
||||
c. Tech-spec provides all context needed
|
||||
d. Implement story 1
|
||||
|
||||
**2. After Story 1 Complete:**
|
||||
|
||||
- Repeat for story-{epic_slug}-2.md
|
||||
- Reference completed story 1 in your work
|
||||
|
||||
**3. After Story 2 Complete:**
|
||||
{{#if story_3}}
|
||||
|
||||
- Repeat for story-{epic_slug}-3.md
|
||||
{{/if}}
|
||||
- Level 1 feature complete!
|
||||
|
||||
**Option B - Generate Additional Context (optional):**
|
||||
|
||||
Only needed for extremely complex multi-story dependencies:
|
||||
|
||||
1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
|
||||
2. Run `story-context` workflow for complex stories
|
||||
3. Then load DEV agent and run `dev-story`
|
||||
|
||||
**Progress Tracking:**
|
||||
|
||||
- All decisions logged in: `bmm-workflow-status.yaml`
|
||||
- Next action clearly identified
|
||||
|
||||
<ask>Ready to proceed? Choose your path:
|
||||
|
||||
1. Go directly to dev-story for story 1 (RECOMMENDED - tech-spec has all context)
|
||||
2. Generate additional story context first (for complex dependencies)
|
||||
3. Exit for now
|
||||
|
||||
Select option (1-3):</ask>
|
||||
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
1133
bmad/bmm/workflows/2-plan-workflows/tech-spec/instructions.md
Normal file
1133
bmad/bmm/workflows/2-plan-workflows/tech-spec/instructions.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,181 @@
|
||||
# {{project_name}} - Technical Specification
|
||||
|
||||
**Author:** {{user_name}}
|
||||
**Date:** {{date}}
|
||||
**Project Level:** {{project_level}}
|
||||
**Change Type:** {{change_type}}
|
||||
**Development Context:** {{development_context}}
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
### Available Documents
|
||||
|
||||
{{loaded_documents_summary}}
|
||||
|
||||
### Project Stack
|
||||
|
||||
{{project_stack_summary}}
|
||||
|
||||
### Existing Codebase Structure
|
||||
|
||||
{{existing_structure_summary}}
|
||||
|
||||
---
|
||||
|
||||
## The Change
|
||||
|
||||
### Problem Statement
|
||||
|
||||
{{problem_statement}}
|
||||
|
||||
### Proposed Solution
|
||||
|
||||
{{solution_overview}}
|
||||
|
||||
### Scope
|
||||
|
||||
**In Scope:**
|
||||
|
||||
{{scope_in}}
|
||||
|
||||
**Out of Scope:**
|
||||
|
||||
{{scope_out}}
|
||||
|
||||
---
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Source Tree Changes
|
||||
|
||||
{{source_tree_changes}}
|
||||
|
||||
### Technical Approach
|
||||
|
||||
{{technical_approach}}
|
||||
|
||||
### Existing Patterns to Follow
|
||||
|
||||
{{existing_patterns}}
|
||||
|
||||
### Integration Points
|
||||
|
||||
{{integration_points}}
|
||||
|
||||
---
|
||||
|
||||
## Development Context
|
||||
|
||||
### Relevant Existing Code
|
||||
|
||||
{{existing_code_references}}
|
||||
|
||||
### Dependencies
|
||||
|
||||
**Framework/Libraries:**
|
||||
|
||||
{{framework_dependencies}}
|
||||
|
||||
**Internal Modules:**
|
||||
|
||||
{{internal_dependencies}}
|
||||
|
||||
### Configuration Changes
|
||||
|
||||
{{configuration_changes}}
|
||||
|
||||
### Existing Conventions (Brownfield)
|
||||
|
||||
{{existing_conventions}}
|
||||
|
||||
### Test Framework & Standards
|
||||
|
||||
{{test_framework_info}}
|
||||
|
||||
---
|
||||
|
||||
## Implementation Stack
|
||||
|
||||
{{implementation_stack}}
|
||||
|
||||
---
|
||||
|
||||
## Technical Details
|
||||
|
||||
{{technical_details}}
|
||||
|
||||
---
|
||||
|
||||
## Development Setup
|
||||
|
||||
{{development_setup}}
|
||||
|
||||
---
|
||||
|
||||
## Implementation Guide
|
||||
|
||||
### Setup Steps
|
||||
|
||||
{{setup_steps}}
|
||||
|
||||
### Implementation Steps
|
||||
|
||||
{{implementation_steps}}
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
{{testing_strategy}}
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
{{acceptance_criteria}}
|
||||
|
||||
---
|
||||
|
||||
## Developer Resources
|
||||
|
||||
### File Paths Reference
|
||||
|
||||
{{file_paths_complete}}
|
||||
|
||||
### Key Code Locations
|
||||
|
||||
{{key_code_locations}}
|
||||
|
||||
### Testing Locations
|
||||
|
||||
{{testing_locations}}
|
||||
|
||||
### Documentation to Update
|
||||
|
||||
{{documentation_updates}}
|
||||
|
||||
---
|
||||
|
||||
## UX/UI Considerations
|
||||
|
||||
{{ux_ui_considerations}}
|
||||
|
||||
---
|
||||
|
||||
## Testing Approach
|
||||
|
||||
{{testing_approach}}
|
||||
|
||||
---
|
||||
|
||||
## Deployment Strategy
|
||||
|
||||
### Deployment Steps
|
||||
|
||||
{{deployment_steps}}
|
||||
|
||||
### Rollback Plan
|
||||
|
||||
{{rollback_plan}}
|
||||
|
||||
### Monitoring
|
||||
|
||||
{{monitoring_approach}}
|
||||
@@ -0,0 +1,87 @@
|
||||
# Story: {{story_title}}
|
||||
|
||||
Status: Draft
|
||||
|
||||
## Story
|
||||
|
||||
As a {{role}},
|
||||
I want {{capability}},
|
||||
so that {{benefit}}.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
{{acceptance_criteria}}
|
||||
|
||||
## Tasks / Subtasks
|
||||
|
||||
{{tasks_subtasks}}
|
||||
|
||||
## Dev Notes
|
||||
|
||||
### Technical Summary
|
||||
|
||||
{{technical_summary}}
|
||||
|
||||
### Tech-Spec Reference
|
||||
|
||||
**Full details:** See [tech-spec.md](../tech-spec.md)
|
||||
|
||||
The tech-spec contains comprehensive context including:
|
||||
|
||||
- Brownfield codebase analysis (if applicable)
|
||||
- Framework and library details with versions
|
||||
- Existing patterns to follow
|
||||
- Integration points and dependencies
|
||||
- Complete implementation guidance
|
||||
|
||||
### Project Structure Notes
|
||||
|
||||
- **Files to modify:** {{files_to_modify}}
|
||||
- **Expected test locations:** {{test_locations}}
|
||||
- **Estimated effort:** {{story_points}} story points ({{time_estimate}})
|
||||
- **Dependencies:** {{dependencies}}
|
||||
|
||||
### Key Code References
|
||||
|
||||
{{existing_code_references}}
|
||||
|
||||
### References
|
||||
|
||||
- **Tech Spec:** [tech-spec.md](../tech-spec.md) - Primary context document
|
||||
- **Architecture:** {{architecture_references}}
|
||||
|
||||
---
|
||||
|
||||
## Dev Agent Record
|
||||
|
||||
### Context Reference
|
||||
|
||||
**Primary Context:** [tech-spec.md](../tech-spec.md) - Contains all brownfield analysis, framework details, and implementation guidance
|
||||
|
||||
<!-- Additional context XML paths will be added here if story-context workflow is run -->
|
||||
|
||||
### Agent Model Used
|
||||
|
||||
<!-- Will be populated during dev-story execution -->
|
||||
|
||||
### Debug Log References
|
||||
|
||||
<!-- Will be populated during dev-story execution -->
|
||||
|
||||
### Completion Notes List
|
||||
|
||||
<!-- Will be populated during dev-story execution -->
|
||||
|
||||
### File List
|
||||
|
||||
<!-- Will be populated during dev-story execution -->
|
||||
|
||||
### Test Results
|
||||
|
||||
<!-- Will be populated during dev-story execution -->
|
||||
|
||||
---
|
||||
|
||||
## Review Notes
|
||||
|
||||
<!-- Will be populated during code review -->
|
||||
60
bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
Normal file
60
bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
Normal file
@@ -0,0 +1,60 @@
|
||||
# Technical Specification Workflow (Level 0)
|
||||
name: tech-spec-sm
|
||||
description: "Technical specification workflow for Level 0 projects (single atomic changes). Creates focused tech spec for bug fixes, single endpoint additions, or small isolated changes. Tech-spec only - no PRD needed."
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
project_name: "{config_source}:project_name"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
date: system-generated
|
||||
|
||||
# Runtime variables (captured during workflow execution)
|
||||
project_level: runtime-captured
|
||||
project_type: runtime-captured
|
||||
development_context: runtime-captured
|
||||
change_type: runtime-captured
|
||||
field_type: runtime-captured
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
template: "{installed_path}/tech-spec-template.md"
|
||||
|
||||
# Story generation instructions (invoked based on level)
|
||||
instructions_level0_story: "{installed_path}/instructions-level0-story.md"
|
||||
instructions_level1_stories: "{installed_path}/instructions-level1-stories.md"
|
||||
|
||||
# Templates
|
||||
user_story_template: "{installed_path}/user-story-template.md"
|
||||
epics_template: "{installed_path}/epics-template.md"
|
||||
|
||||
# Output configuration
|
||||
default_output_file: "{output_folder}/tech-spec.md"
|
||||
user_story_file: "{output_folder}/user-story.md"
|
||||
epics_file: "{output_folder}/epics.md"
|
||||
|
||||
# Recommended input documents (optional for Level 0)
|
||||
recommended_inputs:
|
||||
- bug_report: "Bug description or issue ticket"
|
||||
- feature_request: "Brief feature description"
|
||||
|
||||
# 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
|
||||
Reference in New Issue
Block a user