Host support: Windsurf/Cascade — rules, skills, workflows, hooks, and MCP with Devin Desktop profile separation

[ScriptedAlchemy]

Scope and research evidence

P2 feature expansion. Research date 2026-09-06; Agent Bundle baseline 5fc8de37c9695b816d55bdcf18a6bcb1dfee69f5. Official documentation read; no desktop application was installed or exercised.

Important identity correction: the official Windsurf documentation now redirects to Devin Desktop. Its pages distinguish legacy Cascade from the newer Devin Local agent. This issue owns the requested Windsurf/Cascade compatibility surface; coordinate Devin Local/CLI overlap with #701 rather than assume two names mean identical runtime contracts. Do not mark Cascade hooks or workflows supported in Devin Local merely because the editor contains both.

Primary sources and specifications

• Cascade rules and activation modes — canonical destination of https://docs.windsurf.com/windsurf/cascade/memories
• Cascade skills and file format
• Workflows, discovery and scope precedence
• Hooks: event payloads, exit behavior, configuration levels and platforms
• MCP server configuration and authorization
• Current documentation index

Pin supported editor/agent versions and native parser behavior when implementing. The links above are research references, not an immutable compatibility version.

Native surfaces

Rules are declarative guidance, not deterministic permission enforcement. Workspace rules use trigger modes (always_on, glob, model_decision, manual); current rules docs prefer .devin/rules and retain .windsurf/rules as fallback. The global rule file is a separate, always-on singleton. Root/subdirectory AGENTS.md have scope semantics. Preserve explicit author intent and do not emit the same rules into every fallback directory.

Cascade skills use .windsurf/skills/<name>/SKILL.md or the global Windsurf skills root. Workflows are Markdown prompt procedures invoked manually; their storage and scope rules differ from rules. The host explicitly says Devin Local does not consume Cascade workflows. Neither a rule nor a workflow should create an executable tool route by itself.

MCP for Cascade is configured in ~/.codeium/windsurf/mcp_config.json. This is not proof that a project-local MCP document is automatically loaded. Devin Local uses its CLI configuration instead. Native tool enablement, enterprise controls and OAuth remain authoritative.

Illustrative generated content and install binding

composite-root/
  .windsurf/rules/review.md       # compatibility profile; choose one rule root
  .windsurf/skills/review/SKILL.md
  .windsurf/workflows/review.md
  hooks/cascade-before.mjs
  mcp/example.mjs
  integration/cascade-hooks.json
  integration/cascade-mcp.json

A workspace rule:

---
trigger: glob
globs: "src/**/*.ts"
---

The body is authored guidance generated through the existing content pipeline. Preserve unknown/unrepresentable activation behavior as a diagnostic rather than widening a scoped rule to always-on.

Proposed installation patch, not a document Cascade necessarily auto-discovers inside an arbitrary plugin directory:

{
  "mcpServers": {
    "example": {
      "command": "node",
      "args": ["/absolute/installed-plugin/mcp/example.mjs"]
    }
  }
}

Use the native MCP settings UI to review/install or apply a receipt-owned merge into the documented user file. No windsurf plugin install package command was established by these references; do not invent one. Do not replace the whole user config, leak credentials, or silently make a project-scoped request global.

Hook mapping

Cascade merges system, user and workspace hooks in that order. Workspace hooks use .windsurf/hooks.json; user IDE and JetBrains paths differ. Command fields support POSIX shell and optional PowerShell behavior. Inputs include action, conversation and turn identities plus event-specific tool_info. Pre-hooks can block via exit 2; other failures are not equivalent to a canonical deny. Post-hooks cannot undo completed actions. Restricted Mode disables hook loading.

Illustrative native configuration after installer path resolution:

{
  "hooks": {
    "pre_mcp_tool_use": [{
      "command": "node /absolute/installed-plugin/hooks/cascade-before.mjs",
      "show_output": false
    }]
  }
}

Do not assume UI-visible stdout is model-context injection. Add only codecs whose effect is documented. Preserve quoting, multi-root working-directory behavior and missing home-expansion semantics. System/enterprise policy files are not Agent Bundle installation destinations by default.

Implementation plan

1. Define separate versioned Cascade and Devin Local capability profiles; first ship the smallest proven Cascade subset.
2. Reuse rules/skills/workflow generation and canonical MCP launch records. Generate native hook codecs around shared execution only where semantics match.
3. Model installation as owned file/config bindings rather than pretending an editor extension or npm plugin runtime is necessary.
4. Test .devin/.windsurf/AGENTS.md precedence and collisions with Host support: Devin CLI — native plugin manifest, portable compatibility, and versioned MCP/hook profiles #701 and other composite hosts. A successful file merge is not effective-discovery proof.
5. Keep code immutable, explicit environment inputs secret-free, state outside the installed artifact and cleanup receipt-owned.

Acceptance

• Pin editor and selected agent identity; surface unsupported profile combinations accurately.
• Preserve all rule trigger modes, directory scope and documented size limits without silent truncation.
• Skills activate and workflows remain manual; content-only installation launches no plugin runtime.
• A declared MCP tool succeeds from a relocated/source-free installation with native authorization intact.
• Pre-hook exit 2 prevents a sentinel operation; post-hook/error/Restricted Mode behavior matches the actual host.
• Test global/user/workspace merging, Windows quoting and multi-root cwd with no system-policy mutation.
• Update/remove preserves unrelated rules, user MCP entries, disabled tools and durable state.
• Test composite forbidden discovery and native-versus-legacy rule precedence with reversed target order.
• Record real UI/agent completion separately from JSON validation and synthetic fixtures.

Use existing adapters, manifest/launch/receipt machinery and #651/#652 tests. No memory engine, editor extension marketplace, duplicate agent runtime, automatic migration of user memories, trust bypass or blanket removal of AB4106.

[ScriptedAlchemy]

Landed in #727, squash-merged as b5cf7575e0 on main.

Cascade reads the artifact Agent Bundle already emits, so this needed no adapter, projection, or compiler change — the support is one pinned record in packages/agent-bundle/src/adapters/capabilities/portable-1.0.0.json, which feeds the generated en/zh hosts reference, the generated INSTALL.md, and the discovery tests. Read against docs.devin.ai/desktop on 2026-09-06, where Windsurf is renamed Devin Desktop and Cascade is documented as the legacy agent beside the Devin Local agent.

Tier: skills. Cascade has no register-in-place flag, so a skill directory is copied into one of its discovery roots:

cp -R skills/<skill> .agents/skills/<skill>

.windsurf/skills/<skill>/ (workspace) and ~/.codeium/windsurf/skills/<skill>/ (global) are the Cascade-specific roots; .agents/skills/ and ~/.agents/skills/ are read for cross-agent compatibility, which is where the emitted tree is copied.

Surface	State	Evidence
skills	partial	cascade/skills requires the layout this projection emits and reads .agents/skills/ for cross-agent compatibility. Partial, not full: the emitted package root is not a Cascade discovery root, so each skill directory is copied into one of the roots above before Cascade sees it, and the copy is what loads.
manifest	unsupported	Cascade's documented customization units are Skills, Rules, Workflows, and AGENTS.md (skills, memories); no page defines a plugin manifest, so the emitted root plugin.json is read by nothing there.
mcp	unsupported	Cascade reads MCP servers from ~/.codeium/windsurf/mcp_config.json only (cascade/mcp), where a remote server "requires a serverUrl or url field"; no page reads a plugin-relative mcp.json, so the emitted document is not a Cascade MCP source.
placeholders	unsupported	The documented interpolation patterns are ${env:VAR_NAME} and ${file:/path/to/file} in mcp_config.json; ${PLUGIN_ROOT} and ${PLUGIN_DATA} are documented nowhere for Cascade, so Agent Plugins 1.0.0 §9.1 reserved behavior is not provided.
hooks	unsupported	Agent Plugins 1.0.0 defines no hooks, so this projection emits no hooks document for Cascade to read.

Deferred: nothing for Cascade. Devin Desktop's other profile, the Devin Local agent, uses the Devin CLI configuration per its own page, and that profile is already recorded as devin-cli (#701) at the agent-plugins tier — the two profiles are separate records on purpose rather than one blended claim.