phase 03: write command md files

docs/reports/2026-02-20-opencode-command-md-merge/2026-02-20-phase-03-write-command-files.md

@@ -0,0 +1,54 @@
+# Phase 3 Handoff Report: Write Command Files as .md
+
+## Date
+2026-02-20
+
+## Phase
+3 of feature: OpenCode Commands as .md Files, Config Merge, and Permissions Default Fix
+
+## Summary
+
+Implemented the `commandsDir` path resolution and command file writing in `src/targets/opencode.ts`.
+
+## Changes Made
+
+### 1. Updated `src/targets/opencode.ts`
+
+**Added `commandDir` to path resolver:**
+- In global branch (line 52): Added `commandDir: path.join(outputRoot, "commands")` with inline comment
+- In custom branch (line 66): Added `commandDir: path.join(outputRoot, ".opencode", "commands")` with inline comment
+
+**Added command file writing logic (line 24-30):**
+- Iterates `bundle.commandFiles`
+- Writes each command as `<commandsDir>/<name>.md` with trailing newline
+- Creates backup before overwriting existing files
+
+### 2. Added tests in `tests/opencode-writer.test.ts`
+
+- `"writes command files as .md in commands/ directory"` - Tests global-style output (`.config/opencode`)
+- `"backs up existing command .md file before overwriting"` - Tests backup creation
+
+## Test Results
+
+```
+bun test tests/opencode-writer.test.ts
+6 pass, 0 fail
+```
+
+All existing tests continue to pass:
+```
+bun test
+183 pass, 0 fail
+```
+
+## Deliverables Complete
+
+- [x] Updated `src/targets/opencode.ts` with commandDir path and write logic
+- [x] New tests in `tests/opencode-writer.test.ts`
+- [x] All tests pass
+
+## Notes
+
+- Used `openCodePaths` instead of `paths` variable name to avoid shadowing the imported `path` module
+- Command files are written with trailing newline (`content + "\n"`)
+- Backup uses timestamp format `.bak.2026-02-20T...`

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

@@ -80,4 +80,50 @@ Template text here...
 
 - Converter now produces command files ready for file-system output
 - Writer phase will handle writing to `.opencode/commands/` directory
-- Phase 1 type changes are now fully utilizeds
+- Phase 1 type changes are now fully utilizeds
+
+---
+
+## Decision: Phase 3 - Writer Writes Command .md Files
+
+**Date:** 2026-02-20  
+**Status:** Implemented
+
+## Context
+
+The writer needs to write command files from the bundle to the file system.
+
+## Decision
+
+In `src/targets/opencode.ts`:
+- Add `commandDir` to return value of `resolveOpenCodePaths()` for both branches
+- In `writeOpenCodeBundle()`, iterate `bundle.commandFiles` and write each as `<commandsDir>/<name>.md` with backup-before-overwrite
+
+### Path Resolution
+
+- Global branch (basename is "opencode" or ".opencode"): `commandsDir: path.join(outputRoot, "commands")`
+- Custom branch: `commandDir: path.join(outputRoot, ".opencode", "commands")`
+
+### Writing Logic
+
+```typescript
+for (const commandFile of bundle.commandFiles) {
+  const dest = path.join(openCodePaths.commandDir, `${commandFile.name}.md`)
+  const cmdBackupPath = await backupFile(dest)
+  if (cmdBackupPath) {
+    console.log(`Backed up existing command file to ${cmdBackupPath}`)
+  }
+  await writeText(dest, commandFile.content + "\n")
+}
+```
+
+## Consequences
+
+- Command files are written to `.opencode/commands/` or `commands/` directory
+- Existing files are backed up before overwriting
+- Files content includes trailing newline
+
+## Alternatives Considered
+
+1. Use intermediate variable for commandDir - Rejected: caused intermittent undefined errors
+2. Use direct property reference `openCodePaths.commandDir` - Chosen: more reliable