SwarmForge Handoff Filename Format: Complete Spec with Examples

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:

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

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