# How to Use the ready_for_next.sh Helper Script in Swarm-Forge

> Learn to use the ready_for_next.sh script in Swarm-Forge. This Zsh wrapper with Babashka prepares your Swarm-Forge queue for the next task efficiently.

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

---

**The [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) script is a thin Zsh wrapper that hands off to Babashka to mark the current task or batch as complete and prepare the Swarm-Forge queue for the next work unit.**

The [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) helper is part of the hand-off protocol in **[unclebob/swarm-forge](https://github.com/unclebob/swarm-forge)**. It serves as the bridge between a finished work unit and the next one, updating internal state without requiring direct manipulation of queue files.

## What ready_for_next.sh Does

The script operates as a **minimal shim**. It determines its own directory, then delegates all logic to the corresponding Babashka implementation in `ready_for_next.bb`. This design keeps the wrapper portable while the `.bb` file handles:

- Writing the `dequeued_at` timestamp for the completed work unit
- Moving the current item out of the active queue
- Refreshing Swarm-Forge's internal state for the next unit

The sibling script [`ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh) follows the same pattern, calling `ready_for_next_task.bb` instead.

## Script Location and Structure

The relevant files live in the `swarmforge/scripts/` directory:

| File | Purpose |
|------|---------|
| [`swarmforge/scripts/ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/ready_for_next.sh) | Zsh wrapper for batch-level hand-offs |
| `swarmforge/scripts/ready_for_next.bb` | Babashka implementation for batch mode |
| [`swarmforge/scripts/ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/ready_for_next_task.sh) | Zsh wrapper for task-level hand-offs |
| `swarmforge/scripts/ready_for_next_task.bb` | Babashka implementation for task mode |
| [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) | Protocol documentation referencing these scripts |
| [`swarmforge/scripts/swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.sh) | Main entry point that invokes ready_for_next helpers |

## Command-Line Usage

Both wrapper scripts accept a **single positional argument** specifying the mode. The argument is passed through to the underlying Babashka script.

```bash

# Mark current task complete and prepare next task (explicit)

./ready_for_next.sh task

# Mark current batch complete and prepare next batch

./ready_for_next.sh batch

# Omitting the argument defaults to 'task' mode

./ready_for_next.sh

```

The [`ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh) variant follows identical syntax but is specialized for finer-grained task operations per the hand-off protocol.

## Integration in Swarm-Forge Workflows

These helpers are typically invoked automatically by [`swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.sh) after work completes. You can also call them manually when:

- **Debugging** a stalled queue to force state progression
- **Scripting custom workflows** that need precise hand-off control
- **Recovering from failures** where automatic hand-off was interrupted

For example, embedding in a custom task runner:

```bash
#!/usr/bin/env zsh
set -euo pipefail

# Run your task logic here

echo "Executing custom analysis..."

# Notify Swarm-Forge that this task is finished

"$SWARM_FORGE_ROOT/swarmforge/scripts/ready_for_next_task.sh" task

```

## Relationship to the Hand-Off Protocol

The [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) mechanism implements the core contract documented in [`handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/handoff-protocol.md): work units signal completion through standardized scripts rather than direct file manipulation. This abstraction allows the protocol to evolve without breaking external callers.

The wrapper scripts ensure **consistent environment setup** (directory resolution, interpreter selection) before the Babashka runtime takes over for state mutations.

## Summary

- **ready_for_next.sh** and **ready_for_next_task.sh** are Zsh wrappers that delegate to Babashka implementations
- Accept `task` or `batch` arguments; default to `task` when omitted
- Update Swarm-Forge queue state by writing timestamps and advancing the active unit
- Located in `swarmforge/scripts/` alongside their `.bb` implementations
- Called automatically by [`swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.sh) or manually for debugging and custom workflows

## Frequently Asked Questions

### What is the difference between ready_for_next.sh and ready_for_next_task.sh?

**ready_for_next.sh** handles **batch-level** hand-offs in the Swarm-Forge queue, while **ready_for_next_task.sh** operates at **task-level** granularity. The batch variant manages groups of related tasks; the task variant handles individual work units. Both follow identical calling conventions and delegate to their respective `.bb` files.

### Can I run ready_for_next.sh without Babashka installed?

No. The wrapper script requires **Babashka** (`bb`) available on your `PATH` since it immediately delegates to `ready_for_next.bb`. The `.bb` files contain the actual state-management logic; the `.sh` files only handle directory resolution and process invocation.

### How does ready_for_next.sh handle errors?

The wrapper sets **shell options** (`set -euo pipefail` or equivalent Zsh constructs) to fail fast on errors. If the Babashka script exits non-zero, the wrapper propagates that status. This ensures queue corruption is caught immediately rather than silently proceeding to the next unit.

### Where is the queue state actually modified?

State changes occur in the **Babashka scripts** (`ready_for_next.bb` and `ready_for_next_task.bb`), not the shell wrappers. These `.bb` files write timestamps to `dequeued_at` markers and manipulate the queue directory structure under Swarm-Forge's data paths.