bmad-method 5.1.3 → 6.0.0-alpha.0

package/src/modules/bmb/workflows/edit-workflow/checklist.md

@@ -0,0 +1,70 @@
+# Edit Workflow - Validation Checklist
+
+## Pre-Edit Analysis
+
+- [ ] Target workflow.yaml file successfully loaded and parsed
+- [ ] All referenced workflow files identified and accessible
+- [ ] Workflow type correctly determined (document/action/interactive/autonomous/meta)
+- [ ] Best practices guide loaded and available for reference
+
+## Edit Execution Quality
+
+- [ ] User clearly informed of identified issues with priority levels
+- [ ] Edit menu presented with all 8 standard options
+- [ ] Selected edit type matches the actual changes made
+- [ ] All proposed changes explained with reasoning before application
+
+## File Integrity
+
+- [ ] All modified files maintain valid YAML/Markdown syntax
+- [ ] No placeholders like {TITLE} or {WORKFLOW_CODE} remain in edited files
+- [ ] File paths use proper variable substitution ({project-root}, {installed_path})
+- [ ] All file references resolve to actual paths
+
+## Convention Compliance
+
+- [ ] Instructions.md contains critical workflow engine reference header
+- [ ] Instructions.md contains workflow.yaml processing reference header
+- [ ] All step numbers are sequential (1, 2, 3... or 1a, 1b, 2a...)
+- [ ] Each step has both n= attribute and goal= attribute
+- [ ] Variable names use snake_case consistently
+- [ ] Template variables (if any) match <template-output> tags exactly
+
+## Instruction Quality
+
+- [ ] Each step has a single, clear goal stated
+- [ ] Instructions are specific with quantities (e.g., "3-5 items" not "several items")
+- [ ] Optional steps marked with optional="true" attribute
+- [ ] Repeating steps use proper repeat syntax (repeat="3" or repeat="until-complete")
+- [ ] User prompts use <ask> tags and wait for response
+- [ ] Actions use <action> tags for required operations
+
+## Validation Criteria (if checklist.md exists)
+
+- [ ] All checklist items are measurable and specific
+- [ ] No vague criteria like "Good documentation" present
+- [ ] Checklist organized into logical sections
+- [ ] Each criterion can be objectively verified as true/false
+
+## Change Documentation
+
+- [ ] All changes logged with description of what and why
+- [ ] Change summary includes list of modified files
+- [ ] Improvements clearly articulated in relation to best practices
+- [ ] Next steps or recommendations provided
+
+## Post-Edit Verification
+
+- [ ] Edited workflow follows patterns from production examples
+- [ ] No functionality broken by the edits
+- [ ] Workflow ready for testing or production use
+- [ ] User given option to test the edited workflow
+
+## Common Issues Resolved
+
+- [ ] Missing critical headers added if they were absent
+- [ ] Broken variable references fixed
+- [ ] Vague instructions made specific
+- [ ] Template-only workflows have template.md file
+- [ ] Action workflows have template: false in workflow.yaml
+- [ ] Step count reasonable (5-10 steps maximum unless justified)

package/src/modules/bmb/workflows/edit-workflow/instructions.md

@@ -0,0 +1,170 @@
+# Edit Workflow - Workflow Editor Instructions
+
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.md</critical>
+<critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml</critical>
+<critical>Study the workflow creation guide thoroughly at: {workflow_creation_guide}</critical>
+
+<workflow>
+
+<step n="1" goal="Load and analyze target workflow">
+<ask>What is the path to the workflow you want to edit? (provide path to workflow.yaml or workflow folder)</ask>
+
+<action>Load the workflow.yaml file from the provided path</action>
+<action>Identify the workflow type (document, action, interactive, autonomous, meta)</action>
+<action>List all associated files (template.md, instructions.md, checklist.md, data files)</action>
+<action>Load any existing instructions.md and template.md files if present</action>
+
+Display a summary:
+
+- Workflow name and description
+- Type of workflow
+- Files present
+- Current structure overview
+  </step>
+
+<step n="2" goal="Analyze against best practices">
+<action>Load the complete workflow creation guide from: {workflow_creation_guide}</action>
+<action>Check the workflow against the guide's best practices:</action>
+
+Analyze for:
+
+- **Critical headers**: Are workflow engine references present?
+- **File structure**: Are all expected files present for this workflow type?
+- **Variable consistency**: Do variable names match between files?
+- **Step structure**: Are steps properly numbered and focused?
+- **XML tags**: Are tags used correctly and consistently?
+- **Instructions clarity**: Are instructions specific with examples and limits?
+- **Template variables**: Use snake_case and descriptive names?
+- **Validation criteria**: Are checklist items measurable and specific?
+
+<action>Create a list of identified issues or improvement opportunities</action>
+<action>Prioritize issues by importance (critical, important, nice-to-have)</action>
+</step>
+
+<step n="3" goal="Select editing focus">
+Present the editing menu to the user:
+
+**What aspect would you like to edit?**
+
+1. **Fix critical issues** - Address missing headers, broken references
+2. **Update workflow.yaml** - Modify configuration, paths, metadata
+3. **Refine instructions** - Improve steps, add detail, fix flow
+4. **Update template** - Fix variables, improve structure (if applicable)
+5. **Enhance validation** - Make checklist more specific and measurable
+6. **Add new features** - Add steps, optional sections, or capabilities
+7. **Optimize for clarity** - Improve descriptions, add examples
+8. **Full review and update** - Comprehensive improvements across all files
+
+<ask>Select an option (1-8) or describe a custom edit:</ask>
+</step>
+
+<step n="4" goal="Load relevant documentation">
+Based on the selected edit type, load appropriate reference materials:
+
+<check>If editing instructions or adding features:</check>
+<action>Review the "Writing Instructions" section of the creation guide</action>
+<action>Load example workflows from {project-root}/bmad/bmm/workflows/ for patterns</action>
+
+<check>If editing templates:</check>
+<action>Review the "Templates & Variables" section of the creation guide</action>
+<action>Ensure variable naming conventions are followed</action>
+
+<check>If editing validation:</check>
+<action>Review the "Validation" section and measurable criteria examples</action>
+
+<check>If fixing critical issues:</check>
+<action>Load the workflow execution engine documentation</action>
+<action>Verify all required elements are present</action>
+</step>
+
+<step n="5" goal="Perform edits" repeat="until-complete">
+Based on the selected focus area:
+
+<action>Show the current content that will be edited</action>
+<action>Explain the proposed changes and why they improve the workflow</action>
+<action>Generate the updated content following all conventions from the guide</action>
+
+<ask>Review the proposed changes. Options:
+
+- [a] Accept and apply
+- [e] Edit/modify the changes
+- [s] Skip this change
+- [n] Move to next file/section
+- [d] Done with edits
+  </ask>
+
+<check>If user selects 'a':</check>
+<action>Apply the changes to the file</action>
+<action>Log the change for the summary</action>
+
+<check>If user selects 'e':</check>
+<ask>What modifications would you like to make?</ask>
+<goto step="5">Regenerate with modifications</goto>
+
+<check>If user selects 'd':</check>
+<continue>Proceed to validation</continue>
+</step>
+
+<step n="6" goal="Validate all changes" optional="true">
+<action>Run a comprehensive validation check:</action>
+
+Validation checks:
+
+- [ ] All file paths resolve correctly
+- [ ] Variable names are consistent across files
+- [ ] Step numbering is sequential and logical
+- [ ] Required XML tags are properly formatted
+- [ ] No placeholders remain (like {TITLE} or {WORKFLOW_CODE})
+- [ ] Instructions match the workflow type
+- [ ] Template variables match instruction outputs (if applicable)
+- [ ] Checklist criteria are measurable (if present)
+- [ ] Critical headers are present in instructions
+- [ ] YAML syntax is valid
+
+<check>If any validation fails:</check>
+<ask>Issues found. Would you like to fix them? (y/n)</ask>
+<check>If yes:</check>
+<goto step="5">Return to editing</goto>
+</step>
+
+<step n="7" goal="Generate change summary">
+Create a summary of all changes made:
+
+## Workflow Edit Summary
+
+**Workflow:** {{workflow_name}}
+**Date:** {{date}}
+**Editor:** {{user_name}}
+
+### Changes Made:
+
+<action>List each file that was modified with a brief description of changes</action>
+
+### Improvements:
+
+<action>Summarize how the workflow is now better aligned with best practices</action>
+
+### Files Modified:
+
+<action>List all modified files with their paths</action>
+
+### Next Steps:
+
+<action>Suggest any additional improvements or testing that could be done</action>
+
+<ask>Would you like to:
+
+- Save this summary to: {change_log_output}
+- Test the edited workflow
+- Make additional edits
+- Exit
+  </ask>
+
+<check>If save summary:</check>
+<action>Write the summary to the change log file</action>
+
+<check>If test workflow:</check>
+<invoke-workflow>{{workflow_name}}</invoke-workflow>
+</step>
+
+</workflow>

package/src/modules/bmb/workflows/edit-workflow/workflow.yaml

@@ -0,0 +1,34 @@
+# Edit Workflow - Workflow Editor Configuration
+name: "edit-workflow"
+description: "Edit existing BMAD workflows while following all best practices and conventions"
+author: "BMad"
+
+# Critical variables load from config_source
+config_source: "{project-root}/bmad/bmb/config.yaml"
+output_folder: "{config_source}:output_folder"
+src_impact: "{config_source}:src_impact"
+communication_language: "{config_source}:communication_language"
+user_name: "{config_source}:user_name"
+date: system-generated
+
+# Required Data Files - Critical for understanding workflow conventions
+workflow_creation_guide: "{project-root}/bmad/bmb/workflows/build-workflow/workflow-creation-guide.md"
+workflow_execution_engine: "{project-root}/bmad/core/tasks/workflow.md"
+
+# Optional docs that can be used to understand the target workflow
+recommended_inputs:
+  - target_workflow: "Path to the workflow.yaml file to edit"
+  - workflow_examples: "{project-root}/bmad/bmm/workflows/"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmb/workflows/edit-workflow"
+template: false # This is an action workflow - no template needed
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# No output file for action workflows
+# But we may generate a change log
+change_log_output: "{output_folder}/workflow-edit-log-{{date}}.md"
+
+# No special tools required for editing workflows
+required_tools: []

package/src/modules/bmb/workflows/module-brief/README.md

@@ -0,0 +1,264 @@
+# Module Brief Workflow
+
+## Overview
+
+The Module Brief workflow creates comprehensive blueprints for building new BMAD modules using strategic analysis and creative vision. It serves as the essential planning phase that transforms initial ideas into detailed, actionable specifications ready for implementation with the build-module workflow.
+
+## Key Features
+
+- **Strategic Module Planning** - Comprehensive analysis from concept to implementation roadmap
+- **Multi-Mode Operation** - Interactive, Express, and YOLO modes for different planning needs
+- **Creative Vision Development** - Guided process for innovative module concepts and unique value propositions
+- **Architecture Design** - Detailed agent and workflow ecosystem planning with interaction models
+- **User Journey Mapping** - Scenario-based validation ensuring practical usability
+- **Technical Planning** - Infrastructure requirements, dependencies, and complexity assessment
+- **Risk Assessment** - Proactive identification of challenges with mitigation strategies
+- **Implementation Roadmap** - Phased development plan with clear deliverables and timelines
+
+## Usage
+
+### Basic Invocation
+
+```bash
+workflow module-brief
+```
+
+### With Brainstorming Input
+
+```bash
+# If you have brainstorming results from previous sessions
+workflow module-brief --input brainstorming-session-2024-09-26.md
+```
+
+### Express Mode
+
+```bash
+# For quick essential planning only
+workflow module-brief --mode express
+```
+
+### Configuration
+
+The workflow uses standard BMB configuration:
+
+- **output_folder**: Where the module brief will be saved
+- **user_name**: Brief author information
+- **communication_language**: Language for brief generation
+- **date**: Automatic timestamp for versioning
+
+## Workflow Structure
+
+### Files Included
+
+```
+module-brief/
+├── workflow.yaml           # Configuration and metadata
+├── instructions.md         # Step-by-step execution guide
+├── template.md            # Module brief document structure
+├── checklist.md           # Validation criteria
+└── README.md              # This file
+```
+
+## Workflow Process
+
+### Phase 1: Foundation & Context (Steps 1-3)
+
+**Mode Selection & Input Gathering**
+
+- Choose operational mode (Interactive, Express, YOLO)
+- Check for and optionally load existing brainstorming results
+- Gather background context and inspiration sources
+
+**Module Vision Development**
+
+- Define core problem the module solves
+- Identify target user audience and use cases
+- Establish unique value proposition and differentiators
+- Explore creative themes and personality concepts
+
+**Module Identity Establishment**
+
+- Generate module code (kebab-case) with multiple options
+- Create compelling, memorable module name
+- Select appropriate category (Domain-Specific, Creative, Technical, Business, Personal)
+- Define optional personality theme for consistent agent character
+
+### Phase 2: Architecture Planning (Steps 4-5)
+
+**Agent Architecture Design**
+
+- Plan agent team composition and roles
+- Define agent archetypes (Orchestrator, Specialist, Helper, Creator, Analyzer)
+- Specify personality traits and communication styles
+- Map key capabilities and signature commands
+
+**Workflow Ecosystem Design**
+
+- Categorize workflows by purpose and complexity:
+  - **Core Workflows**: Essential value-delivery functions (2-3)
+  - **Feature Workflows**: Specialized capabilities (3-5)
+  - **Utility Workflows**: Supporting operations (1-3)
+- Define input-process-output flows for each workflow
+- Assess complexity levels and implementation priorities
+
+### Phase 3: Validation & User Experience (Steps 6-7)
+
+**User Journey Mapping**
+
+- Create detailed user scenarios and stories
+- Map step-by-step usage flows through the module
+- Validate end-to-end functionality and value delivery
+- Identify potential friction points and optimization opportunities
+
+**Technical Planning & Requirements**
+
+- Assess data requirements and storage needs
+- Map integration points with other modules and external systems
+- Evaluate technical complexity and resource requirements
+- Document dependencies and infrastructure needs
+
+### Phase 4: Success Planning (Steps 8-9)
+
+**Success Metrics Definition**
+
+- Establish module success criteria and performance indicators
+- Define quality standards and reliability requirements
+- Create user experience goals and feedback mechanisms
+- Set measurable outcomes for module effectiveness
+
+**Development Roadmap Creation**
+
+- Design phased approach with MVP, Enhancement, and Polish phases
+- Define deliverables and timelines for each phase
+- Prioritize features and capabilities by value and complexity
+- Create clear milestones and success checkpoints
+
+### Phase 5: Enhancement & Risk Management (Steps 10-12)
+
+**Creative Features & Special Touches** (Optional)
+
+- Design easter eggs and delightful user interactions
+- Plan module lore and thematic consistency
+- Add personality quirks and creative responses
+- Develop backstories and universe building
+
+**Risk Assessment & Mitigation**
+
+- Identify technical, usability, and scope risks
+- Develop mitigation strategies for each risk category
+- Plan contingency approaches for potential challenges
+- Document decision points and alternative paths
+
+**Final Review & Export Preparation**
+
+- Comprehensive review of all brief sections
+- Validation against quality and completeness criteria
+- Preparation for seamless handoff to build-module workflow
+- Export readiness confirmation with actionable specifications
+
+## Output
+
+### Generated Files
+
+- **Module Brief Document**: Comprehensive planning document at `{output_folder}/module-brief-{module_code}-{date}.md`
+- **Strategic Specifications**: Ready-to-implement blueprint for build-module workflow
+
+### Output Structure
+
+The module brief contains detailed specifications across multiple sections:
+
+1. **Executive Summary** - Vision, category, complexity, target users
+2. **Module Identity** - Core concept, value proposition, personality theme
+3. **Agent Architecture** - Agent roster, roles, interaction models
+4. **Workflow Ecosystem** - Core, feature, and utility workflow specifications
+5. **User Scenarios** - Primary use cases, secondary scenarios, user journey
+6. **Technical Planning** - Data requirements, integrations, dependencies
+7. **Success Metrics** - Success criteria, quality standards, performance targets
+8. **Development Roadmap** - Phased implementation plan with deliverables
+9. **Creative Features** - Special touches, easter eggs, module lore
+10. **Risk Assessment** - Technical, usability, scope risks with mitigation
+11. **Implementation Notes** - Priority order, design decisions, open questions
+12. **Resources & References** - Inspiration sources, similar modules, technical references
+
+## Requirements
+
+- **Creative Vision** - Initial module concept or problem domain
+- **Strategic Thinking** - Ability to plan architecture and user experience
+- **Brainstorming Results** (optional) - Previous ideation sessions enhance planning quality
+
+## Best Practices
+
+### Before Starting
+
+1. **Gather Inspiration** - Research similar tools, modules, and solutions in your domain
+2. **Run Brainstorming Session** - Use ideation techniques to generate initial concepts
+3. **Define Success Criteria** - Know what "successful module" means for your context
+
+### During Execution
+
+1. **Think User-First** - Always consider the end user experience and value delivery
+2. **Be Specific** - Provide concrete examples and detailed specifications rather than abstractions
+3. **Validate Early** - Use user scenarios to test if the module concept actually works
+4. **Plan Iteratively** - Start with MVP and build complexity through phases
+
+### After Completion
+
+1. **Use as Blueprint** - Feed the brief directly into build-module workflow for implementation
+2. **Review with Stakeholders** - Validate assumptions and gather feedback before building
+3. **Update as Needed** - Treat as living document that evolves with implementation learnings
+4. **Reference During Development** - Use as north star for design decisions and scope management
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Stuck on module concept or vision
+
+- **Solution**: Use creative prompts provided in the workflow
+- **Check**: Review existing modules for inspiration and patterns
+
+**Issue**: Agent or workflow architecture too complex
+
+- **Solution**: Focus on MVP first, plan enhancement phases for additional complexity
+- **Check**: Validate each component against user scenarios
+
+**Issue**: Technical requirements unclear
+
+- **Solution**: Research similar modules and their implementation approaches
+- **Check**: Consult with technical stakeholders early in planning
+
+**Issue**: Scope creep during planning
+
+- **Solution**: Use phased roadmap to defer non-essential features
+- **Check**: Regularly validate against core user scenarios and success criteria
+
+## Customization
+
+To customize this workflow:
+
+1. **Modify Template Structure** - Update template.md to add new sections or reorganize content
+2. **Extend Creative Prompts** - Add domain-specific ideation techniques in instructions.md
+3. **Add Planning Tools** - Integrate additional analysis frameworks or planning methodologies
+4. **Customize Validation** - Enhance checklist.md with specific quality criteria for your context
+
+## Version History
+
+- **v1.0.0** - Initial release
+  - Comprehensive strategic module planning
+  - Multi-mode operation (Interactive, Express, YOLO)
+  - Creative vision and architecture design tools
+  - User journey mapping and validation
+  - Risk assessment and mitigation planning
+
+## Support
+
+For issues or questions:
+
+- Review the workflow creation guide at `/bmad/bmb/workflows/build-workflow/workflow-creation-guide.md`
+- Study existing module examples in `/bmad/` for patterns and inspiration
+- Validate output using `checklist.md`
+- Consult module structure guide at `build-module/module-structure.md`
+
+---
+
+_Part of the BMad Method v5 - BMB (Builder) Module_

package/src/modules/bmb/workflows/module-brief/checklist.md

@@ -0,0 +1,116 @@
+# Module Brief Validation Checklist
+
+## Core Identity
+
+- [ ] Module code follows kebab-case convention
+- [ ] Module name is clear and memorable
+- [ ] Module category is identified
+- [ ] Target users are clearly defined
+- [ ] Unique value proposition is articulated
+
+## Vision & Concept
+
+- [ ] Problem being solved is clearly stated
+- [ ] Solution approach is explained
+- [ ] Module scope is well-defined
+- [ ] Success criteria are measurable
+
+## Agent Architecture
+
+- [ ] At least one agent is defined
+- [ ] Each agent has a clear role and purpose
+- [ ] Agent personalities are defined (if using personality themes)
+- [ ] Agent interactions are mapped (for multi-agent modules)
+- [ ] Key commands for each agent are listed
+
+## Workflow Ecosystem
+
+- [ ] Core workflows (2-3) are identified
+- [ ] Each workflow has clear purpose
+- [ ] Workflow complexity is assessed
+- [ ] Input/output for workflows is defined
+- [ ] Workflow categories are logical
+
+## User Experience
+
+- [ ] Primary use case is documented
+- [ ] User scenarios demonstrate value
+- [ ] User journey is realistic
+- [ ] Learning curve is considered
+- [ ] User feedback mechanism planned
+
+## Technical Planning
+
+- [ ] Data requirements are identified
+- [ ] Integration points are mapped
+- [ ] Dependencies are listed
+- [ ] Technical complexity is assessed
+- [ ] Performance requirements stated
+
+## Development Roadmap
+
+- [ ] Phase 1 MVP is clearly scoped
+- [ ] Phase 2 enhancements are outlined
+- [ ] Phase 3 polish items listed
+- [ ] Timeline estimates provided
+- [ ] Deliverables are specific
+
+## Risk Management
+
+- [ ] Technical risks identified
+- [ ] Usability risks considered
+- [ ] Scope risks acknowledged
+- [ ] Mitigation strategies provided
+- [ ] Open questions documented
+
+## Creative Elements (Optional)
+
+- [ ] Personality theme is consistent (if used)
+- [ ] Special features add value
+- [ ] Module feels cohesive
+- [ ] Fun elements don't compromise functionality
+
+## Documentation Quality
+
+- [ ] All sections have content (no empty placeholders)
+- [ ] Writing is clear and concise
+- [ ] Technical terms are explained
+- [ ] Examples are provided where helpful
+- [ ] Next steps are actionable
+
+## Implementation Readiness
+
+- [ ] Brief provides enough detail for build-module workflow
+- [ ] Agent specifications sufficient for build-agent workflow
+- [ ] Workflow descriptions ready for build-workflow
+- [ ] Resource requirements are clear
+- [ ] Success metrics are measurable
+
+## Final Validation
+
+- [ ] Module concept is viable
+- [ ] Scope is achievable
+- [ ] Value is clear
+- [ ] Brief is complete
+- [ ] Ready for development
+
+## Issues Found
+
+### Critical Issues
+
+<!-- Must be fixed before proceeding to build -->
+
+### Recommendations
+
+<!-- Suggested improvements -->
+
+### Nice-to-Haves
+
+<!-- Optional enhancements -->
+
+---
+
+**Validation Complete:** ⬜ Yes / ⬜ With Issues / ⬜ Needs Revision
+
+**Validated By:** **\*\*\*\***\_**\*\*\*\***
+**Date:** **\*\*\*\***\_**\*\*\*\***