Np Core Dispatch

---
name: np-core-dispatch
description: Send a task or a handoff to a fresh agent and supervise it. Use when you want another agent to carry out work — executing a [[np-core-handoff]] doc, running a long/risky job, or parallelizing — especially when you tried to "continue" a previously spawned agent and the SendMessage capability isn't available in this environment. Covers the spawn-fresh-with-context fallback, scoping, stop-points, and verification. The dispatch half of the continuity pair with [[np-core-handoff]] (handoff writes the doc; dispatch sends it).
---

# dispatch — send work to a fresh agent

`[[np-core-handoff]]` writes the doc that lets a context-free agent continue. **This
skill sends it.** Use it whenever the next move is "have an agent go do this."

## The SendMessage gotcha (why this skill exists)

Some harnesses expose a way to *continue a previously-spawned agent* (often
`SendMessage`, keyed by agent id) — and it is **frequently NOT available**: the spawn
returns an id, but no tool to message it back exists. Don't get stuck trying to reach
the warm agent. **Fallback (always works): spawn a FRESH agent with the full context**
— pointed at the handoff doc (or handed the same brief inline), it rebuilds context
from the doc and is equivalent to continuing the original. Don't block on a
continuation channel that isn't there.

## How to dispatch well

1. **Hand it a handoff, not a vibe.** Either pass a `[[np-core-handoff]]` doc path or
   inline an equivalent brief: objective, state (done/in-flight/blocked), the next
   concrete step, suggested skills, and references by path. Self-contained = succeeds.
2. **Scope it.** Say exactly what to do and what NOT to do. For multi-step work, name a
   **stop-point**: "execute steps 1–5, then STOP and report before the irreversible
   step 6." A clear stop-point is how you keep a risky run reviewable.
3. **Carry the conventions in the prompt** (a fresh agent doesn't inherit them):
   sync first (`[[np-core-sync]]`), explicit-path `git add` (never `-A`), author as
   the repo's configured git identity (never a bot) with **no LLM-attribution trailer**, validate-don't-assume, redact secrets
   (pull fresh via [[np-env-secrets-refresh]] — never inline them). Tell it to STOP and
   report on a dirty/diverged tree rather than force anything.
4. **Pick the lane.** Foreground when you want to review + relay the result this turn;
   background for long autonomous jobs that should notify on completion. **Tier the model
   to the phase:** strongest for spec/design authorship, smaller (Sonnet, or Haiku for
   mechanical steps) once the plan is approved and the work is execution or testing.
5. **Verify the result yourself.** Treat the agent's report as a claim — independently
   re-check the key invariants (tree clean, tests/doctor green, nothing pushed public)
   before you trust "done."
6. **Run a retrospective before calling it done.** After verification, ask: what did the
   dispatched agent (or you, supervising) assume that turned out wrong, and what corrected
   it? Capture silent mid-run corrections (a wrong guessed path, a stale checkout, a bad
   sample) via [[np-core-contribute]], not just things that visibly broke — those are
   exactly as valuable and easier to lose once the session ends.

## When a dispatched agent stalls — salvage, don't re-dispatch

A backgrounded agent can die (watchdog stall, "no progress for ~600s") with the
implementation done but **uncommitted** — it typically stalls during final verify, not
mid-edit. Inspect its worktree first (`git -C <worktree> status` / `diff <base>`); if
the diff is sound, finish it yourself — salvage beats restart. Re-dispatch only if the
worktree is empty or the work is unsound. Full recipe: references/recovery.md

When the deaths are **systematic** — the same transient infra error (a stream/idle-timeout
storm) killing agent after agent, not a one-off stall — stop feeding the long role to
dispatch: implement as controller yourself and dispatch only the shorter, **read-only
review** subagent (which finishes far more often). A recurring fault is a signal to change
the execution model, not to keep re-dispatching the role that keeps dying.

**A subagent's claim about a *review* is not a verdict.** An implementer can come to rest
narrating "the review passed" — it can't see the reviewer you dispatched separately. Act
only on the reviewer's actual report or your own controller-side diff review. A
**read-only** reviewer orphaned by a session exit wrote nothing — safe to abandon; just
confirm its target work landed another way. When another agent also runs subagent-driven
work here, the shared `.git/sdd/` state files (`progress.md`, `task-N-brief.md`) collide —
use uniquely-named ledger/brief files, never mass-write the shared ones. See
[[np-flow-merge-gate]].

## Isolate with a worktree when the tree is shared

Dispatch repo-editing agents with **`isolation: "worktree"`** whenever an auto-committing
cron or another session may be active in that tree. A worktree off the committed base
prevents staged-work sweeps; parallel edits land on separate branches (combine both, don't
pick a side). After it reports, verify on its branch, then merge — keeping the agent off
`main`. See [[using-git-worktrees]].
Tasks that are independent by file list can share ONE worktree: rules in
references/parallel-one-worktree.md.

**Trust git ground truth, not the agent's report — it can edit the wrong checkout.**
After each agent, confirm where the change actually landed (`git log --oneline`, `git show
<sha> --stat`). Wrong place? Tag-backup / cherry-pick / reset: references/recovery.md.
Pin the worktree path in the dispatch; have the agent echo `git rev-parse --show-toplevel`
before its first edit.

**When worktrees are impractical:** share one safely with disjoint file lists — give each
agent an explicit, non-overlapping set of files, forbid `git add` inside tasks, and put
every cross-task contract in the plan up front. Full recipe + sweep mechanics:
references/worktree-isolation.md

## Verify the whole plan, not just each task

Green per-task reviews don't mean the plan is done. A task can be silently **skipped**
when an earlier commit made a superficial one-line touch to the file it was meant to
substantively change — a false "done" no per-task review catches, since each sees only
its own diff. The net is a **whole-branch review**: one fresh, most-capable-model pass
over the full diff *against the spec*, told to hunt the missing consumer / unwired
write-path — not just critique what changed. Never skip it, even when every task came
back clean (it has caught a silently-skipped migration that per-task reviews passed).

## Put what you just learned into the brief

- **Let it flag out-of-scope findings** ("flag related issues you can't fix") — otherwise
  it either swallows them or scope-creeps.
- **Pre-bake a just-hit failure.** Task N tripped a pitfall and N+1 uses the same
  machinery? Fold that symptom/cause/fix into the next brief — "we hit this five minutes
  ago" lands where an abstract warning doesn't.
- **Creative/editorial work needs a stricter brief:** what to say, what may be edited
  (name the generated files that must NOT be), voice skills, publication gate.
  references/creative-brief.md
- **Runbook first for migrations/cutovers** — explicit commands, fail-open guards,
  rollback paths — then hand it over via [[np-core-handoff]]. **Stop at the guardrail:**
  lacking live access it must halt and name what's needed, never route around it.

## Not this

- A persistent message bus or agent-to-agent chat — this is one-shot dispatch +
  supervise, not a protocol.
- A replacement for doing small work inline. Dispatch when the work is large, risky,
  parallel, or genuinely better in a fresh context — not to avoid a two-line edit.