validate-adapter

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

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

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

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

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 change