How to Use the `done_with_current.sh` Helper Script in Swarm‑Forge

done_with_current.sh signals task completion by writing a "done" flag to the workspace hand‑off directory, triggering the swarm hand‑off daemon to coordinate the next task.

The done_with_current.sh utility script is part of the Swarm‑Forge orchestration system developed by Uncle Bob. Located at swarmforge/scripts/done_with_current.sh, this lightweight helper enables workers to mark their assigned work as finished, allowing the distributed system to progress through tasks or batches without manual intervention.

What done_with_current.sh Does

When executed, the script performs four core operations that integrate with the broader Swarm‑Forge hand‑off protocol:

• Writes a completion flag to .swarmforge/handshake — the shared directory where status files are exchanged
• Triggers the hand‑off daemon by touching a done sentinel file, waking swarmforge/scripts/swarm_handoff.sh to process the transition
• Cleans temporary state by removing lock files created for the current task
• Returns an exit code — zero for success, non‑zero for failure detection by surrounding automation

This file‑based design ensures reliability across isolated containers and remote workers, as the script never calls external services directly.

Basic Usage

Run the script from within your Swarm‑Forge workspace after completing the assigned task:

./swarmforge/scripts/done_with_current.sh

On success, the script exits silently with status 0. The hand‑off daemon then evaluates whether to fetch a new task, start a fresh batch, or shut down the swarm.

Integration Examples

CI/CD Pipeline Step

In a GitHub Actions workflow, chain your task execution with the completion signal:

steps:
  - name: Checkout repository
    uses: actions/checkout@v4

  - name: Execute Swarm‑Forge task
    run: |
      ./swarmforge/scripts/swarm_tool.sh process_batch

  - name: Signal task completion
    run: ./swarmforge/scripts/done_with_current.sh

Error Handling in Shell Scripts

Detect completion failures for retry logic or alerting:

if ! ./swarmforge/scripts/done_with_current.sh; then
  echo "ERROR: Failed to signal completion to Swarm‑Forge"
  notify_ops_team "Hand-off failed for worker $WORKER_ID"
  exit 1
fi

Chaining Multiple Workers

When orchestrating dependent workers, ensure each completes before the next begins:

# Worker A finishes and signals

./swarmforge/scripts/done_with_current.sh

# Worker B waits for hand-off, then starts

./swarmforge/scripts/ready_for_next.sh
./swarmforge/scripts/swarm_tool.sh next_task

Related Files and Architecture

File	Purpose
swarmforge/scripts/done_with_current.sh	The helper script that marks tasks complete and triggers hand‑off
swarmforge/scripts/swarm_handoff.sh	Daemon watching handshake files to coordinate transitions
swarmforge/scripts/ready_for_next.sh	Worker script indicating readiness for new tasks post‑hand‑off
swarmforge/handoff-protocol.md	Protocol documentation defining the file‑based communication mechanism

These components implement the Swarm‑Forge state machine: workers signal completion via done_with_current.sh, the swarm_handoff.sh daemon processes the transition, and workers re‑enter the pool via ready_for_next.sh.

Summary

• done_with_current.sh writes completion flags to .swarmforge/handshake and triggers the hand‑off daemon
• The script is stateless and service‑less, relying entirely on filesystem operations for reliability
• Exit codes enable automation to detect success or failure
• Integration requires only execution from the workspace directory — no configuration arguments needed
• The hand‑off protocol ties together done_with_current.sh, swarm_handoff.sh, and ready_for_next.sh for robust distributed coordination

Frequently Asked Questions

Where is done_with_current.sh located in the Swarm‑Forge repository?

The script resides at swarmforge/scripts/done_with_current.sh in the unclebob/swarm-forge repository. This placement alongside swarm_handoff.sh and ready_for_next.sh reflects its role in the hand‑off protocol workflow.

Does done_with_current.sh require any command‑line arguments?

No. The script operates without arguments, detecting its context from the workspace structure and environment. It assumes execution from within a Swarm‑Forge workspace where .swarmforge/handshake is accessible.

What happens if the hand‑off daemon is not running when I execute done_with_current.sh?

The script will still write the completion flag and touch the sentinel file. The swarm_handoff.sh daemon processes these files when it starts or on its next polling cycle. This asynchronous design ensures signals are not lost due to temporary daemon unavailability.

How does Swarm‑Forge distinguish between successful completion and failure?

done_with_current.sh returns a zero exit status on success and non‑zero on failure. Surrounding automation — whether shell scripts, CI/CD pipelines, or container orchestrators — should check this exit code. The hand‑off protocol itself does not encode task success semantics; it only signals that the worker has finished its current assignment.

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