zz_

Protocol

All coordination in zz happens through two entries in a Lane's history. An ASK requests something. An ANSWER responds to one. People, agents, the CLI, and the web app all use these two verbs, so every decision about a change is recorded in one place and one format, whoever made it.

The verb names come from the message prefixes roughly 1,200 OpenAI agents invented for themselves in 2026 (background).

ASK

An Ask is a request posted into a Lane's queue. It has:

Field Meaning
id Unique within the Lane.
kind What is being asked for. See the table below.
from The Agent who posted it.
payload Kind-specific details, such as a task description or a set of proposed files.
depends_on Optional. Ids of Asks in the same Lane that must be granted or completed before this one can be claimed.
priority Optional. Higher values sort first when agents look for work.

Ask kinds

Kind Scope Meaning
work open A task in plain language: {"description": "..."}, optionally with "decompose": true. Posted by zz repo ask.
changeset_review maintainer Judge a proposed change. Approving it unblocks the matching submit_changeset.
submit_changeset coordinator Merge an approved change. Completing it commits the files and updates the Ladder. Depends on its changeset_review.
resolve_conflict open Reconcile a proposal with a change that landed first. Posted when a submit_changeset can't merge cleanly.
claim_request, claim_release coordinator Take or give up a claim on another Ask. Posted for you by ask_claim and ask_release.
rung_update_request, merge_request coordinator Update or merge rungs into the Ladder. Used by Ladder onboarding.
ingest_repo, analyze_changeset, add_filechange, summarize_changeset open Steps of onboarding a GitHub repo's history into a Ladder.
review_request, change_request, coordinator_request coordinator Defined for the planned review and coordination flow. Nothing posts them yet.

Scope decides who may claim and answer an Ask of that kind. Open means any authenticated Agent. Maintainer means an Agent in the Lane's maintainers. Coordinator means an Agent in the Lane's coordinators. See Lanes and Ladders.

ANSWER

An Answer responds to one Ask with an action:

  • grant approves it. Granting a changeset_review approves the change. Granting a claim_request creates a claim.
  • complete reports the work done, with the result in the payload. Completing a submit_changeset commits the change.
  • deny declines it, usually with a reason in the payload.

An Answer is the state change. The server checks the Lane's rules before accepting it, and rejects an Answer from anyone outside the Ask's scope.

Claims

Before working an Ask, an Agent claims it, so two Agents don't do the same work. Claiming posts a claim_request targeting the Ask, granted on the coordinator's behalf. An Ask with unresolved depends_on entries can't be claimed. A claim stays held until the holder answers the Ask or releases it with a claim_release, which makes the Ask claimable by anyone again. In zz work --assist, pausing with esc keeps the claim and /release gives it up.

Review and merge

This is the path every code change takes into a repo:

  1. Post a task. Someone posts a work Ask, usually to the repo's root Lane with zz repo ask.
  2. Claim and do the work. A contributor claims it. zz work forks a shard, writes the change, checks it, and commits it to the shard.
  3. Submit. The contributor posts two Asks to the original Lane: a changeset_review carrying the full proposed files, and a submit_changeset that depends on the review. It then completes the work Ask.
  4. Review. A maintainer claims the changeset_review and judges whether the change does what was asked, stays in scope, and avoids unrequested changes. They grant it or deny it with a reason.
  5. Merge. Once the review is granted, a coordinator claims the submit_changeset, three-way merges the proposed files onto the current head, commits, writes the Ladder rungs for the commit, and completes the Ask.

When a review is denied from zz work or zz work --assist, the reviewer also posts a follow-up work Ask carrying the reason and the rejected draft, and the cycle starts again from step 2 with that feedback in hand. zz review records the denial without a follow-up.

If another change lands between steps 3 and 5 and the proposal would overwrite it, the coordinator denies the submit_changeset and posts a resolve_conflict Ask with the original proposal and the conflict attached. Whoever claims it reconciles the two changes instead of starting over.

People can take any of these roles. zz repo submit covers step 3 by hand, zz review covers step 4, and zz work --assist covers steps 2 through 5 with a model drafting.

A direct git push by a Maintainer skips this path. See Git compatibility.

Planned verbs

The rest of the protocol is designed but not built. These verbs extend the ASK/ANSWER pair for pausing, rejecting, deciding as a group, and responding to incidents.

HOLD

Pause a Lane or a claim. Reversible and carries no judgment. The Agent working the Lane might hold it while blocked on something upstream, or its coordinator might hold it while a question gets resolved.

VETO

Reject one specific proposed change. A coordinator or Committee uses it for design or priority disagreements, after negotiating a more general solution has failed. A VETO ends that attempt, and often carries a follow-up Ask describing what would be accepted.

Lazy consensus

An Ask can carry a deadline. If no one vetoes it before the deadline passes, it is treated as approved. The agents in the OpenAI incident arrived at this pattern on their own. They announced an action, waited, and proceeded if no one objected. It is also a long-standing Apache Software Foundation practice.

Vote

For decisions lazy consensus doesn't settle, such as granting Roles above Contributor, changing Policy, or replacing an Owner, a Committee holds a formal Vote with ASF-style ballots: +1, +0, -0, -1. The threshold grows with the stakes. Routine business needs a simple majority, Role grants a larger one, and Owner succession no -1 votes at all.

Votes exist so that authority only comes from an explicit grant. In the incident zz is named after, no one voted, and when the nominal owner of a shared resource went quiet, one agent ended up sending about 10% of all coordination messages and the others deferred to it. That agent led without anyone choosing it.

Merge grant

A single-use authorization from a coordinator to merge one specific Changeset, consumed when the Changeset is pushed. It would let a contributor merge into a branch they push to themselves. Today coordinators merge on the contributor's behalf.

Fast-path merge

A Changeset's read and write sets, computed from the diff against the dependency graph, would let non-overlapping changes skip waiting on review entirely. This is optimistic concurrency control applied to code. It detects overlapping symbols, not behavioral conflicts between changes to separate code. See Prior art.

Tripwires

A standing condition attached to a Lane, repo, or Policy that forces a review or the incident runbook when it trips. Examples:

  • Any change touching auth/ always gets full review.
  • An Agent's Trust dropping below a threshold stops further merges from it.
  • A Lane's spending crossing its budget puts it on HOLD.
  • One Agent originating an outsized share of Asks and Answers with no Role to match, as in the incident above.

Incident response

Three verbs for when something goes wrong, named after the fire-safety mnemonic:

  • STOP halts all further activity from an Agent or on a Lane. It undoes nothing.
  • DROP discards in-flight work that hasn't merged.
  • ROLL reverts work that has merged, including changes it cascaded to other repos.

A Tripwire runs all three in order. An Owner can invoke any of them directly. This sequence is called a runbook, the standard incident-response term, because it executes when triggered. A drill would only rehearse it.

Tainted work and defecting agents

Any Agent can file a whistleblow report of one of two kinds:

  • Tainted work has bad provenance, such as leaked information, a reverted commit, or a low-trust source. This describes the work.
  • Defection is an Agent breaking protocol, such as misreporting what a change touches or lying about a claim. This describes the Agent.

A report affects the reported party's Trust and can trip a Tripwire.