05 · Humans + agents

One process, two kinds of worker

The org chart you already know — planes, seats, blast radius — except a seat no longer cares whether its worker is a person or an agent.

The factory doesn't split "human workflows" from "agent workflows" — it definesseats, and either kind of worker can sit in one. A seat is a set of functional inputs, outputs and permissions, so it can be filled by an agent sub-task, by a main harness loop (bh role <seat>), or by a human doing the same verbs by hand. What keeps the mix safe:

  • Humans hold the gates. Plan approval and kickoff approval are explicit human checkpoints; the default review gate is human; a reviewer bounce sends the bead back with written feedback rather than silently failing. bd humanexists to flag any decision for a person.
  • Every agent signs its work. In agent identity mode each worktree is stamped with a distinct author and a dedicated SSH signing key, so agent commits are attributable and verifiable. In supervised mode the worktree inherits the human's keys — "under my keys, with direct supervision."
  • Seat typing is enforced. An epic can only be started by a dispatcher (disp/), a leaf bead only claimed by a developer (dev/), asecurity:* gate only resolved by a warden. Humans (non-seat identities) are exempt — the machinery constrains agents, not people.
  • Escalation over silent failure. A merge that can't auto-resolve bounces the bead with its branch restored; a broken shared branch escalates loudly for a forward fix. Work is never dropped.
06 · Roles & seats

Four planes, one orchestration spine

Seats are separated by blast radius: the seat that routes work holds no secrets, the seat that holds secrets makes no decisions, the seat that observes writes nothing. A small single-hive factory collapses the four control seats into just the supervisor — deliberately, so the split is a designed merge, not an accident.

supervisor director dispatcher developer / reviewer / mergerthe 3-level orchestration spine (control → control → integration)
Control planegoverns the factory itself · human-supervised · the one plane that never touches bh work
supervisorsuper/

The root. Sets policy, launches and oversees the other control seats, owns cross-plane decisions. Absorbs the other three in a small factory.

authority: ultimate · no code, no merge, no keys
directordir/

The traffic layer. Fields the fleet-wide intake inbox (bh hq intake), routes work to hives, interfaces with per-hive dispatchers, writes fleet membership.

authority: high (routing) · no secrets, no policy
custodiancust/

The commissioning hands: discover → onboard → configure → verify → hand off (→ retire). The only control seat touching secret/key material.

authority: mechanical — applies, doesn't decide
controllerctrl/

The gauge. Reads throughput, health, and OTEL telemetry of the factory; writes reports and dashboards, never the registry.

authority: low · read-mostly
Planning planeidea → gated molecule · human-interactive · beads + decision records, never code
plannerplan

The cartographer. Drives ideate → research → architecture → decompose → file across three fidelity tiers (quick / spec / deep); files spike molecules when feasibility is open; owns replan and groom.

authority: decomposition · no implement, no dispatch
analystsub-agent

Fire-and-forget research: codebase discovery plus external docs/web research, returning structured findings to the planner on deep-tier work.

authority: none · read-only
Integration planemolecule → merged · thebh work loop · parallel devs, serial merge
dispatcherdisp/

Delivers an epic: opens the container branch, assigns beads, fans out developer sub-agents (model per bead) or collapses onto a shared batch branch, watches gates.

authority: scheduling · fanout mode never implements
developerdev/

Implements one bead to a reviewable state in its own worktree: claim → implement → show/refine → check → submit. Squashes its own noise into conventional digests.

authority: one bead · no merge, no lifecycle improv
reviewerseat

Walks the submitted change: reads intent + diff, runs tests and a feature demo locally, checks acceptance criteria, then approves or bounces with written feedback.

authority: gate verdict · read-only re: code
mergerseat

The merge owner. Serializes approved beads onto the green line via the merge slot,--no-ff, conflict ladder, escalates rather than drops work.

authority: landing · no dispatch, no implement
Assurance planethe exception — a cross-cutting gate layer, not a sequential stage
wardenwarden/

Security + policy verdict only: secret-scan, SBOM, policy-as-code. Holds thesecurity:* gate that runs parallel to review — and is the only seat that can resolve it. Read-and-block; never writes.

authority: block · provenance not in scope
verifierlens

Acceptance / e2e / QA — deliberately not a staffed seat yet. Covered by developer self-checks, the reviewer's demo, and CI until end-to-end testing needs its own identity.

status: a lens, promoted only when needed
07 · Harnesses

Which harness a seat runs under

A seat is defined by what it takes in, what it puts out, and what it is allowed to touch — not by the agent CLI executing it. So the harness is configuration. Any seat launches as a main loop with bh role <seat>, which resolves the harness from--harness, then BH_HARNESS, then the hive's setting, then the global one:

bh role dispatcher                      # the configured harness
bh role dispatcher --harness opencode   # override for one launch
bh hive onboard --claude                # furnish a hive for Claude Code
bh hive onboard --opencode              # …or for OpenCode

Two harnesses are furnished today. A third, Codex, reads the managedAGENTS.md steering hint natively but is not launched or furnished bybh.

Capabilityclaudeopencodecodex
Seat launchclaude --agent, plugin-scoped or local overrideopencode --agent, local override
Hive furnishing--claude: plugin mode, or copy mode into .claude/--opencode: opencode.json + translated seat defs--agents: the AGENTS.md hint only
Role skillsbundled in the plugin, or committed in-repoinstalled globally, zero repo footprint
MCP serverbundled, auto-registered by the pluginmcp.bh entry in opencode.json
Hooks / permissionssession steering hook + a deny ruleread-only allow-list + a steering plugin
Sub-agent fan-outyes — a dispatcher delegates each bead to its own developerClaude only today; pin harness: claude for molecules that fan out
Session telemetryfull seat + hive attributionfull seat + hive attribution
Statusline⬡ <hive> · <seat> in the TUI

Worktree provisioning is harness-independent:bh worktree add --preview --json and bh worktree status --json give any external orchestrator the same porcelain the seats use.

What's next

Planes the factory is growing into

These are named so the direction is visible, not described — a guide that documents unbuilt work reads as finished when it isn't. Detail lands with the code.

  • Release · cutting the version itself. The ordering half already ships; determination, changelog and tag are next
  • Contribution · gated contributions to repos we don't own
  • Build · pulling upstream progress into local build branches
  • Delivery · reconciling a cut release into running systems
  • Ideation · deriving candidate work from a repo's own vision documents