# Convert Legacy - v4 to v5 Conversion 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/convert-legacy/workflow.yaml</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 v5 equivalents:

- v4 Task + Template → v5 Workflow (folder with workflow.yaml, instructions.md, template.md)
- v4 Agent YAML → v5 Agent YAML format
- v4 Commands → v5 <menu> with proper handlers
- v4 Dependencies → v5 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>
<check>If custom module:</check>
  <ask>Enter custom module code (kebab-case):</ask>
<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>
<check>If simple agent (basic persona + commands):</check>
<action>Use direct conversion to v5 agent YAML format</action>
<goto step="5a">Direct Agent Conversion</goto>
<check>If complex agent with embedded workflows:</check>
<action>Plan to invoke create-agent workflow</action>
<goto step="5b">Workflow-Assisted Agent Creation</goto>

<check>If template or task conversion to workflow:</check>
<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>

<check>If template conversion:</check>
<goto step="5c">Template-to-Workflow Conversion</goto>
<check>If task conversion:</check>
<goto step="5e">Task-to-Workflow Conversion</goto>

<check>If full module conversion:</check>
<action>Plan to invoke create-module workflow</action>
<goto step="5d">Module Creation</goto>
</step>

<step n="5a" goal="Direct Agent Conversion" optional="true">
<action>Transform v4 YAML agent to v5 YAML format:</action>

1. Convert agent metadata structure:
   - v4 `agent.name` → v5 `agent.metadata.name`
   - v4 `agent.id` → v5 `agent.metadata.id`
   - v4 `agent.title` → v5 `agent.metadata.title`
   - v4 `agent.icon` → v5 `agent.metadata.icon`
   - Add v5 `agent.metadata.module` field

2. Transform persona structure:
   - v4 `persona.role` → v5 `agent.persona.role` (keep as YAML string)
   - v4 `persona.style` → v5 `agent.persona.communication_style`
   - v4 `persona.identity` → v5 `agent.persona.identity`
   - v4 `persona.core_principles` → v5 `agent.persona.principles` (as array)

3. Convert commands to menu:
   - v4 `commands:` list → v5 `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 v5-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 v5 workflows
   - Preserve checklist and data file references
   - CRITICAL: All paths must use {project-root}/bmad/{{module}}/ NOT src/

<action>Generate the converted v5 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 v5 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` → `<elicit-required/>` 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 v5 elicitation
   - Agent permissions → note in instructions
   - Processing flow → integrate into workflow steps

<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>

<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 v5 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 v5 tags

3. Based on confirmed workflow type:
   <check>If Document workflow:</check>
   - Create template.md from output patterns
   - Map generation steps to instructions
   - Add <template-output> tags for sections

   <check>If Action workflow:</check>
   - Set template: false in workflow.yaml
   - Focus on action sequences in instructions
   - Preserve execution logic

4. Handle special v4 patterns:
   - 1-9 elicitation menus → v5 <elicit-required/>
   - Agent permissions → note in instructions
   - YOLO mode → autonomous flag or optional steps
   - Critical notices → workflow.yaml comments

<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>

<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 v5 conventions
- [ ] Template variables match
- [ ] File structure correct

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:</check>
<action>Address specific issues</action>
<goto step="6">Re-validate</goto>
</step>

<step n="7" goal="Migration Report">
<action>Generate conversion report showing:</action>
- Original v4 location
- New v5 location
- Items converted
- Any manual adjustments needed
- Warnings or notes

<action>Save report to: {output_folder}/conversion-report-{{date}}.md</action>
</step>

<step n="8" goal="Cleanup and Finalize">
<ask>Archive original v4 files? (y/n)</ask>
<check>If yes:</check>
  <action>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>
<check>If yes:</check>
<goto step="1">Start new conversion</goto>
</step>

</workflow>