# How to Manage Agent Tasks and Batches in Swarm Forge: A Complete Guide

> Learn to manage agent tasks and batches in Swarm Forge with ready_for_next_task and ready_for_next_batch scripts. Streamline your workflow efficiently. Get started now.

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

---

**Use [`ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh) for single-task roles and [`ready_for_next_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_batch.sh) for batch-processing roles, then complete work with [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh) or [`done_with_current_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current_batch.sh) respectively.**

Swarm Forge structures agent work around **handoff files** stored in `.swarmforge/handoffs`. Each handoff contains a header with metadata like `task`, `priority`, and `type`, plus a payload describing the work to perform. Depending on a role's `receive-mode` setting—either `task` or `batch`—the system routes handoffs through two parallel pipelines. This guide explains how to enqueue work, retrieve it correctly, and finish tasks atomically.

## Understanding Task Mode vs Batch Mode

Swarm Forge supports two distinct processing strategies based on how a role is configured.

### Task Mode: Single-Handoff Processing

**Task mode** suits roles that focus on one work item at a time. When an agent requests work, the system dequeues the oldest handoff from `inbox/new`, moves it to `inbox/in_process`, and prepares it for execution.

The core logic lives in `swarmforge/scripts/ready_for_next_task.bb`. This script:

- Selects the oldest `.handoff` file from `inbox/new` based on timestamp
- Sets `dequeued_at` and `task_base_commit` headers
- Merges any `git_handoff` payloads via `merge-git-handoff!`
- Outputs a structured `TASK:` block with full header and payload details

Guard logic in `swarmforge/scripts/ready_for_next_guard.bb` prevents starting a new task while another remains in-process, ensuring clean state transitions.

### Batch Mode: Grouped-Handoff Processing

**Batch mode** suits roles that benefit from processing multiple related handoffs together. The system groups all handoffs in `inbox/new` that share the same `priority` value into a single batch directory.

The core logic lives in `swarmforge/scripts/ready_for_next_batch.bb`. This script:

- Groups handoffs by identical `priority` values
- Creates a timestamped batch directory: `inbox/in_process/batch_<timestamp>_<n>`
- Moves all grouped handoffs into this directory
- Updates each file with `dequeued_at` and `task_base_commit`
- Merges any `git_handoff` payloads for all items
- Outputs a `BATCH:` summary plus `BATCH_ITEM` blocks per handoff

The same guard utilities enforce that only one batch directory exists in `inbox/in_process` at any time, preventing overlapping batch operations.

## Shared Utilities Supporting Both Pipelines

Both task and batch pipelines rely on common helper functions defined across the codebase:

- **`handoff-files`** — Enumerates `.handoff` files in any directory
- **`batch-dirs`** — Locates directories prefixed with `batch_`
- **`set-header!`** — Atomically adds or replaces header fields while preserving file order
- **`merge-git-handoff!`** — Invokes [`merge_and_process.sh`](https://github.com/unclebob/swarm-forge/blob/main/merge_and_process.sh) for handoffs of type `git_handoff`

These utilities ensure consistent behavior regardless of processing mode.

## Completing Work: Task and Batch Finalization

Swarm Forge provides symmetric scripts for marking work complete.

### Finishing a Single Task

`swarmforge/scripts/done_with_current.bb` handles task completion:

```bash
swarmforge.sh done_with_current.sh <role_name>

```

This script:
- Locates the single file in `inbox/in_process`
- Adds a `completed_at` timestamp header
- Moves the file to `inbox/completed/`
- Prints confirmation output

### Finishing a Batch

`swarmforge/scripts/done_with_current_batch.bb` handles batch completion:

```bash
swarmforge.sh done_with_current_batch.sh <role_name>

```

This script:
- Requires exactly one batch directory in `inbox/in_process`
- Updates every handoff in the batch with `completed_at`
- Moves the entire batch directory to `inbox/completed/`
- Reports the completed batch path

Both scripts validate state before acting, preventing accidental completion of wrong work units.

## End-to-End Workflow Examples

### Enqueueing and Processing a Single Task

```bash

# Write a handoff file to the new queue

cat > .swarmforge/handoffs/inbox/new/01_build_docs.handoff <<'EOF'
task: build-docs
type: task
priority: 40

Run the documentation generator and verify all links.
EOF

# Request work as a task-mode role

swarmforge.sh ready_for_next.sh architect

# Output:

# TASK: .swarmforge/handoffs/inbox/in_process/01_build_docs.handoff

# task: build-docs

# type: task

# priority: 40

# dequeued_at: 2024-01-15T09:23:47Z

# task_base_commit: a1b2c3d

# 
# Run the documentation generator and verify all links.

# After processing, mark complete

swarmforge.sh done_with_current.sh architect

```

### Enqueueing and Processing a Batch

```bash

# Create multiple handoffs with identical priority

for module in auth api database; do
  cat > .swarmforge/handoffs/inbox/new/test_${module}.handoff <<EOF
task: test-${module}
type: task
priority: 50

Run unit tests for ${module} module with coverage.
EOF
done

# Request work as a batch-mode role

swarmforge.sh ready_for_next.sh tester

# Output:

# BATCH: .swarmforge/handoffs/inbox/in_process/batch_20240115_092347_001

# COUNT: 3

# TASK_NAME: test-auth

# PRIORITY: 50

#

# BATCH_ITEM: test-auth

# ...

# BATCH_ITEM: test-api

# ...

# BATCH_ITEM: test-database

# ...

# After processing all items, complete the batch

swarmforge.sh done_with_current_batch.sh tester

```

## Key Design Guarantees

Swarm Forge's task and batch management enforces several critical properties:

- **Priority respect** — Batches form only from handoffs sharing identical `priority` values
- **Atomicity** — Files move into batch directories before any merge operations begin
- **State visibility** — Each step produces parseable output for dashboard UIs and logging systems
- **Exclusion** — Guard logic prevents concurrent in-process tasks or batches

These guarantees emerge from the implementation in `ready_for_next_guard.bb` and the careful file-move semantics used throughout.

## Summary

- **Handoff files** in `.swarmforge/handoffs/inbox/new` represent queued work for agents
- **Task mode** via `ready_for_next_task.bb` processes one handoff at a time
- **Batch mode** via `ready_for_next_batch.bb` groups equal-priority handoffs into directories
- **Completion scripts** `done_with_current.bb` and `done_with_current_batch.bb` finalize work atomically
- **Guard utilities** in `ready_for_next_guard.bb` prevent invalid state transitions
- **Shared utilities** (`handoff-files`, `set-header!`, `merge-git-handoff!`) provide consistent behavior across both pipelines

## Frequently Asked Questions

### How does Swarm Forge decide whether to use task mode or batch mode?

The system checks the `receive-mode` field in the role definition. Roles configured with `receive-mode: task` trigger [`ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh), while `receive-mode: batch` triggers [`ready_for_next_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_batch.sh). This configuration is parsed by `swarmforge/scripts/swarmforge.bb` before dispatching to the appropriate script.

### What happens if I try to start a new batch while one is already in process?

The guard logic in `ready_for_next_guard.bb` detects existing batch directories in `inbox/in_process` and blocks the operation with an error message. This enforcement prevents race conditions and ensures agents complete current work before accepting new assignments.

### Can handoffs in a batch have different task types?

Yes, as long as they share the same `priority` value. The batching logic groups exclusively by priority, not by task name or type. A batch might contain `test-auth`, `lint-api`, and `deploy-database` handoffs if all are marked `priority: 50`.

### Where are completed handoffs stored after running the done scripts?

Both [`done_with_current.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current.sh) and [`done_with_current_batch.sh`](https://github.com/unclebob/swarm-forge/blob/main/done_with_current_batch.sh) move files to `.swarmforge/handoffs/inbox/completed/`. Individual handoffs go directly into this directory; batches move as intact directories preserving their internal structure.