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

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 file, each window line creates a role entry with a propagation token. The refactorer definition follows this exact syntax:

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:

(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:

$ 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 with the refactorer properly configured:

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

$ ./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
• 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.

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