bmad-method 5.1.3 → 6.0.0-alpha.0

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

@@ -0,0 +1,137 @@
+# PRD Workflow - Small Projects (Level 0)
+
+<workflow>
+
+<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This is the SMALL instruction set for Level 0 projects - tech-spec only</critical>
+<critical>Project analysis already completed - proceeding directly to technical specification</critical>
+<critical>NO PRD generated - uses tech_spec_template only</critical>
+
+<step n="1" goal="Confirm project scope">
+
+<action>Load project-workflow-analysis.md</action>
+<action>Confirm Level 0 - Single atomic change</action>
+
+<ask>Please describe the specific change/fix you need to implement:</ask>
+
+</step>
+
+<step n="2" goal="Generate DEFINITIVE tech spec">
+
+<critical>Generate tech-spec.md - this is the TECHNICAL SOURCE OF TRUTH</critical>
+<critical>ALL TECHNICAL DECISIONS MUST BE DEFINITIVE - NO AMBIGUITY ALLOWED</critical>
+
+<action>Initialize tech-spec.md using tech_spec_template from workflow.yaml</action>
+
+<critical>DEFINITIVE DECISIONS REQUIRED:</critical>
+
+**BAD Examples (NEVER DO THIS):**
+
+- "Python 2 or 3" ❌
+- "Use a logger like pino or winston" ❌
+
+**GOOD Examples (ALWAYS DO THIS):**
+
+- "Python 3.11" ✅
+- "winston v3.8.2 for logging" ✅
+
+**Source Tree Structure**: EXACT file changes needed
+<template-output file="tech-spec.md">source_tree</template-output>
+
+**Technical Approach**: SPECIFIC implementation for the change
+<template-output file="tech-spec.md">technical_approach</template-output>
+
+**Implementation Stack**: DEFINITIVE tools and versions
+<template-output file="tech-spec.md">implementation_stack</template-output>
+
+**Technical Details**: PRECISE change details
+<template-output file="tech-spec.md">technical_details</template-output>
+
+**Testing Approach**: How to verify the change
+<template-output file="tech-spec.md">testing_approach</template-output>
+
+**Deployment Strategy**: How to deploy the change
+<template-output file="tech-spec.md">deployment_strategy</template-output>
+
+<elicit-required/>
+
+</step>
+
+<step n="3" goal="Validate cohesion" optional="true">
+
+<action>Offer to run cohesion validation</action>
+
+<ask>Tech-spec complete! Before proceeding to implementation, would you like to validate project cohesion?
+
+**Cohesion Validation** checks:
+
+- Tech spec completeness and definitiveness
+- Feature sequencing and dependencies
+- External dependencies properly planned
+- User/agent responsibilities clear
+- Greenfield/brownfield-specific considerations
+
+Run cohesion validation? (y/n)</ask>
+
+<check>If yes:</check>
+<action>Load {installed_path}/checklist.md</action>
+<action>Review tech-spec.md against "Cohesion Validation (All Levels)" section</action>
+<action>Focus on Section A (Tech Spec), Section D (Feature Sequencing)</action>
+<action>Apply Section B (Greenfield) or Section C (Brownfield) based on field_type</action>
+<action>Generate validation report with findings</action>
+
+</step>
+
+<step n="4" goal="Finalize and determine next steps">
+
+<action>Confirm tech-spec is complete and definitive</action>
+<action>No PRD needed for Level 0</action>
+<action>Ready for implementation</action>
+
+## Summary
+
+- **Level 0 Output**: tech-spec.md only
+- **No PRD required**
+- **Direct to implementation**
+
+## Next Steps Checklist
+
+<action>Determine appropriate next steps for Level 0 atomic change</action>
+
+<check>If change involves UI components:</check>
+
+**Optional Next Steps:**
+
+- [ ] **Create simple UX documentation** (if UI change is user-facing)
+  - Note: Full instructions-ux workflow may be overkill for Level 0
+  - Consider documenting just the specific UI change
+
+- [ ] **Generate implementation task**
+  - Command: `workflow task-generation`
+  - Uses: tech-spec.md
+
+<check>If change is backend/API only:</check>
+
+**Recommended Next Steps:**
+
+- [ ] **Create test plan** for the change
+  - Unit tests for the specific change
+  - Integration test if affects other components
+
+- [ ] **Generate implementation task**
+  - Command: `workflow task-generation`
+  - Uses: tech-spec.md
+
+<ask>Level 0 planning complete! Next action:
+
+1. Proceed to implementation
+2. Generate development task
+3. Create test plan
+4. Exit workflow
+
+Select option (1-4):</ask>
+
+</step>
+
+</workflow>

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

@@ -0,0 +1,59 @@
+# {{project_name}} - Technical Specification
+
+**Author:** {{user_name}}
+**Date:** {{date}}
+**Project Level:** {{project_level}}
+**Project Type:** {{project_type}}
+**Development Context:** {{development_context}}
+
+---
+
+## Source Tree Structure
+
+{{source_tree}}
+
+---
+
+## Technical Approach
+
+{{technical_approach}}
+
+---
+
+## Implementation Stack
+
+{{implementation_stack}}
+
+---
+
+## Technical Details
+
+{{technical_details}}
+
+---
+
+## Development Setup
+
+{{development_setup}}
+
+---
+
+## Implementation Guide
+
+{{implementation_guide}}
+
+---
+
+## Testing Approach
+
+{{testing_approach}}
+
+---
+
+## Deployment Strategy
+
+{{deployment_strategy}}
+
+---
+
+_This tech spec is for Level 0-2 projects (BMad Method v6). It provides the technical details needed for implementation. Level 3+ projects use the separate architecture workflow for comprehensive technical design._

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

@@ -0,0 +1,360 @@
+# UX/UI Specification Workflow Instructions
+
+<workflow>
+
+<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This workflow creates comprehensive UX/UI specifications - can run standalone or as part of plan-project</critical>
+<critical>Uses ux-spec-template.md for structured output generation</critical>
+<critical>Can optionally generate AI Frontend Prompts for tools like Vercel v0, Lovable.ai</critical>
+
+<step n="1" goal="Load context and analyze project requirements">
+
+<action>Determine workflow mode (standalone or integrated)</action>
+
+<check>If mode="standalone":</check>
+<ask>Do you have an existing PRD or requirements document? (y/n)
+
+If yes: Provide the path to the PRD
+If no: We'll gather basic requirements to create the UX spec
+</ask>
+
+<check>If no PRD in standalone mode:</check>
+<ask>Let's gather essential information:
+
+1. **Project Description**: What are you building?
+2. **Target Users**: Who will use this?
+3. **Core Features**: What are the main capabilities? (3-5 key features)
+4. **Platform**: Web, mobile, desktop, or multi-platform?
+5. **Existing Brand/Design**: Any existing style guide or brand to follow?
+   </ask>
+
+<check>If PRD exists or integrated mode:</check>
+<action>Load the following documents if available:</action>
+
+- PRD.md (primary source for requirements and user journeys)
+- epics.md or epic-stories.md (helps understand feature grouping)
+- tech-spec.md (understand technical constraints)
+- architecture.md (if Level 3-4 project)
+- project-workflow-analysis.md (understand project level and scope)
+
+<action>Analyze project for UX complexity:</action>
+
+- Number of user-facing features
+- Types of users/personas mentioned
+- Interaction complexity
+- Platform requirements (web, mobile, desktop)
+
+<action>Load ux-spec-template from workflow.yaml</action>
+
+<template-output>project_context</template-output>
+
+</step>
+
+<step n="2" goal="Define UX goals and principles">
+
+<ask>Let's establish the UX foundation. Based on the PRD:
+
+**1. Target User Personas** (extract from PRD or define):
+
+- Primary persona(s)
+- Secondary persona(s)
+- Their goals and pain points
+
+**2. Key Usability Goals:**
+What does success look like for users?
+
+- Ease of learning?
+- Efficiency for power users?
+- Error prevention?
+- Accessibility requirements?
+
+**3. Core Design Principles** (3-5 principles):
+What will guide all design decisions?
+</ask>
+
+<template-output>user_personas</template-output>
+<template-output>usability_goals</template-output>
+<template-output>design_principles</template-output>
+
+<elicit-required/>
+
+</step>
+
+<step n="3" goal="Create information architecture">
+
+<action>Based on functional requirements from PRD, create site/app structure</action>
+
+**Create comprehensive site map showing:**
+
+- All major sections/screens
+- Hierarchical relationships
+- Navigation paths
+
+<template-output>site_map</template-output>
+
+**Define navigation structure:**
+
+- Primary navigation items
+- Secondary navigation approach
+- Mobile navigation strategy
+- Breadcrumb structure
+
+<template-output>navigation_structure</template-output>
+
+<elicit-required/>
+
+</step>
+
+<step n="4" goal="Design user flows for critical paths">
+
+<action>Extract key user journeys from PRD</action>
+<action>For each critical user task, create detailed flow</action>
+
+<for-each journey="user_journeys_from_prd">
+
+**Flow: {{journey_name}}**
+
+Define:
+
+- User goal
+- Entry points
+- Step-by-step flow with decision points
+- Success criteria
+- Error states and edge cases
+
+Create Mermaid diagram showing complete flow.
+
+<template-output>user*flow*{{journey_number}}</template-output>
+
+</for-each>
+
+<elicit-required/>
+
+</step>
+
+<step n="5" goal="Define component library approach">
+
+<ask>Component Library Strategy:
+
+**1. Design System Approach:**
+
+- [ ] Use existing system (Material UI, Ant Design, etc.)
+- [ ] Create custom component library
+- [ ] Hybrid approach
+
+**2. If using existing, which one?**
+
+**3. Core Components Needed** (based on PRD features):
+We'll need to define states and variants for key components.
+</ask>
+
+<action>For primary components, define:</action>
+
+- Component purpose
+- Variants needed
+- States (default, hover, active, disabled, error)
+- Usage guidelines
+
+<template-output>design_system_approach</template-output>
+<template-output>core_components</template-output>
+
+</step>
+
+<step n="6" goal="Establish visual design foundation">
+
+<ask>Visual Design Foundation:
+
+**1. Brand Guidelines:**
+Do you have existing brand guidelines to follow? (y/n)
+
+**2. If yes, provide link or key elements.**
+
+**3. If no, let's define basics:**
+
+- Primary brand personality (professional, playful, minimal, bold)
+- Industry conventions to follow or break
+  </ask>
+
+<action>Define color palette with semantic meanings</action>
+
+<template-output>color_palette</template-output>
+
+<action>Define typography system</action>
+
+<template-output>font_families</template-output>
+<template-output>type_scale</template-output>
+
+<action>Define spacing and layout grid</action>
+
+<template-output>spacing_layout</template-output>
+
+<elicit-required/>
+
+</step>
+
+<step n="7" goal="Define responsive and accessibility strategy">
+
+**Responsive Design:**
+
+<action>Define breakpoints based on target devices from PRD</action>
+
+<template-output>breakpoints</template-output>
+
+<action>Define adaptation patterns for different screen sizes</action>
+
+<template-output>adaptation_patterns</template-output>
+
+**Accessibility Requirements:**
+
+<action>Based on deployment intent from PRD, define compliance level</action>
+
+<template-output>compliance_target</template-output>
+<template-output>accessibility_requirements</template-output>
+
+</step>
+
+<step n="8" goal="Document interaction patterns" optional="true">
+
+<ask>Would you like to define animation and micro-interactions? (y/n)
+
+This is recommended for:
+
+- Consumer-facing applications
+- Projects emphasizing user delight
+- Complex state transitions
+  </ask>
+
+<check>If yes:</check>
+
+<action>Define motion principles</action>
+<template-output>motion_principles</template-output>
+
+<action>Define key animations and transitions</action>
+<template-output>key_animations</template-output>
+
+</step>
+
+<step n="9" goal="Create wireframes and design references" optional="true">
+
+<ask>Design File Strategy:
+
+**1. Will you be creating high-fidelity designs?**
+
+- [ ] Yes, in Figma
+- [ ] Yes, in Sketch
+- [ ] Yes, in Adobe XD
+- [ ] No, development from spec
+- [ ] Other: **\_\_\_\_**
+
+**2. For key screens, should we:**
+
+- [ ] Reference design file locations
+- [ ] Create low-fi wireframe descriptions
+- [ ] Skip visual representations
+      </ask>
+
+<check>If design files will be created:</check>
+<template-output>design_files</template-output>
+
+<check>If wireframe descriptions needed:</check>
+<for-each screen="key_screens">
+<template-output>screen*layout*{{screen_number}}</template-output>
+</for-each>
+
+</step>
+
+<step n="10" goal="Generate next steps and output options">
+
+## UX Specification Complete
+
+<action>Generate specific next steps based on project level and outputs</action>
+
+<template-output>immediate_actions</template-output>
+
+**Design Handoff Checklist:**
+
+- [ ] All user flows documented
+- [ ] Component inventory complete
+- [ ] Accessibility requirements defined
+- [ ] Responsive strategy clear
+- [ ] Brand guidelines incorporated
+- [ ] Performance goals established
+
+<check>If Level 3-4 project:</check>
+
+- [ ] Ready for detailed visual design
+- [ ] Frontend architecture can proceed
+- [ ] Story generation can include UX details
+
+<check>If Level 1-2 project or standalone:</check>
+
+- [ ] Development can proceed with spec
+- [ ] Component implementation order defined
+- [ ] MVP scope clear
+
+<template-output>design_handoff_checklist</template-output>
+
+<ask>UX Specification saved to {{ux_spec_file}}
+
+**Additional Output Options:**
+
+1. Generate AI Frontend Prompt (for Vercel v0, Lovable.ai, etc.)
+2. Review UX specification
+3. Create/update visual designs in design tool
+4. Return to planning workflow (if not standalone)
+5. Exit
+
+Would you like to generate an AI Frontend Prompt? (y/n):</ask>
+
+<check>If user selects yes or option 1:</check>
+<goto step="11">Generate AI Frontend Prompt</goto>
+
+</step>
+
+<step n="11" goal="Generate AI Frontend Prompt" optional="true">
+
+<action>Prepare context for AI Frontend Prompt generation</action>
+
+<ask>What type of AI frontend generation are you targeting?
+
+1. **Full application** - Complete multi-page application
+2. **Single page** - One complete page/screen
+3. **Component set** - Specific components or sections
+4. **Design system** - Component library setup
+
+Select option (1-4):</ask>
+
+<action>Gather UX spec details for prompt generation:</action>
+
+- Design system approach
+- Color palette and typography
+- Key components and their states
+- User flows to implement
+- Responsive requirements
+
+<invoke-task>{project-root}/bmad/bmm/tasks/ai-fe-prompt.md</invoke-task>
+
+<action>Save AI Frontend Prompt to {{ai_frontend_prompt_file}}</action>
+
+<ask>AI Frontend Prompt saved to {{ai_frontend_prompt_file}}
+
+This prompt is optimized for:
+
+- Vercel v0
+- Lovable.ai
+- Other AI frontend generation tools
+
+**Remember**: AI-generated code requires careful review and testing!
+
+Next actions:
+
+1. Copy prompt to AI tool
+2. Return to UX specification
+3. Exit workflow
+
+Select option (1-3):</ask>
+
+</step>
+
+</workflow>

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

@@ -0,0 +1,162 @@
+# {{project_name}} UX/UI Specification
+
+_Generated on {{date}} by {{user_name}}_
+
+## Executive Summary
+
+{{project_context}}
+
+---
+
+## 1. UX Goals & Principles
+
+### 1.1 Target User Personas
+
+{{user_personas}}
+
+### 1.2 Usability Goals
+
+{{usability_goals}}
+
+### 1.3 Design Principles
+
+{{design_principles}}
+
+---
+
+## 2. Information Architecture
+
+### 2.1 Site Map
+
+{{site_map}}
+
+### 2.2 Navigation Structure
+
+{{navigation_structure}}
+
+---
+
+## 3. User Flows
+
+{{user_flow_1}}
+
+{{user_flow_2}}
+
+{{user_flow_3}}
+
+{{user_flow_4}}
+
+{{user_flow_5}}
+
+---
+
+## 4. Component Library & Design System
+
+### 4.1 Design System Approach
+
+{{design_system_approach}}
+
+### 4.2 Core Components
+
+{{core_components}}
+
+---
+
+## 5. Visual Design Foundation
+
+### 5.1 Color Palette
+
+{{color_palette}}
+
+### 5.2 Typography
+
+**Font Families:**
+{{font_families}}
+
+**Type Scale:**
+{{type_scale}}
+
+### 5.3 Spacing & Layout
+
+{{spacing_layout}}
+
+---
+
+## 6. Responsive Design
+
+### 6.1 Breakpoints
+
+{{breakpoints}}
+
+### 6.2 Adaptation Patterns
+
+{{adaptation_patterns}}
+
+---
+
+## 7. Accessibility
+
+### 7.1 Compliance Target
+
+{{compliance_target}}
+
+### 7.2 Key Requirements
+
+{{accessibility_requirements}}
+
+---
+
+## 8. Interaction & Motion
+
+### 8.1 Motion Principles
+
+{{motion_principles}}
+
+### 8.2 Key Animations
+
+{{key_animations}}
+
+---
+
+## 9. Design Files & Wireframes
+
+### 9.1 Design Files
+
+{{design_files}}
+
+### 9.2 Key Screen Layouts
+
+{{screen_layout_1}}
+
+{{screen_layout_2}}
+
+{{screen_layout_3}}
+
+---
+
+## 10. Next Steps
+
+### 10.1 Immediate Actions
+
+{{immediate_actions}}
+
+### 10.2 Design Handoff Checklist
+
+{{design_handoff_checklist}}
+
+---
+
+## Appendix
+
+### Related Documents
+
+- PRD: `{{prd}}`
+- Epics: `{{epics}}`
+- Tech Spec: `{{tech_spec}}`
+- Architecture: `{{architecture}}`
+
+### Version History
+
+| Date     | Version | Changes               | Author        |
+| -------- | ------- | --------------------- | ------------- |
+| {{date}} | 1.0     | Initial specification | {{user_name}} |