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

1. Wave-Based Conversion - Convert components via parallel agent team with incompatibility resolution
2. Output & Reporting - Write converted files, migration guide, and gap report
3. 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

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

1. Hooks: If claude/{group}/hooks/hooks.json exists:

• Read the file and count hook entries
• Format: hooks:{group} with hook count and event types

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

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

1. Repeat step 3 for any newly discovered External-missing or External-selected dependencies
2. 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" }
   ]

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

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

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

1. Store as `RESEARCH_FINDINGS` — the parsed profile is available throughout the remaining phases for the conversion engine to reference.

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

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.

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

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

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

1. Write the updated adapter file
2. Re-read the updated adapter as ADAPTER and re-merge into CONVERSION_KNOWLEDGE
3. 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"}

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

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

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

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

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

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

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

| Group Key | Decision Type | Workaround Applied | First Component | Apply Globally |
|-----------|-------------|-------------------|-----------------|---------------|

This file grows between waves as the orchestrator resolves incompatibilities.

#### 1e: Compute Wave Assignments

Using CONVERSION_ORDER from Phase 3's topological sort, assign each component to a wave:

• Wave 1: Components with zero dependencies on other selected components (leaf nodes)
• Wave 2: Components whose dependencies are all in Wave 1
• Wave N: Components whose dependencies are all in Waves 1 through N-1

Cap each wave at 5 concurrent agents (matching the execute-tasks pattern).

If a wave has more than 5 components, split it into sub-waves of up to 5, maintaining the same dependency level.

#### 1f: Display Execution Plan

Present the wave-based execution plan:

## Phase 5: Wave-Based Conversion

**Session directory:** .claude/sessions/__port_live__/
**Total components:** {count}
**Waves:** {wave_count}
**Max concurrent agents per wave:** 5

### Execution Plan

| Wave | Components | Types |
|------|-----------|-------|
| 1 | {component_list} | {type_summary} |
| 2 | {component_list} | {type_summary} |
| ... | ... | ... |

### Session Files Written
- conversion_knowledge.md — {line_count} lines (merged adapter + research)
- dependency_graph.md — {line_count} lines (serialized graph)
- resolution_cache.md — initialized (empty)
- results/ — empty directory for agent output

Step 2: Execute Waves

Process components wave by wave. For each wave, spawn port-converter agents in parallel, then resolve incompatibilities between waves.

#### 2a: Wave Loop

For each wave (starting with Wave 1):

Display wave start:

### Wave {n}/{total_waves}: {component_count} component(s)

Spawn converter agents using the Task tool with up to 5 parallel calls in a single turn:

For each component in the current wave, launch a port-converter agent:

Task tool:
  subagent_type: "agent-alchemy-plugin-tools:port-converter"
  model: "sonnet"
  prompt: |
    Convert this component to {TARGET_PLATFORM} format.

    ## Component Details
    - **Type:** {component.type}
    - **Group:** {component.group}
    - **Name:** {component.name}
    - **Source path:** {component.path}
    - **Component ID:** {component.type}-{component.group}-{component.name}

    ## Session Directory
    {absolute_path_to}/.claude/sessions/__port_live__/

    ## Target Platform
    {TARGET_PLATFORM}

    ## Converter Reference to Load
    {If type == "agent": "${CLAUDE_PLUGIN_ROOT}/references/agent-converter.md"}
    {If type == "hooks": "${CLAUDE_PLUGIN_ROOT}/references/hook-converter.md"}
    {If type == "reference": "${CLAUDE_PLUGIN_ROOT}/references/reference-converter.md"}
    {If type == "mcp": "${CLAUDE_PLUGIN_ROOT}/references/mcp-converter.md"}
    {If type == "skill": "None — skill conversion logic is built into the agent"}

    ## Session Format Reference
    Read ${CLAUDE_PLUGIN_ROOT}/skills/port-plugin/references/session-format.md for the result file format specification.

CRITICAL: Launch all agents in a wave as parallel Task tool calls in a single message. Do not wait for one agent to finish before launching the next within the same wave. This is the key to context isolation — each agent gets its own context window.

Wait for all agents in the wave to complete before proceeding.

#### 2b: Collect Wave Results

After all agents in a wave return:

1. Read all result files from .claude/sessions/__port_live__/results/ for this wave's components:

   Read: .claude/sessions/__port_live__/results/result-{component-id}.md

1. Parse each result file extracting: metadata, converted content, fidelity report, decisions, gaps, and unresolved incompatibilities

1. Handle missing or error results: If an agent failed to write a result file, or the result file has Status = error:

• Log: "WARNING: Conversion failed for {component_id}: {error_reason}"
• Create a placeholder entry in CONVERTED_COMPONENTS with status = "error" and fidelity_score = 0
• Add a gap entry: { component, feature: "entire_component", reason: "Conversion agent failed", severity: "critical" }

#### 2c: Resolve Incompatibilities

After collecting all wave results, process unresolved incompatibilities:

1. Collect all unresolved incompatibilities from the wave's result files (from the Unresolved Incompatibilities tables)

1. Group by `group_key` across all results in the wave

1. Check resolution cache: Read .claude/sessions/__port_live__/resolution_cache.md. For each group:

• If group_key found with apply_globally = true: auto-apply the cached decision to the result file's converted content by replacing the inline marker with the resolution. Record with resolution_mode: "cached".
• If found with apply_globally = false: offer to reuse via AskUserQuestion (see below)
• If not found: present for user resolution

1. Present remaining incompatibilities to user using the resolution flow from ${CLAUDE_PLUGIN_ROOT}/references/incompatibility-resolver.md:

• **5 or fewer