OpenCode V2: install skips an existing opencode.json, so no agents and no skills path are ever wired #3559

Summary

On a machine that already has ~/.config/opencode/opencode.json, an OpenCode install copies the whole catalog but never writes ECC's config, so the pieces that depend on config are silently missing. Two separate consequences:

1. No agents are installed. The opencode target declares its 26 subagents inside .opencode/opencode.json under the agent map (each with prompt: "{file:prompts/agents/<name>.txt}"). It does not ship agents/*.md files. Because that config file is skipped, ~/.config/opencode/ ends up with no planner, tdd-guide, code-reviewer, security-reviewer, ... — while commands/*.md reference exactly those agents in frontmatter (commands/plan.md → agent: planner, commands/tdd.md → agent: tdd-guide). 14 of the installed commands delegate to an agent that does not exist.

2. skills.paths is never applied. The template sets "skills": { "paths": ["../skills"] }, which is CWD-relative. It resolves against the user's project directory (e.g. D:/School/skills), not the installed config root. (Same finding as the note in PR fix: port OpenCode plugin from v1 to v2 plugin API #3536; reported here because it is a consequence of the skip for existing-config users.)

Separately: on OpenCode V2 the top-level instructions field is accepted but its entries are not loaded (V2 docs: "OpenCode accepts this field but does not load its entries; use AGENTS.md for instructions"). ECC relies on instructions for its curated instruction set, so none of it takes effect on V2 regardless of whether the config file is written.

Why the config is never written

scripts/lib/install/ownership-guard.js:77-89: a copy-file operation is skipped with a warning when the destination already exists and is not recorded as ECC-managed in the previous install-state — correct behavior for user-owned files, but it also means the ECC config template is never applied to anyone who already has an opencode.json:

Skipped user-owned file ~/.config/opencode/opencode.json: the existing file is not recorded in ECC install-state.

So the install reports success, writes ~1100 files, and leaves the active config completely unwired.

Repro

Windows 11, native. OpenCode v2.0.26. ECC 2.2.3.

git clone https://github.com/affaan-m/ECC
cd ECC
npm install
npm run build:opencode
node scripts/install-apply.js --target opencode --profile full --no-hooks

(with an existing ~/.config/opencode/opencode.json present)

Observed

• Install completes: Operations: 835 planned, Skipped operations: 3 (package.json, package-lock.json, opencode.json).
• ~/.config/opencode/agents/ contains no ECC agents.
• commands/plan.md frontmatter: agent: planner — that agent does not exist.
• ~/.config/opencode/opencode.json has no ECC keys (no plugin/plugins, no agent/agents, no skills, no command/commands).
• ~/.config/opencode/instructions/INSTRUCTIONS.md is written to disk but nothing loads it on V2.

Impact

Users with an existing OpenCode config get a partial install that looks complete: commands appear (they are discovered from the commands/ directory) but every command that delegates to an ECC agent cannot resolve it, and the curated instructions never load. This is close to "installed but does nothing useful", which is likely a strong uninstall trigger.

Suggested fixes

• Do not skip the config outright. Merge only ECC-owned keys into an existing opencode.json (preserving user keys) and record them as managed, so repair/uninstall can reverse them. deepMergeJson already exists in scripts/lib/install/json-ops.js.
• Ship the 26 opencode agents as file-based definitions (agents/<name>.md with description + mode: subagent) instead of agent entries in config. Then agents do not depend on the config file at all, and they are discovered by directory.
• Replace the instructions array with an AGENTS.md for V2 (global ~/.config/opencode/AGENTS.md), since V2 does not load instructions.
• Make skills.paths absolute to the installed config root, or drop it and rely on V2's automatic discovery of the config directory's skills/.

Relations

• OpenCode V2 fails to load ECC plugin (V1 format: needs id + setup) #3537 / PR fix: port OpenCode plugin from v1 to v2 plugin API #3536 cover the V2 plugin API break. This issue is independent: it affects the already-ported plugin too, and persists after the plugin loads.
• [Problem] Opencode there is simple step by step guide? V2 seems currently its for V1 #3229 asks for a V2 guide; this is the concrete install-level gap behind that request.

Environment

• ECC 2.2.3
• OpenCode v2.0.26
• Windows 11, native (no WSL)