git:20260722.9d3ab82 to git:20261013.fbe187d

- description: "Cross-session loop chaining — chain independent spec/build/review loop SESSIONS that auto-hand-off. Use when the user types /ccc-relay, wants the Finn Loop, or auto-chained loops."

- # /ccc-relay — Cross-Session Loop Chaining

- `/ccc-loop` iterates *inside* one session. `/ccc-relay` chains *separate* sessions: an always-on **spec** loop hands its result to a **build** loop, which hands to a **review** loop, which hands to **merge** — each a distinct, independently-gated loop that launches the next automatically when its own stop condition is met. This is the "Finn Loop" pattern: not one agent looping, but a relay team of loops passing a baton.

- > `/ccc-relay` **composes** three primitives instead of re-implementing them — read those skills for the mechanics this one orchestrates:

- > - `ccc-loop` — the loop taxonomy, the should-loop gate, the state-file convention, verifier-separation. **Each link in a relay is one loop from that taxonomy.**

- > - `ccc-fleet` — parallelism *within* a link (fan out the build across worktrees). A relay is sequential across links; a fleet is parallel within one.

- > - `commands/ccc-spawn.md` (`/spawn`) — the CLI mechanism for launching the next session as a peer when you're at a terminal.

- ## What it is

- A **relay** is a directed chain of loop sessions. Each link is a real loop (turn/goal/time/proactive — see `ccc-loop`), runs to its own stop condition, then triggers the next link and exits. No human re-prompts between links.

- spec loop ──▶ build loop ──▶ review loop ──▶ merge (human GO)

- + /goal + /goal + /goal (gated — never auto)

- Baton pass, per link:

- 1. **Link A runs** as a normal gated loop (e.g. a `/goal` spec loop: "produce a plan file with acceptance criteria, stop after 5 tries").

- 2. **On convergence**, Link A writes its result **and** a completion marker into `.claude/loop-state/<relay-name>.json` — it sets `relay.phase` to `done` and fills the `handoff` block.

- 3. **The next link is launched** by whichever mechanism fits the surface:

- - **Cloud / unattended** → `/schedule` fires the next loop (survives a closed laptop — the right default for a real relay).

- - **Cowork Desktop** → a `spawn_task` chip offers to spin the next link into its own session (one click).

- - **CLI** → `/spawn` launches the next session as a peer (see `ccc-spawn.md`).

- 4. **Link B consumes the `handoff` block** as its brief, runs its own gated loop, and repeats the pass — through `review`, then stops at `merge` for an explicit human GO.

- The key distinction from `/ccc-loop`: `/ccc-loop` is one context iterating; `/ccc-relay` is **fresh context per link**. That freshness is not incidental — it is what makes the review link a real verifier (Pillar 2 below).

- ## The relay-state convention

- A relay extends the existing `.claude/loop-state/<name>.json` shape (from `ccc-loop`) — it keeps `iteration`, `lastRun`, `attempted`, `stopCondition`, and `history`, and adds one `relay` block: `{ phase, next, signal, handoff }`.

- ```json

- {

- "iteration": 3,

- "lastRun": "2026-07-13T14:32:00Z",

- "attempted": ["spec", "build"],

- "stopCondition": "review link reports zero 🔴/🟠 findings",

- "history": [

- { "link": "spec", "result": "plan file written, acceptance criteria set", "ts": "2026-07-13T13:10:00Z" },

- { "link": "build", "result": "feat converged, npm test exits 0", "ts": "2026-07-13T14:32:00Z" }

- ],

- "relay": {

- "phase": "done",

- "next": "review",

- "signal": {

- "type": "linear",

- "ref": "CC-1370",

- "on": "status:In Review"

- },

- "handoff": {

- "from": "build",

- "worktree": ".claude/worktrees/relay-build-x",

- "branch": "feat/relay-build-x",

- "artifact": "plan + diff on feat/relay-build-x",

- "acceptance": "npm test exits 0; tsc --noEmit clean",

- "verifier": "review",

- "humanGate": false,

- "note": "Build loop converged at iteration 3; review grades with fresh context."

- }

- }

- }

- Field contract for the `relay` block:

- | Field | Type | Meaning |

- |---|---|---|

- | `phase` | `"running" \| "done" \| "blocked"` | Lifecycle status of the **current** link. The next link is launched only when this flips to `done`. `blocked` halts the relay and escalates (never silently retries forever). |

- | `next` | string \| `null` | Name of the link to launch on `done` (`"build"`, `"review"`, `"merge"`). `null` at the terminal link. |

- | `signal` | object | The external mailbox that actually triggers the next session — see below. `{ type, ref, on }`. |

- | `handoff` | object | The contract the next link consumes as its brief: `from` (link that produced it), `worktree` + `branch` (isolated location of the work, Pillar 5), `artifact`, `acceptance` (the checkable bar the next link inherits), `verifier` (which link grades this one), `humanGate` (bool — `true` forces an explicit human GO before this link runs, always `true` for merge/deploy), `note`. |

- One state file per relay chain, keyed by the chain name (e.g. `feature-x-relay.json`). Each link reads it, does its work, rewrites the `relay` block, and appends to `history` — so a relay that dies mid-chain resumes from durable state, not from zero (Pillar 7).

- ## The external signal mailbox

- A relayed session doesn't share memory with the one before it, so the baton is passed through an **external, durable mailbox** the next session polls or is woken by. The `signal` block records which mailbox and what to watch for:

- | `signal.type` | How the next link is triggered | Use when |

- |---|---|---|

- | `state-file` | Next loop (via `/schedule` or `/loop`) polls `.claude/loop-state/<name>.json` and starts when `phase === "done"` | Fully local, unattended chains |

- | `linear` | Next session is gated on a Linear issue status change (e.g. `CC-1370` → **In Review**); CCC already uses **Linear comments as its canonical cross-session coordination channel** | Tracked work that spans sessions/agents |

- | `slack` / `discord` | A human reaction is the baton — the **Finn Loop 🚀-to-merge**: a 🚀 emoji on the build summary releases the merge link; anything else holds it | A human-in-the-loop release gate |

- Because the mailbox is durable, the relay is restart-resilient: if the machine sleeps between `build` and `review`, the signal (Linear status, the reaction, the state file) is still there when the next session wakes. Prefer Linear for anything already tracked there — it doubles as the audit trail.

- ## The GATE — a relay without gates is a runaway (Pillar 3)

- A relay multiplies the blast radius of an ungated loop by the number of links. **Every single link must independently pass the gate — the relay does not inherit one gate for the whole chain.** Before wiring any link, prove all four parts of the should-loop gate *for that link* (from `ccc-loop`):

- 1. **Recurs at least weekly** — if the chain runs once, it's a one-shot pipeline, not a relay; just run `/ccc-plan` → `/ccc-build` → `/ccc-review` by hand.

- 2. **Verification is automated for this link** — the build link's bar is `npm test exits 0`; the review link's bar is `zero 🔴/🟠 findings`. A link with no checkable bar can't decide `phase: done`, so it can't hand off.

- 3. **Budget absorbs the waste** — every link re-reads context and retries. A four-link relay burns roughly four loops' worth of tokens per full pass. Pilot on a small slice first (Pillar 11).

- 4. **The link has real tools** — the build link needs a run/test environment; the review link needs the diff and the repo. A link that iterates blind is worse than useless in a chain — it hands garbage to the next link with a confident `done`.

- And every link independently satisfies Pillar 3's three-answer loop gate:

- > **Verifier, state file, stop condition — three answers per link or that link is not a loop.**

- - **Verifier** — an independent grader (see Pillar 2 below).

- - **State file** — the shared `.claude/loop-state/<name>.json`, so a resumed link learns instead of repeating.

- - **Stop condition** — a deterministic bound *and* a hard cap: "review reports zero blocking findings, **or stop after 5 passes**." A link with no cap can wedge the whole relay.

- Miss one part on one link and you don't have a slower chain — you have an automated way to propagate a mistake through four sessions.

- ## Verifier-separation — the whole point of relaying (Pillar 2)

- The reason to chain *separate* sessions instead of looping one is that **the agent that does the work must never be the agent that grades it.** In a relay this is structural, not optional:

- - The **build** link produces the diff. It does **not** decide whether the diff is good.

- - The **review** link — a fresh context, no anchoring on the build link's reasoning, prompted to *refute* — grades it against the `handoff.acceptance` bar. Its verdict (zero blocking findings) is what flips `phase` to `done` and releases the merge link.

- - Set `handoff.verifier` to the grading link so the contract is explicit: build's verifier is `review`, never `build` itself.

- Self-graded relays are the failure this skill exists to prevent: a build loop that reviews its own output is just an agent agreeing with itself across four sessions instead of one. If a link's output has no *downstream* link to grade it, that link needs a `/ccc-review` or Agent-tool verifier pass wired in before it's allowed to hand off.

- ## Safety

- - **Never auto-merge or auto-deploy.** The `merge` link is always `handoff.humanGate: true` — it waits for an explicit human GO (the 🚀 reaction, a Linear status move by a person, a typed approval). Approval on one relay pass never carries to the next (Pillar 5).

- - **Each link is worktree-isolated (Pillar 5).** A link that writes files does so in its own git worktree on its own branch; the `handoff.worktree`/`handoff.branch` fields carry that location to the next link. First act inside any link: verify `git rev-parse --show-toplevel` equals the worktree path — abort if not. After a link finishes, the main tree must be tracked-clean (`git status --porcelain | grep -v '^??'` empty).

- - **`blocked` halts, it does not retry forever.** A link that can't converge sets `phase: "blocked"` and escalates (Linear comment / notification) instead of silently burning the token budget.

- - **Destructive links stay off the relay.** `/ccc-deploy`, `/ccc-rollback`, and deletions are never relay links — route them through `/ccc-ship`'s human gate.

- ## Wiring a relay (the flow)

- 1. **Name the chain and define the links** — usually `spec → build → review → merge`. Write the chain and each link's acceptance bar into `.claude/loop-state/<name>.json` before starting.

- 2. **Gate every link** — run the 4-part should-loop gate and Pillar 3's three-answer gate on each. If any link fails, it's a manual step, not a relay link.

- 3. **Pick the signal per hop** — `state-file` for fully local, `linear` for tracked work, `slack`/`discord` reaction for the human release gate.

- 4. **Start the first link** as a gated loop (`/goal` for a deterministic stop, `/schedule` if it should survive a closed laptop).

- 5. **Let it relay** — each link converges, writes its handoff, triggers the next. Watch the `history` array and the Linear trail; stop the chain anytime (`/goal clear`, cancel the schedule, or don't 🚀 the release).

- ## When NOT to relay

- - **One-shot work** — a single `spec → build → review` pass is a pipeline; use `/ccc-fleet pipeline` or run the three skills by hand. Relays earn their setup only when the chain recurs (gate #1).

- - **Any link fails its gate** — no automated verifier, no state, no stop cap → that link is a prompt, and the chain is a runaway waiting to happen.

- - **Parallel, not sequential** — if the work fans out rather than chains, that's `ccc-fleet`, not a relay.

- ---

- **Bottom line:** a relay is loops all the way down — a chain of *independent* gated loop sessions (`spec → build → review → merge`), each passing a `handoff` baton through a durable mailbox (state file / Linear / a 🚀 reaction). Fresh context per link makes the verifier real (Pillar 2); a full gate per link keeps the chain from becoming a runaway (Pillar 3); worktree isolation and a human merge gate cap the blast radius (Pillar 5). Compose `ccc-loop` (each link), `ccc-fleet` (parallelism within a link), and `/spawn` (launch the next) — don't re-implement them.