a8fc9c7715
* fix(shellcheck): declare and assign separately in router.sh (SC2155) * feat(plugin): enhance context management and skill invocation - Update .context-manifest.json to include profile and detailed source information. - Revise context-scout.md to clarify context root discovery and navigation. - Modify commands to replace deprecated skills with updated ones (brainstorming → approach, systematic-debugging → debugger). - Streamline install-context.md for clarity and remove interactive profile selection. - Improve oac-status.md to provide a more comprehensive status report. - Add OAC system paths to session-start.sh for better context management. - Remove obsolete skills and improve documentation for existing commands.
130 lines
4 KiB
Markdown
130 lines
4 KiB
Markdown
<!-- Context: openagents-repo/concepts | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
|
|
|
# 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
|
|
|
|
```typescript
|
|
// Load OAC agent
|
|
const agent = await AgentLoader.loadAgent('.opencode/agent/core/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
|