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

> Discover the specifier agent in SwarmForge four-pack. It translates user intent into Gherkin specs and gates progress with human approval before coding.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: internals
- Published: 2026-08-28

---

**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)](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)](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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) alongside its three companion roles. Here's a representative configuration from the source:

```clojure
;; 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:

```bash

# 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`](https://github.com/unclebob/swarm-forge/blob/main/test/swarmforge/pack_ui_test.clj) provides concrete verification of specifier mechanics:

```clojure
(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`](https://github.com/unclebob/swarm-forge/blob/main/README.md) | 34-38, 37-44 | Four-pack role definitions and specifier duties |
| [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/README.md), [`handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/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`](https://github.com/unclebob/swarm-forge/blob/main/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.