# What Is the Role of the Coder Agent in SwarmForge Two-Pack Workflows?

> Discover the coder agent's role in SwarmForge two-pack workflows. It converts specs to code, saves it, and passes tasks to the next stage, driving efficient development.

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

---

**The coder agent in SwarmForge transforms abstract specifications from the specifier agent into concrete source code, persists the output to the pack's work-tree, and hands off completed tasks to downstream roles.**

In SwarmForge's collaborative AI-driven development system, a **two-pack** pairs the **specifier** role (task definition) with the **coder** role (task implementation). The coder agent sits at the heart of this workflow, bridging the gap between human-readable requirements and executable code. According to the `unclebob/swarm-forge` source code, the coder's responsibilities span reception, generation, persistence, and delegation—each implemented through precise hand-off protocols and tmux-based session management.

## How the Coder Agent Receives Specifications

The coder agent enters the workflow through explicit hand-off directives. When a specifier completes a task description, it queues a structured hand-off targeting the coder role.

In `swarmforge/scripts/swarmforge.bb` at line 952, the orchestration logic processes these hand-offs:

```clojure
;; Hand-off structure used by specifier → coder transitions
{:from "specifier"
 :to "coder"
 :task "htw-console-app"}

```

This payload triggers the coder agent to:

- Activate its dedicated tmux session (named `swarmforge-coder`)
- Read the specification file from the specifier's work-tree output directory
- Parse the requirement using the built-in Gherkin toolchain

The coder agent listens specifically for `from: specifier → to: coder` transitions. Without this precise routing, the agent remains idle in its session, awaiting valid work assignments.

## Code Generation and Toolchain Integration

Once activated, the coder agent invokes its specialized toolchain to transform specifications into source files. The core generation logic resides in `swarmforge/scripts/swarmforge.bb` around line 394:

```clojure
;; Coder toolchain invocation pattern
(let [spec (read-spec task-path)
      generated (generate-source spec coder-tools)]
  (write-work-tree! "coder" task-name generated))

```

The coder's capabilities include:

- **Gherkin parsing** — Extracts scenario definitions from behavior-driven specifications
- **Template expansion** — Applies language-specific generation rules
- **Multi-file output** — Creates cohesive source structures rather than single files

Generated code adheres to the specification's constraints while maintaining idiomatic patterns for the target language. The coder does not merely transcribe—it interprets intent and produces runnable implementations.

## Persistence to the Coder Work-Tree

Output persistence follows a strict directory protocol. As verified in `test/swarmforge/script_test.clj` (lines 68–72), the coder role writes to its designated lane:

```clojure
;; Test verification of coder output location
(deftest coder-persists-to-work-tree
  (let [pack (setup-pack! root ["specifier" "coder"])]
    (create-task root "auth-module" "specifier")
    (queue-handoff! root {:from "specifier" :to "coder" :task "auth-module"})
    (is (exists? (str (pack-worktree root pack "coder") "/auth-module")))))

```

The work-tree structure enables:

| Lane | Purpose | Access Pattern |
|------|---------|--------------|
| `specifier/` | Input specifications | Read-only for coder |
| `coder/` | Generated source code | Write destination |
| Cross-lane | Downstream consumption | Read by cleaner/architect/QA |

This isolation ensures reproducible builds and clear audit trails. Each role's contributions remain traceable through filesystem boundaries.

## Hand-Off to Downstream Roles

Completion triggers the next phase. The coder agent queues subsequent hand-offs as demonstrated in `test/swarmforge/pack_ui_test.clj` (lines 306–312):

```clojure
;; Coder forwarding completed code to cleaner
(queue-handoff! root {:from "coder"
                      :to "cleaner"
                      :task "htw-console-app"})

```

Common coder-initiated transitions include:

- **coder → cleaner** — Code quality and style normalization
- **coder → architect** — Structural review and dependency verification
- **coder → QA** — Automated testing and validation

The hand-off payload includes metadata linking back to the original specification, maintaining full provenance through the pipeline.

## Session Management and Process Visibility

SwarmForge instantiates the coder as a persistent tmux session. Test assertions in `test/swarmforge/script_test.clj` (lines 842–854) confirm:

```clojure
;; Session naming convention
(deftest coder-session-exists
  (let [_ (setup-pack! root ["specifier" "coder"])]
    (is (tmux-session-running? "swarmforge-coder"))))

```

Operational characteristics:

- **Long-running process** — Survives individual task completions for stateful context
- **Named session** — `swarmforge-coder` appears in `tmux ls` output
- **State recovery** — Reattaches to existing sessions on pack restart

This architecture supports iterative refinement. The coder maintains context across multiple specification cycles, improving consistency in generated output.

## Two-Pack Initialization Example

Creating a functional specifier-coder pair requires precise role sequencing:

```clojure
;; Complete two-pack setup with task flow
(def root "/tmp/swarmforge-demo")

;; Initialize the two-pack
(setup-pack! root ["specifier" "coder"])

;; Specify and implement a feature
(create-task root "user-login-flow" "specifier")

;; Trigger coding phase
(queue-handoff! root {:from "specifier"
                      :to "coder"
                      :task "user-login-flow"})

;; Verify output location
(println (slurp (str (pack-worktree root ["specifier" "coder"] "coder")
                     "/user-login-flow")))

```

The `setup-pack!` function establishes both work-trees and sessions. Role ordering in the vector matters—specifier precedes coder in the dependency chain.

## Summary

- The **coder agent** implements the implementation phase of SwarmForge two-packs, receiving structured specifications from the specifier role.
- **Code generation** leverages Gherkin parsers and language-specific templates, producing idiomatic source files rather than mechanical translations.
- **Work-tree persistence** strictly isolates coder output to the `coder/` lane, enabling traceable, reproducible builds.
- **Hand-off protocols** chain the coder to downstream roles (cleaner, architect, QA) through explicit, metadata-rich queue operations.
- **Tmux session management** provides durable, named execution contexts (`swarmforge-coder`) that survive individual task boundaries.

## Frequently Asked Questions

### What tools does the coder agent use for code generation?

The coder agent employs SwarmForge's built-in **coder toolchain**, which includes a Gherkin parser for behavior-driven specifications and template-based generators language-specific output. This toolchain is defined in `swarmforge/scripts/swarmforge.bb` and invoked automatically when the coder receives a valid hand-off.

### Can a two-pack function with only a coder and no specifier?

No. A two-pack requires both roles to complete the specification-to-code pipeline. The coder agent depends on `from: specifier` hand-offs to receive work. Without the specifier, the coder session remains idle with no input source.

### How does the coder agent know when its task is complete?

The coder determines completion when its **code generation toolchain** successfully writes output to the work-tree and the resulting files pass internal validation. At this point, it queues the next hand-off—typically `to: cleaner`—and awaits the next specification.

### Where is the coder agent's session name defined?

The session name `swarmforge-coder` follows SwarmForge's **role-based naming convention**, automatically derived from the role identifier. This is verified in `test/swarmforge/script_test.clj`, where tests assert session existence through tmux process inspection.