OpenAgentsControl/plugins/claude-code/scripts/context/openagents-repo/lookup/compatibility-layer-structure.md

Lookup: Compatibility Layer File Structure

Purpose: Quick reference for where files go in the compatibility-layer package

Last Updated: 2026-02-05

---

Package Location

packages/compatibility-layer/

---

Directory Structure (Current State)

compatibility-layer/
├── package.json              # Dependencies, scripts
├── tsconfig.json             # TypeScript config (strict, ES2022)
├── vitest.config.ts          # Test config (80% coverage threshold)
├── README.md                 # Package documentation
│
├── src/                      # Source code (5,799 lines)
│   ├── types.ts              # Zod schemas + type exports (315 lines) ✅
│   ├── index.ts              # Public API exports (335 lines) ✅
│   │
│   ├── adapters/             # Tool adapters ✅ COMPLETE
│   │   ├── BaseAdapter.ts    # Abstract base class (190 lines)
│   │   ├── ClaudeAdapter.ts  # Claude Code adapter (600 lines)
│   │   ├── CursorAdapter.ts  # Cursor IDE adapter (554 lines)
│   │   └── WindsurfAdapter.ts # Windsurf adapter (514 lines)
│   │
│   ├── core/                 # Core services ✅ COMPLETE
│   │   ├── AgentLoader.ts    # Load/parse OAC agents (386 lines)
│   │   ├── AdapterRegistry.ts # Adapter management (416 lines)
│   │   ├── CapabilityMatrix.ts # Feature parity tracking (559 lines)
│   │   └── TranslationEngine.ts # Conversion orchestration (453 lines)
│   │
│   ├── mappers/              # Feature mappers ✅ COMPLETE
│   │   ├── ToolMapper.ts     # Tool name mapping (308 lines)
│   │   ├── PermissionMapper.ts # Permission translation (354 lines)
│   │   ├── ModelMapper.ts    # Model ID mapping (413 lines)
│   │   └── ContextMapper.ts  # Context path mapping (384 lines)
│   │
│   └── cli/                  # Command-line interface 📝 TODO
│       ├── index.ts          # CLI entry point
│       └── commands/
│           ├── convert.ts    # Convert command
│           ├── validate.ts   # Validate command
│           ├── migrate.ts    # Migrate command
│           └── info.ts       # Info command
│
├── tests/                    # Test files (6,322 lines, 485 tests)
│   └── unit/
│       ├── adapters/         # Adapter tests ✅ COMPLETE
│       │   ├── ClaudeAdapter.test.ts (80 tests)
│       │   ├── CursorAdapter.test.ts (78 tests)
│       │   └── WindsurfAdapter.test.ts (78 tests)
│       ├── mappers/          # Mapper tests ✅ COMPLETE
│       │   ├── ToolMapper.test.ts (34 tests)
│       │   ├── PermissionMapper.test.ts (37 tests)
│       │   ├── ModelMapper.test.ts (37 tests)
│       │   └── ContextMapper.test.ts (51 tests)
│       └── core/             # Core tests ✅ COMPLETE
│           ├── CapabilityMatrix.test.ts (43 tests)
│           └── TranslationEngine.test.ts (47 tests)
│
├── docs/                     # Documentation 📝 TODO
│   ├── migration-guides/     # Migration instructions
│   ├── feature-matrices/     # Feature comparison tables
│   └── api/                  # API documentation
│
└── dist/                     # Compiled output (auto-generated)

---

Implementation Status

✅ Complete (Phases 1-3)

File	Lines	Tests	Coverage
types.ts	315	-	-
index.ts	335	-	-
BaseAdapter.ts	190	-	92%
ClaudeAdapter.ts	600	80	96%
CursorAdapter.ts	554	78	99%
WindsurfAdapter.ts	514	78	99%
AgentLoader.ts	386	-	0%*
AdapterRegistry.ts	416	-	0%*
CapabilityMatrix.ts	559	43	99%
TranslationEngine.ts	453	47	99%
ToolMapper.ts	308	34	100%
PermissionMapper.ts	354	37	98%
ModelMapper.ts	413	37	99%
ContextMapper.ts	384	51	97%

*AgentLoader and AdapterRegistry are tested indirectly via adapters

📝 Pending (Phase 4-5)

File	Purpose	Phase
cli/index.ts	CLI entry point	4
cli/commands/convert.ts	Convert command	4
cli/commands/validate.ts	Validate command	4
cli/commands/migrate.ts	Migrate command	4
cli/commands/info.ts	Info command	4
docs/migration-guides/*.md	Migration guides	5
docs/api/*.md	API documentation	5

---

Dependencies

Production

Package	Purpose	Version
zod	Schema validation	^3.22.0
js-yaml	YAML parsing	^4.1.0
gray-matter	Frontmatter extraction	^4.0.3

Development

Package	Purpose	Version
typescript	TypeScript compiler	^5.4.0
vitest	Test framework	^1.6.1
@vitest/coverage-v8	Coverage reporting	^1.6.1

CLI (Phase 4 - to be added)

Package	Purpose	Version
commander	CLI framework	^11.1.0
chalk	Terminal colors	^5.3.0
ora	Loading spinners	^7.0.1

---

Scripts

{
  "build": "tsc",
  "build:watch": "tsc --watch",
  "test": "vitest run",
  "test:watch": "vitest",
  "test:coverage": "vitest run --coverage"
}

---

Reference

• Issue: https://github.com/darrenhinde/OpenAgentsControl/issues/141
• Branch: devalexanderdaza/issue141

Related:

• lookup/compatibility-layer-progress.md
• lookup/compatibility-layer-adapters.md
• guides/compatibility-layer-workflow.md