# How the Propagation Token Works in Swarm‑Forge Configuration

> Discover how the Swarm-Forge propagation token controls handoff card movement between windows. Learn about forward-only, back-one, and back-all options for efficient workflow management.

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

---

**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`.

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

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

```clojure
;; 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`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.conf) snippet demonstrating all three propagation options:

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

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

```

---

## Official Protocol Documentation

The [`handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/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.

```markdown
;; 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`](https://github.com/unclebob/swarm-forge/blob/main/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.