# 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).

# 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.

# 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).

# 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)).