SwarmForge Pack Workflows Explained: Two-Pack, Four-Pack, Six-Pack, and Simple-Windows

SwarmForge pack workflows are structured development pipelines defined by role-based agent configurations, with four distinct variants ranging from lightweight two-agent setups to comprehensive six-agent enterprise workflows.

SwarmForge organizes software development into packs—self-contained workflow bundles that define how tasks flow through specification, implementation, review, and delivery. Each pack combines shell scripts, role-specific prompts, and constitution articles that govern agent behavior. According to the unclebob/swarm-forge source code, these workflows scale from minimal two-agent configurations to full six-agent enterprise pipelines.

The Four SwarmForge Pack Workflow Types

The repository defines four primary pack workflows, each optimized for different project complexity levels. These are implemented as Git branches that users clone via the get-swarm-forge utility.

Two-Pack Workflow

The two-pack workflow provides the lightest-weight development pipeline, designed for rapid prototyping and small tasks requiring minimal overhead.

Core characteristics:

• Two agents only: coder and reviewer
• No formal specification stage—implementation begins immediately
• No dedicated QA or architectural review
• Fastest feedback loop for experimental work

This workflow appears in the repository as a dedicated branch. When instantiated, it creates a minimal swarmforge.conf and role prompts limited to the two active agents.

Four-Pack Workflow

The four-pack workflow introduces specification-driven development through a specifier agent that generates Gherkin scenarios before implementation.

Core characteristics:

• Four agents: specifier, coder, reviewer, plus orchestration roles
• Gherkin-based requirements written before coding begins
• Contract-first design with acceptance criteria
• Still operates as a single continuous pipeline

The specifier agent outputs .feature files that become the contract for the coder agent, establishing traceability between requirements and implementation.

Six-Pack Workflow

The six-pack workflow represents the full enterprise-grade pipeline with dedicated quality gates and architectural oversight.

Core characteristics:

• Six agents: specifier, coder, reviewer, QA, architect, and orchestration roles
• Multi-stage quality gates with explicit handoff protocols
• Automated acceptance testing integrated into the flow
• Architectural review as a formal approval stage

According to swarmforge/constitution/articles/handoffs.prompt, the six-pack enforces strict handoff rules between each lane, ensuring no task proceeds without explicit sign-off from the responsible agent.

Simple-Windows Tag

The simple-windows configuration is not a pack branch but a runtime mode on main that disables dashboard window management for restricted environments.

Core characteristics:

• Runs from the main branch without pack-specific files
• One terminal window per role—no hidden window tricks
• No web dashboard—pure shell-based operation
• Useful for debugging, CI/CD environments, or systems lacking display capabilities

Shared Infrastructure: Constitution Articles

All pack workflows inherit three global constitution articles from main, stored in swarmforge/constitution/articles/:

• workflow.prompt — defines the MAIN-WORKFLOW base state machine and lane transitions
• engineering.prompt — general engineering policies applied across all packs
• handoffs.prompt — rules for task handoffs between agents, including required artifacts and validation checks

Each pack branch adds local articles (such as local-workflow.prompt) that extend or override global rules. When get-swarm-forge clones a pack, it merges these layers into packs/<pack-name>/swarmforge/constitution/articles/.

Pack Workflow Scripts and Entry Points

Three shell scripts drive all pack workflow operations regardless of which pack type is active:

pack_board.sh

Located at swarmforge/scripts/pack_board.sh, this script manages task boards—the fundamental work unit in SwarmForge.

# Create a new board for a six-pack project

./swarmforge/scripts/pack_board.sh create \
    --name "EnterpriseAPI" \
    --lane specifier \
    --root "$(pwd)"

# List all active boards

./swarmforge/scripts/pack_board.sh list

# Move a task to the next lane

./swarmforge/scripts/pack_board.sh move \
    --board "EnterpriseAPI" \
    --to reviewer

# Archive completed work

./swarmforge/scripts/pack_board.sh archive-all --board "EnterpriseAPI"

The script maintains board state in JSON files under each pack's root directory, tracking task assignments, current lane, and completion status.

pack_web.sh

The swarmforge/scripts/pack_web.sh script launches the web dashboard that visualizes workflow state.

# Start dashboard server on port 8080

./swarmforge/scripts/pack_web.sh --serve "$(pwd)" 8080

# Run with test state injection for validation

./swarmforge/scripts/pack_web.sh --test-state ./fixtures/sample-state.json

# Generate HTML snapshot without serving

./swarmforge/scripts/pack_web.sh --test-html ./output/dashboard.html

The dashboard renders one pane per active agent lane, showing current task, recent output, and available actions. The pack type determines which lanes appear—two-pack shows two panes, six-pack shows six.

pack_dashboard_request.sh

The swarmforge/scripts/pack_dashboard_request.sh script mediates operator interaction when agents require clarification.

# Submit a clarification request from an agent

./swarmforge/scripts/pack_dashboard_request.sh \
    clarify \
    ./tmp/what-is-the-timeout-policy.txt

# Provide operator answer (referencing request ID 42)

./swarmforge/scripts/pack_dashboard_request.sh \
    answer \
    42 \
    ./tmp/timeout-is-30-seconds.txt

This mechanism creates a blocking checkpoint in the workflow—the requesting agent pauses until the operator response arrives via the answer command.

Workflow Execution Examples

Initializing and Running a Two-Pack Workflow

# Clone the two-pack branch into packs/two-pack/

get-swarm-forge two-pack

cd packs/two-pack

# Create minimal board starting in coder lane

./swarmforge/scripts/pack_board.sh create \
    --name "QuickFix" \
    --lane coder \
    --root "$(pwd)"

# Launch dashboard (shows only coder and reviewer panes)

./swarmforge/scripts/pack_web.sh --serve "$(pwd)" 8080

Full Six-Pack Enterprise Workflow

# Clone comprehensive workflow

get-swarm-forge six-pack

cd packs/six-pack

# Board starts in specifier lane for requirements

./swarmforge/scripts/pack_board.sh create \
    --name "PaymentGateway" \
    --lane specifier \
    --root "$(pwd)"

# Start dashboard with all six agent panes visible

./swarmforge/scripts/pack_web.sh --serve "$(pwd)" 8080

# When specifier generates Gherkin, manually advance:

./swarmforge/scripts/pack_board.sh move \
    --board "PaymentGateway" \
    --to coder

# Later stages use same move command through reviewer → QA → architect

Simple-Windows Mode for Restricted Environments

# No pack clone needed—run directly from main

cd /path/to/swarm-forge

# Execute role scripts manually in separate terminals

# No pack_web.sh dashboard—direct shell interaction only

./swarmforge/scripts/agent_runner.sh coder ./tasks/task-001
./swarmforge/scripts/agent_runner.sh reviewer ./tasks/task-001

Pack Configuration File Structure

Each instantiated pack contains:

packs/<pack-name>/
├── swarmforge.conf              # Pack metadata and lane definitions

├── swarmforge/
│   ├── scripts/                 # Runtime scripts (symlinked or copied)

│   ├── roles/
│   │   ├── specifier.prompt     # Only in four-pack, six-pack

│   │   ├── coder.prompt
│   │   ├── reviewer.prompt
│   │   ├── qa.prompt            # Only in six-pack

│   │   └── architect.prompt     # Only in six-pack

│   └── constitution/
│       └── articles/
│           ├── workflow.prompt    # From main (global)

│           ├── engineering.prompt # From main (global)

│           ├── handoffs.prompt    # From main (global)

│           └── local-workflow.prompt  # Pack-specific overrides

└── boards/                      # Runtime board state

The swarmforge.conf file encodes which lanes are active, their ordering, and transition rules—this is what differentiates a two-pack from a six-pack at runtime.

Summary

• SwarmForge pack workflows come in four variants: two-pack (minimal), four-pack (specification-driven), six-pack (enterprise with QA and architecture), and simple-windows (debug mode on main)

• All packs share three global constitution articles (workflow.prompt, engineering.prompt, handoffs.prompt) from the main branch

• Each pack adds local overrides through pack-specific prompt files and swarmforge.conf lane definitions

• Three shell scripts drive all workflows: pack_board.sh (task management), pack_web.sh (dashboard), and pack_dashboard_request.sh (operator interaction)

• Pack selection determines which agent roles execute and which quality gates enforce handoff requirements

Frequently Asked Questions

What determines which agents run in a SwarmForge pack?

The swarmforge.conf file in each pack branch defines the active lanes. According to swarmforge/constitution/articles/workflow.prompt, the MAIN-WORKFLOW state machine reads this configuration to instantiate only the specified agents. Two-pack configures two lanes; six-pack configures six.

Can I switch pack types mid-project?

No—pack types are fixed at initialization via get-swarm-forge. However, you can create a new board in a different pack and manually migrate tasks. The constitution articles are compatible, but lane history from one pack type won't automatically map to another's quality gates.

What happens if an agent fails in a six-pack workflow?

Per swarmforge/constitution/articles/handoffs.prompt, failed handoffs trigger a BLOCKED state. The pack_board.sh command shows blocked tasks with --list, and the dashboard highlights the failing lane. The operator must resolve the blocker (via pack_dashboard_request.sh answer) or manually reset the lane with pack_board.sh move --force.

Is simple-windows suitable for production use?

The README.md describes simple-windows as a debugging convenience. It lacks the dashboard's visibility and the automated handoff validation of full packs. Use it only when the standard dashboard cannot run, such as in containerized CI environments or over SSH without X forwarding.

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