# SwarmForge Handoff Message Types: Supported Formats Explained

> Discover SwarmForge handoff message types. Learn about git_handoff for code and note for user messages to streamline your project transitions.

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

---

**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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) enumerates only these two valid types. The validation logic in [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/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.

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

```

Process the draft through the outbound validation script:

```bash
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).

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

```

Submit using the same validation path:

```bash
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`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) and `handoffd`; invalid types fail with *HANDOFF INVALID*
- Complete protocol details live in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.