# Terminal Broadcast vs Git Handoff: How Swarm-Forge Handles Workflow Completion

> Discover how Swarm-Forge's terminal broadcast differs from standard git handoffs. Learn how this unique method signals recipients to merge and stop.

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

---

**A terminal broadcast is a special git handoff where the `to:` field contains every other role in the pack, signaling recipients to merge and stop rather than forward the commit onward.**

In the **Swarm-Forge** framework, git handoffs coordinate work between roles in a software development pack. While most handoffs chain forward through single recipients, the terminal broadcast serves as a clean termination mechanism for completed work. Understanding this distinction is essential for anyone implementing or auditing Swarm-Forge workflows.

---

## What Is a Normal Git Handoff?

A standard **git handoff** transfers a commit from one role to the next role in the sequence. These handoffs are **single-recipient** by design.

The `to:` field names exactly one target role. After merging the commit, that recipient **must** create and forward a new handoff to continue the chain.

```text
type: git_handoff
from: coder
to: cleaner
recipient: cleaner
priority: 50
task: task-1-cave-setup
commit: a1b2c3d9

```

In this example, `cleaner` receives the handoff, merges commit `a1b2c3d9`, then forwards a new handoff to `architect`. The workflow continues until reaching the final role.

---

## What Makes a Terminal Broadcast Different?

A **terminal broadcast** appears **only at the last role** in a pack. Instead of naming one recipient, the `to:` field enumerates **every other role** in the pack. This structural difference triggers fundamentally different behavior.

### Key Distinctions: Terminal Broadcast vs Normal Git Handoff

| Feature | Normal Git Handoff | Terminal Broadcast |
|---------|-------------------|--------------------|
| **`to:` field** | Single recipient (next role) | **Full list of all other roles** |
| **`recipient` header** | Identifies the sole target | Identifies which copy this is (audit trail) |
| **Forwarding behavior** | Recipient **must forward** after merging | Recipients **merge only, do not forward** |
| **Completion signal** | Implicit via chain continuation | **Explicit**: full recipient list = Done |
| **Partial `to:` list** | Continues normal handoff chain | **Not terminal** — only complete list counts |

The **handoff protocol** specification in [`swarmforge/handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/handoff-protocol.md) defines these rules explicitly: when the last role's `git_handoff` contains a complete `to:` list, it *marks the card Done* and recipients **merge only** without re-forwarding [L176-L190].

---

## Terminal Broadcast Example

When the **QA** role (final in a six-pack) completes validation, it broadcasts to all five preceding roles:

```text
type: git_handoff
from: QA
to: coder,cleaner,architect,hardender,specifier
recipient: QA
priority: 50
task: task-1-cave-setup
commit: a1b2c3d9

```

Each of the five roles receives this handoff, merges the commit, and **stops**. No forwarding occurs. The card's workflow terminates cleanly.

---

## Creating a Terminal Broadcast in Practice

The [`merge_and_process.sh`](https://github.com/unclebob/swarm-forge/blob/main/merge_and_process.sh) script assembles broadcast handoffs by building the full recipient list dynamically:

```bash
#!/usr/bin/env bash
ROLE="QA"

# Build comma-separated list of all roles from roles.tsv

TO="$(awk -F',' '{print $2}' .swarmforge/roles.tsv | paste -sd',' -)"

cat > "$OUTBOX/tmp/${SEQ}_broadcast.handoff" <<EOF
type: git_handoff
from: $ROLE
to: $TO
recipient: $ROLE
priority: 50
task: $TASK
commit: $COMMIT
EOF

```

The **handshaked.bb** daemon monitors `outbox/` for these files, validates the broadcast structure, and distributes copies to each recipient's inbox.

---

## Why the Terminal Broadcast Design Matters

### Auditability

The full `to:` list preserves complete participation records. Auditors examining any copy can see exactly which roles received the final state.

### Clean Termination

Removing the forwarding step eliminates ambiguity about workflow completion. The **presence of a complete recipient list** serves as an unambiguous terminal signal.

### Reliability

By preventing further forwarding, the broadcast reduces risks of:
- **Lost handoffs** at chain termination
- **Duplicate processing** from redundant forwards
- **Infinite loops** from misconfigured routing

The test suite validates this in `test/swarmforge/pack_ui_test.clj` through cases like `two-pack-end-broadcast-marks-the-card-done`, ensuring broadcasts properly mark cards as completed.

---

## Summary

- **Normal git handoffs** use single recipients and mandatory forwarding to progress work through a role sequence.
- **Terminal broadcasts** use complete recipient lists, appear only at the final role, and terminate workflow without forwarding.
- The distinction is enforced by **protocol rules** in [`handoff-protocol.md`](https://github.com/unclebob/swarm-forge/blob/main/handoff-protocol.md) and **implementation logic** across `handshaked.bb`, [`merge_and_process.sh`](https://github.com/unclebob/swarm-forge/blob/main/merge_and_process.sh), and [`ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh).
- Terminal broadcasts improve **auditability**, provide **explicit completion signals**, and reduce **termination errors**.

---

## Frequently Asked Questions

### What happens if a terminal broadcast has a partial `to:` list?

A partial recipient list **does not trigger terminal behavior**. According to the handoff protocol, only a *complete* list of every other role marks the broadcast as terminal. Partial lists are treated as ordinary multi-recipient handoffs that would require forwarding—though such configurations are generally invalid in standard Swarm-Forge operation.

### Can any role send a terminal broadcast, or only the last role?

Protocol semantics designate terminal broadcasts for **the last role only**. While the daemon may technically process any validly-formed handoff, sending a terminal broadcast from a non-terminal role would violate pack workflow invariants and likely cause cards to be incorrectly marked Done before completing their full role sequence.

### How does a recipient know whether to forward or stop?

Recipients examine the `to:` field contents against their knowledge of pack membership. If `to:` contains **all other roles**, the handoff is terminal—merge and stop. If `to:` contains **one role** (including self), forward after merging. The [`ready_for_next_task.sh`](https://github.com/unclebob/swarm-forge/blob/main/ready_for_next_task.sh) script implements this decision logic.

### Where is the terminal broadcast behavior tested?

The test suite in `test/swarmforge/pack_ui_test.clj` includes specific cases verifying that broadcasts correctly mark cards as done without further forwarding. These tests validate both the protocol semantics and the integration between script components.