# Git Handoff vs Note Handoff Behavior in Swarm Forge

> Understand the difference between Git Handoff and Note Handoff in Swarm Forge. Git handoffs trigger merges and forwarding, while note handoffs are simple acknowledgments.

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

---

**TLDR:** In the `unclebob/swarm-forge` framework, a `git_handoff` delivers a Git commit that triggers a merge operation and downstream forwarding, whereas a `note` handoff transmits a short informational message that ends its lifecycle after the agent acknowledges it without spawning follow-up tasks.

The `unclebob/swarm-forge` repository defines a structured protocol for agent communication through handoff files. Understanding the **git_handoff vs note handoff** behavior differences ensures proper implementation of pipeline chains and prevents workflow interruptions when coordinating autonomous roles.

## Protocol Specifications and Validation

The [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) document specifies distinct header requirements and validation rules for each handoff type, enforced by the `swarmforge/scripts/swarm_handoff.bb` validation script.

### Git Handoff Requirements

A `git_handoff` requires specific headers to facilitate code pipeline progression:

- `type: git_handoff`
- `to`, `priority`, `task`, and `commit`

According to the validation logic in `swarm_handoff.bb`, the `priority` must be a two-digit value, and the `commit` must be a 10-character hexadecimal SHA that resolves to a single commit. The `task` field must contain a short, stable name identifying the work unit.

### Note Handoff Requirements

A `note` handoff uses a simplified structure for informational messaging:

- `type: note`
- `to`, `priority`, and `message`

The `message` must be a single line not exceeding 80 characters. Notably, the `task` and `commit` fields are prohibited in note handoffs, as these would imply code-flow responsibilities that notes do not possess.

## Agent Processing and Body Generation

The [`swarmforge/scripts/ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/ready_for_next_task.sh) dispatcher handles both types as tasks, but the generated body content and subsequent actions differ significantly.

### Git Handoff Execution Flow

When an agent receives a `git_handoff`, the body contains instructions to re-read its role and constitution followed by a merge command:

```text
Re-read your role and constitution.

merge_and_process coder a1b2c3d9

```

The agent executes `merge_and_process <role> <commit>` to integrate the changes. After completion, the agent forwards a new `git_handoff` to the next role in the chain, continuing the pipeline.

### Note Handoff Execution Flow

For a `note` handoff, the body contains the literal message prefixed by the standard re-read instruction:

```text
Re-read your role and constitution.

Waiting on QA result before merging cleanup branch.

```

The agent processes the message but runs [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh) immediately afterward, marking the handoff as completed without generating downstream handoffs.

## Pipeline Impact and Lifecycle Differences

The fundamental distinction lies in the forwarding behavior and queue management:

**Git handoffs** drive the code pipeline. Each role must receive the commit, merge it via `merge_and_process`, and typically create a new `git_handoff` for the subsequent role. This chaining mechanism ensures deterministic code flow through the swarm architecture.

**Note handoffs** provide purely informational communication. Because they lack `task` and `commit` identifiers, they cannot participate in the code pipeline. After the agent runs [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh), the note is removed from the inbox and its lifecycle terminates.

Additionally, agents should only send `note` handoffs when explicitly directed by the user, role prompt, or constitution, whereas `git_handoff` types are permitted whenever a role has work to merge.

## Code Examples

### Creating a Git Handoff

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

```

Validated by `swarm_handoff.bb` and transformed into a handoff file with a `merge_and_process` payload.

### Creating a Note Handoff

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

```

After validation, this generates a body containing only the informational message.

### Agent Handling Logic

```bash

# ready_for_next_task.sh dispatches based on type

if [[ "$type" == "git_handoff" ]]; then
    # Executes merge_and_process from the payload

    merge_and_process "$role" "$commit"
    # Agent later forwards new git_handoff downstream

else
    # type == "note"

    echo "$message"
fi

# Both types conclude with

done_with_current.sh  # Marks handoff completed

```

## Summary

- **Git handoffs** carry a `commit` SHA and `task` name, triggering `merge_and_process` execution and downstream forwarding in the pipeline chain.
- **Note handoffs** transmit short messages (≤80 characters) without `task` or `commit` fields, terminating after [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh) without spawning follow-ups.
- Both types are enqueued and processed as tasks according to `priority`, but only `git_handoff` types participate in code-flow chains.
- Validation in `swarm_handoff.bb` enforces strict header requirements: 10-character hex SHAs for commits and single-line messages for notes.
- Agents may send `git_handoffs` whenever merging work, but `note` handoffs require explicit authorization from prompts or constitution.

## Frequently Asked Questions

### What headers are required for a git_handoff versus a note handoff?

A `git_handoff` requires `type`, `to`, `priority`, `task`, and `commit` headers, with the commit being a 10-character hexadecimal SHA. A `note` handoff requires only `type`, `to`, `priority`, and `message`, where the message must be a single line of 80 characters or fewer. The `task` and `commit` fields are explicitly prohibited in note handoffs according to the protocol specification in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md).

### Does a note handoff trigger downstream forwarding?

No. After an agent processes a `note` handoff and executes [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh), the handoff is marked completed and removed from the inbox. Unlike `git_handoff` types, notes do not generate follow-up handoffs because they lack the `task` and `commit` identifiers necessary for pipeline continuation.

### How does the swarm_handoff.bb script validate these handoff types?

The `swarmforge/scripts/swarm_handoff.bb` script maintains an `allowed-types` set containing both `git_handoff` and `note`. For `git_handoff`, it validates that the `commit` is a 10-character hex SHA and that `priority` is two digits. For `note`, it verifies that `message` is present and does not exceed 80 characters, while ensuring no `task` or `commit` fields are present.

### Can agents send note handoffs at any time?

No. According to the swarm-forge protocol, agents should only send `note` handoffs when explicitly directed by the user, role prompt, or constitution. In contrast, `git_handoff` types are always permitted when a role has work to merge, making them the standard mechanism for routine code pipeline progression.