Brain-driven development

The practice: one brain repo from which the whole ecosystem is developed. The brain is a knowledge base — claims, law, and the ritual — and the code repos are surfaces the change passes through. The practice was operated by hand for months on a real production ecosystem — five repos, a ~5,400-line brain — before multivac made it mechanism instead of discipline.

Entry from anywhere, one protocol

The brain is not a place — it is a protocol, because it travels:

• Enter the brain repo → the brain door says how to work on the whole ecosystem: where every repo lives, the law, the ritual (.multivac/ritual.md), landing order.
• Enter any code repo → the brain is mounted there, and that repo’s door says: consult the brain before any decision — and the feature you’re building may not end in this repo. An agent standing in one surface knows the change may cross into others, and the brain tells it which.

Both entry points converge on the same state: work planned against the brain, executed across whatever surfaces the feature touches.

Three layers

Only the map regenerates. For an existing ecosystem the tool therefore generates the map and interviews for the law — the interview is the product, not an accessory. The journal is the asset, not the cost: the one layer that cannot be regenerated, separated so it isn’t always loaded.

The brain’s content is in whatever language the team writes. Nothing in the parser assumes English headings.

The session is home

The consumer of the output is an agent about to write code, reading the run in the same turn it will edit in — the last moment where being told a claim is false still changes what gets written. Design consequences:

• The message is the product, not the exit code. Output says what is wrong and what to do. The exit code is what the invoking hook reads; the text is what the agent reads.
• Self-healing is the normal mode. The agent is already editing and reviews the diff on the spot; moved is not a special case.
• Hard latency budget: under one second. A hook that takes five seconds gets uninstalled. Hence git ls-files rather than walking the tree, and matching in process — one RegExp compiled from the anchor’s POSIX ERE, run over the enumerated files. No subprocess per leg, no external matcher, and nothing cached: at this size the read is cheaper than the bookkeeping a cache would need to stay honest across a rebase.

Enforcement: the ladder

If verification only runs when the agent remembers, the tool inherits the failure mode it came to fix. The tool is agent-agnostic — no privileged harness — so enforcement cannot live in any one harness’s hook API. The universal choke point is git: every agent, and the human, funnels through the commit.

One rung asks and two enforce; there is no third, on purpose. Both enforcing rungs fire inside the session, while the agent that broke the claim is still there to fix it — a check that runs after the session has ended reports the lie to whoever reads it next, with the code already written on top of it.

The two are not redundant; they catch different failure modes:

• Harness hooks are the read side. Session start catches a stale pin or a lying brain before the agent conceives code on top of it.
• Git hooks are the write side. Commit time catches claims the edit broke, before they land.

The harness is the ceiling; git is the floor. Where harness hooks exist, most drift is caught early and the git hook rarely fires. Where they don’t — “any coding agent” includes harnesses with no hook API at all — the git hook guarantees nothing false lands.

The hooks travel with the clone: multivac init points core.hooksPath at a versioned .multivac/hooks/ directory, so there is no install step to forget. The model is git-native throughout — anchors evaluate via git ls-files, distribution is pin + staleness, the change is branch/MR — so init runs git init where missing, and a gitless brain is degraded enforcement, flagged by multivac doctor.