The Bureau
The Bureau coordinates software planning, implementation and review across
isolated agent contexts, with file-based handoffs and resumable run state.
Mechanisms you can inspect
- Cold reviewers receive a staged evidence packet without the full run log,
prior verdicts or conversation transcript. Packet checks reject symlinks and
transcript-like filenames.
- Artifact hashes bind the response to the reviewed files. Coverage checks compare
the reviewer's reported paths and hashes against the manifest in both directions,
exposing missing documents and claims to have read unstaged files.
- The Codex review adapter uses a read-only packet snapshot, disables network tools
and denies access to the live run, repository and session stores.
- Decisions, specifications, plans and reviews persist on disk so work can resume
after a session ends. Code-changing runs use separate Git branches and worktrees.
- Run accounting labels evidence as exact, estimated, inferred, partial or
unavailable. Missing provider data is not recorded as zero.
Current status and limits
This is Novadiem's internal engineering system, published for inspection and still
changing. It is not a supported self-serve product and has no open-source license.
Hash and coverage checks validate the reported evidence set, not whether a model
understood it or reached a sound verdict. Cold review also lacks unwritten context;
the review contract records the remaining
judgment gaps. Isolation depends on the host adapter.
Try this in 5 minutes
Run the packet self-test with Git, Bash, Python 3, jq and cmp installed.
It uses temporary files and stub responses, with no model calls or credentials.
git clone https://github.com/Novadiem-Studio/bureau.git
cd bureau
bash scripts/check-cold-reviewer-packet.sh
The fixtures cover a complete two-document review, a skipped specification,
missing coverage, an unstaged-file claim and a changed packet on resume.
They test validation behavior, not the quality of a live model's review.
Follow the evidence
The checkpoint review tour connects packet
construction, artifact hashing, response checks and acceptance rules.
Read the host constraints for adapter-specific boundaries
and the workflow registry for feature, bug-fix and plan execution.
Why it exists
Long software jobs need decisions and handoffs to survive beyond one model session.
A single session often interprets the brief, chooses an architecture, writes the code and reviews its own choices. Decisions can get buried in chat history. After an interruption, the next session has to reconstruct what happened and which decisions still apply.
The Bureau separates those responsibilities:
- Tasks are classified before an agent is chosen.
- Specialists work in fresh contexts with narrow responsibilities.
- Handoffs are written to files.
- Reviewers see controlled evidence instead of the discussion that produced it.
- Product choices and actions outside the task's authority go back to the human owner.
- Interrupted work resumes from state and artifacts on disk.
How a run moves
By default, a single run has two coordinators. The Delegate manages checkpoints and keeps one resumable Conductor. The Conductor assigns work to fresh specialists and assesses their findings. For a planned series of runs, the Envoy reads an INDEX.md, launches each run through its own Delegate and supervises one run at a time.
flowchart LR
A["Human brief"] --> B["Delegate<br/>flow and gates"]
B --> C["Conductor<br/>dispatch and adjudication"]
C --> D["Fresh specialist<br/>bounded context"]
D --> E["Artifact on disk"]
E --> F["Cold review"]
F -->|revise| C
F -->|proceed| G["Reviewed plan or<br/>dev-verified build"]
B -->|genuine product fork| H["Human decision"]
H --> B
The Conductor selects the smallest workflow that fits the task from the workflow registry and records the choice before work begins. Bug fixes and new product features follow different paths.
What the system protects
Independent review
Specialists start without the manager's conversation. Reviewers examine the written work in a fresh context, without the discussion that produced it.
For integrated checkpoint review, the Bureau prepares an evidence packet and starts a temporary reviewer. The packet excludes the full run log and transcript-like material. The response must identify the artifacts under review and match their hashes. See the host runtime contract and the integrated Delegate bridge.
Artifact memory
Each run has a directory containing its state, decisions, specifications, plans, reviews, prompts and build evidence. Another Conductor can resume from those files without the previous session's transcript.
Anatomy of a Run explains the record a run leaves behind. The run protocol defines how it is written and used.
Human judgment
The Bureau can continue when routine checks pass. It stops for product choices, new authority or external actions the task has not already authorized.
Build workflows stop at the development boundary unless a separate, explicit production action is approved. The standing rules are documented in the Conductor gates and the external-action boundary.
Isolated code changes
Code-changing runs receive their own branch and worktree. Concurrent runs can work against the same repository without sharing a checkout or writing directly to the integration branch. The git worktree contract defines setup, integration and cleanup.
For public GitHub repositories, the delivery unit is a linked issue and pull request: Bureau opens
a draft early, publishes test and cold-review evidence, marks it ready only after review passes,
and merges through GitHub. Private repositories may opt in; non-GitHub work keeps an explicit local
fallback. See GitHub delivery.
Run accounting
The close-out record distinguishes exact, estimated, inferred, partial, and unavailable evidence. Missing provider data is recorded as unavailable rather than counted as zero. See run accounting.
Regression checks
Lessons from repeated failures become conventions, script changes or committed regression fixtures. The standing suite checks artifact binding, verdict validation, run isolation, accounting integrity and gates that refuse to proceed when required evidence is missing or invalid.
.bureau/regression/README.md explains the suite and how run-local fixtures enter it. check-framework.sh checks consistency across framework files.
Workflows
The registered workflows cover different kinds of work:
| Workflow | Purpose | Typical result |
|---|
feature | Define a substantial feature or new product | Requirements, architecture, plan, and scoped prompts |
bug-fix | Reproduce, locate, fix, and verify a known defect | Code change, regression test, cold diff review, and dev verification |
build-review-cold | Build a contained change with risk-triggered cold review | Dev-verified change with review when silent failure is plausible |
execute-plan | Turn an approved plan into vetted prompts and build them | Isolated implementation with per-part review |
design-build | Implement an existing design handoff | Design manifest, build prompts, implementation, and fidelity review |
code-review | Review a branch, pull request, diff, or working tree | Findings-first cold review with no edits by default |
upstream-contribution | Contribute a real fix to an unrelated dependency or tool | Focused, tested, cold-reviewed upstream pull request |
|
workflows/index.md has the complete list. When no entry fits, the Conductor defines a workflow before proceeding.
The cast
Each named role has a written contract:
| Role | Responsibility |
|---|
| The Envoy | Cross-run supervisor when pointed at a plan; launches each run as a Delegate |
| The Delegate | Routine flow and checkpoint gating for a single run |
| The Conductor | Triage, dispatch, adjudication, state, and close-out |
| Analizer 2000 | Requirements, assumptions, edge cases, and acceptance criteria |
| The Architect | Architecture, dependency mapping, and phased plans |
| The Challenger | Cold review of specifications, prompts, code, and evidence |
| The Cleric | Design need, design handoff, and fidelity review |
| The Spellwright | Scoped build instructions from approved plans |
| The Mage | Frontend implementation |
| The Systemsmith | Backend implementation and contracts |
| The Mechanic |
Cast identities and voice live in LORE.md. Mechanics take precedence when lore and runtime behavior differ.
Run artifacts
Each task owns one RUN_DIR. For a targeted repository, new runs live under:
<target-repo>/.bureau/runs/<yyyymmdd>-<task-slug>/
The exact artifact set depends on the workflow. Common files include:
| Artifact | Purpose |
|---|
state.json | Short, machine-readable run state |
log.md | Append-only human record of spawns, decisions, findings, and handoffs |
model-routing.json | Runtime, model, and reasoning assignment by role |
spec.md | Requirements and architecture when the workflow calls for them |
plan.md | Phased delivery plan |
prompts.md or a prompt folder | Approved, scoped build instructions |
design/ | Design brief, handoff, and manifest when a visual surface is involved |
coupling/ | Evidence from cross-surface integration checks |
regression/ | Run-local regression fixtures before promotion |
accounting.json | Close-out record with evidence confidence |
Runtime support
Model routing chooses which model a role uses. The host transport creates and resumes its agent context.
| Runtime | Agent host | Status |
|---|
| Claude | Claude Code Agent tool | Supported |
| OpenAI | Codex collaboration tools | Supported |
| Codex | Alias for OpenAI at startup and reviewer boundaries | Supported |
| OpenRouter | Model routing only | No native run transport; fails closed |
| Hermes | Model routing only | No native run transport; fails closed |
Every specialist receives an explicit model assignment from the run's routing file. Current mappings and known accounting gaps are documented in docs/host-runtime.md, model routing and cast, and config/runtimes/README.md.
Repository map
| Path | What it contains |
|---|
agents/ | Specialist contracts, output formats, and boundaries |
workflows/ | Task-specific routing and execution paths |
docs/ | Runtime, run-state, gate, worktree, accounting, and convention contracts |
scripts/ | Deterministic helpers for startup, verification, review, accounting, and close-out |
config/ | Model policy, runtime adapters, schemas, and experiments |
templates/ | Run state, project context, accounting, and decision templates |
.bureau/regression/ | Committed regression fixtures for framework behavior |
reference/ | Visual references and design canon |
Operator documentation
Start with the entrypoint for your host, then load the contracts needed for the task:
These documents assume an operator working from the repository. Novadiem does not currently provide a beginner installer, hosted control plane or general installation support.
Status and availability
The Bureau changes as we use it. Interfaces, workflow contracts, model mappings and operator instructions may change without a stable release boundary.
License and use
No open-source license is currently attached to this repository. Public visibility should not be read as a supported self-serve distribution. Contact Novadiem Studio to discuss project use or commercial terms.
Further reading
- The Bureau, the public site, cast, records, and visual system
- Novadiem case study, the studio view of the system and the problem it addresses
- The Harness Is the Product, why the coordination layer matters
- Who Checks the Checker?, what happened when several reviewers agreed and the repo-aware reviewer did not
- Gate the Flow, Not the Judgment, how routine gates differ from product decisions
- The Pipeline That Wrote This, a Bureau workflow described by an article it produced
- The Gates, the standing decision boundaries
- Cast and Routing, the public map of roles and handoffs
Work with Novadiem
To discuss using the Bureau to define a product, improve an existing codebase or build an agent workflow, contact Novadiem.
