OpenAgentsControl/.opencode/context/openagents-repo/guides/compatibility-layer-development.md

Guide: Compatibility Layer Development Workflow

Purpose: Step-by-step workflow for developing compatibility layer features

Last Updated: 2026-02-04

---

Core Workflow

Development follows a structured 6-stage approach:

1. Discover (Context)
   ↓
2. Propose (Approval)
   ↓
3. Init Session (Setup)
   ↓
4. Plan (Breakdown)
   ↓
5. Execute (Implement)
   ↓
6. Validate & Handoff

---

Stage 1: Discover

Goal: Understand requirements before implementation

Actions:

1. Use ContextScout to discover relevant context files
2. For external packages: Check install scripts first, then use ExternalScout
3. Read context standards (code-quality.md is MANDATORY)

No files created - Read-only exploration

---

Stage 2: Propose

Goal: Get user approval BEFORE any file creation

Present lightweight summary:

• What we're building (1-2 sentences)
• Components list
• Approach (direct execution vs delegation)
• Context discovered

Wait for user approval before proceeding

---

Stage 3: Init Session

Goal: Create session and persist context (ONLY after approval)

Actions:

1. Create session directory: .tmp/sessions/{YYYY-MM-DD}-{task-slug}/
2. Write context.md with:
   • Task requirements
   • Context files (standards to follow)
   • Reference files (source material)
   • Components
   • Exit criteria

This becomes single source of truth for all agents

---

Stage 4: Plan

Decision: Simple vs Complex?

Simple (1-3 files, <30min):

• Skip TaskManager
• Execute directly in Stage 5

Complex (4+ files, >60min):

• Delegate to TaskManager
• Creates .tmp/tasks/{feature}/task.json + subtasks
• Present plan for confirmation

---

Stage 5: Execute

Incremental approach (one component at a time):

1. Plan Component (if using component-planning):

   • Create component-{name}.md
   • Request approval for design

2. Execute:

   • Load context from session
   • Implement → Validate → Mark complete
   • If delegating: Pass subtask JSON to CoderAgent

3. Integrate:

   • Verify integration with previous components

Critical: Never implement entire plan at once

---

Stage 6: Validate & Handoff

Actions:

1. Run full system integration tests
2. Delegate to TestEngineer or CodeReviewer (pass session context)
3. Summarize what was built
4. Ask user to clean up .tmp files

---

Key Principles

Context First: Load standards BEFORE coding Approval Gates: Never execute without approval Incremental: One step at a time, validate each Stop on Failure: Report → Propose fix → Request approval → Then fix

---

Example: Adapter Implementation

1. Discover:
   - ContextScout finds baseadapter-pattern.md
   - Load code-quality.md standards

2. Propose:
   "Implement WindsurfAdapter (514 lines)
    - Bidirectional conversion
    - Extends BaseAdapter
    - JSON config format"
   
3. Init Session:
   Create .tmp/sessions/2026-02-04-windsurf-adapter/
   Write context.md with standards + references

4. Plan:
   Simple (1 file) → Skip TaskManager

5. Execute:
   - Create WindsurfAdapter.ts
   - Implement toOAC(), fromOAC()
   - Export in index.ts
   - npm run build (validate)

6. Validate:
   - Compilation: ✅ 0 errors
   - Ready for unit tests (next phase)

---

Reference

Related:

• standards/code-quality.md (MANDATORY before coding)
• concepts/compatibility-layer.md
• examples/baseadapter-implementation.md