What Is the Purpose of the Specifier Agent in SwarmForge Four-Pack?

The specifier agent translates high-level user intent into a precise Gherkin acceptance-test specification and gates progress by requiring human approval before handing work to the coder.

The specifier is the first role in SwarmForge's four-pack workflow—a structured multi-agent pipeline designed to break complex software tasks into discrete, verifiable steps. According to the unclebob/swarm-forge source code, this agent establishes the contractual foundation that all downstream roles must satisfy.

Where the Specifier Sits in the Four-Pack Pipeline

The four-pack defines a strict, linear card flow: specifier → coder → refactorer → architect. This sequencing is documented in [README.md](https://github.com/unclebob/swarm-forge/blob/main/README.md) at lines 34-38, where the specifier occupies the entry point of the entire pipeline.

This positioning is intentional. By placing specification authority at the start, the four-pack ensures that:

• No code is written before requirements are formalized
• All agents work from the same Gherkin acceptance test
• Human stakeholders retain veto power over scope definition

Core Responsibilities of the Specifier Agent

1. Creating the Gherkin Specification

The specifier's primary output is a Gherkin acceptance test—a human-readable, machine-parseable specification written in Given-When-Then format. This document lives in swarmforge/roles/specifier.prompt and serves as the canonical behavioral contract for the task.

2. Enforcing the Approval Gate

Before any handoff occurs, the specifier blocks progression pending explicit user approval via the dashboard. As implemented in the SwarmForge source, this gate prevents the downstream roles (coder, refactorer, architect) from consuming resources on poorly-defined requirements.

The handoff protocol at [swarmforge/handoff-protocol.md](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) lines 69-73 explicitly lists the four-pack chain, confirming that the specifier initiates the forwarding sequence only after this approval checkpoint clears.

3. Initiating the Handoff Protocol

Once approved, the specifier uses the standard handoff protocol to transmit a git_handoff (or note) to the coder. The protocol structures this transfer with specific metadata including commit hashes and task identifiers.

Configuring the Specifier in a Four-Pack Project

The specifier is declared in swarmforge.conf alongside its three companion roles. Here's a representative configuration from the source:

;; swarmforge.conf four-pack role definitions
window-invisible specifier grok master
window-invisible coder      codex coder
window-invisible refactorer codex refactorer back-one
window-invisible architect  grok architect batch back-all

Each line declares visibility, role name, model backend, and operational flags. The specifier uses master context mode, granting it persistent memory across the specification phase.

Specifier Agent in Practice: Task Lifecycle Example

Starting the dashboard and creating a task triggers the specifier workflow:

# Launch the SwarmForge dashboard

./swarm

# User action: New Task → "Add login"

# Specifier agent response:

# 1. Prompts user for precise requirements

# 2. Generates Gherkin acceptance test

# 3. Displays **Approval** button in UI

# 4. Upon click: creates handoff to coder

The dashboard enforces that no git_handoff is queued without this explicit approval, making the specifier the workflow's single point of human control.

Testing Specifier Behavior: Four-Pack Validation

The test suite at test/swarmforge/pack_ui_test.clj provides concrete verification of specifier mechanics:

(deftest four-pack-specifier-flow
  (setup-pack! root ["specifier" "coder" "refactorer" "architect"])
  (create-task root "login-feature" "specifier")
  (is (= "specifier" (task-lane root "login-feature")))
  
  ;; Handoff enqueued only after approval
  (queue-handoff! root {:from "specifier"
                        :to   "coder"
                        :task "login-feature"
                        :type "git_handoff"
                        :commit "a1b2c3d9e8"})
  
  (is (= ["50_from_specifier_to_coder.handoff"]
         (pending-names root))))

This test validates:

• Task creation assigns the specifier lane correctly
• The handoff protocol accepts properly structured specifier→coder transitions
• Pending handoffs carry the expected naming convention

Key Source Files for Specifier Implementation

File	Lines	Significance
README.md	34-38, 37-44	Four-pack role definitions and specifier duties
swarmforge/handoff-protocol.md	69-73	Chain-forwarding rules confirming specifier as pipeline origin
swarmforge/scripts/swarmforge.bb	393-403	Internal role list used by launcher (specifier entry)
test/swarmforge/pack_ui_test.clj	Role definitions and handoff tests	Concrete specifier behavior verification

Summary

• The specifier agent in SwarmForge four-pack converts ambiguous user intent into precise, testable Gherkin specifications
• It serves as the approval gatekeeper, preventing downstream agent activation until human stakeholders validate requirements
• The specifier initiates the handoff protocol (git_handoff to coder) only after dashboard approval
• Four-pack configuration places the specifier first in the linear pipeline: specifier → coder → refactorer → architect
• Source implementations in README.md, handoff-protocol.md, and pack_ui_test.clj codify these behavioral guarantees

Frequently Asked Questions

What makes the specifier different from the other four-pack roles?

The specifier is uniquely responsible for human-facing specification work rather than code production. While the coder writes implementations, the refactorer improves structure, and the architect validates design, only the specifier creates requirements artifacts and requires explicit user sign-off before progression.

Can a four-pack function without a specifier agent?

No. The swarmforge/scripts/swarmforge.bb launcher at lines 393-403 treats specifier as a mandatory internal role. Removing it would break the handoff protocol's chain-forwarding assumptions and eliminate the critical human approval checkpoint.

What happens if a user rejects the specifier's Gherkin output?

The task remains in the specifier lane. No handoff is generated, and the downstream agents (coder, refactorer, architect) receive no work. The specifier must iterate with the user until acceptable specification language is achieved—this rejection-and-revision loop is the core quality mechanism of the four-pack workflow.

Is the specifier's Gherkin test used by later roles?

Yes. The Gherkin specification created by the specifier becomes the acceptance criteria that the coder, refactorer, and architect must satisfy. The architect's final validation specifically checks implementation against this original specifier-generated contract.

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