SwarmForge Agent Roles Explained: The 7 Roles That Drive AI-Assisted Software Development

SwarmForge defines seven distinct agent roles—Specifier, Coder, Cleaner, Architect, Hardender, QA, and Lieutenant—that each own a git worktree, tmux session, prompt file, and hand-off mailbox to transform user stories into tested production code.

The unclebob/swarm-forge project implements a disciplined pipeline architecture where specialized AI agents hand off work through a structured protocol. Each role has immutable responsibilities and communicates exclusively through shell scripts, enabling reproducible, observable software development workflows.

---

Core Pipeline Roles: The Six-Pack

The canonical implementation is the six-pack pipeline, defined in the project README. These six roles execute sequentially, with each agent completing its task before handing off to the next via swarmforge/scripts/swarm_handoff.sh.

Specifier

The Specifier ingests user stories or feature requests and produces detailed, unambiguous specifications for downstream agents.

This role eliminates interpretation ambiguity before any code is written. The specification becomes the contract that all subsequent roles must satisfy.

Coder

The Coder implements the specification by writing source code directly into its assigned git worktree.

This is the primary implementation role. The Coder does not refactor, test, or architect—it focuses solely on functional correctness according to the spec.

Cleaner

The Cleaner refactors freshly written code, removes duplication, improves naming, and enforces stylistic consistency.

This role operates as a dedicated refactorer within the pipeline. It preserves behavior while improving internal quality—freeing the Coder to prioritize completion over polish.

Architect

The Architect reviews module boundaries, adjusts interfaces, and guarantees architectural coherence across the codebase.

Unlike the Cleaner, which works at the function and class level, the Architect evaluates systemic design decisions and structural integrity.

Hardender

The Hardender (also referenced as "Hard-ender") introduces robustness through tests, type annotations, defensive code, and error handling.

This role hardens the implementation against edge cases and operational failures. It establishes the safety net that QA will later validate.

QA

The QA role executes the complete test suite, validates the final product against the original specification, and reports any regressions or failures.

QA serves as the pipeline's quality gate. Only after QA approval is the work considered complete.

---

Orchestration Role: The Lieutenant

Beyond the six-pack pipeline, SwarmForge defines a seventh role that operates at the forge level rather than within a single pack.

Lieutenant (Host/Planner)

The Lieutenant hosts a forge-level dashboard, coordinates multiple packs simultaneously, and acts as the human-friendly interface to the entire swarm.

Defined in swarmforge/roles/lieutenant.prompt, the Lieutenant launches the orchestration UI and manages resource allocation across concurrent pipelines. It is the "host lieutenant" that humans interact with when initiating complex multi-pack operations.

Unlike pipeline roles that process a single work item sequentially, the Lieutenant maintains persistent awareness of all active workstreams.

---

Pack Configurations: How Roles Compose

Roles are composed into packs of varying granularity. The unclebob/swarm-forge repository provides three standard configurations:

Pack	Role Sequence	Use Case
Two-pack	Specifier → Coder	Fast backend work where rapid iteration outweighs formal review
Four-pack	Specifier → Coder → Cleaner → Architect	Design-critical work requiring structural oversight
Six-pack	Specifier → Coder → Cleaner → Architect → Hardender → QA	Production-grade end-to-end pipeline

Each pack is instantiated through get-swarm-forge <pack-name>, which provisions the required role directories, tmux configurations, and hand-off mailboxes.

---

The Hand-Off Protocol

Role transitions are governed by explicit shell scripts in swarmforge/scripts/:

• swarm_handoff.sh — Transfers a task from one role's worktree to the next role's inbox
• ready_for_next.sh — Blocks until the downstream role claims available work
• done_with_current.sh — Marks the current role's task as complete in the shared state database

This protocol guarantees that only one role modifies a given worktree at any time, enforcing serializability without complex locking mechanisms.

# Example: Manual hand-off from Coder to Cleaner

./swarmforge/scripts/swarm_handoff.sh \
    --from coder \
    --to cleaner \
    --task-id 42

Each role runs in its own tmux session, enabling human inspection, intervention, or replay of any agent's reasoning process.

---

Role Infrastructure: Files and Directories

Every role receives identical infrastructure mapped to its name:

Resource	Path Pattern	Purpose
Prompt file	swarmforge/roles/{role}.prompt	System instructions defining role behavior
Worktree	work/{role}/	Isolated git working directory
Tmux session	Named per role	Persistent terminal environment for the agent
Mailbox	handoffs/{role}/	FIFO queue for incoming task transfers

The Lieutenant additionally maintains:

• Dashboard UI for forge-level visibility
• Pack registry tracking active pipeline instances

---

Launching a Swarm

# Install and launch the full six-pack pipeline

get-swarm-forge six-pack
./swarm                      # Creates 6 tmux sessions, one per role

# Launch the Lieutenant host for multi-pack coordination

get-swarm-forge lieutenant
./swarm                      # Starts dashboard and orchestration layer

The ./swarm executable reads the active pack definition and initializes each role's environment in dependency order: Specifier first, QA last, with the Lieutenant supervising if present.

---

Summary

• SwarmForge defines seven agent roles: Specifier, Coder, Cleaner, Architect, Hardender, QA, and Lieutenant.

• Pipeline roles (six-pack) execute sequentially via swarm_handoff.sh, each owning a dedicated worktree and tmux session.

• The Lieutenant operates at forge scope, coordinating multiple packs through a persistent dashboard.

• Pack configurations (two-pack, four-pack, six-pack) trade iteration speed for quality assurance depth.

• All hand-offs are explicit, logged, and reversible—implemented through shell scripts in swarmforge/scripts/.

---

Frequently Asked Questions

What is the difference between the Cleaner and Architect roles?

The Cleaner performs local refactoring—improving names, eliminating duplication, and enforcing style within existing structure. The Architect modifies systemic design—restructuring module boundaries, interfaces, and dependencies. Cleaner preserves architecture; Architect redefines it.

Can I add custom roles to a SwarmForge pack?

The swarmforge/roles/ directory structure supports extensibility. Create a new {role}.prompt file and register the role in your pack's manifest. However, you must also implement hand-off logic in swarmforge/scripts/swarm_handoff.sh to connect your role to the pipeline.

Why does each role require its own git worktree?

Worktree isolation eliminates merge conflicts and enables precise human audit. At any moment, you can cd into a role's worktree and see exactly what that agent produced, with full git history preserved per role.

How does the Lieutenant differ from a pack-level role?

Pipeline roles process tasks sequentially and terminate when their step completes. The Lieutenant is long-running and stateful, maintaining awareness across all active packs, managing resource contention, and presenting a unified interface to human operators.

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