opencode-skills-collection 4.0.45 → 4.0.46

package/bundled-skills/omp-delegate/references/dispatch-and-poll.md

@@ -0,0 +1,155 @@
+# Dispatch and poll
+
+`scripts/relay.mjs` wraps omp's non-interactive JSON print mode, captures its event stream, and
+writes a `result.json`. Run one command, then read one file.
+
+## Before the first run
+
+```bash
+command -v omp
+omp --version
+omp models            # list models this install can run; then pass one id as --model
+# omp models --json   # machine-readable catalog
+# omp models find sonnet
+```
+
+Do **not** run `omp --list-models`. That flag is a hard error.
+
+Install with `bun install -g @oh-my-pi/pi-coding-agent`. Authenticate with `/login` inside omp
+(subscription providers) or an API-key environment variable; omp stores credentials in `~/.omp/`.
+
+## Dispatching
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
+```
+
+`<skill-dir>` is the installed folder containing this skill's `SKILL.md`.
+
+| Flag | Effect |
+| --- | --- |
+| `--brief <file>` | Brief path. Omit it to read the brief from stdin. |
+| `--cd <dir>` | Working root and child process cwd (default: current directory). |
+| `--lane <name>` | Fleet lane from `delegate-setup` config. Applies that lane's dials; fails if the lane's `implementer` is not this relay. Explicit dial flags win. A lane `effort` value becomes `--thinking`. |
+| `--provider <name>` | omp `--provider` (default: omp's own default). Token-validated. |
+| `--model <pattern>` | omp `--model` id or fuzzy pattern (default: omp's own default). Token-validated: letters, digits, `. _ : / -`. Pick the value from `omp models`, not from memory. |
+| `--thinking <level>` | omp `--thinking`: `off`, `auto`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. |
+| `--session <id>` | Resume a specific omp session (`--session` / `--resume`); send only the delta brief. A value is required — bare `--resume` would open omp's picker and hang. |
+| `--resume-last` | Continue the most recent omp session for this cwd (`omp --continue`); send only the delta brief. |
+| `--read-only` | Restrict omp to `--tools read,grep,glob`. |
+| `--approve` | Load project-local `.omp` extensions, skills, and rules. The default passes `--no-extensions --no-skills --no-rules`. |
+| `--timeout <dur>` | Relay watchdog (default: `30m`; h/m/s strings). The relay does not forward omp's `--max-time`. |
+| `--out-dir <dir>` | Artifact directory (default: a fresh directory under the system temp dir). |
+| `-h`, `--help` | Print the relay's header help. |
+
+`--session` and `--resume-last` are mutually exclusive. The child cwd pins the workspace; omp's
+`--cwd` is not passed. omp has no sandbox, so reachability is simply the filesystem.
+
+A run without `--read-only` can write and execute anything the user account can: the relay passes
+`--yolo` so print mode does not stall on tool approval. `--read-only` removes write/edit/bash (and
+the rest of omp's default tool surface) from the callable tools; installed extension code still
+runs with the user's host permissions when `--approve` is set.
+
+The relay never forwards `--api-key`.
+
+## Artifacts and result fields
+
+Artifacts live outside the repo by default, so they do not appear in `touchedFiles`; an
+`--out-dir` inside the worktree can make the artifacts appear there:
+
+- `brief.txt` - the exact brief.
+- `events.jsonl` - raw omp stdout events (the session header, then every agent event).
+- `final.txt` - assistant text joined with a blank line between chunks; absent if none was emitted.
+- `stderr.txt` - complete stderr.
+- `result.json` - the stable `delegate-relay.result.v1` contract.
+
+`result.json` fields:
+
+- `schema`, `tool` (`"omp"`), `status` (`completed` | `failed` | `timeout` | `aborted` | `omp_unavailable`), `exitCode`, and
+  `signal` (`null` unless the child died on a signal).
+- `workdir`, requested `provider`/`model`/`thinking`, `projectTrusted`, `readOnly`, `yolo`, `resumed`, `ompVersion`,
+  `sessionId`, `startedAt`, and `finishedAt`.
+- `actualProvider`, `actualModel`, `usage`, and `stopReason` from omp's final assistant event.
+- `briefPath`, `finalPath`, `eventsPath`, and `stderrPath`.
+- `sessionId` - parsed from the JSON stream's `session` header. Resume with `--session <id>`.
+  Note: `--continue` may mint a new session id for the continued run; the result always reports
+  the id of the run that just happened.
+- `finalMessage` - assistant text parts joined with `"\n\n"`; tool calls and tool results are
+  excluded.
+- `touchedFiles` - `git status --porcelain` lines for the **final working tree under `--cd` only**,
+  not an attribution of omp's edits: anything already dirty before dispatch shows up too. Dispatch
+  from a clean tree when you want the list to read as "what omp changed". `null` means git could
+  not report; `[]` means git ran and the tree is clean.
+- `stderrTail` - the last 20 non-empty stderr lines on any run that did not complete (`failed`,
+  `timeout`, `aborted`), except a launch failure, which reports `failed` with no `stderrTail`.
+- `error` - present for launch failures, preflight failures, when the relay watchdog fires
+  (`timeout`), and on an `aborted` run.
+
+omp's stream carries thinking and message-update events the relay archives but does not parse.
+
+## Waiting for completion
+
+The relay blocks. Use the orchestrator's background-command facility, or background it in a
+shell and poll for `result.json`. The run is done only when the process exits and the file
+contains a `status`. The result file is written atomically, so a partial read is impossible.
+
+A pre-run usage error exits 2 and writes no result. A missing `omp` exits 127 and writes
+`status: "omp_unavailable"`.
+
+## When a run misbehaves
+
+- **`status: "omp_unavailable"` (exit 127):** install omp (`bun install -g @oh-my-pi/pi-coding-agent`),
+  authenticate, and re-dispatch.
+- **`status: "failed"`:** read `stderrTail`, `stderrPath`, and the tail of `events.jsonl`. Common
+  causes: an unknown `--model`, an expired login, or a provider error.
+  A final assistant event with `stopReason: "error"` or `"aborted"` is failed even if omp exits zero.
+- **`status: "failed"` with an `error` mentioning `version preflight`:** the bounded `omp --version`
+  probe failed or hung, so omp was never dispatched. Check the install (`omp --version` yourself).
+- **`status: "aborted"`:** the relay itself was killed (its parent's timeout, a stopped task, a
+  closed terminal) and forwarded the kill to omp. The result is written before the relay exits;
+  inspect the working tree before re-dispatching. On native Windows a hard kill of the relay is
+  uncatchable (Node supports no `SIGTERM` handler there), so this status may never get written -
+  a relay process that is gone without a `result.json` is an aborted run; inspect the working
+  tree and `events.jsonl` directly.
+- **`status: "failed"` with `signal: "SIGKILL"`:** the host killed the process, commonly through
+  the OOM killer or a supervisor timeout. This is not an omp error; check host memory and
+  re-dispatch, or split the task into smaller briefs.
+- **`status: "timeout"`:** the `--timeout` watchdog killed the run; `error` reads
+  `omp did not finish within --timeout <dur>; killed by the relay watchdog`. Increase `--timeout`
+  or split the task. On POSIX the relay sends SIGTERM to the process group, waits 10 seconds,
+  then sends SIGKILL if needed; on Windows there is no escalation phase — the whole process tree
+  is felled immediately with `taskkill /pid <pid> /t /f`.
+- **Empty `finalMessage`:** inspect `touchedFiles` and the diff. Add a
+  `<structured_output_contract>` to the next brief to require a closing report.
+
+## Recovering lost work
+
+`events.jsonl` in the run directory records every event the implementer streamed. If finished
+work is lost — the run killed late, or the working tree damaged afterward — read the event log
+before re-dispatching: it identifies which files and tool commands were involved, which scopes
+what needs redoing. Tool execution events carry the write/edit arguments, but treat any
+reconstruction as unverified until it matches a working-tree diff — when the tree still holds the
+work, preserve the tree rather than replaying the log.
+
+## What the relay runs
+
+The launch is equivalent to:
+
+```bash
+cat brief.txt | omp --mode json [--provider <name>] [--model <pattern>] [--thinking <level>] \
+  [--session <id> | --continue] [--yolo] \
+  [--no-extensions --no-skills --no-rules] [--tools read,grep,glob]
+```
+
+`--yolo` is omitted on `--read-only`. The three `--no-*` flags are omitted when `--approve` is
+set.
+
+The brief rides stdin, so it is not visible in the host process list and no argv size cap
+applies. `omp` is a native binary (bun / install script / Homebrew), so the relay never launches
+it through a shell. Before dispatch the relay runs a bounded `omp --version` preflight (10s cap)
+so a hung or crashing CLI fails fast and explicitly instead of hanging the run.
+
+## The commit boundary
+
+The relay never commits. omp edits the working tree; the orchestrator reviews, re-runs the gates,
+and commits. See [review-and-land.md](review-and-land.md).

package/bundled-skills/omp-delegate/references/multi-task-queues.md

@@ -0,0 +1,59 @@
+# Multi-task queues
+
+The single-task loop scales to a queue: a removal across layers, a migration across files, or a
+refactor sweep. Sequencing and bookkeeping make it trustworthy.
+
+## Run sequentially, one commit per task
+
+Run tasks **one at a time, in dependency order**, landing each after review and gates before
+dispatching the next:
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief task-01.txt --cd /path/to/repo
+```
+
+- Later briefs can rely on earlier work only after it lands.
+- One commit per task keeps history reviewable and each step revertible.
+- A clean tree before each dispatch keeps `touchedFiles` honest.
+
+Use parallel runs only for genuinely independent tasks in separate working trees. Sequential is
+the default because it preserves clean task boundaries.
+
+## Carry decided constraints forward
+
+Fresh omp sessions do not remember earlier tasks. If task 2 chooses a helper name, fixture
+location, or interface that task 5 needs, write that fact into task 5's brief.
+
+Use a resumed omp session only for rework on the same task. Send a delta brief with
+`--resume-last`, or with `--session <id>` from that task's `result.json`. Start unrelated queue
+items in fresh sessions.
+
+## Keep a progress file
+
+For more than two or three tasks, maintain one progress file beside the work:
+
+- **Status table** - queued / at-implementer / reviewed+committed, with the commit hash.
+- **Per-task review notes** - what landed, what you verified, and gate outcomes.
+- **Needs your eyes** - design decisions, non-blocking nitpicks, and questions for the human.
+- **End-of-run checklist** - the final cross-task verification.
+
+Update it when each task lands, not in one batch at the end.
+
+## Close with a coherence check
+
+After the last task:
+
+- Run the full test/build once more.
+- Search repo-wide for the thing the queue changed.
+- Replay migrations from a clean state and check drift when applicable.
+- Push and open or update the PR only after the final tree is coherent.
+
+## When to stop and ask
+
+Proceed on work that follows from the agreed plan. Stop and surface when:
+
+- A task cannot be completed correctly within its brief.
+- Review calls the plan itself into question.
+- Gates reveal a problem affecting already-landed tasks.
+
+Report the landed state, commit hashes, and open question, then wait.

package/bundled-skills/omp-delegate/references/review-and-land.md

@@ -0,0 +1,95 @@
+# Review and land
+
+The implementer made the changes; you own the judgment. Verify against reality, never the self-report, and read
+the diff as generated code because a green gate cannot catch every failure mode.
+
+## Check tests before trusting gates
+
+If the diff touches existing tests, review those edits first:
+
+- Treat unbriefed test edits as a contract change, not part of the fix.
+- Treat newly skipped, disabled, or commented-out tests as failing until proven otherwise.
+- Treat loosened assertions the same way: contains/truthy replacing exact matches, broadened error
+  types, and widened tolerances all weaken the gate.
+
+## Re-run the gates yourself
+
+`result.json` carries omp's claims, not evidence. Re-run the project's actual test, lint, and build
+commands in the working tree and read their output. Passing is necessary, not sufficient.
+
+For changes with a specialized verification shape:
+
+- **Migrations or schema:** round-trip them and check for drift.
+- **Removals or renames:** grep for dangling references.
+- **Stateful behavior:** exercise the behavior, not just compilation.
+
+## Read the diff against the brief
+
+Start with `touchedFiles`, open the diff, and compare it to the brief:
+
+- **Scope creep** - changes the brief excluded.
+- **Scope shortfall** - missed behavior, edges, or cleanup.
+- **Quiet judgment calls** - defensible but unasked decisions that need review.
+
+## The implementer sweep
+
+Check every diff for patterns gates often miss:
+
+- Hardcoded success or fixture data on a real-work path.
+- Catch-all error handling that returns a default instead of propagating or recovering.
+- Imports, dependencies, methods, and signatures not present in the installed version.
+- Unused imports, uncalled helpers, unreachable branches, and scaffolding comments.
+- A second client, error idiom, or logging style beside the repo's existing one.
+- Tests that assert internals instead of behavior, or near-duplicate test bodies.
+- Optional parameters, config flags, and abstractions with no caller.
+- Guards for impossible cases that hide trust-boundary validation.
+
+Send anything blocking back to omp as a delta brief, or fix it in the tree, and report either
+choice to the human. Run relevant guard skills if installed.
+
+## The commit boundary
+
+When the gates pass and the diff holds, **the orchestrator commits**, never the implementer.
+Write a clear message describing what landed.
+
+From dispatch until that commit, the uncommitted working tree is the authoritative copy of the
+implementer's work — the only one you can commit from, and often the only copy at all. Never run
+`git checkout`, `reset`, `clean`, or a branch switch in the workspace between those two points —
+however messy an interrupted run looks, inspect it first: `git status`, `git diff`,
+`git diff --cached` for anything the implementer staged (plain `git diff` is blind to the index),
+and open any untracked files (`??` in `git status`) directly — they are the implementer's new
+files, and no diff shows their contents. The tree is evidence, not clutter. After that inspection
+the verdict can legitimately be to discard — work built on a premise you have since corrected,
+for example — and then `git checkout`/`clean` is the right tool. The ban is on reflexive cleanup
+before anyone has looked.
+
+## Rework: send the delta
+
+Continue the same session with only the correction:
+
+```bash
+echo "The fix is right, but the test mocks the DB session. Use the real migrated fixture and remove the
+unused import." | node "<skill-dir>/scripts/relay.mjs" --resume-last --cd /path/to/repo
+```
+
+Use `--session <id>` instead when resuming the specific id recorded in `result.json` - the stable
+handle, since `--continue` may mint a new id for each continued run. The relay rejects
+`--resume-last` plus `--session` before launch. Rework gets the same gate rerun, test review,
+diff review, and implementer sweep.
+
+A write-capable rework run passes `--yolo` and executes with no prompts - keep rework briefs as
+narrow as the original. A `--read-only` run restricts omp to `read,grep,glob`; installed extension
+code still runs with the user's host permissions when `--approve` is set, so inspect `touchedFiles`
+and the tree after every run.
+
+## Surface, do not absorb
+
+The human opted into delegation, so committing verified, gate-passing work is the contract. Keep
+them in the loop when the work changes shape:
+
+- Report design decisions and defensible-but-unrequested turns.
+- Note non-blocking nitpicks you did not block on.
+- Stop and ask if correct completion requires going beyond the brief.
+
+For a queue, keep these notes in the progress file described in
+[multi-task-queues.md](multi-task-queues.md).

package/bundled-skills/omp-delegate/references/writing-the-brief.md

@@ -0,0 +1,149 @@
+# Writing the brief
+
+A brief is the entire task as omp will see it. It runs in a separate session with **no memory of
+your conversation, no access to prior notes, and no shared context** - only the text you send and
+whatever it can inspect in the workspace. If a constraint is not in the brief or discoverable in
+the repo, it does not exist for omp.
+
+One shortcut: omp auto-loads `AGENTS.md` and `CLAUDE.md` context files from the workspace and its
+parent directories, so conventions written there reach omp without inlining. Restate the
+load-bearing rules in the brief anyway - the brief is the contract. Project `.omp` skills, rules,
+and extensions stay undiscovered unless the dispatch passed `--approve`.
+
+## Model choice and resumed sessions
+
+omp uses its configured default model when `--model` is omitted, so a fresh dispatch does not
+require it. Pass `--model <id>` only when the human asked for a specific model.
+
+**How to choose an id:**
+
+1. Run `omp models` (human table) or `omp models --json`. Narrow with `omp models find <substring>`
+   or `omp models <provider>`.
+2. Copy a catalog id (often `provider/model-id`, sometimes a unique substring omp can fuzzy-match).
+3. Pass it as the relay's `--model`. Add `--provider <name>` when two providers share a short name.
+
+Do **not** run `omp --list-models`. That flag was removed; omp exits 2 with `unknown flag:
+--list-models`. Do **not** pass `--api-key` through the relay.
+
+`--thinking` is independent of `--model`. Use `off`, `auto`, `minimal`, `low`, `medium`, `high`,
+`xhigh`, or `max`. The relay rejects any other value before dispatch.
+
+A resumed run keeps the session context. Send only the delta brief with `--resume-last` or
+`--session <id>`.
+
+## The shape that works
+
+Use a compact, block-structured brief. State the task, what done means, the few constraints that
+matter, and the report omp must return.
+
+```xml
+<task>
+One or two sentences: the concrete job and where it lives. Then the specifics - current state, what to
+change, and explicitly what to leave untouched. The leave-untouched list prevents unrelated refactors.
+</task>
+
+<verification_loop>
+Run these before finishing and fix anything they surface, do not just report it:
+  <the project's real test command>
+  <the project's real lint/format command>
+  <the project's real build/typecheck command>
+Confirm the working tree shows only the intended changes afterward.
+</verification_loop>
+
+<action_safety>
+Keep changes scoped to the task. No unrelated refactors, renames, or cleanup unless required for
+correctness. Do NOT run git add or git commit - the orchestrator commits after reviewing. Leave the
+work uncommitted in the working tree.
+</action_safety>
+
+<structured_output_contract>
+End with a report in this exact shape:
+  1. What changed and why
+  2. Files touched
+  3. Gate outcomes (include test/lint counts)
+  4. Anything you deviated on, left open, or want a decision on
+</structured_output_contract>
+```
+
+Add extra blocks only when the task needs them:
+
+- **Debugging or open-ended fixes** - add `<completeness_contract>` (resolve fully, not just the
+  first plausible cause) and `<missing_context_gating>` (find missing repo facts or state what is
+  unknown).
+- **Research or recommendations** - add `<research_mode>` (separate observed facts, inferences,
+  and open questions), and dispatch with `--read-only` so omp cannot invoke write/edit/bash tools.
+  That restricts the tool surface; it is not a sandbox. `AGENTS.md` and `CLAUDE.md` are also
+  repository-controlled instructions and may load without `--approve`. Use read-only dispatches
+  for untrusted repositories. Leave `--approve` off unless the user trusts this repo's `.omp`
+  extras (the relay already passes `--no-extensions --no-skills --no-rules` unless `--approve`
+  is set).
+
+## Always ask for the report explicitly
+
+The relay builds `finalMessage` from assistant text in omp's JSON event stream. Without a closing
+summary, the edits may exist but the result is hard to review. The `<structured_output_contract>`
+block makes the expected report explicit.
+
+## Discover the real gates
+
+Read the repo's `AGENTS.md`, `CLAUDE.md`, `Makefile`, `package.json`, or equivalent first and copy
+the actual commands into `<verification_loop>`. A brief that says only "run the tests" makes the
+implementer guess or skip them.
+
+## Honor repo conventions
+
+Restate the load-bearing house rules in the brief. omp can inspect the workspace (and auto-loads
+context files), but the important constraints should be directly in front of it.
+
+## One task per brief
+
+Keep each brief bounded. One brief -> one omp run -> one reviewed commit keeps the diff and
+rollback clean. Split mixed implementation, review, documentation, and roadmap requests into
+separate dispatches.
+
+## Premises freeze at dispatch
+
+The implementer starts from the brief's facts and there is no steering channel mid-run. Audit the
+fact block before sending — ownership, target branch, constraints, anything a judgment call rests
+on. If a premise turns out wrong while the run is live, stop the run and re-dispatch a corrected
+brief rather than discounting the output afterward; for a write-capable run, inspect the working
+tree and reconcile any partial or premise-contaminated edits — keep or revert them — before the
+re-dispatch.
+
+## A worked example
+
+```xml
+<task>
+In the payments service at services/billing/, the refund path double-charges when a refund is retried
+after a network timeout. Make refund submission idempotent: check for an existing refund by idempotency
+key before creating a new one. Touch only services/billing/refund.py and its tests. Leave the charge
+path, API routes, and data models untouched.
+</task>
+
+<verification_loop>
+Run and make green before finishing:
+  pytest tests/billing/ -q
+  ruff check services/billing/
+Confirm git status shows only refund.py and its test file changed.
+</verification_loop>
+
+<action_safety>
+Scope strictly to the refund idempotency fix. No unrelated refactors. Do NOT git add or commit; leave
+changes in the working tree for review.
+</action_safety>
+
+<structured_output_contract>
+Report: (1) the root cause and fix, (2) files touched, (3) pytest and ruff outcomes with counts,
+(4) anything left open or needing a decision.
+</structured_output_contract>
+```
+
+## Stdin delivery
+
+The relay pipes the brief to omp on stdin. Unlike CLIs that take the brief as an argument, there
+is no OS argv size cap and the brief never appears in the host process list. Large context can be
+inlined, but prefer pointing omp at workspace files it can read itself. Keep secrets out of the
+brief anyway on shared machines - reference environment variables or files with tight permissions.
+
+Dispatch with [dispatch-and-poll.md](dispatch-and-poll.md), then review and commit with
+[review-and-land.md](review-and-land.md).

package/bundled-skills/opencode-delegate/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: opencode-delegate
+description: Delegate coding tasks to the OpenCode CLI only when the user explicitly
+  requests it, while the orchestrator retains review and landing responsibility.
+risk: safe
+category: agent-orchestration
+source: https://github.com/amElnagdy/delegate-skills
+source_repo: amElnagdy/delegate-skills
+source_type: community
+date_added: '2026-08-26'
+license: MIT
+license_source: https://github.com/amElnagdy/delegate-skills/blob/master/LICENSE
+compatibility: Requires the `opencode` CLI installed and authenticated, Node 18+,
+  and git. The orchestrating agent must be able to run shell commands and read files.
+  Shell examples assume bash/zsh (macOS/Linux, or Git Bash/WSL on Windows).
+metadata:
+  version: 0.5.0
+---
+# OpenCode Delegate
+
+## When to Use
+
+- You want to delegate a bounded coding task to a separate `opencode` implementer (`OpenCode`) and then review its diff yourself.
+- The user explicitly asked for delegation to this implementer.
+
+You are the **orchestrator**. This skill lets you hand a bounded coding task to a separate
+**implementer** — the OpenCode CLI — then review what it produced and land it yourself. You write
+the brief and own the judgment; OpenCode does the typing in its own session; you verify and commit.
+
+Nothing here is specific to one orchestrating agent. The loop needs only the ability to run a shell
+command and read a file, so any agent with those two capabilities — Claude Code, OpenCode driving a
+sibling session, or a comparable one — can drive it. (It is designed for and run on Claude Code; treat
+other orchestrators as designed-for, not yet proven.)
+
+## When NOT to use this
+
+- The task is small enough to just do inline — delegation overhead is not worth it.
+- The `opencode` CLI is not installed or not authenticated (run `opencode auth login`).
+- You want to write the code yourself, or you only need a review (use the `plan` agent via `--read-only`).
+
+## Prerequisites (check once)
+
+1. `opencode --version` succeeds. If not, install (`npm i -g opencode-ai`, or the native installer from
+   opencode.ai) and `opencode auth login`.
+2. **Confirm which `opencode` is on PATH.** `command -v opencode` shows the active binary and
+   `opencode --version` its version. The relay records the version it ran into `result.json`, so a stale
+   binary is visible after the fact.
+3. A model provider is authenticated — `opencode auth list` shows at least one credential.
+4. You are in (or will point `--cd` at) the target git repository.
+
+## Choose the implementer model
+
+OpenCode has **no safe default** — a bare `opencode run` errors — so a fresh run needs a model via
+`--model` or a fleet `--lane` that sets one (a resumed run inherits its session's model). Naming the
+model is the one decision a single-model backend like codex-delegate never had, and it has two owners:
+
+- **The human owns which models are allowed.** `opencode models` lists hundreds of entries, most billed
+  per token (OpenRouter and the like); only the human knows which are their flat-rate subscriptions, and
+  the CLI can't tell them apart. So the usable set is theirs — ideally stated once in the repo's
+  `AGENTS.md` or their `CLAUDE.md` (e.g. "delegate mechanical work to `opencode-go/…`, hard logic to
+  `…`").
+- **You, the orchestrator, pick per task — from that set.** Match the model to the brief: a cheap, fast
+  model for a mechanical sweep (rename, migration, removal); a strong one for a subtle bug or a
+  money/security path.
+- **If no usable set is stated, ask — don't guess.** Guessing from the catalog risks a metered model and
+  a surprise bill. Name the constraint to the human and let them choose.
+
+More depth: [references/writing-the-brief.md](references/writing-the-brief.md).
+
+## The loop
+
+Run these five steps per task. Steps 1, 4, and 5 are your judgment; 2 and 3 are mechanical.
+
+### 1. Write the brief
+
+OpenCode sees **only** the text you send plus what it can read from the working tree — no chat history,
+no shared context. Everything the task needs goes in the brief: the goal, the current state, what to
+change, what to leave untouched, the project's **actual** gate commands (discover them from the repo's
+AGENTS.md/CLAUDE.md/Makefile — do not assume), and a report contract. Tell OpenCode it will **not**
+commit (you will). Keep one task per brief. Full guidance and a template:
+[references/writing-the-brief.md](references/writing-the-brief.md).
+
+### 2. Dispatch
+
+Send the brief to OpenCode with the bundled helper. It wraps `opencode run`, captures the run, and
+writes a structured `result.json` — so your only job is "run a command, read a file." (`<skill-dir>`
+below is this skill's installed directory — the folder containing this `SKILL.md`. Claude Code prints
+it as "Base directory for this skill" when the skill loads; on other orchestrators use that same
+directory — if unsure where it landed, run `find ~ -name relay.mjs -path '*opencode-delegate*'` and
+substitute the directory above it.)
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --model <provider/model> --cd /path/to/repo
+# --model (or a --lane that sets model) is required on a fresh run
+# fleet lane from delegate-setup:           add --lane <name>  (dials apply; flags still win)
+# read-only (review/diagnosis, no edits):   add --read-only   (uses the plan agent)
+# continue the previous OpenCode session:   add --resume-last  (delta brief only; keeps the model)
+# hard time limit (watchdog):               add --timeout 2h  (default: off; implementation runs routinely need 1-2h)
+# see all options:                          node .../relay.mjs --help
+```
+
+The helper defaults to the write-capable `build` agent and writes its artifacts to a temp dir, so the
+repo under review stays clean. It **never commits** — see step 5. Mechanics, flags, and the
+`result.json` shape: [references/dispatch-and-poll.md](references/dispatch-and-poll.md).
+
+### 3. Wait for completion
+
+The helper blocks until OpenCode finishes, so back it with whatever your orchestrator offers and resume
+when it returns:
+
+- **Claude Code:** run the Bash call with `run_in_background: true`; you are notified on completion.
+- **Plain shell / other agents:** run it in the foreground for short tasks, or background it and poll
+  the result file — `… &` in bash/zsh (including Git Bash/WSL), or your shell's equivalent (`Start-Job`
+  in PowerShell, `start /b` in cmd). The run is done when `result.json` exists with a `status`. (A
+  pre-run usage error — bad args or an empty brief — instead exits with code 2 and writes no result
+  file, so check the exit code too. A missing `opencode` binary exits 127 but *does* write a
+  `result.json` with status `opencode_unavailable`.)
+
+Do not trust progress trackers over reality: a run is finished when `result.json` is written and the
+process has exited. Read the working tree, not a status line. The implementer's full report is
+the `finalMessage` field in `result.json` (also printed in full on stdout between the report markers).
+
+### 4. Review — do not trust the self-report
+
+OpenCode's `result.json` includes its own final message and any gate claims. **Re-verify, don't accept:**
+
+- **Re-run the project's gates yourself** (the test/lint/build commands from step 1). Never take
+  "gates passed" on faith.
+- **Read the diff** against the brief: did OpenCode do what was asked, nothing more (scope creep) and
+  nothing less? `touchedFiles` in the result is your starting point.
+- **Run the relevant guard skills** on the diff if you have them installed (clean-code-guard,
+  test-guard, etc. from `guard-skills`) — this skill produces the work; those skills judge it.
+- For schema/migration changes, round-trip them; for removals, grep for dangling references.
+
+Full checklist: [references/review-and-land.md](references/review-and-land.md).
+
+### 5. Land it
+
+The implementer edits the working tree; **the orchestrator commits.** Committing should be the act of
+the party that verified the work. Only after the gates pass and the diff holds:
+
+- Commit the verified work yourself, with a clear message.
+- If it needs changes, send a delta brief with `--resume-last` (don't restate the whole task) and
+  review again.
+
+## Autonomy model
+
+OpenCode's autonomy is governed by the **agent**, not a sandbox enum:
+
+- **`build`** (the relay default) — write-capable; edits files in the working dir headlessly. The
+  equivalent of "let it implement."
+- **`plan`** (via `--read-only`) — read-only; reviews and diagnoses without touching the tree. The
+  equivalent of "let it look but not edit."
+
+Permissions **auto-approve by default**: the relay passes `--auto` so a headless run never blocks on a
+prompt no one can answer. That is the point of unattended delegation — the orchestrator's diff review
+and the implementer sweep (step 4) are the safety net, not a per-action prompt. Pass `--no-auto` to
+honor the agent's own permission config instead (allow/ask/deny per action); pair it with an agent whose
+in-workspace permissions are set to *allow*, or a headless run can hang waiting on an `ask`.
+**Read-only (`plan`) runs never get `--auto`** — auto-approving would let the plan agent's ask-gated
+edit/bash permissions through and defeat "read-only," so a review can't be tricked into touching the tree.
+
+## Authorization model
+
+Delegation is something the human opts into. Once they have ("run this queue", "proceed"), committing
+verified, gate-passing work is the agreed contract — that is the whole point. Two limits on that
+mandate: **surface, don't absorb** (report OpenCode's design decisions, defensible-but-unasked turns,
+and non-blocking nitpicks rather than silently keeping them) and **stop for scope changes** (if correct
+completion needs going beyond the brief, ask — don't expand the mandate yourself). The full treatment
+is in [references/review-and-land.md](references/review-and-land.md).
+
+## References
+
+- [references/writing-the-brief.md](references/writing-the-brief.md) — how to write a brief OpenCode can
+  execute blind: structure, XML blocks, the report contract, embedding the real gate commands.
+- [references/dispatch-and-poll.md](references/dispatch-and-poll.md) — `relay.mjs` flags, the
+  `result.json` contract, backgrounding per orchestrator, and recovery when a run misbehaves.
+- [references/review-and-land.md](references/review-and-land.md) — the review checklist, the commit
+  boundary, and the rework cycle via `--resume-last`.
+- [references/multi-task-queues.md](references/multi-task-queues.md) — running a sequential queue:
+  carrying constraints forward, progress tracking, and the end-of-run coherence check.
+
+
+## Limitations
+
+- Docs-only import — executable `scripts/relay.mjs` not included; see upstream for full runtime. Requires `opencode` CLI, Node 18+, git.
+- Relay never commits — it only returns structured result JSON; you review and land the commit.
+
+> Adapted from [amElnagdy/delegate-skills](https://github.com/amElnagdy/delegate-skills) (MIT) — docs-only, runtime not bundled.