ca2e35c30b
* feat: implement compatibility layer foundation (Issue #141) - Add TypeScript project setup with strict mode and Vitest - Implement 20+ Zod validation schemas for OpenAgent format - Create BaseAdapter abstract class with template method pattern - Add context documentation for compatibility layer workflow - Setup ESLint, TypeScript, and test configuration Phase 1 Foundation: 50% complete (subtasks 01-03) Related: #141 * feat: implement AgentLoader with TypeScript (Issue #141) - Add AgentLoader class for loading OAC agent files - Implement parseFrontmatter() for YAML extraction - Add extractSections() for markdown parsing (skills, examples, commands, workflow) - Create custom error classes: AgentLoadError, FrontmatterParseError, ValidationError - Support single file and recursive directory loading - Add metadata merging from agent-metadata.json - Export convenience functions: loadAgent(), loadAgents() - Full Zod schema validation with descriptive error messages - 386 lines, type-safe with strict mode Phase 1 Foundation: 66.7% complete (subtask 04/06) Related: #141 * feat: implement AdapterRegistry with TypeScript (Issue #141) - Add AdapterRegistry class for managing tool adapters - Implement type-safe registration with Map<string, BaseAdapter> - Add alias support for adapter names (case-insensitive) - Create custom error class: AdapterRegistryError - Implement methods: register(), get(), list(), has(), getAll(), unregister(), clear() - Add capability-based adapter discovery: getCapabilities(), findByFeature() - Export singleton registry instance and convenience functions - Support lazy loading of built-in adapters (placeholder for Phase 2) - 416 lines, fully type-safe with strict mode Features: - Duplicate registration prevention - Alias conflict detection - O(1) adapter lookup - Sorted adapter listings - Comprehensive JSDoc documentation Phase 1 Foundation: 83.3% complete (subtask 05/06) Related: #141 * feat: create main entry point index.ts (Issue #141) - Add comprehensive barrel exports for public API - Export all Zod schemas and TypeScript types - Export AgentLoader class and convenience functions - Export AdapterRegistry, singleton, and helpers - Export error classes: AgentLoadError, FrontmatterParseError, ValidationError, AdapterRegistryError - Export BaseAdapter for custom adapter creation - Add package VERSION constant - Include JSDoc documentation with usage examples - Organized exports by category (types, core, adapters) - 168 lines with comprehensive documentation All exports: - Types: All Zod schemas and inferred TypeScript types - Core: AgentLoader, AdapterRegistry, registry singleton - Adapters: BaseAdapter abstract class - Errors: All custom error classes - Utilities: Convenience functions (loadAgent, getAdapter, etc.) Phase 1 Foundation: 100% COMPLETE! 🎉 (6/6 subtasks) Related: #141 * feat: implement ClaudeAdapter with bidirectional conversion (Issue #141) - Implement ClaudeAdapter extending BaseAdapter - Support toOAC() conversion from Claude Code format to OAC - Support fromOAC() conversion from OAC to Claude Code format - Handle .claude/config.json for primary agents - Handle .claude/agents/*.md for subagents with YAML frontmatter - Map Claude Skills system to/from OAC contexts - Map hooks (PreToolUse, PostToolUse, etc.) bidirectionally - Degrade granular OAC permissions to Claude permissionMode - Add warnings for unsupported features (temperature, maxSteps) - Export ClaudeAdapter from main index.ts Capabilities: - supportsMultipleAgents: true - supportsSkills: true - supportsHooks: true - supportsGranularPermissions: false (binary only) - supportsTemperature: false - Model ID mapping (claude-sonnet-4 <-> claude-sonnet-4-20250514) - Tool access mapping (OAC ToolAccess <-> Claude tools array) Subtask: compatibility-layer-141-07 Phase: 2 (Adapters Migration) * feat: implement CursorAdapter with single-file format support (Issue #141) - Implement CursorAdapter extending BaseAdapter - Support toOAC() conversion from .cursorrules to OAC - Support fromOAC() conversion from OAC to .cursorrules format - Handle single-file limitation (no multiple agents) - Implement mergeAgents() for combining multiple OAC agents - Parse optional YAML frontmatter in .cursorrules - Inline context files into .cursorrules content - Add comprehensive warnings for lost features Key limitations: - supportsMultipleAgents: false (single .cursorrules file) - supportsSkills: false (must inline content) - supportsHooks: false (not supported by Cursor) - supportsGranularPermissions: false (binary only) - supportsTemperature: true (limited support) Features: - Model ID mapping (gpt-4, claude-3-opus, etc.) - Tool access parsing and generation - Context file inlining with references - Multi-agent merge capability - Frontmatter parsing for metadata Export CursorAdapter from main index.ts Subtask: compatibility-layer-141-08 Phase: 2 (Adapters Migration) * feat: implement WindsurfAdapter with bidirectional conversion (Issue #141) - Add WindsurfAdapter.ts (514 lines) extending BaseAdapter - Support bidirectional OAC ↔ Windsurf JSON conversion - Implement toOAC() for Windsurf config → OpenAgent parsing - Implement fromOAC() for OpenAgent → Windsurf config generation - Add temperature ↔ creativity setting mapping (low/medium/high) - Add model ID mapping (claude-sonnet-4 ↔ claude-4-sonnet) - Support multi-agent configuration via .windsurf/agents/ - Support context files via .windsurf/context/ - Implement binary permission mapping with degradation warnings - Add priority level normalization (critical/high/medium/low → high/low) - Export WindsurfAdapter in index.ts - All adapters now complete: Claude, Cursor, Windsurf - Compilation successful: 0 errors, 0 warnings Phase 2 (Adapters): 50% complete (3/6 subtasks) Total progress: 28.13% (9/32 subtasks) Code stats: 3,333 lines TypeScript (Foundation + Adapters) * docs: add compatibility layer context files and progress tracking (Issue #141) - Add baseadapter-implementation.md with detailed adapter pattern and testing examples - Add compatibility-layer-development.md with development workflow and best practices - Add compatibility-layer-adapters.md lookup table with adapter specifications - Add compatibility-layer-progress.md tracking Phase 1 completion and Phase 2 status - Add compatibility-learnings.md documenting implementation learnings - Update compatibility-layer.md with latest architecture insights These context files support Phase 2 adapter unit testing and future adapter development. * test: implement comprehensive unit tests for ClaudeAdapter (Issue #141 - Subtask 10) Implemented 80 test cases covering: - toOAC() parsing of config.json and agent.md (YAML frontmatter) - fromOAC() conversion to config.json and agent.md formats - Capabilities and feature validation - Model, tool, skill, hook, and permission mapping - Skill generation from contexts - Edge cases and error handling - Roundtrip conversion validation Coverage achieved: - 96.32% statements (target: 80%+) ✅ - 100% functions (target: 80%+) ✅ - 82.14% branches (target: 75%+) ✅ All test cases follow AAA pattern (Arrange-Act-Assert) and test standards from .opencode/context/core/standards/test-coverage.md * test: implement comprehensive unit tests for CursorAdapter (Issue #141 - Subtask 11) Implemented 78 test cases covering: - toOAC() parsing of plain .cursorrules and YAML frontmatter - fromOAC() conversion to .cursorrules format - Capabilities and feature validation - Agent merging (CURSOR-SPECIFIC - unique feature) - Model, tool mapping - Context inlining - Temperature and configuration handling - Edge cases and error handling - Roundtrip conversion validation Coverage achieved: - 98.55% statements (target: 80%+) ✅ - 100% functions (target: 80%+) ✅ - 89.65% branches (target: 75%+) ✅ Key test areas: - Plain text .cursorrules parsing (no frontmatter) - YAML frontmatter parsing with type coercion - Agent merging (single, two, three+ agents) - Tool union and temperature MAX behavior - Context inlining with proper formatting - Model mapping (Cursor ↔ OAC) All test cases follow AAA pattern and test standards. * test: implement comprehensive unit tests for WindsurfAdapter (Issue #141 - Subtask 12) * feat: implement Phase 3 mappers and translation engine with tests (Issue #141) - Add ToolMapper: maps tool names between OAC and Claude/Cursor/Windsurf - Add PermissionMapper: translates granular to binary permissions - Add ModelMapper: maps AI model IDs between platforms - Add ContextMapper: maps context file paths between platforms - Add CapabilityMatrix: feature compatibility analysis across platforms - Add TranslationEngine: orchestrates all mappers for complete translation Test coverage: - ToolMapper: 100% statements, 100% branches - PermissionMapper: 98% statements, 96% branches - ModelMapper: 99% statements, 90% branches - ContextMapper: 97% statements, 94% branches - CapabilityMatrix: 99% statements, 96% branches - TranslationEngine: 99% statements, 93% branches Total: 485 tests passing (249 new tests added) * docs: update Issue #141 context files to reflect Phase 3 completion - Update progress from 28% to 59.4% (19/32 subtasks) - Mark Phases 1-3 as complete (Foundation, Adapters, Mappers) - Update code stats: 5,799 source lines, 6,322 test lines - Add test coverage metrics: 485 tests, 97-100% on Phase 3 - Update structure with all implemented files - Add executive summary for token-efficient context loading - Document next steps: Phase 4 CLI implementation * docs(context): harvest Claude Code docs and fix MVI compliance (Phase 1) - Harvest external Claude Code documentation into context system: - hooks-system, agent-skills, subagents-system concepts - hook-events, skill-metadata, builtin-subagents lookups - Example files for hooks, skills, and subagents - Plugin architecture and migration guides - Fix 6 critical MVI violations (files > 200 lines): - Split adding-agent.md → adding-agent-basics.md + adding-agent-testing.md - Split adding-skill.md → 3 files (basics, implementation, example) - Split task-delegation.md → 3 files (basics, specialists, caching) - Split external-libraries.md → 3 files (workflow, scenarios, faq) - Split design-assets.md → 4 files (images, icons, fonts, cdn) - Split navigation-design.md → 2 files (basics, templates) - Update navigation files with new references - Remove consumed source docs from to-be-consumed/ Total: 17 new files created, 6 large files replaced, 5 source docs consumed * docs(context): MVI compliance Phase 2 - split large workflow and UI files Split 3 large files into MVI-compliant modules (< 200 lines each): - design-iteration.md (1058 lines) → 9 files: - design-iteration-overview.md (overview, when to use) - design-iteration-plan-file.md (mandatory plan template) - design-iteration-stage-layout.md (Stage 1) - design-iteration-stage-theme.md (Stage 2) - design-iteration-stage-animation.md (Stage 3) - design-iteration-stage-implementation.md (Stage 4) - design-iteration-visual-content.md (Image Specialist) - design-iteration-best-practices.md (quality, troubleshooting) - design-iteration-plan-iterations.md (managing iterations) - animation-patterns.md (753 lines) → 6 files: - animation-basics.md (fundamentals, timing, easing) - animation-components.md (buttons, cards, modals) - animation-chat.md (message, typing animations) - animation-loading.md (skeleton, spinner, progress) - animation-forms.md (focus, validation, scroll) - animation-advanced.md (recipes, best practices) - premium-dark-ui-quick-start.md (638 lines) → 4 files: - premium-dark-ui-colors.md (palette, typography, spacing) - premium-dark-ui-components.md (core building blocks) - premium-dark-ui-layouts.md (hero, features, CTA) - premium-dark-ui-advanced.md (animations, accessibility) Updated navigation files with new references. * feat(cli): implement CLI scaffolding with Commander.js (Issue #141 - Subtask 20) - Add src/cli/index.ts: CLI entry point with convert, validate, migrate, info commands - Add src/cli/types.ts: TypeScript type definitions for CLI options - Add src/cli/utils.ts: Logging, spinner, and formatting utilities - Add "type": "module" to package.json for ESM support - Global options: --verbose, --quiet, --output-format (json|text) - Commands are placeholders pending implementation in subtasks 21-24 * feat(cli): implement convert command with full format support (Issue #141 - Subtask 21) - Add src/cli/commands/convert.ts: Complete convert command implementation - Auto-detect input format from file path and content - Support bidirectional conversion: OAC <-> Cursor/Claude/Windsurf - Output to stdout by default, file with --output flag - Display warnings for feature loss during conversion - Enable registerBuiltInAdapters in AdapterRegistry - Add public constructors to all adapters (CursorAdapter, ClaudeAdapter, WindsurfAdapter) - Fix ESM imports: add .js extensions to all relative imports across codebase All 485 tests passing. * feat(cli): implement validate and info commands (Issue #141 - Subtasks 22, 24) - validate: Checks agent compatibility with target format - Reports compatibility score (0-100%) - Lists preserved/degraded/lost features - Provides suggestions for unsupported features - Exit codes: 0=compatible, 1=partial, 2=incompatible - Supports --strict and --output-format json - info: Displays tool capabilities and feature parity - Shows feature matrix for all platforms - Detailed view for single platform - Platform comparison with --compare - Documentation links - Supports --output-format json * feat(cli): implement migrate command and add migration guides (Issue #141) - Add migrate command for full project migration with batch conversion - Support --dry-run, --force, and --out-dir options - Generate migration reports with success/failure summaries - Preserve directory structure in output Documentation: - Add 5 migration guides (cursor↔oac, claude↔oac, oac→windsurf) - Add comprehensive feature-matrices.md with platform comparisons - Document lossless vs lossy conversion impacts Completes subtasks: 23, 26, 27, 28, 29, 30, 31 * test(cli): add comprehensive integration tests for all CLI commands (Issue #141) - Add convert.test.ts with 23 tests for format conversions - Add validate.test.ts with 21 tests for compatibility validation - Add migrate.test.ts with 25 tests for batch migration - Add info.test.ts with 30 tests for capability queries - Add test fixtures for OAC, Cursor, and Claude formats - Fix empty directory warning in migrate command All 584 tests passing with full coverage of CLI modules. Completes subtask 25 * docs: update README with comprehensive CLI and API documentation (Issue #141) - Add complete CLI command reference with all options - Add programmatic API usage examples - Add feature parity matrix summary - Add links to all migration guides - Add architecture overview - Add custom adapter creation guide Completes subtask 32 - Feature #141 fully implemented * docs: add visual examples and format improvements to README - Add Cursor IDE screenshot (contextscout-cursor.png) - Add Claude Code validation screenshot (claude-code-validation.png) - Format code examples with consistent double quotes - Align feature parity matrix table - Add .cursorrules and bun.lock to .gitignore * fix(lint): resolve all ESLint errors in compatibility layer - Remove async from methods with no await expressions (toOAC, fromOAC, loadFromFile) - Wrap Promise-returning methods with Promise.resolve/reject - Fix unsafe type assertions (replace 'as any' with proper type validation) - Add missing getConfigPath() method to WindsurfAdapter - Validate AgentCategory enum values before assignment - Fix return type compatibility issues All 584 tests passing, 0 ESLint errors (7 acceptable warnings for missing callback return types) * chore: update package.json author and contributors metadata - Update author from string to object format with name and GitHub URL - Add Alexander Daza as contributor with email and GitHub profile - Maintain npm package.json standard format for author/contributors fields
133 lines
4.2 KiB
Markdown
133 lines
4.2 KiB
Markdown
# Lookup: Tool Feature Parity Matrix
|
|
|
|
**Purpose**: Quick reference for feature support across AI coding tools
|
|
|
|
**Last Updated**: 2026-02-04
|
|
|
|
---
|
|
|
|
## Feature Comparison
|
|
|
|
### Core Features
|
|
|
|
| Feature | OAC | Claude Code | Cursor IDE | Windsurf | Notes |
|
|
|---------|-----|-------------|------------|----------|-------|
|
|
| **Multiple agents** | ✅ Yes | ✅ Yes | ❌ Single only | ✅ Yes | Cursor requires merged config |
|
|
| **Agent modes** | ✅ primary/subagent | ✅ Yes | ❌ No | ⚠️ Partial | OAC has explicit mode field |
|
|
| **Temperature control** | ✅ 0.0-2.0 | ❌ No | ⚠️ Limited | ⚠️ Limited | Maps to creativity settings |
|
|
| **Model selection** | ✅ Full control | ✅ Yes | ✅ Yes | ✅ Yes | Different ID formats |
|
|
| **Context files** | ✅ .opencode/context/ | ✅ Skills system | ✅ .cursorrules | ✅ Yes | Path mapping required |
|
|
|
|
### Tool Permissions
|
|
|
|
| Tool Access | OAC | Claude Code | Cursor IDE | Windsurf |
|
|
|-------------|-----|-------------|------------|----------|
|
|
| **read** | ✅ Granular | ⚠️ Binary on/off | ⚠️ Binary | ⚠️ Binary |
|
|
| **write** | ✅ Granular | ⚠️ Binary | ⚠️ Binary | ⚠️ Binary |
|
|
| **edit** | ✅ Granular | ⚠️ Binary | ⚠️ Binary | ⚠️ Binary |
|
|
| **bash** | ✅ Granular | ✅ Yes | ✅ Yes | ✅ Yes |
|
|
| **task** | ✅ Delegation | ✅ Yes | ❌ No | ⚠️ Limited |
|
|
| **grep/glob** | ✅ Separate | ✅ Yes | ✅ Yes | ✅ Yes |
|
|
|
|
**Legend**: ✅ Full support | ⚠️ Partial/degraded | ❌ Not supported
|
|
|
|
### Advanced Features
|
|
|
|
| Feature | OAC | Claude Code | Cursor IDE | Windsurf |
|
|
|---------|-----|-------------|------------|----------|
|
|
| **Skills system** | ✅ Yes | ✅ Yes | ❌ No | ⚠️ Partial |
|
|
| **Hooks** | ✅ 5 types | ✅ Yes | ❌ No | ❌ No |
|
|
| **Dependencies** | ✅ Explicit | ✅ Yes | ❌ No | ⚠️ Partial |
|
|
| **Priority levels** | ✅ 4 levels | ⚠️ 2 levels | ❌ No | ⚠️ 2 levels |
|
|
| **Agent categories** | ✅ 8 types | ⚠️ Limited | ❌ No | ⚠️ Limited |
|
|
|
|
---
|
|
|
|
## Hook Event Support
|
|
|
|
| Event | OAC | Claude Code | Cursor | Windsurf |
|
|
|-------|-----|-------------|--------|----------|
|
|
| PreToolUse | ✅ | ✅ | ❌ | ❌ |
|
|
| PostToolUse | ✅ | ✅ | ❌ | ❌ |
|
|
| PermissionRequest | ✅ | ✅ | ❌ | ❌ |
|
|
| AgentStart | ✅ | ✅ | ❌ | ❌ |
|
|
| AgentEnd | ✅ | ✅ | ❌ | ❌ |
|
|
|
|
---
|
|
|
|
## Permission Granularity Mapping
|
|
|
|
### OAC → Other Tools (Degradation)
|
|
|
|
```
|
|
OAC Granular Permission:
|
|
{
|
|
allow: ["src/**/*.ts"],
|
|
deny: ["src/secrets/**"],
|
|
ask: ["package.json"]
|
|
}
|
|
|
|
↓ Maps to ↓
|
|
|
|
Claude: tools.write = true (with warnings in skills)
|
|
Cursor: Full write access (no granularity)
|
|
Windsurf: Basic allow/deny (ask → deny)
|
|
```
|
|
|
|
---
|
|
|
|
## Model ID Mapping
|
|
|
|
| OAC Model ID | Claude Code | Cursor IDE | Windsurf |
|
|
|--------------|-------------|------------|----------|
|
|
| claude-sonnet-4 | claude-sonnet-4-20250514 | claude-sonnet-4 | claude-4-sonnet |
|
|
| gpt-4 | N/A | gpt-4 | gpt-4 |
|
|
| gpt-4-turbo | N/A | gpt-4-turbo | gpt-4-turbo |
|
|
|
|
---
|
|
|
|
## Configuration File Paths
|
|
|
|
| Tool | Primary Config | Context/Skills | Agents |
|
|
|------|----------------|----------------|--------|
|
|
| **OAC** | .opencode/agent/ | .opencode/context/ | .opencode/agent/*.md |
|
|
| **Claude** | .claude/config.json | .claude/skills/ | .claude/agents/ |
|
|
| **Cursor** | .cursorrules | (inline) | Single file only |
|
|
| **Windsurf** | .windsurf/config.json | .windsurf/context/ | .windsurf/agents/ |
|
|
|
|
---
|
|
|
|
## Conversion Compatibility
|
|
|
|
### OAC → Claude Code
|
|
- ✅ Full feature preservation
|
|
- ⚠️ Temperature ignored (not supported)
|
|
- ✅ Hooks preserved
|
|
- ✅ Skills map 1:1
|
|
|
|
### OAC → Cursor IDE
|
|
- ⚠️ Multiple agents → merged single file
|
|
- ❌ Hooks lost
|
|
- ❌ Skills → inline context
|
|
- ⚠️ Granular permissions → binary
|
|
|
|
### OAC → Windsurf
|
|
- ✅ Multiple agents preserved
|
|
- ⚠️ Temperature → creativity setting
|
|
- ❌ Hooks lost
|
|
- ⚠️ Skills → partial mapping
|
|
|
|
### Reverse Conversions
|
|
- Claude → OAC: ✅ High fidelity
|
|
- Cursor → OAC: ⚠️ Limited (single agent)
|
|
- Windsurf → OAC: ⚠️ Partial feature loss
|
|
|
|
---
|
|
|
|
## Reference
|
|
|
|
- **Implementation**: `packages/compatibility-layer/src/mappers/`
|
|
- **Related**:
|
|
- concepts/compatibility-layer.md
|
|
- examples/baseadapter-pattern.md
|
|
- guides/compatibility-layer-workflow.md
|