SwarmForge Handoff Message Types: Supported Formats Explained

SwarmForge supports exactly two handoff message types: git_handoff for code-based transitions and note for brief user-directed messages.

SwarmForge enforces a rigid, minimal protocol for agent-to-agent communication. Understanding the supported SwarmForge handoff message types is essential for building workflows that pass validation and reach their intended recipients without rejection.

The Two Supported SwarmForge Handoff Message Types

The protocol specification in swarmforge/handoff-protocol.md enumerates only these two valid types. The validation logic in swarm_handoff.sh and the handoffd daemon reject any other type: header with a HANDOFF INVALID error.

git_handoff: Code-Based Handoffs

The git_handoff type signals that one role has committed code requiring another role to merge and continue processing. This is the primary mechanism for multi-role development workflows in SwarmForge.

Required and optional fields include:

• from – originating role
• to – target role(s)
• priority – numeric priority level
• task – task identifier
• commit – Git SHA for the commit to merge

As documented in the protocol (lines 30-46), this type carries full metadata needed for automated queueing and audit trails.

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

Process the draft through the outbound validation script:

swarm_handoff.sh ./tmp/handoff.txt

note: User-Directed Short Messages

The note type allows a single-line message of 80 characters or fewer. It is restricted — agents may only send notes when explicitly directed by a user, role prompt, or constitution (lines 92-100).

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

Submit using the same validation path:

swarm_handoff.sh ./tmp/note.txt

Validation and Enforcement

The SwarmForge handoff message types are strictly enforced at multiple layers:

1. swarmforge/scripts/swarm_handoff.bb (or .sh) — validates outbound drafts before queueing
2. swarmforge/scripts/handoffd.bb — the delivery daemon that processes only git_handoff and note types

Any type: value outside this set triggers immediate rejection. This design prevents protocol drift and maintains predictable agent behavior.

Summary

• SwarmForge recognizes only two handoff message types: git_handoff and note
• git_handoff carries commit SHAs and task metadata for code handoffs
• note provides constrained free-form messaging when explicitly permitted
• Validation occurs in swarm_handoff.sh and handoffd; invalid types fail with HANDOFF INVALID
• Complete protocol details live in swarmforge/handoff-protocol.md

Frequently Asked Questions

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

The handoff is rejected. Both swarm_handoff.sh and the handoffd daemon validate the type: header and return a HANDOFF INVALID error for any value other than git_handoff or note.

Can I extend SwarmForge to support custom message types?

Not without modifying the source. The validation logic is hardcoded in swarmforge/scripts/swarm_handoff.bb and handoffd.bb. The protocol intentionally limits types to maintain interoperability and audit reliability.

When should I use a note instead of a git_handoff?

Use note only for brief, free-form communication when explicitly authorized by user instruction, role prompt, or constitution. For all code-related transitions, git_handoff is required. The note type is capped at 80 characters and cannot carry commit metadata.

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