Git Handoff vs Note Handoff Behavior in Swarm Forge

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

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:

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 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, 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

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

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

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

Does a note handoff trigger downstream forwarding?

No. After an agent processes a note handoff and executes 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.

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