# SwarmForge Handoff Message Types: The Two-Type Protocol Explained

> Discover the two essential handoff message types in SwarmForge: git_handoff and note. Learn how this protocol streamlines agent-to-agent communication for multi-role development.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: deep-dive
- Published: 2026-09-02

---

**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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md). The validation script [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/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:

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

```

To create and validate:

```bash

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

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

```

Validation follows the same path:

```bash
swarm_handoff.sh ./tmp/handoff.txt

```

## How SwarmForge Enforces Handoff Message Types

The validation layer lives in [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.