SwarmForge Branch Structures: Two-Pack, Four-Pack, and Six-Pack Explained

SwarmForge provides three "pack" branches—two-pack, four-pack, and six-pack—that define distinct AI-driven development workflows with 2, 4, or 6 specialized roles respectively.

Each pack in unclebob/swarm-forge is a complete Git branch containing a ready-to-run swarmforge/ directory with configuration files, role prompts, and local constitution articles. The get-swarm-forge helper script installs all three packs into a local packs/ directory, allowing you to choose the workflow that matches your project's size and rigor.

Two-Pack: Fast Backend Tasks

The two-pack branch targets small, fast-turnaround backend work with minimal ceremony.

Aspect	Details
Roles	coder → cleaner → Done
Flow	No specification phase; coder writes code with TDD, cleaner performs batch cleanup and review
Cleanup scope	DRY/CRAP analysis, architectural hints, merge-only copy back to coder

As documented in README.md lines 21-30, the two-pack eliminates upfront specification to maximize velocity. The cleaner's responsibilities include behavior-preserving refactoring, coverage improvement, and sending a merge-only copy back to the coder before the card moves to Done.

To initialize a two-pack project:

mkdir my-forge && cd my-forge
get-swarm-forge
./swarm

# Select "New Project" → choose "two-pack"

Four-Pack: Gherkin-Driven Moderate Projects

The four-pack branch adds structured specification and architectural oversight for projects requiring acceptance criteria.

Role sequence:

1. specifier — creates approved Gherkin acceptance specifications
2. coder — implements with TDD and generated acceptance tests
3. refactorer — cleans up while preserving behavior, sends merge-only copy back to coder
4. architect — reviews high-level structure, dependencies, and mutation hardening, sends merge-only copies to all earlier roles

The refactorer's back-propagation and the architect's broadcast pattern are core to the four-pack's feedback design. Per README.md lines 31-40, this structure suits moderate projects where specification clarity matters but full enterprise rigor isn't required.

Example swarmforge.conf for invisible four-pack windows:

window-invisible specifier codex master --yolo
window-invisible coder     grok  coder
window-invisible refactorer grok  refactorer back-one
window-invisible architect  codex architect batch back-all --yolo

This configuration matches the example in README.md lines 56-63, showing how back-propagation directives (back-one, back-all) control merge-only feedback without moving the card.

Six-Pack: Enterprise-Grade Development

The six-pack branch provides maximum rigor for large projects requiring dedicated QA and mutation hardening.

Added roles	Responsibilities
cleaner	Behavior-preserving cleanup, coverage improvement (sequential with coder)
hardender	Mutation hardening, language-specific mutation checks
QA	End-to-end verification scripts, final completion notification

Following the README.md documentation at lines 41-52, the six-pack sequence is:

specifier → coder → cleaner → architect → hardender → QA → Done

Both architect and QA send merge-only copies to every earlier role, ensuring all participants stay synchronized on structural decisions and final verification results. This broadcast pattern scales the hand-off protocol for complex, multi-stakeholder workflows.

The Hand-Off Protocol: Shared Across All Packs

All three packs implement identical hand-off semantics defined in swarmforge/handoff-protocol.md:

• A card advances only when the last role issues a Git hand-off
• Back-one: merge-only copy to immediate predecessor (does not move card)
• Back-all: merge-only copy to all earlier roles (does not move card)

This deterministic design prevents race conditions while allowing continuous refinement. The protocol is validated in test/swarmforge/pack_ui_test.clj, which verifies pack installation and role wiring—including this assertion for four-pack correctness:

(is (str/includes? 
     (slurp (str (fs/path dest ".swarmforge/pack"))) 
     "four-pack"))

Installing and Selecting Packs

The get-swarm-forge script automates multi-pack setup:

# One-time installation

cp get-swarm-forge ~/cmds/
chmod +x ~/cmds/get-swarm-forge

# Per-forge initialization

mkdir my-forge && cd my-forge
get-swarm-forge  # clones main, checks out two-pack/four-pack/six-pack

The script:

1. Clones main branch for shared scripts and constitution articles
2. Checks out all three pack branches
3. Copies host scripts to swarmforge/ and pack files to packs/<pack-name>/
4. Creates empty projects/ directory

After running ./swarm, the dashboard presents radio buttons for pack selection. The chosen pack's swarmforge/conf file defines concrete role wiring through window or window-invisible declarations.

Summary

• Two-pack (coder → cleaner): No specification, fastest turnaround for backend tasks
• Four-pack (specifier → coder → refactorer → architect): Gherkin specs with architectural review
• Six-pack (specifier → coder → cleaner → architect → hardender → QA): Full enterprise rigor with mutation hardening and dedicated QA

All packs share the same hand-off protocol and are installed together via get-swarm-forge. Configuration lives in per-branch swarmforge/conf files, with behavior validated by test/swarmforge/pack_ui_test.clj.

Frequently Asked Questions

What determines which SwarmForge pack to choose?

Select based on project size and required rigor. Two-pack suits small backend tasks needing no specification. Four-pack fits moderate projects requiring Gherkin acceptance criteria and architectural review. Six-pack addresses enterprise work demanding mutation hardening, dedicated QA automation, and comprehensive verification. The same repository supports all three via branch-based isolation.

How do back-one and back-all differ in pack workflows?

Back-one sends a merge-only copy to the immediate preceding role—common when a refactorer wants the coder to see cleanup changes without moving the card. Back-all broadcasts merge-only copies to every earlier role—used by architects and QA in four-pack and six-pack to synchronize structural or verification decisions across the entire chain. Neither action advances the card; only the terminal role's hand-off moves work to Done.

Can I customize role definitions within a pack?

Yes. Each pack branch contains swarmforge/conf with window or window-invisible declarations specifying LLM provider, model, and back-propagation settings. Modify these before creating projects, or create new pack branches with alternative configurations. The get-swarm-forge script will include custom branches if they follow the *-pack naming convention.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}