03 · How it works

The mental model in one breath

You've run pipelines like this with humans in every box. The difference to look for: every hand-off is a record, and nothing passes a gate on vibes.

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.

The ring

Six phases, one ring — and one edge nobody closes

A car factory isn't successful because the car left the line — it's successful if the car survives the road. Software is no different: what happens in production is the only signal that says whether the last decision was any good, so it has to come back round to the next one.

agentic planningdesign → tasksagentic developmentframeworksSRE & DevOpsagentsscopecodeverifymergedeploytriagefeedbackIdeaPlanBuildReviewIntegrateProduction
Clockwise from Idea. Vertices are phases; edges are the function that carries you to the next one. The outer arcs are the agent product categories now reaching market — three of them, three separate data stores, none able to see the whole ring. An agent working this line shouldn't need six places to look. And note where the arcs stop: feedback is the edge no category sells, which is why it's dashed, and the edge Beadhive is built to close.
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.
05 · Merge order

Merge order is planned, not first-come-first-served

Landing approved beads in whatever order they clear review is fine until a molecule mixeskinds of change — a hotfix for the released version, additive features that should ship as one clean minor bump, and a breaking change that must not leak into a patch. Review order produces a history nobody can version cleanly. So a bead can carry its semantic-version impact, and the merge sequence is computed from it:

  • release: — breaking, feature or fix. A fixed vocabulary, identical in every hive, so the ordering means the same thing everywhere.
  • wave: — a free-form label grouping additive features that should land together as one bump. Distinct from the worktree batching label.

The default strategy, stable-versioning, orders in four tiers: fixes for the released version flush first, up to a churn budget; then additive features, grouped by wave; then any fixes past that budget; then breaking changes last, so they never leak into a patch or minor window early. Both knobs are per-hive configuration (release.strategy, release.fix_churn_budget).

bh release order   # the strategy-preferred merge sequence, read-only

It is advisory. It decides sequence and nothing else — it never claims, merges or mutates anything, and the scheduler consults the same scorer so dispatch and merge never disagree about the order. The one hard counterpart is opt-in per hive: withrelease.enforce_hold on, a release:breaking bead gets arelease-hold: gate that blocks its merge until a releaser resolves it — and only a releaser can.

Merging is still not releasing. All of this orders the green line; it does not cut from it. Version determination, the changelog and the tag are the next piece of the release plane, and they aren't built yet.