What Codee3 does to a repository

Seven steps. Six of them are automatic, and the one that is yours is the one no tool can do for you. Nothing here asks you to change how you write code.

Adoption

One repository, seven steps

your-repositoryThis part is yours

src/
docs/
README.md
package.json

Yours
Your repository, before anything
A working codebase with documentation somewhere in it. No prerequisites, no framework requirement, no minimum size.
Automatic
One command
Installation is additive. It writes new files beside your tree and never overwrites an existing one.
Automatic
The structure appears
Five spine documents covering the recurring roles, a navigation hub as the entry point, and an empty domain tree waiting for your subjects.
Automatic
Your agents are pointed at it
A small redirect block is written into each detected tool’s own instruction file. Your existing content in those files is left exactly as it was, and the block is delimited so you can delete it.
Yours
You write down what is true
This is the part that is yours, and it is the part that matters. Codee3 does not read your source code and does not generate your knowledge — a governed layer full of confident, unverified generated prose would be worse than no layer at all. Start with one domain and one decision.
Yours
The guards go into CI
Three lines in a workflow file. The checks are zero-dependency Node scripts — no account, no token, no network call, nothing transmitted.
Yours
From then on, it is just the repository
Knowledge changes in a pull request, beside the code it describes, reviewed by the same people. The guards fail the build if the structure breaks. There is nothing to log into and nothing running when you are not.

01Installation

The command, in full

Codee3 is a scaffolder. It writes 69 files into the target repository and wires 12 npm scripts into package.json. It is non-destructive: it never overwrites a file that already exists.

npm install
npm run brain:init -- /absolute/path/to/your/repo

What lands is plain Markdown and zero-dependency Node scripts. They live in your repository and are version-controlled alongside your code, which means they are reviewable in a pull request like anything else.

your-repository+19 added · 0 changed

src/
components/
index.ts
docs/
architecture.md
README.md
package.json
.ai/
00_NAVIGATION.mdDERIVED— entry point
PROJECT-BRAIN.mdCANONICAL— operating laws
DECISIONS-LEDGER.mdCANONICAL— what binds
CURRENT-REALITY.mdWITNESS— what is built
CHANGELOG-DELTA.mdWITNESS— history
EXECUTION-QUEUE.mdCANONICAL— sequenced work
domains/
00_INDEX.mdDERIVED
AGENTS.md— routes your agents to .ai/
tools/brain/— the guards

The additions sit alongside the existing tree. Installation is additive and never overwrites an existing file.

Scaffolded scalable-brain filing system into /path/to/your/repo  (brain kit v0.2.2)  created (69):    + .ai/00_NAVIGATION.md    + .ai/CHANGELOG-DELTA.md    + .ai/CURRENT-REALITY.md    + .ai/DECISIONS-LEDGER.md    + .ai/EXECUTION-QUEUE.md    + .ai/PROJECT-BRAIN.md    + .ai/domains/00_INDEX.md    + .ai/domains/example/00_INDEX.md    + .ai/domains/example/01_OVERVIEW.md    + .cursor/rules/brain-routing.mdc    + AGENTS.md    + tools/brain/...            (57 files: guards, engines, CLIs)  wired into package.json: brain:status, brain:check:no-versioning, brain:check:structure,    brain:check:skills-router, brain:check:references, brain:check:record, brain:check, brain:refs:radius,    brain:adopt, brain:skills, brain:version, brain:check:updates, brain:upgrade   agent tools detected: Cursor    → connect the brain to them so it works no matter which one you run:      `npm run brain:adopt`            (preview — shows exactly what it would add)      `npm run brain:adopt -- --apply` (wire them; only adds a removable redirect block)

02Structure

Five spine documents and a tree of domains

The governed .ai/ directory sits alongside your existing code rather than reorganising your source tree. Inside it are a navigation hub, a tree of domains, and five spine documents that between them hold decisions, reality and sequence.

PROJECT-BRAIN.mdCANONICAL: the operating laws
CURRENT-REALITY.mdWITNESS: what is actually built, with evidence
DECISIONS-LEDGER.mdCANONICAL: locked decisions with stable IDs
EXECUTION-QUEUE.mdCANONICAL: sequenced work with explicit readiness
CHANGELOG-DELTA.mdWITNESS: append-only history

03Declaration

Authority classes and verified dates

Every document in the governed directory carries a plain-text header declaring its epistemic status. Two fields do the work: what kind of document this is, and when somebody last confirmed it.

# Payment Processing Strategy

Authority-Class:: CANONICAL
Verified-At:: 2023-10-15

Verified-At records when a document was last confirmed. That makes staleness visible and inspectable to a reader or an agent. It does not prove the document’s content is still correct — a date is evidence of attention, not of accuracy.

The four authority classes

CANONICAL: locked local law; constrains everything below it
WITNESS: what is actually true now, with evidence
DERIVED: indexes and routing; link upward, never redefine canon
ABSTRACTED: domain overviews and leaves

04Navigation

Index-first reading

Agents are routed through indexes: read a folder’s 00_INDEX.md, find the relevant domain, then open the one leaf document the task needs.

Bulk-reading a whole domain is discouraged at every step of that route. The point is that per-turn context cost stays roughly flat as the repository grows, rather than rising with it.

.ai/

00_NAVIGATION.md

PROJECT-BRAIN.md

DECISIONS-LEDGER.md

domains/

00_INDEX.md

auth/

00_INDEX.md

01_OAUTH.md

billing/

00_INDEX.md

01_STRIPE.md

02_INVOICING.md

03_TAX.md

core/

Index-first navigation: reads four documents, not four hundred

05Surfaces

Pointing the tools you already use at one source

brain:adopt detects which AI coding tools the repository uses and writes a small, removable redirect block into each tool’s own instruction file. It previews every change first, is idempotent, and never overwrites the rest of the file.

Tool: Codex
File: AGENTS.md
Purpose: The root instruction file read by Codex and, increasingly, by other tools that adopted the same convention.
Points at: .ai/00_NAVIGATION.md

The block written into AGENTS.md

<!-- codee3:begin — removable. Delete this block to detach this tool. -->
Read `.ai/00_NAVIGATION.md` before anything else. It is the entry point to this
repository's governed knowledge.

- Route through indexes. Read a folder's `00_INDEX.md`, then open the one leaf
  you need. Do not bulk-read `.ai/`.
- Every governed document declares `Authority-Class` and `Verified-At`.
- On conflict, CANONICAL wins. DERIVED documents link upward and never redefine
  canon.
<!-- codee3:end -->