03 · How it works

The mental model in one breath

Every repo is a hive — its own beads database, embedded as Dolt under the repo's gitignored .beads/. Issues carry a short, stable prefix(acme-api-1) derived from the stable part of identity (org + repo); the parts that can change (provider, org) live in labels. Issue history publishes torefs/dolt/data on the repo's own git remote — a separate ref namespace that never touches branches or PRs, so there is no server to run. A workspace-level aggregate (the hub, or its evolved form Factory HQ) pulls every hive into one view, so you can ask "what's ready to work on anywhere?"

bh is deliberately a thin orchestrator: bd (beads) owns issues,git owns history, git-workspace owns cloning. What bhadds is the process — bh work drives a bead through its lifecycle so agents never improvise raw git / gh pr for the lifecycle itself.

The tenets

⬢Planes, kept separate

Control governs the factory. Planning turns ideas into molecules.Integration executes them. Each plane has its own verbs and seats; they hand off sequentially and never step into each other's role. Assurance is the one exception — a cross-cutting gate layer, not a sequential plane.

⬢Merging is not releasing

Integration is high-frequency and dirty: each bead gets its own worktree and lands on an always-green line. Release is a separate, deliberate, gated act.

⬢Lossless history

Agents do the merging, so history is audited: merge --no-ff at the boundary, never squash there. Workers squash only their own local checkpoints into clean conventional digests before submit (tiered retention).

⬢Unit of work = a bead

Worktree → implement → refine → check → submit → review → merge. One bead, one branch (wt/bead/issue/<id>), one reviewable change.

04 · The pipeline

Planning → dispatch → develop → review → merge

The full state machine, with its three feedback loops: the spike loop (settle feasibility before implementation beads exist), the bounce loop(review → changes-requested → resume), and the replan door (a mid-execution blocker re-enters planning). Hexagons are gates — nothing passes one without the right seat resolving it.

PLANNING PLANE — HUMAN-INTERACTIVE · OUTPUTS BEADS + DECISION RECORDS, NEVER CODEINTEGRATION PLANE — DISPATCHER · DEVELOPER · REVIEWER · MERGERideateframe + triageresearchanalyst agentsarchitecturedecisions / ADRsdecomposespec · check · previewPLANbh plan fileKICKOFFbh plan approveroots surfacebd readya dispatcher picks it upopen GO / NO-GO?file spike moleculetag:spike + decision beadverdict landsdecision bead close reasonspikes dispatch like any moleculeGO → replanNO-GO → ADR, closenothing orphanedstart <epic>disp/ opens containerassign--to dev/<name>claimidentity + signingimplementwt/bead/issue/<id>show · refinesquash → digestscheckvalidate_cmdsubmitopens gatesREVIEWhuman · timer · ghSECURITYwarden/ onlyparallel gates — both must clearapprovemerge · merger seat--no-ff → container · merge-slotbounce · changes-requestedresumere-attach + read feedbacknext ready bead — parallel devs, serial mergefinish <epic>all children closed · validate assembled containerone --no-ff merge bubbleblocker / discovery → replan (the one re-entry door)main — always greenmerging ≠ releasing — release is a separate, gated act
gate (bd gate — seat-resolved)approval / verdictfeedback loopalways-green integration lineforward flow
The two-gate planning exit is deliberate: plan approval gates whether the decomposition is right; kickoff approval gates whether the work should start now. Inside a molecule, every bead forks off the epic's container branch (wt/bead/epic/<id>) so bead B sees bead A's merged work; the container lands on main only when the whole molecule is done — one recursive rule that scales to N tiers (issue → epic → workstream → main).

What keeps the line green

  • Serialized merges. Merge is a separate seat (the merger) gated bybd merge-slot — parallel developers, one merge at a time.
  • The conflict ladder. clean → rebased → union → bounce: try a clean --no-ff, then rebase-and-retry, then path-whitelisted union merge (append-only files only, re-validated), else bounce with the branch restored. No work is ever lost.
  • Validation modes. Every bead validates in isolation at submit;relaxed / conservative / loose tune how often thecombination is re-tested. If a re-validation fails on a safe-to-rewrite branch, the tip is rolled back before anyone can observe it; a shared branch escalates for a forward fix instead.
  • The batch exception. Cohesive linear chains can run as one sharedwt/batch/<group> worktree, merged once — guarded by cohesion, a size cap of 5, one model tier, one review gate. A batch fails and bounces as a unit; per-bead commits stay bisectable inside the bubble.
Where the ideas come from. The pipeline starts atideate, which quietly assumes someone showed up with an idea — capping the whole factory at one person's imagination on a given afternoon. Upstream of planning there's a loop that doesn't: read the repo's own vision and strategy documents, derive candidate topics from how those documents are actually structured rather than from a generic checklist, then generate against each topic in parallel — deliberately blind to the others, so the batch stays divergent instead of converging on the same three obvious ideas. Survivors are deduplicated, judged against the vision, and filed throughbh plan file like any other molecule, so nothing skips the kickoff gate.