OpenAgentsControl/.opencode/context/openagents-repo/concepts/compatibility-layer.md

Concept: Compatibility Layer Architecture

Purpose: Enable bidirectional translation between OpenAgents Control and other AI coding tools

Last Updated: 2026-02-04

---

Core Idea

Adapter pattern that translates agent configurations between OAC format and tool-specific formats (Cursor IDE, Claude Code, Windsurf). Enables seamless migration and multi-tool workflows through bidirectional mapping with graceful degradation.

---

Key Components

Adapters: Tool-specific translation classes inheriting from BaseAdapter

• ClaudeAdapter - Claude Code format (.claude/config.json + skills)
• CursorAdapter - Cursor IDE format (.cursorrules single file)
• WindsurfAdapter - Windsurf format (.windsurf/agents/)

Mappers: Pure functions for feature translation

• ToolMapper - Tool name mapping (bash → terminal, task → delegate)
• PermissionMapper - Permission translation with degradation
• ModelMapper - Model ID mapping with fallbacks
• ContextMapper - Context file path translation

Core Services:

• AgentLoader - Parse OAC markdown files with YAML frontmatter
• AdapterRegistry - Register and retrieve adapters
• TranslationEngine - Orchestrate bidirectional conversion
• CapabilityMatrix - Track feature parity across tools

---

Architecture Pattern

OAC Agent File (.md)
  ↓ (parse)
AgentLoader → OpenAgent object (validated with Zod)
  ↓ (convert)
BaseAdapter.fromOAC()
  ↓ (map features)
Mappers (tools, permissions, models, contexts)
  ↓ (output)
Tool-specific config files

Reverse direction: Tool config → toOAC() → OpenAgent → OAC .md file

---

Design Principles

• Bidirectional: Convert OAC → Tool AND Tool → OAC where possible
• Graceful Degradation: Map unsupported features to closest equivalent with warnings
• Pure Mappers: All mapping functions are pure (no side effects)
• Template Method: BaseAdapter defines algorithm, subclasses fill details
• Validation First: Zod schemas validate before/after conversion

---

Feature Parity

Feature	OAC	Claude	Cursor	Windsurf
Multiple agents	✅	✅	❌ Single	✅
Granular permissions	✅	⚠️ Simplified	❌	⚠️ Partial
Temperature	✅	❌	⚠️ Partial	⚠️ Partial
Skills	✅	✅	❌	⚠️ Partial
Hooks	✅	✅	❌	❌
Context files	✅	✅ Skills	✅ .cursorrules	✅

---

Quick Example

// Load OAC agent
const agent = await AgentLoader.loadAgent('.opencode/agent/openagent.md')

// Get Claude adapter
const adapter = AdapterRegistry.get('claude')

// Convert to Claude format
const result = await adapter.fromOAC(agent)

// Outputs: .claude/config.json, .claude/skills/[...]
console.log(result.configs) // Array of files to write
console.log(result.warnings) // Feature degradation warnings

---

Common Challenges

Single-File Tools (Cursor): Merge multiple OAC agents into one .cursorrules file Permission Mapping: OAC granular permissions → simplified tool permissions Model IDs: Different tools use different model identifiers (requires mapping table) Context Paths: OAC uses .opencode/context/, tools use various paths

---

Implementation Status

Issue #141: https://github.com/darrenhinde/OpenAgentsControl/issues/141

Progress: 28.13% (9/32 subtasks)

• ✅ Phase 1 (Foundation): 100% complete - 1,475 lines
• ⬅️ Phase 2 (Adapters): 50% complete - 1,858 lines (implementations done, tests pending)
• 📝 Phase 3 (Mappers): 0% - Pending
• 📝 Phase 4 (CLI): 0% - Pending
• 📝 Phase 5 (Documentation): 0% - Pending

Location: packages/compatibility-layer/src/

---

Reference

• Related:
  • examples/baseadapter-implementation.md
  • guides/compatibility-layer-development.md
  • lookup/compatibility-layer-adapters.md
  • lookup/compatibility-layer-progress.md
  • lookup/compatibility-learnings.md
  • lookup/tool-feature-parity.md