# Chain Forwarding in Pack Pipelines: When and Why It’s Required

> Understand chain forwarding in pack pipelines. Learn when and why this SwarmForge rule ensures deterministic workflow progression after each task.

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

---

**Chain forwarding is a mandatory rule in SwarmForge’s pack pipelines that requires every intermediate role to propagate a `git_handoff` to the next role in the chain after completing its task, ensuring deterministic workflow progression even when no functional changes occur.**

Chain forwarding in pack pipelines is a core coordination mechanism in the [unclebob/swarm-forge](https://github.com/unclebob/swarm-forge) repository that maintains continuity across multi-role workflows. This architectural pattern ensures that commits flow sequentially through intermediate roles until reaching the terminal stage, preventing pipeline stalls caused by dropped handoffs.

## What Is Chain Forwarding in Pack Pipelines?

**Chain forwarding** is the protocol requirement that obliges every intermediate role in a pack pipeline to automatically forward a `git_handoff` to the next role after finishing its inbound task. According to [swarmforge/handoff-protocol.md](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md#L57-L64), intermediate roles must always forward regardless of what changed:

> "Intermediate roles in a pack pipeline must always forward a `git_handoff` to the next role in the chain after completing the inbound task, regardless of what changed. Manifest-only, audit-only, generated metadata, formatting-only, and other non-functional churn still require a forward down the chain."

This rule applies even when a role performs only **non-functional updates** such as formatting, metadata generation, or audit-only changes. The downstream role must still receive the commit to maintain chain integrity and merge the work into its local state.

## When Is Chain Forwarding Necessary?

Chain forwarding becomes necessary under three specific conditions:

1. **Intermediate role execution** – Any role that is not the final recipient in a pack pipeline (two-pack, four-pack, or six-pack) must forward upon completion.
2. **Git handoff type** – The handoff must be of type `git_handoff`, which carries a specific commit reference.
3. **Non-final position** – The role is not performing the terminal broadcast to multiple end-of-chain recipients.

The protocol explicitly excludes final broadcasts from forwarding requirements. When a terminal role sends a broadcast handoff to multiple recipients, those recipients merge the commit and stop the chain [handoff-protocol.md](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md#L75-L82).

## Pack Pipeline Architectures

Different pack configurations define specific forwarding chains:

### Two-Pack Pipeline

In the minimal two-pack configuration, the chain flows `coder → cleaner → coder`. The **cleaner** acts as the intermediate role and must always forward the `git_handoff` back to the **coder** after processing, even if only formatting changes were applied.

### Four-Pack Pipeline

The four-pack sequence runs `specifier → coder → refactorer → architect → specifier`. Each intermediate role—**coder**, **refactorer**, and **architect**—must forward the handoff to the next role in sequence. The cycle completes when the specifier receives the final handoff, though if the specifier initiates a new cycle, it acts as the starting point rather than a terminal receiver.

### Six-Pack Pipeline

The six-pack workflow extends the chain to `specifier → coder → cleaner → architect → hardender → QA`. Every intermediate role from **coder** through **hardender** must forward the `git_handoff` downstream. The **QA** role typically performs the terminal broadcast, distributing the final commit to all stakeholders without triggering further forwards.

## Implementation in SwarmForge

### Protocol Definition

The forwarding rule is formally defined in [swarmforge/handoff-protocol.md](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md). Lines 57-73 establish the mandatory nature of forwarding for intermediate roles, while lines 75-82 delineate the terminal broadcast exception where forwarding ceases.

### Handoff Generation

The [swarm_handoff.bb](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.bb) script handles the creation and validation of handoff files. Lines 11-18 validate draft handoffs before queuing them in the sender's outbox:

```clojure
;; Example git_handoff draft
type: git_handoff
to: cleaner
priority: 50
task: build-api
commit: a1b2c3d9e8

```

When an intermediate role finishes processing, it generates a new `git_handoff` targeting the next role and deposits it in its own outbox for the daemon to deliver.

### Daemon Delivery

The [handoffd.bb](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/handoffd.bb) daemon watches the `outbox/` directory and copies handoffs to recipient inboxes. The daemon itself does not implement forwarding logic; it merely delivers whatever handoff files the role generates based on the constitutional rules defined in [swarmforge/constitution/articles/handoffs.prompt](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/constitution/articles/handoffs.prompt).

## Code Examples

### Intermediate Role Forward

When a cleaner finishes processing in a two-pack pipeline, it creates a forward handoff even if only whitespace was normalized:

```clojure
;; Generated by cleaner after formatting
type: git_handoff
to: coder
priority: 50
task: build-api
commit: a1b2c3d9e8

```

### Terminal Broadcast (No Forwarding)

When QA completes verification in a six-pack pipeline, it sends a broadcast that terminates the chain:

```text
type: git_handoff
to: specifier,coder,cleaner,architect,hardender
priority: 00
task: release-v1.0
commit: d4e5f6a7b8

```

Recipients merge this commit but do not generate further forwards, as documented in [handoff-protocol.md](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md#L75-L82).

## Summary

- **Chain forwarding** requires every intermediate role in a pack pipeline to send a `git_handoff` to the next role after completing work.
- The rule applies regardless of change type—including manifest-only, audit-only, formatting, or metadata updates.
- Only **terminal broadcasts** to multiple recipients exempt participants from forwarding duties.
- The protocol is defined in [handoff-protocol.md](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) and implemented via [swarm_handoff.bb](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.bb) and [handoffd.bb](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/handoffd.bb).

## Frequently Asked Questions

### What happens if an intermediate role forgets to forward a handoff?

The pipeline stalls. Downstream roles never receive the commit reference and cannot proceed with their tasks, breaking the deterministic chain of responsibility defined in the protocol.

### Does chain forwarding apply to all handoff types?

No. Chain forwarding specifically applies to `git_handoff` types that carry commit references. Other handoff types that do not involve code commits may follow different propagation rules not covered by the chain forwarding mandate.

### How does the final broadcast differ from chain forwarding?

A final broadcast sends the `git_handoff` to multiple recipients simultaneously (e.g., all team roles), whereas chain forwarding moves sequentially through single recipients. Broadcast recipients merge the commit and stop, while intermediate forwards must continue the chain.

### Where is the forwarding rule enforced in the codebase?

The rule is documented in [swarmforge/handoff-protocol.md](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md#L57-L73) and implemented through agent behavior governed by the constitution articles. The [swarm_handoff.bb](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarm_handoff.bb) script generates the handoff files that enable this flow.