bmad初始化

2025-11-01 19:22:39 +08:00
parent 5b21dc0bd5
commit 426ae41f54
447 changed files with 80633 additions and 0 deletions
--- a/bmad/bmb/workflows/convert-legacy/README.md
+++ b/bmad/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_
--- a/bmad/bmb/workflows/convert-legacy/checklist.md
+++ b/bmad/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}}
--- a/bmad/bmb/workflows/convert-legacy/instructions.md
+++ b/bmad/bmb/workflows/convert-legacy/instructions.md
@@ -0,0 +1,377 @@
+# Convert Legacy - v4 to v6 Conversion Instructions
+
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<parameter name="You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/convert-legacy/workflow.yaml</critical>
+<critical>Communicate in {communication_language} throughout the conversion process</critical>
+
+<workflow>
+
+<step n="1" goal="Identify and Load Legacy Item">
+<action>Ask user for the path to the v4 item to convert (agent, workflow, or module)</action>
+<action>Load the complete file/folder structure</action>
+<action>Detect item type based on structure and content patterns:</action>
+  - Agent: Contains agent or prompt XML tags, single file
+  - Workflow: Contains workflow YAML or instruction patterns, usually folder
+  - Module: Contains multiple agents/workflows in organized structure
+  - Task: Contains task XML tags
+<ask>Confirm detected type or allow user to correct: "Detected as [type]. Is this correct? (y/n)"</ask>
+</step>
+
+<step n="2" goal="Analyze Legacy Structure">
+<action>Parse the v4 structure and extract key components:</action>
+
+For v4 Agents (YAML-based in markdown):
+
+- Agent metadata (name, id, title, icon, whenToUse)
+- Persona block (role, style, identity, focus, core_principles)
+- Commands list with task/template references
+- Dependencies (tasks, templates, checklists, data files)
+- Activation instructions and workflow rules
+- IDE file resolution patterns
+
+For v4 Templates (YAML-based document generators):
+
+- Template metadata (id, name, version, output)
+- Workflow mode and elicitation settings
+- Sections hierarchy with:
+  - Instructions for content generation
+  - Elicit flags for user interaction
+  - Templates with {{variables}}
+  - Conditional sections
+  - Repeatable sections
+
+For v4 Tasks (Markdown with execution instructions):
+
+- Critical execution notices
+- Step-by-step workflows
+- Elicitation requirements (1-9 menu format)
+- Processing flows and decision trees
+- Agent permission rules
+
+For Modules:
+
+- Module metadata
+- Component list (agents, workflows, tasks)
+- Dependencies
+- Installation requirements
+
+<action>Create a conversion map of what needs to be transformed</action>
+<action>Map v4 patterns to v6 equivalents:
+
+- v4 Task + Template → v6 Workflow (folder with workflow.yaml, instructions.md, template.md)
+- v4 Agent YAML → v6 Agent YAML format
+- v4 Commands → v6 <menu> with proper handlers
+- v4 Dependencies → v6 workflow references or data files
+  </action>
+  </step>
+
+<step n="3" goal="Determine Target Module and Location">
+<ask>Which module should this belong to? (eg. bmm, bmb, cis, bmm-legacy, or custom)</ask>
+<action if="custom module"><ask>Enter custom module code (kebab-case):</ask></action>
+<action>Determine installation path based on type and module</action>
+<critical>IMPORTANT: All paths must use final BMAD installation locations, not src paths!</critical>
+<action>Show user the target location: {project-root}/bmad/{{target_module}}/{{item_type}}/{{item_name}}</action>
+<action>Note: Files will be created in bmad/ but all internal paths will reference {project-root}/bmad/ locations</action>
+<ask>Proceed with this location? (y/n)</ask>
+</step>
+
+<step n="4" goal="Choose Conversion Strategy">
+<action>Based on item type and complexity, choose approach:</action>
+
+<check if="agent conversion">
+  <check if="simple agent (basic persona + commands)">
+    <action>Use direct conversion to v6 agent YAML format</action>
+    <goto step="5a">Direct Agent Conversion</goto>
+  </check>
+  <check if="complex agent with embedded workflows">
+    <action>Plan to invoke create-agent workflow</action>
+    <goto step="5b">Workflow-Assisted Agent Creation</goto>
+  </check>
+</check>
+
+<check if="template or task conversion to workflow">
+  <action>Analyze the v4 item to determine workflow type:</action>
+
+- Does it generate a specific document type? → Document workflow
+- Does it produce structured output files? → Document workflow
+- Does it perform actions without output? → Action workflow
+- Does it coordinate other tasks? → Meta-workflow
+- Does it guide user interaction? → Interactive workflow
+
+<ask>Based on analysis, this appears to be a {{detected_workflow_type}} workflow. Confirm or correct:
+
+1. Document workflow (generates documents with template)
+2. Action workflow (performs actions, no template)
+3. Interactive workflow (guided session)
+4. Meta-workflow (coordinates other workflows)
+   Select 1-4:</ask>
+
+<action if="template conversion"><goto step="5c">Template-to-Workflow Conversion</goto></action>
+<action if="task conversion"><goto step="5e">Task-to-Workflow Conversion</goto></action>
+</check>
+
+<check if="full module conversion">
+  <action>Plan to invoke create-module workflow</action>
+  <goto step="5d">Module Creation</goto>
+</check>
+</step>
+
+<step n="5a" goal="Direct Agent Conversion" optional="true">
+<action>Transform v4 YAML agent to v6 YAML format:</action>
+
+1. Convert agent metadata structure:
+   - v4 `agent.name` → v6 `agent.metadata.name`
+   - v4 `agent.id` → v6 `agent.metadata.id`
+   - v4 `agent.title` → v6 `agent.metadata.title`
+   - v4 `agent.icon` → v6 `agent.metadata.icon`
+   - Add v6 `agent.metadata.module` field
+
+2. Transform persona structure:
+   - v4 `persona.role` → v6 `agent.persona.role` (keep as YAML string)
+   - v4 `persona.style` → v6 `agent.persona.communication_style`
+   - v4 `persona.identity` → v6 `agent.persona.identity`
+   - v4 `persona.core_principles` → v6 `agent.persona.principles` (as array)
+
+3. Convert commands to menu:
+   - v4 `commands:` list → v6 `agent.menu:` array
+   - Each command becomes menu item with:
+     - `trigger:` (without \* prefix - added at build)
+     - `description:`
+     - Handler attributes (`workflow:`, `exec:`, `action:`, etc.)
+   - Map task references to workflow paths
+   - Map template references to workflow invocations
+
+4. Add v6-specific sections (in YAML):
+   - `agent.prompts:` array for inline prompts (if using action: "#id")
+   - `agent.critical_actions:` array for startup requirements
+   - `agent.activation_rules:` for universal agent rules
+
+5. Handle dependencies and paths:
+   - Convert task dependencies to workflow references
+   - Map template dependencies to v6 workflows
+   - Preserve checklist and data file references
+   - CRITICAL: All paths must use {project-root}/bmad/{{module}}/ NOT src/
+
+<action>Generate the converted v6 agent YAML file (.agent.yaml)</action>
+<action>Example path conversions:
+
+- exec="{project-root}/bmad/{{target_module}}/tasks/task-name.md"
+- run-workflow="{project-root}/bmad/{{target_module}}/workflows/workflow-name/workflow.yaml"
+- data="{project-root}/bmad/{{target_module}}/data/data-file.yaml"
+  </action>
+  <action>Save to: bmad/{{target_module}}/agents/{{agent_name}}.agent.yaml (physical location)</action>
+  <action>Note: The build process will later compile this to .md with XML format</action>
+  <goto step="6">Continue to Validation</goto>
+  </step>
+
+<step n="5b" goal="Workflow-Assisted Agent Creation" optional="true">
+<action>Extract key information from v4 agent:</action>
+- Name and purpose
+- Commands and functionality
+- Persona traits
+- Any special behaviors
+
+<invoke-workflow>
+  workflow: {project-root}/bmad/bmb/workflows/create-agent/workflow.yaml
+  inputs:
+    - agent_name: {{extracted_name}}
+    - agent_purpose: {{extracted_purpose}}
+    - commands: {{extracted_commands}}
+    - persona: {{extracted_persona}}
+</invoke-workflow>
+
+<goto step="6">Continue to Validation</goto>
+</step>
+
+<step n="5c" goal="Template-to-Workflow Conversion" optional="true">
+<action>Convert v4 Template (YAML) to v6 Workflow:</action>
+
+1. Extract template metadata:
+   - Template id, name, version → workflow.yaml name/description
+   - Output settings → default_output_file
+   - Workflow mode (interactive/yolo) → workflow settings
+
+2. Convert template sections to instructions.md:
+   - Each YAML section → workflow step
+   - `elicit: true` → `<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>` tag
+   - Conditional sections → `if="condition"` attribute
+   - Repeatable sections → `repeat="for-each"` attribute
+   - Section instructions → step content
+
+3. Extract template structure to template.md:
+   - Section content fields → template structure
+   - {{variables}} → preserve as-is
+   - Nested sections → hierarchical markdown
+
+4. Handle v4 create-doc.md task integration:
+   - Elicitation methods (1-9 menu) → convert to v6 elicitation
+   - Agent permissions → note in instructions
+   - Processing flow → integrate into workflow steps
+
+<critical>When invoking create-workflow, the standard config block will be automatically added:</critical>
+
+```yaml
+# Critical variables from config
+config_source: '{project-root}/bmad/{{target_module}}/config.yaml'
+output_folder: '{config_source}:output_folder'
+user_name: '{config_source}:user_name'
+communication_language: '{config_source}:communication_language'
+date: system-generated
+```
+
+<invoke-workflow>
+  workflow: {project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml
+  inputs:
+    - workflow_name: {{template_name}}
+    - workflow_type: document
+    - template_structure: {{extracted_template}}
+    - instructions: {{converted_sections}}
+</invoke-workflow>
+
+<action>Verify the created workflow.yaml includes standard config block</action>
+<action>Update converted instructions to use config variables where appropriate</action>
+
+<goto step="6">Continue to Validation</goto>
+</step>
+
+<step n="5d" goal="Module Creation" optional="true">
+<action>Analyze module structure and components</action>
+<action>Create module blueprint with all components</action>
+
+<invoke-workflow>
+  workflow: {project-root}/bmad/bmb/workflows/create-module/workflow.yaml
+  inputs:
+    - module_name: {{module_name}}
+    - components: {{component_list}}
+</invoke-workflow>
+
+<goto step="6">Continue to Validation</goto>
+</step>
+
+<step n="5e" goal="Task-to-Workflow Conversion" optional="true">
+<action>Convert v4 Task (Markdown) to v6 Workflow:</action>
+
+1. Analyze task purpose and output:
+   - Does it generate documents? → Create template.md
+   - Does it process data? → Action workflow
+   - Does it guide user interaction? → Interactive workflow
+   - Check for file outputs, templates, or document generation
+
+2. Extract task components:
+   - Execution notices and critical rules → workflow.yaml metadata
+   - Step-by-step instructions → instructions.md steps
+   - Decision trees and branching → flow control tags
+   - User interaction patterns → appropriate v6 tags
+
+3. Based on confirmed workflow type:
+   <check if="Document workflow">
+   - Create template.md from output patterns
+   - Map generation steps to instructions
+   - Add template-output tags for sections
+     </check>
+
+   <check if="Action workflow">
+     - Set template: false in workflow.yaml
+     - Focus on action sequences in instructions
+     - Preserve execution logic
+   </check>
+
+4. Handle special v4 patterns:
+   - 1-9 elicitation menus → v6 <invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
+   - Agent permissions → note in instructions
+   - YOLO mode → autonomous flag or optional steps
+   - Critical notices → workflow.yaml comments
+
+<critical>When invoking create-workflow, the standard config block will be automatically added:</critical>
+
+```yaml
+# Critical variables from config
+config_source: '{project-root}/bmad/{{target_module}}/config.yaml'
+output_folder: '{config_source}:output_folder'
+user_name: '{config_source}:user_name'
+communication_language: '{config_source}:communication_language'
+date: system-generated
+```
+
+<invoke-workflow>
+  workflow: {project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml
+  inputs:
+    - workflow_name: {{task_name}}
+    - workflow_type: {{confirmed_workflow_type}}
+    - instructions: {{extracted_task_logic}}
+    - template: {{generated_template_if_document}}
+</invoke-workflow>
+
+<action>Verify the created workflow.yaml includes standard config block</action>
+<action>Update converted instructions to use config variables where appropriate</action>
+
+<goto step="6">Continue to Validation</goto>
+</step>
+
+<step n="6" goal="Validate Conversion">
+<action>Run validation checks on converted item:</action>
+
+For Agents:
+
+- [ ] Valid YAML structure (.agent.yaml)
+- [ ] All required sections present (metadata, persona, menu)
+- [ ] Menu items properly formatted (trigger, description, handlers)
+- [ ] Paths use {project-root} variables
+
+For Workflows:
+
+- [ ] Valid YAML syntax
+- [ ] Instructions follow v6 conventions
+- [ ] Template variables match
+- [ ] File structure correct
+
+**Standard Config Validation (Workflows):**
+
+- [ ] workflow.yaml contains standard config block:
+  - config_source defined
+  - output_folder, user_name, communication_language pulled from config
+  - date set to system-generated
+- [ ] Converted instructions use config variables where appropriate
+- [ ] Template includes config variables in metadata (if document workflow)
+- [ ] No hardcoded paths that should use {output_folder}
+- [ ] No generic greetings that should use {user_name}
+
+For Modules:
+
+- [ ] All components converted
+- [ ] Proper folder structure
+- [ ] Config files valid
+- [ ] Installation ready
+
+<action>Show validation results to user</action>
+<ask>Any issues to fix before finalizing? (y/n)</ask>
+<check if="yes">
+<action>Address specific issues</action>
+<goto step="6">Re-validate</goto>
+</check>
+</step>
+
+<step n="7" goal="Migration Report">
+<action>Generate conversion report showing:</action>
+- Original v4 location
+- New v6 location
+- Items converted
+- Any manual adjustments needed
+- Warnings or notes
+
+<action>Save report to: {output_folder}/conversion-report-{{date}}.md</action>
+<action>Inform {user_name} in {communication_language} that the conversion report has been generated</action>
+</step>
+
+<step n="8" goal="Cleanup and Finalize">
+<ask>Archive original v4 files? (y/n)</ask>
+<action if="yes">Move v4 files to: {project-root}/archive/v4-legacy/{{date}}/</action>
+
+<action>Show user the final converted items and their locations</action>
+<action>Provide any post-conversion instructions or recommendations</action>
+
+<ask>Would you like to convert another legacy item? (y/n)</ask>
+<action if="yes"><goto step="1">Start new conversion</goto></action>
+</step>
+
+</workflow>
--- a/bmad/bmb/workflows/convert-legacy/workflow.yaml
+++ b/bmad/bmb/workflows/convert-legacy/workflow.yaml
@@ -0,0 +1,32 @@
+# Convert Legacy - BMAD v4 to v6 Converter Configuration
+name: "convert-legacy"
+description: "Converts legacy BMAD v4 or similar items (agents, workflows, modules) to BMad Core compliant format with proper structure and conventions"
+author: "BMad"
+
+# Critical variables load from config_source
+config_source: "{project-root}/bmad/bmb/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Optional docs that can be provided as input
+recommended_inputs:
+  - legacy_file: "Path to v4 agent, workflow, or module to convert"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmb/workflows/convert-legacy"
+template: false # This is an action/meta workflow - no template needed
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Output configuration - Creates converted items in appropriate module locations
+default_output_folder: "{project-root}/bmad/{{target_module}}/{{item_type}}/{{item_name}}"
+
+# Sub-workflows that may be invoked for conversion
+sub_workflows:
+  - create_agent: "{project-root}/bmad/bmb/workflows/create-agent/workflow.yaml"
+  - create_workflow: "{project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml"
+  - create_module: "{project-root}/bmad/bmb/workflows/create-module/workflow.yaml"
+
+standalone: true