BMAD-METHOD/.bmad/bmb/workflows/edit-module/README.md

Edit Module Workflow

Interactive workflow for editing existing BMAD modules, including structure, agents, workflows, configuration, and documentation.

Purpose

This workflow helps you improve and maintain BMAD modules by:

• Analyzing module structure against best practices
• Managing agents and workflows within the module
• Updating configuration and documentation
• Ensuring cross-module integration works correctly
• Maintaining installer configuration (for source modules)

When to Use

Use this workflow when you need to:

• Add new agents or workflows to a module
• Update module configuration
• Improve module documentation
• Reorganize module structure
• Set up cross-module workflow sharing
• Fix issues in module organization
• Update installer configuration

What You'll Need

• Path to the module directory you want to edit
• Understanding of what changes you want to make
• Access to module documentation (loaded automatically)

Workflow Steps

1. Load and analyze target module - Provide path to module directory
2. Analyze against best practices - Automatic audit of module structure
3. Select editing focus - Choose what aspect to edit
4. Load relevant documentation and tools - Auto-loads guides and workflows
5. Perform edits - Review and approve changes iteratively
6. Validate all changes - Comprehensive validation checklist
7. Generate change summary - Summary of improvements made

Editing Options

The workflow provides 12 focused editing options:

1. Fix critical issues - Address missing files, broken references
2. Update module config - Edit config.yaml fields
3. Manage agents - Add, edit, or remove agents
4. Manage workflows - Add, edit, or remove workflows
5. Update documentation - Improve README files and guides
6. Reorganize structure - Fix directory organization
7. Add new agent - Create and integrate new agent
8. Add new workflow - Create and integrate new workflow
9. Update installer - Modify installer configuration (source only)
10. Cross-module integration - Set up workflow sharing with other modules
11. Remove deprecated items - Delete unused agents, workflows, or files
12. Full module review - Comprehensive analysis and improvements

Integration with Other Workflows

This workflow integrates with:

• edit-agent - For editing individual agents
• edit-workflow - For editing individual workflows
• create-agent - For adding new agents
• create-workflow - For adding new workflows

When you select options to manage agents or workflows, the appropriate specialized workflow is invoked automatically.

Module Structure

A proper BMAD module has:

module-code/
├── agents/              # Agent definitions
│   └── *.agent.yaml
├── workflows/           # Workflow definitions
│   └── workflow-name/
│       ├── workflow.yaml
│       ├── instructions.md
│       ├── checklist.md
│       └── README.md
├── config.yaml          # Module configuration
└── README.md           # Module documentation

Standard Module Config

Every module config.yaml should have:

module_name: 'Full Module Name'
module_code: 'xyz'
user_name: 'User Name'
communication_language: 'english'
output_folder: 'path/to/output'

Optional fields may be added for module-specific needs.

Cross-Module Integration

Modules can share workflows:

# In agent menu item:
workflow: '{project-root}/.bmad/other-module/workflows/shared-workflow/workflow.yaml'

Common patterns:

• BMM uses CIS brainstorming workflows
• All modules can use core workflows
• Modules can invoke each other's workflows

Output

The workflow modifies module files in place, including:

• config.yaml
• Agent files
• Workflow files
• README and documentation files
• Directory structure (if reorganizing)

Changes are reviewed and approved by you before being applied.

Best Practices

• Start with analysis - Let the workflow audit your module first
• Use specialized workflows - Let edit-agent and edit-workflow handle detailed edits
• Update documentation - Keep README files current with changes
• Validate thoroughly - Use the validation step to catch structural issues
• Test after editing - Invoke agents and workflows to verify they work

Tips

• For adding agents/workflows, use options 7-8 to create and integrate in one step
• For quick config changes, use option 2 (update module config)
• Cross-module integration (option 10) helps set up workflow sharing
• Full module review (option 12) is great for inherited or legacy modules
• The workflow handles path updates when you reorganize structure

Source vs Installed Modules

Source modules (in src/modules/):

• Have installer files in tools/cli/installers/
• Can configure web bundles
• Are the development source of truth

Installed modules (in .bmad/):

• Are deployed to target projects
• Use config.yaml for user customization
• Are compiled from source during installation

This workflow works with both, but installer options only apply to source modules.

Example Usage

User: I want to add a new workflow to BMM for API design
Workflow: Analyzes BMM → You choose option 8 (add new workflow)
          → Invokes create-workflow → Creates workflow
          → Integrates it into module → Updates README → Done

Activation

Invoke via BMad Builder agent:

/bmad:bmb:agents:bmad-builder
Then select: *edit-module

Or directly via workflow.xml with this workflow config.

Related Resources

• Module Structure Guide - Comprehensive module architecture documentation
• BMM Module - Example of full-featured module
• BMB Module - Example of builder/tooling module
• CIS Module - Example of workflow library module