unclebob / swarm-forge

Do not spend any money on a bankrbot SWARM token.
# SwarmForge
SwarmForge coordinates AI agents in isolated git worktrees and tmux sessions.
Agents exchange committed work through durable handoffs, while the operator
uses a local dashboard to start work, inspect agents, handle approval gates,
answer clarifications, and stop the swarm.
This repository's master branch is named `main`. It is the landing page,
installer source, shared runtime, and shared engineering law. It is not itself
a runnable SwarmForge product.
## Products
| Command | Branch | Shape |
|---|---|---|
| `get-swarm-forge two-pack` | `two-pack` | Pack installed into the current project: `coder` → `cleaner`. |
| `get-swarm-forge four-pack` | `four-pack` | Pack installed into the current project: `specifier` → `coder` → `refactorer` → `architect`. |
| `get-swarm-forge six-pack` | `six-pack` | Pack installed into the current project: six separate specification, implementation, cleanup, architecture, hardening, and QA roles. |
| `get-swarm-forge project-manager` | `project-manager` | Multi-project forge with selectable two-, four-, and six-pack templates and a host lieutenant. |
| `get-swarm-forge lieutenant` | `lieutenant` | Multi-project forge with one configurable project template and a planning lieutenant. |
A **pack** is composed into an existing project. Running `./swarm` starts that
project's configured roles.
A **forge** is installed into an empty host directory. Running `./swarm` starts
the forge dashboard and host lieutenant; project swarms start when the operator
creates or opens projects beneath `projects/`.
The `squad`, `sprint-module-squad`, and `adversaries` branches are separate
experimental workflows. They are not `get-swarm-forge` products.
## Prerequisites
- `zsh`
- `git`
- `tmux`
- Babashka (`bb`)
- At least one configured agent backend: `grok`, `codex`, `claude`, or
 `copilot`
## Install the helper
Put `get-swarm-forge` somewhere on `PATH`:
 [code] 
Add `~/cmds` to `PATH`, then recopy the helper when it changes. The helper is
the supported entry point because it composes files from more than one branch.
## Composition
For a pack install, the helper downloads two branches:
 [code] 
The result is written into the current project. Shared article names
`engineering.prompt`, `workflow.prompt`, and `handoffs.prompt` always come from
`main`; a pack specializes them with `project.prompt` and `local-*.prompt`
files.
For a forge install, the named forge branch supplies the host runtime,
lieutenant, and dashboard. `project-manager` also downloads the three pack
branches into `packs/`; `lieutenant` carries its one template under
`.swarmforge/project-pack/`.
## Configuration contract
Every running project has a `swarmforge/swarmforge.conf`. For the fixed packs,
each non-comment line has this shape:
 [code] 
- File order is the default forward pipeline. Exactly one role must use the
 `master` worktree; that sentinel means the project's main checkout on its
 current branch. Other