# When to Use the SwarmForge Four-Pack Workflow: A Complete Guide

> Discover when to use the SwarmForge four-pack workflow for moderate projects. Get formal Gherkin specs & architectural oversight without full QA overhead.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-08-09

---

**The SwarmForge four-pack workflow is designed for moderate-scale projects that require formal Gherkin acceptance specifications and architectural oversight without the full overhead of dedicated QA agents.**

The `unclebob/swarm-forge` repository provides a multi-agent coding framework that balances automation with software craftsmanship. The **SwarmForge four-pack workflow** occupies the middle ground between the lightweight two-pack for rapid prototyping and the heavyweight six-pack for enterprise-grade quality assurance, offering a disciplined specification pipeline for professional development teams.

## What Is the SwarmForge Four-Pack Workflow?

The four-pack workflow implements a **compact specification pipeline** that enforces structured handoffs between specialized AI agents. According to the [README.md – "four-pack" section](https://github.com/unclebob/swarm-forge/blob/main/README.md#four-pack), this configuration provides balanced process governance for projects that need **Gherkin specification** and **architectural guidance** without deploying dedicated agents for every quality gate.

Unlike the ultra-light two-pack (optimized for quick implementation) or the comprehensive six-pack (full-scale QA with mutation testing), the four-pack targets codebases where architectural cohesion matters but exhaustive pipelines would be overkill.

## The Four Roles and Responsibilities

The workflow orchestrates four distinct roles through a linear handoff chain defined in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md). Each role operates in its own git worktree with dedicated tmux sessions.

### 1. Specifier

The **specifier** translates user intent into precise Gherkin acceptance specifications. This role requires explicit approval before implementation proceeds, ensuring that requirements are captured formally in `.feature` files.

### 2. Coder

The **coder** implements approved specification slices using **Test-Driven Development (TDD)**, unit tests, and generated acceptance tests. This role produces the initial working code that satisfies the Gherkin scenarios.

### 3. Refactorer

The **refactorer** cleans up the implementation while preserving behavior, improves test coverage, and adds property-test scaffolding. This role ensures the code remains maintainable without changing its external semantics.

### 4. Architect

The **architect** reviews high-level structure, enforces dependency direction, hardens mutations, and sends the final completion notification. According to the [hand-off protocol](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md#chain-forwarding), the architect hands work back to the specifier for final review, completing the loop: `specifier → coder → refactorer → architect → specifier`.

## When to Choose the Four-Pack Workflow

Select the SwarmForge four-pack workflow when your project meets these criteria:

- **Formal acceptance specifications are required** — Ideal for user-facing features and API contracts where Gherkin scenarios provide executable documentation.
- **Architectural cohesion is critical** — When dependency direction and high-level design integrity matter more than in rapid-prototype scenarios.
- **Team discipline is preferred over agent abundance** — Perfect for teams wanting code review, coverage gates, and mutation hardening with a modest, four-agent configuration.

## Limitations: What the Four-Pack Excludes

The four-pack intentionally omits roles present in the six-pack workflow to maintain its compact nature:

- **No dedicated QA agent** — The `hardender`/`QA` role that runs end-to-end acceptance suites is reserved for the six-pack configuration.
- **No separate cleaner role** — Aggressive post-iteration refactoring performed by a dedicated cleaner agent requires upgrading to the six-pack workflow.

## Launching the Four-Pack Workflow

To initialize the workflow, fetch the four-pack branch and execute the swarm launcher:

```bash

# 1. Pull the four‑pack branch (the runnable configuration)

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

# 2. Start the swarm (creates tmux windows for each role)

./swarm

```

Under the hood, `./swarm` executes [`swarmforge/scripts/swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.sh) to:

1. Copy shared scripts from the `main` branch into `swarmforge/scripts/`.
2. Read [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) to create a worktree for each role.
3. Launch individual tmux sessions for the specifier, coder, refactorer, and architect.

The **handoff protocol** is enforced by [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.sh) and [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh), which validate message formats before forwarding work to the next role in the chain.

## Key Files in the Four-Pack Architecture

| File | Role in the Workflow |
|------|---------------------|
| [`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md) (four-pack section) | High-level intent and launch instructions |
| [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) | Defines chain forwarding logic |
| `swarmforge/constitution/articles/workflow.prompt` | Enforces worktree discipline and commit conventions |
| [`swarmforge/scripts/swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.sh) | Core orchestration and tmux session management |
| [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.sh) | Validates outbound handoff drafts between roles |

## Summary

- The **SwarmForge four-pack workflow** provides a middle-ground specification pipeline between rapid prototyping and enterprise QA.
- It orchestrates four specialized roles—**specifier**, **coder**, **refactorer**, and **architect**—through a disciplined handoff chain.
- Choose this workflow for projects requiring **Gherkin specifications** and **architectural oversight** without dedicated QA agents.
- The workflow is initialized via the `four-pack` branch using standard curl/tar commands, with orchestration handled by [`swarmforge/scripts/swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.sh).
- Unlike the six-pack, it excludes the `hardender` QA agent and dedicated cleaner role to maintain operational efficiency.

## Frequently Asked Questions

### How does the four-pack differ from the six-pack workflow?

The four-pack provides a compact specification pipeline with four roles focused on specification, implementation, refactoring, and architecture. The six-pack adds dedicated **QA** (`hardender`) and **cleaner** agents for exhaustive mutation testing and aggressive post-iteration refactoring, making it suitable for high-assurance enterprise environments.

### Can I add a dedicated QA agent to the four-pack workflow?

The four-pack configuration in `unclebob/swarm-forge` is designed as a balanced quartet. While you could theoretically modify [`swarmforge/swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/swarmforge.conf) to add additional agents, doing so would effectively transition the workflow toward the six-pack architecture. For formal QA requirements, the repository recommends switching to the `six-pack` branch instead.

### What triggers the handoff between roles in the four-pack?

Handoffs are triggered when a role completes its task and executes [`swarmforge/scripts/swarm_handoff.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.sh), which validates the outbound message format. The [`ready_for_next.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next.sh) script then forwards the work to the next role in the chain—specifier to coder, coder to refactorer, refactorer to architect, and finally architect back to specifier for final approval.

### Is the four-pack suitable for microservices architecture?

Yes, provided the microservices require **formal acceptance specifications** and **architectural cohesion** but do not need the exhaustive QA overhead of the six-pack. The four-pack's emphasis on dependency direction enforcement (handled by the architect role) makes it particularly suitable for services where API contracts and internal structure consistency are priorities.