Agentic Engineering

SwarmForge: What Uncle Bob's Agent Swarm Gets Right

SwarmForge runs several AI coding agents in tmux windows, each in its own git worktree, each holding exactly one engineering role. The tooling is deliberately boring. The interesting part is the org chart it encodes.

Talk to Our AI Engineering Team View AI Development Services

What SwarmForge Actually Is

SwarmForge is a shell and Babashka harness around three primitives most teams already have: tmux windows, git worktrees, and prompt files. Each window runs one agent in one role against its own worktree under .worktrees/, so two agents never fight over the same working tree. Behaviour comes from plain text at swarmforge/roles/<role>.prompt, layered on a shared constitution.prompt and its articles. Agents do not type into each other's terminals; they queue validated handoffs through .swarmforge/handoffs/, and the payload is either a ten-character commit abbreviation or a note of at most eighty characters. Backends are chosen per role, so one session can mix Claude, Codex, Copilot, and Grok.

The main branch is documentary. The runnable swarms live on the two-pack, four-pack, and six-pack branches: you pull down the branch whose shape you want and run ./swarm. Prerequisites are zsh, git, tmux, Babashka, and a configured agent CLI.

Three Swarm Shapes

Each branch is a different answer to how much process a task deserves. The flow is a ring, not a queue: work comes back around.

two-pack

coder → cleaner → coder

A coder working test-first and a cleaner doing cleanup, CRAP and DRY review, and architectural fixes. The smallest useful loop: write it, then hand it to someone who is not attached to it.

four-pack

specifier → coder → refactorer → architect → specifier

Gherkin acceptance specs enter at the front. A refactorer does behaviour-preserving cleanup and coverage, and an architect reviews structure and dependency direction before the ring returns to specification.

six-pack

specifier → coder → cleaner → architect → hardener → QA

Adds a hardening pass that mutates the code to find blind spots, and a QA role that runs executable verification. This is the shape that treats quality as separate concerns rather than one agent's good intentions.

One Agent, One Discipline

The roles are the argument. Every one of them is a job that normally gets squeezed into the same person, in the same hour, under the same deadline.

specifier

Writes Gherkin acceptance specs and QA procedures. Nothing enters the swarm as a vague sentence, which is the failure mode most agent workflows never recover from.

coder

Implements test-first. The role prompt, not a policy page nobody reads, is what makes TDD the default behaviour for this window.

cleaner

Local cleanup, coverage, CRAP and DRY review. Naming and duplication get a dedicated pass instead of a review comment nobody ever actions.

architect

Module structure, boundaries, dependency direction. The only role allowed to care about the shape of the whole rather than the ticket in front of it.

hardening role

Mutation hardening: perturb the code and find out where the suite is blind. A negative check, deliberately placed after the code is already clean.

QA

Executable verification scripts and notifications. Verification is something that runs and reports, not a feeling that the change looked fine.

How the Coordination Works

Three files and three scripts carry the whole protocol. That is the point: the topology is data, and the discipline is text.

The topology is one config file

conf

Each line declares a tmux window: which role, which agent backend, which worktree, and whether it receives work per task or in batches.

# swarmforge/swarmforge.conf
# window <role> <agent> <worktree> [task|batch] [extra-cli-args...]
window coordinator codex master
window coder       codex coder
window architect   codex architect

Handoffs are validated, not chatted

An agent queues an outbound handoff, the next role accepts work when it is free, and closing the current item is an explicit act. The payload is a commit or a very short note, so the code has to carry the meaning.

# queue work for the next role: a commit, or a note of <= 80 chars
./swarm_handoff.sh coder 4f2a9c1b0d "boundary rule now specified"

# on the receiving side
./ready_for_next.sh      # accept the next item or batch
./done_with_current.sh   # close it out and free the window

The standard lives in the prompt tree

text

Shared articles hold engineering rules, handoff rules, and workflow; local articles are where a project overrides them. Role prompts sit on top. Your coding standard becomes an input to the work rather than a document about it.

swarmforge/
  swarmforge.conf
  constitution.prompt
  constitution/articles/
    engineering.prompt
    handoffs.prompt
    workflow.prompt
    project.prompt
    local-engineering.prompt
    local-workflow.prompt
  roles/
    <role>.prompt

What to Borrow Even If You Never Run It

Give each pass a name and a single job

- Split specification, implementation, cleanup, structure, and verification into separate passes with separate instructions
- Stop asking one agent, or one engineer, to hold all five concerns at once
- Name the pass in the pull request so reviewers know which questions are already answered

Isolate the workspace, not just the branch

- A git worktree per role removes the whole class of failures where two agents edit the same file at once
- Isolation makes parallel work legible: every role has a tree you can inspect independently
- The same trick works for one engineer running several agents locally, with no swarm involved

Make handoffs narrow and validated

- A commit reference plus one short line forces intent into the code and the message
- Validation at the handoff boundary catches a malformed request before the next role wastes a run on it
- Narrow handoffs are auditable: you can reconstruct who passed what, and when

Keep the standard where the work happens

- Engineering rules written as prompt articles are read on every task, unlike a wiki page
- Separate shared rules from project-local overrides so one team's exception does not become everyone's rule
- Version the rules with the code, and review changes to them like code

Where the Honest Caveats Are

The ring costs what the ring costs

Six roles reviewing each other's work means several agent runs per change. On small tasks the two-pack loop is usually the rational choice; the six-pack is for work whose defects would be expensive.

Eighty characters is a small pipe

The tiny handoff payload is a discipline: the commit has to explain itself. It also means the swarm's shared understanding lives entirely in specs and code. If your codebase does not already explain itself, the swarm will not fix that for you.

Roles are prompts, not guarantees

A prompt that says use TDD is a strong nudge, not an enforcement mechanism. The gates that actually hold are executable: the test run, the mutation run, the QA script. Keep those in CI, not only in the swarm.

Somebody still signs off

Swarm output is a change proposal, not a release decision. Accountability does not distribute across tmux windows, and the reviewer's job gets harder, not easier, when the volume of plausible code goes up.

The Workflow Is the Contribution

Strip away tmux, Babashka, and the tarball install, and SwarmForge is a claim about software engineering: the disciplines that keep code habitable are separable, and each one deserves its own turn with its own instructions. That claim was true before agents, which is exactly why it transfers.

Read it as a reference implementation rather than a platform. Adopt the role decomposition, the worktree isolation, and the validated handoff, and you get most of the value whether the work is done by six agents, two engineers, or one of each.

FAQ

What do you need to run SwarmForge?

zsh, git, tmux, and Babashka, plus a configured agent CLI such as Claude, Codex, Copilot, or Grok. There is no cloud service and no orchestration layer to stand up: the swarm is tmux windows you can watch, with per-role worktrees on disk.

Which branch should a team start with?

two-pack. Two roles are enough to feel whether the handoff discipline suits your work, and the cost of a full six-role ring is hard to justify before you know that.

Does an agent swarm remove the need for QA?

No. It relocates QA into a named role with executable scripts, which is an improvement over leaving it implicit, but the verification still has to be written by someone who understands what the product owes its users.

Is this production-ready orchestration?

Treat it as a workflow reference rather than a managed platform. The durable value is the decomposition of engineering concerns and the narrow handoff protocol, and both can be adopted independently of the shell scripts.