SwarmForge Handoff Message Types: The Two-Type Protocol Explained

SwarmForge defines exactly two handoff message types — git_handoff and note — for agent-to-agent communication in multi-role development workflows.

The SwarmForge framework, an open-source multi-agent orchestration system developed by Bob Martin ("Uncle Bob"), uses a strictly limited handoff protocol to coordinate work between specialized roles. Unlike general-purpose message queues, SwarmForge enforces a minimal, auditable communication surface. This article explains how the two handoff message types in SwarmForge function, when to use each, and how the system validates them.

The Two SwarmForge Handoff Message Types

All inter-agent communication in SwarmForge centers on two message types defined in swarmforge/handoff-protocol.md. The validation script swarmforge/scripts/swarm_handoff.sh rejects any other values for the type header.

git_handoff: The Primary Work Handoff

git_handoff moves committed code downstream through role chains. When a role completes its inbound task, it forwards this message type to the next role in its pack (two-pack, four-pack, six-pack, etc.) or broadcasts to all roles for terminal operations.

Required headers for git_handoff:

Header	Purpose
type	Must be git_handoff
to	Recipient role name(s)
priority	Integer priority value
task	Associated task identifier
commit	Git commit hash to merge and process

The system automatically injects reserved headers including id, from, role, and created_at.

Example git_handoff header block:

type: git_handoff
to: cleaner
priority: 50
task: task-1-cave-setup
commit: a1b2c3d9e8

To create and validate:

# Save draft to ./tmp/handoff.txt, then run:

swarm_handoff.sh ./tmp/handoff.txt

note: Restricted Informational Messages

note carries short, free-form messages that are not git-based work items. The protocol explicitly restricts notes—they are only permitted when directed by the role prompt, constitution, or operator.

Required headers for note:

Header	Constraint
type	Must be note
to	Recipient role name(s)
priority	Integer priority value
message	Single line, maximum 80 characters

Example note header block:

type: note
to: architect,QA
priority: 70
message: Waiting on QA result before merging cleanup branch.

Validation follows the same path:

swarm_handoff.sh ./tmp/handoff.txt

How SwarmForge Enforces Handoff Message Types

The validation layer lives in swarmforge/scripts/swarm_handoff.sh. This script parses the type header and hard-rejects any value other than git_handoff or note. This enforcement ensures:

• Auditability: All work handoffs trace to specific git commits
• Simplicity: Agents cannot invent ad-hoc communication patterns
• Determinism: The downstream processing logic in swarmforge/scripts/handoffd.bb (the delivery daemon) and swarmforge/scripts/ready_for_next.sh (task selection) assumes only these two shapes

The helper library swarmforge/scripts/handoff_lib.bb provides read/write primitives used by both the validator and the handoffd daemon. When handoffd delivers files to recipient inboxes, it relies on the validated type field to determine routing behavior and tmux wake-up notifications.

Choosing Between git_handoff and note

Use this decision framework based on the SwarmForge protocol specification:

Scenario	Correct Type
Committing completed work for next role to merge	git_handoff
Broadcasting final status to all pack roles	git_handoff
Explicitly instructed by prompt/constitution/operator to send status	note
General chatting, questions, or unsolicited updates	Neither — prohibited

The protocol's strictness prevents conversation drift. Agents that attempt unauthorized note messages fail validation at swarm_handoff.sh before ever reaching the delivery daemon.

Summary

• SwarmForge handoff message types are strictly limited to git_handoff and note as defined in swarmforge/handoff-protocol.md
• git_handoff moves git-committed work through role chains with required headers: type, to, priority, task, commit
• note sends 80-character informational messages only when explicitly authorized, with headers: type, to, priority, message
• swarm_handoff.sh enforces this two-type policy at validation time
• The handoffd.bb daemon and handoff_lib.bb library complete the delivery pipeline for validated handoffs

Frequently Asked Questions

What happens if an agent sends an unrecognized handoff type?

The validation script swarm_handoff.sh rejects the handoff with an error before it enters the delivery queue. Only git_handoff and note pass validation—no extension mechanism exists.

Why does SwarmForge limit handoff types to just two?

The constraint enforces workflow discipline. Every work transfer must reference a git commit (git_handoff), and incidental communication requires explicit authorization (note). This design prevents agents from devolving into unstructured chat and maintains complete audit trails.

Can I use note for any short message I want to send?

No. The swarmforge/handoff-protocol.md specification restricts note to cases "explicitly directed by the role prompt, the constitution, or the operator." Unsolicited notes fail policy compliance even if syntactically valid.

How does the handoff daemon know where to deliver messages?

The handoffd.bb daemon reads the validated to header and routes files to recipient inboxes based on role-to-inbox mappings. It then sends tmux wake-up notifications to alert receiving agents, using handoff_lib.bb for header parsing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}