update-ported-plugin

What this skill does

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

```yaml
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:**

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

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

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

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