bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.4

package/bmad/bmb/workflows/create-module/README.md

@@ -1,220 +1,229 @@
-# Build Module Workflow
+# Create Module Workflow
 
-## Overview
+Interactive scaffolding system creating complete BMad modules with agents, workflows, tasks, and installation infrastructure.
 
-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.
+## Table of Contents
 
-## Key Features
+- [Quick Start](#quick-start)
+- [Workflow Phases](#workflow-phases)
+- [Output Structure](#output-structure)
+- [Module Components](#module-components)
+- [Best Practices](#best-practices)
 
-- **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
+## Quick Start
 
 ```bash
+# Basic invocation
 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:
+# With module brief input
+workflow create-module --input module-brief-{name}-{date}.md
 
-- **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
+# Via BMad Builder
+*create-module
 ```
 
-## Workflow Process
-
-### Phase 1: Concept Definition (Steps 1-2)
+## Workflow Phases
 
-**Module Vision and Identity**
+### Phase 1: Concept Definition
 
-- 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
+- Define module purpose and audience
+- Establish module code (kebab-case) and name
+- Choose category (Domain, Creative, Technical, Business, Personal)
+- Plan component architecture
 
-**Module Brief Integration**
+**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
+- Auto-detects existing briefs
+- Uses as pre-populated blueprint
+- Accelerates planning phase
 
-### Phase 2: Architecture Planning (Steps 3-4)
+### Phase 2: Architecture Planning
 
-**Directory Structure Creation**
+- Create directory hierarchy
+- Setup configuration system
+- Define installer structure
+- Establish component folders
 
-- Creates complete module directory hierarchy
-- Sets up agent, workflow, task, template, and data folders
-- Establishes installer directory with proper configuration
+### Phase 3: Component Creation
 
-**Module Configuration**
+- Optional first agent creation
+- Optional first workflow creation
+- Component placeholder generation
+- Integration validation
 
-- 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 4: Installation Setup
 
-### Phase 3: Component Creation (Steps 5-6)
+- Create install-config.yaml
+- Configure deployment questions
+- Setup installer logic
+- Post-install messaging
 
-**Interactive Component Building**
+### Phase 5: Documentation
 
-- 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
+- Generate comprehensive README
+- Create development roadmap
+- Provide quick commands
+- Document next steps
 
-**Workflow Integration**
+## Output Structure
 
-- Seamlessly invokes sub-workflows for component creation
-- Ensures proper file placement and structure
-- Maintains module consistency across components
+### Generated Directory
 
-### Phase 4: Installation and Documentation (Steps 7-9)
-
-**Installer Infrastructure**
+```
+bmad/{module-code}/
+├── agents/              # Agent definitions
+├── workflows/           # Workflow processes
+├── tasks/              # Reusable tasks
+├── templates/          # Document templates
+├── data/               # Module data files
+├── _module-installer/  # Installation logic
+│   ├── install-config.yaml
+│   └── installer.js
+├── README.md           # Module documentation
+├── TODO.md            # Development roadmap
+└── config.yaml        # Runtime configuration
+```
 
-- Creates install-config.yaml with configuration questions for deployment
-- Sets up optional installer.js for complex installation logic
-- Configures post-install messaging and instructions
+### Configuration Files
 
-**Comprehensive Documentation**
+**install-config.yaml** - Installation questions
 
-- Generates detailed README.md with usage examples
-- Creates development roadmap for remaining components
-- Provides quick commands for continued development
+```yaml
+questions:
+  - id: user_name
+    prompt: 'Your name?'
+    default: 'User'
+  - id: output_folder
+    prompt: 'Output location?'
+    default: './output'
+```
 
-### Phase 5: Validation and Finalization (Step 10)
+**config.yaml** - Generated from user answers during install
 
-**Quality Assurance**
+```yaml
+user_name: 'John Doe'
+output_folder: './my-output'
+```
 
-- 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
+## Module Components
 
-## Output
+### Agents
 
-### Generated Files
+- Full module agents with workflows
+- Expert agents with sidecars
+- Simple utility agents
 
-- **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
+### Workflows
 
-### Output Structure
+- Multi-step guided processes
+- Configuration-driven
+- Web bundle support
 
-The workflow creates a complete module ready for development:
+### Tasks
 
-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
+- Reusable operations
+- Agent-agnostic
+- Modular components
 
-## Requirements
+### Templates
 
-- **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
+- Document structures
+- Output formats
+- Report templates
 
 ## Best Practices
 
-### Before Starting
+### Planning
 
-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
+1. **Use module-brief workflow first** - Creates comprehensive blueprint
+2. **Define clear scope** - Avoid feature creep
+3. **Plan component interactions** - Map agent/workflow relationships
 
-### During Execution
+### Structure
 
-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
+1. **Follow conventions** - Use established patterns
+2. **Keep components focused** - Single responsibility
+3. **Document thoroughly** - Clear README and inline docs
 
-### After Completion
+### Development
 
-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
+1. **Start with core agent** - Build primary functionality first
+2. **Create key workflows** - Essential processes before edge cases
+3. **Test incrementally** - Validate as you build
 
-## Troubleshooting
+### Installation
 
-### Common Issues
+1. **Minimal config questions** - Only essential settings
+2. **Smart defaults** - Sensible out-of-box experience
+3. **Clear post-install** - Guide users to first steps
 
-**Issue**: Module already exists at target location
+## Integration Points
 
-- **Solution**: Choose a different module code or remove existing module
-- **Check**: Verify output folder permissions and available space
+### With Other Workflows
 
-**Issue**: Sub-workflow invocation fails
+- **module-brief** - Strategic planning input
+- **create-agent** - Agent component creation
+- **create-workflow** - Workflow building
+- **redoc** - Documentation maintenance
 
-- **Solution**: Ensure create-agent and create-workflow workflows are available
-- **Check**: Validate workflow paths in config.yaml
+### With BMad Core
 
-**Issue**: Installation configuration invalid
+- Uses core framework capabilities
+- Integrates with module system
+- Follows BMad conventions
 
-- **Solution**: Review install-config.yaml syntax and paths
-- **Check**: Ensure all referenced paths use {project-root} variables correctly
+## Examples
 
-## Customization
+### Domain-Specific Module
 
-To customize this workflow:
+```
+Category: Domain-Specific
+Code: legal-advisor
+Components:
+- Contract Review Agent
+- Compliance Workflow
+- Legal Templates
+```
 
-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
+### Creative Module
 
-## Version History
+```
+Category: Creative
+Code: story-builder
+Components:
+- Narrative Agent
+- Plot Workflow
+- Character Templates
+```
 
-- **v1.0.0** - Initial release
-  - Interactive module scaffolding
-  - Component integration with create-agent and create-workflow
-  - Complete installation infrastructure
-  - Module brief integration support
+### Technical Module
 
-## Support
+```
+Category: Technical
+Code: api-tester
+Components:
+- Test Runner Agent
+- API Validation Workflow
+- Test Report Templates
+```
 
-For issues or questions:
+## Workflow Files
 
-- 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
+```
+create-module/
+├── workflow.yaml          # Configuration
+├── instructions.md        # Step guide
+├── checklist.md          # Validation
+├── module-structure.md   # Architecture
+├── installer-templates/  # Install files
+└── README.md            # This file
+```
 
----
+## Related Documentation
 
-_Part of the BMad Method v6 - BMB (Builder) Module_
+- [Module Structure](./module-structure.md)
+- [Module Brief Workflow](../module-brief/README.md)
+- [Create Agent](../create-agent/README.md)
+- [Create Workflow](../create-workflow/README.md)
+- [BMB Module](../../README.md)

package/bmad/bmb/workflows/create-module/workflow.yaml.bak

@@ -37,4 +37,6 @@ 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

package/bmad/bmb/workflows/create-workflow/instructions.md

@@ -108,7 +108,8 @@ Most workflows should be `standalone: true` to give users direct access.
 1. **Yes (Recommended)** - Users can run it directly (standalone: true)
 2. **No** - Only called by other workflows/agents (standalone: false)
 
-Most workflows choose option 1:</ask>
+Most workflows choose option 1:
+</ask>
 
 <action>Store {{standalone_setting}} as true or false based on response</action>
 
@@ -150,7 +151,8 @@ The architecture workflow is an excellent example of intent-based with prescript
 2. **Prescriptive** - Structured, consistent, controlled interactions
 3. **Mixed/Balanced** - I'll help you decide step-by-step
 
-What feels right for your workflow's purpose?</ask>
+What feels right for your workflow's purpose?
+</ask>
 
 <action>Store {{instruction_style}} preference</action>
 
@@ -185,11 +187,12 @@ Beyond style, consider **how interactive** this workflow should be:
 
 <ask>What interactivity level suits this workflow?
 
-1. **High** - Highly collaborative, user actively involved throughout
-2. **Medium** - Guided with key decision points (most common)
-3. **Low** - Autonomous with final review
+1. **High** - Highly collaborative, user actively involved throughout (Recommended)
+2. **Medium** - Guided with key decision points
+3. **Low** - Mostly autonomous with final review
 
-Select the level that matches your workflow's purpose:</ask>
+Select the level that matches your workflow's purpose:
+</ask>
 
 <action>Store {{interactivity_level}} preference</action>
 
@@ -487,6 +490,7 @@ Generate the template.md file following guide conventions:
    # Document Title
 
    **Date:** {{date}}
+
    **Author:** {{user_name}}
    ```
 
@@ -575,7 +579,9 @@ Review the created workflow:
 4. Validate YAML syntax
 5. Confirm all placeholders are replaced
 
-**Standard Config Validation:** 6. Verify workflow.yaml contains standard config block:
+**Standard Config Validation:**
+
+6. Verify workflow.yaml contains standard config block:
 
 - config_source defined
 - output_folder, user_name, communication_language pulled from config
@@ -584,7 +590,9 @@ Review the created workflow:
 7. Check instructions use config variables where appropriate
 8. Verify template includes config variables in metadata (if document workflow)
 
-**YAML/Instruction/Template Alignment:** 9. Cross-check all workflow.yaml variables against instruction usage:
+**YAML/Instruction/Template Alignment:**
+
+9. Cross-check all workflow.yaml variables against instruction usage:
 
 - Are all yaml variables referenced in instructions.md OR template.md?
 - Are there hardcoded values that should be variables?

package/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md

@@ -1020,6 +1020,164 @@ _Generated on {{date}}_
 - **Unclosed check tags** - Always close `<check if="">...</check>` blocks
 - **Wrong conditional pattern** - Use `<action if="">` for single items, `<check if="">` for blocks
 
+## Document Sharding Support
+
+If your workflow loads large planning documents (PRDs, epics, architecture, etc.), implement sharding support for efficiency.
+
+### What is Document Sharding?
+
+Document sharding splits large markdown files into smaller section-based files:
+
+- `PRD.md` (50k tokens) → `prd/epic-1.md`, `prd/epic-2.md`, etc.
+- Enables selective loading (90%+ token savings)
+- All BMM workflows support both whole and sharded documents
+
+### When to Add Sharding Support
+
+**Add sharding support if your workflow:**
+
+- Loads planning documents (PRD, epics, architecture, UX specs)
+- May be used in large multi-epic projects
+- Processes documents that could exceed 20k tokens
+- Would benefit from selective section loading
+
+**Skip sharding support if your workflow:**
+
+- Only generates small documents
+- Doesn't load external documents
+- Works with code files (not planning docs)
+
+### Implementation Pattern
+
+#### 1. Add input_file_patterns to workflow.yaml
+
+```yaml
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  prd:
+    whole: '{output_folder}/*prd*.md'
+    sharded: '{output_folder}/*prd*/index.md'
+
+  epics:
+    whole: '{output_folder}/*epic*.md'
+    sharded_index: '{output_folder}/*epic*/index.md'
+    sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md' # For selective load
+
+  architecture:
+    whole: '{output_folder}/*architecture*.md'
+    sharded: '{output_folder}/*architecture*/index.md'
+
+  document_project:
+    sharded: '{output_folder}/docs/index.md' # Brownfield always uses index
+```
+
+#### 2. Add Discovery Instructions to instructions.md
+
+Place early in instructions (after critical declarations, before workflow steps):
+
+```markdown
+## 📚 Document Discovery
+
+This workflow requires: [list required documents]
+
+**Discovery Process** (execute for each document):
+
+1. **Search for whole document first** - Use fuzzy file matching
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL section files listed in the index (or specific sections for selective load)
+   - Treat the combined content as if it were a single document
+4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**Fuzzy matching**: Be flexible with document names - users may use variations.
+```
+
+#### 3. Choose Loading Strategy
+
+**Full Load Strategy** (most workflows):
+
+```xml
+<action>Search for document using fuzzy pattern: {output_folder}/*prd*.md</action>
+<action>If not found, check for sharded version: {output_folder}/*prd*/index.md</action>
+<action if="sharded found">Read index.md to understand structure</action>
+<action if="sharded found">Read ALL section files listed in index</action>
+<action if="sharded found">Combine content as single document</action>
+```
+
+**Selective Load Strategy** (advanced - for phase 4 type workflows):
+
+```xml
+<action>Determine section needed (e.g., epic_num from story key)</action>
+<action>Check for sharded version: {output_folder}/*epics*/index.md</action>
+<action if="sharded found">Read ONLY the specific section file: epics/epic-{{epic_num}}.md</action>
+<action if="sharded found">Skip all other section files (efficiency optimization)</action>
+<action if="whole document found">Load complete document and extract relevant section</action>
+```
+
+### Pattern Examples
+
+**Example 1: Simple Full Load**
+
+```yaml
+# workflow.yaml
+input_file_patterns:
+  requirements:
+    whole: '{output_folder}/*requirements*.md'
+    sharded: '{output_folder}/*requirements*/index.md'
+```
+
+```markdown
+<!-- instructions.md -->
+
+## Document Discovery
+
+Load requirements document (whole or sharded).
+
+1. Try whole: _requirements_.md
+2. If not found, try sharded: _requirements_/index.md
+3. If sharded: Read index + ALL section files
+```
+
+**Example 2: Selective Load with Epic Number**
+
+```yaml
+# workflow.yaml
+input_file_patterns:
+  epics:
+    whole: '{output_folder}/*epic*.md'
+    sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md'
+```
+
+```xml
+<!-- instructions.md step -->
+<step n="2" goal="Load Epic Content">
+  <action>Extract epic number from story key (e.g., "3-2-feature" → epic_num = 3)</action>
+  <action>Check for sharded epics: {output_folder}/*epic*/index.md</action>
+  <action if="sharded found">Load ONLY epics/epic-{{epic_num}}.md (selective optimization)</action>
+  <action if="whole document found">Load full epics.md and extract Epic {{epic_num}}</action>
+</step>
+```
+
+### Testing Your Sharding Support
+
+1. **Test with whole document**: Verify workflow works with single `document.md`
+2. **Test with sharded document**: Create sharded version and verify discovery
+3. **Test with both present**: Ensure whole document takes priority
+4. **Test selective loading**: Verify only needed sections are loaded (if applicable)
+
+### Complete Reference
+
+**[→ Document Sharding Guide](../../../../docs/document-sharding-guide.md)** - Comprehensive guide with examples
+
+**BMM Examples**:
+
+- Full Load: `src/modules/bmm/workflows/2-plan-workflows/prd/`
+- Selective Load: `src/modules/bmm/workflows/4-implementation/epic-tech-context/`
+
 ## Web Bundles
 
 Web bundles allow workflows to be deployed as self-contained packages for web environments.

package/bmad/bmb/workflows/create-workflow/workflow.yaml.bak

@@ -35,4 +35,6 @@ workflow_template_path: "{installed_path}/workflow-template"
 # If standalone workflow: Save to custom_workflow_location/{{workflow_name}}
 module_output_folder: "{project-root}/bmad/{{target_module}}/workflows/{{workflow_name}}"
 standalone_output_folder: "{custom_workflow_location}/{{workflow_name}}"
+
+standalone: true
 # Web bundle configuration

package/bmad/bmb/workflows/edit-agent/workflow.yaml.bak

@@ -0,0 +1,33 @@
+# Edit Agent - Agent Editor Configuration
+name: "edit-agent"
+description: "Edit existing BMAD agents 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 agent conventions
+agent_types: "{project-root}/bmad/bmb/workflows/create-agent/agent-types.md"
+agent_architecture: "{project-root}/bmad/bmb/workflows/create-agent/agent-architecture.md"
+agent_commands: "{project-root}/bmad/bmb/workflows/create-agent/agent-command-patterns.md"
+communication_styles: "{project-root}/bmad/bmb/workflows/create-agent/communication-styles.md"
+
+# Workflow execution engine reference
+workflow_execution_engine: "{project-root}/bmad/core/tasks/workflow.xml"
+
+# Optional docs that can be used to understand the target agent
+recommended_inputs:
+  - target_agent: "Path to the agent.yaml or agent.md file to edit"
+  - example_agents: "{project-root}/bmad/bmm/agents/"
+  - agent_activation_rules: "{project-root}/src/utility/models/agent-activation-ide.xml"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmb/workflows/edit-agent"
+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