# How the Refactorer Agent Works in SwarmForge Four‑Pack: Back‑One Propagation Explained

> Discover how the SwarmForge four-pack refactorer agent works by propagating work backward one hop using the back-one token. Understand its role in coding and architecture.

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

---

**The refactorer agent in SwarmForge four‑pack is a task‑type role that propagates work backward by one hop using the `back-one` token, sending a reverse copy to the coder and a forward copy to the architect.**

The refactorer is one of four default agents—alongside specifier, coder, and architect—that form a complete SwarmForge pack. Its unique propagation behavior allows it to apply quick refactoring steps and return control to the coder before final architectural review. This article breaks down exactly how the refactorer agent works based on the unclebob/swarm-forge source code.

## How the Refactorer Role Is Defined

When SwarmForge parses a [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) file, each `window` line creates a role entry with a propagation token. The refactorer definition follows this exact syntax:

```clojure
window refactorer grok refactorer task back-one

```

This line appears in `script_test.clj` at lines 306–307, which verifies the configuration parser correctly extracts the role name, model, task type, and `back-one` propagation token.

The four components of this definition are:

- **`refactorer`** — the role identifier used in handoff routing
- **`grok`** — the LLM backend assigned to this agent
- **`task`** — the role type (contrasts with `batch` used by the architect)
- **`back-one`** — the propagation token that triggers reverse handoff logic

## Back‑One Propagation: Reverse and Forward Copies

The `back-one` token creates a bidirectional handoff during pack execution. When the refactorer receives a card—typically a "HTW" (Halt, Think, Write) task—the `handoff_lib.bb` script resolves the propagation and generates two card copies:

| Destination | Copy Type | Purpose |
|-------------|-----------|---------|
| **coder** | reverse copy | Returns work to coder for integration |
| **architect** | forward copy | Continues normal workflow progression |

This behavior is confirmed in `handoff_test.clj` by the test `swarm-handoff-refactorer-back-one-writes-reverse-copy`. The test validates that the reverse copy mechanism correctly routes refactored work back one step in the pipeline.

## Internal Handoff Logic in handoff_lib.bb

The propagation resolution happens in `swarmforge/scripts/handoff_lib.bb`, which reads the role propagation table from `.swarmforge/roles.tsv`. The library matches the refactorer's `back-one` token against known propagation patterns:

```clojure
(is (str/includes? (:out coder) "forward-only"))   ; coder receives reverse copy
(is (str/includes? (:out cleaner) "back-one"))    ; cleaner (if present) would get back-one
(is (str/includes? (:out architect) "back-all")) ; architect gets forward-only

```

While the test assertions name other tokens, they demonstrate the token-to-behavior mapping that `handoff_lib.bb` implements. The refactorer's `back-one` specifically triggers the **reverse-copy** handoff path.

## The Refactorer's Purpose in the Workflow

Unlike agents with `forward-only` or `back-all` tokens, the refactorer never creates new batches. Its design serves a precise purpose:

1. Receive a task card from upstream (typically the coder)
2. Apply automated refactoring using its assigned LLM
3. Hand the improved code **backward** to the coder via reverse copy
4. Simultaneously send a **forward copy** to the architect for awareness

This "nudge backward" pattern lets the coder review and integrate refactoring changes before the architect finalizes the batch. It prevents architectural bottlenecks while maintaining code quality gates.

## Inspecting a Pack's Propagation Configuration

You can verify how SwarmForge interprets the refactorer role by examining the generated role table:

```bash
$ cat .swarmforge/roles.tsv
specifier   task    forward-only
coder       task    forward-only
refactorer  task    back-one
architect   batch   back-all

```

This TSV file is consumed by `handoff_lib.bb` during execution. The third column shows why the refactorer behaves differently from its peers: `back-one` triggers reverse routing, while `forward-only` and `back-all` follow unidirectional paths.

## Complete Configuration Example

A minimal four-pack [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) with the refactorer properly configured:

```clojure
; swarmforge.conf
window specifier grok specifier task forward-only
window coder grok coder task forward-only
window refactorer grok refactorer task back-one
window architect grok architect batch back-all

```

Running SwarmForge in test-parse mode confirms the refactorer token is recognized:

```bash
$ ./swarmforge.bb --test-parse /tmp/my-pack
...
refactorer Refactorer
task back-one
...

```

## Summary

- The **refactorer agent** is defined with `task back-one` in [`swarmforge.conf`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf)
- **`back-one`** triggers a **reverse copy** to the coder and **forward copy** to the architect
- **`script_test.clj`** (lines 306–307) validates the configuration parsing
- **`handoff_test.clj`** verifies the bidirectional handoff behavior
- **`handoff_lib.bb`** implements token resolution and routing logic
- The refactorer improves code quality without stalling the architect's batch workflow

## Frequently Asked Questions

### What makes the refactorer different from other SwarmForge agents?

The refactorer is the only default agent that propagates **backward** using `back-one`. The specifier and coder use `forward-only`, while the architect uses `back-all`. This unique bidirectional propagation lets the refactorer return work to the coder rather than pushing everything forward.

### Where is the refactorer's propagation behavior tested?

The `swarm-handoff-refactorer-back-one-writes-reverse-copy` test in `test/swarmforge/handoff_test.clj` explicitly validates that the refactorer creates both reverse and forward copies. Configuration parsing tests appear in `test/swarmforge/script_test.clj` at lines 306–307.

### Can I change the refactorer's propagation token?

Technically yes, but this would break the four-pack's intended workflow. The `back-one` token is hardcoded into `handoff_lib.bb`'s routing logic. Changing it to `forward-only` would make the refactorer behave like a second coder; changing to `back-all` would skip the coder entirely and return all work to the specifier.