opencode-skills-collection 4.0.45 → 4.0.46

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

@@ -0,0 +1,171 @@
+# Dispatch and poll
+
+`scripts/relay.mjs` is the dispatch layer. It wraps `grok -p` (headless mode), runs the brief under
+an explicit autonomy profile, captures everything, and writes a structured `result.json`. Your job
+collapses to: run one command, then read one file. Everything Grok-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 grok      # the active binary; a stale install can shadow a current one
+grok version         # recorded into result.json so a stale binary is visible after the fact
+grok login           # or: grok login --device-auth / export XAI_API_KEY=...
+```
+
+Grok Build is an early beta gated behind an eligible xAI subscription (SuperGrok / X Premium+). An
+auth failure or missing beta access shows up as a failed run, not as `grok_unavailable`.
+
+## Dispatching
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --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 Grok (default: current directory); passed as `--cwd`. |
+| `--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>` | Grok model (default: Grok's own configured default). |
+| `--effort <level>` | Reasoning effort for this run (`--effort`). |
+| `--max-turns <n>` | Maximum number of agent turns for this run (`--max-turns`). |
+| `--read-only` | Review/diagnosis intent (`--sandbox read-only --permission-mode plan`). **Best-effort, not enforced** — grok can still edit the tree headlessly. The relay reports a tri-state Git-visible change tripwire. |
+| `--full-access` | Unrestricted auto-approve (`--always-approve --sandbox off`); opt-in. |
+| `--resume-last` | Continue the most recent Grok session for this cwd; send only the delta brief. |
+| `--session <id>` | Continue a specific session id; mutually exclusive with `--resume-last`. |
+| `--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). |
+
+Default autonomy (neither `--read-only` nor `--full-access`) is **workspace-write**:
+`--always-approve --sandbox workspace`. Grok's native default is `ask`, which would hang a headless
+pipe; the relay always sets autonomy explicitly.
+
+Artifacts default to the system temp dir on purpose: the repo under review stays clean, so the
+touched-files report shows only Grok'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` — `"grok"`
+- `status` — `completed` | `failed` | `timeout` | `aborted` | `grok_unavailable`
+- `exitCode` — mirrors Grok's exit code; `128` plus the signal number if the child was killed; `127` if `grok` 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`
+- `grokVersion` — the binary that actually ran
+- `sessionId` — feed this to a later `--session <id>` (or use `--resume-last`)
+- `finalMessage` — Grok's own final report (the `<structured_output_contract>` you asked for), assembled from the streaming-json `text` events
+- `usage` — token counts from the run's end event (`input_tokens` / `output_tokens` / `total_tokens`); `null` if none were reported
+- `touchedFiles` — `git status --porcelain` lines in the working root: your review starting point. `null` (not `[]`) when git can't report; `[]` means git ran and the tree is clean
+- `briefPath` / `eventsPath` / `finalPath` — the exact brief relay sent, the raw streaming-json event stream, and the final-message file
+- `workdir`, `autonomy`, `model`, `effort`, `resumeLast`, `startedAt`, `finishedAt`
+- `readOnlyViolation` — present on dispatched `--read-only` runs: `true` when parsed git porcelain or
+  the working-tree/index fingerprint of an already-dirty Git-visible path proves a change; `false`
+  when coverage is complete and detects none; `null` when coverage is incomplete. Ignored paths,
+  submodule internals, perfect restores, and attribution remain outside it — the diff review, not this flag, is the guarantee
+- `stderrTail` — last ~20 stderr lines; present on every run that did not complete (`failed`, `timeout`, `aborted`), absent on `completed`, `grok_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 Grok's exit code, so a wrapping script can
+branch on success/failure directly.
+
+## Waiting for completion
+
+The helper blocks until Grok 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 `grok` binary exits 127 but *does* write a
+  `result.json` with status `grok_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: grok_unavailable` (exit 127):** `grok` isn't on PATH or isn't found. Install with
+  `npm i -g @xai-official/grok` and `grok login`, then re-dispatch.
+- **an `error` mentioning `version preflight` (`failed`, or `timeout` at exit 124):** the bounded
+  `grok version` probe exited non-zero or hung past its cap (10s, or `--timeout` when shorter), so
+  grok was never dispatched; only the relay's own artifacts may already exist under `--out-dir`.
+  Check the install by running `grok version` yourself.
+- **`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 grok. 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.
+- **`status: failed`:** read `result.json`'s `stderrTail` and the tail of `eventsPath` for the cause.
+  Common causes: an auth lapse, missing beta access, an invalid `--model`, or a sandbox that blocked
+  something the task needed. Fix the cause and re-dispatch; don't paper over it by doing the work
+  yourself unless that's what the user wants.
+- **Empty `finalMessage`:** Grok exited before producing a final message, or the streaming-json event
+  shape didn't match the extractor. Treat as a failed run; the events log usually shows where it
+  stopped — and is the source of truth for tightening the parser.
+
+## 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
+# fresh run (default workspace-write autonomy)
+grok --no-auto-update --no-alt-screen --output-format streaming-json --cwd <repo> \
+  --always-approve --sandbox workspace --prompt-file <brief.txt>
+
+# resume most recent session for this cwd
+grok --no-auto-update --no-alt-screen --output-format streaming-json --cwd <repo> \
+  --continue --always-approve --sandbox workspace --prompt-file <delta.txt>
+
+# resume a specific session
+grok --no-auto-update --no-alt-screen --output-format streaming-json --cwd <repo> \
+  --resume <id> --always-approve --sandbox workspace --prompt-file <delta.txt>
+```
+
+`--no-auto-update` and `--no-alt-screen` are always set so automated runs don't check for updates or
+take over the terminal. Autonomy flags are re-passed on resume because headless permission mode may
+not inherit.
+
+**Prompt delivery:** the brief is handed to grok via `--prompt-file`, never argv — so it stays out of
+the host process list, isn't bounded by the OS argument-length cap, and a brief that begins with `-`
+can't be misread as a flag. The relay writes the brief you pass (via `--brief` or stdin) to a file and
+points `--prompt-file` at it.
+
+Two alternatives exist if you ever want them, but the helper is the recommended path:
+
+- **Raw `grok --prompt-file`** — fine for one-offs; you give up the captured `result.json`,
+  touched-files summary, and session-id extraction the helper does for you.
+- **`grok agent stdio` (ACP)** — richer IDE/tool integration over JSON-RPC. Out of scope for this
+  skill; the headless single-turn path is the one the relay drives.
+
+## The commit boundary
+
+The helper never commits — by design, not omission. The robust contract is: Grok edits the working
+tree, the orchestrator reviews and commits. See [review-and-land.md](review-and-land.md).

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

@@ -0,0 +1,67 @@
+# 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.
+
+## 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. Each fresh dispatch starts a **new** Grok session with no memory of
+the earlier run (unless you deliberately `--resume-last` / `--session`), 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 Grok 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/grok-delegate/references/review-and-land.md

@@ -0,0 +1,130 @@
+# Review and land
+
+Grok 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 Grok'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:
+
+For `--read-only`, treat `readOnlyViolation: true` as proof of a detected Git-visible change and
+`null` as incomplete coverage. `false` does not cover ignored paths, submodule internals, perfect
+restores, or attribution; inspect the actual diff.
+
+- **Scope creep** — did Grok 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 Grok 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 Grok 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 Grok 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 Grok. This isn't a
+workaround for a missing feature; it's the deliberate boundary. Committing should be the act of the
+party that verified the work. 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 Grok 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 Grok's context from the first run (via `grok --continue`), so a short delta is
+enough. To resume a specific session from `result.json`'s `sessionId`, pass `--session <id>` instead.
+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** Grok 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 Grok'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/grok-delegate/references/writing-the-brief.md

@@ -0,0 +1,119 @@
+# Writing the brief
+
+A brief is the entire task as Grok will see it. Grok runs in a fresh process 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 repo rules it discovers via `grok inspect`, and
+the repo's own `AGENTS.md` when present).
+If a constraint isn't in the brief or discoverable in the repo, it doesn't exist for Grok. The single
+most common failure is a brief that assumes context Grok doesn't have.
+
+## The shape that works
+
+Grok responds best 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 Grok 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), tell Grok in the brief not to edit anything, and run with `--read-only`. Note
+  `--read-only` is best-effort on grok, not a hard block — verify `touchedFiles` after the run.
+- **Research / recommendations** — add `<research_mode>` (separate observed facts, inferences, open
+  questions).
+
+## Discover the real gates — don't hardcode
+
+`<verification_loop>` is only useful if it names the project's *actual* commands. Read the repo's
+`CLAUDE.md` / `AGENTS.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 a Grok that guesses — or skips.
+
+## Honor the repo's conventions
+
+Grok discovers project configuration for the current directory (`grok inspect` shows rules, skills,
+plugins, hooks, and MCP servers). House rules in the repo (style, forbidden patterns, commit
+conventions) already apply when configured. 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 — restate the load-bearing ones in the brief too, because compliance is only as reliable
+as what's in front of the implementer.
+
+## 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 Grok
+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/kimi-delegate/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: kimi-delegate
+description: Delegate coding tasks to the Kimi Code CLI (`kimi`) 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
+---
+# Kimi Delegate
+
+## When to Use
+
+- You want to delegate a bounded coding task to a separate `kimi` implementer (`Kimi Code`) and then review its diff yourself.
+- The user explicitly asked for delegation to this implementer.
+
+You are the **orchestrator**. Hand a bounded coding task to a separate **implementer** - the Kimi Code
+CLI - then review what it produced and land it yourself. You write the brief and own the judgment;
+Kimi does the typing 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 `kimi` CLI is not installed or authenticated.
+- You need a CLI-enforced read-only implementer. Headless Kimi has no read-only mode.
+
+## Prerequisites (check once)
+
+1. Install Kimi Code with `brew install kimi-code` on macOS/Linux, or use the native installer from
+   the [official Kimi Code documentation](https://moonshotai.github.io/kimi-code/en/).
+2. Authenticate with `kimi login` (device-code flow, no TUI), or use `/login` in the TUI.
+3. Confirm `kimi --version` succeeds.
+4. Work in, or point `--cd` at, the target git repository.
+
+## Choose the model alias
+
+Kimi uses `default_model` from its `config.toml` when `--model` is omitted. To choose another model
+alias, pass `--model <alias from your kimi config>`. Model aliases are user-defined config keys; use
+one the human has configured rather than inventing one.
+
+## The loop
+
+Run these five steps per task. Steps 1, 4, and 5 require judgment; 2 and 3 are mechanical.
+
+### 1. Write the brief
+
+Kimi 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 Kimi not to commit. Keep one task per brief. See
+[references/writing-the-brief.md](references/writing-the-brief.md).
+
+### 2. Dispatch
+
+Use the bundled helper. It wraps Kimi's headless prompt mode, captures the structured 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 configured model alias:       add --model <alias from your kimi config>
+# 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. Use repeatable `--add-dir` flags only for extra workspace
+directories. 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 helper blocks until Kimi 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 `kimi` exits 127 and writes `status: "kimi_unavailable"`.
+
+Trust process state and the working tree over a progress display. Completion means the process exited
+and `result.json` exists. Kimi'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 Kimi'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
+
+In headless `-p` mode, Kimi always runs in **auto permission mode** and never asks for approval. Kimi
+rejects `--prompt` combined with `--yolo`, `--auto`, or `--plan`, so the relay passes none of them and
+offers no `--read-only` or `--full-access` option. There is no CLI-enforced read-only mode: inspect
+`touchedFiles` and the diff after every run. That diff, not a flag, is the guarantee of what changed.
+
+## 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 Kimi'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, argv 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 Kimi 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 `kimi` 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.