opencode-skills-collection 4.0.45 → 4.0.46

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

@@ -0,0 +1,159 @@
+---
+name: copilot-delegate
+description: Delegate coding tasks to the GitHub Copilot CLI (`copilot`) 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 `copilot` CLI installed and authenticated (`copilot login`),
+  Node 18+ to run the relay (the copilot CLI itself requires Node 22+), and git. The
+  orchestrator must be able to run shell commands and read files.
+metadata:
+  version: 0.5.0
+---
+# Copilot Delegate
+
+## When to Use
+
+- You want to delegate a bounded coding task to a separate `copilot` implementer (`GitHub Copilot CLI`) 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
+GitHub Copilot 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 in a clean working tree; 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 `copilot` CLI is not installed or authenticated.
+- You need a hard sandbox. Copilot exposes sandbox controls, but they are upstream-experimental
+  (MXC-based, controlled via the `/sandbox` command and settings, disabled by default) — this relay
+  does not configure them. `--read-only` only disables edit tools (`--mode plan`); shell commands
+  still run. If project files must not change at all, dispatch against a clean or isolated worktree.
+
+## Prerequisites (check once)
+
+1. Install `copilot` (`npm install -g @github/copilot`; the CLI requires Node 22+, the relay
+   itself runs on Node 18+ — the relay probes `copilot version`).
+2. Authenticate: run `copilot login` (interactive web/device flow), or set
+   `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` in the environment.
+3. Confirm `copilot version` succeeds.
+4. Work in, or point `--cd` at, the target git repository.
+
+## Choose the model (optional)
+
+Copilot picks a default model (`auto`). To choose another, pass `--model <name>`.
+The relay accepts letters, digits, and `. _ : / -` only (the value reaches a shell on Windows).
+
+## Choose the effort (optional)
+
+Copilot supports a reasoning effort dial: `--effort <level>` with values
+`low`, `medium`, `high`, `xhigh`, or `max`. The relay rejects any other value
+before dispatch.
+
+## The loop
+
+Run these five steps per task. Steps 1, 4, and 5 require judgment; 2 and 3 are mechanical.
+
+### 1. Write a brief
+
+Copilot sees only the text you send. It cannot read your conversation: the brief must stand alone
+with the goal, current state, what to change, what to leave untouched, the project's **real**
+gates, and a report contract. Keep each brief to a single task. Write it to a file and pass it as
+the relay's `--brief`. See [references/writing-the-brief.md](references/writing-the-brief.md).
+
+### 2. Dispatch
+
+Use the bundled relay. It runs `copilot -p` with `--output-format json --no-color --stream off`,
+captures the JSONL event stream, and writes `result.json`.
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
+# choose a model:                    add --model <name>
+# set reasoning effort:              add --effort <level>
+# read-only planning pass:           add --read-only  (forces --mode plan)
+# full tool autonomy:                add --allow-all-tools
+# hard time limit (watchdog):        add --timeout 2h   (the 30m default suits brief runs)
+# resume a session:                  add --session <id>  or  --resume-last
+# see all options:                   node .../relay.mjs --help
+```
+
+The child'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 copilot 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 `copilot` exits 127 and writes `status: "copilot_unavailable"`.
+
+Completion means the process exited and `result.json` exists — trust process state and the
+working tree, not the progress display. Copilot's final assistant message is the `finalMessage`
+field of `result.json`.
+
+### 4. Review — do not trust the self-report
+
+- Re-run the project's gates yourself.
+- Read the diff against the brief, starting with `touchedFiles`.
+- Run relevant guard skills if installed.
+
+See [references/review-and-land.md](references/review-and-land.md).
+
+### 5. Land it
+
+If the work is good, commit it. The relay never commits — the diff and `result.json` are the
+record; run `git status` and `git diff` first to confirm exactly what changed. If the group has a
+PR flow, make the commit and push a branch; let human review happen. If the diff is wrong or
+incomplete, re-dispatch a corrected brief in a fresh run and review again.
+
+## Autonomy and permissions
+
+Without `--allow-all-tools`, copilot auto-denies tool calls in headless mode: the process exits 0
+but the relay detects the denial events and reports `status: "failed"` with the CLI's own error
+message and a hint to pass `--allow-all-tools`. This is the honest default — the orchestrator sees
+the failure rather than a silent no-op.
+
+`--allow-all-tools` explicitly grants full tool autonomy and requires explicit human authorization
+for that run. A request to delegate to Copilot is not by itself consent to unrestricted tools.
+`--read-only` selects `--mode plan`,
+which disables edit tools so project files can't be changed by direct edits; it works without
+`--allow-all-tools`. Shell commands still run in plan mode, so it guards against edits, not
+against everything. The two flags are mutually exclusive.
+
+Copilot also exposes sandbox controls, but they are upstream-experimental (MXC-based, controlled
+via the `/sandbox` command and settings, disabled by default). This relay does not configure them.
+
+## Authorization model
+
+Delegation is something the human opts into. Once briefed, copilot works as a tool you approved use
+of. The boundary is: **do not accept conclusions from the self-report**; verify everything on
+disk. For anything touching credentials, production data, or irreversible operations, stop and ask
+the human first instead of encoding it in a brief.
+
+## References
+
+- [references/writing-the-brief.md](references/writing-the-brief.md) — structure, scope, gates,
+  brief delivery.
+- [references/dispatch-and-poll.md](references/dispatch-and-poll.md) — flags, artifacts,
+  `result.json`, and failure recovery.
+- [references/review-and-land.md](references/review-and-land.md) — what to verify before calling
+  the diff done, at the end of a run.
+- [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 `copilot` 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.

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

@@ -0,0 +1,143 @@
+# Dispatch and poll
+
+`scripts/relay.mjs` wraps copilot's headless JSONL mode, captures its event stream, and writes
+a `result.json`. Run one command, then read one file.
+
+## Before the first run
+
+```bash
+command -v copilot
+copilot version
+```
+
+Install `copilot` (`npm install -g @github/copilot`; the CLI requires Node 22+, the relay itself
+runs on Node 18+); on Windows it installs as an npm `.cmd` shim
+(the relay launches it with `shell:true`). Authenticate with `copilot login` or set
+`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`. A headless run that is not authenticated
+fails with `status: "failed"` (exit 1).
+
+## 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 <name>` | Copilot model (default: copilot's own default, `auto`). Token-validated: letters, digits, `. _ : / -`. |
+| `--effort <level>` | Reasoning effort (`low`\|`medium`\|`high`\|`xhigh`\|`max`). Rejected before dispatch if unknown. |
+| `--read-only` | Read-only plan mode (`--mode plan`); works without `--allow-all-tools`. Mutually exclusive with `--allow-all-tools`. |
+| `--allow-all-tools` | Full tool autonomy; requires explicit human authorization for that run. Without this, headless tool calls are auto-denied and the relay reports `status: "failed"`. Mutually exclusive with `--read-only`. |
+| `--resume-last` | Resume the most recent session (`--continue`). |
+| `--session <id>` | Resume a specific session (`--resume=<id>`). Mutually exclusive with `--resume-last`. |
+| `--timeout <dur>` | Relay watchdog (default: `30m`; h/m/s strings). Copilot 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. |
+
+The child cwd pins the workspace. The relay does not pass copilot's `--add-dir`.
+
+## 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 copilot stdout events (every JSONL event copilot emitted).
+- `final.txt` — the last non-ephemeral `assistant.message` content; absent if none was emitted.
+- `stderr.txt` — complete stderr.
+- `result.json` — the stable `delegate-relay.result.v1` contract.
+
+`result.json` fields:
+
+- `schema`, `tool` (`"copilot"`), `status` (`completed` | `failed` | `timeout` | `aborted` | `copilot_unavailable`), `exitCode`, and `signal` (`null` unless the child died on a signal).
+- `workdir`, `model`, `effort`, `readOnly`, `allowAllTools`, `resumed`, `copilotVersion`,
+  `startedAt`, and `finishedAt`.
+- `sessionId` — parsed from the `result` event's `sessionId` field; available for resume.
+- `finalMessage` — text of the last non-ephemeral `assistant.message` event.
+- `touchedFiles` — `git status --porcelain` lines for the **final working tree under `--cd` only**,
+  not an attribution of copilot's edits: anything already dirty before dispatch shows up too.
+  Dispatch from a clean tree when you want the list to read as "what copilot changed". `null` means
+  git could not report; `[]` means git ran and the tree is clean.
+- `briefPath`, nullable `finalPath`, `eventsPath`, and `stderrPath`. `finalPath` is `null` when
+  copilot emitted no non-ephemeral assistant message and `final.txt` was not created.
+- `stderrTail` — the last 20 non-empty stderr lines on any run that did not complete (`failed`,
+  `timeout`, `aborted`).
+- `error` — present on denial failures (with the CLI's own denial message plus a hint to pass
+  `--allow-all-tools`), preflight failures, when the relay watchdog fires (`timeout`), and on an
+  `aborted` run.
+
+## Waiting for completion
+
+The relay blocks. Use the orchestrator's background-command facility, or background it in a shell
+and poll for `result.json`. The run is done only when the process exits and the file contains a
+`status`. The result file is written atomically, so a partial read is impossible.
+
+A pre-run usage error exits 2 and writes no result. A missing `copilot` exits 127 and writes
+`status: "copilot_unavailable"`.
+
+## When a run misbehaves
+
+- **`status: "copilot_unavailable"` (exit 127):** copilot is not on PATH. Install it, authenticate,
+  and re-dispatch.
+- **`status: "failed"` with a denial error:** copilot auto-denied a tool call in headless mode.
+  The error message includes the CLI's own denial text and a hint to pass `--allow-all-tools`.
+  Re-dispatch with `--allow-all-tools` to grant full tool permissions.
+- **`status: "failed"`:** read `stderrTail`, `stderrPath`, and the tail of `events.jsonl`. Common
+  causes: an unknown `--model`, expired credentials, or a provider error.
+- **`status: "failed"` with an `error` mentioning `version preflight`:** the bounded
+  `copilot version` probe failed or hung, so copilot was never dispatched. Check the install
+  (`copilot version` yourself).
+- **`status: "aborted"`:** the relay itself was killed (its parent's timeout, a stopped task, a
+  closed terminal) and forwarded the kill to copilot. The result is written before the relay exits;
+  inspect the working tree before re-dispatching.
+- **`status: "timeout"`:** the `--timeout` watchdog killed the run; `error` reads
+  `copilot did not finish within --timeout <dur>; killed by the relay watchdog`. Increase
+  `--timeout` or split the task.
+- **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 JSONL 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.
+
+## What the relay runs
+
+The launch is equivalent to:
+
+```bash
+copilot --output-format json --no-color --stream off \
+  [--mode plan] [--allow-all-tools] \
+  [--continue | --resume=<id>] \
+  [--model <name>] [--effort <level>] \
+  -p @<brief.txt>
+```
+
+The child process cwd pins the workspace. Only token-validated model/effort/session values and
+fixed text reach the `shell:true` launch on native Windows; the brief is delivered via `-p @<file>`
+(the CLI's @-prefixed file prompt channel), with the brief path quoted for the shell on Windows.
+On resume (`--continue` / `--resume=<id>`) the relay wraps the reference in a fixed directive —
+`Execute the instructions in the referenced file, then report what you did. Do not just summarize
+the file: @<file>` — because a bare `@<file>` reference in a resumed session is echoed back instead
+of executed (verified on copilot 1.0.78). The directive is relay-authored fixed text, so no user
+content ever reaches the shell-quoted value on Windows. Fresh runs deliver the bare `@<file>`,
+which copilot executes correctly.
+Before dispatch the relay runs a bounded `copilot version` preflight (10s cap) so a
+hung or crashing CLI fails fast and explicitly instead of hanging the run.
+
+Copilot's JSONL events include ephemeral events (mcp status, skills_loaded, etc.) which the relay
+skips, `assistant.message` events whose `data.content` becomes `finalMessage`, and a final
+`result` event carrying `sessionId` and `usage.codeChanges`. Tool execution events with
+`success: false` and `error.code: "denied"` trigger the denial-detection path.
+
+## The commit boundary
+
+The relay never commits. Copilot 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/copilot-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 --allow-all-tools
+```
+
+- 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 copilot 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 `--session <id>` to resume a previous session with a delta brief when continuity matters.
+`--resume-last` resumes the most recent session.
+
+## 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/copilot-delegate/references/review-and-land.md

@@ -0,0 +1,80 @@
+# Review and land
+
+The implementer made the changes; you own the judgment. Verify against reality, never the
+self-report, and read the diff as generated code because a green gate cannot catch every failure
+mode.
+
+## Check tests before trusting gates
+
+If the diff touches existing tests, review those edits first:
+
+- Treat unbriefed test edits as a contract change, not part of the fix.
+- Treat newly skipped, disabled, or commented-out tests as failing until proven otherwise.
+- Treat loosened assertions the same way: contains/truthy replacing exact matches, broadened
+  error types, and widened tolerances all weaken the gate.
+
+## Re-run the gates yourself
+
+`result.json` carries copilot'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.
+
+## 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 copilot 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 commit the intended files explicitly.
+
+## Rework: re-dispatch a corrected brief
+
+Re-dispatch the correction with the needed context:
+
+```bash
+echo "The fix is right, but the tests mock the DB session: use the real migrated fixture and
+remove the unused import." | node "<skill-dir>/scripts/relay.mjs" --cd /path/to/repo --allow-all-tools
+```
+
+Use `--session <id>` from the previous run's `result.json` to resume the session with the delta
+brief, or dispatch a fresh run. Each correction gets the same test review, diff review, and
+implementer sweep.
+
+## 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/copilot-delegate/references/writing-the-brief.md

@@ -0,0 +1,140 @@
+# Writing the brief
+
+A brief is the entire task as copilot will see it. It runs in a separate process with **no memory of
+your conversation 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 copilot.
+
+Copilot can auto-discover the workspace's `AGENTS.md`. Still restate load-bearing repo constraints in
+the brief so the implementer does not have to infer which rules matter for this task.
+
+## Model and effort choice
+
+Copilot picks a default model when `--model` is omitted, so a fresh dispatch does not require it.
+Pass `--model <name>` only when the human asked for a specific model. `--effort <level>` sets the
+reasoning effort (`low`, `medium`, `high`, `xhigh`, `max`). The relay rejects any other effort
+value before dispatch. Model values still accept letters, digits, and `. _ : / -` only.
+
+## The shape that works
+
+Use a compact, block-structured brief. State the task, what done means, the few constraints that
+matter, and the report copilot must return.
+
+```xml
+<task>
+One or two sentences: the concrete job and where it lives. Then the specifics - current state, what to
+change, and explicitly what to leave untouched. The leave-untouched list prevents unrelated refactors.
+</task>
+
+<verification_loop>
+Run these before finishing and fix anything they surface, do not just report it:
+  <the project's real test command>
+  <the project's real lint/format command>
+  <the project's real build/typecheck command>
+Confirm the working tree shows only the intended changes afterward.
+</verification_loop>
+
+<action_safety>
+Keep changes scoped to the task. No unrelated refactors, renames, or cleanup unless required for
+correctness. Do NOT run git add or git commit - the orchestrator commits after reviewing. Leave the
+work uncommitted in the working tree.
+</action_safety>
+
+<structured_output_contract>
+End with a report in this exact shape:
+  1. What changed and why
+  2. Files touched
+  3. Gate outcomes (include test/lint counts)
+  4. Anything you deviated on, left open, or want a decision on
+</structured_output_contract>
+```
+
+Add extra blocks only when the task needs them:
+
+- **Debugging or open-ended fixes** — add `<completeness_contract>` (resolve fully, not just the
+  first plausible cause) and `<missing_context_gating>` (find missing repo facts or state what is
+  unknown).
+- **Research or recommendations** — add `<research_mode>` (separate observed facts, inferences,
+  and open questions), and dispatch with `--read-only`; copilot runs in `--mode plan`, which
+  disables edit tools so project files can't be changed by direct edits (shell commands still
+  run). If the repository must not change at all, dispatch against a clean or isolated worktree.
+
+## Always ask for the report explicitly
+
+The relay builds `finalMessage` from the last non-ephemeral `assistant.message` event. 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. Copilot 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 copilot 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; 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>
+```
+
+## Brief delivery
+
+The relay hands the brief to copilot via `-p @<brief.txt>` — the CLI's
+`@`-prefixed file prompt channel (verified on copilot 1.0.78), the same shape
+grok's relay uses with `--prompt-file`. The brief content never rides argv —
+only the `@<brief.txt>` reference does, plus a fixed execution directive on
+resume. The content stays out of the host process list, isn't bounded by the
+OS arg-length cap, and a brief that starts with "-" cannot be misread as a
+flag. On a shared machine keep secrets out of the brief anyway — reference
+them by a path or environment variable the workspace can read. The brief is
+also preserved in the run's `brief.txt` artifact.
+
+On resume (`--session` / `--resume-last` with a delta brief) the relay wraps
+the reference in a fixed directive so the resumed session executes it rather
+than echoing the file back (see [dispatch-and-poll.md](dispatch-and-poll.md)).
+The delta brief itself is unchanged; write it exactly as you would for a fresh
+dispatch.
+
+Dispatch with [dispatch-and-poll.md](dispatch-and-poll.md), then review and commit with
+[review-and-land.md](review-and-land.md).