Architecture¶
How brainrc is built, for contributors and the curious. It has two moments. At install time,
brainrc apply turns sources (brainrc itself and the packs) into files each AI tool reads. At run
time, the tool loads those files, and Gatework drives a ticket through them.
flowchart LR
subgraph sources["Source repos"]
core["core: brainrc itself<br/>rules, overrides, VERSION"]
gatework["Gatework, the default pack<br/>(brainrc/gatework, fetched)"]
packs["packs<br/>(packs.local.toml)"]
local["*.local.* files<br/>(this machine only)"]
end
apply["brainrc apply<br/>render rules · render extensions<br/>link · merge settings"]
subgraph harnesses["Per-harness directories (harnesses.toml)"]
files["skills/ · agents/ · commands/<br/>instructions file · hooks · settings.json"]
end
subgraph run["Run time, in the AI tool"]
engine["/brainrc-work → Gatework engine<br/>reads extensions.md"]
roles["agents (brainrc-analyst … brainrc-verifier)<br/>domain skills · connector"]
end
core --> apply
gatework --> apply
packs --> apply
local --> apply
apply --> files
files --> engine
engine --> roles
Install time vs run time¶
| When | Step | Reads | Writes |
|---|---|---|---|
| install | brainrc validate |
every source, VERSION, CHANGELOG.md |
nothing |
| install | render rules | rules/*.md from core, then each pack, then *.local.md |
$BRAINRC_HOME/instructions.md (default ~/.config/brainrc/) |
| install | render extensions | each enabled pack's pack.toml, through Gatework's validator plugin |
$BRAINRC_HOME/extensions.md (only while Gatework is enabled) |
| install | link and merge | harnesses.toml, overrides/<harness>/ |
symlinks in each harness dir, hook entries in its settings file |
| run | every session | the instructions file, skill descriptions | nothing |
| run | /brainrc-work <ticket> |
extensions.md, the connector, agents, domain skills |
specs/<slug>/ in your project, commits on a feature branch |
| run | every tool call (Claude Code) | guard hooks | an allow, ask, or deny decision |
Skills, agents, commands, and hooks are symlinks, so git pull updates them at once. Rules and
extensions are rendered, so re-run apply after changing them or enabling a pack.
The code is the brainrc/ package (python3 scripts/brainrc.py or python3 -m brainrc), stdlib
only. The main modules: cli (the commands), config (config files and paths), sources and
packs (reading and fetching packs), plan and settings (links and merges), project, lock
and frozen (project scope and the lockfile), mcp and mcp_pins, validate, doctor,
audit, importers/, and plugin (the plugin manifests).
Glossary¶
- Harness: an AI coding tool brainrc syncs into: Claude Code, Codex, OpenCode, Antigravity CLI, Cursor (support).
- Core: brainrc's own repo. Generic content only, versioned by
VERSION(CHANGELOG). - Pack: a folder or repo layered on core for content that doesn't belong in it (packs).
- Default pack: a pack core's
packs.tomlturns on: Gatework, which holds its engine, its agents and the domain skills (packs). - Skill: instructions a tool loads on demand, triggered by its description (format).
- Domain skill: a skill for one stack (Terraform, Kubernetes, ...) that Gatework loads only when the ticket touches it (list).
- Agent: one role in a Gatework run, such as analyst or verifier (roles).
- Connector: the skill Gatework uses to read and update a ticket system (contract).
- Gate: a stop where you approve the spec, the plan, or delivery (Gatework).
requires_core: the core versions a pack supports (compatibility).
Repository layout¶
rules/ brainrc's own rules, as ordered markdown (00-core.md, 10-git.md, ...)
overrides/ per-tool guard hooks and settings fragments (Claude Code, Cursor, OpenCode)
mcp/ core's MCP server registry (empty: servers come from packs)
harnesses.toml where each tool reads each kind of content
packs.toml the default pack, Gatework, pinned to a release
brainrc/ the Python package behind the `brainrc` command (stdlib only, Python 3.11+)
scripts/ brainrc.py (runs the package from a clone), evals, release and CI checks
tests/ unittest suites for the package and the hooks
evals/ eval cases that grade Gatework runs (docs/evals.md)
docs/ this site (MkDocs), plus the JSON Schemas in docs/schemas/
examples/ example packs (pack-acme, pack-homelab) and a sandbox repo for trying Gatework
specs/ the records of Gatework runs that built brainrc
changelog.d/ one fragment per unreleased change, folded into CHANGELOG.md on release
VERSION the core version packs pin with `requires_core`
.claude-plugin/, .cursor-plugin/, plugin.json and package.json are generated by
python3 scripts/brainrc.py plugin; don't edit them by hand.