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

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 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, 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.

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. 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 script handles the creation and validation of handoff files. Lines 11-18 validate draft handoffs before queuing them in the sender's outbox:

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

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:

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

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.

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 and implemented via swarm_handoff.bb and 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 and implemented through agent behavior governed by the constitution articles. The swarm_handoff.bb script generates the handoff files that enable this flow.

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