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)

# 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)

# 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 handoff
agent-toolkit swarm handoff create --type commit --from reviewer --to integrator --commit <sha> --branch <branch> --run-id <run-id>

# Auto behavior:
# - If an active handoff exists where to == from_role, it auto-completes (auto:true) and trace records handoff_completed.
# - Next role gets eager window (Waiting for handoff: <from> -> <to>) replaced by real prompt: export AGENT_TOOLKIT_SWARM_RUN_ID/RUN_DIR/REPO SWARMFORGE_ROLE + cd worktree && exec <runner> "$(cat prompt)"

Verify:

agent-toolkit swarm handoffs --run-id <run-id> --json | jq '.[] | {id,from,to,status,artifact,commit,auto}'
agent-toolkit swarm status --run-id <run-id> --json | jq '.trace | last'
# Expect: handoff create logs, worktree path, and runner exec with $(cat prompt)