OpenAgentsControl/plugins/claude-code/scripts/context/openagents-repo/guides/compatibility-layer-workflow.md

Guide: Compatibility Layer Development Workflow

Purpose: Step-by-step process for extending the compatibility layer to support new AI coding tools

Last Updated: 2026-02-05

---

When to Use This Guide

• Adding support for a new AI coding tool (e.g., Codeium, GitHub Copilot)
• Extending existing adapter capabilities
• Understanding the development phases for compatibility work

---

Development Phases

Phase 1: Foundation ✅ COMPLETE

Objective: Set up project infrastructure and core types

1. Project Setup (1.5h) ✅

   • Create packages/compatibility-layer/package.json
   • Configure TypeScript with strict mode
   • Set up Vitest with 80%+ coverage thresholds

2. Type System (1.5h) ✅

   • Create src/types.ts with Zod schemas
   • Define OpenAgentSchema, AgentFrontmatterSchema
   • Export TypeScript types with z.infer<>

3. Base Adapter (1.5h) ✅

   • Create src/adapters/BaseAdapter.ts abstract class
   • Define abstract methods: toOAC(), fromOAC(), getCapabilities()

4. Agent Loader (1.5h) ✅

   • Create src/core/AgentLoader.ts
   • Use gray-matter for YAML frontmatter parsing

5. Adapter Registry (1h) ✅

   • Create src/core/AdapterRegistry.ts
   • Implement registry pattern with Map<string, BaseAdapter>

6. Public API (1h) ✅

   • Create src/index.ts
   • Export all public APIs

Result: 1,475 lines TypeScript, 0 compilation errors

---

Phase 2: Adapter Migration ✅ COMPLETE

Objective: Migrate existing adapters to TypeScript

1. Claude Adapter (3h) ✅ - 600 lines
2. Cursor Adapter (3h) ✅ - 554 lines
3. Windsurf Adapter (3h) ✅ - 514 lines
4. ClaudeAdapter Tests ✅ - 80 tests, 96% coverage
5. CursorAdapter Tests ✅ - 78 tests, 99% coverage
6. WindsurfAdapter Tests ✅ - 78 tests, 99% coverage

Result: 1,858 lines TypeScript, 236 tests passing

---

Phase 3: Mappers & Translation ✅ COMPLETE

Objective: Implement feature mapping logic

1. Tool Mapper ✅ - 308 lines, 34 tests, 100% coverage
2. Permission Mapper ✅ - 354 lines, 37 tests, 98% coverage
3. Model Mapper ✅ - 413 lines, 37 tests, 99% coverage
4. Context Mapper ✅ - 384 lines, 51 tests, 97% coverage
5. Capability Matrix ✅ - 559 lines, 43 tests, 99% coverage
6. Translation Engine ✅ - 453 lines, 47 tests, 99% coverage
7. Mapper Tests ✅ - 249 tests total

Result: 2,471 lines TypeScript, 249 tests passing

---

Phase 4: CLI Tool ⬅️ NEXT

Objective: Build command-line interface

1. CLI Scaffolding (1.5h)

   • Create src/cli/index.ts with Commander.js
   • Define commands: convert, validate, migrate, info
   • Set up chalk for colored output, ora for spinners

2. Convert Command (2h)

   • Implement commands/convert.ts
   • Usage: oac-compat convert --from oac --to claude agent.md
   • Support batch conversion

3. Validate Command (1.5h)

   • Implement commands/validate.ts
   • Check compatibility before conversion
   • Report warnings and incompatibilities

4. Migrate Command (2h)

   • Implement commands/migrate.ts
   • Migrate entire projects (all agents + context)
   • Generate migration report

5. Info Command (1h)

   • Implement commands/info.ts
   • Show tool capabilities and feature matrices
   • Display adapter list

6. CLI Integration Tests (2h)

   • Test each command end-to-end
   • Test error handling
   • Test output formatting

---

Phase 5: Documentation

Objective: Create migration guides and API docs

26-30. Migration Guides (4h total)

- `docs/migration-guides/cursor-to-oac.md`
- `docs/migration-guides/claude-to-oac.md`
- `docs/migration-guides/oac-to-cursor.md`
- `docs/migration-guides/oac-to-claude.md`
- `docs/migration-guides/oac-to-windsurf.md`

1. Feature Matrices (1h)

   • Generate comparison tables
   • Document degradation patterns

2. API Documentation (1h)

   • Document programmatic API usage
   • Add examples for each adapter

---

Adding a New Tool Adapter

Step-by-Step

1. Research Tool Format

   • Study tool's configuration file structure
   • Identify supported features
   • Note limitations vs OAC

2. Create Adapter Class

   export class NewToolAdapter extends BaseAdapter {
    name = 'newtool'
    displayName = 'New Tool'
        
    async toOAC(source: string): Promise<OpenAgent> { /* ... */ }
    async fromOAC(agent: OpenAgent): Promise<ConversionResult> { /* ... */ }
    getConfigPath(): string { /* ... */ }
    getCapabilities(): ToolCapabilities { /* ... */ }
    validateConversion(agent: OpenAgent): string[] { /* ... */ }
   }
   

3. Use Existing Mappers

   • ToolMapper for tool name translation
   • PermissionMapper for permission translation
   • ModelMapper for model ID translation
   • ContextMapper for context path translation

4. Register Adapter

   AdapterRegistry.register(new NewToolAdapter())
   

5. Write Tests (Target: 80%+ coverage)

6. Update Documentation

---

Success Criteria

Phase 1-3 ✅ ACHIEVED:

• All files compile without errors
• Zod schemas validate correctly
• All 3 adapters migrated to TypeScript
• Unit tests pass with 80%+ coverage
• All mappers are pure functions
• Graceful degradation works

Phase 4 (upcoming):

• CLI commands work end-to-end
• Error handling is comprehensive
• Output is user-friendly

Phase 5 (upcoming):

• Migration guides cover all tools
• API docs are complete
• Examples demonstrate usage

---

Reference

• Issue: https://github.com/darrenhinde/OpenAgentsControl/issues/141
• Branch: devalexanderdaza/issue141
• Location: packages/compatibility-layer/

Related:

• lookup/compatibility-layer-progress.md
• lookup/compatibility-layer-adapters.md
• lookup/compatibility-layer-structure.md