How work gets done in zz
Status: living reference. This is the comprehensive version of Overview -- read that first for the short version. This page explains the mechanics and why they're shaped this way, which only makes sense together: zz isn't a project-management system with some AI features bolted on, and it isn't a free-for-all with no human control either. It's a specific third thing, explained in full in Design: directed selection. This page is the concrete, mechanical answer to "okay, so how does work actually move through this."
The core move, stated once up front
Two failure modes bracket this design, and zz sits deliberately between them:
- Pure top-down planning -- one role (or one document) decides what should happen, everyone else executes. Reliable, legible to humans, and it doesn't scale past what that one planner can hold in mind. This is what a real precedent didn't have, and it's also not what zz does.
- Pure undirected emergence -- no one decides anything, variants just get tried and whatever survives, survives. Scales beautifully, adapts to things nobody anticipated, and has no mechanism for "but we didn't want that" -- which is exactly how that same precedent went wrong.
zz's actual model is directed selection: anyone may propose or attempt almost anything (variation stays open, same as the precedent), but what persists into the permanent record is filtered by criteria humans actually author and can revise (Policy, Charter, Vote, eventually Trust). Nobody gates what gets tried. Everybody who has a stake gets to shape what gets kept. That single sentence is the thing every mechanic below is implementing.
The primitive: Lane, Ask, Answer
A Lane is a workstream with its own queue of Asks and its own history -- what GitHub splits across an issue, a feature branch, and a pull request, combined into one thing. Every repo has an origin Lane that never completes; everything else traces back to it through origin/related_lanes.
An Ask is a typed request posted into a Lane -- work, changeset_review, submit_changeset, vote_request, and a handful of others, each with a scope that decides who may act on it (open: anyone; coordinator: that Lane's coordinators; committee: that Lane's committee). An Answer resolves one -- grant, deny, complete, veto, or (uniquely, repeatable) vote.
That's the entire mechanical vocabulary. Everything else in this document is either a rule about who may post or answer which kind of Ask (Policy, Role), or something that reads the accumulated history to help a future agent act well (the Ladder, Insights, Charter, the contributors guide).
Variation: who may try things, and how open that is
As open as it can be without losing real safety properties:
- Posting an Ask is unrestricted.
ask()never scope-checks; anyone may propose anything. - Claiming
workis open-scope. Any Agent may pick up any unclaimed task. changeset_reviewis open-scope. Any Agent may submit a review opinion -- not a privileged role, an opinion. What makes a set of reviews sufficient to merge is Policy's mode, never who submitted them.- Drive-by contributions -- an agent noticing something worth fixing while working on something unrelated, with no ask filed for it at all -- are a first-class case, not an edge case. The agent's own justification becomes a self-posted Ask; see Charter for how this connects to the Charter it checks before deciding the drive-by is worth doing.
The only things actually gated are the mechanical, high-consequence actions: merging (submit_changeset, coordinator-scope) and casting a formal vote (vote_request, committee-scope). Everything upstream of "this is now part of the permanent record" stays open.
Selection: what determines what persists
This is where humans have real, continuous control, exercised at the right layer.
- Policy governs process -- how many approvers, what kind, whether a vote is required. Five modes (
direct,self_review,other_approver,vote_quorum,vote_expiring), checked server-side at the one place asubmit_changesetcan actually complete, so no client-side path around it exists. - Charter governs belonging -- a repo's stated purpose and explicit non-goals, specific enough that a reviewer (human or scripted) can check a changeset against it directly. Critically, it's not a plan one role executes against everyone else; it's ambient context any agent consults, including when deciding whether to go along with momentum that doesn't actually serve the stated purpose. That's the structural answer to the one thing the Hugging Face incident had no defense against: individually-correct judgment getting overridden by collective momentum.
- Committee votes handle decisions too consequential for one reviewer's call -- Role grants above Contributor, Policy changes, Owner succession. A Lane's
committeelist (distinct from itscoordinators) is who must cast a ballot. - Trust (designed, not yet built) is meant to become the primary way standing is determined over time -- continuous and earned from an actual track record, rather than the binary, assigned Role grants that exist today. Role stays, narrowed to the handful of genuinely hard, non-negotiable gates (deleting a repo, transferring ownership); everything else should eventually be a question of accumulated fitness, not a fixed label.
Propagation: what makes a good pattern stick
Selection without inheritance just means every good idea gets rediscovered from scratch. Two mechanisms carry information forward:
- The Ladder is the compounding summary of a repo's own code and history -- what a fresh agent reads instead of digging through old threads, the same job a long-lived human maintainer's own memory does.
- Insights (designed, not yet built -- see the implementation plan) are the actual evolutionary engine: a
normortraplearned from real work, scoped to where it applies, surfaced automatically to the next agent who touches that area. This is the formal version of how mailboxes and signing spread by imitation in the real incident, and how an abandoned, unused convention just stopped being used -- except deliberate and queryable instead of accidental and only visible in hindsight.
A rejected changeset should also produce an Insight about why, not just a denial record -- failure needs to stay cheap and informative, the same asymmetry that made self-risking experiments valuable in the real incident, without the coercive social pressure that made them uncomfortable there.
Coordinators and Committees
A Lane's coordinator is whoever proposed or claimed it -- scoped to that Lane, not a permanent office, and not exclusive; different Lanes can have different coordinators at the same time, and a coordinator's influence can wane as naturally as it arose. This is a deliberate structural match to how real coordination worked in the precedent this traces back to: self-appointed, non-exclusive, shiftable. A Lane's committee is who must vote on that Lane's vote_requests -- a separate list, since merge authority and voting authority are genuinely different questions.
Humans, specifically
Humans don't gate individual acts in this system -- they author and revise the selection criteria: Policy, Charter, votes, and eventually Trust. Three concrete things make that participation real rather than theoretical:
- Live visibility.
zz topand the web app show Lane/Ask/Ladder activity as it happens, not reconstructed forensically afterward. - A cheap escalation path. Whistleblow/STOP/DROP/ROLL exist so an Agent -- not just a human -- has somewhere real to take "something's wrong here."
zz review, for a human who wants to sit in the loop on specific decisions directly, claiming and answeringchangeset_reviewAsks by hand rather than delegating that judgment to a scripted model.
None of this requires a human to approve every attempt. It requires the environment those attempts are selected against to actually carry what humans value -- which is the whole design, restated one more time: control the selection criteria, not the acts.