I put the handoff protocol on GitHub. Templates, spec, worked example.

Yesterday I posted about the protocol I use to chain AI workflows across fresh, stateless sessions. The test of whether your workflow is real: can it propagate itself.

The post landed with DMs asking for the actual shape. So I wrote it down.

Repo: github.com/PUSHINGSQUARES/icm-handoff-protocol

It is a small repo on purpose.

No framework to install.

No runtime.

Just markdown plus a convention.

It sits on top of ICM, the Interpretable Context Methodology (Van Clief and McDermott, arXiv 2603.16021v2, March 2026).

The canonical ICM repo is linked in the README.

Contents:

1. `docs/protocol.md`. The rules. Eight of them. Short.

2. `docs/writing-briefs.md`. How to write a phase brief for a reader who has never met you, which is every fresh session.

3. `docs/executor-tiers.md`. The four-tier pattern, plus how to pick a tier per phase and where the escalation path goes.

4. `docs/verification-provenance-breakpoints.md`. Three optional patterns ported from the ICM paper's Section 6: a `Verify` block for cross-phase consistency checks, decision IDs for output provenance, and in-phase breakpoints for complex judgment calls.

5. `templates/handoff-doc.md`. The master living doc. Copy, fill in, ship.

6. `templates/phase-brief.md`. The per-phase brief template, with every section annotated.

7. `examples/worked-example.md`. An anonymized eight-phase overnight build. What went right, what went wrong, what the protocol did about it.

The README lives at the top.

Quickstart is five steps.

What the repo does not try to be:

- A replacement for ICM. It sits on top. ICM defines the spatial structure of a workspace: folders, layers, stage contracts. The handoff protocol defines the temporal structure of execution across sessions. Different axes. Both useful together.

- A runtime. There is nothing to run. If you already have a way to launch a session with a cd command, you have enough. The protocol is the doc, not the tooling.

- Prescriptive about model choice. The executor tier doc talks about tiers, not specific models. The cheap tier today is not the cheap tier next quarter. The pattern outlasts the prices.

What it does try to be:

- Copy-pasteable. Every template is a file you fork into your workspace and fill in.

- Load-bearing. Every rule in the spec is one I wrote because I got burned by not having it.

- Honest. The worked example includes a phase where a worker misread an acceptance criterion and declared done when it was not. The fix did not go into that phase's brief. The fix went into the template. Every future build benefits. That is the edit-source principle from the ICM paper, applied.

If you have been running AI workflows that survive one session and fall apart at the seam, this is the layer I use to fix that.

If you fork it or adapt it, tell me what you changed. The spec will get better faster when other builders push back on it.

MIT license. Use it however.

3 comments