When to Use the SwarmForge Two-Pack Workflow: A Guide to Lightweight AI Development

The SwarmForge two-pack workflow is the lightweight, rapid-turnaround option for small tasks that require only a coder and cleaner, bypassing specification overhead while maintaining code quality through TDD and mutation testing.

The SwarmForge two-pack workflow provides a streamlined alternative to full specification pipelines when working with the unclebob/swarm-forge repository. Designed for rapid implementation and refinement, this configuration eliminates the overhead of extensive planning while preserving critical quality gates through a tight coder-cleaner loop.

What Is the SwarmForge Two-Pack Workflow?

According to README.md in the unclebob/swarm-forge repository, the two-pack configuration serves as the quick backend workflow of the system. It implements a minimal two-agent loop consisting exclusively of a coder and a cleaner, following the hand-off chain coder → cleaner → coder as documented in swarmforge/handoff-protocol.md lines 64-71.

Unlike larger configurations, this workflow omits the specifier, architect, and QA roles. The coder writes code using test-driven development (TDD) and unit tests, then hands the draft to the cleaner. The cleaner performs batch cleanup, CRAP/DRY review, architectural refactoring, and language-mutation hardening before returning the result to the coder for final commit.

When to Choose the Two-Pack Workflow

Select the SwarmForge two-pack workflow when your project meets specific criteria that prioritize speed over comprehensive specification:

• Small scope: The task involves a single feature, bug-fix, or prototype that fits within a self-contained unit of work.
• Fast turnaround required: You need to avoid writing Gherkin specifications or running higher-level QA agents that add latency to the development cycle.
• Backend quality needs: Despite the lightweight process, you still require code-quality checks and mutation testing provided by the cleaner role.
• No architectural overhead: The project does not require a separate specifier, architect, or QA role to validate requirements or design decisions.

In contrast, the four-pack and six-pack workflows add specification, architectural, and quality-assurance agents. These larger configurations increase overhead but provide more discipline for medium- to large-scale work. Use two-pack when the speed-first approach outweighs the need for extra quality gates.

How the Two-Pack Workflow Operates

The workflow executes through a defined protocol managed by shell scripts in the swarmforge/scripts/ directory.

The Coder Phase

The coder begins implementation in the .worktrees/coder directory using TDD principles. After writing a failing test and making it pass, the coder initiates the hand-off using swarm_handoff.sh:

# Inside the coder's worktree

bb test  # Run your test runner

swarm_handoff.sh ./tmp/handoff.txt  # Hand draft to cleaner

The Cleaner Phase

The cleaner operates in the .worktrees/cleaner directory, automatically receiving hand-offs through ready_for_next.sh. This role executes batch cleanup, validates CRAP/DRY metrics, applies architectural refactoring, and runs mutation testing to harden the code against edge cases.

# Inside the cleaner's worktree

ready_for_next.sh  # Pull handoff from inbox

# Perform cleanup, then return to coder

swarm_handoff.sh ./tmp/handoff.txt

The Hand-Off Protocol

The swarmforge/handoff-protocol.md file defines the chain-forwarding behavior specific to two-pack. The swarmforge/scripts/swarm_handoff.sh script validates and queues hand-off files, while swarmforge/scripts/ready_for_next.sh consumes incoming work from the role's inbox. This creates a bidirectional flow: the coder sends draft code forward, and the cleaner returns hardened code back to the coder for final integration.

Setting Up a Two-Pack Swarm

Initialize a two-pack environment using the dedicated branch and launcher script:

# Start a two-pack swarm in a clean directory

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

# Launch the swarm (creates coder & cleaner windows)

./swarm

The swarmforge.conf file (generated when running the branch) configures the tmux sessions, specifying window coder and window cleaner entries that swarmforge/scripts/swarmforge.sh uses to initialize the terminal windows. After the cleaner returns the hardened commit, the coder merges the result:

# Back in the coder's worktree

ready_for_next.sh  # Receive cleaned commit

git merge CLEANED_COMMIT  # Finalize the feature

Summary

• The SwarmForge two-pack workflow provides a lightweight alternative to full specification pipelines, utilizing only a coder and cleaner.
• Choose this workflow for small, self-contained tasks requiring rapid turnaround without Gherkin specifications or QA agents.
• The workflow follows a bidirectional hand-off chain (coder → cleaner → coder) managed by swarm_handoff.sh and ready_for_next.sh.
• The cleaner performs CRAP/DRY reviews, architectural refactoring, and mutation testing to maintain code quality despite the minimal process.
• Larger four-pack and six-pack configurations add specification and architectural roles for complex projects.

Frequently Asked Questions

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

The two-pack workflow includes only a coder and cleaner, while the four-pack adds specifier and architect roles. According to the source code in README.md lines 21-30, four-pack workflows introduce specification phases and architectural reviews that increase overhead but provide more discipline for medium-scale projects. Two-pack eliminates these gates for maximum velocity on small tasks.

Can I use the two-pack workflow for large features?

No, the two-pack workflow is explicitly designed for small, self-contained tasks. The README.md documentation indicates that larger features requiring complex architecture or extensive quality assurance should use the four-pack or six-pack configurations instead, as these provide the necessary specification and QA agents missing from the two-pack setup.

What files control the hand-off behavior in two-pack?

The hand-off logic resides in swarmforge/handoff-protocol.md, which defines the coder → cleaner → coder chain. The executable scripts swarmforge/scripts/swarm_handoff.sh (for sending work) and swarmforge/scripts/ready_for_next.sh (for receiving work) implement this protocol, while swarmforge.conf configures the window management for the two agents.

How does the cleaner ensure code quality without a QA agent?

The cleaner performs batch cleanup, CRAP/DRY analysis, architectural refactoring, and language-mutation hardening. These automated checks, documented in the workflow description, provide backend quality assurance through static analysis and mutation testing rather than manual QA review, making the two-pack workflow suitable for rapid development cycles that still require hardened code.

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