OpenWriterControle/packages/compatibility-layer/docs/migration-guides/oac-to-windsurf.md

OAC to Windsurf Migration Guide

Migrate your OpenAgents Control (OAC) agent configurations to Windsurf format. This guide covers the CLI migration command, manual conversion steps, and feature mapping differences between the two formats.

---

Prerequisites

• Node.js v18+
• @openagents/compatibility-layer CLI installed:

  npm install -g @openagents/compatibility-layer
  

---

Quick Migration

One command converts your OAC agent to Windsurf:

oac convert --from oac --to windsurf --input .opencode/agent/my-agent.md --output .windsurf/

Output:

• Primary agents → .windsurf/config.json
• Subagents → .windsurf/agents/{name}.json

---

Step-by-Step Manual Migration

Step 1: Extract Frontmatter

Before (OAC .md file):

---
name: code-reviewer
description: Reviews code for quality and security
mode: subagent
model: claude-sonnet-4
temperature: 0.3
tools:
  read: true
  write: false
  bash: false
---

After (Windsurf .json):

{
  "name": "code-reviewer",
  "description": "Reviews code for quality and security",
  "type": "subagent",
  "model": "claude-4-sonnet",
  "creativity": "low",
  "tools": {
    "read": true,
    "write": false,
    "bash": false
  }
}

Step 2: Convert System Prompt

Before (OAC):

---
name: code-reviewer
---

You are a code reviewer. Analyze code for:
- Security vulnerabilities
- Performance issues
- Best practices

After (Windsurf):

{
  "name": "code-reviewer",
  "systemPrompt": "You are a code reviewer. Analyze code for:\n- Security vulnerabilities\n- Performance issues\n- Best practices"
}

Step 3: Map Contexts

Before (OAC):

contexts:
  - path: .opencode/context/code-standards.md
    priority: critical
    description: Company coding standards
  - path: .opencode/context/security-rules.md
    priority: high

After (Windsurf):

{
  "contexts": [
    {
      "path": ".windsurf/context/code-standards.md",
      "priority": "high",
      "description": "Company coding standards"
    },
    {
      "path": ".windsurf/context/security-rules.md",
      "priority": "high"
    }
  ]
}

Note: Copy context files from .opencode/context/ to .windsurf/context/

---

Key Differences

Aspect	OAC	Windsurf
Format	Markdown + YAML frontmatter	JSON
Location	.opencode/agent/*.md	.windsurf/config.json or .windsurf/agents/*.json
Temperature	Numeric (0.0-2.0)	String: low, medium, high
Permissions	Granular (allow/deny/ask per path)	Binary (on/off)
Hooks	Full support	Not supported
Priority Levels	4 levels (critical/high/medium/low)	2 levels (high/low)
Skills	Full Skills system	Basic context references

---

Feature Mapping

OAC Feature	Windsurf Equivalent	Notes
name	name	Direct mapping
description	description	Direct mapping
mode: primary	type: "primary"	Renamed field
mode: subagent	type: "subagent"	Renamed field
model: claude-sonnet-4	model: "claude-4-sonnet"	Model ID format differs
model: claude-opus-4	model: "claude-4-opus"	Model ID format differs
model: gpt-4o	model: "gpt-4o"	Direct mapping
temperature: 0.0-0.4	creativity: "low"	Mapped to string
temperature: 0.4-0.8	creativity: "medium"	Mapped to string
temperature: 0.8-2.0	creativity: "high"	Mapped to string
tools: { read: true }	tools: { read: true }	Direct mapping
permission: { read: "allow" }	permissions: { read: true }	Simplified to boolean
permission: { write: "ask" }	permissions: { write: false }	"ask" → false (cautious)
skills: ["skill-name"]	contexts: [{ path: ".windsurf/context/skill-name.md" }]	Converted to context refs
hooks	❌ Not supported	Lost in conversion
maxSteps	❌ Not supported	Lost in conversion
priority: critical	priority: "high"	Downgraded
priority: medium	priority: "low"	Downgraded

---

Common Patterns

Pattern 1: Agent with Restricted Tools

Before (OAC):

---
name: doc-writer
description: Writes documentation
mode: subagent
tools:
  read: true
  write: true
  edit: true
  bash: false
  task: false
---

You write technical documentation following project standards.

After (Windsurf):

{
  "name": "doc-writer",
  "description": "Writes documentation",
  "type": "subagent",
  "tools": {
    "read": true,
    "write": true,
    "edit": true,
    "bash": false,
    "task": false
  },
  "systemPrompt": "You write technical documentation following project standards."
}

Pattern 2: Agent with Granular Permissions

Before (OAC):

---
name: safe-coder
description: Writes code with restricted access
mode: subagent
permission:
  read: allow
  write:
    allow: ["src/**/*.ts"]
    deny: ["src/secrets/**"]
  bash: ask
---

After (Windsurf):

{
  "name": "safe-coder",
  "description": "Writes code with restricted access",
  "type": "subagent",
  "permissions": {
    "read": true,
    "write": true,
    "bash": false
  }
}

Warning: Granular path rules (allow: ["src/**/*.ts"]) are lost. Windsurf only supports binary on/off.

Pattern 3: Agent with Skills

Before (OAC):

---
name: context-expert
description: Manages project context
mode: subagent
skills:
  - context-manager
  - task-management
---

After (Windsurf):

{
  "name": "context-expert",
  "description": "Manages project context",
  "type": "subagent",
  "contexts": [
    {
      "path": ".windsurf/context/context-manager.md",
      "priority": "medium",
      "description": "Skill: context-manager"
    },
    {
      "path": ".windsurf/context/task-management.md",
      "priority": "medium",
      "description": "Skill: task-management"
    }
  ]
}

Note: You must manually create the skill context files in .windsurf/context/

Pattern 4: Primary Agent with Full Config

Before (OAC):

---
name: main-agent
description: Primary development agent
mode: primary
model: claude-opus-4
temperature: 0.7
tools:
  read: true
  write: true
  edit: true
  bash: true
  task: true
  grep: true
  glob: true
---

You are the primary development agent for this project.

After (Windsurf .windsurf/config.json):

{
  "name": "main-agent",
  "description": "Primary development agent",
  "type": "primary",
  "model": "claude-4-opus",
  "creativity": "medium",
  "tools": {
    "read": true,
    "write": true,
    "edit": true,
    "bash": true,
    "task": true,
    "grep": true,
    "glob": true
  },
  "systemPrompt": "You are the primary development agent for this project."
}

---

Limitations

OAC Feature	Windsurf Support	Impact
Hooks	❌ Not supported	Behavioral rules (PreToolUse, PostToolUse, etc.) are completely lost
maxSteps	❌ Not supported	Execution step limits cannot be enforced
Granular Permissions	⚠️ Degraded	Path-based allow/deny rules become binary on/off
"ask" Permission	⚠️ Degraded	Converted to false (deny) for safety
4-Level Priority	⚠️ Degraded	critical → high, medium → low
Skills System	⚠️ Partial	Converted to basic context file references
Markdown Format	⚠️ Changed	Agent definition moves from .md to .json

---

Validation Steps

After migration, verify your configuration:

1. Validate JSON Syntax

# Check JSON is valid
cat .windsurf/config.json | jq .

2. Verify Required Fields

# Check required fields exist
jq 'has("name") and has("description") and has("systemPrompt")' .windsurf/config.json

3. Test Agent Loading

# If Windsurf CLI available
windsurf validate .windsurf/config.json

4. Check Context Files Exist

# Verify all referenced contexts exist
jq -r '.contexts[]?.path // empty' .windsurf/config.json | while read path; do
  [ -f "$path" ] || echo "Missing: $path"
done

5. Review Conversion Warnings

The CLI outputs warnings for feature degradation:

⚠️  Permission "ask" for bash degraded to false (deny). Windsurf only supports binary on/off.
⚠️  Granular permissions degraded from allow/deny/ask per path to binary on/off per tool
❌ Windsurf does not support hooks - behavioral rules will be lost
💡 2 context file(s) referenced - ensure they exist in .windsurf/context/

---

Troubleshooting

Issue: "Invalid Windsurf config format"

Cause: Input file is not valid JSON or has unexpected structure.

Solution:

# Validate your source OAC file first
oac validate .opencode/agent/my-agent.md

# Check for YAML syntax errors in frontmatter

Issue: Hooks Not Working

Cause: Windsurf does not support hooks. They are silently dropped.

Solution:

• Document hook behavior manually in context files
• Use Windsurf's native features if available
• Accept limitation or stay on OAC

Issue: Permissions Too Restrictive

Cause: ask permissions convert to false (deny).

Solution:

// Manually change if you want to allow
"permissions": {
  "bash": true  // Changed from false
}

Issue: Context Files Not Found

Cause: Context paths reference .opencode/context/ but Windsurf expects .windsurf/context/.

Solution:

# Copy context files to Windsurf location
mkdir -p .windsurf/context
cp .opencode/context/*.md .windsurf/context/

Issue: Model Not Recognized

Cause: Model ID format differs between OAC and Windsurf.

Solution:

// OAC model IDs map to Windsurf:
// claude-sonnet-4 → claude-4-sonnet
// claude-opus-4 → claude-4-opus
// claude-haiku-4 → claude-4-haiku

Issue: Skills Not Loading

Cause: Skills are converted to context references but the context files don't exist.

Solution:

1. Export skill content from OAC
2. Create .windsurf/context/{skill-name}.md files
3. Include skill instructions in each context file

---

Next Steps

1. Run the migration:

   oac convert --from oac --to windsurf --input .opencode/agent/ --output .windsurf/
   

2. Review warnings for feature degradation

3. Copy context files:

   cp -r .opencode/context/* .windsurf/context/
   

4. Create skill context files for any referenced skills

5. Test the converted agent in Windsurf

6. Document lost features (hooks, granular permissions) in your project README

7. Consider keeping OAC as source of truth if you need features Windsurf doesn't support