opencode-skills-collection 4.0.45 → 4.0.47

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

@@ -0,0 +1,156 @@
+# Dispatch and poll
+
+`scripts/relay.mjs` is the dispatch layer. It wraps `opencode run`, runs the brief under the chosen
+agent, captures everything, and writes a structured `result.json`. Your job collapses to: run one
+command, then read one file. Everything OpenCode-specific lives in the helper, which is what keeps the
+loop portable across orchestrators.
+
+## Before the first run: check the binary
+
+Two gotchas, both worth 30 seconds:
+
+```bash
+command -v opencode    # the active binary on PATH
+opencode --version     # the relay records this in result.json too
+opencode auth list     # at least one provider credential must be present
+```
+
+## Dispatching
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --model <provider/model> --cd /path/to/repo
+```
+
+(`<skill-dir>` is wherever this skill is installed — the folder containing its `SKILL.md`. On Claude
+Code it's the printed "Base directory for this skill"; on other orchestrators substitute that install
+path. See [`SKILL.md`](../SKILL.md) if you need to locate it.)
+
+Options:
+
+| Flag | Effect |
+| --- | --- |
+| `--brief <file>` | The brief. Omit it to read the brief from stdin (`node relay.mjs … < brief.txt`). |
+| `--cd <dir>` | Working root for OpenCode (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. |
+| `--model <name>` | Model as `provider/model`. **Required on a fresh run** — OpenCode has no safe default (a bare `opencode run` errors); a resumed run inherits its session's model. |
+| `--agent <name>` | OpenCode agent (default: `build`, write-capable). |
+| `--read-only` | Shortcut for `--agent plan` — review/diagnosis with no edits. |
+| `--variant <name>` | Provider reasoning effort (e.g. `high`, `max`, `minimal`). |
+| `--no-auto` | The relay passes `opencode`'s `--auto` (auto-approve permissions) **by default** so a headless run doesn't hang on a prompt; `--no-auto` drops it and honors the agent's own permission config instead. A `--read-only`/`plan` run never gets `--auto`, so it can't be auto-approved into edits. |
+| `--resume-last` | Continue the most recent OpenCode session; send only the delta brief (see review-and-land). |
+| `--session <id>` | Continue a specific session id (`ses_…`); send only the delta brief. |
+| `--pure` | Run OpenCode without external plugins (cleaner event stream). |
+| `--timeout <dur>` | Relay-side watchdog (e.g. `30m`, `2h`); on expiry the child is killed and `result.json` gets `status: "timeout"`. Off by default. |
+| `--out-dir <dir>` | Where artifacts go (default: a fresh dir under the system temp dir). |
+
+Artifacts default to the system temp dir on purpose: the repo under review stays clean, so the
+touched-files report shows only OpenCode's edits and nothing of the helper's own.
+
+## The result
+
+`<out-dir>/result.json` is the contract. Fields:
+
+- `schema` — the result-format version (currently `delegate-relay.result.v1`)
+- `tool` — `opencode`
+- `status` — `completed` | `failed` | `timeout` | `aborted` | `opencode_unavailable`
+- `exitCode` — mirrors OpenCode's exit code; `128` plus the signal number if the child was killed; `127` if `opencode` isn't on PATH; on a `timeout` the relay forces a non-zero code even when the child exited `0` after the watchdog's SIGTERM
+- `signal` — the signal that killed the child, otherwise `null`
+- `opencodeVersion` — the binary that actually ran
+- `agent` — the agent selected for this dispatch (`build`, `plan`, …)
+- `sessionId` — feed this to a later `--session <id>` (or use `--resume-last`)
+- `finalMessage` — OpenCode's assembled final text (the `<structured_output_contract>` you asked for).
+  Empty if OpenCode stopped without emitting a closing summary — ask for the report explicitly
+- `touchedFiles` — `git status --porcelain` lines in the working root: your review starting point.
+  `null` (not `[]`) when git can't report — `git` missing, or a non-repo run; `[]` means git ran and
+  the tree is clean
+- `cost` — total run cost in USD, summed from the step events (`null` if none were reported)
+- `briefPath` / `eventsPath` / `finalPath` — the exact brief relay sent, the raw JSON event stream, and
+  the final-message file
+- `workdir`, `model`, `auto`, `resumed`, `resumeLast`, `startedAt`, `finishedAt`
+- `stderrTail` — last ~20 stderr lines; present on every run that did not complete (`failed`, `timeout`, `aborted`), absent on `completed`,
+  `opencode_unavailable`, and launch failures
+- `error` — present on a launch failure, and on `timeout` and `aborted` runs
+
+The helper also prints a summary to stdout and exits with OpenCode's exit code, so a wrapping script can
+branch on success/failure directly.
+
+## Waiting for completion
+
+The helper blocks until OpenCode finishes. Back it with whatever your orchestrator offers:
+
+- **Claude Code:** run the `Bash` call with `run_in_background: true`; you're notified on completion,
+  then read `result.json`.
+- **Plain shell / other agents:** foreground for short tasks, or background and poll — `node relay.mjs
+  … &` in bash/zsh (including Git Bash/WSL), or your shell's equivalent (`Start-Job` in PowerShell,
+  `start /b` in cmd). A run is done when `result.json` exists with a `status`. **But** a pre-run usage
+  error (bad args, empty brief) exits with code 2 *before* writing any file — so check the exit code
+  too, don't only watch for the file. (A missing `opencode` binary exits 127 but *does* write a
+  `result.json` with status `opencode_unavailable`.)
+
+Trust the working tree and the process state over any progress display. A run is finished when the
+process has exited and `result.json` is written — not when a status line says so.
+
+## When a run misbehaves
+
+- **`status: opencode_unavailable` (exit 127):** `opencode` isn't on PATH or isn't found. Install
+  (`npm i -g opencode-ai`) and `opencode auth login`, then re-dispatch.
+- **an `error` mentioning `version preflight` (`failed`, or `timeout` at exit 124):** the bounded
+  `opencode --version` probe exited non-zero or hung past its cap (10s, or `--timeout` when shorter),
+  so opencode was never dispatched; only the relay's own artifacts may already exist under
+  `--out-dir`. Check the install by running `opencode --version` yourself.
+- **`status: failed`:** read `result.json`'s `stderrTail` and the tail of `eventsPath` for the cause.
+  Common causes: an auth lapse, an unknown `--model` or `--agent`, or a permission the run needed but
+  the agent didn't grant. Fix the cause and re-dispatch; don't paper over it by doing the work yourself
+  unless that's what the user wants.
+- **`status: timeout`:** the `--timeout` watchdog killed the run. The working tree may hold a
+  half-applied change — inspect it before deciding between a longer `--timeout`, a smaller brief,
+  or a resume.
+- **`status: aborted`:** the relay itself was killed (its parent's timeout, a stopped task, a
+  closed terminal) and forwarded the kill to opencode. 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 ended the child — commonly the OOM killer
+  or a supervisor timeout, not an implementer error. Free up host memory or split the task into
+  smaller briefs, then re-dispatch.
+- **Empty `finalMessage`:** OpenCode finished without emitting a closing text summary (common when it
+  completes purely through tool calls). The edits may still be correct — check `touchedFiles` and the
+  diff. To get a report next time, add a `<structured_output_contract>` block (see
+  [writing-the-brief.md](writing-the-brief.md)).
+- **A run hangs:** an agent with an `ask` permission can block waiting for approval that never comes in
+  headless mode. Runs pass `--auto` by default precisely to avoid this — so a hang almost always means
+  you passed `--no-auto`. Either drop it, or set the agent's permissions to *allow* (not ask) the
+  actions the task needs.
+
+## 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. Whether it also carries the edit contents depends on what the CLI streams,
+so 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 helper is doing (and the alternatives)
+
+Under the hood the helper runs roughly:
+
+```bash
+opencode run --format json --agent build -m provider/model < brief.txt             # fresh run (model required)
+opencode run --format json --continue --agent build < delta-brief.txt               # resume most recent (inherits model)
+opencode run --format json --session ses_… --agent build < delta-brief.txt           # resume a specific session
+```
+
+The brief is fed on **stdin**, never as an argument — which is why a multi-line, XML-tagged brief needs
+no quoting. The `--format json` stream is newline-delimited JSON events; the relay assembles
+`finalMessage` from the `text` events and pulls `sessionId` from the event stream. OpenCode selects an
+agent for each prompt, so the helper passes the requested agent on fresh and resumed runs.
+
+If you ever want it, raw `opencode run` is fine for one-offs — you just give up the captured
+`result.json`, touched-files summary, and session-id extraction the helper does for you.
+
+## The commit boundary
+
+The helper never commits — by design, not omission. The robust contract is: OpenCode edits the working
+tree, the orchestrator reviews and commits. See [review-and-land.md](review-and-land.md).

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

@@ -0,0 +1,68 @@
+# Multi-task queues
+
+The single-task loop scales to a queue, and that's where delegation pays off most — a removal split
+across layers, a migration touching many files, a refactor sweep. The discipline that makes a queue
+trustworthy is sequencing and bookkeeping, not parallelism.
+
+## Run sequentially, one commit per task
+
+Resist the urge to fan out the whole queue at once. Run tasks **one at a time, in dependency order**,
+landing each (review + gates + commit) before dispatching the next. Three reasons:
+
+- **Later tasks assume earlier ones landed.** Task 3's brief can say "the X added in the previous step
+  exists" only if the previous step actually committed.
+- **One commit per task** keeps the history reviewable and any single step revertible.
+- **Each review is honest.** A clean working tree before each dispatch means the next task's
+  `touchedFiles` shows only *its* changes, not a pile-up from earlier tasks.
+
+Parallelism is occasionally worth it for genuinely independent tasks on separate files, but it
+sacrifices the clean-tree-per-task property and makes review harder. Default to sequential. (Each fresh
+`relay.mjs` dispatch starts a new OpenCode session, so independent tasks don't share context — fold any
+shared constraint into each brief, see below.)
+
+## Carry decided constraints forward
+
+Implementation surfaces facts the original plan didn't have: a helper got named, a fixture lives in a
+specific place, an interface was chosen. When a later task depends on one of those, **fold it into that
+task's brief** as an explicit line. A fresh OpenCode session has no memory of the earlier run, so a
+constraint that emerged in task 2 must be restated in task 5's brief or it won't hold. This is the queue
+equivalent of keeping briefs self-contained.
+
+## Keep a progress file
+
+For anything longer than two or three tasks — especially a run the human steps away from — maintain a
+single progress file alongside the work. It's the durable record that survives your own context limits
+and lets the human catch up at a glance. A shape that works:
+
+- **Status table** — each task: queued / at-implementer / reviewed+committed (with the commit hash).
+- **Per-task review notes** — what landed, what you verified, the gate outcome. One short paragraph.
+- **"Needs your eyes"** — design decisions OpenCode made, non-blocking nitpicks, anything you want the
+  human to overrule or confirm. This is the section they read first.
+- **End-of-run checklist** — what happens after the last task (push, open/update the PR, manual checks
+  the human should do).
+
+Update it as each task lands, not in a batch at the end — if the run is interrupted, the file is still
+accurate.
+
+## Close with a coherence check
+
+Per-task review proves each step in isolation; it doesn't prove the steps cohere. After the last task,
+verify the whole:
+
+- Run the full test/build once more on the final tree — not just the last task's slice.
+- Do a repo-wide check for the thing the queue was about (e.g. after a removal, grep the entire tree
+  for any surviving reference; after a rename, confirm no stragglers).
+- For schema work, replay all the new migrations from a clean state and check for drift.
+- Then push and open or update the PR, with a description that reflects what actually shipped.
+
+## When to stop and ask
+
+Proceed without asking on anything that follows from the agreed plan — that's the point of the human
+opting into the queue. Stop and surface when:
+
+- A task can't be completed correctly within its brief's scope (a scope change is the human's call).
+- A review finds something that calls the *plan* into question, not just the implementation.
+- The gates reveal a problem that affects tasks already "done."
+
+Then report where you are, what's committed, and what the open question is — and wait. A queue that
+quietly works around a broken assumption produces a lot of commits in the wrong direction.

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

@@ -0,0 +1,125 @@
+# Review and land
+
+OpenCode did the typing; you own the judgment. This is where delegation earns its keep or quietly ships
+a mistake. The discipline is simple to state and easy to skip under time pressure: **verify against
+reality, never against the self-report — and read the diff as generated code, which fails in ways a
+green gate can't see.**
+
+## Check the tests before trusting the gates
+
+If the diff touches existing tests, review those edits *first* — before the gate re-run means anything.
+A weakened assertion, an added skip, or a deleted test makes the gate measure less than it did before
+the run; green is only meaningful if the yardstick wasn't shortened.
+
+- **Unbriefed edits to existing tests are a contract change, not part of the fix.** The brief asked for
+  an implementation; nothing in it authorized moving the goalposts. Flag them, don't absorb them.
+- **Skipped, disabled, or commented-out tests added in this diff:** treat the underlying test as failing
+  until proven otherwise, whatever the annotation's comment claims.
+- **Loosened assertions** (exact match relaxed to contains/truthy, error-type checks broadened, tolerance
+  widened): same treatment.
+
+## Re-run the gates yourself
+
+`result.json` carries OpenCode's own claim that the gates passed. Treat that as a claim, not evidence —
+re-run the project's actual test/lint/build commands in the working tree and read the output. And keep
+the result in proportion: **passing is necessary, not sufficient.** An implementer can *game* a gate,
+not just misreport it — that is what the test check above and the sweep below exist to catch.
+
+For changes with their own verification shape, go further:
+
+- **Migrations / schema:** round-trip them (apply, reverse, re-apply on a scratch target) and check for
+  drift, rather than trusting that "the migration is reversible."
+- **Removals / renames:** grep the codebase for dangling references to whatever was removed.
+- **Anything stateful:** exercise the actual behavior, don't just confirm it compiles.
+
+## Read the diff against the brief
+
+Open the diff (`touchedFiles` in the result is your starting list) and hold it against what you asked
+for:
+
+- **Scope creep** — did OpenCode change things the brief said to leave untouched? Unasked refactors,
+  renames, "while I was here" edits. These are the most common quality problem in delegated work.
+- **Scope shortfall** — did it do the whole task, including the edge cases and cleanup, or stop at the
+  first plausible version?
+- **Quiet judgment calls** — sometimes OpenCode makes a defensible decision the brief didn't anticipate.
+  Don't just accept it because it looks reasonable; understand it and decide.
+
+## The implementer sweep
+
+Generated code fails in systematic ways that gates are structurally blind to — each of these can sit in
+a diff whose tests are all green. Walk them against every diff before you commit:
+
+- **Hardcoded success or fixture data** on a path the brief says does real work — a canned
+  `{status: "ok"}` or default return passes tests *by design*. If OpenCode couldn't implement something,
+  the diff should fail loudly, not pretend.
+- **Catch-all error handling that returns a default** instead of propagating — the suppressed failure is
+  exactly what the gate would have caught. A broad catch is only acceptable with a recovery path the
+  contract documents.
+- **Unverified imports and API calls** — confirm every new dependency, method, and signature exists in
+  the *installed* version (read the lockfile or the package, don't trust plausibility).
+- **Dead weight** — unused imports, helpers nothing calls, unreachable branches, "Step 1/Step 2"
+  comment scaffolding, comments that restate the line below them.
+- **A second way to do what the file already does** — a new HTTP client, error idiom, or logging style
+  introduced beside the existing one instead of reusing it.
+- **New tests that assert internals** — asserting that an internal helper was called, or mocking the
+  project's own functions to isolate a "unit." Green, brittle, and worthless as regression cover.
+- **Near-duplicate test bodies** differing by one value — fold into one data-driven test or drop the
+  copies; bloat reads as coverage but isn't.
+- **Speculative surface** — optional parameters, config flags, or abstractions with no caller in this
+  diff or the repo. Delegated work gets the concrete behavior the brief asked for, nothing extra.
+- **Guards for impossible cases** — null/type checks for values the code's own contract already
+  excludes. Noise that buries the validation that matters at real trust boundaries.
+
+Anything the sweep catches goes back to OpenCode as a delta brief (below) or gets fixed in the tree
+before commit — and either way is reported to the user (see "Surface, don't absorb").
+
+If the `guard-skills` package is installed, run the relevant guard on the diff for the full treatment —
+`clean-code-guard` on production code, `test-guard` on tests, `docs-guard` on documentation. The sweep
+above is the built-in floor; the guards go deeper.
+
+## The commit boundary
+
+When the gates pass and the diff holds, **you commit** — the orchestrator, never the implementer. The
+`build` agent *can* write the working tree, but committing should be the act of the party that verified
+the work, not the one that produced it. Write a clear message describing what landed. If your project
+attributes co-authorship, that's the place for it.
+
+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.
+
+## Reworking: send the delta, not the whole task
+
+If the review turns up problems, don't restate the entire brief. Continue the same OpenCode session with
+just the correction:
+
+```bash
+echo "The fix is right, but the test mocks the DB session - use the real migrated fixture instead, and
+drop the now-unused import." | node "<skill-dir>/scripts/relay.mjs" --resume-last --cd /path/to/repo
+```
+
+(`<skill-dir>` is this skill's install directory — see [dispatch-and-poll.md](dispatch-and-poll.md).)
+
+`--resume-last` keeps OpenCode's session context from the first run (and its model), so a short delta is
+enough. Then review again — rework gets the same gate-rerun, test check, diff-read, and sweep as the
+original, no shortcuts. Repeat until it's right, then commit.
+
+## Surface, don't absorb
+
+The human opted into delegation, so committing verified, gate-passing work is the agreed contract.
+But keep them in the loop on anything that changes the shape of the work:
+
+- **Report design decisions** OpenCode made, and any defensible-but-unrequested turns it took.
+- **Note non-blocking nitpicks** you chose not to block on, so the human can overrule you.
+- **Stop and ask** if correct completion requires going beyond the brief — don't expand the mandate on
+  your own. A scope change is the human's call, not yours or OpenCode's.
+
+For a multi-task run, capture these in the progress file rather than letting them scroll past — see
+[multi-task-queues.md](multi-task-queues.md).

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

@@ -0,0 +1,142 @@
+# Writing the brief
+
+A brief is the entire task as OpenCode will see it. OpenCode runs in a fresh session with **no memory of
+your conversation, no access to your prior notes, and no shared context** — only the text you send and
+whatever it can read from the working tree (including the repo's own `AGENTS.md`, which it picks up
+automatically). If a constraint isn't in the brief or discoverable in the repo, it doesn't exist for
+OpenCode. The single most common failure is a brief that assumes context OpenCode doesn't have.
+
+## Match the model to the brief
+
+OpenCode has no default model, so every fresh dispatch names one with `--model provider/model`. Which
+model is a two-owner decision: the **human** owns which models are allowed to run; **you, the
+orchestrator**, pick one of them to fit the task in front of you.
+
+- **The allowed set is the human's to state.** `opencode models` lists a few hundred models, but most
+  bill per token (OpenRouter and the like) and the CLI does not mark which are the human's
+  subscriptions. So they name their usable models — ideally once, in the target repo's `AGENTS.md` or
+  their `CLAUDE.md` (e.g. `opencode-go/…`, `zai-coding-plan/…`, `minimax-coding-plan/…`). If they
+  haven't, ask before dispatching rather than guessing a model and risking a metered bill.
+- **Read the task's difficulty off the brief you just wrote, and match within that set.** A mechanical,
+  well-bounded brief — a rename sweep, a `moment`→`date-fns` migration, a dead-code removal — is safe on
+  a cheap, fast model. A brief whose risk lives in judgment — a concurrency fix, a money or auth path,
+  an ambiguous spec — wants a strong one, because the sweep's failure modes (plausible-but-wrong logic,
+  swallowed errors) are exactly what a weaker model produces more of.
+- **A resumed run keeps the first run's model.** `--resume-last` / `--session` don't take `--model`; the
+  session already has one. Send only the delta brief.
+
+## The shape that works
+
+OpenCode responds well to compact, block-structured prompts with XML tags rather than long prose. State
+the task, what "done" looks like, how to behave by default, and the few constraints that actually
+matter. Add a block only when the task needs it — don't ship empty ceremony.
+
+```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 is what keeps OpenCode from
+wandering into unrelated refactors.
+</task>
+
+<verification_loop>
+Run these before finishing and fix anything they surface, don't 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 (paste the test/lint counts)
+  4. Anything you deviated on, left open, or want a decision on
+</structured_output_contract>
+```
+
+That four-block skeleton covers most implementation tasks. Reach for the extra blocks when the task
+profile calls for them:
+
+- **Debugging / open-ended fixes** — add `<completeness_contract>` (resolve fully, don't stop at the
+  first plausible fix) and `<missing_context_gating>` (don't guess missing repo facts; find them or
+  state what's unknown).
+- **Review / diagnosis (read-only)** — add `<grounding_rules>` (ground every claim in evidence; label
+  inferences) and dispatch with `--read-only` so OpenCode runs as the `plan` agent and can't edit.
+- **Research / recommendations** — add `<research_mode>` (separate observed facts, inferences, open
+  questions).
+
+## Always ask for the report explicitly
+
+The relay assembles OpenCode's final message from the text it emits when it stops. If the agent finishes
+a task purely through tool calls and stops without a closing summary, `finalMessage` comes back empty —
+not a relay defect, just nothing said. The `<structured_output_contract>` block is what guarantees a
+report you can read: it tells OpenCode to end with a written summary, so the result file carries one.
+
+## Discover the real gates — don't hardcode
+
+`<verification_loop>` is only useful if it names the project's *actual* commands. Read the repo's
+`AGENTS.md` / `CLAUDE.md` / `Makefile` / `package.json` first and copy the real ones in (`make test`,
+`npm run lint`, `cargo test`, `pytest -q`, whatever it is). A brief that says "run the tests" without
+naming them gets you an OpenCode that guesses — or skips.
+
+## Honor the repo's conventions
+
+OpenCode reads the repo's `AGENTS.md` automatically, so house rules there (style, forbidden patterns,
+commit conventions) already apply. If the project forbids certain things in code — say, spec/ticket IDs
+in comments, process language like "MVP"/"for now"/"phase N", or specific test conventions, whatever the
+repo's own conventions ban — restate the load-bearing ones in the brief too, because OpenCode's
+compliance is only as reliable as what's in front of it.
+
+## One task per brief
+
+Keep each brief to a single, bounded job. "Review this, fix what you find, update the docs, and suggest
+a roadmap" produces a muddled run; split it into separate dispatches. One brief → one OpenCode run →
+one commit keeps review and rollback clean, and lets a later task assume the earlier one landed.
+
+## 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 (the idempotency key isn't checked before re-submitting). Make the 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, the API routes, and the
+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 your fix, (2) files touched, (3) pytest + ruff outcomes with counts,
+(4) anything you left open or want decided.
+</structured_output_contract>
+```
+
+Send this with `relay.mjs` (see [dispatch-and-poll.md](dispatch-and-poll.md)); review the result and
+commit it yourself (see [review-and-land.md](review-and-land.md)).

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

@@ -0,0 +1,148 @@
+---
+name: pi-delegate
+description: Delegate coding tasks to the Pi coding agent CLI (`pi`) 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
+metadata:
+  version: 0.5.0
+---
+# Pi Delegate
+
+## When to Use
+
+- You want to delegate a bounded coding task to a separate `pi` implementer (`Pi`) and then review its diff yourself.
+- The user explicitly asked for delegation to this implementer.
+
+You are the **orchestrator**. Delegate a bounded coding task to a separate **implementer** - the Pi
+coding agent CLI - then review what it produced and land it yourself. You write the brief and own
+the judgment; the implementer makes changes in its own session; you verify and commit.
+
+The loop needs only a shell command and file access, so any comparable orchestrator can drive it.
+
+## When NOT to use this
+
+- The task is small enough to do inline; delegation overhead is not worth it.
+- The `pi` CLI is not installed or authenticated.
+- You need a sandboxed implementer. Pi has no sandbox and no permission modes; `--read-only`
+  restricts the tool surface, but a write-capable run executes without prompts.
+
+## Prerequisites (check once)
+
+1. Install pi with `npm install -g @earendil-works/pi-coding-agent`.
+2. Authenticate: `/login` inside pi for a subscription provider, or an API-key environment
+   variable / `pi`'s auth file for an API-key provider.
+3. Confirm `pi --version` succeeds.
+4. Work in, or point `--cd` at, the target git repository.
+
+## Choose the model (optional)
+
+Omit `--model` to use pi's configured default. To pick another, choose from `pi --list-models`
+and pass an explicit id or pattern like `<provider>/<model-id>` or `sonnet:high`. The relay
+accepts letters, digits, and `. _ : / -` only (the value reaches a shell on Windows), so glob
+patterns with `*` are not forwarded.
+
+## The loop
+
+Run these five steps per task. Steps 1, 4, and 5 require judgment; 2 and 3 are mechanical.
+
+### 1. Write the brief
+
+Pi sees only the text you send plus what it can inspect in the workspace - no chat history or
+shared context. Include the goal, current state, what to change, what to leave untouched, the
+project's **actual** gates, and a report contract. Tell pi not to commit. Keep one task per brief.
+Pi auto-loads `AGENTS.md`/`CLAUDE.md` context files from the workspace and its parents, so repo
+instructions reach it without inlining. See
+[references/writing-the-brief.md](references/writing-the-brief.md).
+
+### 2. Dispatch
+
+Use the bundled relay. It pipes the brief to `pi --mode json` on stdin, captures the JSON event
+stream, and writes `result.json`. (`<skill-dir>` is the installed folder containing this
+`SKILL.md`.)
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
+# choose a model:                          add --model <id from pi --list-models>
+# choose a provider:                       add --provider <name>
+# read-only run (review/diagnosis):        add --read-only
+# trust project .pi resources:             add --approve
+# resume the most recent session:          add --resume-last  (delta brief only)
+# resume a specific session:               add --session <id> (delta brief only)
+# hard time limit (watchdog):              add --timeout 2h  (the 30m default suits short runs; implementation briefs routinely need 1-2h)
+# see all options:                         node .../relay.mjs --help
+```
+
+The child process's cwd pins the workspace. The relay writes artifacts under the system temp dir
+by default and never commits. See [references/dispatch-and-poll.md](references/dispatch-and-poll.md).
+
+### 3. Wait for completion
+
+The relay blocks until pi finishes. Run it with the orchestrator's background-command facility,
+or background it in the shell and poll for `result.json`. A pre-run usage error exits 2 and writes
+no result; a missing `pi` exits 127 and writes `status: "pi_unavailable"`.
+
+Trust process state and the working tree over a progress display. Completion means the process
+exited and `result.json` exists. Pi'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
+
+Treat pi's final message and gate claims as claims:
+
+- Re-run the project's gates yourself.
+- Read the diff against the brief, starting with `touchedFiles`.
+- Run relevant guard skills if installed.
+- Round-trip migrations and grep for dangling references after removals or renames.
+
+See [references/review-and-land.md](references/review-and-land.md).
+
+### 5. Land it
+
+The implementer edits the working tree; **the orchestrator commits.** Commit only after the gates
+pass and the diff holds. If rework is needed, send a delta brief with `--resume-last` or
+`--session <id>`, then review again.
+
+## Autonomy and permissions
+
+Pi has **no sandbox and no permission modes**. A default headless run reads, writes, edits, and
+executes shell commands with no prompts - the controls are:
+
+1. `--read-only` restricts pi's callable tools to `--tools read,grep,find,ls` across built-in,
+   extension, and custom tools. Installed extension code still runs with the user's host permissions.
+2. The relay passes `--no-approve` by default, so project `.pi` settings, extensions, and skills
+   stay untrusted. `--approve` is the explicit opt-in for a repository the user trusts.
+3. `touchedFiles` and the diff are the record of what changed. Inspect them after every run.
+
+## 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. Two limits remain: **surface, don't
+absorb** (report pi's design decisions, defensible-but-unasked turns, and non-blocking nitpicks)
+and **stop for scope changes** (if correct completion needs going beyond the brief, ask instead of
+expanding the mandate). See [references/review-and-land.md](references/review-and-land.md).
+
+## References
+
+- [references/writing-the-brief.md](references/writing-the-brief.md) - structure, report contract,
+  real gates, stdin delivery, and delta briefs.
+- [references/dispatch-and-poll.md](references/dispatch-and-poll.md) - flags, artifacts,
+  `result.json`, polling, and failure recovery.
+- [references/review-and-land.md](references/review-and-land.md) - review checklist, commit
+  boundary, and rework through pi sessions.
+- [references/multi-task-queues.md](references/multi-task-queues.md) - sequential queues,
+  constraint carry-forward, progress tracking, and the final coherence pass.
+
+
+## Limitations
+
+- Docs-only import — executable `scripts/relay.mjs` not included; see upstream for full runtime. Requires `pi` 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.