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 -- 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 changes
- Model/provider changes
- Hook/lifecycle system changes
- Composition mechanism changes

Return a structured platform profile with your Adapter Comparison section fully populated."

Retry logic: If the Task tool call fails (agent error, timeout, or empty response), retry once automatically. If the retry also fails, proceed to research failure handling in Step 3.

Step 2: Process Research Findings

When the researcher agent returns its platform profile:

1. Store the full response as RESEARCH_FINDINGS
2. Extract key data points:

• research_platform_version -- current platform version found by research
• documentation_quality -- excellent/good/fair/poor/none
• overall_confidence -- high/medium/low
• sources_consulted -- count and list of sources
• stale_mappings -- list from the Adapter Comparison section
• missing_mappings -- list from the Adapter Comparison section

1. Display brief research summary as a progress update (text output, not AskUserQuestion):

``` Research complete:

• Documentation quality: ${documentation_quality}
• Overall confidence: ${overall_confidence}
• Sources consulted: ${sourcescount} (${officialcount} official, ${community_count} community)
• Platform version found: ${researchplatformversion} (adapter targets: ${targetplatformversion})

```

Step 3: Handle Research Failure

If the researcher agent fails or returns empty results:

1. Inform the user of the failure
2. Offer options:

```yaml AskUserQuestion: questions:

• header: "Research Failed"

question: "The researcher agent could not gather platform documentation. How would you like to proceed?" options:

• label: "Retry research"

description: "Spawn the researcher agent again"

• label: "Manual validation"

description: "Skip research; validate adapter structure only (no staleness detection)"

• label: "Cancel"

description: "Cancel the validation workflow" multiSelect: false ```

1. If "Retry research": go back to Step 1
2. If "Manual validation": proceed to Phase 3 with empty research findings (all entries will be classified as "Uncertain")
3. If "Cancel": exit the workflow

---

Phase 3: Compare & Analyze

Goal: Compare each adapter section against research findings and classify every entry.

Step 1: Section-by-Section Comparison

For each of the 9 adapter sections, compare the adapter content against the research findings.

Special handling for low-confidence research: If the researcher reported overall_confidence: low for an entire topic area, or if the Adapter Comparison section has no data for a given adapter section, mark the entire section as Uncertain rather than making unreliable per-entry classifications.

Step 2: Classify Entries

For each mapping/entry in each adapter section, classify it as one of:

| Classification | Meaning | Criteria | |---------------|---------|----------| | Current | Matches research findings | Adapter value aligns with what research found; no changes needed | | Stale | Outdated information | Research has newer/different data for this entry; adapter needs updating | | Missing | Not in adapter | Platform has features/capabilities that the adapter does not cover | | Removed | No longer supported | Adapter references features the platform has deprecated or removed | | Uncertain | Cannot determine | Research confidence is low; unable to reliably classify this entry |

Classification rules by section:

Platform Metadata:

• Compare documentation_url, repository_url, plugin_docs_url against research-discovered URLs
• Check if notes still accurately describe the platform status
• Flag URL changes as Stale; flag removed URLs as Removed

Directory Structure:

• Compare plugin_root, skill_dir, agent_dir, etc. against research-discovered paths
• Flag changed paths as Stale; flag new directories as Missing

Tool Name Mappings:

• Compare each tool mapping against research tool equivalents
• Flag renamed tools as Stale; flag new platform tools as Missing; flag removed tools as Removed

Model Tier Mappings:

• Compare model identifiers against research-discovered models
• Flag renamed or updated model identifiers as Stale; flag new tiers as Missing

Frontmatter Translations:

• Compare field mappings against research-discovered config format
• Flag changed field names as Stale; flag new fields as Missing

Hook/Lifecycle Event Mappings:

• Compare event mappings against research-discovered lifecycle events
• Flag new events as Missing; flag removed events as Removed

Composition Mechanism:

• Compare mechanism, syntax, and capabilities against research findings
• Flag changed behavior as Stale

Path Resolution:

• Compare resolution strategy and patterns against research findings
• Flag changed patterns as Stale

Adapter Version:

• Compare target_platform_version against research_platform_version
• If versions differ, classify as Stale
• Check last_updated age -- if older than 6 months, add a note

Step 3: Build Validation Report

Construct the validation report with the following structure:

Per-section breakdown:

| Section | Total Entries | Current | Stale | Missing | Removed | Uncertain |
|---------|--------------|---------|-------|---------|---------|-----------|
| Platform Metadata | N | N | N | N | N | N |
| Directory Structure | N | N | N | N | N | N |
| Tool Name Mappings | N | N | N | N | N | N |
| ... | ... | ... | ... | ... | ... | ... |
| **Totals** | **N** | **N** | **N** | **N** | **N** | **N** |

Overall health score:

Health Score = (Current entries / Total classified entries) * 100

Exclude Uncertain entries from the denominator (they neither help nor hurt the score). If all entries are Uncertain, report the health score as "N/A -- insufficient research data".

Stale entries detail list:

| Section | Entry | Current Value | Suggested Value | Source |
|---------|-------|--------------|-----------------|--------|
| {section} | {entry name} | {adapter value} | {research value} | {source URL or description} |

Missing entries detail list:

| Section | Feature | Description | Suggested Mapping |
|---------|---------|-------------|-------------------|
| {section} | {feature name} | {research description} | {suggested adapter value} |

Removed entries detail list:

| Section | Entry | Adapter Value | Evidence |
|---------|-------|--------------|----------|
| {section} | {entry name} | {current adapter value} | {evidence of removal from research} |

Store the complete report as VALIDATION_REPORT.

If SKIP_REPORT = true (sub-workflow mode), return VALIDATION_REPORT to the caller and stop here. Do not proceed to Phase 4.

---

Phase 4: Report & Apply

Goal: Present the validation report to the user and optionally apply updates.

Step 1: Present Validation Report

Determine the health indicator based on the health score:

• 90-100%: "Healthy"
• 70-89%: "Needs Attention"
• 50-69%: "Outdated"
• 0-49%: "Critically Outdated"
• N/A: "Insufficient Data"

Build the action options based on context:

• Always include "View detailed findings" and "Export report"
• Include "Apply updates" only if UPDATE_MODE = true AND there are stale/missing/removed entries
• If UPDATE_MODE = false and there are findings, include a note that --update flag enables in-place updates

AskUserQuestion:
  questions:
    - header: "Adapter Validation Report"
      question: |
        ## ${TARGET_PLATFORM} Adapter -- ${health_indicator}

        **Health Score: ${health_score}%**

        | Metric | Count |
        |--------|-------|
        | Current | ${current_count} |
        | Stale | ${stale_count} |
        | Missing | ${missing_count} |
        | Removed | ${removed_count} |
        | Uncertain | ${uncertain_count} |

…

## Source & license

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

- **Author:** [sequenzia](https://github.com/sequenzia)
- **Source:** [sequenzia/agent-alchemy](https://github.com/sequenzia/agent-alchemy)
- **License:** MIT
- **Homepage:** https://sequenzia.github.io/agent-alchemy

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