BigBrain · what holds the repos together

One registry, and nothing faked.

The system is split across many repos that load each other's code. A small control plane outside all of them holds what is true about the machine rather than about any one repo: where each repo lives, which repo may reach into which, and the checks that fail loudly when either drifts.

The system is spread over many separate code folders that borrow from each other. One small shared folder keeps track of where each one lives and which may borrow from which, and runs checks that complain loudly when something is out of place.

Repos around the registry The registry sits in the middle, and every repo around it finds its siblings through it, never through a relative path. A few repos also reach into each other directly; each of those links is a declared edge, drawn dashed, and an undeclared one fails a check. The registry where each repo lives repo repo repo repo repo repo finds its siblings through the registry a declared edge into another repo
Every repo resolves its siblings through the registry. A direct reach into another repo is allowed only as a declared edge.Each folder looks the others up in one shared list. Borrowing straight from another folder is allowed only when it is written down.

The registry: one place a path is written

One file lists every repo: where its checkout lives, its project and its services. No repo writes another repo's path anywhere else.

One file lists every code folder and where it lives. No folder writes down where another one is.

Declared edges

Every place one repo reaches into another is listed as an edge, so the couplings can be re-checked continuously instead of remembered.

Every time one folder borrows from another, that link is written in a list, so it can be checked again and again.

A missing sibling is loud

Before the split, cross-repo requires sat in try/catch blocks that fell back to a stub. The smart-home adapter fell back to an in-memory mock, so the lights could stop working while the health check still reported green.

Code used to quietly swap in a fake when a piece it needed was missing. Once, the smart-home part did this, so the lights stopped working while every status check still said all was well.

The doctor stays at zero failures

bb doctor runs every machine-wide check in one pass and must report zero failures. A warning gets noted; a failure is fixed before other work.

One command runs every machine-wide check. It must always report zero failures, and a failure is fixed before anything else.

One full suite at a time

Agents work in parallel on one machine, and full test suites that ran side by side collided and timed out. bb suite puts every full run into one machine-wide slot, in arrival order.

Many AI helpers share one computer. When several ran the full set of tests at once, the runs got in each other's way, so now they line up and take turns.

Why full runs moved to one per wave of tickets is on Practice.

How the owner fits test runs into the work is on Practice.

The code standard

A fresh agent with one ticket and no memory must find a repo's domains, interfaces, features and errors from the tree alone. These practices say what that means. Each repo carries the same conformance test, copied verbatim from the control plane, so the rules are enforced by tests rather than by a lint, a hook or CI.

An AI helper starts every ticket knowing nothing about the code. These rules make each folder easy to find its way around, and every folder runs the same test that checks them.

  1. Structure reveals domainsls src names the domains, one folder each; its index is the public surface.Folder names say what the code is about.
  2. Interfaces are declaredTyped .ts sources run on Node's native type stripping, with no build step, and npm test typechecks.Code states what it expects, and the tests check it.
  3. Errors are a taxonomyOne errors module per repo, with coded classes carrying a code, domain and HTTP status. No bare throw new Error.Every error has a name and a code, so it can be looked up.
  4. Features are registriesRoutes, jobs, commands, events, env vars, errors and screens are exported data, rendered to a doc that a test fails on when stale.Each folder keeps one list of everything it does, and a test fails if the written copy falls behind.
  5. Knowledge is executableScripts, doctor checks and tests instead of written procedures. Counts and measurements come from tests, never prose.Steps are scripts and checks, not instructions to follow by hand.
  6. Context files are mapsThe agent file is a short page of pointers and invariants, the README is install and use, and rationale still in force is a short decision record.The notes for AI helpers point to where things are rather than explaining everything.
  7. Conventions are enforced by testsEvery rule a repo adopts is an assertion in its conformance test.A rule that matters is a test, not a reminder.
  8. Changes are localA feature touches one domain folder and its tests. A comment cites a ticket only for a rule still in force.A change stays in one area of the code.
  9. One entry point per actionstart, test, registry and, for servers, restart are each one npm script.Each everyday task has one command.
  10. Logs carry a domain taglog(domain, event, fields): one line per event, greppable by domain.Every log line says which area of the code wrote it.

bb doctor --conformance runs every adopted repo's conformance test and names the repos that have not adopted it yet.

One command runs the standard's test in every folder and lists any folder not yet using it.

Paths, hostnames, names and figures taken out.

Private details have been taken out.