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

> Discover how SwarmForge agents use ready_for_next.sh and done_with_current.sh to coordinate work cycles. Learn how these scripts signal readiness and completion to the hand-off daemon for efficient task management.

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

---

**SwarmForge agents rely on [`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) 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:

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

```

For [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh), this 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). Similarly, [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh) forwards to [`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 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`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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:

```clojure
(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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh)** — Top-level dispatcher that selects task or batch mode based on `SWARMFORGE_ROLE`
- **[`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh)** / **[`ready_for_next_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_batch.sh)** — Thin wrappers invoking the Babashka task-specific logic
- **[`done_with_current_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current_task.sh)** / **[`done_with_current_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/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:

```bash
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`](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, 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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) to request work and [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh) to report completion, without managing mode-specific logic.
- **Automatic work cycling** — [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) only signals the daemon that the agent is idle and ready to receive work, [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/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`](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) 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.