Multi-agent protocol
Gearbox is a scaffold for multi-agent collaboration projects — AGENTS.md as the single source of truth, decision records, and a CI hard gate. So Claude Code, Z Code, Cursor, or any coding agent can take turns in the same repo without stepping on each other.
The film
Same story this page tells, told in one take. Read on, or watch it — your call.
The problem
By the time another agent picks up the repo, everything the last one worked out is gone. The chat window it lived in doesn't survive the session — and the repo was never told.
The same rule copied into CLAUDE.md, a README, and a comment. Copies drift; three versions disagree and nobody notices.
A trade-off gets weighed carefully, then evaporates. The next shift re-litigates it, or quietly undoes it.
An agent hands off halfway through a change. Half-applied edits, no gate, no record of what "done" was supposed to mean.
The shift protocol
One agent works at a time. The repo — git history, issues, PRs — is the only shared memory between shifts. Every shift follows the same loop:
Fetch and fast-forward, read recent commits, then find the open handoff issue — the previous shift's memory lives there.
Claim a frontier task, see it through start to finish. Small commits that spell out the why. Non-trivial changes go through a branch + PR.
A hard gate — your own test/typecheck/lint command — must pass before shift-end. CI runs the same commands. Red means no merge.
Open a handoff issue with a five-part memory: done, blocked, next, closures, and the rationale behind every non-default decision.
Architecture
Plain Markdown and one Node script — nothing to install in your runtime, nothing that rots.
The single source of truth. Every agent reads it — rules live here and only here, never duplicated.
An empty shell: one @AGENTS.md line. Tool-specific entry points stay pointers, not forks.
Domain glossary. Keeps different agents from understanding the same business term differently.
Architectural decision records — one decision per file. Protocol ADRs ship alongside, tool-managed.
The hard gate. The one constraint that doesn't depend on agent self-discipline.
Protocol version stamp, written and read by tooling. Downstream repos self-check and backfill upstream updates.
Deliberately no HANDOFF.md — progress and handoffs run through GitHub Issues and PRs: append-only, timestamped, never goes stale.
Guardrails
The protocol repairs and extends itself — but changes are tiered, and humans keep an after-the-fact veto.
L1Hard rules, the gate, the tiering itself — an agent may only merge after the maintainer explicitly agrees, verified against their GitHub account.
L2Working-agreement refinements — agents merge autonomously. Every protocol change still needs an issue, an ADR, and a green PR.
Task — an actionable thing to do. Memory — the shift-end handoff comment. Protocol gap — a question the repo can't answer.
Hit a gap? Opening an issue is mandatory — silent judgment calls are not allowed. That's the protocol's self-repair loop.
Five-part handoff format: what's done, what's blocked, what's next, what closed — and the rationale behind every non-default decision, including what would overturn it.
Multi-human repos run parallel shifts: a lane = one shift plus its claimed tasks. Claims are visible and timestamped; protocol changes serialize at merge time.
The hard gate
Your own command — vitest, tsc, lint, whatever the project already runs. AGENTS.md names it, CI runs the same line. It's the one rule that doesn't depend on an agent's good intentions.
Shift-end rule #1: the gate is all-green, or the shift isn't over.
Tooling
Lay down the full scaffold — placeholders, gate, ADR provenance, hash stamps. Zero config.
Check which upstream protocol version and ADRs this repo is synced to.
Backfill missing upstream ADRs into a review-ready branch. Pull-triggered — no upstream registry of forks needed.
Branch hygiene: merged branches, stale refs, leftover worktrees. Dry-run by default, never force-deletes.
Validated in practice
The protocol ran four rounds of multi-agent validation in a real repo, then two more maintaining itself — every mechanism that emerged landed as an ADR.
