/opencode-skill

name: opencode
description: >
  Delegate a coding task to OpenCode CLI and supervise the result via git diff.
  Trigger: /opencode <instruction>. Claude orchestrates, OpenCode codes.
  Also handles /opencodeon, /opencodeoff, /opencodestatus, /opencode-report,
  /opencode-model-pick, /opencode-model-clear.
license: MIT
user-invocable: true
allowed-tools:
  - Bash
  - Read
  - Grep

/opencodeon | /opencodeoff | /opencodestatus

Toggle auto-delegate mode — OpenCode automatically handles coding tasks without requiring `/opencode` each time.

| Command | Action | |---------|--------| | `/opencodeon` | `touch ~/.local/share/opencode-auto.flag` → confirm "Auto-opencode ON" | | `/opencodeoff` | `rm -f ~/.local/share/opencode-auto.flag` → confirm "Auto-opencode OFF" | | `/opencodestatus` | run `test -f ~/.local/share/opencode-auto.flag && echo ON \|\| echo OFF` |

Run the bash command, print one confirmation line, and stop.

---

/opencode-report

If the user invokes /opencode-report, run ~/tools/delegate-report with any flags extracted from the arguments, display output verbatim, and stop.

| User says | Flag | |-----------|------| | last 7 days, 7d | --since 7 | | last 30 days, 30d | --since 30 | | project foo | --project foo | | only failures, fails | --fails | | (nothing) | (no flags, full report) |

---

/opencode-model-pick | /opencode-model-clear

Override the model for all subsequent delegations without editing the script.

| Command | Action | |---------|--------| | /opencode-model-pick model | echo model > ~/.local/share/opencode-model.flag, confirm | | /opencode-model-clear | rm -f ~/.local/share/opencode-model.flag, confirm back to default |

Run the bash command, print one confirmation line, and stop.

---

OpenCode Orchestrator

When the user invokes `/opencode <instruction>`, Claude delegates the implementation to OpenCode CLI via its headless `run` mode (`opencode run <prompt> --format json`), monitors in real time, and reports.

---

Known Limits

Hard constraints — not config options.

1. No `--max-turns` flag

**Timeout is the only runaway-control lever.** Set timeouts conservatively and decompose tasks.

2. `--dangerously-skip-permissions`

Passed automatically by the delegate script — all tool calls auto-approved. Review the git diff afterwards.

3. `--dir` flag

Passed automatically by the delegate script. Sets the working directory for OpenCode.

4. No pseudo-TTY needed

Plain pipe — no `script -q -c` wrapper required.

5. Free model queue delays

`opencode/deepseek-v4-flash-free` — no API key cost; may queue during peak usage.

6. Orchestration chain — 5 failure points

| Link | Failure mode | Symptom | |------|-------------|---------| | OpenCode CLI | Auth expired, quota hit, network | Immediate exit or silent hang | | Stream parser | OpenCode changes JSON event schema | Tool calls not detected | | Token aggregation | step_finish missing or malformed | Tokens logged as 0 | | git diff | Not a git repo, or OpenCode committed mid-run | Wrong file count | | JSON log | `~/.local/share/` not writable | Silent log skip |

When a run produces unexpected results, check these links top to bottom.

---

Step 1 — Detect workdir

1. `git rev-parse --show-toplevel` in the current directory. 2. If ambiguous or no git repo → ask with `AskUserQuestion`.

---

Step 2 — Decompose the task

**Critical rule**: keep tasks **atomic and focused** — one objective, one prompt.

| Signal | Action | |--------|--------| | 1 file, ≤ ~10 lines to change, location already known | **Do it directly** — don't delegate | | 1 file, logic non-trivial OR location unclear | Delegate | | 2–3 files, single objective | Delegate | | >3 files OR multi-step logic OR migrations | Delegate, broken into sub-tasks |

| Size | Definition | Timeout | Approach | |------|-----------|---------|----------| | **Trivial** | 1 file, change is obvious and located | — | **Skip delegation — edit directly** | | **Simple** | 1 file, non-trivial logic or unknown location | 180s | 1 opencode call | | **Medium** | 2–3 related files, 1 goal | 300s | 1 opencode call with structured prompt | | **Complex** | >3 files OR multi-step logic | — | **Decompose** |

**Decomposition for complex tasks:**

Sub-task 1: Explore relevant files (180s)
Sub-task 2: Implement change A in file X (300s)
Sub-task 3: Implement change B in file Y (300s)
Sub-task 4: Verify / test (180s)

→ Check git diff between sub-tasks before launching the next.

---

Step 3 — Write the OpenCode prompt

The prompt must be **self-contained**.

**Structure:**

Stack: Python/Flask, SQLAlchemy, SQLite
Key files: app.py (routes + fetch), models.py (Entry)

TASK: [one single thing to do, stated as an imperative]

CONSTRAINTS:
- [what must not break]
- [expected format if relevant]

VERIFY: grep for "def function_name" in file.py and confirm it exists.

**Formulation rules:**

• One task per prompt — never "also do X and Y"
• Name the exact files to modify
• Include a grep-based verification criterion (not a file re-read)
• Language: English (best model performance)

**Prompt adaptations:**

• **Any task that defines or calls a specific function**: include the exact signature — `def validate(data: dict) -> tuple[bool, list[str]]:`.
• **No fixed signature, but conventions matter**: point at the file to read first ("read app.py, follow its route/jsonify style") instead — don't do both, they're substitutes.

**Verification — always use grep, not file re-read:**

VERIFY: grep for "def extract_labels" in app.py and confirm it exists.

**Examples:**

❌ Bad (too vague, too wide):

Fix the API, add a signal classifier, update the UI with colored badges

✅ Good (atomic, verifiable):

Stack: Python/Flask. Files: app.py, templates/index.html

TASK: In fetch_data(), convert the date string (format "YYYY-MM-DD")
to datetime.date before returning.

CONSTRAINTS:
- Keep the existing route structure
- Use the same import sty