OpenWriterControle/packages/compatibility-layer/README.md

@openagents-control/compatibility-layer

Compatibility layer for converting OpenAgents Control agents to/from other AI coding tools

Overview

This package provides bidirectional conversion between OpenAgents Control (OAC) agent format and various AI coding tools:

• Cursor IDE - VSCode-based AI editor with .cursorrules
• Claude Code - Anthropic's official CLI with config.json and agents/*.md
• Windsurf - AI-powered development environment with JSON config

Features

• ✅ Bidirectional conversion - Convert OAC ↔ Tool formats
• ✅ Feature parity tracking - Know what's supported in each tool
• ✅ Graceful degradation - Handle unsupported features with warnings
• ✅ CLI tool - Easy conversion from command line
• ✅ Batch migration - Migrate entire projects at once
• ✅ Type-safe - Full TypeScript with Zod validation
• ✅ Extensible - Plugin architecture for new tools

Installation

# npm
npm install @openagents-control/compatibility-layer

# pnpm
pnpm add @openagents-control/compatibility-layer

Quick Start

CLI Usage

# Convert a single file
oac-compat convert agent.md -f cursor -o .cursorrules

# Convert with auto-detection of source format
oac-compat convert .cursorrules -f oac -o agent.md

# Validate compatibility before conversion
oac-compat validate agent.md -t claude --strict

# Migrate entire project
oac-compat migrate ./agents -f claude --out-dir ./output

# Preview migration without writing files
oac-compat migrate ./agents -f windsurf --dry-run

# Show platform capabilities
oac-compat info cursor

# Compare two platforms
oac-compat info cursor --compare claude

Programmatic Usage

import {
  loadAgent,
  getAdapter,
  translate,
  analyzeCompatibility,
} from "@openagents-control/compatibility-layer";

// Load an OAC agent
const agent = await loadAgent("./agent.md");

// Check compatibility with target platform
const compatibility = analyzeCompatibility(agent, "cursor");
console.log("Compatible:", compatibility.compatible);
console.log("Warnings:", compatibility.warnings);
console.log("Blockers:", compatibility.blockers);

// Convert to another format
const adapter = getAdapter("claude");
const result = await adapter.fromOAC(agent);

if (result.success) {
  for (const config of result.configs) {
    console.log(`File: ${config.fileName}`);
    console.log(config.content);
  }
}

// Or use the translate function for quick conversion
const translated = translate(agent, "cursor");

CLI Commands

convert - Convert a single file

oac-compat convert <input> -f <format> [options]

Options:
  -f, --format <format>   Target format (oac, cursor, claude, windsurf)
  -o, --output <path>     Output file path (stdout if omitted)
  --from <format>         Source format (auto-detect if omitted)
  --force                 Overwrite existing output file

validate - Check compatibility

oac-compat validate <input> -t <format> [options]

Options:
  -t, --target <format>   Target format to validate against
  --strict                Enable strict validation mode

migrate - Batch migration

oac-compat migrate <source-dir> -f <format> [options]

Options:
  -f, --format <format>   Target format
  -o, --out-dir <path>    Output directory
  --dry-run               Preview without writing files
  --force                 Overwrite existing files

info - Platform information

oac-compat info [platform] [options]

Options:
  -d, --detailed          Show detailed capability information
  -c, --compare <other>   Compare with another platform

Global Options

-v, --verbose             Enable verbose output
-q, --quiet               Suppress all output except errors
--output-format <format>  Output format (text, json)

Feature Parity Matrix

Feature	OAC	Cursor	Claude	Windsurf
Config Format	YAML+MD	Plain text	JSON	JSON
Multiple Agents	✅	❌	✅	✅
Tool Permissions	Granular	Binary	Binary	Binary
Temperature	✅	❌	❌	✅
Skills/Contexts	✅	❌	✅	⚠️
Hooks	✅	❌	✅	❌
Model Selection	✅	✅	✅	✅

See Feature Matrices for detailed comparison.

Migration Guides

• Cursor → OAC - Import from Cursor
• Claude → OAC - Import from Claude Code
• OAC → Cursor - Export to Cursor
• OAC → Claude - Export to Claude Code
• OAC → Windsurf - Export to Windsurf

API Reference

Agent Loading

import {
  loadAgent,
  loadAgents,
  AgentLoader,
} from "@openagents-control/compatibility-layer";

// Load single agent
const agent = await loadAgent("./agent.md");

// Load all agents from directory
const agents = await loadAgents("./agents/");

// Using the loader class
const loader = new AgentLoader();
const agent = await loader.loadFromFile("./agent.md");

Adapter Registry

import {
  registry,
  getAdapter,
  listAdapters,
} from "@openagents-control/compatibility-layer";

// Get adapter by name
const adapter = getAdapter("cursor");

// List all adapters
const names = listAdapters(); // ['cursor', 'claude', 'windsurf']

// Get all capabilities
const capabilities = getAllCapabilities();

Translation Engine

import {
  translate,
  previewTranslation,
  TranslationEngine,
} from "@openagents-control/compatibility-layer";

// Quick translate
const result = translate(agent, "cursor");

// Preview without converting
const preview = previewTranslation(agent, "claude");
console.log("Features lost:", preview.featuresLost);
console.log("Features gained:", preview.featuresGained);

// Using the engine for more control
const engine = new TranslationEngine();
const result = engine.translate(agent, "windsurf", {
  preserveComments: true,
  strictMode: false,
});

Mappers

import {
  mapToolFromOAC,
  mapModelFromOAC,
  mapPermissionsFromOAC,
  mapContextPathFromOAC,
} from "@openagents-control/compatibility-layer";

// Map tool names
mapToolFromOAC("bash", "cursor"); // { name: 'terminal', exact: true }

// Map model identifiers
mapModelFromOAC("claude-sonnet-4", "cursor"); // { id: 'claude-3-sonnet', exact: true }

// Map permissions
mapPermissionsFromOAC({ bash: { "*": "allow" } }, "claude");
// { permissions: { bash: true }, warnings: [...] }

Architecture

src/
├── types.ts              # Zod schemas and TypeScript types
├── index.ts              # Public API exports
├── core/
│   ├── AgentLoader.ts    # OAC agent file parser
│   ├── AdapterRegistry.ts # Adapter management
│   ├── CapabilityMatrix.ts # Feature compatibility
│   └── TranslationEngine.ts # Orchestrates conversion
├── adapters/
│   ├── BaseAdapter.ts    # Abstract base class
│   ├── CursorAdapter.ts  # Cursor IDE adapter
│   ├── ClaudeAdapter.ts  # Claude Code adapter
│   └── WindsurfAdapter.ts # Windsurf adapter
├── mappers/
│   ├── ToolMapper.ts     # Tool name translation
│   ├── ModelMapper.ts    # Model ID translation
│   ├── PermissionMapper.ts # Permission translation
│   └── ContextMapper.ts  # Context path translation
└── cli/
    ├── index.ts          # CLI entry point
    ├── types.ts          # CLI types
    ├── utils.ts          # CLI utilities
    └── commands/
        ├── convert.ts    # convert command
        ├── validate.ts   # validate command
        ├── migrate.ts    # migrate command
        └── info.ts       # info command

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Test with coverage
npm run test:coverage

# Watch mode for development
npm run build:watch

# Lint
npm run lint
npm run lint:fix

Creating Custom Adapters

import {
  BaseAdapter,
  OpenAgent,
  ConversionResult,
  ToolCapabilities,
} from "@openagents-control/compatibility-layer";

class MyToolAdapter extends BaseAdapter {
  readonly name = "my-tool";
  readonly displayName = "My Tool";
  readonly version = "1.0.0";

  getCapabilities(): ToolCapabilities {
    return {
      supportsMultiAgent: false,
      supportsSkills: false,
      supportsHooks: false,
      supportsGranularPermissions: false,
      configFormat: "json",
    };
  }

  async toOAC(source: string): Promise<OpenAgent> {
    // Parse source and return OpenAgent
  }

  async fromOAC(agent: OpenAgent): Promise<ConversionResult> {
    // Convert OpenAgent to your format
    return {
      success: true,
      configs: [{ fileName: "config.json", content: "...", encoding: "utf-8" }],
      warnings: [],
    };
  }
}

// Register the adapter
import { registry } from "@openagents-control/compatibility-layer";
registry.register(new MyToolAdapter());

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT © OpenAgents Control Contributors