All projects

How I work with knowledge bases

Decisions written down, anchored to the code they govern, checked in CI, and read by agents before they write. The method I run my own work on, and what I set up for teams.

Set this up in your teambrainpi-brain

Tools

brain, pi-brain, enola, enola-guides and tabula, all built by me

Scale

One knowledge base across all the repositories of a system

In the open

Four of the five tools, and this site's own wiki

For

Teams that build with coding agents

37 seconds, no sound. Every terminal and file line in it is real output, shown in full on the tools' pages.

Agents write fast. They don't know what you decided.

A coding agent sees the files in front of it, not the decisions behind them. It will have a background job call a controller, or let billing write another part’s tables, because nothing in the code says why not. Longer prompts and longer reviews only move the problem.

So I give the agent what a good engineer joining the team would get: the decisions, written down, next to the code they govern, and checks that catch the moment a change crosses one.

The practice, step by step.

1. Write it down, where agents read it.

   Sources go in unchanged; the wiki is the synthesis, and every claim cites its source. Decisions are records with a status and a confidence, and an agent may draft one but not approve it. That is brain, and pi-brain for the pi coding agent.

   

2. Anchor it to the code.

   A decision page names the files it governs, so any file can answer which decision applies to it, and numbers cite the receipt they were read from. The method is written down in enola-guides.

   examples/knowledge-base/wiki/shop/permanent/architecture.md

   ---
   title: Shop architecture
   enola_intent:
     governs:
       - app/jobs/**
       - app/models/**
     decisions:
       - jobs enqueue, models decide; a job never calls back into a job
   ---

3. Check every change.

   enola builds one graph of the system from the code and reports only what a change introduced, against laws the team wrote as sentences. It runs in CI, and before an agent says it is done.

   $ enola check --fail-on=constraints .

   FAIL — 2 structural regressions introduced.
   law: 1 rule · 2 breaches · none excused
   
   Regressions (fail):
     - [constraints] 1.00 — Constraint background-jobs-never-invoke-controller-code violated: OrderReportJob#perform -> OrdersController via calls
         app/jobs/order_report_job.rb:2

4. Hold the first edit.

   Before an agent’s first write into a repository, a hook shows it the decisions and laws that govern the file. It holds once and the retry goes through: it forces a reading, never a verdict. People decide.

   intent-first-gate.sh · an agent's first edit in app/billing

   intent-first gate (shop): first write for this piece of work.
   
   Target app/billing/charge.rb (path)
     Component billing (declared in enola/constraints/billing-is-documented.rb)
       rule billing-is-documented [ratchet]: every file of billing must be governed by a compiled page
         because: code under a decision needs the page that decided it
   
   A report, never a gate: these verdicts are for the caller to weigh before editing.

5. Keep people in charge.

   A structural change waits for an approved decision. The agent drafts, a person approves, and the record of what shipped follows. This site works that way; its wiki is public.

   $ git log --follow -- wiki/muhamed.github.io/adrs/project-profile-pages.md

   a831a16 projects: profile pages for enola, enola-guides and Usput.ba
   41eceaa wiki: project profile ADR draft takes the owner's answers on repositories
   d1293af wiki: revise project profile ADR draft (projects URLs, video, brain, enola-guides)
   01b5101 wiki: draft ADR for project profile pages

• Share it across a team.

  When several agents and people work in the same repositories, tabula is their shared memory: files and git as the truth, claims as leases so agents never collide, and a journal of who did what. It is in private development.

What I set up for a team.

A knowledge base your people and agents both work from, across your whole development lifecycle. Coding agents set up for your codebase, with guardrails they cannot bypass and architecture rules checked in CI. All of it with open-source tools I build, in your own repositories, and taught to your team so it keeps running after I leave.

The AI-native offer

• brainthe knowledge base an agent maintains
• pi-braindecisions agents must read, on pi
• enolaone graph of the code, laws in CI
• enola-guidesthe method written down
• tabulashared memory for teams; in private development
• The method in plain wordsa note in my brain