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 <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, 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 <!-- PORT-METADATA ... PORT-METADATA --> block and parse the YAML-like content to extract: source_commit, port_date, adapter_version, target_platform, target_platform_version, 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