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

The 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 helper is part of the hand-off protocol in 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 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	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	Zsh wrapper for task-level hand-offs
swarmforge/scripts/ready_for_next_task.bb	Babashka implementation for task mode
swarmforge/handoff-protocol.md	Protocol documentation referencing these scripts
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.

# 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 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 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:

#!/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 mechanism implements the core contract documented in 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 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.

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