A /dispatch skill for Claude to help it communicate with subagents. Put this in ~/.claude/skills/dispatch/ :

SKILL.md

name	dispatch
description	Use when dispatching one or more background subagents to do a substantial task, especially when fanning out parallel work. Injects a standard discipline preamble so agents keep externalized progress state (survives turn-budget cutoffs), use correct harness wait patterns, avoid stomping on peer agents, and always write a final report — even if incomplete.

Dispatch

Wraps subagent dispatch with a standard discipline preamble. The goal is that any agent you fan out, whether one or five, behaves predictably: it keeps state externalized, fails honestly, and leaves a trail even if cut off.

<when_to_use>

• Dispatching any subagent for non-trivial work (> 5 minutes of expected wall-time).
• Fanning out 2+ parallel agents, especially when they'll touch shared infrastructure (build.zig, build.zig.zon, flake.nix, mod.zig, etc.).
• Tasks where turn-budget cutoff is a realistic risk (dep integrations, cross-compile validation, multi-step debugging). </when_to_use>

<when_not_to_use> Simple one-shot queries ("summarize this file", "count foo in bar") — the overhead isn't worth it. Use Agent directly. </when_not_to_use>

The skill doesn't have a dedicated CLI; it's a prompt-composition discipline. When the user or the parent agent decides to dispatch, this skill's **Preamble** (below) gets prepended to the task prompt before it goes to `Agent(...)`. For parallel fan-outs, optionally use git worktrees per agent (see *Worktree isolation* below).

Preamble (inject into every dispatched prompt)

## Dispatch discipline (from /dispatch skill)

State externalization — MANDATORY

At the very start, create a progress doc at /tmp/dispatch-log/<slug>-progress.md with this template:

# <task> — progress log
Agent ID: <the id printed after spawn>
Started: <iso8601 timestamp>
Brief: <one sentence describing the task>

## Plan checklist
- [ ] <first concrete step>
- [ ] <second>
- [ ] ... (fill in before you start)

## Activity log
<append one line with timestamp + 5-15 words per meaningful step>

After every completed checklist item OR after every 5 tool calls (whichever first), re-write the file with updated checkboxes and append the new activity lines. If you hit a turn-budget cutoff, this file is the only trail we have — treat it as the most important output after the actual code.

Final report — MANDATORY, even if incomplete

Before you finish (whether success, partial success, or stuck), write /tmp/dispatch-log/<slug>-final.md containing:

- Status (done / partial / blocked)
- Where you stopped and why
- Files created/modified/reverted (with paths)
- Commits (with hashes) if any
- Before/after measurements if relevant
- What went wrong and pitfalls to warn the next agent
- Minimum next-steps for a retry

"I got 80% done and ran out" with a clear list is MUCH more valuable than a polished summary that papers over failures.

Harness wait patterns

• Long-running commands: use run_in_background: true on Bash, THEN wait for the completion notification. You are automatically told when a background task finishes — do not poll.
• Multiple events from a running process: use Monitor with a proper until loop that emits on every terminal state, not just success.
• NEVER use sleep N && tail ... — the harness explicitly blocks it.
• NEVER sleep to "wait for a build to finish" — use run_in_background.

Peer-agent coordination (for parallel dispatches)

If you suspect another agent is concurrently editing the same files:

• Never revert another agent's uncommitted work to clean your build. Stash your own changes, open a worktree, or wait — do not destroy theirs.
• If a build is broken by a peer's WIP, say so explicitly in the progress doc instead of silently fixing it. The parent will reconcile.
• If you're about to touch shared infra (build.zig, build.zig.zon, flake.nix, mod.zig), re-read the file IMMEDIATELY before each edit — version snapshots go stale under concurrent writes. Especially relevant for codescan replace_lines / insert_at which silently no-op on version mismatch.

Project skills — USE THEM

Before doing manual work, check if a project skill already solves it:

• fix-zig-deps-hash — any time you touch build.zig.zon and nix build complains about hash mismatch. Do not manually hash-loop.
• ship — for commit + push + CI-watching when work is done.
• zig-microbenchmarks — when adding a perf-sensitive path.
• Check Skill tool output at session start for the full list.

TDD discipline

For bugfixes and new features:

1. Write a failing test FIRST that expresses the expected behavior.
2. Run it, confirm it fails (if it passes, the test is wrong).
3. Write the minimal implementation to pass.
4. Run it, confirm pass.
5. Run the full ./test suite, confirm no regressions.
6. Only commit if all tests pass.

Exception: pure refactors under adequate existing coverage.

Honest-failure preference

A commit that says "I got to X, Y remains because Z" is always better than a commit that LOOKS done but isn't. If you can't make tests pass, don't commit; report what's broken. If you can't add a feature cleanly, don't half-add it; report why and what the clean path would be.

Time calibration

LLM wall-time ≠ human wall-time. Tasks that a human would estimate as "1-2 weeks" are often a single session for you. Don't pre-decide a task is too big — start, make progress, report where you got.

Coding standards (when touching this repo)

Refer to CLAUDE.md / AGENTS.md in the project root for project-specific conventions. Tabs over spaces (unless language forbids), #!/usr/bin/env shebangs, no extensions on executables, minimal comments (WHY, not WHAT), deterministic/seeded tests, no mocking of things under test.

Worktree isolation (for parallel fan-outs touching shared infra)

When dispatching ≥ 2 agents that'll each modify build.zig, build.zig.zon, flake.nix, or mod.zig, prefer giving each its own git worktree. The Agent tool supports isolation: "worktree" — use it.

Worktree rules baked into the preamble already handle the case where you did NOT use worktrees; but worktrees eliminate the coordination hazard entirely.

Post-dispatch review (for the parent agent)

After one or more agents complete, the parent should:

1. Read each agent's <slug>-final.md (small, bounded — safe).
2. Cross-check that final claims match the git log + file state.
3. For parallel dispatches, check whether any agent reverted another's work and whether that revert was intentional.
4. If an agent was cut off, spawn a summarizer on its JSONL transcript:

Summarize `/private/tmp/claude-.../tasks/.output`. Report what got built, what was reverted, where it stopped, and minimum next-steps.

(The summarizer's output fits in your context even though the raw JSONL would overflow.)

Slug naming

Use short, kebab-case, task-indicative slugs. Good: `libvpx`, `libtheora`, `tiff-ifd`, `pdf-streams`. Bad: `task-1`, `agent-2`, `foo`.

The slug appears in both progress and final doc paths and becomes the parent's primary handle for reviewing the work.