diff --git a/AGENTS.md b/AGENTS.md index 471b900..cbc86f2 100644 --- a/AGENTS.md +++ b/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/.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. diff --git a/README.md b/README.md index 27e4ae7..5885038 100644 --- a/README.md +++ b/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/.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. diff --git a/docs/reports/2026-02-20-opencode-command-md-merge/2026-02-20-phase-06-update-docs.md b/docs/reports/2026-02-20-opencode-command-md-merge/2026-02-20-phase-06-update-docs.md new file mode 100644 index 0000000..eafdca0 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/reports/2026-02-20-opencode-command-md-merge/decisions.md b/docs/reports/2026-02-20-opencode-command-md-merge/decisions.md index 3e7bd28..e3d398f 100644 --- a/docs/reports/2026-02-20-opencode-command-md-merge/decisions.md +++ b/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 -3. Write to separate file - Rejected: OpenCode expects permissions in opencode.json \ No newline at end of file +2. Prompt user interactively - Rejected: break CLI automation +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/.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/.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 \ No newline at end of file