How to Test the Converter Output for a New Target Platform

To test converter output for a new target platform, create a minimal ClaudePlugin fixture, invoke the target-specific conversion function, and assert on the bundle structure using the existing test harness in tests/<target>-converter.test.ts.

The compound-engineering-plugin CLI transforms Claude Code plugins into platform-specific formats like Codex, Gemini, or Cursor. When extending support to a new target platform, you must verify that your converter correctly transforms the source plugin into the expected bundle format, ensuring prompts, skills, and MCP servers map accurately to the target's requirements.

Understanding the Converter Architecture

Before writing tests, you need to understand how the conversion pipeline structures its output.

The Converter Entry Point

Each target platform implements a converter in src/converters/claude-to-<target>.ts. For example, src/converters/claude-to-codex.ts parses the source ClaudePlugin, filters commands with disableModelInvocation, and calls helper functions like convertCommandSkill, convertAgent, and transformContentForCodex to generate platform-specific content. The converter returns a bundle object containing prompts, skillDirs, generatedSkills, and mcpServers.

The Bundle Structure

The converter returns a structured bundle that the writer consumes:

• prompts: Prompt files that the target platform expects
• skillDirs: Directories containing existing skills copied verbatim
• generatedSkills: Skills created from commands or agents
• mcpServers: Optional MCP server configuration passed through unchanged

The Writer Implementation

The writer in src/targets/<target>.ts (e.g., src/targets/codex.ts) consumes the bundle and materializes the directory tree on disk. While the converter test validates the bundle structure, the writer handles file system operations.

Creating a Test Fixture for Your Target Platform

To test the converter output, construct a minimal ClaudePlugin fixture that exercises all conversion paths. The fixture should include agents, commands with various configurations, existing skills, and MCP servers.

import { convertClaudeToCodex } from "../src/converters/claude-to-codex"
import type { ClaudePlugin } from "../src/types/claude"

const fixturePlugin: ClaudePlugin = {
  root: "/tmp/plugin",
  manifest: { name: "fixture", version: "1.0.0" },
  agents: [
    {
      name: "Security Reviewer",
      description: "Security‑focused agent",
      capabilities: ["Threat modeling", "OWASP"],
      body: "Focus on vulnerabilities.",
      sourcePath: "/tmp/plugin/agents/security-reviewer.md",
    },
  ],
  commands: [
    {
      name: "workflows:plan",
      description: "Planning command",
      argumentHint: "[FOCUS]",
      allowedTools: ["Read"],
      body: "Plan the work.",
      sourcePath: "/tmp/plugin/commands/workflows/plan.md",
    },
  ],
  skills: [
    {
      name: "existing-skill",
      description: "Existing skill",
      sourceDir: "/tmp/plugin/skills/existing-skill",
      skillPath: "/tmp/plugin/skills/existing-skill/SKILL.md",
    },
  ],
  hooks: undefined,
  mcpServers: { local: { command: "echo", args: ["hello"] } },
}

// Run the converter
const bundle = convertClaudeToCodex(fixturePlugin, {
  agentMode: "subagent",
  inferTemperature: false,
  permissions: "none",
})

Writing Assertions for Converter Output

After generating the bundle, assert on the structure and content to verify correct transformation. Use parseFrontmatter from src/utils/frontmatter.ts to validate prompt metadata.

import { parseFrontmatter } from "../src/utils/frontmatter"
import { describe, test, expect } from "bun:test"

describe("convertClaudeToCodex", () => {
  test("converts commands to prompts and agents to skills", () => {
    const bundle = convertClaudeToCodex(fixturePlugin, {
      agentMode: "subagent",
      inferTemperature: false,
      permissions: "none",
    })

    // Prompt validation
    expect(bundle.prompts).toHaveLength(1)
    const prompt = bundle.prompts[0]
    expect(prompt.name).toBe("workflows-plan")

    const parsedPrompt = parseFrontmatter(prompt.content)
    expect(parsedPrompt.data.description).toBe("Planning command")
    expect(parsedPrompt.data["argument-hint"]).toBe("[FOCUS]")
    expect(parsedPrompt.body).toContain("$workflows-plan")
    expect(parsedPrompt.body).toContain("Plan the work.")

    // Generated skill validation
    const agentSkill = bundle.generatedSkills.find(
      (s) => s.name === "security-reviewer",
    )
    expect(agentSkill).toBeDefined()
    const parsedSkill = parseFrontmatter(agentSkill!.content)
    expect(parsedSkill.data.name).toBe("security-reviewer")
    expect(parsedSkill.data.description).toBe("Security‑focused agent")
    expect(parsedSkill.body).toContain("Capabilities")
    expect(parsedSkill.body).toContain("Threat modeling")

    // MCP server passthrough
    expect(bundle.mcpServers?.local?.command).toBe("echo")
  })
})

Critical assertions for any target platform test include:

• Prompt naming: Verify that command names like workflows:plan transform to workflows-plan (or the target's expected format)
• Front-matter fields: Check that description, argument-hint, and other metadata map correctly
• Body transformations: Confirm that Task calls convert to skill invocations (e.g., Use the $repo-research-analyst skill to:) and slash-commands rewrite to target-specific syntax (e.g., /prompts:)
• Description truncation: Ensure long descriptions are capped at 1024 characters (or target-specific limits)
• MCP server passthrough: Verify that mcpServers configuration passes through unchanged

Adding a New Target Platform (Step-by-Step)

To implement testing for a completely new target platform (e.g., "Foo"):

1. Create the converter – Implement src/converters/claude-to-foo.ts following the pattern in claude-to-codex.ts. Define the bundle structure and transformation logic specific to Foo's requirements.

2. Create the writer – Implement src/targets/foo.ts to consume the bundle and write the directory structure that Foo expects.

3. Add a test file – Create tests/foo-converter.test.ts using the fixture pattern shown above. Import your converter and assert on Foo-specific bundle properties.

4. Run the tests – Execute bun test to validate your converter against the fixture. Adjust transformations until all assertions pass.

Key Files for Testing Converters

Role	File	Purpose
Core converter (example)	src/converters/claude-to-codex.ts	Demonstrates how to parse ClaudePlugin and return a platform-specific bundle.
Unit test template	tests/codex-converter.test.ts	Shows how to construct fixtures and assert on bundle contents using Bun test.
Writer implementation	src/targets/codex.ts	Consumes the bundle to write the final directory structure.
Front-matter utilities	src/utils/frontmatter.ts	Parses and serializes front-matter for validating prompt content.
Type definitions	src/types/claude.ts	Defines the ClaudePlugin interface used in test fixtures.

Summary

• Test the converter output by constructing a minimal ClaudePlugin fixture that includes agents, commands, skills, and MCP servers.
• Assert on the bundle structure returned by convertClaudeTo<Target> to verify prompts, generated skills, and metadata transformations.
• Validate content transformations including front-matter fields, body rewrites (Task calls to skill invocations, slash-command syntax), and description truncation limits.
• Follow the established pattern in tests/codex-converter.test.ts when adding support for new target platforms like Foo or Gemini.

Frequently Asked Questions

What is the minimum fixture needed to test a converter?

You need a ClaudePlugin object with at least one command, one agent, one skill, and an mcpServers configuration. This ensures you test the conversion of prompts, generated skills, directory copying, and server passthrough. The fixture should populate root, manifest, agents, commands, skills, and mcpServers fields with realistic data.

How do I verify that content transformations are correct?

Use the parseFrontmatter utility from src/utils/frontmatter.ts to parse the content field of prompts and skills in the bundle. Then assert on parsed.data for front-matter fields like description and argument-hint, and on parsed.body for transformed content such as skill invocations ($skill-name) or target-specific syntax like /prompts:.

What should I check when testing MCP server configuration?

Assert that the mcpServers object from the input ClaudePlugin passes through to the output bundle unchanged. For example, verify that bundle.mcpServers?.local?.command equals the value set in your fixture. The converter should not modify or drop MCP server configurations during transformation.

Can I use the same test pattern for any target platform?

Yes. The pattern established in tests/codex-converter.test.ts applies to any target. Create tests/<target>-converter.test.ts, import your convertClaudeTo<Target> function, construct the same ClaudePlugin fixture, and assert on the bundle structure. Adjust the specific assertions to match the target's expected file extensions, front-matter keys, and syntax requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}