Agent Harness Compatibility Matrix

This doc surveys the agent-config standards across the agentic-coding harness ecosystem and records how nexus-agents reaches each. AGENTS.md is the canonical surface (per #2805, choosing option B of #2764). Every other harness file in this repo is a thin redirect.

Why federate on AGENTS.md

AGENTS.md is the convergence point. As of Q2 2026 it has explicit support in:

  • OpenAI Codex CLI (codex command)
  • Anthropic Claude Code (via fallback when CLAUDE.md is absent)
  • Cursor (since v0.45 — picked up via .cursor/rules/ or direct AGENTS.md discovery)
  • Windsurf (via Cascade context discovery)
  • Aider (added in v0.69+)
  • Cline / Roo Code (project-context discovery)
  • Continue (rule sources can point at AGENTS.md)
  • Goose (project conventions discovery)
  • OpenCode (opencode.json instructions can reference AGENTS.md)

Maintaining one document with thin shims into each harness gives full coverage for ~30 LOC of shims vs. ~6 KLOC of duplicated content if each harness’s file were independent.

What each harness discovers

HarnessDiscovery file(s)Discovery scopeLoading modelNative instruction format
Anthropic Claude CodeCLAUDE.md (primary), AGENTS.md (fallback)Project root + walking up to $HOMEAuto-loaded into every session’s system promptMarkdown with optional <system-reminder> tags
OpenAI Codex CLIAGENTS.md (canonical, since launch)Project root + global at ~/.codex/AGENTS.mdAuto-loaded at session startMarkdown
Cursor.cursor/rules/*.mdc, .cursorrules (legacy), AGENTS.mdProject rootRule files matched by globs + description; AGENTS.md loaded as project contextMDC (Cursor’s markdown-with-frontmatter) or plain markdown
Windsurf.windsurfrules, .windsurf/rules/*.md, AGENTS.mdProject rootCascade indexes all rule sourcesMarkdown
Aider.aider.conf.yml (config), CONVENTIONS.md (content), AGENTS.mdProject rootread: [...] in conf points at content filesYAML config; markdown content
Cline / Roo Code.clinerules/*, AGENTS.mdProject rootLoaded into Cline’s system messageMarkdown
Continue.continue/rules/*.md, .continue/config.jsonProject root + global at ~/.continue/Rule files referenced from config; AGENTS.md works as a rule sourceMarkdown
Gooserecipe.yaml (per-recipe), project conventions in markdown, AGENTS.mdPer-recipe + project rootRecipe-scoped; project conventions discovered at session startYAML + markdown
OpenCodeopencode.json (config + instructions array), referenced markdown, AGENTS.mdProject root + global at ~/.config/opencode/instructions field can name AGENTS.md directlyJSON config; markdown content

What nexus-agents ships today

FileRoleStatus
AGENTS.mdCanonical surface; harness-neutralSource of truth
CLAUDE.mdClaude Code-specific entry point with plugin/skill integration detailsKept; cross-references AGENTS.md and adds Claude-Code-only sections
skills/index.yaml + skills/*/SKILL.mdAnthropic Agent Skills spec (#1828)Discovered by harnesses that support skills; documented from AGENTS.md
.rules/*.mdPer-rule files auto-loaded by Claude Code; referenced from AGENTS.mdKept; AGENTS.md indexes them
docs/ENTRYPOINTS.mdCLI + MCP tool referenceReferenced from AGENTS.md

What’s missing today (Phase 2 of #2805 closes this)

These harness files don’t exist yet in the repo. Phase 2 adds them as one-line redirects:

FileHarnessContent shape
.cursor/rules/agents.mdcCursorMDC frontmatter alwaysApply: true, body redirects to AGENTS.md
.windsurf/rules/agents.mdWindsurfMarkdown; one-line redirect
.aider.conf.ymlAiderread: [AGENTS.md, CLAUDE.md]
.continue/rules/agents.mdContinueMarkdown redirect
.clinerules/agents.mdClineMarkdown redirect

opencode.json and Goose recipe.yaml are project-config files with broader concerns than just instruction surfacing — those stay out of scope unless we ship an OpenCode/Goose adapter directly.

Federation invariants

When Phase 2 lands, these become invariants of the repo:

  1. AGENTS.md is the only place content is authored. Shim files MUST point at AGENTS.md, not duplicate content.
  2. nexus-agents doctor reports alignment. Project-level doctor walks the discovery files and reports whether each one resolves back to AGENTS.md. Phase 3 of #2805.
  3. Drift detection. Upstream changes to AGENTS.md community conventions or per-harness rule syntax get flagged via a periodic check (Phase 5).
  4. No content duplication ever. PRs that duplicate AGENTS.md content into a harness file are refactored to redirects before merge.

References

See also