sync-opencode

Codex compatibility note:

• Invoke $skill-name: load the registered .agents/skills/<name>/SKILL.md and execute it with Codex tools; no separate Skill tool or Claude mode switch is needed. Author .claude/**; mirrors are generated.
• Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
• Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Preserve protocol order unless the user approves a deviation. Workflows use $start-workflow: gates stay fixed; other steps may flex with logged reasons and evidence.

Quick Summary

Goal: Reconcile the project-root opencode.json with the framework's recommended opencode defaults, compile .claude/settings.json into a portable opencode plugin (.opencode/plugins/easy-claude-hooks.js), and verify both. This runner is the single and only entrypoint for the opencode surface pipeline.

PORTABILITY CONTRACT — .claude/ and .opencode/ are portable, self-running and self-testing. Copy them into ANY repository — a Python repo, a .NET repo, a repo with no package.json at all — and the sync / verify / test entrypoint still works, because it is a path INSIDE the bundle invoked with plain node. Never drive this framework through a host package.json script, and never document one: npm run … names a command that does not exist in most projects the bundle is copied into. The only external requirement is node >= 18 — no node_modules, no npm, no lockfile. The generated plugin imports only node: built-ins and spawns the canonical .claude/hooks/*.cjs scripts.

Discover the roster instead of memorizing it: node .claude/skills/sync-opencode/scripts/run-opencode-sync.mjs --list-stages

Summary:

• opencode has no shell-command hook system — hooks are JavaScript plugin callbacks. This skill compiles .claude/settings.json into a bridge plugin whose runtime drives the original Claude hooks from opencode's plugin events.
• Recommended opencode config is part of the framework. .opencode/opencode.recommended.json is the single source of truth for the framework's opencode defaults; the config stage deep-merges it into the project-root opencode.json (recommended keys win, project-only keys survive).
• Scope is hooks + recommended config + skill permissions + the sub-agent mirror. opencode already auto-discovers skills from .claude/skills and .agents/skills, so there is no skill mirroring here (unlike $sync-codex). opencode ignores disable-model-invocation, so the skills stage enforces the selection policy through permission.skill in the project-root opencode.json instead, and writes a .opencode/commands/<name>.md per hidden skill so its explicit /name keeps working — see Skill permissions. Sub-agents are NOT auto-discovered, so .claude/agents/*.md IS mirrored into .opencode/agent/*.md by the agents stage — that is what lets the workflow protocols dispatch the same specialists (architect, code-reviewer, security-auditor, …) on opencode.
• Keep .claude canonical: edit .claude/settings.json / .claude/hooks/** and re-run this pipeline; never hand-edit the generated .opencode/plugins/easy-claude-hooks.js.
• To change a default opencode setting, edit .opencode/opencode.recommended.json, then re-run this pipeline to propagate it into the root config of every project the .opencode/ folder is copied into.
• The legacy hand-written .opencode/plugins/notification.js is superseded by the generated bridge; the runner backs it up under tmp/opencode-legacy/ and removes it so notifications are not sent twice.