Guide

Bureau — how to use this plugin

Bureau turns AI sessions into a maintained, human-reviewed knowledge base for a repo. This skill is the map: the mental model, the one workflow, the invariants you must not break, and a decision table from intent → command. Read it before reaching for any bureau: command, then drop into the operational skill for the step you're on.

The mental model — a records office

Think of a government records office, and keep the metaphor straight because every command name comes from it:

• bureau — the engine (this plugin). It files, distils, and publishes knowledge.
• canon — the workspace: the durable knowledge for this repo (default dir canon/).
• logbook — an append-only drawer of minutes: one faithful, low-authority record per session. History, never rewritten.
• cabinets — topic drawers holding dossiers (the reviewed pages). This is the canon you read as memory.
• press — the bundled renderer. gazette — what the press produces: a navigable offline board you open in a browser.
• crew — specialized agents (each one a desk) that work the canon; e.g. an auditor desk.
• provenance — every dossier claim traces back to the [[session …]] minute it came from.
• recursion engine — a deterministic dependency gate. A dossier can declare that its claim rests on another dossier's claim (rests_on: + an author-anchored ^span); when that upstream claim changes, the engine flags the downstream dossier needs-review. Tracked in an append-only decision log (_log.jsonl, the source of truth); surfaced by bureau:status and the live board. It flags; a human judges. (See docs/recursion-engine.md.)

A claim's life: it is captured into a minute (low authority) → compiled into a dossier (machine-checked) → reviewed by a human (promoted to fact). Knowledge only earns authority by moving through that pipeline. Nothing skips it. Once filed, its freshness is kept honest by the engine: if an upstream claim it rests on changes, it drops out of current until re-reviewed.

The trust tiers — read every dossier's status:

Every dossier carries a status:. When you use one as memory, honor the tier and cite it:

Never present a non-canonical claim as settled. The tier travels with the claim — if you cite a dossier, cite its tier too. bureau:query enforces this for you, which is why you should query the canon rather than reading dossier files raw.

Freshness is a second, orthogonal axis. Trust is who vouches; freshness is does it still hold. A dossier can be canonical and needs-review/stale at once — approved by a human, but now sitting on a changed upstream claim (the recursion engine flags this). A needs-review or stale page is not current fact even if its trust is canonical — surface the freshness too, and route it back through bureau:review.

The invariants — do not break these

1. Never write canonical yourself. Only a human, via bureau:review, promotes a claim to fact. Setting canonical by hand forges the gate.
2. Never hand-edit a dossier. Durable claims enter only through capture → compile → review. Editing a cabinet page directly bypasses provenance and the human gate.
3. The logbook is append-only. Add minutes; never rewrite or delete a past one.
4. Never hand-edit the materialized crew under .claude/agents/ or .claude/skills/ — those carry a bureau-generated ownership marker and are regenerated. Edit the source in bureau/crew/<name>/ and re-sync.
5. Reach for the canon before re-deriving. If the repo may have already settled something, bureau:query first.

Which command for which intent

The right-hand skills hold the operational detail (steps, rules, edge cases) — this guide does not restate them; open the skill for the step you're actually doing.

When to reach for bureau (and when not)

• Use it in a repo that has a canon/ + BUREAU.md: query before deciding something the repo may have settled; capture before a session ends; compile/review to keep the canon current.
• Don't treat raw dossier files as fact, route durable knowledge around the gate, or render the gazette into the workspace (the one exception: the contained layout — a workspace named bureau — renders its board at <workspace>/<board>, which the press skips as content). Don't use bureau as a scratchpad — minutes are a faithful record, not a TODO list.

Chamber

bureau:serve opens the chamber — a single-user, localhost-only room that serves the gazette read-only, accepts intake (a proposed claim files as an append-only status: logbook minute), and hosts the review/dispose surface. The boundary is structural: propose is open (the human or a convened AI desk POSTs intake), dispose is the human's act — promoting a dossier to canonical requires a reviewer token printed to the bureau:serve terminal, which the AI's agent context never sees. So the chamber proposes (logbook) and a human disposes (canonical); it never lets the AI seat forge a higher tier.

Crew

A repo can run desks — read-only or task-specific agents over its canon. The shipped auditor desk reviews the canon for contradictions, stale claims, and unsupported canonical/verified pages, and only reports (findings still go through the gate). Manage desks with bureau:crew; their source lives in bureau/crew/<name>/ and is materialized into .claude/ on sync.

Examples

Scope note

This skill is orientation only — the plugin's mental model, invariants, and the intent→command map. It does not itself capture (capture/scribe), compile (compile), answer from the canon (recall), promote claims (review), lint, or render. Open the per-step skill for that work. Keep this guide in lockstep with the command surface: the static gate fails if a bureau: command exists that this guide doesn't name, or if it names one that no longer exists.