Two-Pack, Four-Pack, and Six-Pack Workflows in SwarmForge: Choosing the Right Agent Topology

SwarmForge's three workflow packs trade off development speed against specification rigor by varying the number of specialized AI agents from two (minimal overhead) to six (full quality-gate separation).

The unclebob/swarm-forge repository provides three distinct runnable branches—two-pack, four-pack, and six-pack—that encode different development topologies using tmux-based agents. While all three share the same underlying orchestration engine and handoff protocol, they differ fundamentally in role specialization and quality-gate separation. Choosing the appropriate workflow depends on your project's need for Gherkin specifications, architectural oversight, and mutation testing.

Two-Pack Workflow: Minimal Overhead

The two-pack workflow is the leanest configuration, designed for small, fast-turnaround backend tasks where formal specifications would be overkill.

This workflow defines only two roles:

• coder – Writes code using TDD and unit tests.
• cleaner – Performs cleanup, CRAP/DRY review, architectural refactoring, and language-mutation hardening.

The normal hand-off cycle follows a tight feedback loop: coder → cleaner → coder. According to the repository's README.md (lines 21-30), this configuration omits the specification stage entirely, trading formal Gherkin specs for rapid iteration between implementation and cleanup.

Four-Pack Workflow: Specification and Architecture

The four-pack workflow introduces formal specification and architectural oversight, making it suitable for moderate-size projects that require documented acceptance criteria but not dedicated QA agents.

This workflow defines four distinct roles:

• specifier – Converts user intent into Gherkin acceptance specs and asks for approval.
• coder – Implements approved slices with TDD and generated acceptance tests.
• refactorer – Cleans up while preserving behavior, improves coverage, and adds property-test scaffolding.
• architect – Oversees module structure, dependency direction, and final completion notification.

The hand-off cycle runs as: specifier → coder → refactorer → architect → specifier. As documented in README.md (lines 31-39), the four-pack adds the critical specifier role that creates Gherkin acceptance specifications before any code is written, while the architect performs final review rather than a dedicated hardening agent.

Six-Pack Workflow: Full Quality-Gate Separation

The six-pack workflow provides maximum rigor for large, high-stakes projects where each quality gate deserves a dedicated agent.

This workflow defines six specialized roles:

• specifier – Produces Gherkin specs and end-to-end QA procedures.
• coder – Implements slices with TDD and generated acceptance tests.
• cleaner – Performs cleanup, coverage, CRAP/DRY review, and mutation-site scans.
• architect – Reviews module boundaries and property-test coverage.
• hardender – Runs mutation hardening, language mutation, and soft Gherkin mutation.
• QA – Executes the specifier’s QA scripts, verifies UI/acceptance behavior, and sends completion notifications.

The complete hand-off cycle flows as: specifier → coder → cleaner → architect → hardender → QA → completion. According to README.md (lines 41-52), the six-pack adds two extra quality-gate agents—hardender for mutation hardening and QA for full end-to-end verification—whereas the four-pack relies on the architect for final review.

Configuration and Orchestration

Despite their topological differences, all three workflows share identical underlying infrastructure. The differences manifest in branch-specific configuration files that drive the orchestration engine.

Key configuration files include:

• swarmforge/swarmforge.conf – Lists the ordered roles for the selected branch, driving the creation of git worktrees and tmux windows.
• swarmforge/roles/<role>.prompt – Contains the system prompt that each agent receives (e.g., specifier.prompt, coder.prompt).
• swarmforge/constitution/articles/workflow.prompt – Provides shared workflow context; branches may add local-workflow.prompt for specialization.

The hand-off protocol remains unchanged across all packs. Agents exchange validated drafts via swarm_handoff.sh and acknowledge work completion with ready_for_next.sh, as defined in swarmforge/handoff-protocol.md (lines 166-185).

Practical Usage: Switching Between Workflows

Each workflow is accessible as a separate branch. The following commands demonstrate how to instantiate each topology:

# Two-pack: Fast coding without Gherkin specification

BRANCH=two-pack \
curl -L "https://github.com/unclebob/swarm-forge/archive/refs/heads/${BRANCH}.tar.gz" \
| tar -xz --strip-components=1
./swarm   # Launches tmux sessions for coder and cleaner

# Four-pack: Compact specification with architectural oversight

BRANCH=four-pack \
curl -L "https://github.com/unclebob/swarm-forge/archive/refs/heads/${BRANCH}.tar.gz" \
| tar -xz --strip-components=1
./swarm   # Launches tmux windows for specifier, coder, refactorer, architect

# Six-pack: Full six-agent workflow with QA and hardening

BRANCH=six-pack \
curl -L "https://github.com/unclebob/swarm-forge/archive/refs/heads/${BRANCH}.tar.gz" \
| tar -xz --strip-components=1
./swarm   # Launches six tmux windows in defined order

Each ./swarm execution performs the following steps:

1. Copies shared scripts from main if missing.
2. Installs the branch-specific swarmforge.conf.
3. Creates a git worktree for each role defined in the configuration.
4. Starts a tmux session per role, launching the configured backend (e.g., codex, claude).

Summary

• Two-pack provides a minimal coder ↔ cleaner loop for rapid backend tasks without formal specifications.
• Four-pack adds specifier and architect roles, introducing Gherkin acceptance specs and architectural oversight for moderate projects.
• Six-pack implements full quality-gate separation with hardender and QA agents, supporting high-stakes projects requiring mutation testing and end-to-end verification.
• All workflows share the same handoff protocol (swarm_handoff.sh, ready_for_next.sh) and configuration structure, differing only in the role definitions within swarmforge.conf and the prompt files in swarmforge/roles/.

Frequently Asked Questions

Which workflow is fastest for prototyping?

The two-pack workflow is optimized for speed, eliminating the specification and hardening stages to maintain a tight feedback loop between the coder and cleaner. This makes it ideal for rapid prototyping where formal acceptance criteria would slow iteration.

Does the six-pack require more computational resources?

Yes. The six-pack workflow launches six concurrent tmux sessions and agents, compared to two or four in the alternative workflows. Additionally, the hardender role performs mutation testing and language mutation scans, which consume significantly more CPU cycles and LLM tokens than the standard cleanup performed in lighter workflows.

Can I customize the role prompts in each workflow?

Absolutely. Each branch contains swarmforge/roles/<role>.prompt files that define the system instructions for each agent. You can modify these prompts to adjust behaviors, add domain-specific instructions, or tighten quality constraints without altering the underlying handoff protocol defined in swarmforge/handoff-protocol.md.

What is the difference between the cleaner and refactorer roles?

The cleaner (found in two-pack and six-pack workflows) focuses on cleanup, CRAP/DRY analysis, and mutation-site scanning. The refactorer (found only in four-pack) specializes in preserving behavior during cleanup while improving coverage and adding property-test scaffolding. The six-pack splits these concerns, assigning cleanup to the cleaner and architectural boundary review to the architect, whereas the four-pack combines cleanup and property-testing within the refactorer role.

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