# SwarmForge Handoff Filename Format: Complete Spec with Examples

> Understand the SwarmForge handoff filename format <priority>[_<timestamp>_<sequence>]_from_<source>_to_<destination>.handoff. Learn the spec and see examples for effective routing and ordering.

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

---

**The SwarmForge handoff filename format follows the pattern `<priority>[_<timestamp>_<sequence>]_from_<source>_to_<destination>.handoff`, where components encode routing priority, temporal ordering, and directional flow between roles.**

SwarmForge uses a strict naming convention for **handoff files** to coordinate work between autonomous agents. According to the `unclebob/swarm-forge` implementation, these filenames are not merely descriptive—they are functional metadata that the handoff queue system parses to determine processing order and routing. This article breaks down the exact specification with verified examples from the test suite.

---

## Filename Structure: Priority, Timestamp, and Direction

Every handoff filename consists of three to five underscore-separated fields plus a fixed `.handoff` extension:

| Position | Field | Required | Description |
|----------|-------|----------|-------------|
| 1 | `<priority>` | Yes | Numeric priority (lower values = higher priority) |
| 2 | `<timestamp>` | No | UTC datetime in `YYYYMMDDTHHMMSSZ` format |
| 3 | `<sequence>` | No | Zero-padded 6-digit sequence number |
| 4 | `from_<source>` | Yes | Origin role identifier |
| 5 | `to_<destination>` | Yes | Target role identifier |

The timestamp and sequence are **optional** but must appear together when used. This creates two valid patterns:

```

# Simple pattern (no temporal ordering)

<priority>_from_<source>_to_<destination>.handoff

# Full pattern (with temporal sequencing)

<priority>_<YYYYMMDDTHHMMSSZ>_<######>_from_<source>_to_<destination>.handoff

```

---

## Verified Examples from the Test Suite

The test implementation in `test/swarmforge/pack_ui_test.clj` generates handoffs using this exact scheme. Line 128 demonstrates the construction:

```clojure
;; From test/swarmforge/pack_ui_test.clj#L128
(write-handoff-file
  (str priority "_" timestamp "_" sequence "_from_" from "_to_" to ".handoff")
  content)

```

Actual filenames appearing in the tests include:

- `50_from_specifier_to_coder.handoff` — priority 50, no timestamp, specifier → coder
- `10_20260615T000001Z_000001_from_sender_to_receiver.handoff` — priority 10, June 15 2026 00:00:01 UTC, sequence 1, sender → receiver
- `50_20260615T000001Z_000001_from_New_Task_to_receiver.handoff` — priority 50, same timestamp, New_Task → receiver

These examples are verified in `test/swarmforge/handoff_test.clj` where assertions validate filename parsing and priority extraction lines 166–172.

---

## Timestamp and Sequence Number Logic

When multiple handoffs share the **same priority**, SwarmForge uses timestamp + sequence to enforce **FIFO ordering**:

1. **Timestamp** — ISO 8601 basic format with `Z` suffix (UTC), providing millisecond-level precision: `20260615T000001Z`
2. **Sequence** — Six-digit zero-padded integer (`000001`-`999999`) disambiguating handoffs created within the same second

The combined timestamp_sequence segment ensures **total ordering** even when file system timestamps are unreliable or when handoffs are batch-generated.

---

## Role Naming Conventions

The `<source>` and `<destination>` segments use **snake_case identifiers** matching role names defined in the swarm configuration. The literal strings `from_` and `_to_` are **fixed delimiters**—parsing logic in `src/swarmforge/handoff.clj` splits on these markers to extract routing information.

Valid role identifiers observed in tests:
- `specifier`, `coder`, `sender`, `receiver`
- Composite names like `New_Task` (retaining original casing)

---

## File Extension Requirement

All handoff files **must** end with `.handoff`. The queue scanner explicitly filters for this extension when polling the handoff directory, as implemented in the directory-watching logic.

---

## Summary

- **Base format**: `<priority>_from_<source>_to_<destination>.handoff`
- **Full format**: `<priority>_<YYYYMMDDTHHMMSSZ>_<######>_from_<source>_to_<destination>.handoff`
- **Priority** determines processing precedence (numeric, lower = sooner)
- **Timestamp + sequence** provide deterministic ordering for same-priority handoffs
- **Strict delimiters** (`_from_`, `_to_`, `.handoff`) enable reliable parsing
- Source files: `test/swarmforge/pack_ui_test.clj` (generation) and `test/swarmforge/handoff_test.clj` (validation)

---

## Frequently Asked Questions

### What characters are allowed in role names?

Role names support **alphanumeric characters, underscores, and mixed case** (e.g., `New_Task`, `api_gateway`). The parser splits on the literal substrings `_from_` and `_to_`, so these sequences cannot appear within role names themselves.

### Why include both timestamp and sequence number?

The **sequence number prevents collisions** when multiple handoffs are generated within the same second. Six digits supports up to one million handoffs per second per priority level, which exceeds SwarmForge's designed throughput.

### How does SwarmForge handle malformed handoff filenames?

Malformed files are **silently ignored** by the queue scanner, which applies a strict regex pattern matching the documented format before enqueueing. Tests in `handoff_test.clj` verify this filtering behavior.

### Can I create handoff files manually?

Yes, provided you follow the exact naming convention. The `write-handoff-file` function in the test suite demonstrates this—any process with write access to the handoff directory can inject work by creating properly named `.handoff` files with valid JSON content bodies.