validate-adapter

What this skill does

# Validate Adapter

Validate an adapter file against live platform documentation to detect stale mappings, missing features, and outdated version information. Optionally apply updates in-place when the `--update` flag is provided.

**CRITICAL: Complete ALL 4 phases.** The workflow is not complete until Phase 4: Report & Apply 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.

- Summary and confirmation -> AskUserQuestion
- Report presentation -> AskUserQuestion
- Action selection -> AskUserQuestion
- Removal decisions -> AskUserQuestion

Text output should only be used for:
- Displaying progress updates between phases
- Presenting intermediate analysis results
- Explaining context or classification reasoning

If you need the user to make a choice or provide input, use AskUserQuestion.

**NEVER do this** (asking via text output):
```
Would you like to apply updates or export the report?
1. Apply updates
2. Export report
3. View details
```

**ALWAYS do this** (using AskUserQuestion tool):
```yaml
AskUserQuestion:
  questions:
    - header: "Validation Complete"
      question: "How would you like to proceed?"
      options:
        - label: "View detailed findings"
          description: "Show full per-entry breakdown grouped by classification"
        - label: "Apply updates"
          description: "Update stale/missing entries in the adapter file"
        - label: "Export report"
          description: "Write validation report as a markdown file"
      multiSelect: false
```

### Composability

This skill can be invoked standalone via `/validate-adapter` or loaded as a sub-workflow by other skills (e.g., `update-ported-plugin`). When loaded as a sub-workflow:

- The caller may only need Phases 1-3 (the analysis) and not Phase 4 (the interactive report)
- If the caller has already set `SKIP_REPORT = true` in context, stop after Phase 3 and return the validation report data structure to the caller
- If no `SKIP_REPORT` flag is present, execute all 4 phases (standalone behavior)

### Plan Mode Behavior

**CRITICAL**: This skill performs an interactive validation workflow, NOT an implementation plan. When invoked during Claude Code's plan mode:

- **DO NOT** create an implementation plan for how to build the validation feature
- **DO NOT** defer validation to an "execution phase"
- **DO** proceed with the full validation workflow immediately
- **DO** write updated adapter files or reports as normal

## Phase Overview

Execute these phases in order, completing ALL of them:

1. **Load & Parse** - Parse arguments, read adapter format spec and adapter file
2. **Platform Research** - Spawn researcher agent to investigate current platform state
3. **Compare & Analyze** - Compare adapter sections against research findings
4. **Report & Apply** - Present findings and optionally update the adapter

---

## Phase 1: Load & Parse

**Goal:** Parse arguments, load the adapter format specification, read the target adapter file, and extract its current state.

### Step 1: Parse Arguments

Parse `$ARGUMENTS` for:
- `--target <platform>` -- Target platform slug (default: `opencode`)
- `--update` -- Enable in-place update mode (default: `false`)

Set `TARGET_PLATFORM` from `--target` value (default: `opencode`).
Set `UPDATE_MODE` from `--update` flag (default: `false`).

### Step 2: Load Adapter Format Specification

Read the adapter format reference to understand the expected 9-section structure:
```
Read: ${CLAUDE_PLUGIN_ROOT}/references/adapter-format.md
```

Record the 9 required/optional sections:
1. Platform Metadata
2. Directory Structure
3. Tool Name Mappings
4. Model Tier Mappings
5. Frontmatter Translations
6. Hook/Lifecycle Event Mappings
7. Composition Mechanism
8. Path Resolution
9. Adapter Version

### Step 3: Load Adapter File

Read the adapter file for the target platform:
```
Read: ${CLAUDE_PLUGIN_ROOT}/references/adapters/${TARGET_PLATFORM}.md
```

**Error handling -- adapter not found:**

If the adapter file does not exist:
1. Use Glob to list available adapters:
   ```
   Glob: ${CLAUDE_PLUGIN_ROOT}/references/adapters/*.md
   ```
2. Present available options:
   ```yaml
   AskUserQuestion:
     questions:
       - header: "Adapter Not Found"
         question: "No adapter found for '${TARGET_PLATFORM}'. Which adapter would you like to validate?"
         options:
           - label: "{adapter-1}"
             description: "Adapter file: {adapter-1}.md"
           - label: "{adapter-2}"
             description: "Adapter file: {adapter-2}.md"
         multiSelect: false
   ```
3. If no adapters exist at all, inform the user and exit:
   ```
   ERROR: No adapter files found in ${CLAUDE_PLUGIN_ROOT}/references/adapters/.
   Create an adapter first using /port-plugin or manually following the adapter format spec.
   ```

### Step 4: Parse Adapter Sections

Parse all 9 sections from the adapter file by matching H2 (`##`) headers against the section names defined in the adapter format specification.

For each section found:
- Record section name, start line, end line, and raw content
- Count the number of table rows / list entries / code block entries (these are the "entries" for classification)

For each expected section NOT found:
- Record it as missing from the adapter

### Step 5: Extract Metadata

From the **Adapter Version** section (Section 9), extract:
- `adapter_version` -- semver version of this adapter file
- `target_platform_version` -- version of the platform the adapter was written for
- `last_updated` -- ISO 8601 date of last review/update

If any of these fields are missing, record them as `unknown`.

### Step 6: Present Summary and Confirm

```yaml
AskUserQuestion:
  questions:
    - header: "Adapter Validation Summary"
      question: |
        Adapter loaded for validation:

        | Field | Value |
        |-------|-------|
        | Platform | ${TARGET_PLATFORM} |
        | Adapter Version | ${adapter_version} |
        | Target Platform Version | ${target_platform_version} |
        | Last Updated | ${last_updated} |
        | Sections Found | ${found_count} / 9 |
        | Update Mode | ${UPDATE_MODE ? 'Enabled' : 'Disabled'} |

        Proceed with platform research?
      options:
        - label: "Proceed"
          description: "Spawn researcher agent to investigate current platform state"
        - label: "Cancel"
          description: "Cancel validation"
      multiSelect: false
```

If the user selects "Cancel", exit the workflow.

---

## Phase 2: Platform Research

**Goal:** Spawn the researcher agent to gather current platform documentation and compare against the adapter.

### Step 1: Spawn Researcher Agent

Spawn the researcher agent using the Task tool with `subagent_type: "agent-alchemy-plugin-tools:researcher"`:

```
Task tool prompt:
"Research the current state of the plugin/extension system for: ${TARGET_PLATFORM}

You are validating an existing adapter file for this platform. The adapter was last updated on ${last_updated} and targets platform version ${target_platform_version}.

Focus your research on:
1. The current version of ${TARGET_PLATFORM} and any version changes since ${target_platform_version}
2. Plugin system changes, new features, or API modifications since the adapter was written
3. Deprecated or removed features that the adapter may still reference
4. New capabilities or configuration options not present in the adapter

The adapter file is located at: ${CLAUDE_PLUGIN_ROOT}/references/adapters/${TARGET_PLATFORM}.md

Read the adapter file and perform your Phase 4: Adapter Comparison against your research findings. Pay special attention to:
- Tool name changes or new tools added to the platform
- Directory structure changes
- Configuration format chang