# Swarm Forge Handoff File Format and Commit SHA Validation Rules

> Discover Swarm Forge handoff file format and commit SHA validation rules. Ensure your SHAs are exactly 10 hex characters and uniquely resolve to commit objects.

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

---

**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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) validates the `commit` field against the repository's Git objects. The validation logic (implemented in [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.sh) and specified in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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:

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

```

Running the validator:

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

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

```

This generates an error and aborts:

```text
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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md)**: Defines the complete protocol specification, including header formats and validation rules (lines 90–108).
- **[`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md), the `commit` field must contain exactly 10 characters. The [`swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/swarm_handoff.sh) rejects the handoff. This ensures that handoffs reference actual code states rather than directory structures, file contents, or release pointers.