How SwarmForge Agents Use ready_for_next.sh and done_with_current.sh to Coordinate Work Cycles

SwarmForge agents rely on ready_for_next.sh and done_with_current.sh to signal readiness and completion to the hand-off daemon, with both scripts automatically dispatching to role-specific Babashka helpers that handle task versus batch receive modes.

SwarmForge, an open-source orchestration framework maintained by Robert C. Martin in the unclebob/swarm-forge repository, provides a lightweight agent coordination mechanism through two thin Bash wrapper scripts. These scripts abstract away the complexity of role-specific work modes by reading the SWARMFORGE_ROLE environment variable and consulting the project's roles.tsv configuration, allowing agents to seamlessly participate in continuous work loops.

Role Detection and Dispatch Architecture

The coordination system begins with environment-based role identification. When an agent invokes either script, the Babashka implementation files—ready_for_next.bb and done_with_current.bb—read the SWARMFORGE_ROLE variable and look up the role's receive mode (either task or batch) from the project's .swarmforge/roles.tsv file.

Based on this lookup, the top-level wrappers dispatch to specific helper scripts using the Bash command:

exec bb "$SCRIPT_DIR/<helper>.bb" "$@"

For ready_for_next.sh, this dispatches to either ready_for_next_task.sh or ready_for_next_batch.sh. Similarly, done_with_current.sh forwards to done_with_current_task.sh or done_with_current_batch.sh. This architecture ensures that agent code remains agnostic to whether the role processes individual tasks or batch collections.

The Work Coordination Cycle

SwarmForge agents operate in a tight loop of receive → process → report → ready, managed through two distinct phases handled by the wrapper scripts.

Signaling Readiness with ready_for_next.sh

When an agent becomes idle and requires new work, it executes swarmforge/scripts/ready_for_next.sh. The underlying Babashka helper invokes the hand-off daemon's API via a process/exec call, registering the agent as available for the next assignment. The daemon then assigns either a single task or a batch (depending on the role configuration) and launches the assigned command.

Reporting Completion with done_with_current.sh

Upon finishing the current unit of work, the agent runs swarmforge/scripts/done_with_current.sh. This script performs two critical operations sequentially: first signaling task completion to the daemon, then immediately invoking the corresponding ready_for_next_* helper to return the agent to the ready state.

The Babashka implementation explicitly chains these calls:

(process/exec (str (fs/path script-dir "ready_for_next_task.sh")))
;; or for batch mode:
(process/exec (str (fs/path script-dir "ready_for_next_batch.sh")))

This automatic chaining eliminates the need for agents to manually alternate between scripts, creating an uninterrupted work cycle.

Implementation File Structure

The coordination scripts reside in the swarmforge/scripts/ directory and follow a layered architecture:

• ready_for_next.sh — Top-level dispatcher that selects task or batch mode based on SWARMFORGE_ROLE
• done_with_current.sh — Completion dispatcher that reports success and automatically requests new work
• ready_for_next.bb — Babashka implementation that parses roles.tsv and executes the appropriate receive logic
• done_with_current.bb — Babashka implementation that handles completion signaling and chains to the ready helper
• ready_for_next_task.sh / ready_for_next_batch.sh — Thin wrappers invoking the Babashka task-specific logic
• done_with_current_task.sh / done_with_current_batch.sh — Thin wrappers for completion signaling in each mode

All paths assume execution from the project root where the .swarmforge/ configuration directory exists.

Practical Agent Implementation

Agents implement a continuous processing loop by exporting the role environment variable and invoking the coordination scripts. The following pattern demonstrates a standard worker implementation:

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

while true; do
  # Signal readiness and receive assignment from daemon

  ./swarmforge/scripts/ready_for_next.sh
  
  # Execute assigned work (daemon launches the actual process)

  # ... processing occurs here ...

  
  # Report completion and immediately become ready for next unit

  ./swarmforge/scripts/done_with_current.sh
done

If worker is configured with batch receive mode, the scripts internally route to ready_for_next_batch.sh and done_with_current_batch.sh; for task mode, they route to the *_task.sh variants. The agent implementation remains identical regardless of the mode.

Summary

• Role-based dispatch — Both scripts automatically detect the agent's role via SWARMFORGE_ROLE and select appropriate task or batch handlers by parsing roles.tsv.
• Unified entry points — Agents use ready_for_next.sh to request work and done_with_current.sh to report completion, without managing mode-specific logic.
• Automatic work cycling — done_with_current.sh internally chains to the ready helper, creating a tight loop that maintains agent availability.
• Babashka implementation — Core logic resides in .bb files that interface with the hand-off daemon via process/exec calls.
• Zero configuration switching — Changing a role from task to batch processing requires only updating roles.tsv, with no agent code modifications.

Frequently Asked Questions

What environment variable configures a SwarmForge agent's role?

Agents must export SWARMFORGE_ROLE before invoking the coordination scripts. This variable determines which entry in the project's roles.tsv file the scripts consult to identify whether the role operates in task or batch receive mode.

How does done_with_current.sh differ from ready_for_next.sh?

While ready_for_next.sh only signals the daemon that the agent is idle and ready to receive work, done_with_current.sh first reports the completion of the current task or batch, then automatically invokes the appropriate ready_for_next_* helper to return the agent to the ready state without requiring a separate manual call.

Where does the role receive mode configuration live?

The receive mode (task versus batch) for each role is defined in the .swarmforge/roles.tsv file at the project root. The Babashka scripts ready_for_next.bb and done_with_current.bb parse this file during execution to determine which helper scripts to dispatch.

Can agents interact directly with the hand-off daemon without these scripts?

While technically possible, agents should use the ready_for_next.sh and done_with_current.sh wrappers because they handle role detection, mode dispatch, and the specific process/exec API calls required by the daemon. Direct daemon interaction would require reimplementing the logic found in the .bb source files.

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