Pre-Configured SwarmForge Workflow Branches: Two-Pack, Four-Pack, and Six-Pack Explained

SwarmForge provides three pre-configured workflow branches—two-pack, four-pack, and six-pack—that define specific role sequences and hand-off protocols for different project sizes and quality requirements.

The unclebob/swarm-forge repository ships with three distinct Git branches that implement ready-to-use AI agent workflows. These SwarmForge workflow branches eliminate setup overhead by providing tailored configurations, role prompts, and hand-off sequences for everything from rapid prototyping to production-grade development pipelines.

The Three Pre-Configured Workflow Branches

Each branch lives in its own Git branch (e.g., two-pack, four-pack, six-pack) and contains a tailored swarmforge/swarmforge.conf plus role prompt files. The main branch only holds shared scripts and default constitution articles; the runnable branches provide the concrete workflow configuration.

Two-Pack: Fast Backend Development

The two-pack branch targets small tasks that require quick coding without Gherkin specifications or dedicated QA steps. This lightweight workflow cycles between implementation and refinement.

Core Role Sequence: coder → cleaner → coder

In this loop, the coder implements the initial solution, the cleaner refactors and hardens the code, and the work returns to the coder for final verification. According to the repository's swarmforge/handoff-protocol.md, this is the minimal viable workflow for rapid backend iterations.

Four-Pack: Compact Specification Workflow

The four-pack branch supports medium-size projects that require Gherkin acceptance specifications and a single architectural review checkpoint.

Core Role Sequence: specifier → coder → refactorer → architect → specifier

This sequence enforces specification-first development: the specifier writes Gherkin acceptance criteria, the coder implements, the refactorer cleans the implementation, the architect reviews structural soundness, and control returns to the specifier for validation. You can inspect the exact window assignments in swarmforge/swarmforge.conf on the four-pack branch.

Six-Pack: Full-Featured Pipeline

The six-pack branch implements a comprehensive workflow for large projects requiring dedicated QA, mutation hardening, and full architectural oversight.

Core Role Sequence: specifier → coder → cleaner → architect → hardender → QA → completion

This end-to-end pipeline includes specialized roles like the hardender (for mutation testing and robustness checks) and QA (for final quality verification), making it suitable for critical production systems where multiple validation gates are mandatory.

Shared Architecture Across Branches

All three SwarmForge workflow branches share the same underlying architecture while maintaining branch-specific configurations:

• Shared Operational Scripts – Copied from the main branch on first run from swarmforge/scripts/.
• Configuration File – swarmforge/swarmforge.conf lists each window/role and its backend (e.g., window coder codex coder).
• Role Prompt Files – Located under swarmforge/roles/<role>.prompt, these contain the system prompts that drive each AI agent.
• Constitution Articles – Default articles live in swarmforge/constitution/articles/ on main; each runnable branch can add local-*.prompt files to extend or override them.

The hand-off protocol that ties these roles together is defined in swarmforge/handoff-protocol.md, which specifies the message formats and the "normal flow" line for each pack (e.g., - \two-pack`: `coder` -> `cleaner` -> `coder``).

Setting Up and Running a Workflow Branch

To initialize a specific workflow branch, download and extract the branch archive, then launch the swarm:

# Choose the desired workflow branch

BRANCH=two-pack   # or four-pack, six-pack

# Download and extract the branch into the current directory

curl -L "https://github.com/unclebob/swarm-forge/archive/refs/heads/${BRANCH}.tar.gz" \
  | tar -xz --strip-components=1

Start the swarm after unpacking:

./swarm               # launches tmux sessions and opens terminals per role

Inspect the generated configuration to verify the role sequence:

cat swarmforge/swarmforge.conf

# Expected output for four-pack (excerpt):

# window specifier codex specifier

# window coder     codex coder

# window refactorer codex refactorer

# window architect codex architect

Execute hand-offs between roles using the protocol scripts:

# Inside the coder's worktree:

swarm_handoff.sh draft.txt   # validates and queues the handoff

# In the refactorer's worktree:

ready_for_next.sh            # pulls the queued handoff

Summary

• SwarmForge workflow branches are isolated Git branches (two-pack, four-pack, six-pack) that provide complete, runnable configurations.
• The two-pack offers a minimal coder → cleaner → coder loop for rapid backend tasks.
• The four-pack adds specification and architecture gates with a five-role sequence.
• The six-pack provides the full pipeline including hardening and QA for enterprise-grade workflows.
• Each branch contains swarmforge/swarmforge.conf defining roles and swarmforge/roles/<role>.prompt files containing agent instructions.
• The swarmforge/handoff-protocol.md file standardizes the message formats and hand-off sequences across all branches.

Frequently Asked Questions

What is the difference between two-pack and four-pack workflows?

The two-pack workflow omits formal specification and architectural review, running a tight loop between coding and cleaning for rapid prototyping. The four-pack introduces a specifier role for Gherkin acceptance criteria and an architect role for structural review, making it suitable for medium-complexity features that require documentation and design validation.

How do I switch between workflow branches in SwarmForge?

Each workflow exists as a separate Git branch in the unclebob/swarm-forge repository. To switch workflows, download the desired branch archive using curl with the branch name (e.g., four-pack), extract it into a fresh directory, and run ./swarm. The branches are mutually exclusive deployments rather than runtime configurations.

Can I customize the role sequence in a workflow branch?

Yes. While each branch provides a default sequence in swarmforge/swarmforge.conf, you can modify the window declarations and role assignments in that file. Additionally, you can add local-*.prompt files to override default constitution articles from the main branch, or edit the individual swarmforge/roles/<role>.prompt files to adjust agent behavior.

Where are the hand-off protocols defined?

The hand-off protocols are defined in swarmforge/handoff-protocol.md on the main branch. This document specifies the message formats, validation rules, and the "normal flow" sequences for each pack. The actual hand-off execution relies on scripts like swarm_handoff.sh and ready_for_next.sh that implement the protocol defined in this file.

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