How the Propagation Token Works in Swarm‑Forge Configuration

The propagation token in Swarm‑Forge controls how handoff cards travel between windows, with three options: forward-only (default), back-one (single‑step back‑propagation), and back-all (broadcast to all previous windows).

This article explains the propagation token mechanism in Swarm‑Forge, an open‑source, AI‑native build system by Robert C. Martin (Uncle Bob). Understanding how this token controls card flow is essential for configuring multi‑window pipelines with feedback loops or collective review stages.

---

What Is a Propagation Token?

In Swarm‑Forge, each window defines a role with a receive mode (task or batch) followed by an optional propagation token. The token determines whether processed cards move forward only or generate copies that travel backward through the pipeline.

Token	Meaning	Effect on Card Flow
forward-only (default)	Card sent forward to next window only	No backward travel; normal forward pipeline
back-one	Copy sent one window back after processing	Single‑step back‑propagation for quick feedback
back-all	Copies sent back to every previous window	Collective review or broadcast‑like feedback

---

Parsing the Token in swarmforge.bb

The configuration parser receive-fields in swarmforge.bb inspects fields that follow the receive mode. If a field matches one of the three allowed values, it captures that token; otherwise it defaults to forward-only.

;; Located in swarmforge/scripts/swarmforge.bb, lines 49-56
;; The receive-fields function parses the optional propagation token

Each parsed window row includes the token in its :propagation key. The window-row function returns a map containing this value.

;; Located in swarmforge/scripts/swarmforge.bb, lines 82-94
;; window-row populates the :propagation key

---

Runtime Token Retrieval with handoff_lib.bb

Swarm‑Forge writes the normalized receive mode and propagation token to .swarmforge/roles.tsv at configuration time. Runtime helpers read this file instead of re‑parsing the configuration.

The role-propagation helper in swarmforge/scripts/handoff_lib.bb extracts the token from column 7 of a role's row:

;; Located in swarmforge/scripts/handoff_lib.bb, lines 76-78
(role-propagation "cleaner")
;; => "back-one"

If column 7 is empty, role-propagation defaults to forward-only.

---

Configuration Examples

Here is a complete swarmforge.conf snippet demonstrating all three propagation options:

;; swarmforge.conf
window coder    copilot   worktree1 task        forward-only   --yolo
window cleaner  copilot   worktree2 batch       back-one        --allow-all-tools
window architect copilot  worktree3 batch       back-all

Line 1: coder window uses explicit forward-only (could be omitted since it's the default).

Line 2: cleaner window uses back-one — after processing, a copy returns to coder.

Line 3: architect window uses back-all — after processing, copies return to both cleaner and coder.

The parsed result stored internally:

{:role "cleaner"
 :agent "copilot"
 :receive-mode "batch"
 :propagation "back-one"
 :extra-args "--allow-all-tools"}

---

Official Protocol Documentation

The handoff-protocol.md file in the Swarm‑Forge repository formalizes this syntax. According to the specification, the optional propagation token follows the optional receive mode and defaults to forward-only when omitted.

;; Located in swarmforge/handoff-protocol.md, lines 49-55
;; Documents that propagation token defaults to forward-only

The protocol distinguishes movement (forward-only) from merge‑only copies sent backward (back-one, back-all).

---

Key Files and Their Roles

File	Purpose
swarmforge/scripts/swarmforge.bb	Parses configuration, extracts propagation token via receive-fields, stores in :propagation key
swarmforge/scripts/handoff_lib.bb	Provides role-propagation to read token from .swarmforge/roles.tsv column 7
swarmforge/handoff-protocol.md	Documents token syntax and semantics
test/swarmforge/script_test.clj	Tests propagation token parsing and round‑trip through roles.tsv

---

Summary

• Three tokens: forward-only, back-one, back-all control card distribution after window processing
• Parsed by receive-fields in swarmforge.bb and stored in each row's :propagation key
• Defaults to forward-only when not explicitly specified
• Persisted to .swarmforge/roles.tsv for runtime access via role-propagation
• Enables feedback loops (back-one) or collective review (back-all) while maintaining forward pipeline integrity

---

Frequently Asked Questions

What happens if I omit the propagation token in my window definition?

The token defaults to forward-only. According to the Swarm‑Forge protocol specification and the receive-fields implementation in swarmforge.bb, any unrecognized or missing value falls back to this default. The role-propagation helper in handoff_lib.bb also returns forward-only when column 7 of roles.tsv is empty.

Can I use back‑propagation with task mode, or only with batch mode?

The propagation token is independent of receive mode. Both task and batch windows accept any of the three tokens. The receive mode controls how cards enter a window; the propagation token controls where cards go after processing.

How does back‑all differ from creating multiple explicit handoffs?

back-all automatically targets every previous window in declaration order. This is declarative and maintenance‑free — adding a new earlier window automatically includes it in the backward broadcast. Explicit handoffs would require manual updates to each downstream window configuration.

Where is the propagation token actually used at runtime?

Runtime code reads the pre‑parsed value from .swarmforge/roles.tsv rather than the original configuration. The role-propagation function in handoff_lib.bb performs this lookup. The handoff engine uses this value to determine whether to generate backward‑flowing card copies after window processing completes.

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