opencode-skills-collection 4.0.45 → 4.0.47

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

@@ -0,0 +1,134 @@
+# Dispatch and poll
+
+`scripts/relay.mjs` wraps Kimi's headless prompt mode, captures its structured stream, and writes a
+`result.json`. Run one command, then read one file.
+
+## Before the first run
+
+```bash
+command -v kimi
+kimi --version
+kimi login
+```
+
+Install with `brew install kimi-code` on macOS/Linux or use a native installer from the
+[official Kimi Code documentation](https://moonshotai.github.io/kimi-code/en/). `kimi login` uses a
+device-code flow without opening the TUI; `/login` is also available inside the TUI.
+
+## 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. |
+| `--model <alias>` | Kimi model alias for this run (default: Kimi's own `default_model`). |
+| `--session <id>` | Resume a specific Kimi session; send only the delta brief. |
+| `--resume-last` | Resume the most recent Kimi session for this cwd (`kimi --continue`); send only the delta brief. |
+| `--add-dir <dir>` | Add an extra workspace directory. Repeatable. Edits there are not reported in `touchedFiles`. |
+| `--timeout <dur>` | Relay watchdog (default: `30m`; h/m/s strings). Kimi has no timeout flag. |
+| `--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 primary workspace;
+`--add-dir` adds extra workspaces only.
+
+Headless `-p` mode always uses Kimi's auto permission mode. Kimi rejects `--prompt` combined with
+`--yolo`, `--auto`, or `--plan`, so the relay passes no autonomy flags and has no `--read-only` or
+`--full-access` option. Inspect `touchedFiles` and the diff after every run.
+
+## 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 Kimi stdout events.
+- `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` (`"kimi"`), `status` (`completed` | `failed` | `timeout` | `aborted` | `kimi_unavailable`), `exitCode`, and
+  `signal` (`null` unless the child died on a signal).
+- `workdir`, `model` (the model alias or `null`), `resumed`, `kimiVersion`, `sessionId`, `startedAt`,
+  and `finishedAt`.
+- `briefPath`, `finalPath`, `eventsPath`, and `stderrPath`.
+- `finalMessage` - assistant `content` strings 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 Kimi's edits: anything already dirty before dispatch shows up too, and edits
+  Kimi makes inside `--add-dir` workspaces do not show up at all - inspect those trees yourself.
+  Dispatch from a clean tree when you want the list to read as "what Kimi 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, when the relay watchdog fires (`timeout`), and on an `aborted` run.
+
+Kimi's stream carries no token usage, so `result.json` has no `usage` field.
+
+## Waiting for completion
+
+The helper 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`.
+
+A pre-run usage error exits 2 and writes no result. A missing `kimi` exits 127 and writes
+`status: "kimi_unavailable"`.
+
+## When a run misbehaves
+
+- **`status: "kimi_unavailable"` (exit 127):** install the native Kimi Code CLI, authenticate with
+  `kimi login`, and re-dispatch.
+- **an `error` mentioning `version preflight` (`failed`, or `timeout` at exit 124):** the bounded
+  `kimi --version` probe exited non-zero or hung past its cap (10s, or `--timeout` when shorter), so
+  kimi was never dispatched; only the relay's own artifacts may already exist under `--out-dir`.
+  Check the install by running `kimi --version` yourself.
+- **`status: "failed"`:** read `stderrTail`, `stderrPath`, and the tail of `events.jsonl`. A common
+  cause is an unconfigured model alias: `error: failed to run prompt: config.invalid: Model "<x>" is not configured in config.toml…`
+- **`status: "aborted"`:** the relay itself was killed (its parent's timeout, a stopped task, a
+  closed terminal) and forwarded the kill to kimi. 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 a Kimi error; check host memory and re-dispatch, or
+  split the task into smaller briefs.
+- **`status: "timeout"`:** the `--timeout` watchdog killed the run; `error` reads
+  `kimi did not finish within --timeout <dur>; killed by the relay watchdog`. Increase `--timeout` or
+  split the task. The relay sends SIGTERM, waits 10 seconds, then sends SIGKILL if needed.
+- **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. 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 relay runs
+
+The argv is equivalent to:
+
+```bash
+kimi --output-format stream-json [--model <alias>] [--session <id> | --continue] \
+  [--add-dir <dir> ...] --prompt=<brief>
+```
+
+The prompt rides argv and is visible in the host process list. The relay rejects briefs over 120 KB
+before launch because the OS caps a single argument. It spawns the native `kimi` binary directly with
+the selected `--cd` as cwd; no shell or Kimi timeout flag is involved.
+
+## The commit boundary
+
+The relay never commits. Kimi 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/kimi-delegate/references/multi-task-queues.md

@@ -0,0 +1,58 @@
+# 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 Kimi 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 Kimi 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/kimi-delegate/references/review-and-land.md

@@ -0,0 +1,92 @@
+# Review and land
+
+Kimi did the typing; 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 Kimi'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 Kimi 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`. Kimi itself
+rejects combining `--continue` and `--session`; the relay rejects `--resume-last` plus `--session`
+before launch. Rework gets the same gate rerun, test review, diff review, and implementer sweep.
+
+Headless Kimi always uses auto permission mode and has no CLI-enforced read-only mode. Confirm
+`touchedFiles` after every fresh or resumed 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/kimi-delegate/references/writing-the-brief.md

@@ -0,0 +1,132 @@
+# Writing the brief
+
+A brief is the entire task as Kimi 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 Kimi.
+
+## Model choice and resumed sessions
+
+Kimi uses `default_model` from its `config.toml`, so a fresh dispatch does not require `--model`. Pass
+`--model <alias from your kimi config>` only when the human wants one of their configured model
+aliases. Do not invent an alias.
+
+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 Kimi 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).
+
+## Always ask for the report explicitly
+
+The relay builds `finalMessage` from assistant text in Kimi's structured 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. Kimi can inspect the workspace, but the important
+constraints should be directly in front of it.
+
+## One task per brief
+
+Keep each brief bounded. One brief -> one Kimi 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>
+```
+
+## Argv delivery limits
+
+Kimi headless mode requires the brief as a command-line argument. The relay reads a file or stdin for
+convenience, then passes the text with `--prompt=<brief>`. The equals form binds a brief that starts
+with `-` instead of treating it as another flag.
+
+This has two consequences:
+
+- The brief is visible in the host process list (`ps`, `/proc`). Keep secrets out of it on shared
+  machines; reference workspace files or environment variables instead.
+- A brief over 120 KB is rejected before launch because operating systems cap a single argv value.
+  Put large context in the workspace and tell Kimi which file to read.
+
+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/omp-delegate/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: omp-delegate
+description: Delegate coding tasks to Oh My Pi (`omp`) 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 `omp` CLI installed and authenticated (`/login` inside
+  omp, or a provider API-key environment variable), 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
+---
+# Oh My Pi Delegate
+
+## When to Use
+
+- You want to delegate a bounded coding task to a separate `omp` implementer (`Oh My 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** - Oh My
+Pi (`omp`) - 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.
+
+## The binary is `omp`, not `pi`
+
+Oh My Pi is a fork of Pi. This skill drives **`omp`** (`@oh-my-pi/pi-coding-agent`). The original
+Pi CLI is a different binary (`pi`) with a different skill (`pi-delegate`). If `omp` is missing but
+`pi` is installed, you have Pi, not Oh My Pi.
+
+## When NOT to use this
+
+- The task is small enough to do inline; delegation overhead is not worth it.
+- The `omp` CLI is not installed or authenticated.
+- The user asked for the original Pi CLI (`pi`) — use `pi-delegate`.
+- You need a sandboxed implementer. Oh My Pi has no sandbox. `--read-only` restricts the tool
+  surface; a write-capable run executes without prompts (`--yolo`).
+
+## Prerequisites (check once)
+
+1. Install omp with `bun install -g @oh-my-pi/pi-coding-agent` (or the install path from
+   https://omp.sh).
+2. Authenticate: `/login` inside omp for a subscription provider, or an API-key environment
+   variable for an API-key provider. Credentials live under `~/.omp/`.
+3. Confirm `omp --version` succeeds.
+4. Work in, or point `--cd` at, the target git repository.
+
+## Choose the model (optional)
+
+Omit `--model` (and `--provider`) to use omp's configured default for this project / profile. The
+catalog is **this install's** authenticated providers — not a fixed list in this skill.
+
+To pick another model:
+
+1. **List what this install can actually run.** Do **not** pass `omp --list-models` — that flag is
+   gone and omp treats it as an unknown flag (exit 2). Use the `models` subcommand:
+   - `omp models` — every available model, grouped by provider
+   - `omp models --json` — the same catalog, machine-readable
+   - `omp models find <substring>` — filter by provider, id, or name (example:
+     `omp models find sonnet`)
+   - `omp models <provider>` — one provider's models
+2. **Pass that id to the relay.** `--model <pattern>` is omp's own `--model`: a fuzzy match against
+   the catalog (provider/id, a bare id, or a unique substring). `--provider <name>` pins the
+   provider when the pattern is ambiguous.
+3. The relay forwards only letters, digits, and `. _ : / -`. Glob patterns with `*` are rejected.
+
+`--thinking <level>` is a separate reasoning dial, not a model id. Allowed values: `off`, `auto`,
+`minimal`, `low`, `medium`, `high`, `xhigh`, `max`. The relay rejects anything else (including
+`inherit`) before dispatch — omp would otherwise warn and ignore a bad value.
+
+A fleet lane (`--lane`) can set `provider`, `model`, and `effort`. Lane `effort` becomes
+`--thinking`; an explicit `--thinking` / `--model` / `--provider` flag wins over the lane.
+
+The relay does not forward `--api-key`, `--smol`, `--slow`, or `--plan`. Those stay omp's own CLI.
+
+## The loop
+
+Run these five steps per task. Steps 1, 4, and 5 require judgment; 2 and 3 are mechanical.
+
+### 1. Write the brief
+
+Oh My 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 omp not to commit. Keep one task per brief.
+omp 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 `omp --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
+# list models first:                       omp models   (or: omp models --json)
+# choose a model:                          add --model <id from omp models>
+# choose a provider:                       add --provider <name>
+# set thinking level:                      add --thinking high
+# read-only run (review/diagnosis):        add --read-only
+# trust project .omp 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 omp 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 `omp` exits 127 and writes `status: "omp_unavailable"`.
+
+Trust process state and the working tree over a progress display. Completion means the process
+exited and `result.json` exists. omp'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 omp'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
+
+Oh My Pi has **no sandbox**. Print mode has no approval UI, so a write-capable relay run always
+passes `--yolo` (`tools.approvalMode: yolo`) — otherwise a user's `always-ask` or `write` config
+would stall until the watchdog. The other controls are:
+
+1. `--read-only` restricts omp's callable tools to `--tools read,grep,glob`. It does not pass
+   `--yolo`. Installed extension code still runs with the user's host permissions if project
+   resources are trusted.
+2. The relay passes `--no-extensions --no-skills --no-rules` by default, so project `.omp`
+   extensions, skills, and rules stay undiscovered. `--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 omp'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, model listing, 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 omp 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 `omp` 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.