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

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, 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. 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, 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:

# 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 to:

1. Copy shared scripts from the main branch into swarmforge/scripts/.
2. Read 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 and 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 (four-pack section)	High-level intent and launch instructions
swarmforge/handoff-protocol.md	Defines chain forwarding logic
swarmforge/constitution/articles/workflow.prompt	Enforces worktree discipline and commit conventions
swarmforge/scripts/swarmforge.sh	Core orchestration and tmux session management
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.
• 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 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, which validates the outbound message format. The 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.

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