SwarmForge Handoff Protocol Helper Scripts: A Complete Guide to File-Based Workflow Automation

SwarmForge handoff protocol helper scripts are Bash and Babashka utilities located in swarmforge/scripts/ that manage the creation, delivery, and lifecycle of .handoff files between tmux-based roles.

The unclebob/swarm-forge repository implements a lightweight, file-based coordination mechanism through its SwarmForge handoff protocol helper scripts. These utilities enable seamless task transfer between different roles (such as builder and tester) in a tmux-driven development environment. Located in the swarmforge/scripts directory, the scripts handle everything from sequence number generation to daemon-based delivery and workflow state transitions.

Core Helper Scripts for Handoff Management

handoff_lib.bb – The Foundation Library

The handoff_lib.bb file serves as the core library for the entire handoff system. It provides essential functions for generating unique sequence numbers, reading and writing handoff headers, and printing task or batch information. All other scripts in the swarmforge/scripts directory depend on this library to maintain consistent file formats and metadata structure.

handoffd.bb – The Delivery Daemon

The handoffd.bb script runs as a background daemon that monitors each role's outbox directory for pending handoffs. When it detects a new .handoff file, it adds delivery metadata (including enqueued_at and recipient timestamps), moves the file to the recipient's inbox, and sends a notification to the appropriate tmux session. This automates the transfer process without requiring manual file manipulation.

swarm_handoff.bb – Creating Handoffs

The swarm_handoff.bb script (invoked through the swarm_handoff.sh wrapper) generates new handoff files in the sender's outbox. It utilizes handoff_lib.bb to ensure proper header formatting and sequence numbering before the daemon processes the delivery.

Daemon Control and Workflow Utilities

Stopping the Daemon

To gracefully terminate the background delivery process, use stop_handoff_daemon.sh or its Babashka counterpart stop_handoff_daemon.bb. These scripts ensure the handoffd process shuts down cleanly without leaving orphaned handoff files in transit.

User Workflow Helpers

A suite of convenience scripts assists users in managing handoff state transitions:

• ready_for_next.sh and ready_for_next.bb: Move handoff files to signal readiness for the next workflow step
• ready_for_next_task.sh / ready_for_next_task.bb: Specifically handle task-level readiness signals
• ready_for_next_batch.sh / ready_for_next_batch.bb: Handle batch-level transitions
• done_with_current.sh and done_with_current.bb: Mark current handoffs as completed
• done_with_current_task.sh / done_with_current_task.bb: Complete individual tasks
• done_with_current_batch.sh / done_with_current_batch.bb: Complete entire batches

These utilities relocate .handoff files between the new, inbox, outbox, and sent directories according to the protocol defined in swarmforge/handoff-protocol.md.

The Handoff Lifecycle in Practice

Creating a handoff from the builder role to the tester role requires specifying the source, destination, type, and priority:

# In the builder's worktree

SWARMFORGE_ROLE=builder ./swarmforge/scripts/swarm_handoff.sh \
  --from builder \
  --to tester \
  --type task \
  --priority 10 \
  --task "build-image" \
  --message "Image built successfully"

This command internally calls handoff_lib.bb to write a properly formatted .handoff file into the outbox/ directory.

To run the delivery daemon manually (normally started automatically by SwarmForge):

# From the project root

./swarmforge/scripts/handoffd.bb /path/to/project

The daemon continuously polls outbox directories, delivers pending handoffs to recipient inboxes, and triggers tmux notifications.

When you are ready to process the next item:

./swarmforge/scripts/ready_for_next_task.sh

This moves the .handoff file from inbox/new/ to inbox/ready/ so the recipient can pick it up.

Upon completion:

./swarmforge/scripts/done_with_current_task.sh

This relocates the handoff to the sent/ directory and cleans up temporary state files.

Summary

• SwarmForge handoff protocol helper scripts reside in swarmforge/scripts/ and implement a complete file-based workflow system using Bash and Babashka
• The handoff_lib.bb library provides core functionality for sequence generation and header management used by all other scripts
• handoffd.bb operates as a background daemon that automates delivery from outbox to inbox while notifying tmux sessions
• swarm_handoff.bb (via swarm_handoff.sh) creates properly formatted handoff files with metadata and priorities
• Workflow helpers like ready_for_next*.sh and done_with_current*.sh manage state transitions between new, inbox, outbox, and sent directories
• The protocol is documented in swarmforge/handoff-protocol.md and integrates tightly with SwarmForge's tmux-driven architecture

Frequently Asked Questions

What is the purpose of the handoffd.bb daemon in SwarmForge?

The handoffd.bb daemon automates the delivery phase of the handoff protocol by monitoring outbox directories for new .handoff files. It adds delivery metadata including timestamps and recipient information, moves files to the appropriate inbox, and sends notifications to the recipient's tmux session to alert them of pending work.

How do I create a handoff between two roles using the helper scripts?

Use the swarm_handoff.sh wrapper (which invokes swarm_handoff.bb) with parameters specifying --from, --to, --type, --priority, and --task. This generates a properly sequenced .handoff file in the sender's outbox, which the daemon then delivers to the recipient's inbox according to the handoff protocol.

What is the difference between ready_for_next and done_with_current scripts?

The ready_for_next scripts (including task and batch variants) signal that a handoff is ready to be processed by moving files from inbox/new/ to inbox/ready/. The done_with_current scripts mark work as completed by relocating handoffs to the sent/ directory and removing temporary state, effectively closing out that workflow item.

Where are the SwarmForge handoff protocol helper scripts located in the repository?

All helper scripts are located in the swarmforge/scripts/ directory of the unclebob/swarm-forge repository. This includes the core library (handoff_lib.bb), the daemon (handoffd.bb), creation utilities (swarm_handoff.bb), control scripts (stop_handoff_daemon.sh), and workflow helpers (ready_for_next*.sh, done_with_current*.sh).

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