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

> Discover how SwarmForge agents use ready_for_next.sh and done_with_current.sh to automate task coordination and create a continuous work loop for efficient batch and task modes.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-08-08

---

**SwarmForge agents utilize the [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) and [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) and [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/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:

```bash
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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh)** dispatches to either [`ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh) or [`ready_for_next_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_batch.sh)
- **[`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh)** dispatches to either [`done_with_current_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current_task.sh) or [`done_with_current_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh), [`done_with_current_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh); for `batch` mode, it calls [`ready_for_next_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_batch.sh).

### Reporting Completion with done_with_current.sh

After processing a work unit, the agent runs [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/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:

```clojure
(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.

```bash
#!/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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_batch.sh) and [`done_with_current_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh)** and **[`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) and [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh) or [`ready_for_next_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh), [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh), and their task/batch variants) using `exec bb` to execute the Clojure-based orchestration code.