bmad-method 5.1.3 → 6.0.0-alpha.1

package/src/modules/bmb/workflows/create-module/module-structure.md

@@ -0,0 +1,366 @@
+# BMAD Module Structure Guide
+
+## What is a Module?
+
+A BMAD module is a self-contained package of agents, workflows, tasks, and resources that work together to provide specialized functionality. Think of it as an expansion pack for the BMAD Method.
+
+## Module Architecture
+
+### Core Structure
+
+```
+# SOURCE MODULE (in BMAD-METHOD project)
+src/modules/{module-code}/
+├── agents/                        # Agent definitions (.agent.yaml)
+├── workflows/                     # Workflow folders
+├── tasks/                         # Task files
+├── tools/                         # Tool files
+├── templates/                     # Shared templates
+├── data/                          # Static data
+├── _module-installer/             # Installation configuration
+│   ├── install-config.yaml  # Installation questions & config
+│   ├── installer.js              # Optional custom install logic
+│   └── assets/                   # Files to copy during install
+└── README.md                      # Module documentation
+
+# INSTALLED MODULE (in target project)
+{project-root}/bmad/{module-code}/
+├── agents/                        # Compiled agent files (.md)
+├── workflows/                     # Workflow instances
+├── tasks/                         # Task files
+├── tools/                         # Tool files
+├── templates/                     # Templates
+├── data/                          # Module data
+├── config.yaml                    # Generated from install-config.yaml
+└── README.md                      # Module documentation
+```
+
+## Module Types by Complexity
+
+### Simple Module (1-2 agents, 2-3 workflows)
+
+Perfect for focused, single-purpose tools.
+
+**Example: Code Review Module**
+
+- 1 Reviewer Agent
+- 2 Workflows: quick-review, deep-review
+- Clear, narrow scope
+
+### Standard Module (3-5 agents, 5-10 workflows)
+
+Comprehensive solution for a domain.
+
+**Example: Project Management Module**
+
+- PM Agent, Scrum Master Agent, Analyst Agent
+- Workflows: sprint-planning, retrospective, roadmap, user-stories
+- Integrated component ecosystem
+
+### Complex Module (5+ agents, 10+ workflows)
+
+Full platform or framework.
+
+**Example: RPG Toolkit Module**
+
+- DM Agent, NPC Agent, Monster Agent, Loot Agent, Map Agent
+- 15+ workflows for every aspect of game management
+- Multiple interconnected systems
+
+## Module Naming Conventions
+
+### Module Code (kebab-case)
+
+- `data-viz` - Data Visualization
+- `team-collab` - Team Collaboration
+- `rpg-toolkit` - RPG Toolkit
+- `legal-assist` - Legal Assistant
+
+### Module Name (Title Case)
+
+- "Data Visualization Suite"
+- "Team Collaboration Platform"
+- "RPG Game Master Toolkit"
+- "Legal Document Assistant"
+
+## Component Guidelines
+
+### Agents per Module
+
+**Recommended Distribution:**
+
+- **Primary Agent (1)**: The main interface/orchestrator
+- **Specialist Agents (2-4)**: Domain-specific experts
+- **Utility Agents (0-2)**: Helper/support functions
+
+**Anti-patterns to Avoid:**
+
+- Too many overlapping agents
+- Agents that could be combined
+- Agents without clear purpose
+
+### Workflows per Module
+
+**Categories:**
+
+- **Core Workflows (2-3)**: Essential functionality
+- **Feature Workflows (3-5)**: Specific capabilities
+- **Utility Workflows (2-3)**: Supporting operations
+- **Admin Workflows (0-2)**: Maintenance/config
+
+**Workflow Complexity Guide:**
+
+- Simple: 3-5 steps, single output
+- Standard: 5-10 steps, multiple outputs
+- Complex: 10+ steps, conditional logic, sub-workflows
+
+### Tasks per Module
+
+Tasks should be used for:
+
+- Single-operation utilities
+- Shared subroutines
+- Quick actions that don't warrant workflows
+
+## Module Dependencies
+
+### Internal Dependencies
+
+- Agents can reference module workflows
+- Workflows can invoke module tasks
+- Tasks can use module templates
+
+### External Dependencies
+
+- Reference other modules via full paths
+- Declare dependencies in config.yaml
+- Version compatibility notes
+
+## Installation Infrastructure
+
+### Required: \_module-installer/install-config.yaml
+
+This file defines both installation questions AND static configuration values:
+
+```yaml
+# Module metadata
+code: module-code
+name: 'Module Name'
+default_selected: false
+
+# Welcome message during installation
+prompt:
+  - 'Welcome to Module Name!'
+  - 'Brief description here'
+
+# Core values automatically inherited from installer:
+## user_name
+## communication_language
+## document_output_language
+## output_folder
+
+# INTERACTIVE fields (ask user during install)
+output_location:
+  prompt: 'Where should module outputs be saved?'
+  default: 'output/module-code'
+  result: '{project-root}/{value}'
+
+feature_level:
+  prompt: 'Which feature set?'
+  default: 'standard'
+  result: '{value}'
+  single-select:
+    - value: 'basic'
+      label: 'Basic - Core features only'
+    - value: 'standard'
+      label: 'Standard - Recommended features'
+    - value: 'advanced'
+      label: 'Advanced - All features'
+
+# STATIC fields (no prompt, just hardcoded values)
+module_version:
+  result: '1.0.0'
+
+data_path:
+  result: '{project-root}/bmad/module-code/data'
+```
+
+**Key Points:**
+
+- File is named `install-config.yaml` (NOT install-config.yaml)
+- Supports both interactive prompts and static values
+- `result` field uses placeholders: `{value}`, `{project-root}`, `{directory_name}`
+- Installer generates final `config.yaml` from this template
+
+### Optional: \_module-installer/installer.js
+
+For complex installations requiring custom logic:
+
+```javascript
+/**
+ * @param {Object} options - Installation options
+ * @param {string} options.projectRoot - Target project directory
+ * @param {Object} options.config - Config from install-config.yaml
+ * @param {Array} options.installedIDEs - IDEs being configured
+ * @param {Object} options.logger - Logger (log, warn, error)
+ * @returns {boolean} - true if successful
+ */
+async function install(options) {
+  // Custom installation logic here
+  // - Database setup
+  // - API configuration
+  // - External downloads
+  // - Integration setup
+
+  return true;
+}
+
+module.exports = { install };
+```
+
+### Optional: \_module-installer/assets/
+
+Files to copy during installation:
+
+- External configurations
+- Documentation
+- Example files
+- Integration scripts
+
+## Module Lifecycle
+
+### Development Phases
+
+1. **Planning Phase**
+   - Define scope and purpose
+   - Identify components
+   - Design architecture
+
+2. **Scaffolding Phase**
+   - Create directory structure
+   - Generate configurations
+   - Setup installer
+
+3. **Building Phase**
+   - Create agents incrementally
+   - Build workflows progressively
+   - Add tasks as needed
+
+4. **Testing Phase**
+   - Test individual components
+   - Verify integration
+   - Validate installation
+
+5. **Deployment Phase**
+   - Package module
+   - Document usage
+   - Distribute/share
+
+## Best Practices
+
+### Module Cohesion
+
+- All components should relate to module theme
+- Clear boundaries between modules
+- No feature creep
+
+### Progressive Enhancement
+
+- Start with MVP (1 agent, 2 workflows)
+- Add components based on usage
+- Refactor as patterns emerge
+
+### Documentation Standards
+
+- Every module needs README.md
+- Each agent needs purpose statement
+- Workflows need clear descriptions
+- Include examples and quickstart
+
+### Naming Consistency
+
+- Use module code prefix for uniqueness
+- Consistent naming patterns within module
+- Clear, descriptive names
+
+## Example Modules
+
+### Example 1: Personal Productivity
+
+```
+productivity/
+├── agents/
+│   ├── task-manager.md      # GTD methodology
+│   └── focus-coach.md        # Pomodoro timer
+├── workflows/
+│   ├── daily-planning/       # Morning routine
+│   ├── weekly-review/        # Week retrospective
+│   └── project-setup/        # New project init
+└── config.yaml
+```
+
+### Example 2: Content Creation
+
+```
+content/
+├── agents/
+│   ├── writer.md            # Blog/article writer
+│   ├── editor.md            # Copy editor
+│   └── seo-optimizer.md     # SEO specialist
+├── workflows/
+│   ├── blog-post/           # Full blog creation
+│   ├── social-media/        # Social content
+│   ├── email-campaign/      # Email sequence
+│   └── content-calendar/    # Planning
+└── templates/
+    ├── blog-template.md
+    └── email-template.md
+```
+
+### Example 3: DevOps Automation
+
+```
+devops/
+├── agents/
+│   ├── deploy-master.md     # Deployment orchestrator
+│   ├── monitor.md           # System monitoring
+│   ├── incident-responder.md # Incident management
+│   └── infra-architect.md   # Infrastructure design
+├── workflows/
+│   ├── ci-cd-setup/         # Pipeline creation
+│   ├── deploy-app/          # Application deployment
+│   ├── rollback/            # Emergency rollback
+│   ├── health-check/        # System verification
+│   └── incident-response/   # Incident handling
+├── tasks/
+│   ├── check-status.md      # Quick status check
+│   └── notify-team.md       # Team notifications
+└── data/
+    └── runbooks/            # Operational guides
+```
+
+## Module Evolution Pattern
+
+```
+Simple Module → Standard Module → Complex Module → Module Suite
+     (MVP)          (Enhanced)        (Complete)      (Ecosystem)
+```
+
+## Common Pitfalls
+
+1. **Over-engineering**: Starting too complex
+2. **Under-planning**: No clear architecture
+3. **Poor boundaries**: Module does too much
+4. **Weak integration**: Components don't work together
+5. **Missing docs**: No clear usage guide
+
+## Success Metrics
+
+A well-designed module has:
+
+- ✅ Clear, focused purpose
+- ✅ Cohesive components
+- ✅ Smooth installation
+- ✅ Comprehensive docs
+- ✅ Room for growth
+- ✅ Happy users!

package/src/modules/bmb/workflows/create-module/workflow.yaml

@@ -0,0 +1,44 @@
+# Build Module Workflow Configuration
+name: create-module
+description: "Interactive workflow to build complete BMAD modules with agents, workflows, tasks, and installation infrastructure"
+author: "BMad"
+
+# Critical variables load from config_source
+config_source: "{project-root}/bmad/bmb/config.yaml"
+custom_module_location: "{config_source}:custom_module_location"
+communication_language: "{config_source}:communication_language"
+user_name: "{config_source}:user_name"
+
+# Reference guides for module building
+module_structure_guide: "{installed_path}/module-structure.md"
+installer_templates: "{installed_path}/installer-templates/"
+
+# Use existing build workflows
+agent_builder: "{project-root}/bmad/bmb/workflows/create-agent/workflow.yaml"
+workflow_builder: "{project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml"
+brainstorming_workflow: "{project-root}/bmad/core/workflows/brainstorming/workflow.yaml"
+brainstorming_context: "{installed_path}/brainstorm-context.md"
+
+# Optional docs that help understand module patterns
+recommended_inputs:
+  - module_brief: "{output_folder}/module-brief-*.md"
+  - brainstorming_results: "{output_folder}/brainstorming-*.md"
+  - bmm_module: "{project-root}/bmad/bmm/"
+  - cis_module: "{project-root}/bmad/cis/"
+  - existing_agents: "{project-root}/bmad/*/agents/"
+  - existing_workflows: "{project-root}/bmad/*/workflows/"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmb/workflows/create-module"
+template: false # This is an interactive scaffolding workflow
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Output configuration - creates entire module structure
+# Save to custom_module_location/{{module_code}}
+installer_output_folder: "{custom_module_location}/{{module_code}}"
+
+standalone: true
+
+# Web bundle configuration
+web_bundle: false # BMB workflows run locally in BMAD-METHOD project

package/src/modules/bmb/workflows/create-workflow/README.md

@@ -0,0 +1,277 @@
+# Build Workflow
+
+## Overview
+
+The Build Workflow is an interactive workflow builder that guides you through creating new BMAD workflows with proper structure, conventions, and validation. It ensures all workflows follow best practices for optimal human-AI collaboration and are fully compliant with the BMAD Core v6 workflow execution engine.
+
+## Key Features
+
+- **Optional Brainstorming Phase**: Creative exploration of workflow ideas before structured development
+- **Comprehensive Guidance**: Step-by-step process with detailed instructions and examples
+- **Template-Based**: Uses proven templates for all workflow components
+- **Convention Enforcement**: Ensures adherence to BMAD workflow creation guide
+- **README Generation**: Automatically creates comprehensive documentation
+- **Validation Built-In**: Includes checklist generation for quality assurance
+- **Type-Aware**: Adapts to document, action, interactive, autonomous, or meta-workflow types
+
+## Usage
+
+### Basic Invocation
+
+```bash
+workflow create-workflow
+```
+
+### Through BMad Builder Agent
+
+```
+*create-workflow
+```
+
+### What You'll Be Asked
+
+1. **Optional**: Whether to brainstorm workflow ideas first (creative exploration phase)
+2. Workflow name and target module
+3. Workflow purpose and type (enhanced by brainstorming insights if used)
+4. Metadata (description, author, outputs)
+5. Step-by-step design (goals, variables, flow)
+6. Whether to include optional components
+
+## Workflow Structure
+
+### Files Included
+
+```
+create-workflow/
+├── workflow.yaml                  # Configuration and metadata
+├── instructions.md                # Step-by-step execution guide
+├── checklist.md                   # Validation criteria
+├── workflow-creation-guide.md     # Comprehensive reference guide
+├── README.md                      # This file
+└── workflow-template/             # Templates for new workflows
+    ├── workflow.yaml
+    ├── instructions.md
+    ├── template.md
+    ├── checklist.md
+    └── README.md
+```
+
+## Understanding Instruction Styles
+
+One of the most important decisions when creating a workflow is choosing the **instruction style** - how the workflow guides the AI's interaction with users.
+
+### Intent-Based vs Prescriptive Instructions
+
+**Intent-Based (Recommended for most workflows)**
+
+Guides the LLM with goals and principles, allowing natural conversation adaptation.
+
+- **More flexible and conversational** - AI adapts questions to context
+- **Better for complex discovery** - Requirements gathering, creative exploration
+- **Quality over consistency** - Focus on deep understanding
+- **Example**: `<action>Guide user to define their target audience with specific demographics and needs</action>`
+
+**Best for:**
+
+- Complex discovery processes (user research, requirements)
+- Creative brainstorming and ideation
+- Iterative refinement workflows
+- When adaptation to context matters
+- Workflows requiring nuanced understanding
+
+**Prescriptive**
+
+Provides exact wording for questions and structured options.
+
+- **More controlled and predictable** - Same questions every time
+- **Better for simple data collection** - Platform choices, yes/no decisions
+- **Consistency over quality** - Standardized execution
+- **Example**: `<ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>`
+
+**Best for:**
+
+- Simple data collection (platform, format, binary choices)
+- Compliance verification and standards
+- Configuration with finite options
+- Quick setup wizards
+- When consistency is critical
+
+### Best Practice: Mix Both Styles
+
+The most effective workflows use **both styles strategically**:
+
+```xml
+<!-- Intent-based workflow with prescriptive moments -->
+<step n="1" goal="Understand user vision">
+  <action>Explore the user's vision, uncovering creative intent and target experience</action>
+</step>
+
+<step n="2" goal="Capture basic metadata">
+  <ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>
+</step>
+
+<step n="3" goal="Deep dive into details">
+  <action>Guide user to articulate their core approach and unique aspects</action>
+</step>
+```
+
+**During workflow creation**, you'll be asked to choose a **primary style preference** - this sets the default approach, but you can (and should) use the other style when it makes more sense for specific steps.
+
+## Workflow Process
+
+### Phase 0: Optional Brainstorming (Step -1)
+
+- **Creative Exploration**: Option to brainstorm workflow ideas before structured development
+- **Design Concept Development**: Generate multiple approaches and explore different possibilities
+- **Requirement Clarification**: Use brainstorming output to inform workflow purpose, type, and structure
+- **Enhanced Creativity**: Leverage AI brainstorming tools for innovative workflow design
+
+The brainstorming phase invokes the CIS brainstorming workflow to:
+
+- Explore workflow ideas and approaches
+- Clarify requirements and use cases
+- Generate creative solutions for complex automation needs
+- Inform the structured workflow building process
+
+### Phase 1: Planning (Steps 0-3)
+
+- Load workflow creation guide and conventions
+- Define workflow purpose, name, and type (informed by brainstorming if used)
+- Gather metadata and configuration details
+- Design step structure and flow
+
+### Phase 2: Generation (Steps 4-8)
+
+- Create workflow.yaml with proper configuration
+- Generate instructions.md with XML-structured steps
+- Create template.md (for document workflows)
+- Generate validation checklist
+- Create supporting data files (optional)
+
+### Phase 3: Documentation and Validation (Steps 9-11)
+
+- Create comprehensive README.md (MANDATORY)
+- Test and validate workflow structure
+- Provide usage instructions and next steps
+
+## Output
+
+### Generated Workflow Folder
+
+Creates a complete workflow folder at:
+`{project-root}/bmad/{{target_module}}/workflows/{{workflow_name}}/`
+
+### Files Created
+
+**Always Created:**
+
+- `workflow.yaml` - Configuration with paths and variables
+- `README.md` - Comprehensive documentation (MANDATORY as of v6)
+- `instructions.md` - Execution steps (if not template-only workflow)
+
+**Conditionally Created:**
+
+- `template.md` - Document structure (for document workflows)
+- `checklist.md` - Validation criteria (optional but recommended)
+- Supporting data files (CSV, JSON, etc. as needed)
+
+### Output Structure
+
+For document workflows, the README documents:
+
+- Workflow purpose and use cases
+- Usage examples with actual commands
+- Input expectations
+- Output structure and location
+- Best practices
+
+## Requirements
+
+- Access to workflow creation guide
+- BMAD Core v6 project structure
+- Module to host the new workflow (bmm, bmb, cis, or custom)
+
+## Best Practices
+
+### Before Starting
+
+1. **Consider Brainstorming**: If you're unsure about the workflow approach, use the optional brainstorming phase
+2. Review the workflow creation guide to understand conventions
+3. Have a clear understanding of the workflow's purpose (or be ready to explore it creatively)
+4. Know which type of workflow you're creating (document, action, etc.) or be open to discovery
+5. Identify any data files or references needed
+
+### Creative Workflow Design
+
+The create-workflow now supports a **seamless transition from creative ideation to structured implementation**:
+
+- **"I need a workflow for something..."** → Start with brainstorming to explore possibilities
+- **Brainstorm** → Generate multiple approaches and clarify requirements
+- **Structured workflow** → Build the actual workflow using insights from brainstorming
+- **One seamless session** → Complete the entire process from idea to implementation
+
+### During Execution
+
+1. Follow kebab-case naming conventions
+2. Be specific with step goals and instructions
+3. Use descriptive variable names (snake_case)
+4. Set appropriate limits ("3-5 items maximum")
+5. Include examples where helpful
+
+### After Completion
+
+1. Test the newly created workflow
+2. Validate against the checklist
+3. Ensure README is comprehensive and accurate
+4. Test all file paths and variable references
+
+## Troubleshooting
+
+### Issue: Generated workflow won't execute
+
+- **Solution**: Verify all file paths in workflow.yaml use proper variable substitution
+- **Check**: Ensure installed_path and project-root are correctly set
+
+### Issue: Variables not replacing in template
+
+- **Solution**: Ensure variable names match exactly between instructions `<template-output>` tags and template `{{variables}}`
+- **Check**: Use snake_case consistently
+
+### Issue: README has placeholder text
+
+- **Solution**: This workflow now enforces README generation - ensure Step 10 completed fully
+- **Check**: No {WORKFLOW_TITLE} or similar placeholders should remain
+
+## Customization
+
+To modify this workflow:
+
+1. Edit `instructions.md` to adjust the creation process
+2. Update templates in `workflow-template/` to change generated files
+3. Modify `workflow-creation-guide.md` to update conventions
+4. Edit `checklist.md` to change validation criteria
+
+## Version History
+
+- **v6.0.0** - README.md now MANDATORY for all workflows
+  - Added comprehensive README template
+  - Enhanced validation for documentation
+  - Improved Step 10 with detailed README requirements
+
+- **v6.0.0** - Initial BMAD Core v6 compatible version
+  - Template-based workflow generation
+  - Convention enforcement
+  - Validation checklist support
+
+## Support
+
+For issues or questions:
+
+- Review `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
+- Check existing workflows in `/bmad/bmm/workflows/` for examples
+- Validate against `/bmad/bmb/workflows/create-workflow/checklist.md`
+- Consult BMAD Method v6 documentation
+
+---
+
+_Part of the BMad Method v6 - BMB (BMad Builder) Module_