Skip to content
Codee3

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
  1. Yours

    Your repository, before anything

    A working codebase with documentation somewhere in it. No prerequisites, no framework requirement, no minimum size.

  2. Automatic

    One command

    Installation is additive. It writes new files beside your tree and never overwrites an existing one.

  3. 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.

  4. 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.

  5. 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.

  6. Yours

    The guards go into CI

    An ordinary workflow file — checkout, Node, install. The only Codee3-specific line is the last one. The checks are zero-dependency Node scripts: no account, no token, no network call, nothing transmitted.

  7. 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 57 files into the target repository and wires 14 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.

Non-destructive means more than an existence check. Every write refuses a symlink, a junction, or a hard link at the destination — and checks that the resolved path stays inside your repository before it creates so much as a directory. A link planted to redirect a write outside the repo is refused, not followed.

your-repository+19 added · 0 changed
  • src/
  • components/
  • index.ts
  • docs/
  • architecture.md
  • README.md
  • package.json
  • .ai/
  • 00_NAVIGATION.md
  • PROJECT-BRAIN.md
  • DECISIONS-LEDGER.md
  • CURRENT-REALITY.md
  • CHANGELOG-DELTA.md
  • EXECUTION-QUEUE.md
  • domains/
  • 00_INDEX.md
  • AGENTS.md
  • tools/brain/

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.3.0)  created (57):    + .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    + AGENTS.md    + tools/brain/...            (47 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:correct, 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.

Tree diagram highlighting the agent's path: 00_NAVIGATION.md → domains/00_INDEX.md → domains/billing/00_INDEX.md → 02_INVOICING.md. Everything off the path is dimmed.
.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

<!-- brain:adapter:start -->
<!-- Managed by the brain kit. Safe to delete this block — it only redirects this agent to the repo brain; it changes nothing else. -->
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.
<!-- brain:adapter:end -->

Illustrative shape of the block. The exact wording is written by `brain:adopt`, which previews every change before applying it and never overwrites the rest of the file.

"Never overwrites the rest of the file" is a recorded guarantee, not a promise taken on faith. Every block written is fingerprinted, and the fingerprint is what a later run checks against — never the content by eye. That gives every surface exactly one of four states: unchanged since the kit wrote it; behind and safe to refresh; edited by a person, in which case it is never touched again; or unrecorded, in which case it is left alone rather than guessed at. Custody is proven, not assumed.

This points every tool at the governed .ai/ directory instead of forking into per-tool copies. It does not make different agents reason identically — it gives them shared governed grounding to reason from.

06Guards

Five checks, wired into CI

Five zero-dependency guards run under npm run brain:check. Each one exits non-zero when its invariant is violated, which is what lets any CI system fail the build on it. They check the shape, naming, reference and decision-record integrity of the governed directory — not the factual accuracy of its prose.

  • brain:check:no-versioning

    fails on versioned names in the brain (v2, api-v2, FooV2, mk2)

  • brain:check:structure

    every folder holding documents must have an index; no two siblings share NN_ prefix; warns if index has no Authority-Class

  • brain:check:skills-router

    validates the skill-routing contract

  • brain:check:references

    registry declares each canonical fact, its path, rename history. Surviving mentions of retired names fail the build (reference-drift guard)

  • brain:check:record

    guards the decision record itself: fails if DECISIONS-LEDGER.md is missing, unreadable, truncated or carries two records under one id, or if an agent surface presents a decision the ledger does not contain or shows superseded text as current

Checks · pull request1 failing check
  • codee3 / brain:check:no-versioningFailed— 3 versioned reference(s) in .ai
    Violations reported by brain:check:no-versioning: path, matched pattern, and offending name
    PathRuleName
    .ai/domains/payments/00_INDEX.md:1[v<n>]v2
    .ai/domains/payments/00_INDEX.md:5[<name>-v<n>]i-v2

    The brain owns change — rename to a timeless name; record the evolution in CHANGELOG-DELTA.md. A genuine external pin (someone else’s `api-v2`) is exempted per line or per file, so the law never forces you to lie about a third party’s version number.

  • codee3 / brain:check:structurePassed— every document folder is indexed
  • codee3 / brain:check:skills-routerPassed— routing contract valid
  • codee3 / brain:check:referencesPassed— no retired names still referenced
  • codee3 / brain:check:recordPassed— decision record intact

brain:check FAILED — 1 blocking, 1 to look at, across 5 guards + install integrity.

Node diagram showing a canonical fact with edges to five referencing documents. Three are highlighted as "must be updated".
The blast radius fan-out finds referencing documents, and CI fails if one is missed during a rename.
07The loop

Correct it once.

The expensive part of working with an agent is not that it gets something wrong. It is that you fix it, the session ends, and the next session starts from the same missing information. A correction that survives the session is the difference between explaining something once and explaining it every week.

  1. the agent

    The agent proposes something locally reasonable

    It finds two payment flows that look duplicated and offers to consolidate them. Nothing in the repository says they are deliberately separate, so from the code alone the suggestion is correct.

    proposed: merge createCharge / createVendorCharge

  2. you

    You correct it, the way you already would

    They are separate because they carry different contractual authorities. You would have said this anyway — the only change is that you say it to a command instead of into a chat window that closes.

    npm run brain:correct

  3. the record

    It lands in the record with standing

    Written to the decisions ledger with a stable id, the reason, who has standing to have decided it, and the date. Not a note in a file — a governed entry the guards then protect.

    D-014 · CANONICAL · .ai/DECISIONS-LEDGER.md

  4. the agent

    The next agent starts from it

    A different session, a different tool, possibly a different model. It routes through the governed source before proposing, finds the constraint already settled, and preserves the boundary instead of rediscovering it.

    read: D-014 — in force

  5. Step four is step one again — the same situation, arriving at a different answer because the record carried forward. That is the whole product; everything else exists to keep this loop from breaking.

Two things it will not record

Not by policy — by grammar. The command has no way to express either one.

An inference recorded as a decision
Only what a person actually stated is admissible. Inferred, observed and derived sources are named and refused outright — so nothing an agent merely concluded can enter the record as something the organisation decided.
An evaluation of a person
The subject of a correction can be a constraint or a decision. It cannot be a person. The tool records who had standing to decide something; it has no representation for how anybody performed.

Documentation disciplines usually fail on incentives rather than on intent: the cost is immediate and personal, the benefit is delayed and collective, and under pressure the writing loses. Correction inverts that. You are not documenting for a stranger — you are stopping something that just wasted your afternoon from wasting it again.

What this does not do: it does not notice the agent was wrong, and it does not decide what your correction means. You do both. It also cannot compel the next agent to obey what it reads — different models reason differently, and will continue to. What changes is that the constraint is present, dated and attributed at the moment of work, instead of living in a chat log nobody can search.

08Reporting

A summary regenerated from your own files

brain:status emits a read-only summary of the governed directory. It is faithful — it equals its sources — and deterministic: the same files produce byte-identical output, with no clock and no randomness involved.

It stores nothing and owns nothing. A --json flag emits the same content for machines, under the codee3.repository-intelligence schema.

  Codee3 · Your Repository Brain  A living project brain your AI agents can use — rebuilt from your repository, owns nothing.  ──────────────────────────────────────────────────────────────────────────   ● HEALTHY — 5 checks ran and none failed.  9 documents tracked · 9 of them carry brain headers   Brain health    ✓ Every document says what authority it carries        9 checked, all clear    ✓ Every document records when it was last verified     9 checked, all clear    ✓ No document is left flagged as unresolved            9 checked, all clear    ✓ No two brain documents claim the same short name     9 checked, all clear    ✓ Your record of decisions is readable and consistent  1 checked, all clear    ✓ What your agents read still matches your record      4 surfaces checked, all clear    ✓ Every wired Codee3 command can actually run          9 checked, all clear    ○ No upgrade was left unfinished                       nothing to check yet — no upgrade is in progress or unresolved   What this organisation is held to      3 active binding commitment(s) of 100   (97 more can be recorded)   Your Codee3 tooling — wiring, checked but not run    Licensed to you perpetually for internal use: an installed version goes on running.    A ✓ below means: the command exists, the file it runs is here, and everything that file    loads is here too. Nothing was executed, so it is not proof the command works.    ✓ wired       Repository Intelligence    your repository explains itself in one glance    ✓ wired       Brain health guards        your five guards — decisions record, structure, references, no-versioning & skills routing — reporting the worst thing any of them finds    ✓ wired       Agent adoption             connect the brain to every AI tool you use    ✓ wired       Skills router              route work to the right on-demand skill    ✓ wired       Record a correction        what you tell it once, it keeps — as governed judgement, not chat    ✓ wired       Reference blast-radius     see what a change touches before you make it    ✓ wired       Brain version              the kit release this brain is running    ✓ wired       Update check               know when a newer kit release is available    ✓ wired       Upgrade the brain          adopt a newer kit release non-destructively   What needs attention    ✓ Nothing. Your brain is healthy — every check is green.   This is a read-only summary, generated fresh from your own files — not a second copy to maintain.  Prefer machine-readable output? Run `npm run brain:status -- --json`.
09Capabilities

Everything in the box

The complete list, with the status of each claim stated beside it rather than assumed.

Non-destructive scaffolding (brain:init)

Writes 57 files into your repository and wires 14 npm scripts into package.json. Never overwrites existing files.

Agent surface adoption (brain:adopt)

Detects ten supported AI coding tools and writes a removable redirect block into their instruction files, pointing them all at the .ai/ brain.

Structural guards (brain:check)

Five zero-dependency CI-ready checks that fail your build on versioned names, missing indexes, broken references, invalid routing, and a decision record that is missing, corrupt, or contradicted by what an agent surface shows.

Correction capture (brain:correct)

Records a correction you make as a governed decision with a stable id, so the next agent receives it instead of repeating the mistake. It only accepts what a person actually stated — it cannot record an inference as a decision, and it cannot record an evaluation of a person.

Reference blast-radius (brain:refs:radius)

Given a canonical fact, returns every document that references it, so you can fix renames everywhere in one pass.

Repository Intelligence (brain:status)

A read-only, faithful, and deterministic summary of the brain's health. Regenerated from your files, owns nothing. Supports --json output.

Skills routing (brain:skills)

Measures the per-repository context cost of your skills, loading them only when an agent actually triggers them.

Version and updates

Cached update check for release information at most once per 24 hours. Sends no repository content or telemetry. Non-destructive upgrade command.

Advanced governance layer

Planned — not built

Executable authority chains, supersession rules and identity integrity — the discipline this product is built under. It is deliberately NOT in the box: pointed at a newly scaffolded brain, those checks fail against the files the scaffolder just wrote, so advertising them would be advertising a capability that cannot work on day one.

10Boundary

What you author yourself

Codee3 installs the structure, the routing and the structural guards. It does not author your knowledge for you.

After installation you have a structurally healthy but empty corpus, marked throughout with (replace me) placeholders. You — with your agents — fill it in.

What the product gives knowledge is a governed place to live, and a mechanical way to stop that place from structurally deteriorating. The knowledge itself is your organisation’s; the discipline and the structural enforcement are the product.

What Codee3 does not do

  • It does not author your knowledge.
  • It does not read or interpret your source code.
  • It does not detect semantic drift, and nothing compares documentation against implementation.
  • There is no hosted service, no federation and no cloud component.
11Posture

Privacy, network, and what happens if we disappear

Stated plainly, because a governance tool that is vague about its own behaviour has already lost the argument.

The product

Codee3 operates offline. It requires no network connection to work. There is no account, no activation, no licence server and no telemetry. The one network request is an optional cached update check for release information, at most once per 24 hours, sending no repository content and no Codee3 telemetry payload, and failing quietly when there is no connection.

This website

This website stores only what you deliberately submit. It does not use analytics tracking scripts.

If Codee3 stopped existing tomorrow

Nothing would stop working. What is in your repository is Markdown and zero-dependency Node scripts, already checked into your version control. There is no licence server to go dark, no account to be deactivated, no hosted service to shut down and no format only we can read. The guards keep running because they are just files in your repository that exit non-zero.

Deleting Codee3 is rm -rf tools/brain and removing the npm scripts. Your .ai/ directory — the part with your organisation's actual knowledge in it — stays exactly where it is, in plain Markdown, whether or not any of this is still installed.

The guards in detail →The model underneath →