From eef96843a997408d29d6933545b667fd6a56b61a Mon Sep 17 00:00:00 2001 From: Dai Ha Date: Wed, 12 Aug 2026 20:59:59 +0200 Subject: [PATCH] 11: add 'Port a workspace to OpenCode' MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Records the port-to-opencode skill: what it does, that it is primary-side only, why a porting tool is the wrong reach (OpenCode reads CLAUDE.md natively; the Codex translation corrupted a never-commit rule), and the two gotchas — a stale AGENTS.md shadows CLAUDE.md, and skills do not cross. --- 11-Features.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/11-Features.md b/11-Features.md index 73a4ea9..031c5c9 100644 --- a/11-Features.md +++ b/11-Features.md @@ -30,6 +30,7 @@ six weeks, and the table alone will not carry it. | [Durable reply inbox](#durable-reply-inbox) | `broker:` | CB-307 | `msg/AmqpReplyInbox` | | [Pin an opencode endpoint](#pin-an-opencode-endpoint) | profile `baseUrl:` | CB-508 | `worker/OpenCodeLauncher` | | [Onboard a project with the plugin](#onboard-a-project-with-the-plugin) | `/plugin install claude-bridge` → `/claude-bridge:setup` | CB-527 | `plugin/` | +| [Port a workspace to OpenCode](#port-a-workspace-to-opencode) | `port-to-opencode` skill + `opencode.json` | CB-529 | `.claude/skills/port-to-opencode` | Nearly every knob above lives in one file, on one profile: @@ -229,6 +230,31 @@ at the repo would collide with the very isolation CB-525 exists to enforce. --- +## Port a workspace to OpenCode + +**What.** A `port-to-opencode` skill that makes an OpenCode session a first-class participant in a +Claude Code workspace — same instructions, same MCP servers, same bridge mount — by writing a single +`opencode.json` and nothing else. + +**On.** Load the `port-to-opencode` skill in the primary. It is a primary-side skill, not a +delegation playbook: a worker mounts only the bridge MCP and cannot run it. + +**Why.** OpenCode reads `CLAUDE.md` natively — including `~/.claude/CLAUDE.md` — so the rules cross +for free and only MCP servers need mapping. That is worth writing down because the obvious move is +the wrong one: the Codex attempt translated `CLAUDE.md` into a second rules file with a third-party +tool, and the translation silently corrupted a "never commit" rule into one naming a path that +cannot be committed at all. The skill exists to stop anyone reaching for a porting tool again. +Secrets cross by `{env:VAR}` reference, which is what makes `opencode.json` committable — and it +must be, because a peer in a worktree receives tracked files only. + +**Gotcha.** An `AGENTS.md` left in the repo **shadows `CLAUDE.md`** — opencode takes the first match +walking up from the cwd, so a stale file from an earlier port silently wins over the live rules. +Delete it before anything else. And skills do not cross: `.claude/skills/**` is not read by opencode, +so a brief telling a peer to "load the *implementer* skill" is a no-op there — spell the procedure +out in the brief instead. + +--- + ## Backfill status This page was started after the fact, so it is **not yet complete**. Entries above are written from