Reference

SwarmForge glossary

Shared vocabulary for this workspace. Lessons stick to these meanings. Primary source: the swarm-forge repo under /tmp.

Lesson 1 Lesson 2 Lesson 3 Pack pipelines System map Handoff lifecycle Handoff viz Mission Resources
SwarmForge
Local, tmux-based agent orchestration: one process surface per role, git isolation via worktrees, and handoffs for coordination. Not a cloud agent platform.
main branch (documentary)
Carries shared operational scripts, default constitution articles, and protocol docs. Not the pack you drop into a product repo; runnable configs live on pack branches.
Pack (runnable branch)
A workflow shape with fixed roles and handoff chain: two-pack, four-pack, six-pack. Each has its own swarmforge.conf, role prompts, and local constitution. ./swarm pulls scripts from main when missing.
Role
Named agent identity (e.g. coder, cleaner). Maps to one config line, one prompt file (swarmforge/roles/<role>.prompt), usually one worktree and one tmux session. Role names must not contain underscores (filename/audit constraint).
Constitution
Shared behavioral law. Entry point swarmforge/constitution.prompt points agents at article files under constitution/articles/. Shared defaults on main; packs can add local-* or override by same filename.
swarmforge.conf
Project-local topology file. Lines: window <role> <agent> <worktree> [task|batch] [extra-cli-args…]. First window is the cleanup window.
Agent backend
CLI that runs in a role’s session: claude, codex, copilot, or grok. Chosen per role in the config.
Worktree
Git worktree under .worktrees/<name> for a role, or the main checkout when worktree is master / none. Keeps concurrent roles from editing the same files blindly.
Handoff
Durable, file-based work message between roles. Two types only: git_handoff and note. Agents draft headers; helpers generate bodies and queue files.
git_handoff
Points a recipient at a committed git state (exactly 10 hex chars, validated). Body becomes instructions like merge_and_process <role> <commit>. Primary pipeline message.
note
One short freeform line (max 80 chars). Constitution says: do not send unless user/role/constitution explicitly directs; prefer stopping to ask when blocked.
handoffd (handoff daemon)
Babashka process that polls each role outbox/, copies validated handoffs into recipient inbox/new/, and sends a generic tmux wake-up. Sole owner of tmux socket access for delivery.
Outbox / inbox
Per-worktree dirs under .swarmforge/handoffs/. Outbox is producer queue; inbox is consumer queue (new → in_process → completed). Also sent/ and failed/ on the sender side.
Receive mode (task | batch)
How a role accepts inbox work. task: one handoff at a time. batch: all equal-priority queued handoffs as one unit. Configured on the window line; runtime copy in .swarmforge/roles.tsv.
Wake-up (lossy notify)
Generic tmux send-keys text telling an idle agent to run ready_for_next.sh. Intentionally lossy: busy agents ignore; completion helpers re-check the durable queue.
Cleanup window
First role in swarmforge.conf. Closing it runs swarm teardown (tmux sessions, tracked terminal windows, handoff daemon). Closing other windows is non-destructive if the watchdog can reopen them.
Runtime state (.swarmforge/)
Project-local non-git state: sockets, roles/sessions TSV, daemon PID, handoff dirs, prompts generated at launch. Agents must not stage or commit this.
Three layers
Teaching model for this track: (1) Runtime — processes, tmux, terminals, worktrees; (2) Protocol — handoff files, daemon, queue helpers; (3) Discipline — constitution, roles, pack pipelines. A rewrite can swap layer 1 freely if 2 and 3 stay coherent.