| 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
- 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.
- 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.
- 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.
- Pick the lane. Foreground when you want to review + relay the result this turn;
background for long autonomous jobs that should notify on completion. Use a capable
model for risky/judgment-heavy runs.
- 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."
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
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 (nervepack's own metrics/maintain crons
are). A concurrent committer can otherwise sweep the agent's staged work into its own
commit (and push it) — a worktree off the committed base is immune — and two agents editing
the same files in parallel land on separate branches instead of colliding (resolve the
overlap by combining both, not picking a side). After it reports, verify on its branch
(tree clean, tests green, nothing on main), then you merge — FF or cherry-pick — keeping
the agent off main. See [[using-git-worktrees]].
Trust git ground truth, not the agent's report — it can edit the wrong checkout. Even
when told to work in a given worktree, a dispatched agent may edit the main checkout or
commit to main/an off-branch orphan while reporting "DONE, committed" with a plausible
SHA. After each agent, confirm where the change actually landed (git log --oneline,
git show <sha> --stat, git merge-base --is-ancestor <sha> HEAD) — never accept the
self-reported location. Wrong place? Reconcile, don't re-run — tag-backup / cherry-pick /
verify-identity / reset recipe: references/recovery.md. Pin the worktree path in the
dispatch and have the agent echo git rev-parse --show-toplevel before its first edit.
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).
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.
