Reference

System map (cheat sheet)

Compressed picture of unclebob/swarm-forge for reimplementation. Details live in the repo; this is the map you pin to the wall.

Lesson 1 Lesson 2 Glossary Handoff lifecycle Handoff viz Lesson 3 Pack pipelines Mission Resources

One-sentence product

SwarmForge runs several AI coding CLIs locally—each in its own tmux session and usually its own git worktree—and coordinates them with a durable file handoff protocol plus role/constitution prompts that encode a software craftsmanship pipeline.

Three layers

1 · Runtime

swarmforge.bb: parse conf, git init/worktrees, tmux sessions, launch agent CLIs, terminal surfaces, window watchdog, sleep inhibitor, cleanup. State under .swarmforge/.

2 · Protocol

Outbox → handoffd → inbox; helpers swarm_handoff / ready_for_next / done_with_current. Message types: git_handoff, note. Durable queue; lossy wake-ups.

3 · Discipline

Constitution articles + role prompts + pack pipelines (two / four / six). Ownership boundaries, TDD, quality gates, always-forward chain rules. This is most of the “professional engineer” effect.

Repo shape

main (documentary + shared scripts)
├── swarmforge/scripts/*.bb     # launcher, daemon, handoff helpers
├── swarmforge/constitution/articles/  # shared engineering/handoffs/workflow
├── swarmforge/handoff-protocol.md
└── test/

two-pack | four-pack | six-pack (runnable)
├── ./swarm                     # bootstrap scripts from main, then launch
├── swarmforge/swarmforge.conf
├── swarmforge/constitution.prompt + articles/
└── swarmforge/roles/*.prompt

Startup sequence (condensed)

  1. Require tmux, git, bb, agent CLIs.
  2. Init git repo if needed; ensure ignores for .swarmforge/ and .worktrees/.
  3. Parse swarmforge.conf; write roles.tsv / sessions.tsv.
  4. Create worktrees + handoff directory trees per role.
  5. Create tmux sessions; sync scripts into each worktree; start handoffd.
  6. Launch each agent with constitution/role instructions on PATH.
  7. Open terminal surfaces (or attach); optional window watchdog.

Pack pipelines

Pack Roles (typical flow) Use when
two-pack coder → cleaner → coder Small backend tasks; no Gherkin/QA split
four-pack specifier → coder → refactorer → architect → specifier Spec + compact quality gates
six-pack specifier → coder → cleaner → architect → hardender → QA Full separation of review concerns

Handoff directories (per worktree)

.swarmforge/handoffs/
  outbox/          # agent writes via swarm_handoff (tmp/ then rename)
  sent/ failed/
  inbox/
    new/           # daemon delivers here
    in_process/    # ready_for_next claims work
    completed/     # done_with_current archives

Migration lens (early)

Primary sources