opencode-skills-collection 4.0.44 → 4.0.46

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

@@ -0,0 +1,222 @@
+# Dispatch and poll
+
+`scripts/relay.mjs` is the dispatch layer. It wraps `cmd -p`, feeds it the brief on stdin, captures the
+NDJSON event stream, and writes a structured `result.json`. Your job collapses to: run one command,
+then read one file. Everything Command Code-specific lives in the helper, which is what keeps the loop
+portable across orchestrators.
+
+## Before the first run: check the binary
+
+Three gotchas, all worth 30 seconds:
+
+```bash
+command -v cmd        # `cmd` is a generic name — an alias or another tool can shadow it
+cmd --version         # the relay records this in result.json; confirm it is Command Code's
+cmd status            # must report authenticated (else `cmd login`)
+```
+
+On native Windows, use `cmdc`; `cmd` is the system shell. The relay launches the installed `cmdc.cmd`
+shim through `cmd.exe`, while the brief stays on stdin and variable argument values stay restricted to
+shell-safe tokens. Native Windows launch is contract-tested, but a live Command Code run is still
+unverified. `COMMANDCODE_BIN` remains an absolute-path override, including for `.cmd`/`.bat` shims,
+and must never point to `COMSPEC`.
+
+## 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 Command Code (default: current directory). It is the child's working directory — Command Code has no `--cd` of its own, and under `--yolo` it is a starting point, not a boundary. |
+| `--lane <name>` | Fleet lane from `delegate-setup` config. Applies that lane's dials; fails if the lane's `implementer` is not this relay. Explicit dial flags win. |
+| `--model <name>` | Model for this run, e.g. `vendor/model` (default: Command Code's own). `cmd --list-models` lists what your account can use. |
+| `--effort <level>` | Reasoning effort — `low` \| `medium` \| `high`, model-dependent. The relay accepts a bare token; Command Code and the model own the supported levels. |
+| `--read-only` | Withhold the write, edit, and shell tools: no `--yolo`, plus `--permission-mode plan`. For review and diagnosis, followed by a Git-visible `readOnlyViolation` tripwire. |
+| `--tools-all` | Also pass `--tools-all`, so no tool stays withheld. Ignored under `--read-only` — it does not lift the write gate. |
+| `--max-turns <n>` | Cap conversation turns (default: Command Code's own, 100). Command Code may exit 0 at the cap; when its complete result reports `max_turns`, the relay reports failure and exits 1. |
+| `--session <id>` | Continue one specific session by id (the `sessionId` from a prior `result.json`); send only the delta brief. Mutually exclusive with `--continue-last`. |
+| `--continue-last` | Continue the most recent session. "Most recent" is global, not per-repo, so an unrelated run can steal it — prefer `--session`. |
+| `--clean-env` | Pass only runtime basics (`PATH`, home, locale, temp, and Windows equivalents) to Command Code and its version preflight. This changes inherited variables only; it does not protect files or other same-user secrets. |
+| `--keep-env <name>` | Keep one additional variable under `--clean-env`; repeat for each required environment-backed credential, proxy, certificate, or MCP variable. The name must be set and use portable environment-variable syntax. |
+| `--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 private dir under the system temp dir). |
+
+Artifacts default to the system temp dir so relay-created files stay out of the target repository.
+On POSIX, that directory is mode `0700` and its files are created as `0600`. The touched-files report
+then shows Command Code's Git-visible edits without the helper's artifacts.
+
+`--clean-env` is not a security boundary: Command Code still reaches files and other same-user secrets
+through `HOME` (its own state lives in `~/.commandcode`) and OS facilities, and under `--yolo` there is
+no sandbox at all. Its login credentials are file-backed, so a `--clean-env` run stays authenticated;
+provider, proxy, certificate, or MCP settings that reference a stripped variable need it named with
+`--keep-env`. The same filtered environment is used for preflight and dispatch.
+
+## What the helper is doing
+
+```bash
+cmd -p --output-format json --skip-onboarding --no-auto-update -t --yolo [--tools-all] \
+    [-m <model>] [--effort <level>] [--max-turns <n>] < brief.txt          # fresh implementation run
+cmd -p --output-format json --skip-onboarding --no-auto-update -t --permission-mode plan …  # --read-only
+cmd -p … --resume <sessionId> < delta-brief.txt                            # exact-session rework
+cmd -p … --continue < delta-brief.txt                                      # most-recent fallback
+```
+
+The four constant flags earn their place: `--output-format json` is what makes the run machine-readable
+at all, `--skip-onboarding` stops the taste-onboarding prompt from blocking an automated run, `-t`
+auto-trusts the project so the trust prompt doesn't, and `--no-auto-update` keeps a background update
+from swapping the binary mid-run. The brief goes in on stdin, never in argv — Command Code's `-p` takes
+an optional query argument, so an unrecognized flag would be read as that query and the run would die
+with "too many arguments". Command Code waits at most 30 seconds for piped stdin; the relay writes the
+brief immediately.
+
+## The result
+
+`<out-dir>/result.json` is the contract. Fields:
+
+- `schema` — the result-format version (currently `delegate-relay.result.v1`)
+- `status` — `completed` | `failed` | `timeout` | `aborted` | `commandcode_unavailable`
+- `exitCode` — preserves Command Code's non-zero exit code; changes a zero exit with a complete non-success result to 1; uses `128` plus the signal number if the child was killed;
+  `127` if the binary 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`
+- `commandCodeVersion` — the binary that actually ran
+- `sessionId` — feed this to a later `--session <id>` (exact session; preferred) or `--continue-last`
+  (global "most recent", which another run can steal)
+- `finalMessage` — Command Code's own final report (the `<structured_output_contract>` you asked for),
+  lifted from `finalText` on a complete result line or recovered from the last `message_end` or
+  `text_delta`; recovered text may be partial or empty, and is written to `finalPath` only when non-empty
+- `resultLine` — how much of the tail survived: `complete`, `truncated`, or `absent`. See the
+  truncation section below; the four fields under it are null unless this says `complete`
+- `resultSubtype` / `stopReason` / `usage` / `durationMs` — straight from that result line: `success`,
+  `error`, or `max_turns`; why the turn ended; token counts; wall-clock
+- `touchedFiles` — `git status --porcelain` lines in the working root: your review starting point.
+  `null` (not `[]`) when git can't report — `git` missing, or a non-repo working root; `[]` means git
+  ran and the tree is clean
+- `readOnlyViolation` — only meaningful under `--read-only`: `false` when the Git-visible detector
+  saw no change beyond the relay's own artifacts; it does not cover ignored or outside-repository
+  paths. `true` when the detector saw a change, `null` when git couldn't snapshot either side.
+  `null` on write-capable runs, where the question doesn't apply
+- `autonomy` — the state the run actually got, in Command Code's terms (`--yolo …` or `plan …`)
+- `briefPath` / `eventsPath` / `finalPath` — the exact brief relay sent, the raw NDJSON event stream,
+  and the final-message file; `finalPath` is `null` when `finalMessage` is empty
+- `workdir`, `readOnly`, `toolsAll`, `model`, `effort`, `maxTurns`, `session`, `continueLast`,
+  `cleanEnv`, `keepEnv`, `startedAt`, `finishedAt` — `session` is the explicit session id, or `null`
+  for fresh and `--continue-last` runs; `keepEnv` records names only, never values
+- `stderrTail` — last ~20 stderr lines; present on every run that did not complete (`failed`,
+  `timeout`, `aborted`), absent on `completed`, `commandcode_unavailable`, and launch failures
+- `error` — present on a launch failure, on `timeout` and `aborted` runs, and when Command Code
+  reported a non-success result of its own
+
+The helper also prints a summary to stdout and exits with Command Code's exit code, so a wrapping
+script can branch on success/failure directly.
+
+## The tail is not reliable — read `resultLine`
+
+`cmd` ends a run with a `run_end` event that embeds the **entire conversation** — every tool call,
+its arguments, and its result — and then exits with `process.exit`, which discards whatever is still
+queued in its stdout pipe. On any run big enough to matter, the tail therefore arrives cut mid-write
+and the `result` line after it never lands. Successful live write runs have lost the result line,
+either truncating `run_end` or dropping the rest of the stream. A synthetic writer that exits the
+same way loses the stream down to whatever fits the OS
+pipe buffer, no matter how fast the reader is — so this is the CLI's flush behavior, not the relay's
+read speed (the relay batches its event-log writes precisely so it drains as fast as it can).
+
+What the relay does about it, and what it means for you:
+
+- Nothing load-bearing is read from the tail. `sessionId` comes from `run_start`, the **first** line of
+  the stream, so resume always works. The report is taken from the last `message_end`, falling back to
+  the streamed `text_delta`s of a message whose `message_end` was lost.
+- `resultLine` tells you which case you got. Under `truncated` or `absent`, `resultSubtype`,
+  `stopReason`, `usage`, and `durationMs` are `null` because the CLI never delivered them — not because
+  the run lacked them. The summary prints a note saying so.
+- `finalMessage` can still come back short or empty when the report itself was in the discarded
+  region. **The diff is the deliverable, not the report** — review `touchedFiles` and `git diff`, and
+  treat a thin report as missing information rather than as a failed run.
+- Read-only runs are small and usually keep a `complete` result line, so the second-opinion use is
+  unaffected.
+
+When a complete result line arrives, `status: "completed"` requires exit 0 and
+`resultSubtype: "success"`; any other subtype is reported as failed with exit 1. When the result line
+is truncated or absent, the relay falls back to the process exit code: exit 0 is completed and a
+non-zero exit is failed. In that fallback case, read `resultLine` and review the diff because the
+missing subtype cannot prove the task finished.
+
+## Waiting for completion
+
+The helper blocks until Command Code 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, or your shell's equivalent (`Start-Job` in PowerShell). 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 binary exits 127 but *does* write a `result.json` with status `commandcode_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: commandcode_unavailable` (exit 127):** the binary isn't on PATH. Install Command Code, run
+  `cmd login` (`cmdc login` on Windows), or set `COMMANDCODE_BIN`, then re-dispatch.
+- **an `error` mentioning `version preflight` (`failed`, or `timeout` at exit 124):** the bounded
+  `cmd --version` probe exited non-zero or hung past its cap (10s, or `--timeout` when shorter), so
+  Command Code was never dispatched; only the relay's own artifacts may already exist under
+  `--out-dir`. Check the install by running `cmd --version` yourself.
+- **`status: failed` at exit 3:** not authenticated. `cmd login`, then re-dispatch.
+- **`status: failed` at exit 5 or 10:** rate limited, or out of credits. Wait, lower the model tier, or
+  top up — the relay's summary names which.
+- **`status: failed` with `stopReason: max_turns`:** the run hit the turn cap mid-task. If Command Code exited 0, the relay exits 1; otherwise it preserves the non-zero child exit. The
+  tree may hold a half-applied change. Inspect it, then either raise `--max-turns` and re-dispatch, or
+  split the brief.
+- **`status: failed` at exit 0→1 with an `error` about subtype:** Command Code ended the run cleanly
+  without succeeding. The usual cause is a write-capable task dispatched `--read-only`, where the report
+  says the tools were refused. Re-dispatch without `--read-only`.
+- **`status: failed` otherwise:** read `result.json`'s `stderrTail` and the tail of `eventsPath`. Common
+  causes: an invalid `--model`, an unsupported `--effort` for the selected model, or a network lapse.
+  Fix the cause and re-dispatch; don't paper over it by doing the work yourself unless that's what the
+  user wants.
+- **`status: timeout`:** the `--timeout` watchdog killed the run. The working tree may hold a
+  half-applied change — inspect it before deciding between a longer `--timeout`, a smaller brief,
+  or a resume.
+- **`status: aborted`:** the relay itself was killed (its parent's timeout, a stopped task, a closed
+  terminal) and forwarded the kill to `cmd`. 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.
+- **`readOnlyViolation: true`:** the tripwire detected a Git-visible change during a `--read-only`
+  run. It cannot attribute a concurrent change to Command Code, but its read-only state is a permission
+  layer rather than an OS sandbox. Review the diff and report the warning before doing anything else.
+- **Empty `finalMessage`:** this is missing information, not a separate failure state. Read `status`
+  and `resultLine`; when the result line is truncated or absent, inspect the event log and diff before
+  landing.
+
+## Recovering lost work
+
+`events.jsonl` records every NDJSON line Command Code streamed, and its `run_end` event embeds the
+whole conversation — every tool call, its arguments, and its result. That makes the log both the map of
+what a lost run did and, for file writes, often a literal copy of the content it wrote. If finished work
+is lost — the run killed late, or the tree damaged afterward — read the event log before re-dispatching.
+The flip side of that completeness: the log contains whatever the run read or wrote, so treat it as
+sensitive as the repo itself, and note that it grows with the transcript (tens of KB for a trivial run,
+much more for a long one).
+
+## The commit boundary
+
+The helper never commits — by design, not omission. Under `--yolo` Command Code *can* write `.git`,
+which is the reason: a run that commits itself is a run you must unpick before you can review it. The
+robust contract is: Command Code edits the working tree, the orchestrator reviews and commits. See
+[review-and-land.md](review-and-land.md).

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

@@ -0,0 +1,81 @@
+# 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.
+
+With Command Code there's a fourth reason, and it's the strongest: an implementation run has no
+filesystem sandbox. Two concurrent `--yolo` runs in one tree can interleave writes to the same file with
+nothing arbitrating between them, and the resulting diff belongs to neither task. If you do need
+parallelism, give each run its own tree — `git worktree add` per task, or a container — rather than
+running two of them side by side in the same checkout. 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. Command Code has no memory of the earlier run, so a constraint that
+emerged in task 2 must be restated in task 5's brief or it won't hold. This is the queue equivalent of
+keeping briefs self-contained.
+
+(`--session` does carry one run's context into its own rework, but that's for reworking a single task —
+not a channel for handing task 2's discoveries to task 5. Each task in a queue gets a fresh dispatch.)
+
+## 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 Command Code made, non-blocking nitpicks, any write that
+  landed outside the brief's paths, 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.
+
+## Watch the per-task budget
+
+Each dispatch has its own turn cap (Command Code's default is 100; `--max-turns` overrides it) and its
+own `--timeout` if you set one. In a long queue those limits bite unevenly: the task in the middle that
+touches twenty files is the one that stops at `stopReason: max_turns` with a half-applied change. Size
+briefs so no single task needs the whole budget, and treat a capped task as an unfinished one — inspect
+the tree, then re-dispatch or split, rather than letting the queue move on past it.
+
+## 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/commandcode-delegate/references/review-and-land.md

@@ -0,0 +1,144 @@
+# Review and land
+
+Command Code 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.**
+
+One thing to add to the usual routine here: the run had no sandbox. An implementation dispatch goes out
+under `--yolo`, so "did it stay inside the brief's paths?" is a question you answer from `touchedFiles`,
+not one the tooling answered for you.
+
+## 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 Command Code'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:
+
+- **Out-of-scope writes** — this is the first check here, not an afterthought. Under `--yolo` there was
+  nothing stopping a write outside `--cd` or outside the paths the brief named. `touchedFiles` is a
+  `git status` review aid, not containment proof: it misses ignored files and anything outside the
+  repository. A worktree isolates the checkout but not the process. Use a container or another
+  OS-enforced boundary when writes outside the target tree are unacceptable.
+- **Scope creep** — did it 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? A `stopReason` of `max_turns` in `result.json` is a strong hint of a run that
+  stopped mid-task rather than finishing.
+- **Quiet judgment calls** — sometimes Command Code makes a defensible decision the brief didn't
+  anticipate. Don't just accept it because it looks reasonable; understand it and decide.
+- **A commit it made itself** — the brief forbids it, but nothing enforced that. Compare `HEAD` with
+  the pre-dispatch baseline, then inspect status, staged and unstaged diffs, and the intervening log.
+  If the whole range belongs to the run, `git reset --soft <recorded-baseline>` and review it as a diff.
+
+## 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 Command Code 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 Command Code 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 Command Code. This
+isn't a workaround for a missing feature; it's the deliberate boundary. Under `--yolo` Command Code is
+perfectly capable of committing, and that is precisely the problem: committing should be the act of the
+party that verified the work, and a self-committed run has to be unpicked before it can be reviewed.
+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 Command Code 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" --session <sessionId> --cd /path/to/repo
+```
+
+(`<skill-dir>` is this skill's install directory — see [dispatch-and-poll.md](dispatch-and-poll.md).
+`<sessionId>` is the field of that name from the prior `result.json`.)
+
+`--session <sessionId>` keeps the context from the first run, so a short delta is enough; use
+`--continue-last` only when no session id came back, since "most recent" is global and another run can
+steal it. 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** Command Code 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.
+- **Report any write outside the brief's paths**, and any `readOnlyViolation: true` on a read-only
+  dispatch, even when the change itself looks harmless. Those say something about the run's containment,
+  which is the human's call to weigh, not yours to normalize.
+- **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 Command Code'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/commandcode-delegate/references/writing-the-brief.md

@@ -0,0 +1,147 @@
+# Writing the brief
+
+A brief is the entire task as Command Code will see it. It 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 the repo's own `AGENTS.md`, which it picks up
+automatically, and any skills it discovers there).
+If a constraint isn't in the brief or discoverable in the repo, it doesn't exist for Command Code. The
+single most common failure is a brief that assumes context it doesn't have.
+
+## The shape that works
+
+Command Code 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 Command Code
+from wandering into unrelated refactors.
+</task>
+
+<verification_loop>
+Run these before finishing and fix anything they surface, don't just report it:
+  <the project's real test command>
+  <the project's real lint/format command>
+  <the project's real build/typecheck command>
+Confirm the working tree shows only the intended changes afterward.
+</verification_loop>
+
+<action_safety>
+Keep changes scoped to the task. No unrelated refactors, renames, or cleanup unless required for
+correctness. Do NOT run git add or git commit — the orchestrator commits after reviewing. Leave the
+work uncommitted in the working tree.
+</action_safety>
+
+<structured_output_contract>
+End with a report in this exact shape:
+  1. What changed and why
+  2. Files touched
+  3. Gate outcomes (paste the test/lint counts)
+  4. Anything you deviated on, left open, or want a decision on
+</structured_output_contract>
+```
+
+That four-block skeleton covers most implementation tasks. Reach for the extra blocks when the task
+profile calls for them:
+
+- **Debugging / open-ended fixes** — add `<completeness_contract>` (resolve fully, don't stop at the
+  first plausible fix) and `<missing_context_gating>` (don't guess missing repo facts; find them or
+  state what's unknown).
+- **Review / diagnosis (read-only)** — add `<grounding_rules>` (ground every claim in evidence; label
+  inferences) and run with `--read-only` so the write, edit, and shell tools stay withheld.
+- **Research / recommendations** — add `<research_mode>` (separate observed facts, inferences, open
+  questions).
+
+## Path discipline is scope guidance
+
+An implementation run goes out under `--yolo`, which means no filesystem boundary: Command Code can
+write anywhere the process can reach, not just under `--cd`. Name the files or directories it may
+change, say plainly that everything else is off limits, and keep `<action_safety>` in every
+write-capable brief. That is guidance, not a sandbox. A worktree isolates the checkout but does not
+contain the process; use a container or another OS-enforced boundary when writes outside the target
+tree are unacceptable. `touchedFiles` is only a review aid: it cannot show ignored files or writes
+outside the repository.
+
+## `git commit` is not blocked, only forbidden
+
+Sibling delegates can rely on a sandbox refusing to write `.git`. This one cannot: under `--yolo`,
+Command Code can commit, so the brief has to tell it not to. Record `HEAD` before dispatch and keep the
+"do NOT run git add or git commit" line. If `HEAD` changed, inspect status, staged and unstaged diffs,
+and the intervening log first. Only after confirming the whole commit range belongs to the run, use
+`git reset --soft <recorded-baseline>` so you can review that range as a diff.
+
+## Discover the real gates — don't hardcode
+
+`<verification_loop>` is only useful if it names the project's *actual* commands. Read the repo's
+`AGENTS.md` / `CLAUDE.md` / `Makefile` / `package.json` first and copy the real ones in (`make test`,
+`npm run lint`, `cargo test`, `pytest -q`, whatever it is). A brief that says "run the tests" without
+naming them gets you an implementer that guesses — or skips.
+
+## Honor the repo's conventions
+
+Command Code reads the repo's `AGENTS.md` automatically, so house rules there (style, forbidden
+patterns, commit conventions) already apply. If the project forbids certain things in code — say,
+spec/ticket IDs in comments, process language like "MVP"/"for now"/"phase N", or specific test
+conventions, whatever the repo's own conventions ban — restate the load-bearing ones in the brief too,
+because compliance is only as reliable as what's in front of it.
+
+## One task per brief
+
+Keep each brief to a single, bounded job. "Review this, fix what you find, update the docs, and
+suggest a roadmap" produces a muddled run; split it into separate dispatches. One brief → one run →
+one commit keeps review and rollback clean, and lets a later task assume the earlier one landed.
+
+Turns are capped (Command Code's own default is 100; `--max-turns` changes it). A brief bundling four
+jobs is also the brief most likely to hit that cap and stop mid-way, reported as `stopReason:
+max_turns` with a half-finished tree.
+
+## 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.
+
+## Expect environment preamble in the reply
+
+The final message may carry environment noise on top of your requested report — a banner injected by
+the repo's `AGENTS.md`, extra text from an MCP server or skill you have configured locally, taste
+notes from Command Code's own learning. That comes from your setup, not a relay defect. The
+`<structured_output_contract>` is your defense: ask for a clearly delimited report section so you can
+find the real output regardless of what wraps it.
+
+## 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, and do not write outside services/billing/.
+</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)).