Four-Pack vs Two-Pack Workflow in Swarm-Forge: Key Differences Explained

The four-pack workflow adds specification and architectural review stages to the two-pack's lean code-and-clean loop, moving from a 2-agent cycle (coder → cleaner → coder) to a 4-agent pipeline (specifier → coder → refactorer → architect).

Swarm-Forge, an open-source multi-agent orchestration framework by Uncle Bob, ships with three canonical "pack" configurations that define how AI agents hand off work. The two-pack and four-pack workflows target different project sizes and rigor requirements. This article breaks down their structural differences using the actual source implementation in unclebob/swarm-forge.

Purpose and Project Fit

Choosing between packs starts with understanding what each prioritizes.

• Two-pack – Optimized for speed. Designed for small backend tasks where rapid iteration outweighs specification overhead. Skips Gherkin acceptance tests entirely.

• Four-pack – Balances structure and efficiency. Adds Gherkin-based specifications and architectural gates for moderate-size projects that need traceability without six-pack granularity.

As documented in [README.md](https://github.com/unclebob/swarm-forge/blob/main/README.md#L21), the two-pack exists specifically for "quick coding without the overhead of Gherkin specifications."

Role Structure: Two Agents vs Four Agents

The most visible difference lies in the agent chain.

Two-Pack Roles

Only two roles operate in a closed loop:

Role	Responsibility
coder	Generates initial implementation
cleaner	Reviews, refactors, and returns work

The complete chain is: coder → cleaner → coder

Per [handoff-protocol.md line 169](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md#L169), the cleaner always forwards back to the coder. No branching occurs—this is a strict ping-pong pattern. Line 185 confirms: "the cleaner forwards to the coder" with no "back-one" logic.

Four-Pack Roles

Four distinct roles create a linear pipeline with broadcast capability:

Role	Responsibility
specifier	Writes Gherkin acceptance criteria
coder	Implements against specifications
refactorer	Hardens and optimizes code
architect	Validates design decisions

The chain runs: specifier → coder → refactorer → architect

The test suite exposes this role list explicitly as four-pack-roles in pack_ui_test.clj lines 335-336.

Hand-Off Behavior and Control Flow

Two-pack hand-offs are deterministic. Four-pack introduces selective broadcasting.

Two-pack limitation: The cleaner has one destination—the coder. This eliminates routing complexity but prevents escalation of systemic issues.

Four-pack flexibility: The architect can broadcast backward. Per [handoff-protocol.md line 187](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md#L187), the architect's hand-off target includes: to: specifier, coder, refactorer. This allows architectural concerns to reach any prior stage without traversing the full chain.

Quality Gates and Verification

Workflow	Gates Present
Two-pack	Code review loop only
Four-pack	Gherkin spec validation → implementation → refactoring → architectural review

The four-pack's specifier role mandates Gherkin acceptance criteria before coding begins—a quality gate entirely absent in the two-pack workflow.

Configuration and Selection

Both packs install via the same mechanism but activate differently.

Project initialization uses the get-swarm-forge script. The pack_names variable controls available options. Selection happens through a UI radio-button list as shown in [project-board.md line 35](https://github.com/unclebob/swarm-forge/blob/main/project-board.md#L35).

# Create project with two-pack (minimal overhead)

./get-swarm-forge --test-new-project $(pwd) my-project two-pack

# Create project with four-pack (structured pipeline)

./get-swarm-forge --test-new-project $(pwd) my-project four-pack

Both commands invoke the same entry point (see get-swarm-forge line 5). The third argument selects the pack, which determines the active role chain from [handoff-protocol.md](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md).

When to Use Each Workflow

• Choose two-pack for internal tools, rapid prototypes, or backend microservices where team velocity matters more than specification traceability.

• Choose four-pack for customer-facing features requiring acceptance criteria, or when technical debt prevention outweighs pure speed.

Summary

• Two-pack runs a 2-agent closed loop (coder ↔ cleaner) with minimal overhead and no Gherkin requirements.

• Four-pack expands to 4 agents with linear progression and architect broadcast capability, adding specification and architectural validation.

• Hand-off rules differ fundamentally: two-pack forwards deterministically; four-pack allows selective backward broadcast from the architect role.

• Selection occurs at project creation via get-swarm-forge with the pack name as the third argument.

Frequently Asked Questions

Can I switch from two-pack to four-pack mid-project?

Swarm-Forge does not support runtime pack migration. The role chain and hand-off protocol are baked into project initialization. Per [project-board.md](https://github.com/unclebob/swarm-forge/blob/main/project-board.md#L35), pack selection happens via UI radio buttons at creation time, with no reconfiguration path documented.

Does the four-pack always require Gherkin specifications?

Yes. The specifier role's sole purpose is Gherkin creation. Removing this stage would collapse the four-pack into a three-role chain incompatible with the expected specifier → coder → refactorer → architect hand-off sequence defined in [handoff-protocol.md lines 170-187](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md#L170).

Is the two-pack deprecated in favor of the four-pack?

No. Both remain actively maintained. The two-pack serves a distinct use case—"small tasks that need quick coding without the overhead" per [README.md line 21](https://github.com/unclebob/swarm-forge/blob/main/README.md#L21). The get-swarm-forge script continues installing both by default.

What happens if the architect rejects work in the four-pack?

The architect's broadcast capability (to: specifier, coder, refactorer) allows returning work to any previous role. This differs from the two-pack where rejection cycles exclusively back to the coder. The specific routing depends on rejection reason—specification flaws go to specifier, implementation bugs to coder, refactoring issues to refactorer.

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