bmad-method 5.1.3 → 6.0.0-alpha.1

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

@@ -0,0 +1,342 @@
+# Edit Workflow - Workflow Editor Instructions
+
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml</critical>
+<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication based on context and user needs</critical>
+<critical>The goal is COLLABORATIVE IMPROVEMENT - work WITH the user, not FOR them</critical>
+<critical>Communicate all responses in {communication_language}</critical>
+
+<workflow>
+
+<step n="1" goal="Load and deeply understand the target workflow">
+<ask>What is the path to the workflow you want to edit? (provide path to workflow.yaml or workflow directory)</ask>
+
+<action>Load the target workflow completely:
+
+- workflow.yaml configuration
+- instructions.md (if exists)
+- template.md (if exists)
+- checklist.md (if exists)
+- Any additional data files referenced
+  </action>
+
+<action>Load ALL workflow documentation to inform understanding:
+
+- Workflow creation guide: {workflow_creation_guide}
+- Workflow execution engine: {workflow_execution_engine}
+- Study example workflows from: {project-root}/bmad/bmm/workflows/
+  </action>
+
+<action>Analyze the workflow deeply:
+
+- Identify workflow type (document, action, interactive, autonomous, meta)
+- Understand purpose and user journey
+- Map out step flow and logic
+- Check variable consistency across files
+- Evaluate instruction style (intent-based vs prescriptive)
+- Assess template structure (if applicable)
+- Review validation criteria
+- Identify config dependencies
+- Check for web bundle configuration
+- Evaluate against best practices from loaded guides
+  </action>
+
+<action>Reflect understanding back to {user_name}:
+
+Present a warm, conversational summary adapted to the workflow's complexity:
+
+- What this workflow accomplishes (its purpose and value)
+- How it's structured (type, steps, interactive points)
+- What you notice (strengths, potential improvements, issues)
+- Your initial assessment based on best practices
+- How it fits in the larger BMAD ecosystem
+
+Be conversational and insightful. Help {user_name} see their workflow through your eyes.
+</action>
+
+<ask>Does this match your understanding of what this workflow should accomplish?</ask>
+<template-output>workflow_understanding</template-output>
+</step>
+
+<step n="2" goal="Discover improvement goals collaboratively">
+<critical>Understand WHAT the user wants to improve and WHY before diving into edits</critical>
+
+<action>Engage in collaborative discovery:
+
+Ask open-ended questions to understand their goals:
+
+- What prompted you to want to edit this workflow?
+- What feedback have you gotten from users running it?
+- Are there specific steps that feel clunky or confusing?
+- Is the workflow achieving its intended outcome?
+- Are there new capabilities you want to add?
+- Is the instruction style working well for your users?
+
+Listen for clues about:
+
+- User experience issues (confusing steps, unclear instructions)
+- Functional issues (broken references, missing validation)
+- Performance issues (too many steps, repetitive, tedious)
+- Maintainability issues (hard to update, bloated, inconsistent variables)
+- Instruction style mismatch (too prescriptive when should be adaptive, or vice versa)
+- Integration issues (doesn't work well with other workflows)
+  </action>
+
+<action>Based on their responses and your analysis from step 1, identify improvement opportunities:
+
+Organize by priority and user goals:
+
+- CRITICAL issues blocking successful runs
+- IMPORTANT improvements enhancing user experience
+- NICE-TO-HAVE enhancements for polish
+
+Present these conversationally, explaining WHY each matters and HOW it would help.
+</action>
+
+<action>Assess instruction style fit:
+
+Based on the workflow's purpose and your analysis:
+
+- Is the current style (intent-based vs prescriptive) appropriate?
+- Would users benefit from more/less structure?
+- Are there steps that should be more adaptive?
+- Are there steps that need more specificity?
+
+Discuss style as part of improvement discovery, not as a separate concern.
+</action>
+
+<action>Collaborate on priorities:
+
+Don't just list options - discuss them:
+
+- "I noticed {{issue}} - this could make users feel {{problem}}. Want to address this?"
+- "The workflow could be more {{improvement}} which would help when {{use_case}}. Worth exploring?"
+- "Based on what you said about {{user_goal}}, we might want to {{suggestion}}. Thoughts?"
+
+Let the conversation flow naturally. Build a shared vision of what "better" looks like.
+</action>
+
+<template-output>improvement_goals</template-output>
+</step>
+
+<step n="3" goal="Facilitate improvements collaboratively" repeat="until-user-satisfied">
+<critical>Work iteratively - improve, review, refine. Never dump all changes at once.</critical>
+
+<action>For each improvement area, facilitate collaboratively:
+
+1. **Explain the current state and why it matters**
+   - Show relevant sections of the workflow
+   - Explain how it works now and implications
+   - Connect to user's goals from step 2
+
+2. **Propose improvements with rationale**
+   - Suggest specific changes that align with best practices
+   - Explain WHY each change helps
+   - Provide examples from the loaded guides when helpful
+   - Show before/after comparisons for clarity
+   - Reference the creation guide's patterns naturally
+
+3. **Collaborate on the approach**
+   - Ask if the proposed change addresses their need
+   - Invite modifications or alternative approaches
+   - Explain tradeoffs when relevant
+   - Adapt based on their feedback
+
+4. **Apply changes iteratively**
+   - Make one focused improvement at a time
+   - Show the updated section
+   - Confirm it meets their expectation
+   - Move to next improvement or refine current one
+     </action>
+
+<action>Common improvement patterns to facilitate:
+
+**If refining instruction style:**
+
+- Discuss where the workflow feels too rigid or too loose
+- Identify steps that would benefit from intent-based approach
+- Identify steps that need prescriptive structure
+- Convert between styles thoughtfully, explaining tradeoffs
+- Show how each style serves the user differently
+- Test proposed changes by reading them aloud
+
+**If improving step flow:**
+
+- Walk through the user journey step by step
+- Identify friction points or redundancy
+- Propose streamlined flow
+- Consider where steps could merge or split
+- Ensure each step has clear goal and value
+- Check that repeat conditions make sense
+
+**If fixing variable consistency:**
+
+- Identify variables used across files
+- Find mismatches in naming or usage
+- Propose consistent naming scheme
+- Update all files to match
+- Verify variables are defined in workflow.yaml
+
+**If enhancing validation:**
+
+- Review current checklist (if exists)
+- Discuss what "done well" looks like
+- Make criteria specific and measurable
+- Add validation for new features
+- Remove outdated or vague criteria
+
+**If updating configuration:**
+
+- Review standard config pattern
+- Check if user context variables are needed
+- Ensure output_folder, user_name, communication_language are used appropriately
+- Add missing config dependencies
+- Clean up unused config fields
+
+**If adding/updating templates:**
+
+- Understand the document structure needed
+- Design template variables that match instruction outputs
+- Ensure variable names are descriptive snake_case
+- Include proper metadata headers
+- Test that all variables can be filled
+
+**If configuring web bundle:**
+
+- Identify all files the workflow depends on
+- Check for invoked workflows (must be included)
+- Verify paths are bmad/-relative
+- Remove config_source dependencies
+- Build complete file list
+
+**If improving user interaction:**
+
+- Find places where <ask> could be more open-ended
+- Add educational context where users might be lost
+- Remove unnecessary confirmation steps
+- Make questions clearer and more purposeful
+- Balance guidance with user autonomy
+  </action>
+
+<action>Throughout improvements, educate when helpful:
+
+Share insights from the guides naturally:
+
+- "The creation guide recommends {{pattern}} for workflows like this"
+- "Looking at examples in BMM, this type of step usually {{approach}}"
+- "The execution engine expects {{structure}} for this to work properly"
+
+Connect improvements to broader BMAD principles without being preachy.
+</action>
+
+<ask>After each significant change:
+
+- "Does this flow feel better for what you're trying to achieve?"
+- "Want to refine this further, or move to the next improvement?"
+- "How does this change affect the user experience?"
+  </ask>
+
+<template-output>improvement_implementation</template-output>
+</step>
+
+<step n="4" goal="Validate improvements holistically">
+<action>Run comprehensive validation conversationally:
+
+Don't just check boxes - explain what you're validating and why it matters:
+
+- "Let me verify all file references resolve correctly..."
+- "Checking that variables are consistent across all files..."
+- "Making sure the step flow is logical and complete..."
+- "Validating template variables match instruction outputs..."
+- "Ensuring config dependencies are properly set up..."
+  </action>
+
+<action>Load validation checklist: {installed_path}/checklist.md</action>
+<action>Check all items from checklist systematically</action>
+
+<check if="validation_issues_found">
+  <action>Present issues conversationally:
+
+Explain what's wrong and implications:
+
+- "I found {{issue}} which could cause {{problem}} when users run this"
+- "The {{component}} needs {{fix}} because {{reason}}"
+
+Propose fixes immediately:
+
+- "I can fix this by {{solution}}. Should I?"
+- "We have a couple options here: {{option1}} or {{option2}}. Thoughts?"
+  </action>
+
+<action>Fix approved issues and re-validate</action>
+</check>
+
+<check if="validation_passes">
+  <action>Confirm success warmly:
+
+"Excellent! Everything validates cleanly:
+
+- All file references resolve
+- Variables are consistent throughout
+- Step flow is logical and complete
+- Template aligns with instructions (if applicable)
+- Config dependencies are set up correctly
+- Web bundle is complete (if applicable)
+
+Your workflow is in great shape."
+</action>
+</check>
+
+<template-output>validation_results</template-output>
+</step>
+
+<step n="5" goal="Review improvements and guide next steps">
+<action>Create a conversational summary of what improved:
+
+Tell the story of the transformation:
+
+- "We started with {{initial_state}}"
+- "You wanted to {{user_goals}}"
+- "We made these key improvements: {{changes_list}}"
+- "Now your workflow {{improved_capabilities}}"
+
+Highlight the impact:
+
+- "This means users will experience {{benefit}}"
+- "The workflow is now more {{quality}}"
+- "It follows best practices for {{patterns}}"
+  </action>
+
+<action>Guide next steps based on changes made:
+
+If instruction style changed:
+
+- "Since we made the workflow more {{style}}, you might want to test it with a real user to see how it feels"
+
+If template was updated:
+
+- "The template now has {{new_variables}} - run the workflow to generate a sample document"
+
+If this is part of larger module work:
+
+- "This workflow is part of {{module}} - consider if other workflows need similar improvements"
+
+If web bundle was configured:
+
+- "The web bundle is now set up - you can test deploying this workflow standalone"
+
+Be a helpful guide to what comes next, not just a task completer.
+</action>
+
+<ask>Would you like to:
+
+- Test the edited workflow by running it
+- Edit another workflow
+- Make additional refinements to this one
+- Return to your module work
+  </ask>
+
+<template-output>completion_summary</template-output>
+</step>
+
+</workflow>

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

@@ -0,0 +1,29 @@
+# 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"
+communication_language: "{config_source}:communication_language"
+user_name: "{config_source}:user_name"
+
+# Required Data Files - Critical for understanding workflow conventions
+workflow_creation_guide: "{project-root}/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md"
+workflow_execution_engine: "{project-root}/bmad/core/tasks/workflow.xml"
+
+# 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"
+
+standalone: true
+
+# Web bundle configuration
+web_bundle: false # BMB workflows run locally in BMAD-METHOD project

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 create-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 and Context (Steps 1-3)
+
+**Mode Selection and 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 and 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 and 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 and Risk Management (Steps 10-12)
+
+**Creative Features and 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 and 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 and Export Preparation**
+
+- Comprehensive review of all brief sections
+- Validation against quality and completeness criteria
+- Preparation for seamless handoff to create-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 create-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 and 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 create-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/create-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 `create-module/module-structure.md`
+
+---
+
+_Part of the BMad Method v6 - BMB (Builder) Module_