Update Ported Plugin

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 tool for ALL questions to the user. Never ask questions through regular text output. Text output is only for status updates and informational summaries.

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

• --target -- 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 -- Override output directory for updated files (default: write in-place)

Set TARGET_PLATFORM, SOURCE_ONLY, PLATFORM_ONLY, and OUTPUT_DIR from parsed arguments. If both --source-only and --platform-only are specified, they are mutually exclusive -- inform the user and proceed with full update (both flags false).

Step 2: Load Settings

Check .claude/agent-alchemy.local.md for a plugin-tools section (default-target, default-output-dir). Apply settings as defaults -- CLI arguments override.

Step 3: Locate MIGRATION-GUIDE.md

Search order: (1) {OUTPUT_DIR}/MIGRATION-GUIDE.md if specified, (2) ported/{TARGET_PLATFORM}/MIGRATION-GUIDE.md, (3) 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: "Run /port-plugin" (start fresh), "Specify path manually", or "Cancel". Handle accordingly. Store the located path as MIGRATION_GUIDE_PATH and its parent as PORT_OUTPUT_DIR.

Step 4: Extract PORT-METADATA

Read the MIGRATION-GUIDE.md file and extract the PORT-METADATA HTML comment block:

Read: {MIGRATION_GUIDE_PATH}

Search for the ` block and parse the YAML-like content to extract: sourcecommit, portdate, adapterversion, targetplatform, targetplatformversion, and components list (each with 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 for converted files via Glob, find the most recent port commit via git log --oneline --all -- {MIGRATION_GUIDE_PATH}, and build best-effort metadata. Warn user it may be incomplete.

Error handling -- Malformed metadata: Fall back to line-by-line regex extraction of key-value pairs and - source: / target: / fidelity: patterns. If fallback fails, present the reconstruction option.

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 or --platform-only was specified).

Track A: Source Changes

Skip this track if PLATFORM_ONLY is true.

Step A1: Diff Source Files

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

If SOURCE_COMMIT_VALID is false, fall back to git log --since="{PORT_METADATA.port_date}" and diff each file against its state at the closest commit to the port date.

Step A2: Detect New and Deleted Files

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

Parse output: A (new), D (deleted), M (modified, already in A1), R (renamed -- track both paths).

Step A3: Classify Changes

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

| Classification | Examples | Action | |---------------|----------|--------| | Structural | Frontmatter changes, new/removed sections, tool list changes, new/removed AskUserQuestion blocks | Re-run conversion logic | | Content | Prompt text modifications, instruction wording, reference path changes, code/table content | Targeted text transformation | | Cosmetic | Whitespace, formatting, comment text, markdown styling changes | Auto-apply without prompting |

Build SOURCE_CHANGES list. Each entry: file_path, change_type (modified/added/deleted/renamed), classification (structural/content/cosmetic), diff_summary, diff_lines_added, diff_lines_removed, affected_sections, and component_entry (matching PORT-METADATA component, or null for new files).

New files get classification: "structural" and diff_summary: "New component -- requires full port". Deleted files get classification: "structural" and diff_summary: "Source component deleted -- ported version may be orphaned".

Track B: Platform Changes

Skip this track if SOURCE_ONLY is 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

1. Spawn the researcher agent:

``yaml 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} ``

1. 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:

| Type | Fields | Default Impact | |------|--------|----------------| | stale | adapter_section, old_mapping, new_mapping, affected_components | breaking or cosmetic | | missing | adapter_section, feature_description, potential_benefit | additive | | removed | adapter_section, feature_description, alternative, affected_components | breaking |

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 list from the classified findings.

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 with two sub-lists: selected_source_changes and 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 where 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 where change_type == "modified" and classification is "structural" or "content":

2a: Load Conversion Context

1. Read the current source file:

`` Read: {source_change.file_path} ``

1. Read the current ported target file:

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

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

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

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sequenzia
• Source: sequenzia/agent-alchemy
• License: MIT
• Homepage: https://sequenzia.github.io/agent-alchemy

Install and usage instructions live in the source repository linked above.