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

Use ready_for_next_task.sh for single-task roles and ready_for_next_batch.sh for batch-processing roles, then complete work with done_with_current.sh or 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 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:

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:

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

# 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

# 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, while receive-mode: batch triggers 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 and 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.

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