SwarmForge Handoff Protocol Message Types: `git_handoff` and `note` Explained

SwarmForge's handoff protocol defines exactly two message types—git_handoff and note—that agents exchange when transferring work between roles.

SwarmForge is an open-source multi-agent orchestration framework developed by Uncle Bob (Robert C. Martin). Its inter-agent communication relies on a strict handoff protocol with only two valid message types. Understanding these types is essential for building custom agents or extending the SwarmForge ecosystem.

The Two Message Types in SwarmForge

The SwarmForge handoff protocol permits only git_handoff and note. All other values for the type header are rejected by the validation layer in swarmforge/scripts/swarm_handoff.sh. This constraint appears in the specification document at lines 27-31 and is reinforced in the "Message Types" section around line 90 of swarmforge/handoff-protocol.md.

git_handoff: Code-Based Task Transfers

git_handoff signals that one role has committed code another role must merge and act upon.

Required header fields:

• type: git_handoff
• to — recipient role(s)
• priority — integer priority level
• task — logical task identifier
• commit — SHA of the commit to merge

Example draft:

# handoff draft (./tmp/handoff.txt)

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

Run the validator:

swarm_handoff.sh ./tmp/handoff.txt

The script expands this draft by injecting mandatory headers (id, from, created_at, version) and writes a body containing canonical merge instructions. The completed handoff lands in the agent's outbox/ directory. The handoffd.bb daemon then routes it to the recipient's inbox and sends a tmux wake-up notification.

note: Informational Messages

note carries short free-form text for status updates or coordination.

Required header fields:

• type: note
• to — recipient role(s)
• priority — integer priority level
• message — single-line informational text

Example draft:

# handoff draft (./tmp/note.txt)

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

Validate and queue:

swarm_handoff.sh ./tmp/note.txt

The resulting handoff includes standard headers plus the message payload. The daemon delivers to each recipient's inbox. Per the protocol specification, note should only be sent when explicitly directed by role prompts, constitution, or user instruction.

Protocol Validation and Enforcement

The swarm_handoff.sh script serves as the strict validation gate for SwarmForge message types. It:

1. Rejects any type value other than git_handoff or note
2. Enforces presence of required headers per message type
3. Generates system-populated headers (id, from, created_at, version)
4. Constructs the final handoff file ready for daemon processing

This validation ensures protocol integrity across all agent interactions.

Key Files in the Handoff System

File	Purpose
swarmforge/handoff-protocol.md	Official specification of format, filename conventions, and valid message types (lines 27-31, 90-99)
swarmforge/scripts/swarm_handoff.sh	Validation gate and handoff file generator
swarmforge/scripts/handoffd.bb	Daemon consuming outbound handoffs, routing to inboxes, sending tmux notifications
swarmforge/scripts/ready_for_next_task.sh	Agent helper for pulling and parsing incoming handoffs

Summary

• SwarmForge handoff protocol recognizes exactly two message types: git_handoff and note.
• git_handoff transmits code commits with merge instructions for downstream roles.
• note sends free-form informational messages per explicit directive.
• swarm_handoff.sh enforces strict type validation and header requirements.
• Both types trigger daemon-managed delivery via handoffd.bb to recipient inboxes.

Frequently Asked Questions

What happens if I use an invalid message type in SwarmForge?

The swarm_handoff.sh script rejects the handoff and exits with an error. Only git_handoff and note pass validation. Check swarmforge/handoff-protocol.md for the complete type specification.

Can a single handoff have multiple recipients?

Yes. The to header accepts comma-separated role names: to: architect,QA. The daemon copies the handoff to each recipient's inbox directory.

How does an agent receive handoffs in SwarmForge?

Agents invoke ready_for_next_task.sh (or its batch variant) to poll their inbox. These helpers read the type header and surface the payload appropriately to the agent's context.

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