Subterranean LogoSubterranean.
Company Brain

Company Brain / Workspace files

/brain/CONVENTIONS.md

Brain Conventions

The contract every agent obeys. When it conflicts with your instinct, this file wins; when it is wrong, say so instead of working around it.

Page anatomy

Every page carries frontmatter:

title:          Refund policy
area:           finance
owner:          a person's name, never an agent's
status:         draft | canonical | superseded | archived
review_due:     2026-11-01
last_verified:  2026-08-06
sources:        [where this came from]
supersedes:     /brain/finance/refunds-v1.md

And a body with three headings, in this order:

  1. What is true — the claim, stated flatly.
  2. Why we chose this — the reasoning, the alternatives, who decided.
  3. What would change this — the conditions under which this page becomes wrong.

Heading 3 is the one nobody writes and the one that makes a page ageable. A page that says "this changes if we move off our current payment processor" can be checked in four seconds. A page without it can only be checked by re-litigating the whole decision, which is why review dates get rubber-stamped everywhere else.

Heading 2 matters because the thing nobody writes down is why. Procedures get documented; decisions get forgotten and then re-argued a year later by people who do not know they are re-arguing.

A page with no owner and no review date is a draft, however finished it looks. A canonical page with no owner is an error to flag, not a state to create.

Status lifecycle

draft → canonical → superseded → archived

  • draft — written, not yet vouched for by an owner.
  • canonical — the answer. Exactly one canonical page per question.
  • superseded — replaced. Carries a header naming its replacement.
  • archived — moved to /brain/archive/. Still readable, never cited as current.

Only a human promotes a page to canonical or retires one. Both are claims about reality.

The file always wins

The Pages table is a derived cache. When a row and a page disagree, the index is wrong and the fix is to reindex — never to edit a page so it matches a row.

Citation

  • Every claim carries the page path and its last_verified date.
  • A source past review_due can still be cited, but the age must be stated prominently. "This is what we wrote in March and nobody has checked since" is an honest answer.
  • When two canonical pages disagree, name both with their dates and owners. Do not resolve it. A contradiction surfaced is worth more than one silently picked.
  • Never answer from training knowledge. You know a great deal about the world and nothing about this company that is not written here. Blurring the two is how a brain becomes untrustworthy, and the reader has no way to tell.

Review cadence

Starter defaults, to be edited during setup:

  • Anything touching pricing or contracts — 3 months
  • Policy and process — 6 months
  • Architecture and technical decisions — 6 months
  • Reference material and how-tos — 12 months

A page past review is unverified, not wrong. Say the right one.

Capture

  • Search before writing. A fifth page on one topic is worse than no page.
  • Supersede, never overwrite. The old page goes to /brain/archive/ with a header naming its replacement and the reason.
  • Never invent an owner, a date, or a rationale to complete a page. Missing is honest; a plausible attribution is a lie the next reader will act on.
  • Capture the decision and the why, not just the conclusion. The conclusion is the part people can already guess.

Query discipline

Use the table tool with action get_rows and a where clause, or search_rows. Never use read_table on Pages or Questions once the brain has grown — it takes no filter and returns every row.

Use grep_search and glob_files to search page contents. That is what they are for, and it is faster than reading directories one file at a time.

State lives in /brain/

Cursors go in /brain/state/, reports in /brain/reports/. Never write workspace state under /agents/ — those writes route through the agent configuration seam and will stall an unattended run waiting for a confirmation nobody is there to give.

Never automatic

Deleting a page, promoting a page to canonical, retiring a page, changing schema, and resolving a contradiction all require a human in the loop.

/brain/CONVENTIONS.md - Company Brain | Subterranean