Swarm Forge Handoff File Format and Commit SHA Validation Rules

Swarm Forge requires a strict plain-text handoff protocol consisting of a key-value header block, a mandatory blank separator, and an opaque body, where commit SHAs must validate as exactly 10 hexadecimal characters uniquely resolving to a commit object.

The unclebob/swarm-forge repository implements a file-based coordination system for multi-agent software development workflows. Agents generate handoffs to transfer context and tasks between roles, with the swarm_handoff.sh script enforcing rigorous validation on commit references to ensure repository integrity and deterministic routing.

Handoff File Structure

Each handoff is a plain-text file divided into three distinct sections, as defined in swarmforge/handoff-protocol.md (lines 90–108).

Header Block

The header consists of one key: value pair per line. Reserved keys—including id, from, and created_at—are generated automatically by swarm_handoff.sh and must not be supplied by agents. All other headers are written by the creating agent.

The canonical header fields include:

• id: <timestamp>_<sequence>_from_<sender> (auto-generated)
• from: <sender> (auto-generated)
• to: <recipient-list>
• recipient: <single-recipient>
• priority: <00-99>
• type: <git_handoff|note>
• role: <sender-role>
• task: <short-stable-task-name>
• commit: <commit-abbrev>
• created_at: <ISO-8601-UTC> (auto-generated)
• enqueued_at: <ISO-8601-UTC> (auto-generated)

Mutable headers such as dequeued_at and completed_at are appended later by the daemon or helper scripts during handoff lifecycle management.

Separator and Body

A single blank line separates the header from the body. The body contains opaque data generated by the daemon; receiving agents treat this section as opaque and do not parse its contents.

Commit SHA Validation Rules

When the handoff type is git_handoff, swarm_handoff.sh validates the commit field against the repository's Git objects. The validation logic (implemented in swarmforge/scripts/swarm_handoff.sh and specified in swarmforge/handoff-protocol.md lines 96–103) enforces five strict rules:

1. Hexadecimal characters only: The abbreviation must contain only characters in the range [0-9a-f].
2. Exact length of 10: The abbreviation must be exactly ten characters long.
3. Unique resolution: git rev-parse <abbrev> must resolve to exactly one object.
4. Commit object type: The resolved object must be a commit, not a tree, blob, or tag.
5. Canonicalization: After validation, the script writes the canonical ten-character abbreviation into the final handoff file.

If any validation rule fails, swarm_handoff.sh aborts handoff creation and returns a detailed error message (see error handling at lines 74–81 of the protocol specification).

Practical Examples

Valid Git Handoff Draft

Agents create draft files for processing by the validation script:

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

Running the validator:

./swarm_handoff.sh ./tmp/handoff.txt

On success, the script emits a completed file to .swarmforge/handoffs/outbox/ with a structured filename incorporating the priority, timestamp, sequence, sender, and recipient.

Invalid Commit Handling

An abbreviation that is too short or ambiguous fails validation:

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

This generates an error and aborts:

HANDOFF INVALID: ./tmp/handoff.txt

Errors:
- message: commit `a1b2c3` is ambiguous; use at least 9 characters.

Core Implementation Files

The handoff system spans several critical files in the unclebob/swarm-forge repository:

• swarmforge/handoff-protocol.md: Defines the complete protocol specification, including header formats and validation rules (lines 90–108).
• swarmforge/scripts/swarm_handoff.sh: Implements outbound validation, including the five-rule commit SHA verification.
• swarmforge/scripts/handoffd.bb: The daemon responsible for delivering validated handoffs to recipient inboxes.
• swarmforge/scripts/ready_for_next_task.sh: Consumes handoffs from the inbox and expects the commit field to contain a pre-validated, canonical abbreviation.

Summary

• Swarm Forge handoffs use a plain-text format with a structured header, blank separator, and opaque body.
• Headers follow strict key: value syntax, with reserved keys (id, from, created_at) generated by swarm_handoff.sh.
• Commit SHAs in git_handoff types must be exactly 10 hexadecimal characters that uniquely resolve to a commit object.
• Validation failures abort handoff creation with detailed error messages to prevent ambiguous or malformed references.
• The canonical 10-character abbreviation is written to the final handoff file after successful validation.

Frequently Asked Questions

What happens if I provide a full 40-character SHA instead of 10?

The validation will fail. According to the protocol specification in swarmforge/handoff-protocol.md, the commit field must contain exactly 10 characters. The swarm_handoff.sh script checks length before attempting resolution, rejecting any abbreviation that does not match the 10-character requirement.

Can agents manually set the id or created_at headers?

No. These are reserved keys generated automatically by swarm_handoff.sh during processing. Agents that supply these fields in draft handoffs will cause validation errors, as the protocol mandates that only the script may assign identifiers and timestamps to ensure auditability and prevent collisions.

Why does the system require exactly 10 characters for commit abbreviations?

Ten characters provides sufficient entropy to be globally unique across the repository while maintaining readability. The validation rules require that git rev-parse resolves the abbreviation to exactly one object, and the 10-character minimum ensures deterministic references that prevent ambiguous handoffs between agents.

What object types are rejected during commit validation?

The validator accepts only commit objects. If the abbreviation resolves to a tree, blob, or tag, swarm_handoff.sh rejects the handoff. This ensures that handoffs reference actual code states rather than directory structures, file contents, or release pointers.

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