bmad-method 5.1.3 → 6.0.0-alpha.1

package/src/modules/bmb/workflows/convert-legacy/README.md

@@ -0,0 +1,262 @@
+# Convert Legacy Workflow
+
+## Overview
+
+The Convert Legacy workflow is a comprehensive migration tool that converts BMAD v4 items (agents, workflows, modules) to v6 compliant format with proper structure and conventions. It bridges the gap between legacy BMAD implementations and the modern v6 architecture, ensuring seamless migration while preserving functionality and improving structure.
+
+## Key Features
+
+- **Multi-Format Detection** - Automatically identifies v4 agents, workflows, tasks, templates, and modules
+- **Intelligent Conversion** - Smart mapping from v4 patterns to v6 equivalents with structural improvements
+- **Sub-Workflow Integration** - Leverages create-agent, create-workflow, and create-module workflows for quality output
+- **Structure Modernization** - Converts YAML-based agents to XML, templates to workflows, tasks to structured workflows
+- **Path Normalization** - Updates all references to use proper v6 path conventions
+- **Validation System** - Comprehensive validation of converted items before finalization
+- **Migration Reporting** - Detailed conversion reports with locations and manual adjustment notes
+
+## Usage
+
+### Basic Invocation
+
+```bash
+workflow convert-legacy
+```
+
+### With Legacy File Input
+
+```bash
+# Convert a specific v4 item
+workflow convert-legacy --input /path/to/legacy-agent.md
+```
+
+### With Legacy Module
+
+```bash
+# Convert an entire v4 module structure
+workflow convert-legacy --input /path/to/legacy-module/
+```
+
+### Configuration
+
+The workflow uses standard BMB configuration:
+
+- **output_folder**: Where converted items will be placed
+- **user_name**: Author information for converted items
+- **conversion_mappings**: v4-to-v6 pattern mappings (optional)
+
+## Workflow Structure
+
+### Files Included
+
+```
+convert-legacy/
+├── workflow.yaml           # Configuration and metadata
+├── instructions.md         # Step-by-step conversion guide
+├── checklist.md           # Validation criteria
+└── README.md              # This file
+```
+
+## Workflow Process
+
+### Phase 1: Legacy Analysis (Steps 1-3)
+
+**Item Identification and Loading**
+
+- Accepts file path or directory from user
+- Loads complete file/folder structure for analysis
+- Automatically detects item type based on content patterns:
+  - **Agents**: Contains `<agent>` or `<prompt>` XML tags
+  - **Workflows**: Contains workflow YAML or instruction patterns
+  - **Modules**: Contains multiple organized agents/workflows
+  - **Tasks**: Contains `<task>` XML tags
+  - **Templates**: Contains YAML-based document generators
+
+**Legacy Structure Analysis**
+
+- Parses v4 structure and extracts key components
+- Maps v4 agent metadata (name, id, title, icon, persona)
+- Analyzes v4 template sections and elicitation patterns
+- Identifies task workflows and decision trees
+- Catalogs dependencies and file references
+
+**Target Module Selection**
+
+- Prompts for target module (bmm, bmb, cis, custom)
+- Determines proper installation paths using v6 conventions
+- Shows target location for user confirmation
+- Ensures all paths use `{project-root}/bmad/` format
+
+### Phase 2: Conversion Strategy (Step 4)
+
+**Strategy Selection Based on Item Type**
+
+- **Simple Agents**: Direct XML conversion with metadata mapping
+- **Complex Agents**: Workflow-assisted creation using create-agent
+- **Templates**: Template-to-workflow conversion with proper structure
+- **Tasks**: Task-to-workflow conversion with step mapping
+- **Modules**: Full module creation using create-module workflow
+
+**Workflow Type Determination**
+
+- Analyzes legacy items to determine v6 workflow type:
+  - **Document Workflow**: Generates documents with templates
+  - **Action Workflow**: Performs actions without output documents
+  - **Interactive Workflow**: Guides user interaction sessions
+  - **Meta-Workflow**: Coordinates other workflows
+
+### Phase 3: Conversion Execution (Steps 5a-5e)
+
+**Direct Agent Conversion (5a)**
+
+- Transforms v4 YAML agent format to v6 XML structure
+- Maps persona blocks (role, style, identity, principles)
+- Converts commands list to v6 `<cmds>` format
+- Updates task references to workflow invocations
+- Normalizes all paths to v6 conventions
+
+**Workflow-Assisted Creation (5b-5e)**
+
+- Extracts key information from legacy items
+- Invokes appropriate sub-workflows:
+  - `create-agent` for complex agent creation
+  - `create-workflow` for template/task conversion
+  - `create-module` for full module migration
+- Ensures proper v6 structure and conventions
+
+**Template-to-Workflow Conversion (5c)**
+
+- Converts YAML template sections to workflow steps
+- Maps `elicit: true` flags to `<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>` tags
+- Transforms conditional sections to flow control
+- Creates proper template.md from content structure
+- Integrates v4 create-doc.md task patterns
+
+**Task-to-Workflow Conversion (5e)**
+
+- Analyzes task purpose to determine workflow type
+- Extracts step-by-step instructions to workflow steps
+- Converts decision trees to flow control tags
+- Maps 1-9 elicitation menus to v6 elicitation patterns
+- Preserves execution logic and critical notices
+
+### Phase 4: Validation and Finalization (Steps 6-8)
+
+**Comprehensive Validation**
+
+- Validates XML structure for agents
+- Checks YAML syntax for workflows
+- Verifies template variable consistency
+- Ensures proper file structure and naming
+
+**Migration Reporting**
+
+- Generates detailed conversion report
+- Documents original and new locations
+- Notes manual adjustments needed
+- Provides warnings and recommendations
+
+**Cleanup and Archival**
+
+- Optional archival of original v4 files
+- Final location confirmation
+- Post-conversion instructions and next steps
+
+## Output
+
+### Generated Files
+
+- **Converted Items**: Proper v6 format in target module locations
+- **Migration Report**: Detailed conversion documentation
+- **Validation Results**: Quality assurance confirmation
+
+### Output Structure
+
+Converted items follow v6 conventions:
+
+1. **Agents** - XML format with proper persona and command structure
+2. **Workflows** - Complete workflow folders with yaml, instructions, and templates
+3. **Modules** - Full module structure with installation infrastructure
+4. **Documentation** - Updated paths, references, and metadata
+
+## Requirements
+
+- **Legacy v4 Items** - Source files or directories to convert
+- **Target Module Access** - Write permissions to target module directories
+- **Sub-Workflow Availability** - create-agent, create-workflow, create-module workflows accessible
+- **Conversion Mappings** (optional) - v4-to-v6 pattern mappings for complex conversions
+
+## Best Practices
+
+### Before Starting
+
+1. **Backup Legacy Items** - Create copies of original v4 files before conversion
+2. **Review Target Module** - Understand target module structure and conventions
+3. **Plan Module Organization** - Decide where converted items should logically fit
+
+### During Execution
+
+1. **Validate Item Type Detection** - Confirm automatic detection or correct manually
+2. **Choose Appropriate Strategy** - Use workflow-assisted creation for complex items
+3. **Review Path Mappings** - Ensure all references use proper v6 path conventions
+4. **Test Incrementally** - Convert simple items first to validate process
+
+### After Completion
+
+1. **Validate Converted Items** - Test agents and workflows for proper functionality
+2. **Review Migration Report** - Address any manual adjustments noted
+3. **Update Documentation** - Ensure README and documentation reflect changes
+4. **Archive Originals** - Store v4 files safely for reference if needed
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Item type detection fails or incorrect
+
+- **Solution**: Manually specify item type when prompted
+- **Check**: Verify file structure matches expected v4 patterns
+
+**Issue**: Path conversion errors
+
+- **Solution**: Ensure all references use `{project-root}/bmad/` format
+- **Check**: Review conversion mappings for proper path patterns
+
+**Issue**: Sub-workflow invocation fails
+
+- **Solution**: Verify build workflows are available and accessible
+- **Check**: Ensure target module exists and has proper permissions
+
+**Issue**: XML or YAML syntax errors in output
+
+- **Solution**: Review conversion mappings and adjust patterns
+- **Check**: Validate converted files with appropriate parsers
+
+## Customization
+
+To customize this workflow:
+
+1. **Update Conversion Mappings** - Modify v4-to-v6 pattern mappings in data/
+2. **Extend Detection Logic** - Add new item type detection patterns
+3. **Add Conversion Strategies** - Implement specialized conversion approaches
+4. **Enhance Validation** - Add additional quality checks in validation step
+
+## Version History
+
+- **v1.0.0** - Initial release
+  - Multi-format v4 item detection and conversion
+  - Integration with create-agent, create-workflow, create-module
+  - Comprehensive path normalization
+  - Migration reporting and validation
+
+## Support
+
+For issues or questions:
+
+- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
+- Check conversion mappings at `/bmad/bmb/data/v4-to-v6-mappings.yaml`
+- Validate output using `checklist.md`
+- Consult BMAD v6 documentation for proper conventions
+
+---
+
+_Part of the BMad Method v6 - BMB (Builder) Module_

package/src/modules/bmb/workflows/convert-legacy/checklist.md

@@ -0,0 +1,205 @@
+# Convert Legacy - Validation Checklist
+
+## Pre-Conversion Validation
+
+### Source Analysis
+
+- [ ] Original v4 file(s) fully loaded and parsed
+- [ ] Item type correctly identified (agent/template/task/module)
+- [ ] All dependencies documented and accounted for
+- [ ] No critical content overlooked in source files
+
+## Conversion Completeness
+
+### For Agent Conversions
+
+#### Content Preservation
+
+- [ ] Agent name, id, title, and icon transferred
+- [ ] All persona elements mapped to v6 structure
+- [ ] All commands converted to v6 menu array (YAML)
+- [ ] Dependencies properly referenced or converted
+- [ ] Activation instructions adapted to v6 patterns
+
+#### v6 Compliance (YAML Format)
+
+- [ ] Valid YAML structure with proper indentation
+- [ ] agent.metadata has all required fields (id, name, title, icon, module)
+- [ ] agent.persona has all sections (role, identity, communication_style, principles)
+- [ ] agent.menu uses proper handlers (workflow, action, exec, tmpl, data)
+- [ ] agent.critical_actions array present when needed
+- [ ] agent.prompts defined for any action: "#id" references
+- [ ] File extension is .agent.yaml (will be compiled to .md later)
+
+#### Best Practices
+
+- [ ] Commands use appropriate workflow references instead of direct task calls
+- [ ] File paths use {project-root} variables
+- [ ] Config values use {config_source}: pattern
+- [ ] Agent follows naming conventions (kebab-case for files)
+- [ ] ALL paths reference {project-root}/bmad/{{module}}/ locations, NOT src/
+- [ ] exec, data, run-workflow commands point to final BMAD installation paths
+
+### For Template/Workflow Conversions
+
+#### Content Preservation
+
+- [ ] Template metadata (name, description, output) transferred
+- [ ] All sections converted to workflow steps
+- [ ] Section hierarchy maintained in instructions
+- [ ] Variables ({{var}}) preserved in template.md
+- [ ] Elicitation points (elicit: true) converted to <invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
+- [ ] Conditional sections preserved with if="" attributes
+- [ ] Repeatable sections converted to repeat="" attributes
+
+#### v6 Compliance
+
+- [ ] workflow.yaml follows structure from workflow-creation-guide.md
+- [ ] instructions.md has critical headers referencing workflow engine
+- [ ] Steps numbered sequentially with clear goals
+- [ ] Template variables match between instructions and template.md
+- [ ] Proper use of XML tags (<action>, <check>, <ask>, <template-output>)
+- [ ] File structure follows v6 pattern (folder with yaml/md files)
+
+#### Best Practices
+
+- [ ] Steps are focused with single goals
+- [ ] Instructions are specific ("Write 1-2 paragraphs" not "Write about")
+- [ ] Examples provided where helpful
+- [ ] Limits set where appropriate ("3-5 items maximum")
+- [ ] Save checkpoints with <template-output> at logical points
+- [ ] Variables use descriptive snake_case names
+
+### For Task Conversions
+
+#### Content Preservation
+
+- [ ] Task logic fully captured in workflow instructions
+- [ ] Execution flow maintained
+- [ ] User interaction points preserved
+- [ ] Decision trees converted to workflow logic
+- [ ] All processing steps accounted for
+- [ ] Document generation patterns identified and preserved
+
+#### Type Determination
+
+- [ ] Workflow type correctly identified (document/action/interactive/meta)
+- [ ] If generates documents, template.md created
+- [ ] If performs actions only, marked as action workflow
+- [ ] Output patterns properly analyzed
+
+#### v6 Compliance
+
+- [ ] Converted to proper workflow format (not standalone task)
+- [ ] Follows workflow execution engine patterns
+- [ ] Interactive elements use proper v6 tags
+- [ ] Flow control uses v6 patterns (goto, check, loop)
+- [ ] 1-9 elicitation menus converted to v6 elicitation
+- [ ] Critical notices preserved in workflow.yaml
+- [ ] YOLO mode converted to appropriate v6 patterns
+
+### Module-Level Validation
+
+#### Structure
+
+- [ ] Module follows v6 directory structure
+- [ ] All components in correct locations:
+  - Agents in /agents/
+  - Workflows in /workflows/
+  - Data files in appropriate locations
+- [ ] Config files properly formatted
+
+#### Integration
+
+- [ ] Cross-references between components work
+- [ ] Workflow invocations use correct paths
+- [ ] Data file references are valid
+- [ ] No broken dependencies
+
+## Technical Validation
+
+### Syntax and Format
+
+- [ ] YAML files have valid syntax (no parsing errors)
+- [ ] XML structures properly formed and closed
+- [ ] Markdown files render correctly
+- [ ] File encoding is UTF-8
+- [ ] Line endings consistent (LF)
+
+### Path Resolution
+
+- [ ] All file paths resolve correctly
+- [ ] Variable substitutions work ({project-root}, {installed_path}, etc.)
+- [ ] Config references load properly
+- [ ] No hardcoded absolute paths (unless intentional)
+
+## Functional Validation
+
+### Execution Testing
+
+- [ ] Converted item can be loaded without errors
+- [ ] Agents activate properly when invoked
+- [ ] Workflows execute through completion
+- [ ] User interaction points function correctly
+- [ ] Output generation works as expected
+
+### Behavioral Validation
+
+- [ ] Converted item behaves similarly to v4 version
+- [ ] Core functionality preserved
+- [ ] User experience maintains or improves
+- [ ] No functionality regression
+
+## Documentation and Cleanup
+
+### Documentation
+
+- [ ] Conversion report generated with all changes
+- [ ] Any manual adjustments documented
+- [ ] Known limitations or differences noted
+- [ ] Migration instructions provided if needed
+
+### Post-Conversion
+
+- [ ] Original v4 files archived (if requested)
+- [ ] File permissions set correctly
+- [ ] Git tracking updated if applicable
+- [ ] User informed of new locations
+
+## Final Verification
+
+### Quality Assurance
+
+- [ ] Converted item follows ALL v6 best practices
+- [ ] Code/config is clean and maintainable
+- [ ] No TODO or FIXME items remain
+- [ ] Ready for production use
+
+### User Acceptance
+
+- [ ] User reviewed conversion output
+- [ ] User tested basic functionality
+- [ ] User approved final result
+- [ ] Any user feedback incorporated
+
+## Notes Section
+
+### Conversion Issues Found:
+
+_List any issues encountered during validation_
+
+### Manual Interventions Required:
+
+_Document any manual fixes needed_
+
+### Recommendations:
+
+_Suggestions for further improvements or considerations_
+
+---
+
+**Validation Result:** [ ] PASSED / [ ] FAILED
+
+**Validator:** {{user_name}}
+**Date:** {{date}}
+**Items Converted:** {{conversion_summary}}