Using Bones Swarm

Using bones swarm

bones swarm is the slot-scoped session primitive. One swarm session = one leaf = one worktree + one claimed task + one open hub branch. This skill walks you through the 5-step lifecycle.

Prerequisite: a bones workspace (.bones/repo.fossil exists in cwd or a parent). If missing, run bones up first.

The lifecycle

1. swarm join    →  open a leaf, claim a task, prepare a worktree (atomic)
2. swarm cwd     →  navigate to the worktree
3. work          →  edit files; make changes
4. swarm commit  →  heartbeat the session + commit (repeat as needed)
5. swarm close   →  release claim, post result, stop the leaf

Step 1: Join

bones swarm join --slot=<slot-name> --task-id=<task-id>

What this does (atomically):

• Opens a new leaf in the hub for the given slot.
• Claims the named task in bones tasks (fails if already claimed or closed).
• Prepares a worktree on disk for that leaf.
• Registers the swarm session so swarm status and swarm cwd can find it.

Recovery: if a previous swarm session is stuck (crashed agent, stale lock):

bones swarm join --slot=<slot> --task-id=<id> --force

This clobbers the existing slot session. Use only when you're sure nothing else is using that slot.

Step 2: Navigate

cd "$(bones swarm cwd --slot=<slot-name>)"

Or capture the path once:

WORKTREE=$(bones swarm cwd --slot=<slot-name>)
cd "$WORKTREE"

Step 3: Work

Edit files. The worktree is a normal filesystem checkout — your editor and tools work as usual.

If you need to verify the workspace is clean:

bones repo status

Step 4: Commit and heartbeat

Every meaningful save during the session:

bones swarm commit -m "<message>" [files...]

This commits and emits a heartbeat. The hub knows the session is alive. Repeat as often as you'd commit normally.

If you only want to commit (not heartbeat — rare), use bones repo ci -m "…" <files> directly. Prefer swarm commit while inside a session.

Step 5: Close

When work is done:

bones swarm close --result=success --summary="<one-line result>"

This releases the claim, posts the result to the task's thread, and stops the leaf. The leaf remains in the hub (open for fan-in).

If the work is incomplete or failed:

bones swarm close --result=fail --summary="<reason>"

Releases the claim so another worker (or another attempt) can pick the task back up.

Composition

This skill is a primitive used by other bones-powers skills:

• bones-powers:executing-plans (single-session inline) — invokes the lifecycle once per task.
• bones-powers:subagent-driven-development — invokes the lifecycle per implementer subagent (one per slot, in parallel).
• bones-powers:dispatching-parallel-agents — N concurrent invocations across N slots.
• bones-powers:finishing-a-bones-leaf — what happens AFTER swarm close: fan-in, keep, or abandon.

Common pitfalls