How SwarmForge Agents Use ready_for_next.sh and done_with_current.sh for Work Coordination

SwarmForge agents utilize the ready_for_next.sh and done_with_current.sh wrapper scripts to signal readiness and completion to the hand-off daemon, creating a continuous work loop that automatically handles both task and batch modes based on the SWARMFORGE_ROLE environment variable.

In the unclebob/swarm-forge repository, agents coordinate distributed workloads through a lightweight yet robust signaling mechanism. These Bash entry points abstract away role-specific details by dispatching to Babashka implementations, allowing agents to seamlessly transition between idle and working states. By reading the project’s roles.tsv configuration, the scripts determine whether an agent operates in task or batch mode and route commands to the appropriate handlers.

Role-Based Dispatch Architecture

The coordination system relies on environment variables and project configuration to determine how an agent receives work.

Detecting the Receive Mode

Both ready_for_next.sh and done_with_current.sh delegate their core logic to Babashka scripts (ready_for_next.bb and done_with_current.bb) that read the SWARMFORGE_ROLE environment variable. The Babashka code queries the project’s .swarmforge/roles.tsv file to determine the role’s receive mode—either task or batch.

Agents must export this variable before invoking either script:

export SWARMFORGE_ROLE=worker

Task vs. Batch Forwarding

Depending on the detected receive mode, the top-level scripts forward execution to specialized helpers using the Bash pattern exec bb "$SCRIPT_DIR/<helper>.bb" "$@".

• ready_for_next.sh dispatches to either ready_for_next_task.sh or ready_for_next_batch.sh
• done_with_current.sh dispatches to either done_with_current_task.sh or done_with_current_batch.sh

This internal case dispatch ensures the agent code remains agnostic to the work unit type. The thin shell wrappers (ready_for_next_task.sh, done_with_current_batch.sh, etc.) subsequently invoke their corresponding .bb files to perform the actual daemon communication.

The Agent Work Cycle

These two scripts form the bookends of the agent’s operational loop: signaling availability and reporting completion.

Signaling Readiness with ready_for_next.sh

When an agent finishes its current workload (or on startup), it executes ready_for_next.sh to inform the hand-off daemon that it is idle and ready to receive the next assignment. The underlying Babashka implementation invokes the daemon’s API via a process/exec call, blocking until the daemon assigns work.

For a role configured in task mode, the script internally calls ready_for_next_task.sh; for batch mode, it calls ready_for_next_batch.sh.

Reporting Completion with done_with_current.sh

After processing a work unit, the agent runs done_with_current.sh to signal success. Unlike a simple status report, this script performs a two-step atomic operation:

1. Signal completion of the current task or batch to the daemon
2. Immediately invoke the corresponding ready_for_next_* helper to fetch new work

The Babashka source in done_with_current.bb explicitly chains these calls:

(process/exec (str (fs/path script-dir "ready_for_next_task.sh")))

This design eliminates race conditions and ensures the agent remains in a tight work-loop—receive → process → report → ready—without requiring a separate manual call to signal availability.

Implementing a Continuous Work Loop

A typical SwarmForge agent implements an infinite loop using these scripts to maintain constant throughput. The agent does not need conditional logic for task versus batch modes; the wrapper scripts handle routing automatically based on the SWARMFORGE_ROLE configuration.

#!/bin/bash

# Example: Continuous agent loop for unclebob/swarm-forge

export SWARMFORGE_ROLE=builder  # Defined in .swarmforge/roles.tsv

while true; do
  # Block until daemon assigns work (task or batch)

  ./swarmforge/scripts/ready_for_next.sh
  
  # Execute the assigned payload (daemon controls what runs here)

  # ... agent performs build, test, or computation ...

  
  # Report success and immediately request next assignment

  ./swarmforge/scripts/done_with_current.sh
done

If the role’s receive mode is batch, the loop internally utilizes ready_for_next_batch.sh and done_with_current_batch.sh; for task mode, it uses the *_task.sh variants. The agent implementation remains identical regardless of the mode.

Summary

• ready_for_next.sh and done_with_current.sh are thin Bash wrappers that serve as the primary interface between SwarmForge agents and the hand-off daemon.
• The scripts dynamically dispatch to task or batch helpers by reading the SWARMFORGE_ROLE environment variable and querying roles.tsv via the Babashka implementations in ready_for_next.bb and done_with_current.bb.
• done_with_current.sh automatically chains into the ready state, ensuring agents maintain a continuous work loop without manual intervention.
• Agents remain mode-agnostic; the routing logic in swarmforge/scripts/ handles the complexity of task versus batch coordination.

Frequently Asked Questions

What is the difference between task mode and batch mode in SwarmForge?

Task mode assigns individual work units to agents one at a time, while batch mode assigns groups of work units as a single allocation. The ready_for_next.sh and done_with_current.sh scripts detect the appropriate mode by reading the SWARMFORGE_ROLE variable and looking up the configuration in the project’s roles.tsv file, then dispatch to the corresponding task or batch helper scripts.

How does an agent specify which role it is performing?

The agent must export the SWARMFORGE_ROLE environment variable before executing either script. This variable maps to an entry in the .swarmforge/roles.tsv file, which defines the role’s receive mode and other orchestration parameters. The Babashka logic in ready_for_next.bb and done_with_current.bb reads this variable to determine whether to invoke the task or batch variants of the helper scripts.

Why does done_with_current.sh call ready_for_next.sh internally?

This design pattern creates an atomic transition from completion to readiness, preventing the agent from entering an ambiguous idle state between tasks. By invoking ready_for_next_task.sh or ready_for_next_batch.sh immediately after reporting completion—via the process/exec call in done_with_current.bb—the agent ensures the hand-off daemon can instantly assign new work without waiting for a separate readiness signal.

Where are the Babashka implementation files located?

The core logic resides in swarmforge/scripts/ready_for_next.bb and swarmforge/scripts/done_with_current.bb. These files handle the role detection, roles.tsv parsing, and daemon API communication. They are invoked by the thin shell wrappers (ready_for_next.sh, done_with_current.sh, and their task/batch variants) using exec bb to execute the Clojure-based orchestration code.

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