phase 01: type change for command files

docs/reports/2026-02-20-opencode-command-md-merge/2026-02-20-phase-01-type-changes.md

@@ -0,0 +1,48 @@
+# Phase 1 Handoff Report: Type Changes for Command Files
+
+**Date:** 2026-02-20  
+**Phase:** 1 of 4  
+**Status:** Complete
+
+## Summary
+
+Implemented type changes to support storing commands as `.md` files instead of inline in `opencode.json`.
+
+## Changes Made
+
+### 1. Type Changes (`src/types/opencode.ts`)
+
+- Removed `OpenCodeCommandConfig` type (lines 23-28)
+- Removed `command?: Record<string, OpenCodeCommandConfig>` from `OpenCodeConfig`
+- Added `OpenCodeCommandFile` type:
+  ```typescript
+  export type OpenCodeCommandFile = {
+    name: string
+    content: string
+  }
+  ```
+- Added `commandFiles: OpenCodeCommandFile[]` to `OpenCodeBundle` (with comment referencing ADR-001)
+
+### 2. Import Update (`src/converters/claude-to-opencode.ts`)
+
+- Removed `OpenCodeCommandConfig` from imports
+- Added `OpenCodeCommandFile` to import
+
+### 3. Test Updates
+
+- `tests/converter.test.ts`: Updated 4 tests to use `bundle.commandFiles.find()` instead of `bundle.config.command`
+- `tests/opencode-writer.test.ts`: Added `commandFiles: []` to all 4 bundle literals definitions
+
+## Test Status
+
+4 tests fail in `converter.test.ts` because the converter hasn't been updated yet to populate `commandFiles`. This is expected behavior - Phase 2 will fix these.
+
+```
+76 pass, 4 fail in converter.test.ts
+```
+
+## Next Steps (Phase 2)
+
+- Update converter to populate `commandFiles` instead of `config.command`
+- Update writer to output `.md` files for commands
+- Tests will pass after Phase 2 implementation

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

@@ -0,0 +1,44 @@
+# Decision Log: OpenCode Commands as .md Files
+
+## Decision: ADR-001 - Store Commands as Individual .md Files
+
+**Date:** 2026-02-20  
+**Status:** Adopted
+
+## Context
+
+The original design stored commands configurations inline in `opencode.json` under `config.command`. This tightly couples command metadata with config, making it harder to version-control commands separately and share command files.
+
+## Decision
+
+Store commands definitions as individual `.md` files in `.opencode/commands/` directory, with YAML frontmatter for metadata and markdown body for the command prompt.
+
+**New Type:**
+```typescript
+export type OpenCodeCommandFile = {
+  name: string    // command name, used as filename stem: <name>.md
+  content: string // full file content: YAML frontmatter + body
+}
+```
+
+**Bundle Structure:**
+```typescript
+export type OpenCodeBundle = {
+  config: OpenCodeConfig
+  agents: OpenCodeAgentFile[]
+  commandFiles: OpenCodeCommandFile[]  // NEW
+  plugins: OpenCodePluginFile[]
+  skillDirs: { sourceDir: string; name: string }[]
+}
+```
+
+## Consequences
+
+- **Positive:** Commands can be versioned, shared, and edited independently
+- **Negative:** Requires updating converter, writer, and all consumers
+- **Migration:** Phase 1-4 will implement the full migration
+
+## Alternatives Considered
+
+1. Keep inline in config - Rejected: limits flexibility
+2. Use separate JSON files - Rejected: YAML frontmatter is more idiomatic for commands