bmad-method 5.1.3 → 6.0.0-alpha.1

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

@@ -0,0 +1,220 @@
+# Build Module Workflow
+
+## Overview
+
+The Build Module workflow is an interactive scaffolding system that creates complete BMAD modules with agents, workflows, tasks, and installation infrastructure. It serves as the primary tool for building new modules in the BMAD ecosystem, guiding users through the entire module creation process from concept to deployment-ready structure.
+
+## Key Features
+
+- **Interactive Module Planning** - Collaborative session to define module concept, scope, and architecture
+- **Intelligent Scaffolding** - Automatic creation of proper directory structures and configuration files
+- **Component Integration** - Seamless integration with create-agent and create-workflow workflows
+- **Installation Infrastructure** - Complete installer setup with configuration templates
+- **Module Brief Integration** - Can use existing module briefs as blueprints for accelerated development
+- **Validation and Documentation** - Built-in validation checks and comprehensive README generation
+
+## Usage
+
+### Basic Invocation
+
+```bash
+workflow create-module
+```
+
+### With Module Brief Input
+
+```bash
+# If you have a module brief from the module-brief workflow
+workflow create-module --input module-brief-my-module-2024-09-26.md
+```
+
+### Configuration
+
+The workflow loads critical variables from the BMB configuration:
+
+- **custom_module_location**: Where custom modules are created (default: `bmad/`)
+- **user_name**: Module author information
+- **date**: Automatic timestamp for versioning
+
+## Workflow Structure
+
+### Files Included
+
+```
+create-module/
+├── workflow.yaml           # Configuration and metadata
+├── instructions.md         # Step-by-step execution guide
+├── checklist.md           # Validation criteria
+├── module-structure.md    # Module architecture guide
+├── installer-templates/   # Installation templates
+│   ├── install-config.yaml
+│   └── installer.js
+└── README.md             # This file
+```
+
+## Workflow Process
+
+### Phase 1: Concept Definition (Steps 1-2)
+
+**Module Vision and Identity**
+
+- Define module concept, purpose, and target audience
+- Establish module code (kebab-case) and friendly name
+- Choose module category (Domain-Specific, Creative, Technical, Business, Personal)
+- Plan component architecture with agent and workflow specifications
+
+**Module Brief Integration**
+
+- Automatically detects existing module briefs in output folder
+- Can load and use briefs as pre-populated blueprints
+- Accelerates planning when comprehensive brief exists
+
+### Phase 2: Architecture Planning (Steps 3-4)
+
+**Directory Structure Creation**
+
+- Creates complete module directory hierarchy
+- Sets up agent, workflow, task, template, and data folders
+- Establishes installer directory with proper configuration
+
+**Module Configuration**
+
+- Defines configuration questions in install-config.yaml (config.yaml generated during installation)
+- Configures component counts and references
+- Sets up output and data folder specifications
+
+### Phase 3: Component Creation (Steps 5-6)
+
+**Interactive Component Building**
+
+- Optional creation of first agent using create-agent workflow
+- Optional creation of first workflow using create-workflow workflow
+- Creates placeholders for components to be built later
+
+**Workflow Integration**
+
+- Seamlessly invokes sub-workflows for component creation
+- Ensures proper file placement and structure
+- Maintains module consistency across components
+
+### Phase 4: Installation and Documentation (Steps 7-9)
+
+**Installer Infrastructure**
+
+- Creates install-config.yaml with configuration questions for deployment
+- Sets up optional installer.js for complex installation logic
+- Configures post-install messaging and instructions
+
+**Comprehensive Documentation**
+
+- Generates detailed README.md with usage examples
+- Creates development roadmap for remaining components
+- Provides quick commands for continued development
+
+### Phase 5: Validation and Finalization (Step 10)
+
+**Quality Assurance**
+
+- Validates directory structure and configuration files
+- Checks component references and path consistency
+- Ensures installer configuration is deployment-ready
+- Provides comprehensive module summary and next steps
+
+## Output
+
+### Generated Files
+
+- **Module Directory**: Complete module structure at `{project-root}/bmad/{module_code}/`
+- **Configuration Files**:
+  - Source: install-config.yaml (configuration questions)
+  - Target: config.yaml (generated from user answers during installation)
+- **Documentation**: README.md, TODO.md development roadmap
+- **Component Placeholders**: Structured folders for agents, workflows, and tasks
+
+### Output Structure
+
+The workflow creates a complete module ready for development:
+
+1. **Module Identity** - Name, code, version, and metadata
+2. **Directory Structure** - Proper BMAD module hierarchy
+3. **Configuration System** - Runtime and installation configs
+4. **Component Framework** - Ready-to-use agent and workflow scaffolding
+5. **Installation Infrastructure** - Deployment-ready installer
+6. **Documentation Suite** - README, roadmap, and development guides
+
+## Requirements
+
+- **Module Brief** (optional but recommended) - Use module-brief workflow first for best results
+- **BMAD Core Configuration** - Properly configured BMB config.yaml
+- **Build Tools Access** - create-agent and create-workflow workflows must be available
+
+## Best Practices
+
+### Before Starting
+
+1. **Create a Module Brief** - Run module-brief workflow for comprehensive planning
+2. **Review Existing Modules** - Study similar modules in `/bmad/` for patterns and inspiration
+3. **Define Clear Scope** - Have a concrete vision of what the module will accomplish
+
+### During Execution
+
+1. **Use Module Briefs** - Load existing briefs when prompted for accelerated development
+2. **Start Simple** - Create one core agent and workflow, then expand iteratively
+3. **Leverage Sub-workflows** - Use create-agent and create-workflow for quality components
+4. **Validate Early** - Review generated structure before proceeding to next phases
+
+### After Completion
+
+1. **Follow the Roadmap** - Use generated TODO.md for systematic development
+2. **Test Installation** - Validate installer with `bmad install {module_code}`
+3. **Iterate Components** - Use quick commands to add agents and workflows
+4. **Document Progress** - Update README.md as the module evolves
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Module already exists at target location
+
+- **Solution**: Choose a different module code or remove existing module
+- **Check**: Verify output folder permissions and available space
+
+**Issue**: Sub-workflow invocation fails
+
+- **Solution**: Ensure create-agent and create-workflow workflows are available
+- **Check**: Validate workflow paths in config.yaml
+
+**Issue**: Installation configuration invalid
+
+- **Solution**: Review install-config.yaml syntax and paths
+- **Check**: Ensure all referenced paths use {project-root} variables correctly
+
+## Customization
+
+To customize this workflow:
+
+1. **Modify Instructions** - Update instructions.md to adjust scaffolding steps
+2. **Extend Templates** - Add new installer templates in installer-templates/
+3. **Update Validation** - Enhance checklist.md with additional quality checks
+4. **Add Components** - Integrate additional sub-workflows for specialized components
+
+## Version History
+
+- **v1.0.0** - Initial release
+  - Interactive module scaffolding
+  - Component integration with create-agent and create-workflow
+  - Complete installation infrastructure
+  - Module brief integration support
+
+## Support
+
+For issues or questions:
+
+- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
+- Study module structure patterns at `module-structure.md`
+- Validate output using `checklist.md`
+- Consult existing modules in `/bmad/` for examples
+
+---
+
+_Part of the BMad Method v6 - BMB (Builder) Module_

package/src/modules/bmb/workflows/create-module/brainstorm-context.md

@@ -0,0 +1,137 @@
+# Module Brainstorming Context
+
+_Context provided to brainstorming workflow when creating a new BMAD module_
+
+## Session Focus
+
+You are brainstorming ideas for a **complete BMAD module** - a self-contained package that extends the BMAD Method with specialized domain expertise and capabilities.
+
+## What is a BMAD Module?
+
+A module is a cohesive package that provides:
+
+- **Domain Expertise**: Specialized knowledge in a specific area (RPG, DevOps, Content Creation, etc.)
+- **Agent Team**: Multiple AI personas with complementary skills
+- **Workflows**: Guided processes for common tasks in the domain
+- **Templates**: Document structures for consistent outputs
+- **Integration**: Components that work together seamlessly
+
+## Brainstorming Goals
+
+Explore and define:
+
+### 1. Domain and Purpose
+
+- **What domain/problem space?** (e.g., game development, marketing, personal productivity)
+- **Who is the target user?** (developers, writers, managers, hobbyists)
+- **What pain points does it solve?** (tedious tasks, missing structure, need for expertise)
+- **What makes this domain exciting?** (creativity, efficiency, empowerment)
+
+### 2. Agent Team Composition
+
+- **How many agents?** (typically 3-7 for a module)
+- **What roles/personas?** (architect, researcher, reviewer, specialist)
+- **How do they collaborate?** (handoffs, reviews, ensemble work)
+- **What personality theme?** (Star Trek crew, superhero team, fantasy party, professional squad)
+
+### 3. Core Workflows
+
+- **What documents need creating?** (plans, specs, reports, creative outputs)
+- **What processes need automation?** (analysis, generation, review, deployment)
+- **What workflows enable the vision?** (3-10 key workflows that define the module)
+
+### 4. Value Proposition
+
+- **What becomes easier?** (specific tasks that get 10x faster)
+- **What becomes possible?** (new capabilities previously unavailable)
+- **What becomes better?** (quality improvements, consistency gains)
+
+## Creative Constraints
+
+A good BMAD module should be:
+
+- **Focused**: Serves a specific domain well (not generic)
+- **Complete**: Provides end-to-end capabilities for that domain
+- **Cohesive**: Agents and workflows complement each other
+- **Fun**: Personality and creativity make it enjoyable to use
+- **Practical**: Solves real problems, delivers real value
+
+## Module Architecture Questions
+
+1. **Module Identity**
+   - Module code (kebab-case, e.g., "rpg-toolkit")
+   - Module name (friendly, e.g., "RPG Toolkit")
+   - Module purpose (one sentence)
+   - Target audience
+
+2. **Agent Lineup**
+   - Agent names and roles
+   - Communication styles and personalities
+   - Expertise areas
+   - Command sets (what each agent can do)
+
+3. **Workflow Portfolio**
+   - Document generation workflows
+   - Action/automation workflows
+   - Analysis/research workflows
+   - Creative/ideation workflows
+
+4. **Integration Points**
+   - How agents invoke workflows
+   - How workflows use templates
+   - How components pass data
+   - Dependencies on other modules
+
+## Example Module Patterns
+
+### Professional Domains
+
+- **DevOps Suite**: Deploy, Monitor, Troubleshoot agents + deployment workflows
+- **Marketing Engine**: Content, SEO, Analytics agents + campaign workflows
+- **Legal Assistant**: Contract, Research, Review agents + document workflows
+
+### Creative Domains
+
+- **RPG Toolkit**: DM, NPC, Quest agents + adventure creation workflows
+- **Story Crafter**: Plot, Character, World agents + writing workflows
+- **Music Producer**: Composer, Arranger, Mixer agents + production workflows
+
+### Personal Domains
+
+- **Life Coach**: Planner, Tracker, Mentor agents + productivity workflows
+- **Learning Companion**: Tutor, Quiz, Reviewer agents + study workflows
+- **Health Guide**: Nutrition, Fitness, Wellness agents + tracking workflows
+
+## Suggested Brainstorming Techniques
+
+Particularly effective for module ideation:
+
+1. **Domain Immersion**: Deep dive into target domain's problems
+2. **Persona Mapping**: Who needs this and what do they struggle with?
+3. **Workflow Mapping**: What processes exist today? How could they improve?
+4. **Team Building**: What personalities would make a great team?
+5. **Integration Thinking**: How do pieces connect and amplify each other?
+
+## Key Questions to Answer
+
+1. What domain expertise should this module embody?
+2. What would users be able to do that they can't do now?
+3. Who are the 3-7 agents and what are their personalities?
+4. What are the 5-10 core workflows?
+5. What makes this module delightful to use?
+6. How is this different from existing tools?
+7. What's the "killer feature" that makes this essential?
+
+## Output Goals
+
+Generate:
+
+- **Module concept**: Clear vision and purpose
+- **Agent roster**: Names, roles, personalities for each agent
+- **Workflow list**: Core workflows with brief descriptions
+- **Unique angle**: What makes this module special
+- **Use cases**: 3-5 concrete scenarios where this module shines
+
+---
+
+_This focused context helps create cohesive, valuable BMAD modules_

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

@@ -0,0 +1,244 @@
+# Build Module Validation Checklist
+
+## Module Identity and Metadata
+
+### Basic Information
+
+- [ ] Module code follows kebab-case convention (e.g., "rpg-toolkit")
+- [ ] Module name is descriptive and title-cased
+- [ ] Module purpose is clearly defined (1-2 sentences)
+- [ ] Target audience is identified
+- [ ] Version number follows semantic versioning (e.g., "1.0.0")
+- [ ] Author information is present
+
+### Naming Consistency
+
+- [ ] Module code used consistently throughout all files
+- [ ] No naming conflicts with existing modules
+- [ ] All paths use consistent module code references
+
+## Directory Structure
+
+### Source Directories (bmad/{module-code}/)
+
+- [ ] `/agents` directory created (even if empty)
+- [ ] `/workflows` directory created (even if empty)
+- [ ] `/tasks` directory exists (if tasks planned)
+- [ ] `/templates` directory exists (if templates used)
+- [ ] `/data` directory exists (if data files needed)
+- [ ] `/_module-installer/install-config.yaml` present (defines configuration questions)
+- [ ] `README.md` present with documentation
+
+### Installed Module Structure (generated in target after installation)
+
+- [ ] `/agents` directory for compiled agents
+- [ ] `/workflows` directory for workflow instances
+- [ ] `/data` directory for user data
+- [ ] `config.yaml` generated from install-config.yaml during installation
+
+## Component Planning
+
+### Agents
+
+- [ ] At least one agent defined or planned
+- [ ] Agent purposes are distinct and clear
+- [ ] Agent types (Simple/Expert/Module) identified
+- [ ] No significant overlap between agents
+- [ ] Primary agent is identified
+
+### Workflows
+
+- [ ] At least one workflow defined or planned
+- [ ] Workflow purposes are clear
+- [ ] Workflow types identified (Document/Action/Interactive)
+- [ ] Primary workflow is identified
+- [ ] Workflow complexity is appropriate
+
+### Tasks (if applicable)
+
+- [ ] Tasks have single, clear purposes
+- [ ] Tasks don't duplicate workflow functionality
+- [ ] Task files follow naming conventions
+
+## Configuration Files
+
+### Installation Configuration (install-config.yaml)
+
+- [ ] `install-config.yaml` exists in `_module-installer`
+- [ ] Module metadata present (code, name, version)
+- [ ] Configuration questions defined for user input
+- [ ] Default values provided for all questions
+- [ ] Prompt text is clear and helpful
+- [ ] Result templates use proper variable substitution
+- [ ] Paths use proper variables ({project-root}, {value}, etc.)
+
+### Generated Config (config.yaml in target)
+
+- [ ] Generated during installation from install-config.yaml
+- [ ] Contains all user-provided configuration values
+- [ ] Module metadata included
+- [ ] No config.yaml should exist in source module
+
+## Installation Infrastructure
+
+### Installer Files
+
+- [ ] Install configuration validates against schema
+- [ ] All source paths exist or are marked as templates
+- [ ] Destination paths use correct variables
+- [ ] Optional vs required steps clearly marked
+
+### installer.js (if present)
+
+- [ ] Main `installModule` function exists
+- [ ] Error handling implemented
+- [ ] Console logging for user feedback
+- [ ] Exports correct function names
+- [ ] Placeholder code replaced with actual logic (or logged as TODO)
+
+### External Assets (if any)
+
+- [ ] Asset files exist in assets directory
+- [ ] Copy destinations are valid
+- [ ] Permissions requirements documented
+
+## Documentation
+
+### README.md
+
+- [ ] Module overview section present
+- [ ] Installation instructions included
+- [ ] Component listing with descriptions
+- [ ] Quick start guide provided
+- [ ] Configuration options documented
+- [ ] At least one usage example
+- [ ] Directory structure shown
+- [ ] Author and date information
+
+### Component Documentation
+
+- [ ] Each agent has purpose documentation
+- [ ] Each workflow has description
+- [ ] Tasks are documented (if present)
+- [ ] Examples demonstrate typical usage
+
+### Development Roadmap
+
+- [ ] TODO.md or roadmap section exists
+- [ ] Planned components listed
+- [ ] Development phases identified
+- [ ] Quick commands for adding components
+
+## Integration
+
+### Cross-component References
+
+- [ ] Agents reference correct workflow paths
+- [ ] Workflows reference correct task paths
+- [ ] All internal paths use module variables
+- [ ] External dependencies declared
+
+### Module Boundaries
+
+- [ ] Module scope is well-defined
+- [ ] No feature creep into other domains
+- [ ] Clear separation from other modules
+
+## Quality Checks
+
+### Completeness
+
+- [ ] At least one functional component (not all placeholders)
+- [ ] Core functionality is implementable
+- [ ] Module provides clear value
+
+### Consistency
+
+- [ ] Formatting consistent across files
+- [ ] Variable naming follows conventions
+- [ ] Communication style appropriate for domain
+
+### Scalability
+
+- [ ] Structure supports future growth
+- [ ] Component organization is logical
+- [ ] No hard-coded limits
+
+## Testing and Validation
+
+### Structural Validation
+
+- [ ] YAML files parse without errors
+- [ ] JSON files (if any) are valid
+- [ ] XML files (if any) are well-formed
+- [ ] No syntax errors in JavaScript files
+
+### Path Validation
+
+- [ ] All referenced paths exist or are clearly marked as TODO
+- [ ] Variable substitutions are correct
+- [ ] No absolute paths (unless intentional)
+
+### Installation Testing
+
+- [ ] Installation steps can be simulated
+- [ ] No circular dependencies
+- [ ] Uninstall process defined (if complex)
+
+## Final Checks
+
+### Ready for Use
+
+- [ ] Module can be installed without errors
+- [ ] At least one component is functional
+- [ ] User can understand how to get started
+- [ ] Next steps are clear
+
+### Professional Quality
+
+- [ ] No placeholder text remains (unless marked TODO)
+- [ ] No obvious typos or grammar issues
+- [ ] Professional tone throughout
+- [ ] Contact/support information provided
+
+## Issues Found
+
+### Critical Issues
+
+<!-- List any issues that MUST be fixed before module can be used -->
+
+### Warnings
+
+<!-- List any issues that should be addressed but won't prevent basic usage -->
+
+### Improvements
+
+<!-- List any optional enhancements that would improve the module -->
+
+### Missing Components
+
+<!-- List any planned components not yet implemented -->
+
+## Module Complexity Assessment
+
+### Complexity Rating
+
+- [ ] Simple (1-2 agents, 2-3 workflows)
+- [ ] Standard (3-5 agents, 5-10 workflows)
+- [ ] Complex (5+ agents, 10+ workflows)
+
+### Readiness Level
+
+- [ ] Prototype (Basic structure, mostly placeholders)
+- [ ] Alpha (Core functionality works)
+- [ ] Beta (Most features complete, needs testing)
+- [ ] Release (Full functionality, documented)
+
+## Sign-off
+
+**Module Name:** \***\*\*\*\*\***\_\_\***\*\*\*\*\***
+**Module Code:** \***\*\*\*\*\***\_\_\***\*\*\*\*\***
+**Version:** \***\*\*\*\*\***\_\_\***\*\*\*\*\***
+**Validated By:** \***\*\*\*\*\***\_\_\***\*\*\*\*\***
+**Date:** \***\*\*\*\*\***\_\_\***\*\*\*\*\***
+**Status:** ⬜ Pass / ⬜ Pass with Issues / ⬜ Fail

package/src/modules/bmb/workflows/create-module/installer-templates/install-config.yaml

@@ -0,0 +1,92 @@
+# {{MODULE_NAME}} Module Configuration
+# This file defines installation questions and module configuration values
+
+code: "{{MODULE_CODE}}"
+name: "{{MODULE_NAME}}"
+default_selected: "{{DEFAULT_SELECTED}}" # true if this should be selected by default
+
+# Welcome message shown during installation
+prompt:
+  - "{{WELCOME_MESSAGE_LINE_1}}"
+  - "{{WELCOME_MESSAGE_LINE_2}}"
+# Core config values are automatically inherited:
+## user_name
+## communication_language
+## document_output_language
+## output_folder
+
+# ============================================================================
+# CONFIGURATION FIELDS
+# ============================================================================
+#
+# Each field can be:
+# 1. INTERACTIVE (has 'prompt' - asks user during installation)
+# 2. STATIC (no 'prompt' - just uses 'result' value)
+#
+# Field structure:
+#   field_name:
+#     prompt: "Question to ask user" (optional - omit for static values)
+#     default: "default_value" (optional)
+#     result: "{value}" or "static-value"
+#     single-select: [...] (optional - for dropdown)
+#     multi-select: [...] (optional - for checkboxes)
+#
+# Special placeholders in result:
+#   {value} - replaced with user's answer
+#   {project-root} - replaced with project root path
+#   {directory_name} - replaced with project directory name
+#   {module_code} - replaced with this module's code
+# ============================================================================
+
+# EXAMPLE: Interactive text input
+# example_project_name:
+#   prompt: "What is your project name?"
+#   default: "{directory_name}"
+#   result: "{value}"
+
+# EXAMPLE: Interactive single-select dropdown
+# example_skill_level:
+#   prompt: "What is your experience level?"
+#   default: "intermediate"
+#   result: "{value}"
+#   single-select:
+#     - value: "beginner"
+#       label: "Beginner - New to this domain"
+#     - value: "intermediate"
+#       label: "Intermediate - Familiar with basics"
+#     - value: "expert"
+#       label: "Expert - Deep knowledge"
+
+# EXAMPLE: Interactive multi-select checkboxes
+# example_features:
+#   prompt:
+#     - "Which features do you want to enable?"
+#     - "(Select all that apply)"
+#   result: "{value}"
+#   multi-select:
+#     - "Feature A"
+#     - "Feature B"
+#     - "Feature C"
+
+# EXAMPLE: Interactive path input
+# example_output_path:
+#   prompt: "Where should outputs be saved?"
+#   default: "output/{{MODULE_CODE}}"
+#   result: "{project-root}/{value}"
+
+# EXAMPLE: Static value (no user prompt)
+# example_static_setting:
+#   result: "hardcoded-value"
+
+# EXAMPLE: Static path
+# module_data_path:
+#   result: "{project-root}/bmad/{{MODULE_CODE}}/data"
+
+# ============================================================================
+# YOUR MODULE CONFIGURATION FIELDS
+# ============================================================================
+# Replace examples above with your module's actual configuration needs.
+# Delete this comment block and the examples when implementing.
+# ============================================================================
+
+# TODO: INSERT {MODULE_CONFIG_FIELDS} HERE