SwarmForge Handoff Protocol Message Types: git_handoff and note Explained

SwarmForge defines exactly two valid message types—git_handoff for code commits and note for free-form status updates—that agents exchange when passing work through the handoff protocol.

The SwarmForge handoff protocol governs inter-agent communication in the unclebob/swarm-forge repository, enforcing a strict contract for how autonomous roles transfer tasks. Understanding these SwarmForge handoff protocol message types is essential for writing valid handoff files that the validation scripts accept and the delivery daemon processes.

The Two Message Types

According to swarmforge/handoff-protocol.md (lines 27-31 and 90-99), the protocol permits only two distinct message kinds. The swarmforge/scripts/swarm_handoff.sh validation script explicitly rejects any other type values, ensuring protocol compliance across the swarm.

git_handoff

Emit a git_handoff when your role has committed code that another role must merge and act upon. This message type carries the commit SHA and the logical task name that the commit belongs to.

Required headers:

• type: git_handoff
• to — the recipient role(s)
• priority — integer priority level
• task — the task identifier
• commit — the Git SHA to be merged

note

Use a note for short free-form informational messages, such as "waiting on QA" or blockers. The protocol restricts this type to explicit directives from the role prompt, constitution, or user instructions.

Required headers:

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

Message Validation and Expansion

The swarmforge/scripts/swarm_handoff.sh script serves as the validation gate for all outbound handoffs. It enforces the two allowed message types, checks for required headers, and expands drafts by injecting mandatory metadata headers including id, from, and created_at. After validation, the script writes the completed handoff file to the agent’s outbox/ directory for pickup by the daemon.

Practical Examples

Drafting a git_handoff

Create a draft file with the required headers:

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

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

Validate and queue the handoff:

swarm_handoff.sh ./tmp/handoff.txt

The script expands the draft with canonical headers, adds a body containing the merge instruction, and places the final file in outbox/cleaner/.

Drafting a note

Create a status update draft:

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

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

Process the note through the validator:

swarm_handoff.sh ./tmp/note.txt

The resulting handoff includes the standard headers plus the message payload, and the daemon delivers it to each recipient’s inbox.

Daemon Processing and Delivery

The swarmforge/scripts/handoffd.bb daemon consumes files from the outbox/ directory, copies them to each recipient’s inbox/, and sends tmux wake-up notifications. It relies on the message type to determine how to handle the payload. Meanwhile, helper scripts such as ready_for_next_task.sh and ready_for_next_task_batch.sh read the type header to report incoming work to the receiving agent.

Summary

• Two exclusive types: The protocol recognizes only git_handoff and note; all other types are rejected by swarm_handoff.sh.
• Context-specific usage: Use git_handoff for code commits requiring merge actions, and note only when explicitly authorized for status updates.
• Strict validation: The swarmforge/scripts/swarm_handoff.sh script enforces header requirements and expands drafts before queueing.
• Automated delivery: The handoffd.bb daemon routes validated messages to recipient inboxes based on the to header.

Frequently Asked Questions

What happens if I use a message type other than git_handoff or note?

The swarmforge/scripts/swarm_handoff.sh validator will reject the handoff file and exit with an error. The protocol explicitly forbids custom message types to maintain consistency across the swarm.

Can I send a note without being explicitly directed?

No. The protocol specification in swarmforge/handoff-protocol.md mandates that note messages should only be sent when directed by the role prompt, constitution, or user. Unauthorized notes violate the protocol contract.

Where are handoff files stored after validation?

After swarm_handoff.sh validates and expands the draft, it writes the completed handoff file to the agent’s outbox/ directory. The handoffd.bb daemon then moves copies to each recipient’s inbox/ directory.

How does the daemon know which agent receives the handoff?

The daemon parses the to header from the validated handoff file. It supports multiple recipients (comma-separated) and copies the message to each target agent’s inbox before sending tmux notifications to wake the receiving processes.

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