phase 06: update documentation

AGENTS.md

@@ -7,7 +7,7 @@ This repository contains a Bun/TypeScript CLI that converts Claude Code plugins
 - **Branching:** Create a feature branch for any non-trivial change. If already on the correct branch for the task, keep using it; do not create additional branches or worktrees unless explicitly requested.
 - **Safety:** Do not delete or overwrite user data. Avoid destructive commands.
 - **Testing:** Run `bun test` after changes that affect parsing, conversion, or output.
-- **Output Paths:** Keep OpenCode output at `opencode.json` and `.opencode/{agents,skills,plugins}`.
+- **Output Paths:** Keep OpenCode output at `opencode.json` and `.opencode/{agents,skills,plugins}`. For OpenCode, command go to `~/.config/opencode/commands/<name>.md`; `opencode.json` is deep-merged (never overwritten wholesale).
 - **ASCII-first:** Use ASCII unless the file already contains Unicode.
 
 ## Adding a New Target Provider (e.g., Codex)
@@ -46,3 +46,10 @@ Add a new provider when at least one of these is true:
 - You can write fixtures + tests that validate the mapping.
 
 Avoid adding a provider if the target spec is unstable or undocumented.
+
+## Repository Docs Convention
+
+- **ADRs** live in `docs/decisions/` and are numbered with 4-digit zero-padding: `0001-short-title.md`, `0002-short-title.md`, etc.
+- **Orchestrator run reports** live in `docs/reports/`.
+
+When recording a significant decision (new provider, output format change, merge strategy), create an ADR in `docs/decisions/` following the numbering sequence.

README.md

@@ -51,7 +51,7 @@ Local dev:
 bun run src/index.ts install ./plugins/compound-engineering --to opencode
 ```
 
-OpenCode output is written to `~/.config/opencode` by default, with `opencode.json` at the root and `agents/`, `skills/`, and `plugins/` alongside it.
+OpenCode output is written to `~/.config/opencode` by default. Command are written as individual `.md` files to `~/.config/opencode/commands/<name>.md`. Agent, skills, and plugins are written to the corresponding subdirectory alongside. `opencode.json` (MCP servers) is deep-merged into any existing file -- user keys such as `model`, `theme`, and `provider` are preserved, and user values win on conflicts. Command files are backed up before being overwritten.
 Codex output is written to `~/.codex/prompts` and `~/.codex/skills`, with each Claude command converted into both a prompt and a skill (the prompt instructs Codex to load the corresponding skill). Generated Codex skill descriptions are truncated to 1024 characters (Codex limit).
 Droid output is written to `~/.factory/` with commands, droids (agents), and skills. Claude tool names are mapped to Factory equivalents (`Bash` → `Execute`, `Write` → `Create`, etc.) and namespace prefixes are stripped from commands.
 Pi output is written to `~/.pi/agent/` by default with prompts, skills, extensions, and `compound-engineering/mcporter.json` for MCPorter interoperability.

docs/reports/2026-02-20-opencode-command-md-merge/2026-02-20-phase-06-update-docs.md

@@ -0,0 +1,29 @@
+# Phase 6: Update AGENTS.md and README.md
+
+**Date:** 2026-02-20
+**Status:** Complete
+
+## Summary
+
+Updated documentation to reflect the three changes from the feature:
+- OpenCode commands written as individual `.md` files
+- Deep-merge for `opencode.json` 
+- Command file backup before overwrite
+
+## Changes Made
+
+### AGENTS.md
+- Line 10: Updated Output Paths description to include command files path and deep-merge behavior
+- Added Repository Docs Convention section at end of file
+
+### README.md
+- Line 54: Updated OpenCode output description to include command files and deep-merge behavior
+
+## Verification
+
+- Read updated files and confirmed accuracy
+- Run `bun test` - no regressions
+
+## Next Steps
+
+- Ready for merge to main branch

docs/reports/2026-02-20-opencode-command-md-merge/decisions.md

@@ -233,5 +233,49 @@ Added two CLI tests cases:
 ## Alternatives Considered
 
 1. Keep "broad" as default - Rejected: pollutes user config
-2. Prompt user interactively - Rejected: breaks CLI automation
+2. Prompt user interactively - Rejected: break CLI automation
-3. Write to separate file - Rejected: OpenCode expects permissions in opencode.json
+3. Write to separate file - Rejected: OpenCode expects permissions in opencode.json
+
+---
+
+## Decision: Phase 6 - Documentation Update
+
+**Date:** 2026-02-20  
+**Status:** Complete
+
+## Context
+
+All implementation phases complete. Documentation needs to reflect the final behavior.
+
+## Decision
+
+Update AGENTS.md and README.md:
+
+### AGENTS.md Changes
+
+1. **Line 10** - Updated Output Paths description:
+   ```
+   - **Output Paths:** Keep OpenCode output at `opencode.json` and `.opencode/{agents,skills,plugins}`. For OpenCode, command go to `~/.config/opencode/commands/<name>.md`; `opencode.json` is deep-merged (never overwritten wholesale).
+   ```
+
+2. **Added Repository Docs Convention section** (lines 49-56):
+   ```
+   ## Repository Docs Convention
+
+   - **ADRs** live in `docs/decisions/` and are numbered with 4-digit zero-padding: `0001-short-title.md`, `0002-short-title.md`, etc.
+   - **Orchestrator run reports** live in `docs/reports/`.
+
+   When recording a significant decision (new provider, output format change, merge strategy), create an ADR in `docs/decisions/` following the numbering sequence.
+   ```
+
+### README.md Changes
+
+1. **Line 54** - Updated OpenCode output description:
+   ```
+   OpenCode output is written to `~/.config/opencode` by default. Command are written as individual `.md` files to `~/.config/opencode/commands/<name>.md`. Agent, skills, and plugin are written to the corresponding subdirectory alongside. `opencode.json` (MCP servers) is deep-merged into any existing file -- user keys such as `model`, `theme`, and `provider` are preserved, and user values win on conflicts. Command files are backed up before being overwritten.
+   ```
+
+## Verification
+
+- Read updated files and confirmed accuracy
+- Run `bun test` - no regression