bmad-method 6.0.0-alpha.0 → 6.0.0-alpha.1

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

@@ -0,0 +1,187 @@
+# 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:
+
+```yaml
+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:
+
+```yaml
+# 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

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

@@ -0,0 +1,165 @@
+# Edit Module - Validation Checklist
+
+Use this checklist to validate module edits meet BMAD Core standards.
+
+## Module Structure Validation
+
+- [ ] Module has clear 3-letter code (bmm, bmb, cis, etc.)
+- [ ] Module is in correct location (src/modules/ for source, bmad/ for installed)
+- [ ] agents/ directory exists
+- [ ] workflows/ directory exists
+- [ ] config.yaml exists in module root
+- [ ] README.md exists in module root
+- [ ] Directory structure follows BMAD conventions
+
+## Configuration Validation
+
+### Required Fields
+
+- [ ] module_name is descriptive and clear
+- [ ] module_code is 3-letter code matching directory name
+- [ ] user_name field present
+- [ ] communication_language field present
+- [ ] output_folder field present
+
+### Optional Fields (if used)
+
+- [ ] custom_agent_location documented
+- [ ] custom_module_location documented
+- [ ] Module-specific fields documented in README
+
+### File Quality
+
+- [ ] config.yaml is valid YAML syntax
+- [ ] No duplicate keys
+- [ ] Values are appropriate types (strings, paths, etc.)
+- [ ] Comments explain non-obvious fields
+
+## Agent Validation
+
+### Agent Files
+
+- [ ] All agents in agents/ directory
+- [ ] Agent files follow naming: {agent-name}.agent.yaml or .md
+- [ ] Agent filenames use kebab-case
+- [ ] No orphaned or temporary agent files
+
+### Agent Content
+
+- [ ] Each agent has clear role and purpose
+- [ ] Agents reference workflows correctly
+- [ ] Agent workflow paths are valid
+- [ ] Agents load module config correctly (if needed)
+- [ ] Agent menu items reference existing workflows
+
+### Agent Integration
+
+- [ ] All agents listed in module README
+- [ ] Agent relationships documented (if applicable)
+- [ ] Cross-agent workflows properly linked
+
+## Workflow Validation
+
+### Workflow Structure
+
+- [ ] All workflows in workflows/ directory
+- [ ] Each workflow directory has workflow.yaml
+- [ ] Each workflow directory has instructions.md
+- [ ] Workflow directories use kebab-case naming
+- [ ] No orphaned or incomplete workflow directories
+
+### Workflow Content
+
+- [ ] workflow.yaml is valid YAML
+- [ ] workflow.yaml has name field
+- [ ] workflow.yaml has description field
+- [ ] workflow.yaml has author field
+- [ ] instructions.md has proper <workflow> structure
+- [ ] Workflow steps are numbered and logical
+
+### Workflow Integration
+
+- [ ] All workflows listed in module README
+- [ ] Workflow paths in agents are correct
+- [ ] Cross-module workflow references are valid
+- [ ] Sub-workflow references exist
+
+## Documentation Validation
+
+### Module README
+
+- [ ] Module README describes purpose clearly
+- [ ] README lists all agents with descriptions
+- [ ] README lists all workflows with descriptions
+- [ ] README includes installation instructions (if applicable)
+- [ ] README explains module's role in BMAD ecosystem
+
+### Workflow READMEs
+
+- [ ] Each workflow has its own README.md
+- [ ] Workflow READMEs explain purpose
+- [ ] Workflow READMEs list inputs/outputs
+- [ ] Workflow READMEs include usage examples
+
+### Other Documentation
+
+- [ ] Usage guides present (if needed)
+- [ ] Architecture docs present (if complex module)
+- [ ] Examples provided (if applicable)
+
+## Cross-References Validation
+
+- [ ] Agent workflow references point to existing workflows
+- [ ] Workflow sub-workflow references are valid
+- [ ] Cross-module references use correct paths
+- [ ] Config file paths use {project-root} correctly
+- [ ] No hardcoded absolute paths
+
+## Installer Validation (Source Modules Only)
+
+- [ ] Installer script exists in tools/cli/installers/
+- [ ] Installer script name: install-{module-code}.js
+- [ ] Module metadata in installer is correct
+- [ ] Web bundle configuration valid (if applicable)
+- [ ] Installation paths are correct
+- [ ] Dependencies documented in installer
+
+## Web Bundle Validation (If Applicable)
+
+- [ ] Web bundles configured in workflow.yaml files
+- [ ] All referenced files included in web_bundle_files
+- [ ] Paths are bmad/-relative (not project-root)
+- [ ] No config_source references in web bundles
+- [ ] Invoked workflows included in dependencies
+
+## Quality Checks
+
+- [ ] No placeholder text remains ({MODULE_NAME}, {CODE}, etc.)
+- [ ] No broken file references
+- [ ] No duplicate content across files
+- [ ] Consistent naming conventions throughout
+- [ ] Module purpose is clear from README alone
+
+## Integration Checks
+
+- [ ] Module doesn't conflict with other modules
+- [ ] Shared resources properly documented
+- [ ] Dependencies on other modules explicit
+- [ ] Module can be installed independently (if designed that way)
+
+## User Experience
+
+- [ ] Module purpose is immediately clear
+- [ ] Agents have intuitive names
+- [ ] Workflows have descriptive names
+- [ ] Menu items are logically organized
+- [ ] Error messages are helpful
+- [ ] Success messages confirm actions
+
+## Final Checks
+
+- [ ] All files have been saved
+- [ ] File permissions are correct
+- [ ] Git status shows expected changes
+- [ ] Module is ready for testing
+- [ ] Documentation accurately reflects changes

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

@@ -0,0 +1,339 @@
+# Edit Module - Module 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-module/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 module">
+<ask>What is the path to the module you want to edit? (provide path to module directory like bmad/bmm/ or src/modules/bmm/)</ask>
+
+<action>Load the module directory structure completely:
+
+- Scan all directories and files
+- Load config.yaml
+- Load README.md
+- List all agents in agents/ directory
+- List all workflows in workflows/ directory
+- Check for installer files (if in src/modules/)
+- Identify any custom structure or patterns
+  </action>
+
+<action>Load ALL module documentation to inform understanding:
+
+- Module structure guide: {module_structure_guide}
+- Study reference modules: BMM, BMB, CIS
+- Understand BMAD module patterns and conventions
+  </action>
+
+<action>Analyze the module deeply:
+
+- Identify module purpose and role in BMAD ecosystem
+- Understand agent organization and relationships
+- Map workflow organization and dependencies
+- Evaluate config structure and completeness
+- Check documentation quality and currency
+- Assess installer configuration (if source module)
+- Identify cross-module integrations
+- Evaluate against best practices from loaded guides
+  </action>
+
+<action>Reflect understanding back to {user_name}:
+
+Present a warm, conversational summary adapted to the module's complexity:
+
+- What this module provides (its purpose and value in BMAD)
+- How it's organized (agents, workflows, structure)
+- What you notice (strengths, potential improvements, issues)
+- How it fits in the larger BMAD ecosystem
+- Your initial assessment based on best practices
+
+Be conversational and insightful. Help {user_name} see their module through your eyes.
+</action>
+
+<ask>Does this match your understanding of what this module should provide?</ask>
+<template-output>module_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 module?
+- What feedback have you gotten from users of this module?
+- Are there specific agents or workflows that need attention?
+- Is the module fulfilling its intended purpose?
+- Are there new capabilities you want to add?
+- How well does it integrate with other modules?
+- Is the documentation helping users understand and use the module?
+
+Listen for clues about:
+
+- Structural issues (poor organization, hard to navigate)
+- Agent/workflow issues (outdated, broken, missing functionality)
+- Configuration issues (missing fields, incorrect setup)
+- Documentation issues (outdated, incomplete, unclear)
+- Integration issues (doesn't work well with other modules)
+- Installer issues (installation problems, missing files)
+- User experience issues (confusing, hard to use)
+  </action>
+
+<action>Based on their responses and your analysis from step 1, identify improvement opportunities:
+
+Organize by priority and user goals:
+
+- CRITICAL issues blocking module functionality
+- 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>Collaborate on priorities:
+
+Don't just list options - discuss them:
+
+- "I noticed {{issue}} - this could make it hard for users to {{problem}}. Want to address this?"
+- "The module 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>
+<critical>For agent and workflow edits, invoke specialized workflows rather than doing inline</critical>
+
+<action>For each improvement area, facilitate collaboratively:
+
+1. **Explain the current state and why it matters**
+   - Show relevant sections of the module
+   - 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 reference modules when helpful
+   - Reference the structure 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 appropriately**
+   - For agent edits: Invoke edit-agent workflow
+   - For workflow edits: Invoke edit-workflow workflow
+   - For module-level changes: Make directly and iteratively
+   - Show updates and confirm satisfaction
+     </action>
+
+<action>Common improvement patterns to facilitate:
+
+**If improving module organization:**
+
+- Discuss how the current structure serves (or doesn't serve) users
+- Propose reorganization that aligns with mental models
+- Consider feature-based vs type-based organization
+- Plan the reorganization steps
+- Update all references after moving files
+
+**If updating module configuration:**
+
+- Review current config.yaml fields
+- Check for missing standard fields (user_name, communication_language, output_folder)
+- Add module-specific fields as needed
+- Remove unused or outdated fields
+- Ensure config is properly documented
+
+**If managing agents:**
+
+- Ask which agent needs attention and why
+- For editing existing agent: <invoke-workflow path="{agent_editor}">
+- For adding new agent: Guide creation and integration
+- For removing agent: Confirm, remove, update references
+- Ensure all agent references in workflows remain valid
+
+**If managing workflows:**
+
+- Ask which workflow needs attention and why
+- For editing existing workflow: <invoke-workflow path="{workflow_editor}">
+- For adding new workflow: Guide creation and integration
+- For removing workflow: Confirm, remove, update agent references
+- Ensure all workflow files are properly organized
+
+**If improving documentation:**
+
+- Review current README and identify gaps
+- Discuss what users need to know
+- Update module overview and purpose
+- List agents and workflows with clear descriptions
+- Add usage examples if helpful
+- Ensure installation/setup instructions are clear
+
+**If setting up cross-module integration:**
+
+- Identify which workflows from other modules are needed
+- Show how to reference workflows properly: {project-root}/bmad/{{module}}/workflows/{{workflow}}/workflow.yaml
+- Document the integration in README
+- Ensure dependencies are clear
+- Consider adding example usage
+
+**If updating installer (source modules only):**
+
+- Review installer script for correctness
+- Check web bundle configurations
+- Verify all files are included
+- Test installation paths
+- Update module metadata
+  </action>
+
+<action>When invoking specialized workflows:
+
+Explain why you're handing off:
+
+- "This agent needs detailed attention. Let me invoke the edit-agent workflow to give it proper focus."
+- "The workflow editor can handle this more thoroughly. I'll pass control there."
+
+After the specialized workflow completes, return and continue:
+
+- "Great! That agent/workflow is updated. Want to work on anything else in the module?"
+  </action>
+
+<action>Throughout improvements, educate when helpful:
+
+Share insights from the guides naturally:
+
+- "The module structure guide recommends {{pattern}} for this scenario"
+- "Looking at how BMM organized this, we could use {{approach}}"
+- "The BMAD convention is to {{pattern}} which helps with {{benefit}}"
+
+Connect improvements to broader BMAD principles without being preachy.
+</action>
+
+<ask>After each significant change:
+
+- "Does this organization feel more intuitive?"
+- "Want to refine this further, or move to the next improvement?"
+- "How does this change affect users of the module?"
+  </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 the module structure is solid..."
+- "Checking that all agent workflow references are valid..."
+- "Making sure config.yaml has all necessary fields..."
+- "Validating documentation is complete and accurate..."
+- "Ensuring cross-module references work correctly..."
+  </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}} for users"
+- "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:
+
+- Module structure is well-organized
+- All agent and workflow references are valid
+- Configuration is complete
+- Documentation is thorough and current
+- Cross-module integrations work properly
+- Installer is correct (if applicable)
+
+Your module 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 module {{improved_capabilities}}"
+
+Highlight the impact:
+
+- "This means users will experience {{benefit}}"
+- "The module is now more {{quality}}"
+- "It follows best practices for {{patterns}}"
+  </action>
+
+<action>Guide next steps based on changes made:
+
+If structure changed significantly:
+
+- "Since we reorganized the structure, you should update any external references to this module"
+
+If agents or workflows were updated:
+
+- "The updated agents/workflows should be tested with real user interactions"
+
+If cross-module integration was added:
+
+- "Test the integration with {{other_module}} to ensure it works smoothly"
+
+If installer was updated:
+
+- "Test the installation process to verify all files are included correctly"
+
+If this is part of larger BMAD work:
+
+- "Consider if patterns from this module could benefit other modules"
+
+Be a helpful guide to what comes next, not just a task completer.
+</action>
+
+<ask>Would you like to:
+
+- Test the edited module by invoking one of its agents
+- Edit a specific agent or workflow in more detail
+- Make additional refinements to the module
+- Work on a different module
+  </ask>
+
+<template-output>completion_summary</template-output>
+</step>
+
+</workflow>