field guidemain · attested greentoolchain pins ↗shippeddirectionproposed
04 Roles & seats

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. Any decision can be parked behind a type:human gate for a person, and a seat approving its own submission is refused by default.
  • 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; refusing unsigned commits at merge is a per-hive opt-in. 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.
The seats

The 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.

Seat identities below are the prefixes bh stamps on every action (disp/, dev/, …). The full matrix — who may resolve which gate, which tools each seat is denied — is a target-state design reconciling: the prefixes and gate rules ship; some renames and least-privilege tool lists are still being reconciled across docs and agent definitions.

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
analystanalyst/

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
Development planethe CLI calls it Integration · molecule → merged · the bh 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. The older epic-coordinator and foreman names fold into its modes.

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. (crew/ is the retired name; still recognised, with a warning.)

authority: one bead · no merge, no lifecycle improv
reviewerrev/

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
mergermerge/

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
Release planeverbs ship · the seat is roadmapseat: roadmap
releaserrelease/

Owns the guarded bump — preflight, bump, attest, await, atomic push — and is the only seat that can clear arelease-hold: gate on a breaking change. The verbs run today; the seat is not yet a staffed stage, so a human runs them.

authority: cut the version · no merge, no dispatch
Sessions

Seats are not sessions

A seat is an identity plus a permission archetype; a session is a running loop. One long-context session under a human's supervision can hold several seats over the course of a bead, and that is the normal small-factory shape — because permissions are stamped peraction, not per window, the seats compose sequentially and never as a union.

A · SUPERVISED — ONE LONG-CONTEXT SESSION, MANY SEATS, ONE SEAT PER ACTIONone session · a human is watching · identity: supervised (your keys, your git config)bh work start <epic>--as disp/briin force: dispatcher onlybh work claim <bead>--as dev/briin force: developer onlybh work submit <bead>--as dev/briin force: developer onlybh work approve <bead>--as rev/alexin force: reviewer onlybh work merge <bead>--as merge/briin force: merger onlypermissions never accumulate: the union of seats is never in force, even though one context window carried all of themapprove is stamped by a different person — dev/bri and rev/bri are one person in two hats, and a type:human gate refuses self-approval (reviewer_cross_seat: hard)a collapsed dispatcher @ batch session is this shape: it implements, self-reviews under review_mode: self only where a human is watching, and merges, one seat per verbwhat a seat isidentity prefix + preloaded skill + tool ceilingdisp/dispatcherskills: dispatcher + worktools: Task · Bash · Read — no Editdev/developerskills: developer + worktools: Edit · Write · Bash — no Taskrev/reviewerskills: reviewer + worktools: read-only re: codemerge/mergerskills: merger + worktools: Bash · Read — no EditB · FANOUT — ONE SEAT PER SESSION, FOR ITS WHOLE LIFEdispatcher sessiondisp/nova · identity: agentskills: dispatcher + worktools: Task, Bash, Read — never Editroutes one bead per Task; watches gates;serializes merges. Fanout never implements.work.dispatch.mode: fanout (default)Taskdeveloper sessiondev/ada · wt/bead/issue/bh-ws.2.1own worktree · own signing key · exactly one seatTaskdeveloper sessiondev/bo · wt/bead/issue/bh-ws.2.2own worktree · own signing key · exactly one seatsubmitreviewer sessionrev/ · fresh contextreview_mode: fresh — a second Task,so it needs dispatch depth 2the rules· multi-seat session, single seat per action· author ≠ approver, compared by person· tools: is a hard ceiling under claude; advisory: don't stack too many seatsA seat never cares which kind of worker fills it: a person typing the verbs, a sub-agent Task, or a main loop launched with bh role <seat>.Every action is stamped either way — the audit trail reads the same whether one session or five produced it.
Seats compose sequentially, not additively. A supervised operator can drive a whole bead through dispatcher, developer, reviewer and merger seats in one long context window without separate permission sets, because --as <seat>/<name> re-stamps every verb and the gate machinery checks the stamp, not the window. The two limits that remain are deliberate: the self-approval block compares people, so a different human (or a fresh reviewer session) has to clear a type:human gate; and conflict-of-interest pairings are advised, not enforced, to split across sessions. The role skill a seat needs rides in on its agent definition's skills: frontmatter, with work for every seat that drives a bead lifecycle.
Hosts

Host roles are not seats

A seat answers "what may this session do right now?" and is stamped per action. Ahost role answers "may this machine own execution for a hive?" and governs a lease. They are different layers and the vocabulary is kept apart on purpose:

There are three host roles — executor, transient,viewer — and a hive has one primary host at a time. A session on an executor may hold several seats over a day; the executor still holds exactly one lease. The roles, the lease, the dispatcher loops and the proposed Frame enrollment are all on theFrames page.

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 · the guarded bump ships; the releaser as a staffed seat, and changelog authorship, are next
  • Contribution · gated contributions to repos we don't own (contributor seat)
  • Delivery · reconciling a cut release into running systems (operator seat)
  • Ideation · deriving candidate work from a repo's own vision and accumulated evidence — intake and adoption ship today, the plane's states do not
  • Observation and Feedback · named placeholders; owners, inputs and transitions are undecided