Update Ported Plugin

Apply incremental updates to previously-ported plugins when source plugins have changed or the target platform has evolved. Reads the PORT-METADATA embedded in MIGRATION-GUIDE.md to determine the baseline, detects source diffs and platform drift, and applies targeted updates without re-running the full port-plugin workflow.

CRITICAL: Complete ALL 5 phases. The workflow is not complete until Phase 5: Output & Refresh is finished. After completing each phase, immediately proceed to the next phase without waiting for user prompts.

Critical Rules

AskUserQuestion is MANDATORY

IMPORTANT: You MUST use the

AskUserQuestion

Plan Mode Behavior

CRITICAL: This skill performs an interactive update workflow, NOT an implementation plan. Proceed with the full detection and update workflow immediately -- do not defer to an "execution phase".

Phase Overview

Execute these phases in order, completing ALL of them:

1. Load Context -- Parse arguments, locate MIGRATION-GUIDE.md, extract and validate PORT-METADATA
2. Detect Changes -- Diff source files against baseline commit, check platform adapter staleness
3. Apply Source Changes -- Incrementally update ported files for source modifications
4. Apply Platform Changes -- Update ported files for platform adapter drift
5. Output & Refresh -- Write files, refresh metadata, update history, and summarize

Phase 1: Load Context

Goal: Parse arguments, locate the MIGRATION-GUIDE.md from a previous port, extract the PORT-METADATA block, and validate that the baseline is intact.

Step 1: Parse Arguments

Parse

$ARGUMENTS

• --target <platform>

  -- Target platform slug (default:

  opencode

  )

• --source-only

  -- Only detect and apply source changes; skip platform change detection

• --platform-only

  -- Only detect and apply platform changes; skip source change detection

• --output-dir <path>

  -- Override output directory for updated files (default: write in-place)

Set

TARGET_PLATFORM

SOURCE_ONLY

PLATFORM_ONLY

OUTPUT_DIR

--source-only

--platform-only

false

Step 2: Load Settings

Check

.claude/agent-alchemy.local.md

plugin-tools

default-target

default-output-dir

Step 3: Locate MIGRATION-GUIDE.md

Search order: (1)

{OUTPUT_DIR}/MIGRATION-GUIDE.md

ported/{TARGET_PLATFORM}/MIGRATION-GUIDE.md

Glob: **/MIGRATION-GUIDE.md

If multiple found, present for selection:

AskUserQuestion:
  questions:
    - header: "Multiple Migration Guides Found"
      question: "Multiple MIGRATION-GUIDE.md files were found. Which one should be updated?"
      options:
        - label: "{path_1}"
          description: "Last modified: {date}"
        - label: "{path_2}"
          description: "Last modified: {date}"
      multiSelect: false

If none found, offer options via

AskUserQuestion

MIGRATION_GUIDE_PATH

PORT_OUTPUT_DIR

Step 4: Extract PORT-METADATA

Read the MIGRATION-GUIDE.md file and extract the

PORT-METADATA

Read: {MIGRATION_GUIDE_PATH}

Search for the

<!-- PORT-METADATA ... PORT-METADATA -->

source_commit

port_date

adapter_version

target_platform

target_platform_version

components

source

target

fidelity

Error handling -- Missing metadata block:

AskUserQuestion:
  questions:
    - header: "Missing PORT-METADATA"
      question: "The MIGRATION-GUIDE.md does not contain a PORT-METADATA block. How would you like to proceed?"
      options:
        - label: "Reconstruct metadata"
          description: "Scan the output directory and git history to rebuild the metadata block"
        - label: "Run fresh port"
          description: "Start over with /port-plugin"
        - label: "Cancel"
          description: "Exit the update workflow"
      multiSelect: false

If reconstructing: scan

PORT_OUTPUT_DIR

Glob

git log --oneline --all -- {MIGRATION_GUIDE_PATH}

Error handling -- Malformed metadata: Fall back to line-by-line regex extraction of key-value pairs and

- source:

target:

fidelity:

Store extracted metadata as

PORT_METADATA

Step 5: Validate Baseline

Verify the baseline is intact:

1. Source commit:

   git rev-parse --verify {PORT_METADATA.source_commit}

   -- if not found, set

   SOURCE_COMMIT_VALID = false

   and warn
2. Source files: Check each

   component.source

   still exists; build

   MISSING_SOURCES

   list
3. Target files: Check each

   {PORT_OUTPUT_DIR}/{component.target}

   still exists; build

   MISSING_TARGETS

   list
4. Adapter file: Verify

   ${CLAUDE_PLUGIN_ROOT}/references/adapters/{PORT_METADATA.target_platform}.md

   exists

Step 6: Display Summary and Confirm

Present the baseline summary via

AskUserQuestion

AskUserQuestion:
  questions:
    - header: "Port Baseline Summary"
      question: |
        Previous port details:
        - Port date: {PORT_METADATA.port_date}
        - Source commit: {PORT_METADATA.source_commit} (short hash)
        - Components: {PORT_METADATA.components.length} ported
        - Adapter version: {PORT_METADATA.adapter_version}
        - Target platform: {PORT_METADATA.target_platform} v{PORT_METADATA.target_platform_version}
        {If MISSING_SOURCES.length > 0:}
        - WARNING: {MISSING_SOURCES.length} source file(s) no longer exist
        {If MISSING_TARGETS.length > 0:}
        - WARNING: {MISSING_TARGETS.length} target file(s) no longer exist
        {If !SOURCE_COMMIT_VALID:}
        - WARNING: Source commit not found in git history (history may have been rewritten)

        Proceed with update check?
      options:
        - label: "Proceed"
          description: "Check for source and platform changes since the last port"
        - label: "View missing files"
          description: "Show details of missing source or target files before proceeding"
        - label: "Cancel"
          description: "Exit the update workflow"
      multiSelect: false

If "View missing files": list all missing files, then re-present proceed/cancel. If "Cancel": exit gracefully.

Phase 2: Detect Changes

Goal: Identify what has changed since the original port -- both in source plugin files and on the target platform -- and present a combined summary for the user to scope the update.

Run two parallel change detection tracks (unless

--source-only

--platform-only

Track A: Source Changes

Skip this track if

PLATFORM_ONLY

true

Step A1: Diff Source Files

git diff {PORT_METADATA.source_commit}..HEAD -- {space-separated list of source paths}

If

SOURCE_COMMIT_VALID

false

git log --since="{PORT_METADATA.port_date}"

Step A2: Detect New and Deleted Files

git diff --name-status {PORT_METADATA.source_commit}..HEAD -- {source parent directories}

Parse output:

A

D

M

R

Step A3: Classify Changes

For each changed source file, classify the change into one of three categories:

Build

SOURCE_CHANGES

file_path

change_type

classification

diff_summary

diff_lines_added

diff_lines_removed

affected_sections

component_entry

null

New files get

classification: "structural"

diff_summary: "New component -- requires full port"

classification: "structural"

diff_summary: "Source component deleted -- ported version may be orphaned"

Track B: Platform Changes

Skip this track if

SOURCE_ONLY

true

Step B1: Load Validate-Adapter Skill

Read the validate-adapter skill to access its platform validation logic:

Read: ${CLAUDE_PLUGIN_ROOT}/skills/validate-adapter/SKILL.md

Step B2: Run Platform Validation

1. Load the adapter file:

   Read: ${CLAUDE_PLUGIN_ROOT}/references/adapters/{TARGET_PLATFORM}.md

2. Spawn the researcher agent:

   Task:
     description: "Research current state of {TARGET_PLATFORM}'s plugin system. Compare against adapter. Focus on changes since v{PORT_METADATA.target_platform_version}."
     subagent_type: "agent-alchemy-plugin-tools:researcher"
     input: |
       Target platform: {TARGET_PLATFORM}
       Existing adapter file: ${CLAUDE_PLUGIN_ROOT}/references/adapters/{TARGET_PLATFORM}.md
       Last known platform version: {PORT_METADATA.target_platform_version}
   

3. Collect the researcher's platform profile and adapter comparison results.

Step B3: Extract Platform Findings

From the researcher's adapter comparison results, extract three categories:

Categorize findings into three types:

adapter_section

old_mapping

new_mapping

affected_components

adapter_section

feature_description

potential_benefit

adapter_section

feature_description

alternative

affected_components

Step B4: Classify Platform Impact

Classify each finding by cross-referencing against

PORT_METADATA.components

• Breaking: Stale/removed mapping used by at least one ported component
• Additive: New feature that could improve ported components but is not required
• Cosmetic: Naming change or minor adjustment with no functional impact

Build

PLATFORM_CHANGES

Combined Change Summary

After both tracks complete, present the combined results via

AskUserQuestion

AskUserQuestion:
  questions:
    - header: "Change Detection Summary"
      question: |
        Changes detected since the last port ({PORT_METADATA.port_date}):

        Source changes:
        - {count} files modified ({structural_count} structural, {content_count} content, {cosmetic_count} cosmetic)
        - {added_count} new files detected
        - {deleted_count} files deleted

        Platform changes ({TARGET_PLATFORM}):
        - {stale_count} stale mappings ({breaking_stale_count} breaking)
        - {missing_count} new platform features
        - {removed_count} removed features ({breaking_removed_count} breaking)

        Estimated update scope: {small/medium/large}

        How would you like to proceed?
      options:
        - label: "Apply all changes"
          description: "Process both source and platform changes"
        - label: "Source changes only"
          description: "Apply only source file updates, skip platform changes"
        - label: "Platform changes only"
          description: "Apply only platform-related updates, skip source changes"
        - label: "Select specific changes"
          description: "Choose individual changes to apply"
        - label: "Cancel"
          description: "Exit without making changes"
      multiSelect: false

Scope estimation:

• Small: 0-3 total changes, all cosmetic or content
• Medium: 4-10 total changes, or any structural source changes, or any additive platform changes
• Large: 10+ total changes, or any breaking platform changes, or any new/deleted source files

If user selects "Select specific changes", present a detailed checklist:

AskUserQuestion:
  questions:
    - header: "Select Changes to Apply"
      question: "Select which changes to apply:"
      options:
        - label: "[source] {file_name} ({classification})"
          description: "{diff_summary}"
        - label: "[platform] {finding_type}: {description}"
          description: "Impact: {impact} -- affects {affected_count} component(s)"
      multiSelect: true

Store the user's selection as

SELECTED_CHANGES

selected_source_changes

selected_platform_changes

If user selects "Cancel", exit gracefully.

Phase 3: Apply Source Changes

Goal: Incrementally update ported files to reflect source plugin modifications.

Skip this phase entirely if:

• User selected "Platform changes only" in Phase 2
• User selected "Cancel" in Phase 2

• SOURCE_CHANGES

  is empty (no source changes detected)

Initialize tracking:

UPDATED_FILES = []      // files modified during this phase
SKIPPED_FILES = []      // files user chose to skip
NEW_COMPONENTS = []     // new source files that need full porting
DELETED_COMPONENTS = [] // source files deleted, ported versions potentially orphaned

Step 1: Apply Cosmetic Changes

Process all cosmetic changes first (these do not require user approval):

For each entry in

SOURCE_CHANGES

classification == "cosmetic"

1. Read the current ported target file:

   Read: {PORT_OUTPUT_DIR}/{component_entry.target}

2. Apply whitespace and formatting changes to match the updated source
3. Write the updated file using

   Edit

   tool
4. Add to

   UPDATED_FILES

   with

   update_type: "cosmetic"

Log:

Applied {count} cosmetic updates automatically.

Step 2: Process Modified Components (Structural and Content)

For each entry in

SOURCE_CHANGES

change_type == "modified"

classification

"structural"

"content"

2a: Load Conversion Context

1. Read the current source file:

   Read: {source_change.file_path}
   

2. Read the current ported target file:

   Read: {PORT_OUTPUT_DIR}/{source_change.component_entry.target}
   

3. Load the appropriate converter reference from

   ${CLAUDE_PLUGIN_ROOT}/references/

   :

   Source path contains	Load converter
   /agents/	agent-converter.md
   /hooks/	hook-converter.md
   /references/	reference-converter.md
   .mcp.json	mcp-converter.md
   Skills (default)	adapters/{TARGET_PLATFORM}.md

4. Also load the adapter file (

   adapters/{TARGET_PLATFORM}.md

   ) if not already loaded.

2b: Apply Structural Changes

For structural changes, re-run conversion on the changed sections:

1. Identify changed sections by comparing the diff against the file structure
2. For each changed section: extract updated content, apply converter mapping rules, replace the corresponding section in the ported target
3. For frontmatter changes: parse updated frontmatter, apply adapter mappings, merge with existing ported frontmatter (preserve target-specific fields, update source-derived fields)
4. For

   allowed-tools

   /

   tools

   changes: map new tools through adapter equivalents, remove dropped tools, flag tools with no target equivalent

2c: Apply Content Changes

For content changes, apply targeted text transformations:

1. Identify specific text changes from the diff and locate them in the ported target
2. Apply converter mapping rules to transform the new text
3. Replace the old text, preserving any target-platform-specific modifications from the original port

2d: Check for New Incompatibilities

Load the incompatibility resolver:

Read: ${CLAUDE_PLUGIN_ROOT}/references/incompatibility-resolver.md

Check if any of the changes introduce new incompatibilities with the target platform:

• New tool references that have no target equivalent
• New composition patterns not supported by the target
• New agent configurations with no mapping

For each new incompatibility found, present it to the user:

AskUserQuestion:
  questions:
    - header: "New Incompatibility Detected"
      question: |
        The source change in {file_path} introduces a new incompatibility:

        Feature: {feature_description}
        Issue: {incompatibility_description}
        Severity: {critical/functional/cosmetic}

        How should this be handled?
      options:
        - label: "Apply workaround"
          description: "{workaround_description}"
        - label: "Add TODO placeholder"
          description: "Insert a TODO comment for manual resolution"
        - label: "Skip this change"
          description: "Do not apply this specific change"
      multiSelect: false

2e: Confirm and Apply

For each significant change (structural or content with incompatibilities), present a before/after preview:

AskUserQuestion:
  questions:
    - header: "Confirm Update: {file_name}"
      question: |
        Source change: {diff_summary}
        Affected section: {section_name}

        The ported file will be updated with the converted changes.
        Apply this update?
      options:
        - label: "Apply"
          description: "Update the ported file"
        - label: "Skip"
          description: "Leave the ported file unchanged for this change"
        - label: "Show diff"
          description: "View the detailed before/after comparison"
      multiSelect: false

If "Show diff", display before/after and re-ask. If "Apply", write with

Edit

UPDATED_FILES

SKIPPED_FILES

Step 3: Handle New Components

For each entry in

SOURCE_CHANGES

change_type == "added"

AskUserQuestion:
  questions:
    - header: "New Source Component"
      question: |
        A new component was detected: {file_path}

        This file was added since the last port and requires a full conversion.
        The update skill handles incremental changes; full conversions are best
        handled by the port-plugin skill.
      options:
        - label: "Run /port-plugin for this component"
          description: "Recommended: use the full porting workflow for new components"
        - label: "Add to gap report"
          description: "Note this as an unported component in the gap report"
        - label: "Skip"
          description: "Ignore this new component"
      multiSelect: false

If "Run /port-plugin": add to

NEW_COMPONENTS

action: "port"

action: "gap"

Step 4: Handle Deleted Components

For each entry in

SOURCE_CHANGES

change_type == "deleted"

AskUserQuestion:
  questions:
    - header: "Deleted Source Component"
      question: |
        Source component was deleted: {file_path}
        Ported version exists at: {PORT_OUTPUT_DIR}/{target_path}

        The source file no longer exists. What should we do with the ported version?
      options:
        - label: "Delete ported file"
          description: "Remove the ported version since its source no longer exists"
        - label: "Keep as orphaned"
          description: "Keep the ported file but mark it as orphaned in the migration guide"
        - label: "Skip"
          description: "Take no action"
      multiSelect: false

If "Delete": remove via

Bash

rm {PORT_OUTPUT_DIR}/{target_path}

DELETED_COMPONENTS

<!-- ORPHANED: Source file {source_path} was deleted on {date} -->

DELETED_COMPONENTS

Phase 4: Apply Platform Changes

Goal: Update ported files to reflect changes in the target platform since the original port.

Skip this phase entirely if:

• User selected "Source changes only" in Phase 2
• User selected "Cancel" in Phase 2

• PLATFORM_CHANGES

  is empty (no platform changes detected)

Step 1: Apply Breaking Changes

Process breaking changes first as they affect correctness.

1a: Stale Mappings

For each stale breaking change: identify affected ported files, locate stale mapping instances, and prepare replacements. Present each:

AskUserQuestion:
  questions:
    - header: "Stale Platform Mapping"
      question: |
        Platform mapping has changed for {TARGET_PLATFORM}:

        Section: {adapter_section}
        Old: {old_mapping}
        New: {new_mapping}

        Affected files ({affected_count}):
        {list of affected ported files}

        Apply the updated mapping?
      options:
        - label: "Apply to all affected files"
          description: "Update all {affected_count} file(s) with the new mapping"
        - label: "Apply selectively"
          description: "Choose which files to update"
        - label: "Skip"
          description: "Keep the current mapping (may cause issues on the platform)"
      multiSelect: false

If "Apply selectively", present each file individually. Apply updates via

Edit

UPDATED_FILES

update_type: "platform_stale"

1b: Removed Features

For each removed breaking feature, identify affected files and present:

AskUserQuestion:
  questions:
    - header: "Removed Platform Feature"
      question: |
        {TARGET_PLATFORM} has removed or deprecated a feature used by ported components:

        Feature: {feature_description}
        {If alternative:}Alternative: {alternative}
        {If no alternative:}No direct alternative available.

        Affected files ({affected_count}):
        {list of affected ported files}

        How should this be handled?
      options:
        - label: "Apply alternative"
          description: "Replace with: {alternative}"
        - label: "Add TODO placeholder"
          description: "Insert a TODO comment for manual resolution"
        - label: "Remove feature usage"
          description: "Remove references to this feature from ported files"
        - label: "Keep as-is with warning"
          description: "Leave unchanged but add a deprecation warning comment"
      multiSelect: false

Apply the selected resolution to each affected file and add to

UPDATED_FILES

update_type: "platform_removed"

Step 2: Apply Additive Changes

Present new platform features that could enhance ported components:

AskUserQuestion:
  questions:
    - header: "New Platform Features"
      question: |
        {TARGET_PLATFORM} has added new features since the last port.
        Select which ones to apply to your ported components:
      options:
        - label: "{feature_description}"
          description: "Benefit: {potential_benefit} -- affects {affected_count} component(s)"
      multiSelect: true

For each selected feature: identify benefiting files, apply using adapter mapping rules, add to

UPDATED_FILES

update_type: "platform_additive"

No additive platform changes applied.

Step 3: Update Adapter File

After applying platform changes, offer to update the adapter file:

AskUserQuestion:
  questions:
    - header: "Update Adapter File"
      question: |
        The adapter file for {TARGET_PLATFORM} may be stale based on the platform changes detected.
        Would you like to update it?
      options:
        - label: "Update adapter"
          description: "Apply validated platform changes to the adapter file"
        - label: "Skip adapter update"
          description: "Leave the adapter file unchanged (note: it may be stale)"
      multiSelect: false

If "Update adapter": load validate-adapter (

Read: ${CLAUDE_PLUGIN_ROOT}/skills/validate-adapter/SKILL.md

ADAPTER_UPDATED = false

Phase 5: Output & Refresh

Goal: Write all updated files, refresh the PORT-METADATA block, update the migration guide history, refresh the gap report, and present a final summary.

Step 1: Write Updated Files

For each file in

UPDATED_FILES

OUTPUT_DIR

{OUTPUT_DIR}/{relative_target_path}

WRITE_RESULTS

files_written

files_failed

Step 2: Refresh PORT-METADATA

Get the current HEAD commit hash:

git rev-parse HEAD

Get today's date for the port_date field.

Build the updated PORT-METADATA block:

<!-- PORT-METADATA
source_commit: {current_HEAD_hash}
port_date: {today_date}
adapter_version: {new_adapter_version or PORT_METADATA.adapter_version if not updated}
target_platform: {PORT_METADATA.target_platform}
target_platform_version: {new_platform_version or PORT_METADATA.target_platform_version}
components:
{For each component in PORT_METADATA.components that was NOT deleted:}
  - source: {component.source}
    target: {component.target}
    fidelity: {updated_fidelity_score or original if unchanged}
{For any NEW components that were fully ported:}
  - source: {new_source_path}
    target: {new_target_path}
    fidelity: {new_fidelity_score}
PORT-METADATA -->

Fidelity score rules: Cosmetic/content changes keep original score. Structural changes and platform breaking changes trigger recalculation. Orphaned components are removed from the list.

Replace the old PORT-METADATA block in MIGRATION-GUIDE.md with the updated block using

Edit

Step 3: Append Update History

Add an update history entry to MIGRATION-GUIDE.md. If an

## Update History

## Update History

### {today_date} -- Incremental Update
- **Source changes**: {modified_count} files updated, {added_count} new, {deleted_count} deleted
- **Platform changes**: {stale_updated_count} mappings updated, {additive_applied_count} features added, {removed_handled_count} removals handled
- **Scope**: {source-only|platform-only|full}
- **Skipped**: {skipped_count} changes skipped by user
- **Components affected**: {affected_component_count}/{total_component_count}

If the Update History section already has entries, append the new entry at the top (most recent first).

Step 4: Refresh GAP-REPORT.md

Check if a GAP-REPORT.md exists in

PORT_OUTPUT_DIR

Glob: {PORT_OUTPUT_DIR}/GAP-REPORT.md

If exists: Read it, remove entries that were resolved by this update (mark as

RESOLVED

If does not exist: Create a new GAP-REPORT.md (following port-plugin format) only if there are new gaps. If no new gaps, do not create one.

Step 5: Final Summary

Present the update results via

AskUserQuestion

AskUserQuestion:
  questions:
    - header: "Update Complete"
      question: |
        Update summary for {TARGET_PLATFORM} port:

        Files updated: {WRITE_RESULTS.files_written.length}
        {For each file: - {path} ({update_type})}

        New gaps introduced: {new_gap_count}
        Gaps resolved: {resolved_gap_count}
        Metadata refreshed: yes
        Adapter updated: {yes/no}

        Components:
        - Updated: {updated_count}
        - Skipped: {skipped_count}
        - New (needs full port): {new_component_count}
        - Deleted/orphaned: {deleted_count}

        Next steps:
        {If NEW_COMPONENTS with action "port":}
        1. Run /port-plugin --target {TARGET_PLATFORM} for {new_count} new component(s)
        {If SKIPPED_FILES.length > 0:}
        2. Review {skipped_count} skipped change(s) for manual handling
        {If ADAPTER_UPDATED == false and PLATFORM_CHANGES.length > 0:}
        3. Consider updating the adapter file with /validate-adapter --target {TARGET_PLATFORM}
        4. Test updated plugins on {TARGET_PLATFORM}
        5. Review MIGRATION-GUIDE.md for full update history
      options:
        - label: "Done"
          description: "Finish the update workflow"
        - label: "View updated files"
          description: "List all files that were modified"
        - label: "Run another update"
          description: "Check for additional changes"
      multiSelect: false

If "View updated files": list all written files with paths and update types, then re-present options. If "Run another update": return to Phase 1 Step 3 (re-locate migration guide with refreshed metadata).

Error Handling

If any phase fails:

1. Explain what went wrong
2. Use

   AskUserQuestion

   to ask how to proceed:

   AskUserQuestion:
     questions:
       - header: "Error Recovery"
         question: "{Description of what failed}. How would you like to proceed?"
         options:
           - label: "Retry this phase"
             description: "Attempt the failed phase again"
           - label: "Skip to next phase"
             description: "Continue without this phase's output"
           - label: "Cancel"
             description: "Exit the update workflow"
         multiSelect: false
   

Specific Error Scenarios

Git history unavailable: If

git

• Log:

  WARNING: Git history is unavailable. Source change detection requires git history.

• If

  SOURCE_ONLY

  or full update: cannot detect source changes, offer to proceed with platform changes only or cancel
• If

  PLATFORM_ONLY

  : git is not needed, continue normally

Adapter file missing: If the adapter file for

TARGET_PLATFORM

• Log:

  WARNING: No adapter file found for {TARGET_PLATFORM}. Platform change detection is limited.

• Source changes can still be applied using generic conversion logic
• Platform changes cannot be fully evaluated without an adapter

Ported file write conflict: If a target file has been manually edited since the last port (detected by comparing file modification time against

PORT_METADATA.port_date

• Warn the user that the file appears to have manual edits
• Offer: "Overwrite", "Merge manually", or "Skip"

Reference Files

• references/adapter-format.md

  -- Adapter file format specification (9 mapping sections)

• references/agent-converter.md

  -- Agent conversion logic (frontmatter mapping, body transformation, gap handling, fidelity scoring)

• references/hook-converter.md

  -- Hook conversion logic (event mapping, behavioral classification, workaround strategies)

• references/reference-converter.md

  -- Reference file conversion logic (discovery, path transformation, flattening)

• references/mcp-converter.md

  -- MCP config conversion logic (server mapping, transport types, tool reference renaming, platform support detection)

• references/incompatibility-resolver.md

  -- Incompatibility detection, interactive resolution, batch handling, decision tracking

• references/adapters/

  -- Directory for per-platform adapter files (one markdown file per target platform)