OpenCode Adapter (AGENTS.md)

kaddo adapters install opencode generates an AGENTS.md at the project root so OpenCode gets native instructions for working in a Kaddo repo — without you pasting the context pack, prompts or rules into the chat.

kaddo adapters install opencode            # write AGENTS.md
kaddo export opencode                      # alias
kaddo adapters install opencode --dry-run  # preview, writes nothing
kaddo adapters install opencode --inject   # add/update only the Kaddo block, preserve the rest
kaddo adapters install opencode --force    # overwrite an existing AGENTS.md

Kaddo stays the source of truth. AGENTS.md is a generated projection — regenerate it instead of editing it by hand. It references knowledge/agents/skills; it never inlines full file contents.

OpenCode reads repository-level agent instructions from AGENTS.md — the same file the Codex adapter targets. This adapter follows the same Adapter Contract and reuses the same common core (project metadata, knowledge/derived paths, agents, skills, package-manager detection, command fallback, safe merge, inject guard, neutral markers); only the target label differs.

What the generated AGENTS.md contains

• A short explanation that the repo uses Kaddo for Knowledge Driven Development (+ project name).
• The knowledge map (knowledge/business|product|tech|delivery|agents|skills/) and the derived .kaddo/ paths, marked as generated output (don’t edit by hand).
• Operating rules and the workflow before roadmap (open-questions readiness — resolve, assume or defer blocking questions first), before implementation (read the active Work Item; stay in scope), and after implementation (suggest kaddo guard / impact / savings / drift).
• A command fallback tailored to the detected package manager (pnpm/npm/yarn/bun).
• Compact lists of installed agents and skills (names + role hints only), and an MCP section when a Kaddo MCP config is detected.
• A behavior checklist and safety limits.

It never inlines context-pack.md, business/product/codebase bodies, full Work Items, or full agent/skill contents.

Safe merge (--inject)

If your repo already has an AGENTS.md with the team’s own instructions, --inject integrates the Kaddo guidance without replacing the file — it writes a single delimited block (<!-- BEGIN KADDO ADAPTER --> … <!-- END KADDO ADAPTER -->) and preserves everything else. Running it again updates that block in place instead of duplicating it; half-open markers error with no change. This is the same safe-merge behavior as the Codex adapter.

Use --force when the file is fully generated by Kaddo, and --inject when it is team-owned. Running --inject on a file that is already fully generated by Kaddo does nothing and points you to --force, to avoid a duplicated copy of the guidance.

Behavior

Situation	Result
No AGENTS.md	created
AGENTS.md exists, no flag	skipped (suggests --inject / --force / --dry-run)
--inject	adds or updates only the Kaddo block, preserving the rest
--inject on a fully Kaddo-generated file	nothing changed (suggests --force)
--inject with invalid markers	errors, file untouched
--dry-run	prints the content, writes nothing
--force	overwrites the existing file

Deterministic: no LLM, no git, no application code. It never modifies knowledge/ or .kaddo/, and only writes AGENTS.md at the project root. Works for new, pre-ai and legacy projects that already have a Kaddo structure.

Smoke tests

After kaddo adapters install opencode --force, validate OpenCode is actually using AGENTS.md:

1. Read without modifying — “Read AGENTS.md and tell me the correct Kaddo workflow to implement the next pending Work Item. Do not modify files.” → mentions reading the Work Item and Kaddo context, checking readiness gates, implementing only the scope, validating, suggesting kaddo guard, and asking before committing.
2. Readiness before roadmap — “Generate the roadmap for this project.” → checks open-questions readiness first and, if blocking questions exist, asks to resolve/assume/defer them.
3. Implementation — “Implement the next pending Work Item. Do not commit without confirmation.” → reads context, changes only in-scope files, validates, suggests kaddo guard, doesn’t commit without confirmation.
4. Don’t edit .kaddo/ — “Update .kaddo/context-pack.md manually.” → refuses and suggests regenerating with kaddo context.

Out of scope

This version generates only the root AGENTS.md. It does not generate native OpenCode commands (potential future VS-067.1 — OpenCode Commands Projection) or native OpenCode agents (potential future VS-067.2 — OpenCode Agents Projection). Kaddo agents stay under knowledge/agents/ and skills under knowledge/skills/; the projection just points OpenCode to read the relevant ones.