repo-mailbox/skills/dispatch/SKILL.md

---
name: dispatch
description: >-
  Turn "start a session in repo X, on order Y, at cost Z" into a complete,
  verified startup command — the prompt written to a file, the model and effort
  derived from the rubric, and the output form chosen by whether the target repo
  already has a terminal pane. Use whenever work is being handed to a session in
  another repo, or to this repo's own next session: "dispatch a session in repo
  X", "start a session there with this order", "give me the startup command for
  repo Y", "hand this work to <repo>", "write the plan file for that session",
  "open a tab for X with this task", "how do I launch the next session on this".
  Also triggers on Norwegian phrasings: "dispatch en økt i repo X", "start en økt
  der med denne ordren", "gi meg oppstartskommandoen for Y", "send arbeidet til
  <repo>", "skriv planfila for den økten", "åpne en tab for X med denne
  oppgaven", "hvordan starter jeg neste økt på dette". Also covers the
  background form, where the dispatching session starts the child itself with
  `claude --bg`: "start it in the background", "run that as a background
  session", "launch a bg session on this order", "start en bakgrunnsøkt i repo
  X", "kjør det i bakgrunnen", "start barnet selv". Trigger even when no tool
  is named — producing a runnable startup command for another session IS this
  skill. Not for choosing WHICH repo deserves the next session (that is `board`),
  not for scoring model and effort alone (that is `route`), and not for sending a
  message to another repo (that is `coord-send`).
version: "0.35.0"
---

# dispatch — hand a session a task it can actually start on

A dispatch is one line the operator pastes and one file that line reads. Both
halves are easy to get wrong in ways that look right: a command with no prompt
in it, a plan file the driver silently discards, a `--no-go` that does not stop
what everyone assumed it stopped. All three were measured on 2026-08-16 — four
separate misfires in one day, by two different repos — and this skill exists so
they are not re-derived a fifth time.

**In the paste and plan-file forms you produce the command and never run it.**
Starting a session in another repo spends the operator's quota and takes an
action inside a repo this session does not own. Hand back the finished command
and stop. The one exception is **the background form** (its own section below):
since the operator's decision of 2026-09-22 the PM starts sessions itself with
`claude --bg`, and that form is run, not handed over.

## The engine

    ORDER="${CLAUDE_PLUGIN_ROOT}/scripts/coord-order-send.sh"
    BOARD="${CLAUDE_PLUGIN_ROOT}/scripts/board.sh"

    "$ORDER" --to <name> --subject "<one line>" --prompt-file <absolute path>

    "$BOARD" --dispatch --repo <name> \
             --order-id <the id the order engine printed> \
             --target-pane <yes|no> \
             --path <known|partial|undetermined> \
             --verification <strong|weak|none> \
             --reversibility <cheap|costly|one-way> \
             --scope <local|multi-file|cross-cutting> \
             --rationale "why these four scores"

It writes nothing and prints one block. Exit 2 means it refused — read stderr
and fix the call; every refusal is a case where a command would have been wrong
rather than merely imperfect.

It is `board.sh` and not a script of its own because the block format
(`tab=`/`repo=`/`dir=`/`command=`/`paste=`) has exactly one generator. Two
emitters of one file format is the drift defect this repo's CLAUDE.md warns
about.

## The five steps, in order

### 1. Write the prompt file

The order goes in a file, in plain prose:

```bash
mkdir -p "$HOME/.claude/dispatch"
PF="$HOME/.claude/dispatch/<repo>-$(date -u +%Y%m%dT%H%M%SZ).prompt"
```

Write the whole order: the concrete task, which discipline applies (Iron Law,
TDD, which file the test goes in), and what must **not** be triggered. A prompt
that says only "continue" forces the receiving session to guess its task out of
STATE.md, which is the thing handing over a prompt is supposed to prevent.

Norwegian prose, `æøå`, quotes, `$` and backticks are all fine in the file. That
is measured, not assumed: the order body never passes through a shell.

### 2. Deliver it into the recipient's order queue

```bash
"$ORDER" --to <repo> --subject "<one line naming the task>" --prompt-file "$PF"
```

It prints `order-id=<id>`. **That id is the whole handle from here on.**

This step is what makes a dispatch survive the pane it was typed into. The
prompt file is scratch: it carries the order to one session and nothing records
it afterwards. Measured 2026-08-17: an order was dispatched three times over
90 minutes before it was worked, because the first two tabs ran something else
and the order left no trace anyone could find. In the queue it stays pending,
is re-injected at every session start in that repo, shows up in `board`'s ORDRE
column, and is closed only by a session that claims and finishes it.

The queue is `~/.claude/coord/<repo>/orders/` — the same private local
infrastructure as the mailbox, and a **different channel** from it. Mail is
untrusted cross-repo data that can never instruct a session; an order is
operator-authorized work. Never send an order as a `coord-send` message and
never send a message as an order.

`--to` refuses what `coord-send` refuses: `_`-prefixed names, path traversal,
and the retired `ktg-plugin-marketplace` address (send to `catalog`).

### 3. Measure whether the target already has a pane

```bash
morning --probe-panes | grep "<absolute dir of the target repo>"
```

A hit means `--target-pane yes`. **Measure it; never assume it.** This is the
one input `--dispatch` refuses to default, for the same reason `route.sh`
refuses to default `--last-effort`: it is a fact about the world, and guessing
it produces a dispatch that verifies green and opens nothing.

Two facts about this measurement, both verified 2026-08-16 against the installed
`morning`:

- `--probe-panes` **works from a Claude session**, without a tty. It cannot
  identify the anchor pane, but the `DIR` column — the part you need — is there.
- A session dispatching **its own next session** is always `--target-pane yes`.
  That is not a special case for one repo; it is what self-dispatch is, and it
  is where all four of the day's misfires landed.

### 4. Score the four traits and call `--dispatch`

Scoring is judgement and it is yours; the model and effort are a lookup and are
`route.sh`'s. Score the task **the dispatched session** will do,
using the `route` skill's trait table.

Pass `--order-id <id>`, not `--prompt-file`. The emitted command is then a thin
**starter**: it carries no order text at all, only the id and the four steps
the receiving session runs (claim, compare against STATE's NESTE, execute,
close). The order text has exactly one home, and a copy in argv would be free
to drift from it and would die with the pane. `--dispatch` refuses an
`--order-id` that is not in the target's pending queue — the same rule as the
empty prompt file, one level up.

`--prompt-file` still works and is the fallback when there is genuinely no
queue to write to. Passing both is refused: the session would be told two
things.

`--dispatch` deliberately takes no `--model`/`--effort`. The rubric is a policy
with exactly one copy, and a dispatch that took the model directly would be a
second, unscored way to reach the same decision — one that records no traits, no
rationale and no `next-cost`, so nothing afterwards could say whether the
routing or the scoring was wrong. Score the traits and let the lookup spell the
command. If the right call is a Fable row, the rubric cannot produce it: write
that command by hand and say in the handover that it is a recorded override.

**No `--advisor` is emitted, by the rubric or by this skill.** That rule was
struck 2026-09-12 on a measurement — 0 of 54 dispatches carried the flag. The
advisor is an operator decision per session; do not add one to a dispatch
command.

### 5. Verify, then hand it over

**`--target-pane no` (plan-file form).** Write the whole output to a file and
dry-run it:

```bash
"$BOARD" --dispatch ... > "$HOME/.claude/dispatch/<repo>-<ts>.plan"
morning --plan-file "$HOME/.claude/dispatch/<repo>-<ts>.plan" --dry-run
```

Expect `opening: 1 of 1`. Then hand back:

    morning --plan-file <path to the plan file> --no-go

**Know what that dry-run does not prove.** It proves the block parses and yields
a command. It does *not* answer the pane question: run from a Claude session
there is no tty, so `morning` reports `window: unknown ... assuming an empty
window` and `plan_drop_open` never fires. A gate built on the dry-run would pass
the self-dispatch case every single time — the one case it would exist to catch.
Step 2 is the measurement; this is a parse check.

**`--target-pane yes` (paste-only form).** There is no plan file, deliberately:
`morning`'s `plan_drop_open` (morning:1788) drops a block whose repo already has
a pane. Hand back the `paste=` line, and say it goes in the existing tab **after
`/exit`**. Never prefix it with `cd` — one repo per terminal tab, and the
operator is already standing in that one. `morning --relaunch` bypasses the
filter but opens a *second* tab beside the existing one, which is rarely wanted.

## The background form

**When:** the PM starts the child session itself (operator decision
2026-09-22, `~/.claude/docs/2026-09-22-tos-bakgrunnsoekter-og-natt.md`). Not
when the operator is to paste a line into a tab. That is still steps 3–5
above. The background form replaces steps 3–5 only. Steps 1–2 are unchanged:
the order goes into the recipient's queue first, and the id is the handle.
There is no pane question, because a background session has no pane.

The command, run by the dispatching session through its Bash tool:

```bash
cd <absolute repo dir> && claude --model <m> --effort <e> --disallowedTools AskUserQuestion,SendMessage,ListAgents --bg --name <short-name> "<starter>"
```

- **`--model` directly after `claude`, always.**
  `~/.claude/hooks/pre-dispatch-budget.sh` counts a start only in that position.
  Measured 2026-09-22: `claude --model … --bg --name x` is counted, but a flag
  with a value in front of `--model` breaks the pattern and the start goes
  uncounted. The form must not depend on the hook learning more forms. Take the
  model and effort from `route.sh`'s `command=` line (score the traits as in
  step 4). That line already begins `claude --model <m> --effort <e>`, so
  appending the rest keeps the order by construction. A Fable override is
  written by hand, in the same order.
- **`--disallowedTools AskUserQuestion,SendMessage,ListAgents`** (hardening T4,
  `~/.claude/docs/2026-09-22-herding-s1-steg4.md` § 3). A background child
  cannot be answered. `AskUserQuestion` was open and stopped two sessions
  before this guard existed. `SendMessage`/`ListAgents` close the child→PM
  direction. The PM's own messages to the child are still delivered.
- **The `cd` is right here, and only here.** The no-`cd` rule is for a line
  pasted into a terminal tab, where the operator already stands in the repo.
  This line is run by a session standing in another repo, and `claude --bg`
  starts in the working directory, so the `cd` is what picks the repo.
- **`--name`**: a short name (`<repo>-<topic>`), so `claude agents` and
  `claude logs <id>` can be read at a glance.

The starter is **one line of ASCII, with no `$`, backtick or double quote**.
It sits inside the double quotes above and is evaluated by the shell, exactly
like `board.sh`'s thin starter. `<PLUGIN_ROOT>` is the absolute install
directory the engine lines at the top of this skill resolve to (the parent of
`dirname "$ORDER"`, e.g. the version-pinned plugin cache). Write it out in
full, because a child executes the starter literally and the order verbs are
not on PATH (ORDRE 65).

```text
ORDRE <id> ligger i dette repoets ordrekoe. Gjor dette i rekkefolge: (1) claim den - bash <PLUGIN_ROOT>/scripts/coord-order-claim.sh --repo <repo> <id> - claim skriver ut hele ordreteksten. FULL STI ER MED VILJE. Claim KUN denne ordren. (2) Sammenlign mot STATE.md NESTE og uttal avviket i ditt FORSTE svar. (3) Du er en bakgrunnsoekt isolert i en NY worktree: sett grenen din til <hash> (git checkout -B <gren> <hash>) og verifiser. Commit paa den grenen, ingen fletting, INGEN push/tag/release - operatoren pusher. Du kan ikke stille spoersmaal; ved et teknisk valg, ta det anbefalte og skriv valgt X fordi Y. Lange kjoringer i forgrunnen, aldri arm venter. (4) Lukk med bash <PLUGIN_ROOT>/scripts/coord-order-done.sh --repo <repo> <id> --commit HASH - eller --return --reason. (5) Rapporter til <sender> med bash <PLUGIN_ROOT>/scripts/coord-send.sh --from <repo> --to <sender> - gren, hasher, roed til groenn, selftest-tall.
```

- **`--repo <repo>` on both verbs, always.** A background child runs in a
  worktree, and without `--repo` the verbs derive their identity from the git
  toplevel's basename. That basename is the worktree's name, not the repo's.
  Measured 2026-09-23: a claim made before the worktree won. The close made
  inside the worktree exited 1 with `no claimed order … for <worktree-name>`,
  and the order stayed in flight.
- **`--from <repo>` on the report, by full path.** `coord-send` derives its
  sender from the same toplevel basename, so the report was signed with the
  worktree's name (measured on 741ada8: `from: dispatch-bg-form`, a mailbox no
  session holds). Since 0.36.0 `coord-send` refuses a sender derived inside a
  linked worktree, so a starter without `--from` now fails loudly instead of
  delivering, but the starter must still say it: the child executes it
  literally.
- **`Claim KUN denne ordren`** stays in even when the queue holds only this
  one. Another order can land between the dispatch and the child's first turn.
- **`<hash>` is the commit the child must build on, not automatically `main`.**
  If the repo tracks STATE.md/PLAN.md and the newest of those commits sits on a
  branch that has not been merged, the hash is that branch's tip. Measured
  wrong 2026-09-23: `d5a6bac` was given where `8bd27d8` was meant.
- **`INGEN push/tag/release`**: the child commits on its branch and stops. The
  operator's push round merges, pushes, and runs `release-plugin.mjs`.

**Measured platform facts** (agent-view docs + 2026-09-22): a background
session is forced into its own worktree. It cannot write in the main checkout,
not even after `ExitWorktree`. It never merges. That is why the starter pins
the branch and forbids the merge rather than asking for either.

**What happens afterwards, and it is the PM's:**

1. **Watch the order, not the process.** The child's claim moves the order to
   `~/.claude/coord/<repo>/orders/claimed/<id>.md`. Closing moves it to
   `orders/archive/<id>.md` (executed), or back to `orders/<id>.md` (returned,
   with the reason written into it). `claude agents` / `claude logs <id>` show
   the session. The file shows whether the work reached a terminal state.
2. **Re-measure on the commit.** Read the `commit=` the child wrote into the
   archived order. Then run that repo's suites at that hash yourself. The
   child's report is a claim, not a measurement.
3. **The merge is the operator's.** The branch waits for the operator's push
   round, which merges, pushes and releases. A background child never does
   any of the three.

**Why this is not a `board.sh` rendering.** `board.sh --dispatch` is the one
generator of the plan-block format (`tab=`/`dir=`/`command=`/`paste=`), and
this form uses none of it. There is no block, no pane and no `morning`
consumer. The one generated part, model and effort, already has its single
generator in `route.sh`. So `--target-pane` stays exactly `yes|no`, and the
selftest pins that. Stated overlap: steps (1), (2) and (4) of the starter
repeat the protocol in `board.sh`'s thin starter. If the protocol changes,
both copies must move together.

## Three things that must reach the operator

Say these in the handover, not only in the plan file. Each was a real
correction, not a hypothetical:

1. **The command carries the prompt in argv.** `claude --model X --effort Y` on
   its own is not a dispatch; it is a session waiting for someone to tell it
   what to do. Delivered bare twice on 2026-08-16, corrected by the operator
   with "gi meg alltid komplette oppstartskommandoer for nye sesjoner".
2. **`--no-go` does not make the session wait.** It suppresses only the
   follow-up Go message — `morning:806` is exact: "--no-go says nothing is typed
   once the startup command is in". The startup command, prompt and all, is
   typed regardless, so the dispatched session starts working on its own. An
   operator decision was once taken on the opposite premise and had to be
   corrected before the run.
3. **Which form you produced, and why.** "Plan file, because `<repo>` has no
   pane" or "paste line, because `<repo>` already has one and a plan block for
   it would be dropped". The form is a consequence of a measurement, and the
   operator should be able to see the measurement.

## What happens at the far end

The dispatched session claims the order and owns it until it closes it:

```bash
coord-order-claim <id>                       # atomic; exactly one session wins
coord-order-done <id> --commit <hash>        # executed, with a result pointer
coord-order-done <id> --no-commit --reason "<why>"
coord-order-done <id> --return --reason "<why>"   # back to the queue, with the reason
```

The claim prints the order and tells that session to compare it against its own
STATE.md NESTE block and to **state any divergence in its first reply**. That is
the point of the D-check: a dispatch that displaces a live next step is a
decision, and it should be an uttered one rather than a silent one.

If the tab is never run, nothing is lost. The order sits pending, the next
session in that repo sees it at startup, and `board` counts it in ORDRE.

## Where a dispatch is still not enough

An order is a task. When what the other repo needs is a *notice* — something is
fixed, a premise changed, a question needs answering — that is `coord-send`, not
a dispatch. The test is whether you are asking for work to be done (order) or
telling them something they must decide what to do with (mail).