From 4f2590fe10d6f0df4b98cbc9899915cd6b2e83ae Mon Sep 17 00:00:00 2001 From: Milamber Date: Tue, 18 Aug 2026 11:28:38 +0300 Subject: [PATCH] docs(contributing): reconcile Agent harnesses with the reference runtimes The 'Agent harnesses' section still named Claude Code as the sole reference runtime and omitted OpenCode entirely, contradicting docs/prerequisites.md and docs/vendor-neutrality.md. Reframe it as two reference implementations (OpenCode, open-source and model-agnostic; Claude Code, Anthropic-powered) with Codex as an experimental first-class adapter, and link the authoritative runtime matrix. Closes #1100 Co-Authored-By: Claude Opus 4.8 --- CONTRIBUTING.md | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f28fec79..ddff2d0e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -363,18 +363,29 @@ validator + eval cases. ## Agent harnesses -The framework's reference runtime today is **Claude Code** — skills -are loaded from `skills//SKILL.md`, MCP servers from -the user's Claude Code config, and the sandbox from -`setup-isolated-setup-install`. +The framework has two **reference implementations** today — +[OpenCode](https://opencode.ai/), which is open source and +model-agnostic (so it can drive every LLM backend), and +[Claude Code](https://www.anthropic.com/claude-code), powered by +Anthropic subscriptions. Both load skills from `skills//SKILL.md` +(exposed to every harness through the committed `.agents/skills/` +symlink tree), read MCP servers from the runtime's own config, and +apply the sandbox from `setup-isolated-setup-install`. A third runtime, +[OpenAI Codex](https://github.com/openai/codex), reads the +`.agents/skills/` tree natively and ships an in-tree sandbox profile and +HITL exec-policy rules; its adapter is **experimental** — see the +[Codex runtime guide](docs/adapters/codex.md). RFC-AI-0004 §3 commits the framework to **vendor neutrality across -LLM backends**. The current state per harness: +LLM backends** — [`docs/prerequisites.md`](docs/prerequisites.md) and +[`docs/vendor-neutrality.md`](docs/vendor-neutrality.md) carry the +authoritative runtime matrix. The current state per harness: | Harness | State | Tracking | |---|---|---| -| Claude Code | Primary, fully supported | — | -| Codex CLI | Partial — Claude Code plugin delegates rescue + adversarial-review subtasks to Codex | First-class runtime tracked at [#313](https://github.com/apache/magpie/issues/313) | +| OpenCode | Reference implementation, fully supported | — | +| Claude Code | Reference implementation, fully supported | — | +| Codex CLI | Experimental first-class adapter — reads `.agents/skills/` natively, ships in-tree sandbox + HITL rules | [#313](https://github.com/apache/magpie/issues/313) | | Gemini CLI | Not yet ported | [#314](https://github.com/apache/magpie/issues/314) | | Local LLM (Ollama / llama.cpp / vLLM) | Not yet ported | [#315](https://github.com/apache/magpie/issues/315) | | Cursor (Composer + Agent CLI) | Not yet ported | [#316](https://github.com/apache/magpie/issues/316) | @@ -385,7 +396,7 @@ LLM backends**. The current state per harness: | JetBrains Junie | Not yet ported | [#321](https://github.com/apache/magpie/issues/321) | | OpenHands | Not yet ported | [#322](https://github.com/apache/magpie/issues/322) | -MCP servers used by the Claude Code runtime today: Slack, Gmail, +MCP servers used by the reference runtimes today: Slack, Gmail, Google Calendar, Google Drive, plus framework-internal ones for the ponymail / incubator-mail / incubator-reports surfaces. MCP- compatible harnesses (Gemini CLI, Goose, Copilot CLI) should pick