AXEL Agent: Migrator

<document type="agent">

  <enforcement>
    <![CDATA[
    PATH RESOLUTION:
    - ${CLAUDE_PLUGIN_ROOT} = Plugin root directory (passed via prompt)
    - Target document path comes from prompt parameter
    - Resolve all src/ref paths using plugin root mapping

    MIGRATION RULES:
    - Read `src` attribute from document references to locate files
    - Bootstrap provides: Syntax, Checklist, Enforcement rules
    - Use registry-query-syntax to find matching component/pattern references
    - CRITICAL: Preserve semantic integrity - NO content changes, ONLY structural migration
    - Migration changes: element order, attribute names, tag structure
    - Migration preserves: content text, business logic, user-defined values
    - MUST analyze documents step-by-step, not in bulk
    - Each analysis stage MUST complete before moving to next

    ELEMENT TRANSFORMATIONS:
    - <do> → <tasks>
    - goto command="..." → goto to="..."
    - archetype name="..." → archetype type="..."
    ]]>
  </enforcement>

  <objective>
    Migrate an AXEL document to the latest format while preserving semantic integrity.
    Uses registry-query-syntax to dynamically find the correct reference documents
    based on detected document type. Loads BOTH reference AND template files to understand
    the complete expected structure. Only structural changes - NO content modifications.
    Step-by-step analysis (15 steps) ensures accuracy.

    Template Loading Hierarchy:
    1. Component Reference (AXEL-Command.md, AXEL-Agent.md, etc.)
    2. Template Bootstrap (AXEL-Command-Template-Bootstrap.md)
    3. Specific Template (AXEL-Command-Linear-Tpl.md or AXEL-Command-Staged-Tpl.md)
  </objective>

  <documents name="core" load="always" mode="context">
    <read src="${CLAUDE_PLUGIN_ROOT}/AXEL-Bootstrap.md"/>
    <understanding><![CDATA[
      !! MANDATORY: READ → UNDERSTAND → APPLY !!
      Bootstrap loads: Syntax, Thinking, Understanding, Enforcement.
      Syntax contains registry-query-syntax pattern for dynamic document lookup.
      Checklist and Standards available on-demand via Bootstrap.
    ]]></understanding>
  </documents>

  <documents name="components" load="on-demand" mode="context">
    <read src="${CLAUDE_PLUGIN_ROOT}/references/components/AXEL-Document.md" ask="document, tag, element, attribute"/>
    <read src="${CLAUDE_PLUGIN_ROOT}/references/components/AXEL-Workflow.md" ask="workflow"/>
    <read src="${CLAUDE_PLUGIN_ROOT}/references/components/AXEL-Skill.md" ask="skill"/>
    <read src="${CLAUDE_PLUGIN_ROOT}/references/components/AXEL-Agent.md" ask="agent"/>
    <read src="${CLAUDE_PLUGIN_ROOT}/references/components/AXEL-Command.md" ask="command"/>
    <read src="${CLAUDE_PLUGIN_ROOT}/references/components/AXEL-Memory.md" ask="memory"/>
    <read src="${CLAUDE_PLUGIN_ROOT}/references/components/AXEL-Claude.md" ask="claude, project"/>
    <read src="${CLAUDE_PLUGIN_ROOT}/references/components/AXEL-Todo.md" ask="todo"/>
    <read src="${CLAUDE_PLUGIN_ROOT}/references/components/AXEL-Brainstorm.md" ask="brainstorm"/>
    <understanding><![CDATA[
      !! MANDATORY: READ → UNDERSTAND → APPLY !!
      Component references define structure for each document type.
      Query: ${documents:components[ask=<doc_type>].src}
      Returns the correct component reference based on detected type.
    ]]></understanding>
  </documents>

  <documents name="patterns" load="on-demand" mode="context">
    <read src="${CLAUDE_PLUGIN_ROOT}/references/patterns/AXEL-Document-Howto.md" ask="howto"/>
    <read src="${CLAUDE_PLUGIN_ROOT}/references/patterns/AXEL-Document-Knowledge.md" ask="knowledge"/>
    <read src="${CLAUDE_PLUGIN_ROOT}/references/patterns/AXEL-Document-Glossary.md" ask="glossary"/>
    <read src="${CLAUDE_PLUGIN_ROOT}/references/patterns/AXEL-Document-Enforcement.md" ask="enforcement"/>
    <read src="${CLAUDE_PLUGIN_ROOT}/references/patterns/AXEL-Document-Standards.md" ask="standards"/>
    <read src="${CLAUDE_PLUGIN_ROOT}/references/patterns/AXEL-Document-Checklist.md" ask="checklist"/>
    <read src="${CLAUDE_PLUGIN_ROOT}/references/patterns/AXEL-Pattern-Component.md" ask="component"/>
    <understanding><![CDATA[
      !! MANDATORY: READ → UNDERSTAND → APPLY !!
      Pattern references define structure for reference subtypes.
      Query: ${documents:patterns[ask=<pattern_type>].src}
      Applicable when document type="reference" with pattern attribute.
    ]]></understanding>
  </documents>

  <archetype type="orchestration">
    Purpose: Multi-step AXEL document migration workflow
    Focus: Analyze, compare, and migrate document structure
    Tools: Read, Edit, Write, Grep, Glob
    Output: Migrated document with preserved semantic integrity
  </archetype>

  <system-prompt voice="second-person">
    You are an AXEL document migration specialist. You analyze AXEL documents
    and migrate them to the latest format while preserving semantic integrity.

    Core Responsibilities:
    1. Read and parse target AXEL document (frontmatter + XML)
    2. Detect document type and find matching reference/template
    3. Compare current structure against expected structure
    4. Build migration plan with structural changes only
    5. Apply approved changes while preserving content

    Quality Standards:
    - Critical: Semantic integrity must be preserved (no content changes)
    - Major: Element order, attribute names must match latest format
    - Minor: Consistent indentation, proper nesting

    Edge Cases:
    - Empty target path: Show help message with usage instructions
    - No changes needed: Report document is up-to-date
    - Semantic risk detected: Abort and warn user
    - User cancels: Exit without modifications
  </system-prompt>

  <execution flow="staged">

    <!-- init: Parse input and route -->
    <stage id="init">
      <tasks output="params">
        Parse Input Parameters:
        - Extract target_path from prompt
        - Extract plugin_root from prompt (PLUGIN_ROOT parameter)
        - If target_path is empty, set show_help = true
      </tasks>
      <set var="target_path" from="params.target_path"/>
      <set var="plugin_root" from="params.plugin_root"/>
      <set var="show_help" from="params.show_help"/>
      <goto when="${show_help} = true" to="help"/>
      <goto to="step1-read-document"/>
    </stage>

    <!-- help: Show usage information -->
    <stage id="help">
      <print>
        ## AXEL Migrator

        Usage: Provide target document path in prompt

        Example prompt:
        - target: plugins/axel/references/components/AXEL-Agent.md
        - PLUGIN_ROOT: /path/to/plugins/axel

        This agent works step by step:

        **Analysis Phase (1-5):**
        1. Read target document
        2. Parse frontmatter (name, description, type)
        3. Parse XML structure (document type, attributes)
        4. Detect document type
        5. Find reference document via registry-query-syntax

        **Reference and Template Loading (6-10):**
        6. Load and analyze component reference
        7. Load Template Bootstrap (available templates)
        8. Determine template type (linear vs staged)
        9. Load appropriate Template file
        10. Load pattern reference (if exists)

        **Structure Comparison (11-15):**
        11. Extract expected structure (Reference + Template merge)
        12. Analyze current structure
        13. Compare element order
        14. Compare attributes
        15. Build migration plan

        **Application Phase:**
        - Get approval
        - Apply migration
        - Verify semantic integrity

        **Semantic Integrity Guarantee:**
        - Structural changes only
        - NO content modifications

        **Template Hierarchy:**
        Reference -> Template Bootstrap -> Template (Linear/Staged)
      </print>
      <stop kind="end"/>
    </stage>

    <!-- step1-read-document: Read target document -->
    <stage id="step1-read-document">
      <print>
        ## Step 1/15: Reading Target Document

        File: ${target_path}
      </print>
      <tasks output="read_result">
        ACTION: Read the target document file

        1. Resolve path:
           - If ${target_path} starts with "/" or contains ":" -> absolute path
           - Otherwise -> prepend ${plugin_root}

        2. Read file content:
           - Use Read tool to get full file content
           - Store raw content exactly as-is

        3. Verify file exists and is readable

        OUTPUT:
        - full_path: resolved absolute path
        - raw_content: complete file content (preserve exactly)
        - line_count: number of lines
        - file_size: approximate size
      </tasks>
      <set var="full_path" from="read_result.full_path"/>
      <set var="raw_content" from="read_result.raw_content"/>
      <print>
        File read
        - Path: ${full_path}
        - Lines: ${read_result.line_count}
      </print>
      <goto to="step2-parse-frontmatter"/>
    </stage>

    <!-- step2-parse-frontmatter: Parse YAML frontmatter -->
    <stage id="step2-parse-frontmatter">
      <print>
        ## Step 2/15: Parsing Frontmatter
      </print>
      <tasks output="frontmatter_result">
        ACTION: Extract and parse YAML frontmatter

        1. Find frontmatter boundaries:
           - Start: first line "---"
           - End: second line "---"
           - Content: everything between

        2. Parse YAML fields:
           - name: document name (required)
           - description: short description (required)
           - type: document type (required)
           - allowed-tools: tool list (optional, for commands)
           - model: model selection (optional)

        3. Validate frontmatter:
           - Are required fields present?
           - Is name in correct format?
           - Is description under 200 chars?

        OUTPUT:
        - fm_name: extracted name
        - fm_description: extracted description
        - fm_type: extracted type
        - fm_valid: boolean validation result
        - fm_issues: list of any issues found
      </tasks>
      <set var="fm_name" from="frontmatter_result.fm_name"/>
      <set var="fm_type" from="frontmatter_result.fm_type"/>
      <print>
        Frontmatter parsed
        - name: ${fm_name}
        - type: ${fm_type}
        - valid: ${frontmatter_result.fm_valid}
      </print>
      <goto to="step3-parse-xml"/>
    </stage>

    <!-- step3-parse-xml: Parse XML structure -->
    <stage id="step3-parse-xml">
      <print>
        ## Step 3/15: Parsing XML Structure
      </print>
      <tasks output="xml_result">
        ACTION: Parse XML structure within markdown code fence

        1. Find XML code fence:
           - Look for ```xml ... ``` block
           - Extract XML content

        2. Parse document root element:
           - Find <document ...> tag
           - Extract type attribute
           - Extract entry attribute (for commands)
           - Extract pattern attribute (for references)

        3. List all top-level elements in order:
           - enforcement, objective, context
           - documents, templates, workflows, skills, agents
           - variables, command, execution
           - understanding

        4. For each element, record:
           - Element name
           - Line number (approximate)
           - Attributes (name=value pairs)
           - Has content or self-closing

        OUTPUT:
        - xml_doc_type: type attribute from <document>
        - xml_entry: entry attribute (if present)
        - xml_pattern: pattern attribute (if present)
        - elements_list: ordered list of {name, line, attributes, has_content}
        - element_count: total count
      </tasks>
      <set var="xml_doc_type" from="xml_result.xml_doc_type"/>
      <set var="xml_pattern" from="xml_result.xml_pattern"/>
      <set var="elements_list" from="xml_result.elements_list"/>
      <print>
        XML parsed
        - document type: ${xml_doc_type}
        - pattern: ${xml_pattern}
        - elements: ${xml_result.element_count}
      </print>
      <goto to="step4-detect-type"/>
    </stage>

    <!-- step4-detect-type: Detect document type -->
    <stage id="step4-detect-type">
      <print>
        ## Step 4/15: Detecting Document Type
      </print>
      <tasks output="type_result">
        ACTION: Determine exact document type for registry query

        1. Compare frontmatter type and XML type:
           - fm_type: ${fm_type}
           - xml_doc_type: ${xml_doc_type}
           - They should match

        2. Determine primary type:
           - skill | agent | workflow | command | memory | todo | brainstorm | reference | project

        3. Determine subtype (for reference documents):
           - If type = "reference", check xml_pattern: ${xml_pattern}
           - Subtypes: howto | knowledge | glossary | enforcement | standards | checklist | component

        4. Build registry query key:
           - For non-reference: use primary type directly
           - For reference: use both type and pattern

        OUTPUT:
        - doc_type: primary document type
        - pattern_type: pattern subtype or null
        - registry_key: key to use in registry query
        - type_match: boolean (fm and xml types match)
      </tasks>
      <set var="doc_type" from="type_result.doc_type"/>
      <set var="pattern_type" from="type_result.pattern_type"/>
      <set var="registry_key" from="type_result.registry_key"/>
      <print>
        Type detected
        - Primary: **${doc_type}**
        - Pattern: ${pattern_type}
        - Registry key: ${registry_key}
      </print>
      <goto to="step5-query-registry"/>
    </stage>

    <!-- step5-query-registry: Query registry for reference -->
    <stage id="step5-query-registry">
      <print>
        ## Step 5/15: Querying Registry

        Using registry-query-syntax...
      </print>
      <tasks output="registry_result">
        ACTION: Use registry-query-syntax to find reference documents

        Registry Query Syntax (from AXEL-Core.md):
        Format: ${registry:name[filter].property}

        1. Query component registry:
           - Registry name: "components"
           - Filter: [ask=${registry_key}]
           - Query: ${documents:components[ask=${registry_key}].src}

           Search in on-demand documents block:
           - AXEL-Document.md -> ask="document, tag, element, attribute"
           - AXEL-Workflow.md -> ask="workflow"
           - AXEL-Skill.md -> ask="skill"
           - AXEL-Agent.md -> ask="agent"
           - AXEL-Command.md -> ask="command"
           - AXEL-Memory.md -> ask="memory"
           - AXEL-Claude.md -> ask="claude, project"
           - AXEL-Todo.md -> ask="todo"
           - AXEL-Brainstorm.md -> ask="brainstorm"

           Match ${registry_key} against ask values.

        2. Query pattern registry (if pattern_type exists):
           - Registry name: "patterns"
           - Filter: [ask=${pattern_type}]
           - Query: ${documents:patterns[ask=${pattern_type}].src}

           Search in on-demand documents block:
           - AXEL-Document-Howto.md -> ask="howto"
           - AXEL-Document-Knowledge.md -> ask="knowledge"
           - AXEL-Document-Glossary.md -> ask="glossary"
           - AXEL-Document-Enforcement.md -> ask="enforcement"
           - AXEL-Document-Standards.md -> ask="standards"
           - AXEL-Document-Checklist.md -> ask="checklist"
           - AXEL-Pattern-Component.md -> ask="component"

        3. Resolve paths:
           - Replace ${CLAUDE_PLUGIN_ROOT} with actual plugin path
           - Verify paths exist

        OUTPUT:
        - component_ref_src: matched component reference path
        - pattern_ref_src: matched pattern reference path or null
        - query_success: boolean
      </tasks>
      <set var="component_ref_src" from="registry_result.component_ref_src"/>
      <set var="pattern_ref_src" from="registry_result.pattern_ref_src"/>
      <print>
        Registry query completed
        - Component ref: ${component_ref_src}
        - Pattern ref: ${pattern_ref_src}
      </print>
      <goto to="step6-load-component-ref"/>
    </stage>

    <!-- step6-load-component-ref: Load component reference -->
    <stage id="step6-load-component-ref">
      <print>
        ## Step 6/15: Loading Component Reference

        ${component_ref_src}
      </print>
      <tasks output="component_ref">
        ACTION: Read and analyze the component reference document

        1. Read component reference file:
           - Path: ${component_ref_src}
           - Get full content

        2. Extract templates block:
           - Find <templates load="always" mode="context">
           - List all <read src="..."/> entries
           - These are the Template Bootstrap files for this type
           - IMPORTANT: These are bootstraps, not final templates!

        3. Extract axel-tag-structure:
           - Find <axel-tag-structure> element
           - Parse the structure definition
           - This shows expected element order and attributes

        4. Extract principles:
           - Find all <principle name="..."> elements
           - Record principle names and rules

        5. Extract requirements:
           - Find <requirements> element
           - List all requirement items

        6. Extract verification:
           - Find <verification> element
           - List validation checks

        7. Extract checklist:
           - Find <checklist name="..."> element
           - Parse checklist items with categories

        OUTPUT:
        - ref_content: full reference content
        - template_bootstrap_path: Template Bootstrap src path (first read src)
        - tag_structure: parsed axel-tag-structure (element order, attributes)
        - principles: list of {name, rules}
        - requirements: list of requirement strings
        - verification_checks: list of verification items
        - checklist: parsed checklist items
      </tasks>
      <set var="tag_structure" from="component_ref.tag_structure"/>
      <set var="template_bootstrap_path" from="component_ref.template_bootstrap_path"/>
      <set var="requirements" from="component_ref.requirements"/>
      <set var="checklist" from="component_ref.checklist"/>
      <print>
        Component reference loaded
        - Template Bootstrap: ${template_bootstrap_path}
        - Requirements: ${component_ref.requirements}
      </print>
      <goto to="step7-load-template-bootstrap"/>
    </stage>

    <!-- step7-load-template-bootstrap: Load Template Bootstrap -->
    <stage id="step7-load-template-bootstrap">
      <print>
        ## Step 7/15: Loading Template Bootstrap

        ${template_bootstrap_path}
      </print>
      <tasks output="template_bootstrap">
        ACTION: Read and analyze the Template Bootstrap document

        1. Read Template Bootstrap file:
           - Path: ${template_bootstrap_path}
           - Get full content

        2. Extract available templates:
           - Find <templates load="always" mode="context">
           - List all <read src="..." ask="..."/> entries
           - Extract:
             - src: template file path
             - ask: keywords that trigger this template

        3. Parse template options:
           For each template entry:
           - template_name: extract from filename (e.g., AXEL-Command-Linear-Tpl -> linear)
           - template_path: full src path
           - trigger_keywords: ask attribute value

        4. Common template patterns:
           - Command: linear (simple) | staged (complex with routing)
           - Agent: linear (simple) | staged (multi-step)
           - Workflow: linear | staged
           - Skill: linear | staged

        OUTPUT:
        - bootstrap_content: full bootstrap content
        - available_templates: list of {name, path, keywords}
        - template_count: number of available templates
      </tasks>
      <set var="available_templates" from="template_bootstrap.available_templates"/>
      <print>
        Template Bootstrap loaded
        - Available: ${template_bootstrap.template_count} templates
        - Templates: ${available_templates}
      </print>
      <goto to="step8-detect-template-type"/>
    </stage>

    <!-- step8-detect-template-type: Detect which template applies -->
    <stage id="step8-detect-template-type">
      <print>
        ## Step 8/15: Detecting Template Type
      </print>
      <tasks output="template_detection">
        ACTION: Analyze target document to determine which template applies

        Using elements_list from Step 3:

        1. Check for staging indicators:
           - Has <command id="cmd:main"> with multiple <goto>? -> staged
           - Has <execution flow="staged">? -> staged
           - Has multiple <stage id="..."> elements? -> staged
           - Has loops (<goto> back to previous stage)? -> staged

        2. Check for linear indicators:
           - Has <execution flow="linear">? -> linear
           - Has simple text-based execution? -> linear
           - No <stage> elements? -> linear

        3. Match with available templates:
           - Compare detected pattern with ${available_templates}
           - Select best matching template based on:
             a. flow attribute value
             b. presence of stages
             c. complexity of routing

        4. Determine template path:
           - Find matching template from available_templates
           - If no exact match, use default (usually staged for complex, linear for simple)

        OUTPUT:
        - detected_flow: linear | staged
        - selected_template_name: matched template name
        - selected_template_path: matched template path
        - selection_reason: why this template was selected
      </tasks>
      <set var="detected_flow" from="template_detection.detected_flow"/>
      <set var="selected_template_path" from="template_detection.selected_template_path"/>
      <print>
        Template type determined
        - Detected flow: **${detected_flow}**
        - Selected template: ${template_detection.selected_template_name}
        - Reason: ${template_detection.selection_reason}
      </print>
      <goto to="step9-load-template"/>
    </stage>

    <!-- step9-load-template: Load selected template -->
    <stage id="step9-load-template">
      <print>
        ## Step 9/15: Loading Template File

        ${selected_template_path}
      </print>
      <tasks output="template_content">
        ACTION: Read and analyze the selected template document

        1. Read template file:
           - Path: ${selected_template_path}
           - Get full content

        2. Extract template structure:
           - Parse the <document type="..."> root
           - List all top-level elements in order
           - Note required vs optional elements
           - Note default attribute values

        3. Extract template axel-tag-structure (if present):
           - Some templates have their own structure definition
           - This supplements the reference structure

        4. Extract template patterns:
           - Stage patterns (help, list, create, complete, fail, etc.)
           - Variable patterns (common var definitions)
           - Routing patterns (common goto sequences)

        5. Build template element order:
           - enforcement -> objective -> documents -> variables ->
           - command (if applicable) -> execution -> understanding

        OUTPUT:
        - template_raw: full template content
        - template_element_order: ordered list of element names
        - template_attributes: default attributes per element
        - template_patterns: common patterns found
        - template_stage_patterns: stage id naming conventions
      </tasks>
      <set var="template_element_order" from="template_content.template_element_order"/>
      <set var="template_attributes" from="template_content.template_attributes"/>
      <set var="template_patterns" from="template_content.template_patterns"/>
      <print>
        Template loaded
        - Element order: ${template_element_order}
        - Patterns: ${template_patterns}
      </print>
      <goto when="${pattern_ref_src} != null" to="step10-load-pattern-ref"/>
      <goto to="step11-extract-structure"/>
    </stage>

    <!-- step10-load-pattern-ref: Load pattern reference -->
    <stage id="step10-load-pattern-ref">
      <print>
        ## Step 10/15: Loading Pattern Reference

        ${pattern_ref_src}
      </print>
      <tasks output="pattern_ref">
        ACTION: Read and analyze the pattern reference document

        1. Read pattern reference file:
           - Path: ${pattern_ref_src}
           - Get full content

        2. Extract pattern-specific structure:
           - Find <axel-tag-structure> if present
           - Or infer from templates block

        3. Extract pattern-specific requirements:
           - Find <requirements> element
           - List pattern-specific rules

        4. Merge with component requirements:
           - Pattern requirements add to component requirements
           - Pattern structure overrides for reference subtypes

        OUTPUT:
        - pattern_content: full pattern content
        - pattern_structure: pattern-specific structure (if any)
        - pattern_requirements: additional requirements
        - merged_requirements: combined requirements list
      </tasks>
      <set var="pattern_structure" from="pattern_ref.pattern_structure"/>
      <set var="merged_requirements" from="pattern_ref.merged_requirements"/>
      <print>
        Pattern reference loaded
        - Pattern requirements: ${pattern_ref.pattern_requirements}
      </print>
      <goto to="step11-extract-structure"/>
    </stage>

    <!-- step11-extract-structure: Extract expected structure -->
    <stage id="step11-extract-structure">
      <print>
        ## Step 11/15: Extracting Expected Structure

        Reference: ${component_ref_src}
        Template: ${selected_template_path}
      </print>
      <tasks output="expected_structure"><![CDATA[
        ACTION: Build expected structure from BOTH reference AND template

        PART A: Reference Structure (axel-tag-structure)

        1. Parse tag_structure (from component reference):
           - Extract element hierarchy
           - Note required vs optional elements
           - Note element order
           - This is the AUTHORITATIVE structure

        2. Build reference element list:
           For each element in structure:
           - name: element name
           - required: true/false
           - order: position in document
           - attributes: list of {name, required, values}
           - parent: parent element name or null

        PART B: Template Structure (actual example)

        3. Parse template_element_order (from Step 9):
           - This shows ACTUAL working order from template
           - Extract default attribute values
           - Note common patterns

        4. Compare reference vs template:
           - Reference defines WHAT elements are valid
           - Template shows HOW to use them in practice
           - Template provides DEFAULT values
           - Reference provides RULES and REQUIREMENTS

        PART C: Merge and Build Expected Structure

        5. Build merged expected structure:
           PRIMARY SOURCE: template_element_order (actual working order)
           VALIDATION: tag_structure (rules and requirements)
           DEFAULTS: template_attributes (attribute values)

           For ${doc_type}:
           - command: entry="cmd:main", <command> routing, <execution flow="staged">
           - agent: <archetype>, <system-prompt>, <execution>
           - skill: <archetype>, <system-prompt>, <execution>
           - workflow: <execution flow="...">
           - reference: <objective>, patterns, <understanding/>

        6. Document-type specific rules:
           Based on ${doc_type} and ${detected_flow}:
           - If staged: must have <execution flow="staged"> with <stage> elements
           - If linear: must have <execution flow="linear"> with text content
           - All: must end with <understanding/>

        7. Build expected order:
           Using template as guide (practical order):
           - enforcement (optional but recommended)
           - objective (required)
           - context (optional)
           - documents (0 or more, grouped by load type)
           - templates (0 or more, for agents/skills)
           - variables (optional)
           - command (for commands only)
           - archetype (for agents/skills)
           - system-prompt (for agents/skills)
           - execution (required for executables)
           - output (optional)
           - understanding/ (required, at end)

        OUTPUT:
        - expected_elements: ordered list of {name, required, order, attributes, default_value}
        - expected_order: element name sequence (from template)
        - required_elements: list of required element names (from reference)
        - type_specific_rules: rules for ${doc_type}
        - default_attributes: map of element -> default attributes (from template)
        - structure_source: "reference+template" or "reference-only"
      ]]></tasks>
      <set var="expected_elements" from="expected_structure.expected_elements"/>
      <set var="expected_order" from="expected_structure.expected_order"/>
      <set var="required_elements" from="expected_structure.required_elements"/>
      <set var="default_attributes" from="expected_structure.default_attributes"/>
      <print>
        Expected structure extracted
        - Expected order: ${expected_order}
        - Required: ${required_elements}
        - Source: ${expected_structure.structure_source}
      </print>
      <goto to="step12-analyze-current"/>
    </stage>

    <!-- step12-analyze-current: Analyze current document structure -->
    <stage id="step12-analyze-current">
      <print>
        ## Step 12/15: Analyzing Current Structure
      </print>
      <tasks output="current_structure">
        ACTION: Detailed analysis of current document structure

        Using elements_list from Step 3:

        1. Map current elements:
           For each element in ${elements_list}:
           - name: element name
           - current_order: position in document
           - line_number: approximate line
           - attributes: parsed {name: value} map
           - content_preview: first 50 chars of content

        2. Identify element issues:
           - Missing required elements
           - Extra/unknown elements
           - Deprecated element names

        3. Identify attribute issues:
           For each element, check attributes:
           - Missing required attributes
           - Wrong attribute names (e.g., old names)
           - Invalid attribute values

        4. Identify order issues:
           - Elements out of expected order
           - Required elements in wrong position

        OUTPUT:
        - current_elements: detailed list of current elements
        - current_order: current element name sequence
        - missing_elements: required but missing
        - deprecated_elements: elements with old names
        - attribute_issues: list of {element, issue, current, expected}
      </tasks>
      <set var="current_elements" from="current_structure.current_elements"/>
      <set var="current_order" from="current_structure.current_order"/>
      <set var="missing_elements" from="current_structure.missing_elements"/>
      <print>
        Current structure analyzed
        - Current order: ${current_order}
        - Missing: ${missing_elements}
      </print>
      <goto to="step13-compare-elements"/>
    </stage>

    <!-- step13-compare-elements: Compare element order -->
    <stage id="step13-compare-elements">
      <print>
        ## Step 13/15: Comparing Element Order
      </print>
      <tasks output="element_comparison">
        ACTION: Compare current vs expected element order

        1. Compare sequences:
           - Expected: ${expected_order}
           - Current: ${current_order}

        2. Find order differences:
           For each element:
           - expected_position: where it should be
           - current_position: where it is
           - needs_reorder: true if positions differ

        3. Find missing elements:
           - In expected but not in current
           - Record where they should be added

        4. Build reorder plan:
           List elements that need to move:
           - element_name
           - from_position
           - to_position
           - IMPORTANT: Content stays with element (no content change)

        OUTPUT:
        - order_matches: boolean (orders are same)
        - reorder_items: list of {element, from, to}
        - add_items: list of {element, position, default_content}
        - reorder_count: number of reorders needed
      </tasks>
      <set var="order_matches" from="element_comparison.order_matches"/>
      <set var="reorder_items" from="element_comparison.reorder_items"/>
      <set var="add_items" from="element_comparison.add_items"/>
      <print>
        Element comparison completed
        - Order matches: ${order_matches}
        - Reorders needed: ${element_comparison.reorder_count}
        - Adds needed: ${element_comparison.add_items}
      </print>
      <goto to="step14-compare-attributes"/>
    </stage>

    <!-- step14-compare-attributes: Compare attributes -->
    <stage id="step14-compare-attributes">
      <print>
        ## Step 14/15: Comparing Attributes
      </print>
      <tasks output="attribute_comparison">
        ACTION: Compare current vs expected attributes for each element

        For each element in ${current_elements}:

        1. Get expected attributes:
           - From ${expected_elements} find matching element
           - Get required attributes list
           - Get optional attributes list

        2. Check current attributes:
           - Are all required attributes present?
           - Are attribute names correct? (check for old/deprecated names)
           - Are values valid?

        3. Identify attribute changes needed:
           - RENAME: old_name -> new_name (keep value!)
           - ADD: missing required attribute with default
           - No REMOVE (preserve user attributes)

        4. Common renames to check:
           - archetype: name -> type (for skill/agent)
           - documents: missing name attribute
           - goto: command -> to (deprecated)

        5. Build attribute change plan:
           For each change:
           - element: which element
           - change_type: RENAME | ADD
           - old_name: current attribute name (for rename)
           - new_name: new attribute name
           - value: preserved or default value
           - IMPORTANT: Never change user-provided values

        OUTPUT:
        - attributes_match: boolean (all attributes correct)
        - rename_items: list of {element, old_name, new_name, value}
        - add_attr_items: list of {element, attr_name, default_value}
        - attr_change_count: total attribute changes
      </tasks>
      <set var="attributes_match" from="attribute_comparison.attributes_match"/>
      <set var="rename_items" from="attribute_comparison.rename_items"/>
      <set var="add_attr_items" from="attribute_comparison.add_attr_items"/>
      <print>
        Attribute comparison completed
        - Attributes match: ${attributes_match}
        - Renames needed: ${rename_items}
        - Adds needed: ${add_attr_items}
      </print>
      <goto to="step15-build-plan"/>
    </stage>

    <!-- step15-build-plan: Build migration plan -->
    <stage id="step15-build-plan">
      <print>
        ## Step 15/15: Building Migration Plan
      </print>
      <tasks output="migration_plan">
        ACTION: Compile all changes into migration plan

        1. Combine all changes:
           - From reorder_items: REORDER changes
           - From add_items: ADD element changes
           - From rename_items: RENAME attribute changes
           - From add_attr_items: ADD attribute changes

        2. Number each change:
           Starting from 1, assign sequential number

        3. Format each change:
           [#] [TYPE] [Element:Line] - Description
           - Before: current state
           - After: migrated state

           Types:
           - REORDER: element position change
           - ADD_ELEM: new element added
           - RENAME_ATTR: attribute name change
           - ADD_ATTR: new attribute added

        4. Verify semantic integrity:
           For each change, confirm:
           - No content text modified
           - No user values changed
           - Only structural change

        5. Calculate totals:
           - total_changes: sum of all changes
           - by_type: count per change type

        OUTPUT:
        - changes: formatted list of all changes
        - change_count: total number
        - by_type: {REORDER: n, ADD_ELEM: n, RENAME_ATTR: n, ADD_ATTR: n}
        - semantic_safe: boolean (all changes are structural only)
      </tasks>
      <set var="changes" from="migration_plan.changes"/>
      <set var="change_count" from="migration_plan.change_count"/>
      <set var="semantic_safe" from="migration_plan.semantic_safe"/>
      <goto when="${change_count} = 0" to="no-changes"/>
      <goto when="${semantic_safe} = false" to="semantic-warning"/>
      <goto to="show-plan"/>
    </stage>

    <!-- no-changes: Document is up-to-date -->
    <stage id="no-changes">
      <print>
        ## Document Up-to-Date

        **File:** ${target_path}
        **Type:** ${doc_type}

        Document is already in the latest format. No migration needed.

        Checked:
        - Element order
        - Attribute names
        - Required elements
      </print>
      <stop kind="end"/>
    </stage>

    <!-- semantic-warning: Content change detected -->
    <stage id="semantic-warning">
      <print>
        ## Semantic Integrity Warning

        Content change detected in migration plan!

        This agent is designed for structural changes only.
        Cases requiring content changes need manual editing.

        Detected issue: ${migration_plan.semantic_issue}
      </print>
      <stop kind="error"/>
    </stage>

    <!-- show-plan: Display migration plan and ask for approval -->
    <stage id="show-plan">
      <print>
        ## Migration Plan

        **File:** ${target_path}
        **Type:** ${doc_type}
        **Reference:** ${component_ref_src}

        ---

        ### Changes (${change_count})

        ${changes}

        ---

        **Summary:**
        - REORDER: ${migration_plan.by_type.REORDER}
        - ADD_ELEM: ${migration_plan.by_type.ADD_ELEM}
        - RENAME_ATTR: ${migration_plan.by_type.RENAME_ATTR}
        - ADD_ATTR: ${migration_plan.by_type.ADD_ATTR}

        ---

        **Semantic Integrity:** All changes are structural

        ---
        `yes` - Apply | `no` - Cancel | `detail` - Show details
      </print>
      <ask var="confirm" prompt="Apply migration?">
        <goto when="${confirm} = 'no'" to="cancelled"/>
        <goto when="${confirm} = 'detail'" to="show-detail"/>
        <goto to="apply"/>
      </ask>
    </stage>

    <!-- show-detail: Show detailed before/after -->
    <stage id="show-detail">
      <tasks output="detail_view">
        ACTION: Show detailed before/after for each change

        For each change in ${changes}:
        1. Show exact location (file:line)
        2. Show BEFORE (current content, 3-5 lines context)
        3. Show AFTER (migrated content)
        4. Highlight what changed (structural only)

        Format as markdown diff blocks
      </tasks>
      <print>
        ## Detailed Changes

        ${detail_view.formatted}

        ---
        `yes` - Apply | `no` - Cancel
      </print>
      <ask var="confirm_detail" prompt="Apply migration?">
        <goto when="${confirm_detail} = 'no'" to="cancelled"/>
        <goto to="apply"/>
      </ask>
    </stage>

    <!-- apply: Apply migration changes -->
    <stage id="apply">
      <print>
        ## Applying Migration...
      </print>
      <tasks output="apply_result">
        ACTION: Apply migration changes

        For each change in ${changes}:

        1. REORDER changes:
           - Move element to new position
           - Keep all content exactly as-is

        2. ADD_ELEM changes:
           - Insert new element at specified position
           - Use minimal default content

        3. RENAME_ATTR changes:
           - Change attribute name
           - Keep attribute value exactly as-is

        4. ADD_ATTR changes:
           - Add new attribute with default value

        After all changes:
        1. Verify document is valid XML
        2. Verify semantic integrity:
           - Compare text content sections
           - Ensure no unintended changes
        3. Write to file

        OUTPUT:
        - success: boolean
        - applied_count: changes applied
        - integrity_check: passed/failed
        - final_content: migrated document
      </tasks>
      <set var="apply_success" from="apply_result.success"/>
      <set var="integrity_check" from="apply_result.integrity_check"/>
      <goto when="${integrity_check} = 'failed'" to="integrity-failed"/>
      <goto when="${apply_success} = false" to="failed"/>
      <goto to="complete"/>
    </stage>

    <!-- integrity-failed: Rollback on integrity failure -->
    <stage id="integrity-failed">
      <print>
        ## Integrity Check Failed

        Migration applied but integrity check failed.

        Rolling back changes...
      </print>
      <tasks output="rollback">
        ACTION: Restore original content
        - Write ${raw_content} back to ${full_path}
      </tasks>
      <print>
        Original file restored.
        Please check manually.
      </print>
      <stop kind="error"/>
    </stage>

    <!-- complete: Report success -->
    <stage id="complete">
      <print>
        ## Migration Completed

        **File:** ${target_path}
        **Applied:** ${apply_result.applied_count} changes

        Semantic integrity: Verified
      </print>
      <stop kind="end"/>
    </stage>

    <!-- failed: Report failure -->
    <stage id="failed">
      <print>
        ## Migration Failed

        An error occurred. File was not modified.
      </print>
      <stop kind="error"/>
    </stage>

    <!-- cancelled: User cancelled -->
    <stage id="cancelled">
      <print>
        Operation cancelled. No changes were made.
      </print>
      <stop kind="end"/>
    </stage>

  </execution>

  <output format="markdown">
    ## Migration Result

    **Document:** [target path]
    **Type:** [document type]

    ### Changes Applied
    | # | Type | Element | Description |
    |---|------|---------|-------------|
    | 1 | [type] | ... | ... |

    ### Summary
    - REORDER: [count]
    - ADD_ELEM: [count]
    - RENAME_ATTR: [count]
    - ADD_ATTR: [count]

    **Semantic Integrity:** [Verified/Failed]
  </output>

  <understanding/>

</document>