swarm-handoff

# Swarm Handoff Create correct file handoffs between swarm roles so work moves via **Git + filesystem**, not chat copy. Every writer gets an isolated worktree/branch; the filesystem `state.json` is authoritative. ## When to use - The swarm needs to move work: implementer → reviewer → integrator (or any `from -> to`). - User asks to "hand off", "delegate", "send artifact", or "promote". - After `swarm-observer` diagnoses a stuck `active` handoff. ## Prerequisites - Run exists: `.agent-toolkit/swarm/runs/<run-id>/state.json`. - Artifact file lives under the repo (prefer `artifacts/`). For `commit` type, commit/branch must exist locally. - Know `from` and `to` roles from the recipe (`pair`: implementer→reviewer; `team`: implementer→reviewer→integrator). ## Workflow ### 1. Prepare the artifact (file handoff is preferred) ```bash # Artifact — by convention in artifacts/ mkdir -p artifacts cat > artifacts/<name>.md <<'EOF' # Context for <to> - What was implemented and why - Files changed and how to verify - Risks / open questions EOF git add artifacts/<name>.md # optional, but keeps history # Commit handoff — use when work is already committed git log --oneline -n 5 git branch --show-current ``` ### 2. Create the handoff (CLI owns state) ```bash # Artifact handoff — triggers auto-provision of <to>'s worktree/tab + agent agent-toolkit swarm handoff create --type artifact --from implementer --to reviewer --artifact artifacts/cna-ideas.md --run-id <run-id> # Commit handof...