sequenzia avatar

agent-alchemy-plugin-tools

Agent Alchemy Plugin Tools — plugin lifecycle tools for AI agents

version
0.2.6
GitHub stars
45

Install

/plugin install agent-alchemy-plugin-tools@agent-alchemy

Run it inside Claude Code after adding the marketplace with /plugin marketplace add sequenzia/agent-alchemy.

Contents

Discovered from source

Skills 6

Bump Plugin Version

Automate version bumps across the Agent Alchemy ecosystem. Scans 5 version locations per plugin, detects drift, applies consistent updates, adds a CHANGELOG entry, and creates a conventional commit.

CRITICAL: Complete ALL 6 phases. The workflow is not complete until Phase 6: Commit 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.

  • Plugin selection -> AskUserQuestion
  • Bump level selection -> AskUserQuestion
  • Drift resolution -> AskUserQuestion
  • Confirmation prompts -> AskUserQuestion

Text output should only be used for:

  • Displaying progress updates between phases
  • Presenting inventory tables and drift reports
  • Phase transition markers

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

NEVER do this (asking via text output):

Which plugins would you like to bump?
1. core-tools
2. dev-tools

ALWAYS do this (using AskUserQuestion tool):

AskUserQuestion:
  questions:
    - header: "Plugins"
      question: "Which plugins would you like to bump?"
      options:
        - label: "core-tools (0.1.1)"
          description: "Current version: 0.1.1"
        - label: "dev-tools (0.1.1)"
          description: "Current version: 0.1.1"
      multiSelect: true

Plan Mode Behavior

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

  • DO NOT create an implementation plan for how to build the bumper
  • DO NOT defer the version bump to an "execution phase"
  • DO proceed with the full workflow immediately
  • DO make file edits as normal

Phase Overview

Execute these phases in order, completing ALL of them:

  1. Discovery — Read marketplace.json, build plugin inventory with current versions
  2. Drift Check — Scan all 5 version locations for inconsistencies
  3. Selection — Choose plugins and bump level, compute new versions
  4. Bump — Edit all 5 version locations per plugin
  5. Changelog — Add entries under ## [Unreleased] in CHANGELOG.md
  6. Commit — Stage modified files and create a conventional commit

Phase 1: Discovery

Goal: Read the marketplace registry and build a complete plugin inventory.

Step 1: Parse Arguments

Parse $ARGUMENTS for:

  • --plugin <group,...> — Comma-separated list of plugin groups to bump (e.g., --plugin core-tools,dev-tools). Default: prompt for selection in Phase 3.
  • --level patch|minor|major — Bump level. Default: prompt for selection in Phase 3.
  • --dry-run — Show what would change without modifying files. Default: false.

Set variables:

  • PLUGIN_FILTER from --plugin value (default: null = prompt in Phase 3)
  • BUMP_LEVEL from --level value (default: null = prompt in Phase 3)
  • DRY_RUN from --dry-run flag (default: false)

Step 2: Load Marketplace Registry

Read the marketplace registry:

Read: ${CLAUDE_PLUGIN_ROOT}/../../.claude-plugin/marketplace.json

Build a plugin map from the plugins array:

{
  group_name -> {
    marketplace_name: "agent-alchemy-{group}",
    version: "x.y.z",
    source_dir: "{group}"
  }
}

The group_name is derived from the source field by stripping the leading ./.

Step 3: Display Inventory

Display the current plugin inventory:

[Phase 1/6] Plugin Inventory

| Plugin | Marketplace Name | Current Version |
|--------|-----------------|-----------------|
| core-tools | agent-alchemy-core-tools | 0.1.1 |
| dev-tools | agent-alchemy-dev-tools | 0.1.1 |
| sdd-tools | agent-alchemy-sdd-tools | 0.1.2 |
| tdd-tools | agent-alchemy-tdd-tools | 0.1.0 |
| git-tools | agent-alchemy-git-tools | 0.1.0 |
| plugin-tools | agent-alchemy-plugin-tools | 0.1.0 |

Phase 2: Drift Check

Goal: Scan all 5 version locations and detect inconsistencies against marketplace.json (the source of truth).

Version Locations

For each plugin, versions appear in up to 5 locations:

#FileDescription
1claude/.claude-plugin/marketplace.jsonSource of truth — JSON "version" field
2CLAUDE.md (root)Plugin Inventory table — | {group} | ... | {version} |
3docs/index.mdProject Status table — | {Display Name} | {version} | {status} |
4docs/plugins/index.mdAt a Glance table — | [{Name}](...) | ... | {version} |
5docs/plugins/{group}.mdPer-plugin doc file — format varies (see Per-Plugin Formats below)

Per-Plugin Doc Formats (Location 5)

Each plugin doc uses a different version format. When scanning, look within the first 15 lines:

PluginFormatExample
core-toolsParenthetical in prose + vertical tableCore Tools (v0.1.1) provides... and | **Version** | 0.1.1 |
dev-toolsBold metadata line**Version:** 0.1.1 | **Skills:** ...
sdd-toolsBold metadata with plugin name**Plugin:** ... | **Version:** 0.1.2 | ...
tdd-toolsBacktick-wrapped parenthetical(`v0.1.0`) in prose
git-toolsBold metadata line**Version:** 0.1.0 | **Skills:** ...
plugin-toolsBold metadata with plugin name**Plugin:** ... | **Version:** 0.1.0 | ...

Step 1: Scan All Locations

For each plugin in the inventory:

  1. Location 2 (CLAUDE.md): Read the Plugin Inventory table. Find the row matching the plugin group name. Extract the version from the last column.

  2. Location 3 (docs/index.md): Read the Project Status table. Find the row matching the plugin's display name. Extract the version. Note: not all plugins may be listed here — skip silently if absent.

  3. Location 4 (docs/plugins/index.md): Read the At a Glance table. Find the row matching the plugin name. Extract the version from the Version column.

  4. Location 5 (docs/plugins/{group}.md): Read the first 15 lines. Search for the version string using the format described in Per-Plugin Formats above.

Compare each found version against the marketplace.json version (Location 1). Record any mismatches.

Step 2: Present Drift Report

[Phase 2/6] Version Drift Check

✓ No drift detected — all locations consistent.

Or if drift is found:

[Phase 2/6] Version Drift Check

| Plugin | Location | Expected | Found |
|--------|----------|----------|-------|
| core-tools | docs/plugins/core-tools.md | 0.1.1 | 0.1.0 |
| dev-tools | CLAUDE.md | 0.1.1 | 0.1.0 |

Step 3: Resolve Drift (if any)

If drift was detected, present resolution options via AskUserQuestion:

AskUserQuestion:
  questions:
    - header: "Drift"
      question: "Version drift detected in N locations. How should we proceed?"
      options:
        - label: "Fix drift first"
          description: "Update drifted locations to match marketplace.json before bumping"
        - label: "Ignore and bump"
          description: "Proceed with version bump — drifted locations will be overwritten with new version"
        - label: "Abort"
          description: "Stop the workflow to investigate manually"
      multiSelect: false

If Fix drift first: Use Edit to update each drifted location to match marketplace.json, then continue to Phase 3.

If Ignore and bump: Continue to Phase 3. The bump will overwrite with the new version anyway.

If Abort: Display the drift details and exit.


Phase 3: Selection

Goal: Determine which plugins to bump and the bump level. Compute new versions.

Step 1: Select Plugins

If PLUGIN_FILTER was provided via --plugin, use those plugins. Validate each against the inventory — warn and skip any that don't exist.

Otherwise, present a multi-select via AskUserQuestion listing all plugins with their current versions. The options should include each plugin as a selectable item.

Step 2: Select Bump Level

If BUMP_LEVEL was provided via --level, use it.

Otherwise, ask via AskUserQuestion:

AskUserQuestion:
  questions:
    - header: "Bump Level"
      question: "What type of version bump?"
      options:
        - label: "Patch (x.y.Z)"
          description: "Bug fixes, minor updates — most common for skill changes"
        - label: "Minor (x.Y.0)"
          description: "New features, new skills or agents"
        - label: "Major (X.0.0)"
          description: "Breaking changes to skill interfaces or agent contracts"
      multiSelect: false

Step 3: Compute New Versions

For each selected plugin, compute the new version by applying the bump level:

  • patch: Increment the third segment (0.1.1 → 0.1.2)
  • minor: Increment the second segment, reset third to 0 (0.1.1 → 0.2.0)
  • major: Increment the first segment, reset second and third to 0 (0.1.1 → 1.0.0)

Step 4: Display Bump Plan

[Phase 3/6] Bump Plan

| Plugin | Current | New | Level |
|--------|---------|-----|-------|
| core-tools | 0.1.1 | 0.1.2 | patch |
| dev-tools | 0.1.1 | 0.1.2 | patch |

If DRY_RUN is true:

[Dry Run] No files will be modified. Showing what would change:

Files that would be edited:
- claude/.claude-plugin/marketplace.json (2 entries)
- CLAUDE.md (2 rows in Plugin Inventory)
- docs/index.md (2 rows in Project Status — if present)
- docs/plugins/index.md (2 rows in At a Glance)
- docs/plugins/core-tools.md (2 version occurrences)
- docs/plugins/dev-tools.md (1 version occurrence)
- CHANGELOG.md (1 new entry)

Dry run complete.

Then stop — do NOT proceed to Phase 4.


Phase 4: Bump

Goal: Edit all 5 version locations for each selected plugin.

CRITICAL: Track every file modified in a MODIFIED_FILES list for Phase 6 staging.

Location 1: marketplace.json

Read claude/.claude-plugin/marketplace.json. For each selected plugin, use Edit to replace the old version string with the new one. Target the specific "version": "old_version" line within that plugin's entry block.

Location 2: CLAUDE.md (Plugin Inventory Table)

Read the Plugin Inventory table in the root CLAUDE.md. For each selected plugin, find the row matching the group name and use Edit to replace the old version with the new version in that row. Use enough surrounding context to ensure a unique match.

Location 3: docs/index.md (Project Status Table)

Read the Project Status table in docs/index.md. For each selected plugin, find the row matching the plugin's display name. Use Edit to replace the old version with the new one.

Note: Not all plugins appear in this table. If a plugin is not found, skip silently — do not abort or warn.

Location 4: docs/plugins/index.md (At a Glance Table)

Read the At a Glance table in docs/plugins/index.md. For each selected plugin, find the row and use Edit to replace the old version with the new one.

Location 5: Per-Plugin Doc Files

For each selected plugin, read the first 15 lines of docs/plugins/{group}.md and update version occurrences using the format-specific patterns:

core-tools — Two occurrences:

  1. Parenthetical: (v{old}) → (v{new}) in the prose paragraph
  2. Vertical table: | **Version** | {old} | → | **Version** | {new} |

dev-tools — One occurrence:

  1. Bold metadata: **Version:** {old} → **Version:** {new}

sdd-tools — One occurrence:

  1. Bold metadata: **Version:** {old} → **Version:** {new}

tdd-tools — One occurrence:

  1. Backtick parenthetical: (`v{old}`) → (`v{new}`)

git-tools — One occurrence:

  1. Bold metadata: **Version:** {old} → **Version:** {new}

plugin-tools — One occurrence:

  1. Bold metadata: **Version:** {old} → **Version:** {new}

Strategy for Each Edit

  1. Read the file (or use already-read content)
  2. Search for the old version string in the expected location/format
  3. Use Edit with enough surrounding context for a unique match
  4. If the pattern is not found, warn and skip — do not abort the entire workflow
  5. Add the file path to MODIFIED_FILES

Display Progress

After completing all edits:

[Phase 4/6] Version Bump Complete

Updated N files across N plugins:
- claude/.claude-plugin/marketplace.json ✓
- CLAUDE.md ✓
- docs/index.md ✓ (N of N plugins found)
- docs/plugins/index.md ✓
- docs/plugins/core-tools.md ✓ (2 occurrences)
- docs/plugins/dev-tools.md ✓ (1 occurrence)

If any locations were skipped:

Skipped:
- docs/index.md: plugin-tools not found in table (OK — not listed)

Phase 5: Changelog

Goal: Add version bump entries under ## [Unreleased] in CHANGELOG.md.

Step 1: Read CHANGELOG.md

Read CHANGELOG.md from the repository root. Find the ## [Unreleased] section.

Step 2: Build Entry

Group bumped plugins by version transition for concise entries. For example, if core-tools and dev-tools both went from 0.1.1 to 0.1.2:

### Changed

- Bump core-tools and dev-tools from 0.1.1 to 0.1.2

If plugins had different starting versions:

### Changed

- Bump core-tools and dev-tools from 0.1.1 to 0.1.2
- Bump sdd-tools from 0.1.2 to 0.1.3

Step 3: Insert Entry

Use Edit to insert the changelog entry immediately after the ## [Unreleased] line. If there is already content under [Unreleased], add the new entry after any existing entries (before the next ## [x.y.z] heading or end of section). If a ### Changed section already exists under [Unreleased], append to it rather than creating a duplicate.

Add CHANGELOG.md to MODIFIED_FILES.

Display Progress

[Phase 5/6] Changelog Updated

Added entry under [Unreleased]:
  - Bump core-tools and dev-tools from 0.1.1 to 0.1.2

Phase 6: Commit

Goal: Stage all modified files and create a conventional commit.

Step 1: Stage Files

Stage each file in MODIFIED_FILES individually using git add:

git add claude/.claude-plugin/marketplace.json
git add CLAUDE.md
git add docs/index.md
git add docs/plugins/index.md
git add docs/plugins/core-tools.md
git add docs/plugins/dev-tools.md
git add CHANGELOG.md

CRITICAL: Do NOT use git add -A or git add .. Only stage files that were actually modified by this skill.

Step 2: Create Commit

Build the commit message:

Single plugin:

chore(marketplace): bump {group} to {new_version}

Multiple plugins, same new version:

chore(marketplace): bump {group1}, {group2} to {new_version}

Multiple plugins, different new versions:

chore(marketplace): bump {group1} to {v1}, {group2} to {v2}

Create the commit:

git commit -m "$(cat <<'EOF'
chore(marketplace): bump core-tools, dev-tools to 0.1.2
EOF
)"

Step 3: Verify and Report

Run git status to verify the commit succeeded.

[Phase 6/6] Committed

chore(marketplace): bump core-tools, dev-tools to 0.1.2

Staged files: N
Commit: {short_hash}

If the commit fails (e.g., pre-commit hook):

  1. Display the error output
  2. Do NOT use --amend or --no-verify
  3. Suggest the user fix the issue and run /git-commit manually

Error Handling

Missing Doc Files

If a docs/plugins/{group}.md file doesn't exist for a selected plugin, warn and skip:

Warning: docs/plugins/{group}.md not found — skipping Location 5 for {group}

Unmatched Version Patterns

If a version string can't be found at an expected location:

Warning: Could not find version {old} in {file} at expected location — skipping

Continue with other locations. Do not abort.

Plugin Not in Docs Table

If a plugin doesn't appear in docs/index.md or docs/plugins/index.md tables, skip silently. These tables may not list all plugins.

Git Commit Failure

If git commit fails:

  1. Report the full error output
  2. Do NOT use --amend (would modify the previous commit)
  3. Do NOT use --no-verify (would skip hooks)
  4. Suggest manual resolution

No Plugins Selected

If the user selects no plugins in Phase 3, display a message and exit:

No plugins selected. Exiting.

Invalid Bump Level

If --level has an unrecognized value, warn and prompt via AskUserQuestion.

Dependency Checker

Analyze the Agent Alchemy plugin ecosystem to detect dependency issues, broken paths, orphaned components, and documentation drift. Produces a health report with severity-ranked findings.

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

  • Report presentation -> AskUserQuestion
  • Action selection -> AskUserQuestion
  • View mode selection -> AskUserQuestion

Text output should only be used for:

  • Displaying progress updates between phases
  • Presenting intermediate analysis summaries (inventory counts, graph stats)
  • Phase transition markers

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 view findings by severity or by plugin group?
1. By severity
2. By plugin group

ALWAYS do this (using AskUserQuestion tool):

AskUserQuestion:
  questions:
    - header: "View Mode"
      question: "How would you like to view the findings?"
      options:
        - label: "By severity"
          description: "Group findings from critical to low"
        - label: "By plugin group"
          description: "Filter findings to a specific plugin group"
      multiSelect: false

Plan Mode Behavior

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

  • DO NOT create an implementation plan for how to build the analysis
  • DO NOT defer analysis to an "execution phase"
  • DO proceed with the full analysis workflow immediately
  • DO write report files as normal if --report-file is specified

Phase Overview

Execute these phases in order, completing ALL of them:

  1. Load & Discover — Parse arguments, load settings, build component inventory
  2. Build Dependency Graph — Parse every component file to extract dependency edges
  3. Analyze — Run 7 detection passes over the dependency graph
  4. Cross-Reference Documentation — Compare graph against CLAUDE.md/README docs for drift
  5. Report — Present findings interactively; optionally export

Phase 1: Load & Discover

Goal: Parse arguments, load settings, build a complete component inventory of the plugin ecosystem.

Step 1: Parse Arguments

Parse $ARGUMENTS for:

  • --plugin <group> — Filter to one plugin group by short directory name (e.g., core-tools). Default: analyze all groups.
  • --verbose — Include healthy/passing entries in the report, not just issues. Default: false.
  • --report-file <path> — Export the full report as a markdown file to the given path. Default: none (interactive only).

Set variables:

  • FILTER_GROUP from --plugin value (default: null = all groups)
  • VERBOSE_MODE from --verbose flag (default: false)
  • REPORT_FILE from --report-file value (default: null)

Step 2: Load Settings

Read settings from .claude/agent-alchemy.local.md if it exists. Look for the plugin-tools.dependency-checker section in the YAML frontmatter.

SettingDefaultDescription
severity-thresholdlowMinimum severity to show: critical, high, medium, low
check-docs-drifttrueWhether to run Phase 4 documentation cross-referencing
line-count-tolerance10Percentage tolerance for line count drift in CLAUDE.md tables

If the settings file doesn't exist or the section is missing, use defaults.

Step 3: Load Marketplace Registry

Read the marketplace registry:

Read: ${CLAUDE_PLUGIN_ROOT}/../../.claude-plugin/marketplace.json

Build a registry map: { plugin_name -> { version, source_dir, description } } for each entry in the plugins array. The source_dir is derived from the source field (strip leading ./).

Step 4: Discover Components

For each plugin group directory under claude/ (or only FILTER_GROUP if set), enumerate all components using Glob:

Skills:

Glob: claude/{group}/skills/*/SKILL.md

For each found skill, read its YAML frontmatter to extract:

  • name, description, user-invocable, disable-model-invocation
  • allowed-tools list
  • skills list (if present — for agent-like skill composition)

Agents:

Glob: claude/{group}/agents/*.md

For each found agent, read its YAML frontmatter to extract:

  • name, description, model
  • tools list
  • skills list (these are skill bindings that must resolve to real skills)

Shared references (plugin-level):

Glob: claude/{group}/references/**/*.md

Skill-local references:

Glob: claude/{group}/skills/*/references/**/*.md

Hooks:

Glob: claude/{group}/hooks/hooks.json

If found, read and parse the JSON to extract hook entries.

Hook scripts:

Glob: claude/{group}/hooks/*.sh

Step 5: Display Inventory Summary

Display a text summary of what was discovered:

[Phase 1/5] Plugin Ecosystem Inventory

| Group | Skills | Agents | Shared Refs | Skill Refs | Hooks | Scripts |
|-------|--------|--------|-------------|------------|-------|---------|
| core-tools | N | N | N | N | N | N |
| dev-tools | N | N | N | N | N | N |
| ... | ... | ... | ... | ... | ... | ... |
| **Total** | **N** | **N** | **N** | **N** | **N** | **N** |

Phase 2: Build Dependency Graph

Goal: Parse every component file to extract all dependency edges, building a directed graph of the ecosystem.

Step 1: Define Edge Types

The graph has the following edge types:

Edge TypeSourceTargetPattern
skill-loads-skillSkillSkill (same plugin)${CLAUDE_PLUGIN_ROOT}/skills/{name}/SKILL.md (without /../)
skill-loads-skill-crossSkillSkill (other plugin)${CLAUDE_PLUGIN_ROOT}/../{group}/skills/{name}/SKILL.md
skill-loads-shared-refSkillShared reference${CLAUDE_PLUGIN_ROOT}/references/{path}
skill-loads-local-refSkillSkill-local reference${CLAUDE_PLUGIN_ROOT}/skills/{name}/references/{path}
skill-loads-cross-refSkillCross-plugin reference${CLAUDE_PLUGIN_ROOT}/../{group}/(skills/{name}/)?references/{path}
skill-spawns-agentSkillAgentsubagent_type references in skill body
skill-reads-registrySkillRegistry${CLAUDE_PLUGIN_ROOT}/../../.claude-plugin/ patterns
agent-binds-skillAgentSkillskills: list in YAML frontmatter
hook-runs-scriptHook configHook script${CLAUDE_PLUGIN_ROOT}/hooks/{script} in command strings

Step 2: Extract Edges from Skills

For each SKILL.md file discovered in Phase 1, scan the full file content (not just frontmatter) using these regex patterns:

Cross-plugin skill loads:

\$\{CLAUDE_PLUGIN_ROOT\}/\.\./([^/]+)/skills/([^/]+)/SKILL\.md

Creates edge: skill-loads-skill-cross from current skill to {group}:{skill_name}

Same-plugin skill loads:

\$\{CLAUDE_PLUGIN_ROOT\}/skills/([^/]+)/SKILL\.md

Match only if the path does NOT contain /../ before it. Creates edge: skill-loads-skill from current skill to {skill_name} within the same plugin.

Shared reference loads (same plugin):

\$\{CLAUDE_PLUGIN_ROOT\}/references/([^\s"'`)+]+\.md)

Creates edge: skill-loads-shared-ref

Skill-local reference loads:

\$\{CLAUDE_PLUGIN_ROOT\}/skills/([^/]+)/references/([^\s"'`)+]+\.md)

Creates edge: skill-loads-local-ref

Cross-plugin reference loads:

\$\{CLAUDE_PLUGIN_ROOT\}/\.\./([^/]+)/(skills/[^/]+/)?references/([^\s"'`)+]+\.md)

Creates edge: skill-loads-cross-ref

Agent spawning:

subagent_type[:\s]*["']?([^"'\s,}]+)

Creates edge: skill-spawns-agent from current skill to the resolved agent name.

Registry reads:

\$\{CLAUDE_PLUGIN_ROOT\}/\.\./\.\./\.claude-plugin/

Creates edge: skill-reads-registry

Step 3: Extract Edges from Agents

For each agent .md file, parse its YAML frontmatter and extract the skills: list.

Each entry in the skills: list creates an agent-binds-skill edge. The skill name must be resolved to a skill within the same plugin group as the agent (since agent frontmatter skill bindings are group-local).

Step 4: Extract Edges from Hooks

For each hooks.json file, parse the JSON and scan all command strings for script references:

\$\{CLAUDE_PLUGIN_ROOT\}/hooks/([^\s"']+)

Creates edge: hook-runs-script from the hook config to the referenced script file.

Step 5: Display Graph Summary

[Phase 2/5] Dependency Graph Built

Nodes: N total (N skills, N agents, N shared refs, N skill refs, N hooks, N scripts)
Edges: N total
  - skill-loads-skill: N (same-plugin: N, cross-plugin: N)
  - skill-loads-ref: N (shared: N, local: N, cross-plugin: N)
  - skill-spawns-agent: N
  - skill-reads-registry: N
  - agent-binds-skill: N
  - hook-runs-script: N

Phase 3: Analyze (7 Detection Passes)

Goal: Run 7 detection passes over the dependency graph to find issues. Each pass produces findings with a severity level.

Filter findings by severity-threshold setting — only retain findings at or above the configured threshold.

Pass 1: Circular Dependencies (Critical)

Run DFS cycle detection on the skill-loads-skill and skill-loads-skill-cross edges (the skill-to-skill subgraph).

Algorithm:

  1. For each skill node, perform DFS tracking the visit stack
  2. If a node is encountered that is already in the current visit stack, a cycle is detected
  3. Record the full cycle path: skill_A -> skill_B -> ... -> skill_A

Each cycle found is a Critical severity finding.

Pass 2: Missing Dependencies (High)

For every edge in the graph, verify that the target node exists on disk:

  • skill-loads-skill / skill-loads-skill-cross: Check the target SKILL.md file exists
  • skill-loads-shared-ref / skill-loads-local-ref / skill-loads-cross-ref: Check the target .md file exists
  • skill-spawns-agent: Resolve the agent name to a file. Agent names may be:
    • Bare names (e.g., "code-explorer") — look in the same plugin group's agents/ directory
    • Qualified names (e.g., "agent-alchemy-core-tools:code-explorer") — map marketplace name to source dir, then look in that group's agents/
  • agent-binds-skill: Check the skill exists in the same plugin group's skills/ directory
  • hook-runs-script: Check the script file exists

Each missing target is a High severity finding. Include the source file, expected target path, and edge type.

Pass 3: Broken Cross-Plugin Paths (Medium)

Scan all SKILL.md and agent .md files for path anti-patterns:

Anti-pattern 1 — Marketplace name in path:

agent-alchemy-[a-z-]+/

Paths should use short directory names (e.g., core-tools), not marketplace names (e.g., agent-alchemy-core-tools).

Anti-pattern 2 — Hardcoded absolute paths:

/Users/|/home/|/tmp/.*claude/

Paths should use ${CLAUDE_PLUGIN_ROOT} variable, not absolute paths.

Anti-pattern 3 — Incorrect nesting depth:

\$\{CLAUDE_PLUGIN_ROOT\}/\.\./\.\./\.\./

Triple ../ or deeper should not appear (maximum is ../../ for registry access).

Each finding is Medium severity.

Pass 4: Orphaned Components (Low)

Find components with zero inbound edges (nothing references them):

  • Skills: Only flag non-user-invocable skills with zero inbound edges. User-invocable skills are entry points and are expected to have no inbound edges.
  • Agents: Flag agents with zero skill-spawns-agent inbound edges (no skill spawns them) AND zero agent-binds-skill outbound edges isn't sufficient — check that nothing spawns them.
  • Shared references: Flag .md files in references/ directories with zero skill-loads-shared-ref or skill-loads-cross-ref inbound edges.
  • Skill-local references: Flag .md files in skills/*/references/ with zero skill-loads-local-ref inbound edges.
  • Hook scripts: Flag .sh files in hooks/ with zero hook-runs-script inbound edges.

Each orphaned component is a Low severity finding. Note: files in references/adapters/ subdirectories may be dynamically loaded based on arguments and should be flagged with a caveat noting they may be loaded dynamically.

Pass 5: Agent-Skill Mismatches (High)

For each agent's skills: list in its frontmatter:

  1. Unresolvable skill names: The skill name doesn't match any skill in the same plugin group. Flag as High severity with the agent name, unresolvable skill name, and a suggestion of possible matches (fuzzy).

  2. Ambiguous cross-plugin bindings: If the skill name matches skills in multiple plugin groups but no qualifier is provided, flag as High severity.

Note: Agent skills: bindings in Claude Code are resolved within the same plugin group. A skill name in an agent's skills: list refers to a skill directory name under the agent's own plugin group's skills/ directory.

Pass 6: Marketplace Consistency (Medium)

Compare the marketplace registry against actual directories:

  1. Missing registry entries: Directories under claude/ that look like plugin groups (contain skills/ or agents/ subdirectories) but have no corresponding entry in marketplace.json. Exclude .claude-plugin/ itself.

  2. Stale registry entries: Entries in marketplace.json whose source path doesn't resolve to an existing directory.

  3. Source path mismatches: Registry entry source field doesn't match the actual directory name.

Each finding is Medium severity.

Pass 7: Hook Integrity (Low)

For each hooks.json file:

  1. Invalid matcher patterns: Check that matcher values reference valid Claude Code tool names. Known valid tools include: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, AskUserQuestion, NotebookEdit, SendMessage, TodoWrite. Matchers using | for OR are valid. Flag unrecognized tool names.

  2. Missing scripts: Already covered by Pass 2 (missing dependencies), but if the script reference uses a non-standard path pattern (not ${CLAUDE_PLUGIN_ROOT}/hooks/), flag it.

  3. Timeout values: If timeout is set, verify it's a positive number. Flag zero or negative timeouts.

  4. Invalid hook types: Verify type field is a recognized value (command, prompt).

Each finding is Low severity.

Step: Display Analysis Summary

[Phase 3/5] Analysis Complete

| Pass | Check | Severity | Findings |
|------|-------|----------|----------|
| 1 | Circular dependencies | Critical | N |
| 2 | Missing dependencies | High | N |
| 3 | Broken cross-plugin paths | Medium | N |
| 4 | Orphaned components | Low | N |
| 5 | Agent-skill mismatches | High | N |
| 6 | Marketplace consistency | Medium | N |
| 7 | Hook integrity | Low | N |
| | **Total** | | **N** |

Phase 4: Cross-Reference Documentation

Goal: Compare the dependency graph against documentation files (CLAUDE.md, plugin README files) to detect drift. Skip this phase if the check-docs-drift setting is false.

If check-docs-drift is false, display:

[Phase 4/5] Documentation cross-referencing skipped (check-docs-drift: false)

Then proceed to Phase 5.

Check 1: CLAUDE.md Plugin Inventory Table

Read the root CLAUDE.md file and parse the Plugin Inventory table.

For each row in the table:

  • Skill count: Compare the comma-separated skill names in the "Skills" column against the actual skills discovered in Phase 1. Flag missing or extra skills.
  • Agent count: Compare the comma-separated agent names in the "Agents" column against actual agents. Flag missing or extra agents.
  • Version: Compare the version in the table against the version in marketplace.json. Flag mismatches.

Each drift finding is Medium severity with type docs-drift.

Check 2: CLAUDE.md Composition Chains

Read the Key Skill Composition Chains section in CLAUDE.md. For each documented chain:

  • Verify the source skill exists
  • Verify the target skill/agent exists
  • Check that the edge exists in the dependency graph (the source actually loads/spawns the target)

Flag documented chains that don't match the actual graph as Medium severity docs-drift.

Do NOT flag undocumented chains — CLAUDE.md only documents "key" chains, not all of them.

Check 3: CLAUDE.md Critical Plugin Files Table

Read the Critical Plugin Files table. For each row:

  • Verify the file exists at the listed path
  • Get the actual line count using Bash: wc -l
  • Compare against the documented line count. Apply the line-count-tolerance setting (default 10%). Flag if the actual count differs by more than the tolerance percentage.

Each finding is Low severity with type docs-drift.

Check 4: Plugin README Files

For each plugin group, read its README.md (if it exists):

  • Parse the skills table and compare listed skills against actual skills in that group
  • Parse the agents table and compare listed agents against actual agents in that group

Flag missing or extra entries as Medium severity with type docs-drift.

Display Documentation Summary

[Phase 4/5] Documentation Cross-Reference

| Source | Check | Findings |
|--------|-------|----------|
| CLAUDE.md | Plugin Inventory | N |
| CLAUDE.md | Composition Chains | N |
| CLAUDE.md | Critical Files | N |
| README files | Skill/Agent tables | N |
| **Total** | | **N** |

Phase 5: Report

Goal: Present findings interactively; optionally export as a markdown file.

Step 1: Compute Health Score

health_score = (components_without_issues / total_components) × 100

Where total_components is the count of all skills, agents, references, and scripts discovered in Phase 1. A component "has issues" if it appears in any finding from Phase 3 or Phase 4.

Determine health indicator:

  • 90-100%: "Healthy"
  • 70-89%: "Needs Attention"
  • 50-69%: "Outdated"
  • 0-49%: "Critical Issues"

Step 2: Auto-Export (if --report-file)

If REPORT_FILE is set, write the full report before presenting the interactive menu. The markdown report should include:

  1. Header with ecosystem name, date, health score
  2. Inventory summary table from Phase 1
  3. Dependency graph statistics from Phase 2
  4. Dependency graph diagram — Load Read ${CLAUDE_PLUGIN_ROOT}/../core-tools/skills/technical-diagrams/SKILL.md, then generate a Mermaid flowchart showing plugin groups as subgraphs and key cross-plugin dependency edges. Limit to 15-20 nodes max. Highlight nodes involved in findings using danger (critical) or warning (high) classDef styles.
  5. All findings grouped by severity (critical → low), each with:
    • Component involved
    • Issue type and description
    • Expected vs actual (where applicable)
    • Suggested fix
  6. Documentation drift findings from Phase 4 (if run)
  7. Health score and recommendation
Write: {REPORT_FILE}

Display: Report exported to: {REPORT_FILE}

Step 3: Present Interactive Report

Present the summary via AskUserQuestion:

AskUserQuestion:
  questions:
    - header: "Dependency Health Report"
      question: |
        ## Plugin Ecosystem — {health_indicator}

        **Health Score: {health_score}%** ({components_without_issues}/{total_components} components clean)

        | Severity | Count |
        |----------|-------|
        | Critical | N |
        | High | N |
        | Medium | N |
        | Low | N |

        {total_findings} findings across {groups_with_issues} plugin groups.

        How would you like to explore the results?
      options:
        - label: "View all findings"
          description: "Findings grouped by severity, from critical to low"
        - label: "View by plugin group"
          description: "Select a plugin group to see its findings"
        - label: "View dependency graph"
          description: "Text-based graph showing all dependency edges"
        - label: "Done"
          description: "Exit the dependency checker"
      multiSelect: false

Step 4: Handle User Selections

View all findings: Display all findings grouped by severity (critical first), each showing:

  • Component: The file or component involved
  • Issue: Description of the problem
  • Expected: What was expected (if applicable)
  • Actual: What was found (if applicable)
  • Fix: Suggested remediation

After displaying, loop back to the interactive menu (Step 3).

View by plugin group: Present a follow-up AskUserQuestion with the plugin groups as options. After the user selects a group, display only findings involving components in that group. Then loop back to the interactive menu.

View dependency graph: Display a text-based representation of the dependency graph:

core-tools/
  skills/
    deep-analysis
      -> spawns: code-explorer (core-tools), code-synthesizer (core-tools)
      <- loaded by: codebase-analysis (core-tools), feature-dev (dev-tools), docs-manager (dev-tools), create-spec (sdd-tools)
    codebase-analysis
      -> loads: deep-analysis (core-tools)
      -> loads ref: report-template.md, actionable-insights-template.md
  agents/
    code-explorer
      -> binds: project-conventions, language-patterns
      <- spawned by: deep-analysis
...

Also generate a Mermaid flowchart version showing plugin groups as subgraphs with color-coded finding severity (danger classDef for critical, warning for high, primary/secondary for clean nodes). Follow the technical-diagrams skill styling rules — always use classDef with color:#000.

After displaying, loop back to the interactive menu.

Done: Exit the workflow. Display a final one-line summary:

Dependency check complete. {total_findings} findings ({critical_count} critical, {high_count} high).

Error Handling

No Plugin Groups Found

If no plugin group directories are found under claude/ (or the filtered group doesn't exist):

  1. Display an error message listing what was searched
  2. If --plugin was used, suggest valid group names from the marketplace registry
  3. Exit the workflow

Marketplace Registry Missing

If marketplace.json doesn't exist or can't be parsed:

  1. Log a warning: Warning: marketplace.json not found or invalid. Skipping marketplace consistency checks (Pass 6).
  2. Continue with all other passes — the registry is only needed for Pass 6 and documentation drift checks.

Malformed Component Files

If a SKILL.md or agent .md file can't have its YAML frontmatter parsed:

  1. Log a warning for that specific file
  2. Skip edge extraction for that file
  3. Add a Medium severity finding: "Malformed frontmatter: {file_path}"
  4. Continue processing other files

Large Ecosystem Performance

The analysis reads every component file. For performance:

  • Read frontmatter-only when only frontmatter fields are needed (agents)
  • Read full file content when body scanning is needed (skills — for subagent_type and path patterns)
  • Use Glob results from Phase 1 to avoid redundant file discovery

Finding Schema

Every finding produced by Phase 3 and Phase 4 follows this structure:

{
  id: "{pass_number}.{index}",
  severity: "critical" | "high" | "medium" | "low",
  type: "circular-dep" | "missing-dep" | "broken-path" | "orphaned" |
        "agent-skill-mismatch" | "marketplace-inconsistency" |
        "hook-integrity" | "docs-drift",
  component: "{group}/{component_type}/{name}",
  message: "Human-readable description of the issue",
  expected: "What was expected (optional)",
  actual: "What was found (optional)",
  fix: "Suggested remediation"
}

Dependency Patterns Reference

These are the regex patterns used in Phase 2 for edge extraction. They are provided here as a quick reference — the authoritative patterns are in Phase 2 above.

Dependency TypeRegex Pattern
Cross-plugin skill load\$\{CLAUDE_PLUGIN_ROOT\}/\.\./([^/]+)/skills/([^/]+)/SKILL\.md
Same-plugin skill load\$\{CLAUDE_PLUGIN_ROOT\}/skills/([^/]+)/SKILL\.md (without preceding /../)
Shared reference load\$\{CLAUDE_PLUGIN_ROOT\}/references/([^\s"' )]+\.md)
Skill-local reference load\$\{CLAUDE_PLUGIN_ROOT\}/skills/([^/]+)/references/([^\s"' )]+\.md)
Cross-plugin reference\$\{CLAUDE_PLUGIN_ROOT\}/\.\./([^/]+)/(skills/[^/]+/)?references/([^\s"' )]+\.md)
Agent spawningsubagent_type[:\s]*["']?([^"'\s,}]+)
Registry read\$\{CLAUDE_PLUGIN_ROOT\}/\.\./\.\./\.claude-plugin/
Hook script\$\{CLAUDE_PLUGIN_ROOT\}/hooks/([^\s"']+)
Agent skill bindingYAML skills: list in agent frontmatter

Port Master

Extract the platform-agnostic intent from Claude Code plugins, producing clean markdown files that any agent harness developer can read and adapt. The output preserves the what and why of each skill, agent, and hook while removing implementation details tied to Claude Code.

The goal is portability through clarity — a developer familiar with any agent framework should be able to read the output and integrate it into their system without needing to understand Claude Code's internals.

Three output modes are supported:

  • Full mode (default): Produces skills, agents, and hooks — preserves the original component structure in generic format. Supports two output layouts:
    • Per-group (default): Each plugin group gets its own subdirectory with separate manifest and integration guide.
    • Unified (--unified): All groups merged into a single directory — one manifest, one integration guide, components organized by type. Cross-group dependencies become internal. Only meaningful when converting multiple groups.
  • Flatten mode (--flatten): Produces skills only — agents are converted to skills, hooks are absorbed into a lifecycle-hooks skill. Use this for agent harnesses that only support skills and not agents or hooks.
  • Nested mode (--nested): Agents become pure markdown instruction files nested within their parent skill's agents/ directory. Hooks are absorbed into a lifecycle-hooks skill. Use this for harnesses that support sub-agent delegation but use skills as the primary organizational unit.

Complete ALL 5 phases. After completing each phase, immediately proceed to the next without waiting for user prompts.

Critical Rules

AskUserQuestion is MANDATORY

Use the AskUserQuestion tool for ALL questions to the user. Never ask questions through regular text output.

  • Selection questions → AskUserQuestion
  • Confirmation questions → AskUserQuestion
  • Clarifying questions → AskUserQuestion

Text output is only for status updates, summaries, and informational context.

AskUserQuestion Option Limits

Each question in AskUserQuestion supports 2-4 options maximum (plus a built-in "Other" for free-text input). Never create questions with more than 4 options — use presets, categories, or follow-up questions to stay within limits. When users need to pick from a large set, list all available items in the question text and let users specify via "Other".

Plan Mode Behavior

This skill performs an interactive conversion workflow. When invoked during plan mode:

  • Proceed with the full wizard and conversion workflow immediately
  • Write converted files to the output directory as normal
  • Do NOT create an implementation plan or defer work to an "execution phase"

Phase Overview

  1. Configuration Wizard & Component Selection — Parse arguments, upfront wizard, load registry, interactive selection
  2. Dependency Analysis — Build dependency graph, classify dependencies, plan smart resolution
  3. Conversion — Transform each component using rules from references/conversion-rules.md
  4. Output Generation — Write files, manifest, and integration guide
  5. Summary — Present results and next steps

Phase 1: Configuration Wizard & Component Selection

Goal: Gather all configuration (plugins, output directory, output mode) upfront, then select components.

Step 1: Parse Arguments

Parse $ARGUMENTS for:

  • Plugin group name(s) — positional arguments
  • --all — Convert all plugin groups
  • --output <dir> — Output directory (default: ./ported/)
  • --flatten — Skills-only output mode (agents converted to skills, hooks absorbed)
  • --nested — Nested output mode (agents nested as pure markdown within parent skills, hooks absorbed)
  • --unified — Unified output layout (all groups merged into a single directory tree; full mode only)

If both --flatten and --nested are provided, report an error: these flags are mutually exclusive. Ask the user to choose one.

If --unified is provided together with --flatten or --nested, report an error: --unified only applies to full mode.

If --unified is provided with only one group (not --all), ignore it silently — unified and per-group produce identical output for a single group.

Step 2: Load Marketplace Registry

Read the plugin registry to enumerate available plugin groups:

Read: ${CLAUDE_PLUGIN_ROOT}/../../.claude-plugin/marketplace.json

Parse the plugins array. Each entry has name, version, description, and source (relative path like ./core-tools). Extract the short group name from the source path.

Exclude plugin-tools from the selection list — the converter should not attempt to convert itself.

For each group, scan its directory to count components:

  • Skills: Glob claude/{group}/skills/*/SKILL.md
  • Agents: Glob claude/{group}/agents/*.md
  • Hooks: check for claude/{group}/hooks/hooks.json

Step 3: Configuration Wizard

Present configuration options via AskUserQuestion. Build the questions array dynamically — include only questions that still need user input (skip questions fully answered by arguments).

If ALL arguments were provided (valid plugin names or --all, plus --output and --flatten or --nested), skip this step entirely and proceed to Step 4.

Otherwise, build the questions array from the following, including only the ones needed. Combine applicable questions into a single AskUserQuestion call (max 4 questions per call).

Q1: Plugin Groups — include unless --all was specified or all positional args are valid group names.

List all available groups (with component counts) in the question text so users can reference them when choosing "Other". Use preset-based options to stay within the 4-option limit:

- header: "Plugin Groups"
  question: "Which plugin groups would you like to convert? Available: {group1} ({N} skills, {M} agents), {group2} (...), ..."
  options:
    - label: "All groups"
      description: "Convert all {count} available plugin groups"
    - label: "Core stack"
      description: "core-tools + dev-tools + claude-tools"
    - label: "SDD pipeline"
      description: "sdd-tools + tdd-tools + claude-tools"
  multiSelect: false

Build the preset options dynamically from the available groups — create 2-3 logical groupings based on the plugin descriptions. The user can always type specific group names via the built-in "Other" option.

If positional arguments named specific plugins but any name is invalid, note the invalid name in the question text: "'{invalid-name}' was not found."

Q2: Output Directory — include unless --output was provided:

- header: "Output"
  question: "Where should the converted files be written?"
  options:
    - label: "./ported/ (Recommended)"
      description: "Standard ported output location — timestamped subdirectory created automatically"
    - label: "Custom path"
      description: "Specify a different output directory"
  multiSelect: false

Q3: Output Mode — include unless --flatten or --nested was provided:

- header: "Output Mode"
  question: "What output format should be used?"
  options:
    - label: "Full (skills, agents, hooks)"
      description: "Preserves original component structure in generic format"
    - label: "Skills only (flatten)"
      description: "Converts agents to skills, absorbs hooks — for harnesses that only support skills"
    - label: "Nested (skills with embedded agents)"
      description: "Agents nested as pure markdown in parent skills, hooks absorbed — for harnesses using skills as primary unit"
  multiSelect: false

Q4: Output Layout — include only when ALL of these conditions are met:

  • Output mode is "Full" (not flatten or nested) — determined by arguments or Q3 answer
  • Multiple groups are selected or --all was specified — determined by arguments or Q1 answer
  • --unified was NOT already provided as an argument
- header: "Output Layout"
  question: "How should the output be organized?"
  options:
    - label: "Per-group (Recommended)"
      description: "Each group in its own subdirectory with separate manifest and integration guide"
    - label: "Unified"
      description: "All groups merged into one directory — single manifest, single integration guide, components organized by type"
  multiSelect: false

Store results as:

  • SELECTED_GROUPS — plugin groups to convert (parse from preset or "Other" text)
  • OUTPUT_DIR — base output directory (before timestamp)
  • FLATTEN_MODE — boolean, true if "Skills only" selected or --flatten provided
  • NESTED_MODE — boolean, true if "Nested" selected or --nested provided
  • UNIFIED_LAYOUT — boolean, true if "Unified" selected or --unified provided. Always false in flatten/nested mode or when only one group is selected

Step 4: Component-Level Selection

For each selected group, enumerate components by reading frontmatter from each file to extract name and description. Count skills, agents, and hooks.

Present a simplified selection per group using preset options (stays within 4-option limit). List all component names in the question text so users know what's available:

AskUserQuestion:
  questions:
    - header: "{group-name}"
      question: "Select components from {group-name} ({total} total — Skills: {skill_names}; Agents: {agent_names}; Hooks: {yes/no}):"
      options:
        - label: "All components (Recommended)"
          description: "Convert all {total} components"
        - label: "Skills only"
          description: "Convert {skill_count} skills, skip agents and hooks"
        - label: "Custom selection"
          description: "Specify which components to include via text"
      multiSelect: false

If multiple groups are selected, you can ask about all groups in a single AskUserQuestion call (one question per group, max 4 questions per call). For more than 4 groups, use multiple sequential calls.

If the user selects "Custom selection" or types specific names via "Other", parse their response to build the component list.

In flatten mode, add context to the question text:

  • Note that agents will be converted to skills and hooks will be absorbed into a lifecycle-hooks skill

In nested mode, add context to the question text:

  • Note that agents will be nested as pure markdown instruction files within their parent skill's agents/ directory
  • Note that hooks will be absorbed into a lifecycle-hooks skill (same as flatten)

Build SELECTED_COMPONENTS — a flat list:

[{ type: "skill"|"agent"|"hooks", group: "{group}", name: "{name}", path: "{file path}" }]

Step 5: Confirm Selection

Present a summary table showing selected components, output mode, and output directory. Confirm with the user:

AskUserQuestion:
  questions:
    - header: "Confirm"
      question: "Proceed with converting {count} components? Output: {output_mode}{layout_suffix}, Directory: {OUTPUT_DIR}"
      options:
        - label: "Proceed"
          description: "Continue to dependency analysis"
        - label: "Modify"
          description: "Change configuration"
        - label: "Cancel"
          description: "Exit"
      multiSelect: false

Where {output_mode} is "Full", "Flatten (skills only)", or "Nested (skills with embedded agents)". {layout_suffix} is (unified layout) when UNIFIED_LAYOUT is true, empty string otherwise.


Phase 2: Dependency Analysis & Resolution Planning

Goal: Map all dependencies between selected components and plan how to resolve them in the generic output.

Step 1: Parse Dependencies

For each component in SELECTED_COMPONENTS, read its source file and scan for dependency patterns.

Six dependency patterns to detect:

PatternExampleType
Same-plugin skill loadRead ${CLAUDE_PLUGIN_ROOT}/skills/{name}/SKILL.mdskill-to-skill
Cross-plugin load${CLAUDE_PLUGIN_ROOT}/../{group}/skills/{name}/SKILL.mdcross-plugin
Reference file include${CLAUDE_PLUGIN_ROOT}/skills/{name}/references/{file}reference
Agent spawnsubagent_type: "{name}" or subagent_type: "{plugin}:{name}"agent-ref
Agent skill preloadskills: array in agent frontmatteragent-to-skill
Agent-to-agent referenceAgent body mentions another agent by name in spawning contextagent-to-agent

Also detect external dependencies (MCP servers, shell scripts) for informational tracking.

Step 2: Classify Dependencies

For each dependency found, classify it:

ClassificationMeaningAction
InternalTarget is in SELECTED_COMPONENTSWill be converted; reference by name
External-availableTarget exists on disk but wasn't selectedReference by name in manifest
External-missingTarget doesn't exist locallyNote as unresolved in manifest
Reference filePoints to a references/*.md fileSmart resolution (see Step 3)

Unified layout adjustment: When UNIFIED_LAYOUT is active, dependencies that would be classified as External-available between selected groups are reclassified as Internal. A component from group A that depends on a component from group B (both selected) is internal in unified mode because both exist in the same output directory. Only dependencies pointing to groups NOT in SELECTED_GROUPS remain external.

Step 3: Smart Resolution Planning

For each reference file dependency, determine how to handle it based on line count, consumer count, and consumer type.

  1. Count lines in the referenced file using Bash: wc -l < {path}
  2. Determine the primary owner — the skill whose source directory originally contained the reference file (from the source path skills/{owner}/references/{file}). If the primary owner was not selected for conversion, assign ownership to the first selected consumer
  3. Identify all consumers — which skills and agents use this reference

Decision logic for skill-consumed references:

  • Under 250 lines AND single consumer → mark for inline (content will be embedded directly in the consuming skill's SKILL.md)
  • 250+ lines AND single consumer → mark as separate in the consuming skill's references/ directory
  • Multiple skill consumers → mark as separate in the primary owner skill's references/ directory; other consumers reference via relative path ../{owner-skill}/references/{file}

Decision logic for agent-consumed references (full mode):

  • Under 250 lines → mark for inline into the agent's body
  • 250+ lines → mark as promote_to_skill — the reference becomes a new skill at skills/{ref-name}/SKILL.md with its content as the body. The agent's converted text will reference it as a dependency. If the name collides with an existing skill, prefix with the agent name: {agent-name}-{ref-name}

Decision logic for agent-consumed references (flatten mode):

When FLATTEN_MODE is active, agents are converted to skills. Use skill-consumed rules instead of promote_to_skill:

  • Under 250 lines AND single consumer → mark for inline into the agent-as-skill's body
  • 250+ lines AND single consumer → mark as separate in the agent-as-skill's references/ directory
  • Multiple consumers → mark as separate in the primary owner skill's references/ directory

This avoids creating promoted skills when the agent itself is already becoming a skill — the reference can live directly in the agent-as-skill's own references/ directory.

Decision logic for agent-consumed references (nested mode):

When NESTED_MODE is active, agents are nested within their parent skill's directory. Use skill-consumed rules (same as flatten), but the "owning skill" for a nested agent's references is the parent skill from AGENT_PARENT_MAP:

  • Under 250 lines AND single consumer → mark for inline into the nested agent's markdown body
  • 250+ lines AND single consumer → mark as separate in the parent skill's references/ directory
  • Multiple consumers → mark as separate in the primary owner skill's references/ directory

This keeps all reference files at the skill directory level — nested agents don't have their own references/ subdirectory.

Mixed consumers (skill + agent): Skill-consumed rules take precedence. The agent references the owning skill's directory.

Unified layout adjustment: When UNIFIED_LAYOUT is active, cross-group reference resolution follows the same rules as same-group resolution. All skills are siblings under a single skills/ directory, so cross-skill paths use the standard ../{owner-skill}/references/{file} convention regardless of which group the skills originated from.

Store decisions as RESOLUTION_PLAN:

[{ ref_path, line_count, decision: "inline"|"separate"|"promote_to_skill", owner_skill: "{skill-name}", used_by: [component names] }]

Step 3b: Agent-to-Parent Mapping (Nested Mode Only)

Skip this step unless NESTED_MODE is active.

For each agent in SELECTED_COMPONENTS, determine which skill "owns" it — the parent skill under which the agent will be nested.

Detection patterns (ordered by priority):

  1. subagent_type references — Scan all selected skills for subagent_type patterns matching the agent name (e.g., subagent_type: "code-explorer" or subagent_type: "core-tools:code-explorer"). Highest confidence.
  2. Prose spawning references — Scan skill bodies and their reference files for the agent name appearing in spawning contexts (e.g., "launch a wave-lead", "spawn the code-explorer agent"). Lower confidence but catches agents referenced without subagent_type.
  3. Agent-to-agent chains — Scan other agents' bodies for references to this agent. If agent A spawns agent B, and agent A's parent is skill S, then agent B also nests under skill S.

Priority resolution when multiple skills reference the same agent:

  • Same-group skill with subagent_type takes priority
  • Same-group skill with prose reference is second
  • Agent-spawner's parent skill is third (for agent-to-agent chains)
  • If still tied, the skill with the most references to the agent wins

Agent-spawns-agent chains: When an agent spawns another agent (e.g., wave-lead spawns context-manager), both nest under the same grandparent skill. The agents/ directory is flat — no nesting within nested agents.

Orphan agents: If no selected skill references an agent, mark it as orphan. Orphan agents will be promoted to standalone skills during Phase 3.

Store the mapping as AGENT_PARENT_MAP:

{ agent_name: parent_skill_name | "orphan" }

Step 4: Present Dependency Summary

Show the user:

  • Total dependencies found
  • How many will be inlined vs. kept as separate files
  • Which skill directories will contain references/ subdirectories and what they own
  • Any references promoted from agent references to standalone skills
  • Any external/missing dependencies that won't be included
  • In nested mode, also show:
    • Agent-to-parent mappings discovered (which agent nests under which skill)
    • Any orphan agents that will be promoted to standalone skills
    • Any agents referenced by multiple skills (which skill gets the nesting, which get cross-references)
  • In unified layout, also show:
    • Cross-group dependencies reclassified as internal (count and list)
    • Any name collisions detected across groups (components with the same type and name from different groups)
  • Ask for confirmation to proceed

Phase 3: Conversion

Goal: Transform each component into a clean, platform-agnostic format.

Before starting conversion, read the detailed transformation rules:

Read ${CLAUDE_PLUGIN_ROOT}/skills/port-master/references/conversion-rules.md

Process components in dependency order (leaf nodes first) so that when a component references another, the referenced component has already been converted.

Skill Conversion

For each skill:

  1. Read source — Read the SKILL.md file, split into YAML frontmatter and markdown body
  2. Transform frontmatter — Apply the Skill Frontmatter Rules from conversion-rules.md: keep name and description, remove platform-specific fields, add dependencies list
  3. Transform body — Apply all Body Transformation Rules from conversion-rules.md in order:
    • Resolve ${CLAUDE_PLUGIN_ROOT} references (inline small content or add See: {name} pointers)
    • Rewrite tool-specific language to generic descriptions
    • Decompose orchestration patterns (teams, tasks, waves) into sequential/parallel prose
    • Remove prompt engineering directives aimed at Claude specifically
    • Generalize settings and configuration references (rule 3f)
    • Apply .claude/ → .agents/ path replacement (rule 3g)
  4. Append Integration Notes — Add a ## Integration Notes section describing what capabilities the target harness needs to support this skill
  5. Store result for output in Phase 4

Agent Conversion (Full Mode)

Skip this section if FLATTEN_MODE or NESTED_MODE is active — use "Agent-to-Skill Conversion" or "Agent-to-Nested Conversion" below instead.

For each agent:

  1. Read source — Read the agent .md file
  2. Transform frontmatter — Keep name and description. Add role (inferred from description: explorer, reviewer, architect, executor, etc.). Add dependencies for any preloaded skills
  3. Transform body — Same rules as skills (including 3g path replacement), plus:
    • Resolve skills: preloads into prose ("This agent draws on knowledge from {skill-name}")
    • Remove tool-restriction prose ("You only have access to Read, Glob, Grep")
  4. Append Integration Notes
  5. Store result

Hook Conversion (Full Mode)

Skip this section if FLATTEN_MODE or NESTED_MODE is active — use "Hook-to-Skill Conversion" below instead.

For each hooks component:

  1. Read source — Read hooks.json and parse JSON
  2. Convert to YAML — Map Claude Code event names to generic lifecycle events using the Hook Event Mapping table from conversion-rules.md
  3. Process hook entries:
    • Command hooks → Copy referenced scripts, resolve ${CLAUDE_PLUGIN_ROOT} paths to relative paths within the output directory. Apply rule 3g (.claude/ → .agents/) to script content. Add a comment explaining what the script does (read the script to understand its purpose)
    • Prompt hooks → Preserve the prompt text as-is (already platform-agnostic). Apply rule 3g to any .claude/ paths in the prompt text
  4. Add descriptions — For each hook entry, add a description field explaining when and why this hook fires
  5. Store result

Agent-to-Nested Conversion (Nested Mode)

Skip this section unless NESTED_MODE is active.

For each agent with a parent in AGENT_PARENT_MAP:

  1. Read source — Read the agent .md file, split into YAML frontmatter and markdown body
  2. Strip frontmatter — Remove YAML frontmatter entirely (no --- delimiters in output)
  3. Structure as pure markdown — Apply the Agent-to-Nested Conversion Rules from Section 9 of conversion-rules.md:
    • # {Agent Name} title (from frontmatter name)
    • One-line summary (from frontmatter description)
    • ## Role — Rewrite identity framing to role description. Keep the role-based voice (e.g., "Responsible for exploring codebases...") since this is still a sub-agent — do NOT use task instruction framing like flatten mode
    • ## Inputs — Document expected parameters the agent receives when spawned
    • ## Process — Preserve numbered workflow steps and phase structure from the body
    • ## Output Format — Document structured output format if applicable; omit if not
    • ## Guidelines — Consolidate behavioral rules and constraints; omit if none
  4. Transform body — Apply all standard Body Transformation Rules (3a-3g from conversion-rules.md) to the content within each section
  5. Convert skills: preloads — Add "This agent draws on knowledge from:" in the Role section, listing each preloaded skill with a brief description
  6. Remove tool-restriction prose — Same as full/flatten mode
  7. Store result for output at skills/{parent-skill}/agents/{agent-name}.md

For each orphan agent (marked as orphan in AGENT_PARENT_MAP):

  1. Apply the Agent-to-Skill conversion rules (same as flatten mode, Section 7 of conversion-rules.md)
  2. Store as skills/{agent-name}/SKILL.md
  3. Append to Integration Notes: "Origin: Promoted from orphan agent {name} — no parent skill in this package spawns this agent directly"

Parent Skill Augmentation (Nested Mode)

Skip this section unless NESTED_MODE is active.

After converting all nested agents, augment each parent skill's converted SKILL.md:

  1. Add a ## Nested Agents section listing all agents nested under this skill:

    ## Nested Agents
    
    The `agents/` directory contains instructions for specialized sub-agents.
    Read them when spawning the relevant sub-agent.
    
    - `agents/{agent-name}.md` — {one-line description from the agent's original description}
    
  2. Rewrite spawn instructions in the parent skill's body to reference nested files:

    • Before: "Spawn N agents via Agent tool with subagent_type: '{name}'"
    • After: "Delegate to N independent {role} agents (see agents/{name}.md for instructions)"
  3. Add cross-references for agents nested under a different skill:

    • "This step uses the {agent-name} agent from the {parent-skill} skill (see ../{parent-skill}/agents/{agent-name}.md)"
  4. Add sub-agent capability requirements to the parent skill's Integration Notes:

    **Sub-agent capabilities:**
    - **{agent-name}**: Requires {capability list from the agent's original tools field}
    

Agent-to-Skill Conversion (Flatten Mode)

Only applies when FLATTEN_MODE is active. Each agent is converted to a skill.

For each agent:

  1. Read source — Read the agent .md file, split into YAML frontmatter and markdown body
  2. Build skill frontmatter:
    • name: Keep the agent name
    • description: Keep the agent description. Append " (converted from agent)"
    • dependencies: Merge the agent's skills: preloads with any detected skill references in the body
  3. Transform body — Apply all standard Body Transformation Rules (3a-3g from conversion-rules.md), then apply the Agent-to-Skill Reframing Rules from Section 7 of conversion-rules.md:
    • Rewrite agent identity framing ("You are a {role} that...") to task instructions ("When invoked, perform the following {role} tasks:")
    • Remove tool-restriction prose ("You only have access to...")
    • Convert skills: preloads into "Prerequisites" section
    • Convert the agent's tools list into a capabilities paragraph in Integration Notes
  4. Append Integration Notes — Use the standard template plus:
    • "Origin: Converted from agent {name} — originally invoked as a sub-agent, not directly by the user"
    • If the agent had a specific model (e.g., Opus, Sonnet), note: "Complexity hint: Originally ran on a {model-tier} model — may benefit from a more capable model for reasoning-heavy steps"
    • Include the Tool Capability Summary from Section 7 of conversion-rules.md
  5. Store result as a skill entry (output to skills/{name}/SKILL.md, not agents/)

Hook-to-Skill Conversion (Flatten and Nested Modes)

Only applies when FLATTEN_MODE or NESTED_MODE is active. ALL hooks from a group are merged into a single lifecycle-hooks skill.

If the group has no hooks, skip this section.

  1. Read source — Read hooks.json and parse JSON
  2. Check for name collision — If a skill named lifecycle-hooks already exists in SELECTED_COMPONENTS for this group, use {group}-lifecycle-hooks as the name instead
  3. Build skill frontmatter — Apply the structure from Section 8 of conversion-rules.md:
    • name: lifecycle-hooks (or {group}-lifecycle-hooks if collision)
    • description: "Behavioral rules and lifecycle event handlers for the {group-name} package. (converted from hooks)"
    • dependencies: []
  4. Build skill body — For each hook entry:
    • Map the Claude Code event name to its generic name using Section 4 (Hook Event Mapping)
    • Create a ## On {generic-event-name} subsection
    • For prompt hooks: include the prompt text verbatim as the rule body
    • For command hooks: read the referenced script, summarize its behavior in prose, store the script in skills/lifecycle-hooks/references/{script-name}.sh (with rule 3g applied to script content)
    • Group multiple hooks on the same event under one heading with matcher sub-sections
  5. Append Integration Notes — Use the template from Section 8 of conversion-rules.md
  6. Store result as a skill entry

Reference File Handling

For reference files marked as "separate" in the RESOLUTION_PLAN:

  1. Read the source file
  2. Clean any ${CLAUDE_PLUGIN_ROOT} paths in the content
  3. Remove Claude Code-specific tool references if present
  4. Apply rule 3g (.claude/ → .agents/ path replacement) to the content
  5. Store for copying to the owning skill's references/ directory (i.e., skills/{owner_skill}/references/{file})

For reference files marked as "promote_to_skill" (full mode only):

  1. Read the source file
  2. Apply the same body transformation rules (3a-3g from conversion-rules.md) to the content
  3. Wrap the content as a new skill with minimal frontmatter (name and description inferred from the reference content and heading)
  4. Store as a new skill entry at skills/{ref-name}/SKILL.md
  5. Update the consuming agent's dependencies list to include the new skill name

For reference files marked as "inline" — their content was already embedded during skill/agent conversion.


Phase 4: Output Generation

Goal: Write all converted files, the manifest, and the integration guide.

Step 1: Create Timestamped Output Directory

The output directory (OUTPUT_DIR) was determined in Phase 1's Configuration Wizard.

Generate a timestamp in YYYYMMDD-HHMMSS format (e.g., 20260304-143052) using the current date and time.

Create the timestamped output directory structure:

{OUTPUT_DIR}/{YYYYMMDD-HHMMSS}/
└── {group-name}/
    └── ...

Each selected group gets its own subdirectory under the timestamp. Store the full timestamped path as TIMESTAMPED_OUTPUT.

When UNIFIED_LAYOUT is active, skip group subdirectories — all components go directly under the timestamp:

{OUTPUT_DIR}/{YYYYMMDD-HHMMSS}/
├── manifest.yaml
├── INTEGRATION-GUIDE.md
├── skills/
├── agents/
└── hooks/

Step 2: Write Component Files

Create the output directory structure and write all converted files.

Full mode output structure:

{TIMESTAMPED_OUTPUT}/{group-name}/
├── manifest.yaml
├── INTEGRATION-GUIDE.md
├── skills/
│   └── {name}/
│       ├── SKILL.md
│       └── references/         (only if this skill owns reference files)
│           └── {file}.md
├── agents/
│   └── {name}.md
└── hooks/
    ├── hooks.yaml
    └── scripts/
        └── {script-name}.sh

Full mode — unified layout output structure (when UNIFIED_LAYOUT is active):

{TIMESTAMPED_OUTPUT}/
├── manifest.yaml              (single combined manifest)
├── INTEGRATION-GUIDE.md       (single combined guide)
├── skills/
│   └── {name}/                (all skills from all groups, flat)
│       ├── SKILL.md
│       └── references/
│           └── {file}.md
├── agents/
│   └── {name}.md              (all agents from all groups, flat)
└── hooks/
    ├── hooks.yaml             (merged hooks from all groups)
    └── scripts/
        └── {script-name}.sh

Name collision handling: When merging components from different groups, names may collide (e.g., two groups both have a researcher agent). Detect collisions before writing:

  1. Build a map of {component-type}:{name} across all groups
  2. For any collision, prefix the component name with its origin group: {group}-{name} (e.g., sdd-researcher and plugin-researcher)
  3. Update all internal references (dependency lists, spawn instructions, cross-references) to use the prefixed name
  4. Record the original name in the manifest's original_name field for traceability

Hooks merging: When multiple groups have hooks, merge all hook entries into a single hooks.yaml. Add an origin_group field to each entry. If script names collide across groups, prefix with group name: {group}-{script-name}.sh.

Flatten mode output structure (skills only — no agents/ or hooks/ directories):

{TIMESTAMPED_OUTPUT}/{group-name}/
├── manifest.yaml
├── INTEGRATION-GUIDE.md
└── skills/
    └── {name}/
        ├── SKILL.md
        └── references/         (only if this skill owns reference files)
            └── {file}.md

In flatten mode, this includes:

  • Original skills (converted as normal)
  • Agent-converted skills (from Agent-to-Skill conversion)
  • The lifecycle-hooks skill (from Hook-to-Skill conversion, if hooks existed in the source)

Nested mode output structure (skills with embedded agents — no top-level agents/ or hooks/):

{TIMESTAMPED_OUTPUT}/{group-name}/
├── manifest.yaml
├── INTEGRATION-GUIDE.md
└── skills/
    └── {name}/
        ├── SKILL.md
        ├── agents/             (only if this skill owns nested agents)
        │   └── {agent-name}.md (pure markdown, no YAML frontmatter)
        └── references/         (only if this skill owns reference files)
            └── {file}.md

In nested mode, this includes:

  • Original skills (converted as normal, augmented with ## Nested Agents section if they own agents)
  • Nested agent instruction files within their parent skill's agents/ directory
  • Orphan agents promoted to standalone skills (from Agent-to-Skill conversion)
  • The lifecycle-hooks skill (from Hook-to-Skill conversion, if hooks existed in the source)

Each skill gets its own directory with SKILL.md inside. Reference files are co-located in the owning skill's references/ subdirectory — only create the references/ subdirectory when at least one separate reference file exists. There is no root-level references/ directory.

Write each converted component to its appropriate location.

Step 3: Generate manifest.yaml

The manifest provides a machine-readable inventory of the package:

name: {group-name}
description: {from marketplace registry}
mode: "full"                               # or "flatten" or "nested"
source:
  platform: "Claude Code"
  plugin: "{marketplace-name}"
  version: "{version}"
converted: "{YYYY-MM-DD}"

components:
  skills:
    - name: {name}
      file: skills/{name}/SKILL.md
      description: {description}
      origin: skill                        # "skill", "agent", or "hooks"
      references:                          # only if this skill owns reference files
        - name: {ref-name}
          file: skills/{name}/references/{ref-name}.md
          used_by: [{component names}]
  agents:                                  # omit this section in flatten mode
    - name: {name}
      file: agents/{name}.md
      description: {description}
      role: {role}
  hooks:                                   # omit this section in flatten mode
    - event: {generic-event-name}
      file: hooks/hooks.yaml
      description: {what the hook does}

dependencies:
  internal:
    - from: {component}
      to: {component}
      relationship: "{what it loads/uses}"
  external:
    - from: {component}
      to: {external name}
      source_plugin: "{plugin group}"
      relationship: "{what it needs}"
      note: "Not included — convert separately if needed"

The origin field indicates whether each skill was originally a skill, an agent (converted to skill in flatten mode), or hooks (absorbed into lifecycle-hooks skill). In full mode, all skills have origin: skill.

Full mode — unified layout manifest (when UNIFIED_LAYOUT is active):

name: unified-export
description: "Combined export of {group1}, {group2}, ... plugin groups"
mode: "full"
layout: "unified"
source:
  platform: "Claude Code"
  groups:
    - name: {group1}
      plugin: "{marketplace-name-1}"
      version: "{version-1}"
    - name: {group2}
      plugin: "{marketplace-name-2}"
      version: "{version-2}"
converted: "{YYYY-MM-DD}"

components:
  skills:
    - name: {name}
      file: skills/{name}/SKILL.md
      description: {description}
      origin: skill
      origin_group: {group-name}
      original_name: {original-name}    # only present if renamed due to collision
      references:
        - name: {ref-name}
          file: skills/{name}/references/{ref-name}.md
          used_by: [{component names}]
  agents:
    - name: {name}
      file: agents/{name}.md
      description: {description}
      role: {role}
      origin_group: {group-name}
      original_name: {original-name}    # only present if renamed due to collision
  hooks:
    - event: {generic-event-name}
      file: hooks/hooks.yaml
      description: {what the hook does}
      origin_group: {group-name}

dependencies:
  internal:                             # includes cross-group deps that were external in per-group mode
    - from: {component}
      to: {component}
      relationship: "{what it loads/uses}"
  external:                             # only deps pointing to groups NOT in SELECTED_GROUPS
    - from: {component}
      to: {external name}
      source_plugin: "{plugin group}"
      relationship: "{what it needs}"
      note: "Not included — convert separately if needed"

Key differences from per-group manifest: name is unified-export, layout: "unified" field added, source.groups is an array, every component has origin_group, and cross-group dependencies appear as internal.

In flatten mode, omit the agents and hooks sections entirely — all components appear under skills.

In nested mode, use mode: "nested" and represent agents within their parent skill entries:

mode: "nested"

components:
  skills:
    - name: {skill-name}
      file: skills/{skill-name}/SKILL.md
      description: {description}
      origin: skill
      nested_agents:                                         # only if this skill has nested agents
        - name: {agent-name}
          file: skills/{skill-name}/agents/{agent-name}.md
          description: {description}
          origin: agent
          role: {role}
      references:                                            # only if this skill owns reference files
        - name: {ref-name}
          file: skills/{skill-name}/references/{ref-name}.md
          used_by: [{component names}]
    - name: {orphan-agent-name}                              # orphan agents appear as top-level skills
      file: skills/{orphan-agent-name}/SKILL.md
      description: {description}
      origin: agent

In nested mode, omit top-level agents and hooks sections. Agents appear as nested_agents within their parent skill. Orphan agents appear as top-level skill entries with origin: agent.

Step 4: Generate INTEGRATION-GUIDE.md

The guide helps harness developers understand and integrate the converted components.

Full mode:

# Integration Guide: {group-name}

## Overview
{What this package provides — summarize the plugin group's purpose}

## Component Inventory
| Component | Type | Description |
|-----------|------|-------------|
{table of all components}

## Capability Requirements
{What features the target harness needs — organized by category:}
- **File operations**: Which components need to read/write/search files
- **Shell execution**: Which components run shell commands
- **User interaction**: Which components prompt for user input
- **Sub-agent delegation**: Which components spawn child agents
- **Web access**: Which components fetch external content (if any)

## Per-Component Notes
{For each component, compile the Integration Notes section from the converted file}

## Dependency Map
{If more than 5 internal dependencies, include a text-based dependency diagram}

## Adaptation Checklist
- [ ] Review each skill's instructions and adapt tool-specific language for your harness
- [ ] Configure agent spawning for components that delegate to sub-agents
- [ ] Set up lifecycle hooks if your harness supports them
- [ ] Resolve external dependencies listed in manifest.yaml
- [ ] Test each component individually before combining

Full mode — unified layout adjustments to the integration guide:

  • Title: # Integration Guide: Unified Export
  • Add an "Overview" paragraph explaining this package combines components from N groups, with a brief description of each group
  • Add a "Source Groups" table:
## Source Groups
| Group | Original Plugin | Version | Skills | Agents | Hooks |
|-------|----------------|---------|--------|--------|-------|
{table of all source groups with component counts}
  • The "Component Inventory" table adds an "Origin Group" column
  • Add a "Name Collisions" section (omit entirely if no collisions occurred):
## Name Collisions
| Current Name | Original Name | Origin Group | Reason |
|-------------|---------------|-------------|--------|
{collision table}
  • "Per-Component Notes" grouped by origin group with ### From {group} subheadings
  • "Dependency Map" is a single unified graph — cross-group dependencies appear as internal
  • Update the "Adaptation Checklist":
## Adaptation Checklist
- [ ] Review each skill's instructions and adapt tool-specific language for your harness
- [ ] Configure agent spawning for components that delegate to sub-agents
- [ ] Set up lifecycle hooks if your harness supports them (hooks merged from {N} groups)
- [ ] Resolve external dependencies listed in manifest.yaml
- [ ] If components were renamed due to collisions, update any external references
- [ ] Test each component individually before combining

Flatten mode adjustments to the integration guide:

  • The "Component Inventory" table uses "skill" for all types, with an "Origin" column showing the original type (skill, agent, hooks)
  • The "Capability Requirements" section notes that agent and hook capabilities have been folded into skills
  • Add a "Flatten Mode Notes" section after "Per-Component Notes":
## Flatten Mode Notes

This package was converted in flatten mode — all components are skills.

### Agent-Converted Skills
{List skills that were originally agents, with their original role context}

### Lifecycle Hooks Skill
{If lifecycle-hooks skill exists: describe the behavioral rules it contains and their original event triggers}

### Capability Notes
{Any tool-scope restrictions from original agents that consumers should be aware of}
  • Update the "Adaptation Checklist" for flatten mode:
## Adaptation Checklist
- [ ] Review each skill's instructions and adapt tool-specific language for your harness
- [ ] Review agent-converted skills for role-appropriate context injection
- [ ] Implement lifecycle-hooks rules as middleware, event handlers, or manual checks
- [ ] Resolve external dependencies listed in manifest.yaml
- [ ] Test each component individually before combining

Nested mode adjustments to the integration guide:

  • The "Component Inventory" table includes columns: Component, Type, Origin, Parent Skill, Description. Nested agents have their parent skill listed; top-level skills and orphans have "—".
  • The "Capability Requirements" section notes that agent capabilities are documented within their parent skill's Integration Notes under "Sub-agent capabilities"
  • Add a "Nested Mode Notes" section after "Per-Component Notes":
## Nested Mode Notes

This package was converted in nested mode — agents are embedded within their parent skills as pure markdown instruction files.

### Nesting Map
| Agent | Parent Skill | Role | Purpose |
|-------|-------------|------|---------|
{table of agent-to-parent mappings from AGENT_PARENT_MAP}

### Reading Nested Agents
Each parent skill's SKILL.md contains a "Nested Agents" section listing its sub-agents with one-line descriptions. The agent files in `agents/` are pure markdown instructions — read them when spawning the corresponding sub-agent. They have no YAML frontmatter.

### Orphan Agents
{If any orphan agents were promoted to standalone skills, list them here with explanation. Otherwise: "No orphan agents — all agents are nested under a parent skill."}

### Cross-Skill Agent References
{If any skills reference agents nested under a different skill, list the cross-references here.}

### Lifecycle Hooks Skill
{Same as flatten mode — describe the behavioral rules it contains and their original event triggers, if hooks existed in the source}
  • Update the "Adaptation Checklist" for nested mode:
## Adaptation Checklist
- [ ] Review each skill's instructions and adapt tool-specific language for your harness
- [ ] For skills with nested agents, configure sub-agent spawning to read instructions from the agents/ directory
- [ ] Review orphan agents (promoted to standalone skills) for role-appropriate context
- [ ] Check cross-skill agent references and ensure relative paths work in your harness
- [ ] Implement lifecycle-hooks rules as middleware, event handlers, or manual checks
- [ ] Resolve external dependencies listed in manifest.yaml
- [ ] Test each component individually before combining

Step 5: Write All Files

Write all files to the output directory using the Write tool. Track every file written for the summary.


Phase 5: Summary

Goal: Present conversion results and suggest next steps.

Results Table

## Conversion Complete

**Output mode:** {Full | Flatten (skills only) | Nested (skills with embedded agents)}
**Output directory:** {TIMESTAMPED_OUTPUT}

| Component | Type | Origin | Lines (source → output) | Notes |
|-----------|------|--------|------------------------|-------|
{for each component}

**Files written:** {count}
**Skill directories created:** {count}
**References inlined:** {count} ({total lines})
**References co-located with skills:** {count}
**References promoted to skills:** {count} (from agent references, full mode only)
**External dependencies:** {count} (not included)

In unified layout, add these additional stats:

**Output layout:** Unified
**Groups merged:** {count} ({group names})
**Cross-group deps internalized:** {count}
**Name collisions resolved:** {count} (renamed with group prefix)

In flatten mode, add these additional stats:

**Agents converted to skills:** {count}
**Hooks absorbed into lifecycle-hooks:** {count} ({hook_count} events)

In nested mode, add these additional stats:

**Agents nested within skills:** {count} (across {parent_count} parent skills)
**Orphan agents promoted to skills:** {count}
**Hooks absorbed into lifecycle-hooks:** {count} ({hook_count} events)

The "Origin" column shows "skill", "agent", or "hooks" — in full mode this always matches "Type", but in flatten mode it shows the original component type before conversion.

Next Steps

Suggest:

  1. Review the INTEGRATION-GUIDE.md for capability requirements
  2. Start with the simplest skill to validate integration with the target harness
  3. If external dependencies exist, note which plugin groups they come from
  4. For components that used team orchestration (now decomposed to sequential/parallel steps), test the simplified workflow to ensure it meets needs
  5. In flatten mode: review agent-converted skills to verify the reframing preserved the original intent
  6. In nested mode: verify agent-to-parent mappings — ensure each agent is nested under the skill that logically spawns it. Review cross-skill references for accuracy
  7. In unified layout: check renamed components (if any collisions occurred) and verify the unified dependency map captures all cross-group relationships

Plugin Porter

Convert Agent Alchemy plugins (skills, agents, hooks, references, MCP configs) into formats compatible with other AI coding platforms using an extensible markdown-based adapter framework, live platform research, and interactive conversion workflows.

CRITICAL: Complete ALL 7 phases. The workflow is not complete until Phase 7: Summary 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.

  • Every wizard question -> AskUserQuestion
  • Selection questions -> AskUserQuestion
  • Confirmation questions -> AskUserQuestion
  • Yes/no consent questions -> AskUserQuestion
  • Clarifying questions -> AskUserQuestion

Text output should only be used for:

  • Summarizing selections and findings
  • Presenting information and status updates
  • Explaining context or conversion details

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

NEVER do this (asking via text output):

Which plugin groups would you like to port?
1. core-tools
2. dev-tools
3. sdd-tools

ALWAYS do this (using AskUserQuestion tool):

AskUserQuestion:
  questions:
    - header: "Plugin Groups"
      question: "Which plugin groups would you like to port?"
      options:
        - label: "core-tools"
          description: "3 skills, 2 agents — Deep analysis, codebase analysis, language patterns"
        - label: "dev-tools"
          description: "6 skills, 4 agents — Feature dev, code review, docs, changelog"
        - label: "sdd-tools"
          description: "6 skills, 3 agents — Spec creation, task management, execution"
      multiSelect: true

Plan Mode Behavior

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

  • DO NOT create an implementation plan for how to build the porting feature
  • DO NOT defer conversion to an "execution phase"
  • DO proceed with the full wizard and conversion workflow immediately
  • DO write converted files to the output directory as normal

Phase Overview

Execute these phases in order, completing ALL of them:

  1. Settings & Arguments - Load configuration and parse arguments
  2. Plugin Selection Wizard - Interactive selection of plugin groups and components
  3. Dependency Validation - Build dependency graph and detect missing references
  4. Platform Research - Spawn research agent to investigate target platform 4.5. Dry-Run Preview - Optional preview of expected output before conversion
  5. Wave-Based Conversion - Convert components via parallel agent team with incompatibility resolution
  6. Output & Reporting - Write converted files, migration guide, and gap report
  7. Summary - Present results and next steps

Phase 1: Settings & Arguments

Goal: Load configuration, parse arguments, and determine the target platform.

Step 1: Parse Arguments

Parse $ARGUMENTS for:

  • --target <platform> — Target platform slug (default: opencode)
  • --dry-run — Preview mode; show expected output without writing files

Set TARGET_PLATFORM from --target value (default: opencode). Set DRY_RUN from --dry-run flag (default: false).

Step 2: Load Settings

Check if .claude/agent-alchemy.local.md exists and read for any plugin-tools section with settings:

- **plugin-tools**:
  - **default-target**: opencode
  - **default-output-dir**: ported/
  - **auto-research**: true

If settings exist, apply them as defaults (CLI arguments override settings file values).

Step 3: Validate Adapter

Check that an adapter file exists for the target platform:

  1. Use Glob to check ${CLAUDE_PLUGIN_ROOT}/references/adapters/{TARGET_PLATFORM}.md
  2. If the adapter file exists, read it and store as ADAPTER
  3. If no adapter file exists:
    • Inform the user: "No adapter file found for '{TARGET_PLATFORM}'. The research agent will investigate the platform from scratch, and a new adapter file can be created from the findings."
    • Set ADAPTER = null
    • Continue — the research phase will gather platform information

Step 4: Load Marketplace Registry

Read the marketplace registry to enumerate available plugin groups:

Read: ${CLAUDE_PLUGIN_ROOT}/../../.claude-plugin/marketplace.json

Parse the plugins array. Each entry has:

  • name — Full plugin name (e.g., agent-alchemy-core-tools)
  • version — Current version
  • description — Brief description
  • source — Relative path to plugin directory (e.g., ./core-tools)

Build a list of available plugin groups, extracting the short group name from the source path (e.g., core-tools from ./core-tools).

Exclude plugin-tools from the selection list — the porter should not attempt to port itself.


Phase 2: Plugin Selection Wizard

Goal: Guide the user through selecting which plugin groups and individual components to port.

Step 1: Target Platform Confirmation

Inform the user of the target platform and configuration:

Target platform: {TARGET_PLATFORM}
Adapter: {adapter file path or "None — research agent will investigate"}
Dry-run: {DRY_RUN}

Step 2: Group-Level Selection

Present all available plugin groups for selection using AskUserQuestion with multiSelect: true.

For each plugin group, scan its directory to count components:

  1. Use Glob to count skills: claude/{group}/skills/*/SKILL.md
  2. Use Glob to count agents: claude/{group}/agents/*.md
  3. Use Glob to check for hooks: claude/{group}/hooks/hooks.json
  4. Use Glob to count reference dirs: claude/{group}/skills/*/references/
  5. Use Glob to check for MCP config: claude/{group}/.mcp.json

Build the selection options:

AskUserQuestion:
  questions:
    - header: "Plugin Group Selection"
      question: "Which plugin groups would you like to port to {TARGET_PLATFORM}?"
      options:
        - label: "{group-name} (v{version})"
          description: "{skill_count} skills, {agent_count} agents{, hooks}{, MCP config} — {marketplace description}"
      multiSelect: true

Edge case — Empty plugin group: If a scanned group has zero skills, zero agents, no hooks, and no MCP config, skip it from the selection list and note: "Skipped {group}: no portable components found."

Store the selected groups as SELECTED_GROUPS.

If no groups are selected (user cancels or selects nothing), use AskUserQuestion to confirm:

AskUserQuestion:
  questions:
    - header: "No Selection"
      question: "No plugin groups were selected. Would you like to start over or cancel?"
      options:
        - label: "Start over"
          description: "Return to group selection"
        - label: "Cancel"
          description: "Exit the porter"
      multiSelect: false

If "Start over", repeat Step 2. If "Cancel", end the workflow gracefully.

Step 3: Component-Level Selection

For each selected group, scan and enumerate all individual components, then present for selection.

Component scanning per group:

  1. Skills: For each claude/{group}/skills/*/SKILL.md:

    • Read the frontmatter to extract name and description
    • Check for references/ subdirectory and count reference files
    • Format: skill:{group}/{skill-name} with description
  2. Agents: For each claude/{group}/agents/*.md:

    • Read the frontmatter to extract name, description, and model
    • Format: agent:{group}/{agent-name} with description and model tier
  3. Hooks: If claude/{group}/hooks/hooks.json exists:

    • Read the file and count hook entries
    • Format: hooks:{group} with hook count and event types
  4. MCP Config: If claude/{group}/.mcp.json exists:

    • Read the file and list configured servers
    • Format: mcp:{group} with server names

Present components for each group using AskUserQuestion:

AskUserQuestion:
  questions:
    - header: "{group-name} Components"
      question: "Select components to port from {group-name}:"
      options:
        - label: "All components"
          description: "Port everything in {group-name} ({total_count} components)"
        - label: "skill: {skill-name}"
          description: "{skill description} ({ref_count} references)"
        - label: "agent: {agent-name}"
          description: "{agent description} (model: {model})"
        - label: "hooks: {group}"
          description: "{hook_count} hooks ({event types})"
        - label: "mcp: {group}"
          description: "MCP config ({server names})"
      multiSelect: true

Edge case — "All components" selected: If the user selects "All components", include every component from that group in the selection. Do not present further sub-selection.

Build the final component list as SELECTED_COMPONENTS, a flat list of component identifiers with their types:

[
  { type: "skill", group: "core-tools", name: "deep-analysis", path: "claude/core-tools/skills/deep-analysis/SKILL.md" },
  { type: "agent", group: "core-tools", name: "code-explorer", path: "claude/core-tools/agents/code-explorer.md" },
  { type: "hooks", group: "core-tools", name: "hooks", path: "claude/core-tools/hooks/hooks.json" },
  ...
]

Step 4: Selection Summary

Present a summary of the selection to the user:

## Selection Summary

**Target platform:** {TARGET_PLATFORM}
**Plugin groups:** {count} selected
**Total components:** {count}

| Group | Skills | Agents | Hooks | MCP | References |
|-------|--------|--------|-------|-----|------------|
| {group} | {n} | {n} | {yes/no} | {yes/no} | {n} files |

Components:
- {component list with types}

Use AskUserQuestion to confirm:

AskUserQuestion:
  questions:
    - header: "Confirm Selection"
      question: "Proceed with this selection?"
      options:
        - label: "Proceed"
          description: "Continue to dependency validation"
        - label: "Modify selection"
          description: "Go back and change component selection"
        - label: "Cancel"
          description: "Exit the porter"
      multiSelect: false

If "Modify selection", return to Step 2. If "Cancel", end the workflow gracefully.


Phase 3: Dependency Validation

Goal: Build a full dependency graph from selected components, detect all five dependency types, flag missing references and external dependencies, and produce a dependency-sorted conversion order for Phase 5.

This phase consumes SELECTED_COMPONENTS and SELECTED_GROUPS from Phase 2 and produces DEPENDENCY_GRAPH (including CONVERSION_ORDER) for Phase 5.

Step 1: Parse Dependencies

For each component in SELECTED_COMPONENTS, read its source file and extract all dependency references. Initialize a flat dependency list:

DEPENDENCIES = []   // each entry: { source, target_type, target_ref, dep_type, raw_pattern, transitive }

Process each component type using the sub-steps below. Apply these error handling rules during scanning:

Error: Unreadable file. If a component file cannot be read (permission error, file missing, I/O error), log a warning and continue scanning the remaining components:

WARNING: Could not read {component.path} -- skipping dependency scan for this component.

Error: Malformed YAML frontmatter. If a component's YAML frontmatter cannot be parsed (invalid YAML between --- delimiters), log a parsing error and fall back to body-only scanning for that component:

WARNING: Malformed YAML frontmatter in {component.path} -- scanning body text only for dependencies.
1a: Skill Dependencies

For each skill component (type: "skill"), read its SKILL.md and scan for all five dependency types:

Dependency Type 1 -- Skill-to-skill references:

Scan the skill body for patterns that load another skill from the same plugin group:

Read ${CLAUDE_PLUGIN_ROOT}/skills/{skill-name}/SKILL.md

For each match, extract {skill-name} and record:

{ source: this_component, target_type: "skill", target_ref: "{this_group}/{skill-name}", dep_type: "skill-to-skill", raw_pattern: "{matched line}", transitive: false }

Dependency Type 2 -- Cross-plugin references:

Scan the body for patterns that reference a different plugin group:

${CLAUDE_PLUGIN_ROOT}/../{source-dir-name}/skills/{skill-name}/SKILL.md
${CLAUDE_PLUGIN_ROOT}/../{source-dir-name}/agents/{agent-name}.md
${CLAUDE_PLUGIN_ROOT}/../{source-dir-name}/

For each match, extract {source-dir-name} and the component name, and record:

{ source: this_component, target_type: "skill" or "agent", target_ref: "{source-dir-name}/{name}", dep_type: "cross-plugin", raw_pattern: "{matched line}", transitive: false }

Dependency Type 3 -- Reference file includes:

Scan the body for patterns that load reference files:

Read ${CLAUDE_PLUGIN_ROOT}/skills/{skill-name}/references/{filename}
${CLAUDE_PLUGIN_ROOT}/skills/{skill-name}/references/{filename}

For each match, determine if the reference belongs to this skill or another skill:

  • References to this skill's own references/ directory are internal by definition and do not create a dependency edge
  • References to another skill's references/ directory create a dependency:
{ source: this_component, target_type: "reference", target_ref: "{group}/{skill-name}/references/{filename}", dep_type: "reference-include", raw_pattern: "{matched line}", transitive: false }

Dependency Type 4 -- Agent/subagent references:

Scan the body for Task tool invocations that spawn agents:

subagent_type: "{agent-name}"

For each match, record:

{ source: this_component, target_type: "agent", target_ref: "{group}/{agent-name}", dep_type: "skill-to-skill", raw_pattern: "{matched line}", transitive: false }

External dependencies (non-component):

Scan for system-level dependencies that cannot be ported as components:

  • MCP server tool references: patterns like mcp__{server}__{tool} or the mcp__ prefix in the body or allowed-tools list
  • Bash script invocations: references to specific script files (paths ending in .sh, .py, .js)

For each external dependency found:

{ source: this_component, target_type: "external", target_ref: "{description}", dep_type: "external", raw_pattern: "{matched line}", transitive: false }
1b: Agent Dependencies

For each agent component (type: "agent"), read its .md file:

Dependency Type 5 -- Agent-to-skill references:

Parse the YAML frontmatter and extract the skills: field (array of skill identifiers). For each skill listed:

{ source: this_component, target_type: "skill", target_ref: "{resolved skill reference}", dep_type: "agent-to-skill", raw_pattern: "skills: [{skill}]", transitive: false }

Also scan the agent's markdown body for Read ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_ROOT}/../ patterns, applying the same Type 1, Type 2, and Type 3 scans from Step 1a.

Tool dependencies (informational only):

Parse the tools: field from frontmatter. These are Claude Code platform tools classified as System dependencies. They do not create dependency edges but are tracked for the gap report.

1c: Hook Dependencies

For each hooks component (type: "hooks"), read the hooks.json file and parse the JSON:

Dependency Type 4 -- Hook-to-script references:

For each hook entry, extract the command field and scan for:

  • Script file paths: any path in the command string (e.g., ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/auto-approve.sh)
  • Direct script references: paths ending in .sh, .py, .js, or other executable extensions

For each script reference:

{ source: this_component, target_type: "script", target_ref: "{script path}", dep_type: "hook-to-script", raw_pattern: "{command value}", transitive: false }

Tool matcher patterns in hooks reference Claude Code tool names -- classify these as System dependencies for informational tracking only.

1d: MCP Config Dependencies

For each MCP config component (type: "mcp"), read the .mcp.json file:

Each configured MCP server is an external dependency requiring manual porting on the target platform. Record each server:

{ source: this_component, target_type: "external", target_ref: "MCP server: {server_name} ({command})", dep_type: "external", raw_pattern: "{server config snippet}", transitive: false }

Step 2: Build Dependency Graph

Construct a directed dependency graph from the parsed dependencies.

2a: Create Graph Nodes and Edges

Nodes: All components in SELECTED_COMPONENTS, each identified by {type}:{group}/{name}.

Edges: For each entry in DEPENDENCIES where dep_type is NOT "external" and NOT a system dependency, create a directed edge from the source node to the node matching target_ref.

2b: Classify Each Dependency

For each dependency in DEPENDENCIES, determine its classification by checking target_ref against SELECTED_COMPONENTS and SELECTED_GROUPS:

ClassificationCondition
InternalTarget component exists in SELECTED_COMPONENTS
External-selectedTarget component's group is in SELECTED_GROUPS but the specific component was not individually selected
External-missingTarget component's group is NOT in SELECTED_GROUPS and not available in the marketplace
SystemTarget is a Claude Code platform feature (built-in tool, MCP protocol feature)
ExternalTarget is a non-component dependency (MCP server process, bash script, external service)
2c: Resolve Deeply Nested References (Recursive)

Dependencies can form chains: Skill A loads Skill B, which loads Skill C, which loads Skill D. To ensure the full transitive dependency tree is captured:

  1. Start with the directly parsed dependencies from Step 1 (all have transitive: false)
  2. Build a set SCANNED_COMPONENTS containing all components already processed in Step 1
  3. For each dependency classified as External-missing or External-selected: a. Determine the file path of the target component on disk (using the component scanning conventions: claude/{group}/skills/{name}/SKILL.md for skills, claude/{group}/agents/{name}.md for agents) b. If the file exists and the component is NOT in SCANNED_COMPONENTS:
    • Read the file and scan it using the same rules from Step 1a/1b/1c/1d
    • Mark all newly discovered dependencies with transitive: true
    • Add newly found dependencies to DEPENDENCIES
    • Add the component to SCANNED_COMPONENTS c. If the file does not exist, skip it (it will be reported as unresolvable in Step 4)
  4. Repeat step 3 for any newly discovered External-missing or External-selected dependencies
  5. Recursion depth limit: Cap at depth 10 to prevent runaway expansion. If depth 10 is reached, log:
    WARNING: Dependency chain depth limit (10) reached starting from {root component}. Some transitive dependencies may not be fully resolved.
    
2d: Detect Circular Dependencies

Run a cycle detection pass on the dependency graph using depth-first search:

  1. For each node in the graph, perform a depth-first traversal
  2. Maintain a traversal stack (current path from root)
  3. If a node is encountered that is already on the current stack, a cycle exists
  4. Record each unique cycle (avoid duplicates for cycles detected from different starting nodes):
    CIRCULAR_REFS = [
      { cycle: ["{component_id_1}", "{component_id_2}", ..., "{component_id_1}"], warning: "Circular dependency detected" }
    ]
    
  5. Circular references are warnings that do not block conversion. They will be handled during Phase 5 via topological sort with cycle-breaking.

Step 3: Self-Contained Check

Before alerting the user, determine whether the selection has any unresolved dependencies.

Count dependencies by classification:

  • internal_count -- dependencies already satisfied within the selection
  • external_selected_count -- dependencies in selected groups but not individually selected
  • external_missing_count -- dependencies not in any selected group
  • external_count -- non-component external dependencies (MCP servers, scripts)
  • system_count -- Claude Code platform dependencies

If external_selected_count == 0 AND external_missing_count == 0 AND external_count == 0:

The selection is fully self-contained. Display a brief confirmation and skip to Step 5:

All dependencies resolved -- no missing cross-plugin references.
{internal_count} internal dependencies found between selected components.

Otherwise, proceed to Step 4.

Step 4: Alert on Missing Dependencies

Present the dependency analysis to the user, organized by category:

## Dependency Analysis

**Components scanned:** {SELECTED_COMPONENTS.length}
**Total dependencies found:** {DEPENDENCIES.length}
**Internal (resolved):** {internal_count}
**Missing component dependencies:** {external_selected_count + external_missing_count}
**External (manual porting needed):** {external_count}
**System (Claude Code platform):** {system_count}

{If external_selected_count + external_missing_count > 0:}
### Missing Component Dependencies

These selected components depend on components not in your selection:

| Source Component | Depends On | Dependency Type | Group | Reference Pattern |
|---|---|---|---|---|
| {source.name} | {target_ref} | {dep_type} | {target_group} | `{raw_pattern snippet}` |

{If any dependency has transitive: true:}
Note: Dependencies marked with (*) are transitive -- discovered by following dependency chains beyond the initial selection.

{If external_count > 0:}
### External Dependencies (Manual Porting Required)

These dependencies cannot be automatically ported and will require manual setup on the target platform:

| Source Component | External Dependency | Type | Notes |
|---|---|---|---|
| {source.name} | {target_ref} | MCP server / bash script | Requires manual configuration |

These will be documented in the gap report with setup instructions.
4a: Resolve Missing Component Dependencies

If there are missing component dependencies (external_selected_count + external_missing_count > 0):

Use AskUserQuestion to let the user decide:

AskUserQuestion:
  questions:
    - header: "Missing Dependencies"
      question: "Some selected components depend on {external_selected_count + external_missing_count} components not in your selection. How would you like to handle this?"
      options:
        - label: "Add missing dependencies"
          description: "Include {count} additional components to resolve all references"
        - label: "Proceed without them"
          description: "Continue -- missing references will be flagged in the gap report"
        - label: "Go back to selection"
          description: "Return to component selection to adjust"
      multiSelect: false

If "Add missing dependencies":

  1. For each External-selected dependency: locate the component in its group directory, build its component entry (type, group, name, path), and add to SELECTED_COMPONENTS
  2. For each External-missing dependency: scan the component from disk using the component scanning conventions, build its entry, and add to SELECTED_COMPONENTS
  3. Re-run Steps 1 and 2 to capture any new transitive dependencies introduced by the added components
  4. Repeat the self-contained check (Step 3). If new missing dependencies are found, present Step 4 again. Continue until either the selection is self-contained or the user chooses to proceed without remaining dependencies.

If "Go back to selection": Return to Phase 2 Step 2.

If "Proceed without them": Continue to Step 5. Missing dependencies will be tracked as entries in CONVERSION_GAPS during Phase 5.

4b: Report Circular References

If circular references were detected (from Step 2d):

Display a warning after the missing dependencies resolution:

### Circular References Detected

WARNING: {CIRCULAR_REFS.length} circular dependency chain(s) found:

{For each cycle in CIRCULAR_REFS:}
- {cycle[0]} -> {cycle[1]} -> ... -> {cycle[0]}

These will be handled during conversion (Phase 5) using topological sort with cycle-breaking.
The component with the fewest incoming dependencies in each cycle will be processed first.

Circular references do not require user action -- they are informational warnings. Proceed to Step 5.

Step 5: Dependency Graph Summary

Build the final dependency graph summary and compute the conversion order for Phase 5.

5a: Topological Sort

Compute a dependency-sorted conversion order:

  1. Start with components that have zero unresolved dependencies (leaf nodes with no outgoing edges to other selected components)
  2. Process in layers: each layer contains components whose dependencies are all in previous layers
  3. Cycle-breaking: For components involved in circular references, break each cycle by placing the component with the fewest incoming edges first, then continue the sort normally
  4. Within each layer, sort alphabetically by {type}:{group}/{name} for deterministic ordering

Store the sorted list as CONVERSION_ORDER.

5b: Display Summary
## Dependency Graph

**Components:** {SELECTED_COMPONENTS.length}
**Internal dependencies:** {internal_count}
**External dependencies (to be flagged):** {external_count + external_missing_count}
**Circular references:** {CIRCULAR_REFS.length or "none"}
**System dependencies:** {system_count} Claude Code platform features

Conversion order (dependency-sorted):
1. {component_id} -- no dependencies
2. {component_id} -- depends on: {dep1}, {dep2}
3. {component_id} -- depends on: {dep1}
...
5c: Store Dependency Graph

Store the complete graph as DEPENDENCY_GRAPH for consumption by Phase 5:

DEPENDENCY_GRAPH = {
  nodes: SELECTED_COMPONENTS,
  edges: DEPENDENCIES,
  circular_refs: CIRCULAR_REFS,
  conversion_order: CONVERSION_ORDER,
  external_deps: [entries where dep_type == "external"],
  classification_counts: { internal, external_selected, external_missing, external, system }
}

Phase 4: Platform Research

Goal: Spawn a research subagent to investigate the target platform's current plugin architecture, compare findings against the existing adapter file, and produce a merged knowledge base for conversion.

Step 1: Prepare Research Context

Before spawning the research agent, gather the context it needs:

  1. Count selected components by type from SELECTED_COMPONENTS:

    • skill_count — number of skill components
    • agent_count — number of agent components
    • hook_count — number of hooks components
    • ref_count — total reference files across all selected skills
    • mcp_count — number of MCP config components
  2. Extract adapter content (if ADAPTER exists):

    • Read the full content of the adapter file at ${CLAUDE_PLUGIN_ROOT}/references/adapters/{TARGET_PLATFORM}.md
    • Store the raw content as ADAPTER_CONTENT for inclusion in the research prompt
    • Extract the adapter's target_platform_version field from the Adapter Version section
  3. Build component summary — a brief list of what is being ported, to help the research agent focus on relevant platform features:

    Components to convert:
    - Skills: {list of skill names}
    - Agents: {list of agent names with model tiers}
    - Hooks: {yes/no, with event types if yes}
    - References: {count} files
    - MCP configs: {yes/no, with server names if yes}
    
    Key features used by these components:
    - {e.g., "Task tool for subagent spawning (used by deep-analysis)"}
    - {e.g., "AskUserQuestion for interactive workflows (used by create-spec)"}
    - {e.g., "Cross-plugin composition via ${CLAUDE_PLUGIN_ROOT}/../ paths"}
    

Step 2: Launch Research Agent

Spawn the research agent using the Task tool with subagent_type: "researcher" and model: "sonnet":

Task tool prompt:
"Research the plugin/extension system for: {TARGET_PLATFORM}

You are researching this platform to support converting Agent Alchemy (Claude Code) plugins to {TARGET_PLATFORM} format. The conversion needs to handle {skill_count} skills, {agent_count} agents, {hook_count} hook configs, {ref_count} reference files, and {mcp_count} MCP configs.

{If ADAPTER exists:}
## Existing Adapter File

An adapter file already exists for this platform. Here is its full content:

---BEGIN ADAPTER---
{ADAPTER_CONTENT}
---END ADAPTER---

IMPORTANT: Compare your research findings against every mapping in this adapter file. In your Adapter Comparison section:
- Flag any mappings that appear outdated based on your research
- Identify new platform features or changes not covered by the adapter
- Note the adapter's platform version ({adapter_platform_version}) vs. the current version you find
- For each stale or missing mapping, provide the corrected/new mapping

{If ADAPTER is null:}
## No Existing Adapter

No adapter file exists for this platform yet. Research from scratch and produce a comprehensive platform profile. Your findings will be the primary source of truth for the conversion engine.

## Components Being Ported

{component_summary from Step 1}

## Research Focus Areas

Investigate these areas thoroughly — they directly affect conversion quality:

1. **Plugin directory structure**: Where plugins live, file naming conventions, required files
2. **Configuration format**: YAML, JSON, TOML, or other formats for plugin metadata
3. **Tool/capability equivalents**: What built-in tools does the platform provide? Map against Claude Code's tools (Read, Write, Edit, Glob, Grep, Bash, Task, WebSearch, WebFetch, AskUserQuestion)
4. **Model configuration**: How are AI models specified? Does the platform support model tiers or selection?
5. **Lifecycle hooks**: Does the platform have pre/post execution hooks? Event system?
6. **Composition mechanism**: How do plugins load or reference other plugins? Is there an equivalent to skill composition via prompt injection?
7. **Path resolution**: Equivalent of ${CLAUDE_PLUGIN_ROOT} for resolving plugin-relative paths
8. **Agent/subagent support**: Can plugins spawn sub-tasks or sub-agents? How?
9. **User interaction**: How do plugins prompt the user for input during execution?
10. **MCP integration**: Does the platform support Model Context Protocol servers?

Return a structured platform profile following your output format specification. Include confidence levels for every finding."

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

Step 3: Process Research Findings

When the research agent returns its platform profile:

  1. Parse the structured platform profile from the response. Extract these sections:

    • Research Summary (documentation quality, sources consulted, overall confidence)
    • Plugin System Overview
    • Directory Structure
    • File Format
    • Tool Equivalents table
    • Model Tier Mappings table
    • Composition Patterns
    • Lifecycle Hooks
    • Known Limitations
    • Adapter Comparison (if adapter was provided)
    • Sources list
  2. Store as RESEARCH_FINDINGS — the parsed profile is available throughout the remaining phases for the conversion engine to reference.

  3. Merge research with adapter into CONVERSION_KNOWLEDGE:

    The conversion engine uses a merged knowledge base called CONVERSION_KNOWLEDGE that combines the adapter file and research findings with clear precedence rules:

    CategoryPrecedence Rule
    Tool name mappingsAdapter takes precedence for established mappings; research fills gaps where adapter has null or no entry
    Model tier mappingsAdapter takes precedence; research supplements with version-specific notes
    Platform version infoResearch always takes precedence (it is fresher)
    Directory structureResearch takes precedence if it differs from adapter (platform may have changed)
    Composition patternsResearch takes precedence if it provides more detail; adapter is baseline
    Lifecycle hooksResearch takes precedence if it finds new hook types; adapter is baseline
    Known limitationsUnion of both — all limitations from adapter AND research are tracked
    Path resolutionResearch takes precedence if adapter mapping is marked as uncertain

    When adapter and research agree on a mapping, mark it as confidence: high. When only one source provides a mapping, mark it as confidence: medium. When adapter and research disagree, mark it as confidence: conflict and flag for user resolution in Step 4.

  4. Check for adapter staleness:

    Initialize STALENESS_STATUS to track the result for migration guide logging:

    STALENESS_STATUS = {
      checked: false,
      adapter_version: null,
      adapter_platform_version: null,
      research_platform_version: null,
      is_stale: false,
      is_unversioned: false,
      research_has_version: false,
      stale_mappings: [],
      new_features: [],
      user_decision: null,
      error: null
    }
    

    Wrap the entire staleness check in error-safe logic. If any step below fails (parsing error, unexpected format, etc.), set STALENESS_STATUS.error to a description of the failure, log a warning ("Staleness check encountered an error: {error}. Proceeding with conversion."), and continue to Step 4. The staleness check must never block the conversion workflow.

    If ADAPTER exists:

    a. Read adapter version fields from the Adapter Version section of the adapter file:

    • Extract adapter_version (the adapter file's own version, e.g., 1.0.0)
    • Extract target_platform_version (the platform version the adapter was written for, e.g., 0.0.55)
    • Set STALENESS_STATUS.checked = true
    • If neither field is found, set STALENESS_STATUS.is_unversioned = true and log a warning: "Adapter file for {TARGET_PLATFORM} has no version fields. Staleness cannot be determined — proceeding with adapter as-is."

    b. Check if research reported a platform version:

    • Look for a version in the research findings (Platform Overview, Research Summary, or version-related fields)
    • If research did not report a version, set STALENESS_STATUS.research_has_version = false and log a note: "Research did not report a specific platform version for {TARGET_PLATFORM}. Skipping version comparison."
    • If research reported a version, set STALENESS_STATUS.research_has_version = true and store it in STALENESS_STATUS.research_platform_version

    c. Compare versions (only if both adapter and research have version information):

    • Perform version comparison using these rules:
      • Exact match: If target_platform_version equals research_platform_version exactly, versions match — STALENESS_STATUS.is_stale = false
      • Semantic version comparison: If both versions follow semver format (e.g., 0.0.55, 1.2.3), compare numerically. If research version is newer, set STALENESS_STATUS.is_stale = true
      • Fuzzy comparison: If version formats differ (e.g., adapter has 0.0.55 but research reports v0.0.55, 0.0.55-beta, or a date-based version), attempt normalization:
        • Strip leading v or V prefix
        • Strip trailing pre-release suffixes (-alpha, -beta, -rc.1, etc.) for comparison
        • If normalized versions match, treat as matching
        • If normalization fails or formats are incomparable, set STALENESS_STATUS.is_stale = true (err on the side of warning) and note: "Version format mismatch — adapter: '{adapter_version}', research: '{research_version}'. Treating as potentially stale."

    d. Collect stale mappings and new features (regardless of version match, if research provides an Adapter Comparison section):

    • If the Adapter Comparison section flags outdated mappings, collect them as STALE_MAPPINGS and store in STALENESS_STATUS.stale_mappings
    • If the research found new platform features not in the adapter, collect them as NEW_FEATURES and store in STALENESS_STATUS.new_features
    • If stale mappings or new features exist even when versions match, set ADAPTER_STALE = true (content staleness despite version match)

Step 4: Resolve Conflicts

If any mappings in CONVERSION_KNOWLEDGE are marked as confidence: conflict:

  1. Build a conflict list summarizing each disagreement:

    Conflicts found between adapter file and research findings:
    
    1. {mapping_name}:
       - Adapter says: {adapter_value}
       - Research says: {research_value} (source: {url})
       - Impact: {which components are affected}
    
    2. {mapping_name}:
       ...
    
  2. Present conflicts to user via AskUserQuestion for each conflict (or batch if fewer than 5):

    AskUserQuestion:
      questions:
        - header: "Research Conflict"
          question: "The adapter file and fresh research disagree on {mapping_name}. Which should be used for conversion?"
          options:
            - label: "Use research finding"
              description: "{research_value} — from {source}, researched today"
            - label: "Use adapter mapping"
              description: "{adapter_value} — from adapter file v{adapter_version}"
            - label: "Skip this mapping"
              description: "Flag as unresolved in the gap report"
          multiSelect: false
    
  3. Apply resolutions to CONVERSION_KNOWLEDGE:

    • "Use research finding": Update the mapping to the research value, set confidence: high, mark source: research
    • "Use adapter mapping": Keep the adapter value, set confidence: high, mark source: adapter
    • "Skip this mapping": Set confidence: unresolved, will appear in the gap report

If there are no conflicts, skip this step entirely.

Step 5: Present Research Summary

Display a summary of the research findings and merged knowledge to the user:

## Platform Research: {TARGET_PLATFORM}

**Documentation quality:** {research_summary.documentation_quality}
**Sources consulted:** {research_summary.sources_consulted}
**Overall confidence:** {research_summary.overall_confidence}

### Key Findings
- **Plugin format:** {file_format description}
- **Tool equivalents:** {matched_count}/{total_count} Claude Code tools have equivalents
- **Model support:** {model_tier_summary}
- **Composition:** {composition_patterns summary}
- **Hooks:** {lifecycle_hooks summary — supported/not supported/partial}
- **Agent spawning:** {agent/subagent support summary}
- **User interaction:** {user interaction mechanism summary}

### Knowledge Sources for Conversion
- Adapter file mappings: {count} mappings
- Research-supplemented mappings: {count} new/updated mappings
- Conflicts resolved: {count}
- Unresolved gaps: {count}

{If STALENESS_STATUS.is_unversioned = true:}
### Adapter Version Notice

NOTE: The adapter file for {TARGET_PLATFORM} has no version fields. Staleness cannot be determined. The adapter will be used as-is, supplemented by research findings.

{If STALENESS_STATUS.research_has_version = false AND ADAPTER exists:}
### Research Version Notice

NOTE: Research did not report a specific platform version for {TARGET_PLATFORM}. Version comparison was skipped. The adapter's target_platform_version ({STALENESS_STATUS.adapter_platform_version}) is assumed current.

{If STALENESS_STATUS.error:}
### Staleness Check Notice

NOTE: The staleness check encountered an error: {STALENESS_STATUS.error}. Conversion will proceed using available adapter and research data.

{If ADAPTER_STALE = true:}
### Adapter Staleness Warning

WARNING: The existing adapter file targets {TARGET_PLATFORM} v{STALENESS_STATUS.adapter_platform_version}, but research found the current version is v{STALENESS_STATUS.research_platform_version}.

Stale mappings detected:
{For each stale mapping in STALENESS_STATUS.stale_mappings:}
- {mapping_name}: adapter says "{old_value}", research found "{new_value}"

New platform features not in adapter:
{For each new feature in STALENESS_STATUS.new_features:}
- {feature_name}: {description}

{If no ADAPTER:}
### New Platform Profile

Research produced a fresh platform profile since no adapter file existed.
Consider saving a new adapter file from these findings after conversion.

After displaying the summary, if ADAPTER_STALE = true, present the user with options via AskUserQuestion:

AskUserQuestion:
  questions:
    - header: "Adapter Staleness"
      question: "The adapter file for {TARGET_PLATFORM} appears to be stale (adapter targets v{STALENESS_STATUS.adapter_platform_version}, research found v{STALENESS_STATUS.research_platform_version}). {stale_mapping_count} mappings may be outdated and {new_feature_count} new platform features were found. How would you like to proceed?"
      options:
        - label: "Proceed with existing adapter"
          description: "Continue conversion — research findings will supplement and override stale adapter mappings via CONVERSION_KNOWLEDGE precedence rules"
        - label: "Update adapter file first"
          description: "Pause conversion to update the adapter file with research findings, then resume"
      multiSelect: false

Handle each choice:

  • "Proceed with existing adapter": Set STALENESS_STATUS.user_decision = "proceed". Continue to Phase 5 using CONVERSION_KNOWLEDGE as already merged (research takes precedence for stale mappings per the precedence rules in Step 3). Log: "User chose to proceed with existing adapter. Research findings will supplement stale mappings during conversion."

  • "Update adapter file first": Set STALENESS_STATUS.user_decision = "update". Before continuing to Phase 5:

    1. Read the current adapter file at ${CLAUDE_PLUGIN_ROOT}/references/adapters/{TARGET_PLATFORM}.md
    2. Apply research findings to update stale mappings in-place:
      • For each entry in STALE_MAPPINGS: update the mapping value in the adapter to match the research finding
      • For each entry in NEW_FEATURES: add the feature to the appropriate adapter section
      • Update the target_platform_version field to the research-reported version
      • Update the last_updated field to today's date
      • Increment the adapter_version patch number (e.g., 1.0.0 -> 1.0.1)
      • Append to the changelog field describing the update
    3. Write the updated adapter file
    4. Re-read the updated adapter as ADAPTER and re-merge into CONVERSION_KNOWLEDGE
    5. Log: "Adapter file updated to target {TARGET_PLATFORM} v{research_platform_version}. Conversion will use updated mappings."

If STALENESS_STATUS.is_unversioned = true and stale mappings or new features were found, also present the AskUserQuestion above (since content can be stale even without version fields).

Record staleness status for migration guide:

Store STALENESS_STATUS for inclusion in the migration guide output (Phase 6). The migration guide should include a "Platform Adapter Status" section documenting:

  • Whether a staleness check was performed
  • Adapter version vs. research-reported version (if available)
  • Whether the adapter was stale, unversioned, or current
  • What decision the user made (proceed or update)
  • Any stale mappings that were identified
  • Any new features discovered by research

Step 6: Handle Research Failure

If the research agent failed (both initial attempt and retry):

  1. Inform the user of what happened:

    The platform research agent was unable to complete its investigation.
    Reason: {error_message or "timeout/empty response"}
    
  2. Offer recovery options via AskUserQuestion:

    AskUserQuestion:
      questions:
        - header: "Research Issue"
          question: "The platform research agent encountered an issue: {brief_reason}. How would you like to proceed?"
          options:
            - label: "Retry research"
              description: "Launch the research agent again (attempt {retry_count + 1})"
            - label: "Use adapter only"
              description: "Proceed with existing adapter file mappings (no fresh research)"
            - label: "Cancel"
              description: "Exit the porter"
          multiSelect: false
    
  3. Handle each choice:

    • "Retry research": Return to Step 2 and re-launch the research agent. Allow up to 2 total retries (3 attempts total).

    • "Use adapter only":

      • If ADAPTER exists: Set RESEARCH_FINDINGS = null. Set CONVERSION_KNOWLEDGE to adapter mappings only with confidence: medium on all entries (no research validation). Inform the user: "Proceeding with adapter file mappings only. Conversion quality may be affected — adapter mappings have not been validated against current platform documentation." Continue to Phase 5.
      • If ADAPTER is null: Inform the user: "Cannot proceed — no adapter file exists and research failed. The conversion engine requires at least one source of platform knowledge." Offer:
        AskUserQuestion:
          questions:
            - header: "No Platform Knowledge Available"
              question: "Neither an adapter file nor research findings are available. What would you like to do?"
              options:
                - label: "Retry research"
                  description: "Try the research agent one more time"
                - label: "Cancel"
                  description: "Exit the porter — conversion cannot proceed without platform knowledge"
              multiSelect: false
        
    • "Cancel": End the workflow gracefully with a summary of what was completed so far.


Phase 4.5: Dry-Run Preview

Goal: Offer an optional preview of expected conversion output -- showing the target file tree, per-component conversion status, expected issues, and estimated fidelity -- without writing any files or running the full conversion engine.

This phase consumes SELECTED_COMPONENTS, DEPENDENCY_GRAPH (from Phase 3), and CONVERSION_KNOWLEDGE (from Phase 4). It does not modify any of these structures.

Step 1: Offer Dry-Run Preview

If DRY_RUN = true (set via --dry-run flag): Skip the offer and proceed directly to Step 2 (preview is mandatory).

If DRY_RUN = false: Use AskUserQuestion to offer the preview as an optional step:

AskUserQuestion:
  questions:
    - header: "Dry-Run Preview"
      question: "Would you like to preview the expected conversion output before proceeding? This shows the target file tree, per-component status, and expected issues without writing any files."
      options:
        - label: "Run preview"
          description: "Generate and display a dry-run preview of the conversion"
        - label: "Skip preview and convert"
          description: "Proceed directly to interactive conversion (Phase 5)"
      multiSelect: false

If "Skip preview and convert": Skip the rest of Phase 4.5 and proceed directly to Phase 5.

If "Run preview": Continue to Step 2.

Step 2: Generate Preview

Generate the preview by analyzing CONVERSION_KNOWLEDGE mappings against each component in SELECTED_COMPONENTS. This step predicts conversion outcomes without running the full conversion engine.

Wrap the entire preview generation in error-safe logic. If any step below fails (parsing error, unexpected format, etc.), log a warning ("Preview generation encountered an error: {error}. You can still proceed with conversion."), skip to Step 4 (user decision), and offer the option to proceed with conversion despite the preview failure.

2a: Build Target File Tree

For each component in SELECTED_COMPONENTS, predict the output file path using CONVERSION_KNOWLEDGE:

  1. Skills: Map source path claude/{group}/skills/{name}/SKILL.md to target path using directory structure mappings:

    • Check CONVERSION_KNOWLEDGE for skill_file_pattern in directory structure mappings
    • If skill_file_pattern is defined (e.g., {name}/SKILL.md): expand the pattern by replacing {name} with the skill name (applying naming_convention), then build path: {plugin_root}/{skill_dir}/{expanded_pattern} (e.g., .opencode/skills/deep-analysis/SKILL.md)
    • If no skill_file_pattern: apply naming_convention and file_extension for a flat filename, then build path: {plugin_root}/{skill_dir}/{converted_filename}
  2. Agents: Map source path claude/{group}/agents/{name}.md to target path:

    • If the target platform has an agent concept: {plugin_root}/{agent_dir}/{converted_filename}
    • If no agent concept (adapter maps agent type to null or alternative): note the mapping strategy (e.g., "merged into skill" or "mapped to fixed type")
  3. Hooks: Map claude/{group}/hooks/hooks.json to the target hooks format:

    • If target supports hooks: {plugin_root}/{hook_dir}/{target_hook_filename}
    • If no hook support: note as "unsupported -- will be documented in gap report"
  4. References: For each reference file in selected skills' references/ directories:

    • If target supports reference directories: {plugin_root}/{reference_dir}/{filename}
    • If no reference support (composition is none or inline): note as "will be inlined into parent skill"
  5. MCP configs: Map claude/{group}/.mcp.json to the target MCP format:

    • If target supports MCP: {plugin_root}/{config_dir}/{target_mcp_filename}
    • If no MCP support: note as "unsupported -- will be documented in gap report"

Store the predicted paths as PREVIEW_FILE_TREE -- a list of entries, each containing: { source_path, target_path, component_type, component_name, mapping_strategy }.

2b: Predict Per-Component Conversion Status

For each component, estimate its conversion status by analyzing how well CONVERSION_KNOWLEDGE covers the component's features:

  1. Read the component source file (already loaded during Phase 2/3)
  2. Count mappable features:
    • Frontmatter fields: count fields, check how many have non-null mappings in frontmatter mappings
    • Tool references: count tools in allowed-tools and body, check how many have non-null mappings in tool name mappings
    • Composition references: count ${CLAUDE_PLUGIN_ROOT} patterns, check if composition mechanism is not none
    • Path references: count path patterns, check if path resolution root variable is not null
    • User interaction patterns: count AskUserQuestion references, check if a mapping exists
  3. Classify the component:
    • Count supported (non-null mapping exists), partial (mapping is partial:* or workaround-dependent), and unsupported (mapping is null) features
    • Apply fidelity estimation to calculate a score range:
      optimistic_score = ((supported + partial) * 1.0 + unsupported * 0.0) / total * 100
      pessimistic_score = ((supported * 1.0) + (partial * 0.7) + (unsupported * 0.0)) / total * 100
      
    • Determine predicted status:
      • Both scores >= 80: "Full" -- component is highly portable
      • Pessimistic >= 50: "Partial" -- component works but with limitations
      • Pessimistic < 50: "Unsupported" -- significant gaps, may not be worthwhile

Store predictions as PREVIEW_STATUS -- a list of entries, each containing: { component_name, component_type, group, supported_count, partial_count, unsupported_count, total_count, optimistic_score, pessimistic_score, predicted_status }.

2c: Collect Expected Issues

For each component, identify expected issues from the mapping analysis:

  1. Null tool mappings: List tools that map to null in tool name mappings
  2. Null frontmatter fields: List fields that map to null in frontmatter mappings
  3. Unsupported composition: Flag if composition mechanism is none and component uses composition
  4. Unsupported hooks: Flag if hook events map to null in hook event mappings
  5. Missing cross-plugin support: Flag if component uses cross-plugin references and composition does not support cross-plugin
  6. No user interaction equivalent: Flag if component uses AskUserQuestion and the mapping is null

Group issues by severity:

  • Critical: Features essential to the component's core function (e.g., Task tool for hub-and-spoke skills)
  • Functional: Features that affect behavior but the component can work without them (e.g., specific tool references)
  • Cosmetic: Minor formatting or metadata differences (e.g., omitted frontmatter fields)

Store as PREVIEW_ISSUES -- a list of entries, each containing: { component_name, feature, severity, reason, adapter_notes }.

2d: Calculate Estimated Fidelity Range

Compute an overall estimated fidelity range across all components:

overall_optimistic = sum(component.optimistic_score * component.weight) / sum(component.weight)
overall_pessimistic = sum(component.pessimistic_score * component.weight) / sum(component.weight)

Where weight is the same as Phase 5 Step 9:

  • skill = 3, agent = 2, hooks = 1, reference = 1, mcp = 1

Round both scores to the nearest integer.

Step 3: Display Preview

Present the preview in a structured format.

Large plugin group handling: If SELECTED_COMPONENTS has more than 20 components, summarize the file tree by grouping files by directory rather than listing every individual file. Show the directory structure with file counts per directory instead.

## Dry-Run Preview: {TARGET_PLATFORM}

**Components:** {SELECTED_COMPONENTS.length}
**Estimated fidelity:** {overall_pessimistic}% - {overall_optimistic}%

### Target File Tree

{If 20 or fewer components:}

{target_root}/
  {For each entry in PREVIEW_FILE_TREE, sorted by target_path:}
  {target_path}    <- {source_path} [{mapping_strategy}]

{If more than 20 components:}

{target_root}/
  {skill_dir}/          ({skill_count} files)
  {agent_dir}/          ({agent_count} files)
  {hook_dir}/           ({hook_count} files)
  {reference_dir}/      ({ref_count} files)
  {config_dir}/         ({config_count} files)

### Per-Component Conversion Status

| Component | Type | Group | Status | Fidelity Estimate | Issues |
|-----------|------|-------|--------|-------------------|--------|
{For each entry in PREVIEW_STATUS:}
| {component_name} | {component_type} | {group} | {predicted_status} | {pessimistic_score}% - {optimistic_score}% | {issue_count} |

{If all components have predicted_status == "Unsupported":}
### Warning: All Components Unsupported

All selected components are predicted to have significant conversion gaps on {TARGET_PLATFORM}. The overall estimated fidelity is {overall_pessimistic}% - {overall_optimistic}%. Conversion may not produce useful output. Consider:
- Selecting a different target platform
- Selecting fewer, simpler components
- Reviewing the gap details below before proceeding

### Expected Issues

{If PREVIEW_ISSUES is empty:}
No significant issues detected. All features have direct or partial mappings.

{If PREVIEW_ISSUES is not empty:}
{Group by severity, show critical first:}

**Critical ({critical_count}):**
{For each critical issue:}
- **{component_name}**: `{feature}` -- {reason}{If adapter_notes: " ({adapter_notes})"}

**Functional ({functional_count}):**
{For each functional issue:}
- **{component_name}**: `{feature}` -- {reason}

**Cosmetic ({cosmetic_count}):**
{For each cosmetic issue:}
- **{component_name}**: `{feature}` -- {reason}

### Estimated Fidelity

**Overall:** {overall_pessimistic}% - {overall_optimistic}% (weighted by component complexity)

The fidelity range reflects the best-case (all partial mappings succeed fully) and worst-case (partial mappings contribute reduced fidelity) scenarios. The actual score will be determined during interactive conversion when incompatibilities are resolved.

Step 4: User Decision

After displaying the preview, present the user with a decision via AskUserQuestion.

If DRY_RUN = true (invoked with --dry-run flag):

AskUserQuestion:
  questions:
    - header: "Dry-Run Complete"
      question: "The dry-run preview is complete. No files were written. Would you like to proceed with the actual conversion?"
      options:
        - label: "Proceed with conversion"
          description: "Continue to Phase 5 (Interactive Conversion) and convert the selected components"
        - label: "Done"
          description: "Exit the porter -- preview only"
      multiSelect: false

If DRY_RUN = false (preview was offered and accepted):

AskUserQuestion:
  questions:
    - header: "Preview Complete"
      question: "Preview complete. Proceed with interactive conversion?"
      options:
        - label: "Proceed with conversion"
          description: "Continue to Phase 5 and convert the selected components"
        - label: "Cancel"
          description: "Exit the porter"
      multiSelect: false

Handle choices:

  • "Proceed with conversion": Set DRY_RUN = false (in case it was true). Continue to Phase 5.
  • "Done" or "Cancel": End the workflow gracefully. Display a brief summary:
    Porter exited after dry-run preview. No files were written.
    Components analyzed: {count}
    Estimated fidelity: {overall_pessimistic}% - {overall_optimistic}%
    

Phase 5: Wave-Based Conversion

Goal: Convert each selected component using a wave-based agent team, where each port-converter agent (Sonnet) handles a single component in an isolated context. The orchestrator (this skill, Opus) manages session files, spawns agent waves, resolves incompatibilities between waves, and consolidates results.

This phase consumes SELECTED_COMPONENTS, CONVERSION_ORDER, DEPENDENCY_GRAPH, and CONVERSION_KNOWLEDGE from Phases 2-4.

Step 1: Initialize Session

Create the session directory and write shared files that converter agents will read.

1a: Create Session Directory
mkdir -p .claude/sessions/__port_live__/results

If .claude/sessions/__port_live__/ already exists (stale session from a previous interrupted run):

  1. Archive the stale session: mv .claude/sessions/__port_live__ .claude/sessions/port-interrupted-{YYYYMMDD}-{HHMMSS}
  2. Recreate: mkdir -p .claude/sessions/__port_live__/results
  3. Log: "Archived stale porting session to .claude/sessions/port-interrupted-{timestamp}/"
1b: Serialize Conversion Knowledge

Write CONVERSION_KNOWLEDGE to .claude/sessions/__port_live__/conversion_knowledge.md following the format specified in ${CLAUDE_PLUGIN_ROOT}/skills/port-plugin/references/session-format.md.

The file contains all 9 adapter mapping sections (tool names, model tiers, skill frontmatter, agent frontmatter, hook events, directory structure, composition mechanism, path resolution, known limitations) serialized as markdown tables and key-value sections.

This file is written once and not modified during conversion.

1c: Serialize Dependency Graph

Write DEPENDENCY_GRAPH to .claude/sessions/__port_live__/dependency_graph.md following the session format reference.

Include: conversion order with wave assignments, dependency edges, circular references (if any), external dependencies, and classification counts.

This file is written once and not modified during conversion.

1d: Initialize Resolution Cache

Write an empty resolution cache to .claude/sessions/__port_live__/resolution_cache.md:

# Resolution Cache

## Cached Decisions

View the full port-plugin on GitHub

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:

ClassificationExamplesAction
StructuralFrontmatter changes, new/removed sections, tool list changes, new/removed AskUserQuestion blocksRe-run conversion logic
ContentPrompt text modifications, instruction wording, reference path changes, code/table contentTargeted text transformation
CosmeticWhitespace, formatting, comment text, markdown styling changesAuto-apply without prompting

Build SOURCE_CHANGES list. Each entry: file_path, change_type (modified/added/deleted/renamed), classification (structural/content/cosmetic), diff_summary, diff_lines_added, diff_lines_removed, affected_sections, and component_entry (matching PORT-METADATA component, or null for new files).

New files get classification: "structural" and diff_summary: "New component -- requires full port". Deleted files get classification: "structural" and diff_summary: "Source component deleted -- ported version may be orphaned".

Track B: Platform Changes

Skip this track if SOURCE_ONLY is true.

Step B1: Load Validate-Adapter Skill

Read the validate-adapter skill to access its platform validation logic:

Read: ${CLAUDE_PLUGIN_ROOT}/skills/validate-adapter/SKILL.md
Step B2: Run Platform Validation
  1. Load the adapter file: Read: ${CLAUDE_PLUGIN_ROOT}/references/adapters/{TARGET_PLATFORM}.md

  2. Spawn the researcher agent:

    Task:
      description: "Research current state of {TARGET_PLATFORM}'s plugin system. Compare against adapter. Focus on changes since v{PORT_METADATA.target_platform_version}."
      subagent_type: "agent-alchemy-plugin-tools:researcher"
      input: |
        Target platform: {TARGET_PLATFORM}
        Existing adapter file: ${CLAUDE_PLUGIN_ROOT}/references/adapters/{TARGET_PLATFORM}.md
        Last known platform version: {PORT_METADATA.target_platform_version}
    
  3. Collect the researcher's platform profile and adapter comparison results.

Step B3: Extract Platform Findings

From the researcher's adapter comparison results, extract three categories:

Categorize findings into three types:

TypeFieldsDefault Impact
staleadapter_section, old_mapping, new_mapping, affected_componentsbreaking or cosmetic
missingadapter_section, feature_description, potential_benefitadditive
removedadapter_section, feature_description, alternative, affected_componentsbreaking
Step B4: Classify Platform Impact

Classify each finding by cross-referencing against PORT_METADATA.components:

  • Breaking: Stale/removed mapping used by at least one ported component
  • Additive: New feature that could improve ported components but is not required
  • Cosmetic: Naming change or minor adjustment with no functional impact

Build PLATFORM_CHANGES list from the classified findings.

Combined Change Summary

After both tracks complete, present the combined results via AskUserQuestion:

AskUserQuestion:
  questions:
    - header: "Change Detection Summary"
      question: |
        Changes detected since the last port ({PORT_METADATA.port_date}):

        Source changes:
        - {count} files modified ({structural_count} structural, {content_count} content, {cosmetic_count} cosmetic)
        - {added_count} new files detected
        - {deleted_count} files deleted

        Platform changes ({TARGET_PLATFORM}):
        - {stale_count} stale mappings ({breaking_stale_count} breaking)
        - {missing_count} new platform features
        - {removed_count} removed features ({breaking_removed_count} breaking)

        Estimated update scope: {small/medium/large}

        How would you like to proceed?
      options:
        - label: "Apply all changes"
          description: "Process both source and platform changes"
        - label: "Source changes only"
          description: "Apply only source file updates, skip platform changes"
        - label: "Platform changes only"
          description: "Apply only platform-related updates, skip source changes"
        - label: "Select specific changes"
          description: "Choose individual changes to apply"
        - label: "Cancel"
          description: "Exit without making changes"
      multiSelect: false

Scope estimation:

  • Small: 0-3 total changes, all cosmetic or content
  • Medium: 4-10 total changes, or any structural source changes, or any additive platform changes
  • Large: 10+ total changes, or any breaking platform changes, or any new/deleted source files

If user selects "Select specific changes", present a detailed checklist:

AskUserQuestion:
  questions:
    - header: "Select Changes to Apply"
      question: "Select which changes to apply:"
      options:
        - label: "[source] {file_name} ({classification})"
          description: "{diff_summary}"
        - label: "[platform] {finding_type}: {description}"
          description: "Impact: {impact} -- affects {affected_count} component(s)"
      multiSelect: true

Store the user's selection as SELECTED_CHANGES with two sub-lists: selected_source_changes and selected_platform_changes.

If user selects "Cancel", exit gracefully.


Phase 3: Apply Source Changes

Goal: Incrementally update ported files to reflect source plugin modifications.

Skip this phase entirely if:

  • User selected "Platform changes only" in Phase 2
  • User selected "Cancel" in Phase 2
  • SOURCE_CHANGES is empty (no source changes detected)

Initialize tracking:

UPDATED_FILES = []      // files modified during this phase
SKIPPED_FILES = []      // files user chose to skip
NEW_COMPONENTS = []     // new source files that need full porting
DELETED_COMPONENTS = [] // source files deleted, ported versions potentially orphaned

Step 1: Apply Cosmetic Changes

Process all cosmetic changes first (these do not require user approval):

For each entry in SOURCE_CHANGES where classification == "cosmetic":

  1. Read the current ported target file: Read: {PORT_OUTPUT_DIR}/{component_entry.target}
  2. Apply whitespace and formatting changes to match the updated source
  3. Write the updated file using Edit tool
  4. Add to UPDATED_FILES with update_type: "cosmetic"

Log: Applied {count} cosmetic updates automatically.

Step 2: Process Modified Components (Structural and Content)

For each entry in SOURCE_CHANGES where change_type == "modified" and classification is "structural" or "content":

2a: Load Conversion Context
  1. Read the current source file:

    Read: {source_change.file_path}
    
  2. Read the current ported target file:

    Read: {PORT_OUTPUT_DIR}/{source_change.component_entry.target}
    
  3. Load the appropriate converter reference from ${CLAUDE_PLUGIN_ROOT}/references/:

    Source path containsLoad converter
    /agents/agent-converter.md
    /hooks/hook-converter.md
    /references/reference-converter.md
    .mcp.jsonmcp-converter.md
    Skills (default)adapters/{TARGET_PLATFORM}.md
  4. Also load the adapter file (adapters/{TARGET_PLATFORM}.md) if not already loaded.

2b: Apply Structural Changes

For structural changes, re-run conversion on the changed sections:

  1. Identify changed sections by comparing the diff against the file structure
  2. For each changed section: extract updated content, apply converter mapping rules, replace the corresponding section in the ported target
  3. For frontmatter changes: parse updated frontmatter, apply adapter mappings, merge with existing ported frontmatter (preserve target-specific fields, update source-derived fields)
  4. For allowed-tools / tools changes: map new tools through adapter equivalents, remove dropped tools, flag tools with no target equivalent
2c: Apply Content Changes

For content changes, apply targeted text transformations:

  1. Identify specific text changes from the diff and locate them in the ported target
  2. Apply converter mapping rules to transform the new text
  3. Replace the old text, preserving any target-platform-specific modifications from the original port
2d: Check for New Incompatibilities

Load the incompatibility resolver:

Read: ${CLAUDE_PLUGIN_ROOT}/references/incompatibility-resolver.md

Check if any of the changes introduce new incompatibilities with the target platform:

  • New tool references that have no target equivalent
  • New composition patterns not supported by the target
  • New agent configurations with no mapping

For each new incompatibility found, present it to the user:

AskUserQuestion:
  questions:
    - header: "New Incompatibility Detected"
      question: |
        The source change in {file_path} introduces a new incompatibility:

        Feature: {feature_description}
        Issue: {incompatibility_description}
        Severity: {critical/functional/cosmetic}

        How should this be handled?
      options:
        - label: "Apply workaround"
          description: "{workaround_description}"
        - label: "Add TODO placeholder"
          description: "Insert a TODO comment for manual resolution"
        - label: "Skip this change"
          description: "Do not apply this specific change"
      multiSelect: false
2e: Confirm and Apply

For each significant change (structural or content with incompatibilities), present a before/after preview:

AskUserQuestion:
  questions:
    - header: "Confirm Update: {file_name}"
      question: |
        Source change: {diff_summary}
        Affected section: {section_name}

        The ported file will be updated with the converted changes.
        Apply this update?
      options:
        - label: "Apply"
          description: "Update the ported file"
        - label: "Skip"
          description: "Leave the ported file unchanged for this change"
        - label: "Show diff"
          description: "View the detailed before/after comparison"
      multiSelect: false

If "Show diff", display before/after and re-ask. If "Apply", write with Edit and add to UPDATED_FILES. If "Skip", add to SKIPPED_FILES.

Step 3: Handle New Components

For each entry in SOURCE_CHANGES where change_type == "added":

AskUserQuestion:
  questions:
    - header: "New Source Component"
      question: |
        A new component was detected: {file_path}

        This file was added since the last port and requires a full conversion.
        The update skill handles incremental changes; full conversions are best
        handled by the port-plugin skill.
      options:
        - label: "Run /port-plugin for this component"
          description: "Recommended: use the full porting workflow for new components"
        - label: "Add to gap report"
          description: "Note this as an unported component in the gap report"
        - label: "Skip"
          description: "Ignore this new component"
      multiSelect: false

If "Run /port-plugin": add to NEW_COMPONENTS with action: "port" and inform user to run it after this update. If "Add to gap report": add with action: "gap".

Step 4: Handle Deleted Components

For each entry in SOURCE_CHANGES where change_type == "deleted":

AskUserQuestion:
  questions:
    - header: "Deleted Source Component"
      question: |
        Source component was deleted: {file_path}
        Ported version exists at: {PORT_OUTPUT_DIR}/{target_path}

        The source file no longer exists. What should we do with the ported version?
      options:
        - label: "Delete ported file"
          description: "Remove the ported version since its source no longer exists"
        - label: "Keep as orphaned"
          description: "Keep the ported file but mark it as orphaned in the migration guide"
        - label: "Skip"
          description: "Take no action"
      multiSelect: false

If "Delete": remove via Bash (rm {PORT_OUTPUT_DIR}/{target_path}) and add to DELETED_COMPONENTS. If "Keep as orphaned": prepend <!-- ORPHANED: Source file {source_path} was deleted on {date} --> and add to DELETED_COMPONENTS.


Phase 4: Apply Platform Changes

Goal: Update ported files to reflect changes in the target platform since the original port.

Skip this phase entirely if:

  • User selected "Source changes only" in Phase 2
  • User selected "Cancel" in Phase 2
  • PLATFORM_CHANGES is empty (no platform changes detected)

Step 1: Apply Breaking Changes

Process breaking changes first as they affect correctness.

1a: Stale Mappings

For each stale breaking change: identify affected ported files, locate stale mapping instances, and prepare replacements. Present each:

AskUserQuestion:
  questions:
    - header: "Stale Platform Mapping"
      question: |
        Platform mapping has changed for {TARGET_PLATFORM}:

        Section: {adapter_section}
        Old: {old_mapping}
        New: {new_mapping}

        Affected files ({affected_count}):
        {list of affected ported files}

        Apply the updated mapping?
      options:
        - label: "Apply to all affected files"
          description: "Update all {affected_count} file(s) with the new mapping"
        - label: "Apply selectively"
          description: "Choose which files to update"
        - label: "Skip"
          description: "Keep the current mapping (may cause issues on the platform)"
      multiSelect: false

If "Apply selectively", present each file individually. Apply updates via Edit and add to UPDATED_FILES with update_type: "platform_stale".

1b: Removed Features

For each removed breaking feature, identify affected files and present:

AskUserQuestion:
  questions:
    - header: "Removed Platform Feature"
      question: |
        {TARGET_PLATFORM} has removed or deprecated a feature used by ported components:

        Feature: {feature_description}
        {If alternative:}Alternative: {alternative}
        {If no alternative:}No direct alternative available.

        Affected files ({affected_count}):
        {list of affected ported files}

        How should this be handled?
      options:
        - label: "Apply alternative"
          description: "Replace with: {alternative}"
        - label: "Add TODO placeholder"
          description: "Insert a TODO comment for manual resolution"
        - label: "Remove feature usage"
          description: "Remove references to this feature from ported files"
        - label: "Keep as-is with warning"
          description: "Leave unchanged but add a deprecation warning comment"
      multiSelect: false

Apply the selected resolution to each affected file and add to UPDATED_FILES with update_type: "platform_removed".

Step 2: Apply Additive Changes

Present new platform features that could enhance ported components:

AskUserQuestion:
  questions:
    - header: "New Platform Features"
      question: |
        {TARGET_PLATFORM} has added new features since the last port.
        Select which ones to apply to your ported components:
      options:
        - label: "{feature_description}"
          description: "Benefit: {potential_benefit} -- affects {affected_count} component(s)"
      multiSelect: true

For each selected feature: identify benefiting files, apply using adapter mapping rules, add to UPDATED_FILES with update_type: "platform_additive". If none selected, log: No additive platform changes applied.

Step 3: Update Adapter File

After applying platform changes, offer to update the adapter file:

AskUserQuestion:
  questions:
    - header: "Update Adapter File"
      question: |
        The adapter file for {TARGET_PLATFORM} may be stale based on the platform changes detected.
        Would you like to update it?
      options:
        - label: "Update adapter"
          description: "Apply validated platform changes to the adapter file"
        - label: "Skip adapter update"
          description: "Leave the adapter file unchanged (note: it may be stale)"
      multiSelect: false

If "Update adapter": load validate-adapter (Read: ${CLAUDE_PLUGIN_ROOT}/skills/validate-adapter/SKILL.md), execute its update logic, and track the new version. If "Skip": log that adapter is stale and set ADAPTER_UPDATED = false.


Phase 5: Output & Refresh

Goal: Write all updated files, refresh the PORT-METADATA block, update the migration guide history, refresh the gap report, and present a final summary.

Step 1: Write Updated Files

For each file in UPDATED_FILES: if OUTPUT_DIR is specified, write to {OUTPUT_DIR}/{relative_target_path} (creating intermediate directories as needed); otherwise write in-place. Track results in WRITE_RESULTS (files_written and files_failed lists). If any writes fail, log the error and continue.

Step 2: Refresh PORT-METADATA

Get the current HEAD commit hash:

git rev-parse HEAD

Get today's date for the port_date field.

Build the updated PORT-METADATA block:

<!-- PORT-METADATA
source_commit: {current_HEAD_hash}
port_date: {today_date}
adapter_version: {new_adapter_version or PORT_METADATA.adapter_version if not updated}
target_platform: {PORT_METADATA.target_platform}
target_platform_version: {new_platform_version or PORT_METADATA.target_platform_version}
components:
{For each component in PORT_METADATA.components that was NOT deleted:}
  - source: {component.source}
    target: {component.target}
    fidelity: {updated_fidelity_score or original if unchanged}
{For any NEW components that were fully ported:}
  - source: {new_source_path}
    target: {new_target_path}
    fidelity: {new_fidelity_score}
PORT-METADATA -->

Fidelity score rules: Cosmetic/content changes keep original score. Structural changes and platform breaking changes trigger recalculation. Orphaned components are removed from the list.

Replace the old PORT-METADATA block in MIGRATION-GUIDE.md with the updated block using Edit tool.

Step 3: Append Update History

Add an update history entry to MIGRATION-GUIDE.md. If an ## Update History section already exists, append to it. If not, create it before the PORT-METADATA block.

## Update History

### {today_date} -- Incremental Update
- **Source changes**: {modified_count} files updated, {added_count} new, {deleted_count} deleted
- **Platform changes**: {stale_updated_count} mappings updated, {additive_applied_count} features added, {removed_handled_count} removals handled
- **Scope**: {source-only|platform-only|full}
- **Skipped**: {skipped_count} changes skipped by user
- **Components affected**: {affected_component_count}/{total_component_count}

If the Update History section already has entries, append the new entry at the top (most recent first).

Step 4: Refresh GAP-REPORT.md

Check if a GAP-REPORT.md exists in PORT_OUTPUT_DIR:

Glob: {PORT_OUTPUT_DIR}/GAP-REPORT.md

If exists: Read it, remove entries that were resolved by this update (mark as RESOLVED with date), add new entries for any new gaps (incompatibilities, removed features, skipped breaking changes), and write the updated file.

If does not exist: Create a new GAP-REPORT.md (following port-plugin format) only if there are new gaps. If no new gaps, do not create one.

Step 5: Final Summary

Present the update results via AskUserQuestion:

AskUserQuestion:
  questions:
    - header: "Update Complete"
      question: |
        Update summary for {TARGET_PLATFORM} port:

        Files updated: {WRITE_RESULTS.files_written.length}
        {For each file: - {path} ({update_type})}

        New gaps introduced: {new_gap_count}
        Gaps resolved: {resolved_gap_count}
        Metadata refreshed: yes
        Adapter updated: {yes/no}

        Components:
        - Updated: {updated_count}
        - Skipped: {skipped_count}
        - New (needs full port): {new_component_count}
        - Deleted/orphaned: {deleted_count}

        Next steps:
        {If NEW_COMPONENTS with action "port":}
        1. Run /port-plugin --target {TARGET_PLATFORM} for {new_count} new component(s)
        {If SKIPPED_FILES.length > 0:}
        2. Review {skipped_count} skipped change(s) for manual handling
        {If ADAPTER_UPDATED == false and PLATFORM_CHANGES.length > 0:}
        3. Consider updating the adapter file with /validate-adapter --target {TARGET_PLATFORM}
        4. Test updated plugins on {TARGET_PLATFORM}
        5. Review MIGRATION-GUIDE.md for full update history
      options:
        - label: "Done"
          description: "Finish the update workflow"
        - label: "View updated files"
          description: "List all files that were modified"
        - label: "Run another update"
          description: "Check for additional changes"
      multiSelect: false

If "View updated files": list all written files with paths and update types, then re-present options. If "Run another update": return to Phase 1 Step 3 (re-locate migration guide with refreshed metadata).


Error Handling

If any phase fails:

  1. Explain what went wrong
  2. Use AskUserQuestion to ask how to proceed:
    AskUserQuestion:
      questions:
        - header: "Error Recovery"
          question: "{Description of what failed}. How would you like to proceed?"
          options:
            - label: "Retry this phase"
              description: "Attempt the failed phase again"
            - label: "Skip to next phase"
              description: "Continue without this phase's output"
            - label: "Cancel"
              description: "Exit the update workflow"
          multiSelect: false
    

Specific Error Scenarios

Git history unavailable: If git commands fail (not a git repo, corrupted history):

  • Log: WARNING: Git history is unavailable. Source change detection requires git history.
  • If SOURCE_ONLY or full update: cannot detect source changes, offer to proceed with platform changes only or cancel
  • If PLATFORM_ONLY: git is not needed, continue normally

Adapter file missing: If the adapter file for TARGET_PLATFORM does not exist:

  • Log: WARNING: No adapter file found for {TARGET_PLATFORM}. Platform change detection is limited.
  • Source changes can still be applied using generic conversion logic
  • Platform changes cannot be fully evaluated without an adapter

Ported file write conflict: If a target file has been manually edited since the last port (detected by comparing file modification time against PORT_METADATA.port_date):

  • Warn the user that the file appears to have manual edits
  • Offer: "Overwrite", "Merge manually", or "Skip"

Reference Files

  • references/adapter-format.md -- Adapter file format specification (9 mapping sections)
  • references/agent-converter.md -- Agent conversion logic (frontmatter mapping, body transformation, gap handling, fidelity scoring)
  • references/hook-converter.md -- Hook conversion logic (event mapping, behavioral classification, workaround strategies)
  • references/reference-converter.md -- Reference file conversion logic (discovery, path transformation, flattening)
  • references/mcp-converter.md -- MCP config conversion logic (server mapping, transport types, tool reference renaming, platform support detection)
  • references/incompatibility-resolver.md -- Incompatibility detection, interactive resolution, batch handling, decision tracking
  • references/adapters/ -- Directory for per-platform adapter files (one markdown file per target platform)

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
    
  2. Present available options:
    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

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
  3. Display brief research summary as a progress update (text output, not AskUserQuestion):
    Research complete:
    - Documentation quality: ${documentation_quality}
    - Overall confidence: ${overall_confidence}
    - Sources consulted: ${sources_count} (${official_count} official, ${community_count} community)
    - Platform version found: ${research_platform_version} (adapter targets: ${target_platform_version})
    

Step 3: Handle Research Failure

If the researcher agent fails or returns empty results:

  1. Inform the user of the failure
  2. Offer options:
    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
    
  3. If "Retry research": go back to Step 1
  4. If "Manual validation": proceed to Phase 3 with empty research findings (all entries will be classified as "Uncertain")
  5. 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:

ClassificationMeaningCriteria
CurrentMatches research findingsAdapter value aligns with what research found; no changes needed
StaleOutdated informationResearch has newer/different data for this entry; adapter needs updating
MissingNot in adapterPlatform has features/capabilities that the adapter does not cover
RemovedNo longer supportedAdapter references features the platform has deprecated or removed
UncertainCannot determineResearch 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} |

        ${stale_count + missing_count + removed_count > 0 ?
          stale_count + " stale, " + missing_count + " missing, and " + removed_count + " removed entries found." :
          "All entries are current. No updates needed."}

        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 the adapter file with research-backed corrections (requires --update flag)"
        - label: "Export report"
          description: "Write validation report to a markdown file"
      multiSelect: false

Step 2: View Detailed Findings

If the user selects "View detailed findings":

  1. Present the full per-entry breakdown grouped by classification:

    Stale Entries (if any): Show the stale entries detail list with current value, suggested value, and source.

    Missing Entries (if any): Show the missing entries detail list with feature name, description, and suggested mapping.

    Removed Entries (if any): Show the removed entries detail list with entry name, current value, and evidence.

    Uncertain Entries (if any): Show uncertain entries with a note explaining the low research confidence.

    Current Entries (if any): Show a summary count per section (do not list every current entry individually).

  2. After presenting details, re-present the action choice:

    AskUserQuestion:
      questions:
        - header: "Next Steps"
          question: "What would you like to do with these findings?"
          options:
            - label: "Apply updates"
              description: "Update the adapter file with research-backed corrections"
            - label: "Export report"
              description: "Write validation report to a markdown file"
            - label: "Done"
              description: "Exit without taking action"
          multiSelect: false
    

Step 3: Apply Updates

If the user selects "Apply updates":

Guard check: If UPDATE_MODE = false, inform the user:

Update mode is not enabled. Re-run with the --update flag to apply changes:
  /validate-adapter --target ${TARGET_PLATFORM} --update

Then return to the action choice prompt.

If UPDATE_MODE = true, proceed with updates:

  1. Update stale entries: For each stale entry in the validation report:

    • Read the current adapter file section containing the entry
    • Use Edit to replace the old value with the research-suggested value
    • Record the change: { section, entry, old_value, new_value }
  2. Add missing entries: For each missing entry in the validation report:

    • Determine the correct adapter section for the new entry
    • Use Edit to add the new entry in the appropriate location within the section
    • Follow the formatting conventions of the existing entries in that section
    • Record the addition: { section, entry, new_value }
  3. Handle removed entries: For each removed entry, ask the user individually:

    AskUserQuestion:
      questions:
        - header: "Removed Feature: ${entry_name}"
          question: |
            The adapter references "${entry_name}" in the ${section} section,
            but research indicates this feature has been removed from ${TARGET_PLATFORM}.
    
            Evidence: ${evidence}
    
            What should be done with this entry?
          options:
            - label: "Remove entry"
              description: "Delete this entry from the adapter"
            - label: "Keep with deprecation note"
              description: "Keep the entry but add a deprecation note"
          multiSelect: false
    
    • If "Remove entry": use Edit to remove the entry from the adapter
    • If "Keep with deprecation note": use Edit to append [DEPRECATED] to the entry's notes column
  4. Update metadata: In the Adapter Version section:

    • Bump adapter_version patch number (e.g., 1.0.0 -> 1.0.1)
    • Update last_updated to today's date (ISO 8601 format)
    • Update target_platform_version to research_platform_version if it changed
    • Append to the changelog field:
      ${new_version} (${today}): Validation-driven update — ${stale_count} stale entries updated, ${missing_count} missing entries added, ${removed_count} removed entries handled.
      
  5. Write updated adapter file:

    Write: ${CLAUDE_PLUGIN_ROOT}/references/adapters/${TARGET_PLATFORM}.md
    
  6. Display update summary:

    Adapter updated successfully:
    - Stale entries updated: ${updated_stale_count}
    - Missing entries added: ${added_missing_count}
    - Removed entries handled: ${handled_removed_count}
    - New adapter version: ${new_version}
    - Target platform version: ${research_platform_version}
    

Step 4: Export Report

If the user selects "Export report":

  1. Determine the output directory:

    • If an OUTPUT_DIR was provided by a caller (sub-workflow mode), use it
    • Otherwise default to the project root
  2. Write the validation report as markdown:

    Write: ${OUTPUT_DIR}/adapter-validation-${TARGET_PLATFORM}.md
    

    The report file should include:

    • Report header with platform name, date, and health score
    • Per-section breakdown table
    • Stale entries detail list
    • Missing entries detail list
    • Removed entries detail list
    • Uncertain entries list with confidence notes
    • Research sources consulted
    • Recommendation (update adapter / adapter is current / insufficient data)
  3. Inform the user of the export location:

    Validation report exported to: ${OUTPUT_DIR}/adapter-validation-${TARGET_PLATFORM}.md
    

Error Handling

Missing Adapter File

Handled in Phase 1 Step 3. The user is offered available alternatives or informed that no adapters exist.

Researcher Agent Failure

Handled in Phase 2 Step 3. The user can retry, proceed with structural validation only, or cancel.

Empty Research Results

If the researcher returns a profile with all sections marked as "unknown" or confidence "low":

  • Proceed to Phase 3 but classify all entries as Uncertain
  • In Phase 4, note that the health score is "N/A" due to insufficient research data
  • Recommend the user provide documentation URLs directly or try again later

Malformed Adapter File

If the adapter file cannot be parsed (missing H2 headers, unrecognized structure):

  1. Report which sections were found and which are missing or malformed
  2. Offer to validate only the parseable sections
  3. Note structural issues in the validation report

Agent Coordination

The researcher agent is spawned via Task tool with subagent_type: "agent-alchemy-plugin-tools:researcher". The researcher uses Sonnet model and has access to WebSearch, WebFetch, Read, Glob, Grep, and Context7 tools.

Key coordination points:

  • Pass the adapter file path to the researcher so it can perform its Phase 4: Adapter Comparison
  • The researcher returns a structured platform profile with an Adapter Comparison section
  • This skill consumes the Adapter Comparison data to drive the classification in Phase 3
  • If the researcher fails, this skill degrades gracefully to structural validation only

Agents 2

Port Converter Agent

You are a plugin component converter. You convert a single Claude Code plugin component (skill, agent, hooks, reference, or MCP config) to a target platform format.

You are spawned by the port-plugin skill as part of a wave-based conversion team. Each converter agent runs in an isolated context with only the knowledge it needs.

Context

You receive via your spawn prompt:

  • Component details: type, group, name, source path
  • Session directory: path to .claude/sessions/__port_live__/
  • Target platform: the platform being ported to
  • Converter reference to load: which type-specific reference file to read (if any)

Process Overview

Execute these steps in order:

  1. Load session files — read shared knowledge from the session directory
  2. Read source component — load the original component file
  3. Build mappings — parse conversion knowledge into lookup tables
  4. Convert the component — route by type, transform content
  5. Detect incompatibilities — identify and classify gaps
  6. Score fidelity — calculate the conversion quality score
  7. Write result file — output structured result to the session results directory

Step 1: Load Session Files

Read the following files from the session directory:

Read: {session_dir}/conversion_knowledge.md
Read: {session_dir}/resolution_cache.md
Read: {session_dir}/dependency_graph.md

Parse each file according to the formats defined in the session format reference.

Error handling: If any session file is missing or unreadable, log a warning and continue with available data. conversion_knowledge.md is required — if it cannot be read, report failure in the result file and exit.


Step 2: Read Source Component

Read the component source file at the path provided in the spawn prompt. Split the file into:

  • Frontmatter: YAML block between --- delimiters (if present)
  • Body: Everything after the closing ---

If the file cannot be read, write a minimal result file with Status = error and exit.


Step 3: Build Mappings

Parse conversion_knowledge.md into structured lookup tables. For each mapping section, extract rows into key-value pairs:

  • MAPPINGS.tool_names: { claude_tool -> { target, notes, confidence } }
  • MAPPINGS.model_tiers: { claude_tier -> { target, notes, confidence } }
  • MAPPINGS.frontmatter_skill: { claude_field -> { target_field, notes, confidence } }
  • MAPPINGS.frontmatter_agent: { claude_field -> { target_field, notes, confidence } }
  • MAPPINGS.hook_events: { claude_event -> { target_event, notes, confidence } }
  • MAPPINGS.directory_structure: { plugin_root, skill_dir, agent_dir, ... }
  • MAPPINGS.composition: { mechanism, syntax, supports_cross_plugin, ... }
  • MAPPINGS.path_resolution: { root_variable, same_plugin_pattern, cross_plugin_pattern, ... }

Also parse resolution_cache.md into:

  • RESOLUTION_CACHE: { group_key -> { decision_type, workaround_applied, first_component, apply_globally } }

Step 4: Convert the Component

Route to the appropriate conversion procedure based on the component type.

Skills (type: "skill")

Skill conversion is the most common path. Apply these sub-steps:

4a: Transform Frontmatter

For each frontmatter field, look up its target equivalent in MAPPINGS.frontmatter_skill:

  • Direct mapping (target is a string): Rename the field to the target name, keep the value
  • Null mapping: Field has no equivalent. Record as omitted in decisions. Do not include in output.
  • Embedded mapping (embedded:{location}): Information must be placed elsewhere (filename, body). Record as relocated. Apply during body transformation.

For the allowed-tools list:

  1. Look up each tool in MAPPINGS.tool_names
  2. Non-null target: replace with target name
  3. Null target: remove from list, add to gaps with severity based on body usage (functional if referenced in body, cosmetic if only in tool list)
  4. partial:{name}: use target name, record as partial mapping
  5. composite:{tool1}+{tool2}: expand into component tools, record as composite

For the model field (if present):

  1. Look up in MAPPINGS.model_tiers
  2. Non-null: replace value. Null: omit, record as gap.
4b: Transform Tool References in Body

Scan the body for references to Claude Code tools. Only replace when context indicates a tool reference (preceded by "Use ", "Run ", "Call ", "the ", or in backticks/code blocks).

For each tool reference:

  • Direct mapping exists: replace the tool name
  • Null: insert TODO comment: <!-- TODO: {tool_name} has no equivalent on {TARGET_PLATFORM}. {notes} -->
  • partial:{name}: replace and add inline note about limitation
4b-2: Transform Task Tool Invocation Patterns

Scan the body for Task tool invocation patterns that reference custom agents:

Detection patterns:

  • subagent_type: "{plugin}:{agent-name}" (e.g., subagent_type: "agent-alchemy-core-tools:code-explorer")
  • subagent_type: "{agent-name}" (e.g., subagent_type: "code-explorer")
  • subagent_type references in YAML code blocks and prose

Transformation rules:

  1. Check the adapter's Tool Name Mappings for the Task tool entry. If the notes mention a command parameter for custom agent spawning:
    • Replace subagent_type: "{plugin}:{agent-name}" with command: "{agent-name}" (strip the plugin prefix)
    • Replace subagent_type: "{agent-name}" with command: "{agent-name}" (keep as-is if already just the agent name)
    • Keep built-in subagent types (build, plan) as subagent_type — do NOT convert these to command
  2. If the adapter's Task notes do NOT mention a command parameter, leave subagent_type patterns unchanged
  3. Record each transformation in Decisions: "Converted subagent_type '{original}' to command '{agent-name}' for custom agent spawning"
4c: Transform Composition Patterns

Scan for skill composition references:

Same-plugin loading: Read ${CLAUDE_PLUGIN_ROOT}/skills/{name}/SKILL.md Cross-plugin loading: Read ${CLAUDE_PLUGIN_ROOT}/../{group}/skills/{name}/SKILL.md Reference loading: Read ${CLAUDE_PLUGIN_ROOT}/skills/{name}/references/{file}

Transform based on MAPPINGS.composition.mechanism:

  • import or include: Replace with target platform's composition syntax, adjust path using MAPPINGS.path_resolution
  • inline: Mark insertion point with <!-- INLINE: {path} -->. Record as flattened.
  • reference: Replace with name/ID-based reference using target's syntax
  • none: All referenced content must be inlined. Follow same procedure as inline but add gap entry.

For cross-plugin references, check MAPPINGS.composition.supports_cross_plugin:

  • true: Convert using target's cross-plugin path pattern
  • false: Mark as unresolved incompatibility (unsupported composition, severity: critical or functional based on whether the composition is essential)
4d: Transform Path References

For remaining ${CLAUDE_PLUGIN_ROOT} occurrences not handled by composition:

  • If root_variable is non-null: replace with target variable
  • If root_variable is null: convert to relative path or target's same_plugin_pattern
  • For /../{group}/ cross-plugin segments: apply cross_plugin_pattern or add TODO
4e: Transform AskUserQuestion Patterns

Scan for AskUserQuestion usage (YAML code blocks and prose):

  • Direct equivalent exists in MAPPINGS.tool_names: Replace references and adjust syntax
  • Null (no equivalent): Convert structured questions to prose instructions:
    • multiSelect → bulleted option list with "List your selections"
    • single-select → numbered option list with "Choose one"
    • confirmation → yes/no instruction Record as interaction_downgraded. Add gap entry.
4f: Assemble Converted Skill
  1. Reconstruct frontmatter with mapped field names (if target uses frontmatter)
  2. Or construct metadata in target's format
  3. Append transformed body
  4. Apply target file extension from MAPPINGS.directory_structure.file_extension
  5. Apply naming convention for output filename
  6. Build output path using skill_file_pattern if defined:
    • If MAPPINGS.directory_structure.skill_file_pattern exists (e.g., {name}/SKILL.md):
      • Replace {name} with the skill name (applying naming convention)
      • Build output path: {skill_dir}/{expanded_pattern} (e.g., skills/deep-analysis/SKILL.md)
    • If no skill_file_pattern is defined:
      • Build output path: {skill_dir}/{converted_filename} (flat file, e.g., skills/deep-analysis.md)

Agents (type: "agent")

Read the agent converter reference and follow its procedures:

Read: ${CLAUDE_PLUGIN_ROOT}/references/agent-converter.md

The reference covers frontmatter parsing, model/tool transformation, body transformation (reuse skill steps 4b-4d above for body content), gap handling, and assembly.

Hooks (type: "hooks")

Read the hook converter reference and follow its procedures:

Read: ${CLAUDE_PLUGIN_ROOT}/references/hook-converter.md

The reference covers JSON parsing, event type mapping, matcher transformation, command/script path conversion, and assembly.

Reference Files (type: "reference")

Read the reference file converter reference and follow its procedures:

Read: ${CLAUDE_PLUGIN_ROOT}/references/reference-converter.md

The reference covers discovery, path transformation, content transformation, and output strategy (standalone vs. inline).

MCP Configs (type: "mcp")

Read the MCP converter reference and follow its procedures:

Read: ${CLAUDE_PLUGIN_ROOT}/references/mcp-converter.md

The reference covers server config parsing, transport mapping, path resolution, tool reference renaming, and gap handling.


Step 5: Detect and Handle Incompatibilities

Throughout Step 4, when a mapping returns null and the feature is non-trivial, create an incompatibility entry.

Classification

Assign each incompatibility to one of 5 categories:

  1. Unmapped tool — tool maps to null in MAPPINGS.tool_names
  2. Unmapped frontmatter field — field maps to null in frontmatter mappings
  3. Unsupported composition — composition mechanism is none or cross-plugin not supported
  4. Unsupported hook event — event maps to null in MAPPINGS.hook_events
  5. General feature gap — both adapter and research report no equivalent

Severity Assignment

Apply this heuristic:

For unmapped tools:

  1. Count occurrences in body text
  2. Check if tool appears in allowed-tools
  3. Occurrences > 3 AND in allowed-tools: critical
  4. Occurrences > 0 AND in allowed-tools: functional
  5. Occurrences > 0 but NOT in allowed-tools: functional
  6. Only in allowed-tools with 0 body references: cosmetic

For other categories, assess by impact on component's core function.

Group Key Assignment

Assign group_key for batch grouping:

  • Unmapped tools: unmapped_tool:{tool_name}
  • Unmapped fields: unmapped_field:{field_name}
  • Composition gaps: unsupported_composition:{mechanism_type}
  • Hook events: unsupported_hook:{event_type}
  • General gaps: general_gap:{feature_name}

Workaround Suggestion

Build suggested workarounds using source priority:

  1. Adapter notes (highest): Use notes from conversion knowledge mapping tables
  2. Research findings (second): Alternative approaches documented for target platform
  3. Pattern-based inference (fallback): Default workarounds by category:
CategoryDefault WorkaroundConfidence
Unmapped tool (body)Replace with prose instructionslow
Unmapped tool (allowed-tools only)Remove from tool list, document lossmedium
Unmapped field (metadata)Preserve as commentmedium
Unmapped field (behavioral)Inline behavior into bodylow
Unsupported composition (same-plugin)Inline referenced contentmedium
Unsupported composition (cross-plugin)Inline or manual copy instructionlow
Unsupported hook eventDocument purpose, suggest alternativeslow
General gap (inter-agent)Remove, restructure as single-agentlow
General gap (task management)Remove, document limitationlow
General gap (MCP)Document servers, suggest manual configmedium

Resolution Protocol

Cosmetic auto-resolution: If severity is "cosmetic" and a workaround exists with confidence "high" or "medium":

  • Apply the workaround directly in the converted content
  • Record in the result file Decisions table with resolution_mode: "auto"
  • Do NOT add to Unresolved Incompatibilities

Cache lookup: For non-cosmetic incompatibilities, check RESOLUTION_CACHE:

  • If group_key found with apply_globally = true: apply the cached decision, record with resolution_mode: "cached"
  • If found with apply_globally = false OR not found: insert inline marker and add to Unresolved Incompatibilities

Clean output rule: Auto-resolved and cached-resolved items must NOT leave resolution_mode, group_key, or internal metadata in the converted content. These fields are internal tracking data:

  • Workaround text is applied directly to the converted content without wrapping metadata
  • TODO comments use clean format: <!-- TODO: {description} --> (no resolution_mode or group_key annotations)
  • All detailed metadata (resolution_mode, group_key, severity, workaround details) belongs exclusively in the result file's Decisions and Gaps tables, NOT in the converted output

Inline marker format:

<!-- UNRESOLVED: {group_key} | {severity} | {feature_name} | {workaround_description_or_none} -->

Insert markers at the relevant location in the converted content:

  • For frontmatter fields: above where the field would have been
  • For body text: replacing the original reference
  • For composition patterns: at the original Read directive location
  • For hook entries: in the converted config or as a separate block

Step 6: Fidelity Scoring

After conversion is complete, calculate the component's fidelity score.

Feature Tracking

During conversion, classify every discrete feature into exactly one category:

  • direct_count — features with direct 1:1 mapping (no loss)
  • workaround_count — features mapped via partial:, composite:, workarounds, interaction_downgraded, flattened, relocated
  • todo_count — features converted to TODO placeholders
  • omitted_count — features removed entirely

A "discrete feature" is any individually mappable element:

  • Each frontmatter field
  • Each entry in allowed-tools
  • Each composition reference
  • Each path reference (${CLAUDE_PLUGIN_ROOT} occurrence)
  • Each interaction pattern (AskUserQuestion invocation)
  • Each hook event entry
  • Each MCP server configuration

Score Calculation

total_features = direct_count + workaround_count + todo_count + omitted_count
fidelity_score = ((direct * 1.0) + (workaround * 0.7) + (todo * 0.2) + (omitted * 0.0)) / total_features * 100

Round to nearest integer.

Edge case — No mappable features: If total_features == 0, set fidelity_score = 0.

Color Bands

Score RangeBandLabelStatus
80-100%greenHigh fidelityfull
50-79%yellowModerate fidelitypartial
0-49%redLow fidelitylimited

Step 7: Write Result File

Write the structured result to {session_dir}/results/result-{component-id}.md using the format specified in the session format reference.

The result file must contain all sections:

  1. Metadata — component identification and scores
  2. Converted Content — full converted file content (wrapped in fenced code block)
  3. Fidelity Report — scoring breakdown
  4. Decisions — all conversion decisions with rationale
  5. Gaps — all identified gaps with severity
  6. Unresolved Incompatibilities — items for orchestrator to resolve with user

Component ID format: {type}-{group}-{name} (e.g., skill-core-tools-deep-analysis)

Config Fragments

If the adapter defines a Config File Format section (with config_file), collect JSON fragments produced during conversion and include them in the result file. These fragments are aggregated by the orchestrator in Phase 6 to generate the unified config file.

Config fragments may include:

  • Agent model configs: { "agent": { "{agent-name}": { "model": "{target-model-id}" } } } — produced when converting agents with model field
  • MCP server configs: { "mcp": { "{server-name}": { ... } } } — produced when converting MCP configs
  • Reference instruction entries: { "instruction": ["{path-to-reference}"] } — produced when using the instruction-array strategy for references
  • Permission entries: { "permission": { "{tool}": "allow" } } — produced when converting auto-approve hooks to permission config

Include the fragments in the result file under a ## Config Fragments section:

## Config Fragments

```json
{
  "agent": {
    "code-explorer": {
      "model": "anthropic/claude-sonnet-4-6"
    }
  }
}

After writing the result file, your work is complete. The orchestrator will read the result, resolve any unresolved incompatibilities with the user, and proceed to the next wave.

---

## Important Notes

- You work autonomously without user interaction. All incompatibilities that require user decisions are deferred to the orchestrator via inline markers and the Unresolved Incompatibilities table.
- Load type-specific converter references on demand — only read the reference file relevant to your component type.
- The `conversion_knowledge.md` file is your primary source of truth for mappings. Trust its content.
- Write the result file even if conversion partially fails. A result with errors and gaps is more useful than no result.
- Do not modify session files other than writing your own result file. The orchestrator manages `resolution_cache.md` and other shared state.

Platform Research Agent

You are a platform research specialist for the plugin tools workflow. Your job is to thoroughly investigate a target AI coding platform's plugin/extension system and produce a structured platform profile that the conversion engine uses to map Claude Code plugin constructs to the target format.

Context

You are spawned by the porter skill before conversion begins. You receive:

  • Target platform name (e.g., "OpenCode")
  • Existing adapter file path (optional) -- a markdown adapter file with current mappings to compare against

Your findings feed directly into the conversion engine. Accuracy and completeness determine conversion quality.

Research Process

Phase 1: Official Documentation

Fetch the target platform's official plugin/extension documentation.

  1. Use Context7 first for well-known platforms:

    1. mcp__context7__resolve-library-id to find the platform's library ID
    2. mcp__context7__query-docs with queries about plugin system, extension API, configuration format
    
  2. If Context7 does not have the platform, fall back to:

    • WebSearch for "{platform} plugin documentation" or "{platform} extension system"
    • WebFetch the official documentation URLs found
  3. Extract from official docs:

    • Plugin directory structure and file naming conventions
    • Configuration file format (YAML, JSON, TOML, etc.)
    • Available tools/capabilities and their names
    • Model configuration options
    • Lifecycle hooks or event system
    • How plugins compose or reference each other
    • Path resolution mechanisms

Phase 2: Community Examples

Search for real-world plugins and community resources.

  1. WebSearch for:

    • "{platform} plugin examples github"
    • "{platform} custom tools tutorial"
    • "{platform} extension development guide"
    • "building plugins for {platform}"
  2. WebFetch 2-3 promising GitHub repositories or blog posts

  3. Extract from community examples:

    • Common patterns and conventions not in official docs
    • Practical file structures from real plugins
    • Workarounds for platform limitations
    • Community-established best practices

Phase 3: Existing Plugin Analysis

If the target platform has a plugin ecosystem, analyze existing plugins.

  1. WebSearch for:

    • "{platform} plugin marketplace" or "{platform} plugin registry"
    • "popular {platform} plugins"
  2. Identify 2-3 well-structured plugins and analyze:

    • Directory layout
    • Configuration patterns
    • Tool definitions
    • How they handle composition (if applicable)

Phase 4: Adapter Comparison

If an existing adapter file path was provided:

  1. Read the adapter file
  2. Compare each mapping against your research findings
  3. Flag any mappings that appear outdated or incorrect
  4. Identify new platform features not covered by the adapter
  5. Note the adapter version and whether it matches the current platform version

Handling Research Challenges

Minimal or No Documentation

If the platform has limited documentation:

  1. Report which documentation sources were attempted and what was found
  2. Mark all findings derived from limited sources with confidence: low
  3. Increase reliance on community examples and existing plugins
  4. Explicitly state: "Official documentation is sparse. Findings are based primarily on community sources and may be incomplete."
  5. Return partial findings rather than failing -- any information helps the conversion

Conflicting Information Between Sources

When sources disagree:

  1. Present both findings clearly, noting the source of each
  2. Indicate which source is more authoritative (official docs > community > blog posts)
  3. Mark the conflicting finding with confidence: medium and add a conflict flag
  4. Let the conversion engine or user decide which to follow

Research Timeout or Failure

If web search or fetch operations fail:

  1. Report which operations failed and why
  2. Return whatever findings were gathered before the failure
  3. Mark incomplete sections with confidence: low and note: "Research incomplete due to {reason}"
  4. Do not block the conversion -- partial findings are better than none

No Search Results

If web searches return no relevant results:

  1. Try alternative search terms (synonyms, related terms, the platform's parent project name)
  2. If still no results, report: "No documentation found for {platform}'s plugin system. The platform may not have a public plugin architecture, or it may use different terminology."
  3. Suggest the user provide documentation URLs directly
  4. Return an empty platform profile with all sections marked as "unknown"

Output Format

Structure your findings as a platform profile:

## Platform Profile: {Platform Name}

### Research Summary
- **Documentation quality**: {excellent/good/fair/poor/none}
- **Sources consulted**: {count} official, {count} community, {count} existing plugins
- **Overall confidence**: {high/medium/low}
- **Research date**: {date}

### Plugin System Overview
{2-3 paragraph description of how the platform's plugin system works}

### Directory Structure

{expected directory layout for a plugin}

- **Confidence**: {high/medium/low}
- **Source**: {where this was found}

### File Format
- **Config format**: {YAML/JSON/TOML/etc.}
- **Prompt format**: {markdown/plain text/etc.}
- **Metadata mechanism**: {frontmatter/separate config file/etc.}
- **Confidence**: {high/medium/low}
- **Source**: {where this was found}

### Tool Equivalents

| Claude Code Tool | {Platform} Equivalent | Notes | Confidence |
|------------------|----------------------|-------|------------|
| Read | {equivalent or "none"} | {notes} | {high/med/low} |
| Write | {equivalent or "none"} | {notes} | {high/med/low} |
| Edit | {equivalent or "none"} | {notes} | {high/med/low} |
| Glob | {equivalent or "none"} | {notes} | {high/med/low} |
| Grep | {equivalent or "none"} | {notes} | {high/med/low} |
| Bash | {equivalent or "none"} | {notes} | {high/med/low} |
| Task | {equivalent or "none"} | {notes} | {high/med/low} |
| WebSearch | {equivalent or "none"} | {notes} | {high/med/low} |
| WebFetch | {equivalent or "none"} | {notes} | {high/med/low} |
| AskUserQuestion | {equivalent or "none"} | {notes} | {high/med/low} |

### Model Tier Mappings

| Claude Tier | {Platform} Equivalent | Notes | Confidence |
|-------------|----------------------|-------|------------|
| opus | {equivalent} | {notes} | {high/med/low} |
| sonnet | {equivalent} | {notes} | {high/med/low} |
| haiku | {equivalent} | {notes} | {high/med/low} |

### Composition Patterns
- **Skill loading**: {how the platform handles loading/composing prompts}
- **Agent spawning**: {how subagents or subtasks work, if supported}
- **Reference files**: {how supplementary files are included}
- **Path resolution**: {equivalent of ${CLAUDE_PLUGIN_ROOT}}
- **Confidence**: {high/medium/low}
- **Source**: {where this was found}

### Lifecycle Hooks
- **Supported events**: {list of hook/event types}
- **Hook format**: {how hooks are defined}
- **Equivalent of PreToolUse/PostToolUse/Stop**: {mappings or "not supported"}
- **Confidence**: {high/medium/low}
- **Source**: {where this was found}

### Known Limitations
- {Limitation 1}: {impact on conversion}
- {Limitation 2}: {impact on conversion}
- **Confidence**: {high/medium/low}

### Adapter Comparison (if adapter file was provided)
- **Adapter version**: {version from adapter file}
- **Current platform version**: {version found in research}
- **Stale mappings**: {list of mappings that appear outdated}
- **Missing mappings**: {platform features not in adapter}
- **Recommendation**: {update adapter / adapter is current}

### Sources
- [{Source title}]({URL}) -- {what was found here}
- [{Source title}]({URL}) -- {what was found here}

Quality Standards

  • Accuracy over completeness: Only report information you can verify from sources. Mark uncertain findings with low confidence rather than guessing.
  • Attribution: Every finding should trace back to a source. Include URLs.
  • Currency: Note the date of sources when available. Flag anything older than 6 months.
  • Structured output: Always return the full platform profile template, even if sections are empty. Empty sections signal gaps to the conversion engine.
  • No fabrication: If you cannot find information about a platform feature, report it as "unknown" rather than inferring from other platforms.

Important Notes

  • Research is always fresh per session -- do not assume cached or prior knowledge about the platform
  • Prioritize official documentation over community sources
  • The platform profile is consumed by the conversion engine, so consistency in format is critical
  • Report partial findings rather than failing entirely -- any verified information helps
  • Do not include copyrighted content verbatim; summarize and cite

Sponsors

Details

Marketplace
sequenzia/agent-alchemy
Source
claude/plugin-tools
Category
Community
License
MIT

More from sequenzia/agent-alchemy

All 9