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

> Understand SwarmForge's git_handoff and note message types. Learn how agents exchange work in this handoff protocol.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: api-reference
- Published: 2026-08-29

---

**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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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:

```text

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

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

```

Run the validator:

```bash
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:

```text

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

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

```

Validate and queue:

```bash
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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) | Official specification of format, filename conventions, and valid message types (lines 27-31, 90-99) |
| [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) script rejects the handoff and exits with an error. Only `git_handoff` and `note` pass validation. Check [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.