A knowledge-as-code operating model for supervised AI-assisted development.
Knowledge Cairn is a repo-resident operating model for working with an AI coding assistant over the long haul. It keeps project knowledge — requirements, rules, discovered facts, decisions, risks, open questions — in the repository next to the code, in a form both humans and AI tools can read, review, and version. Its engine is a task lifecycle that ends by promoting what the work taught into that knowledge — so context accumulates as a side effect of doing the work, and ceremony scales with blast radius: a quick fix is just a validated fix, while work that earns tracking gets the full cycle.
A cairn is a stack of stones that marks a path. This system is the same idea for a codebase: durable markers left in the repo so the next agent (human or AI) can find the way without re-deriving it from chat logs.
Three ways in, by temperament:
One paste — the assistant does everything. If your assistant can run shell commands, open it in your project's root and paste:
Clone https://github.com/escogido/knowledge-cairn next to this repository
(a sibling directory, not inside it), then read system/onboarding.md
from that clone and onboard Knowledge Cairn into this repository.
You drive; ask me what you need.
Clone first. Clone this repository next to your project yourself, open your assistant in your project's root, and paste:
Read <path-to-this-clone>/system/onboarding.md
and onboard Knowledge Cairn into this repository.
You drive; ask me what you need.
By hand — no agent writes anything. Everything the agent would do is a short checklist you can walk yourself: see ADOPTING.md, Manual fallback.
On either agent-driven path, the agent surveys your project read-only, asks one or two short batched rounds of questions (your project's identity, hard boundaries and sanctioned operations, validation commands — each with a drafted answer to confirm), routes any existing AI-instruction files to their Cairn homes on a mapping you approve, verifies the install by resolving your validation bindings, files what your existing docs already state into the knowledge base as one table you review, and lands everything as a single reviewable commit — nothing is committed without your approval. Read ADOPTING.md first if you want to know exactly what it will do and ask — including how to prepare your hard boundaries.
The same procedure repairs a drifted install and upgrades to a newer Cairn: point the prompt at a fresh clone and say so.
Cairn can be the first thing in the repository — install it before you decide anything, whether you mean to work the stack out with your assistant or already know exactly what you want.
Create the empty repo (git init, or a fresh GitHub repo cloned), open your assistant there, and paste:
Clone https://github.com/escogido/knowledge-cairn next to this repository
(a sibling directory, not inside it), then read system/onboarding.md
from that clone and create a new project here using Knowledge Cairn.
You drive; ask me what you need.
The files are installed, staged, and committed on your approval, and the project's first task opens — a conversation that begins with what are we building and captures the decisions, their reasons, and the alternatives you rejected as you make them. If you mean to think the stack and tooling through with an AI, have that conversation there — it is kept; a chat before the install is not. The task closes when you say the foundation is settled: rationale filed, skeleton up, validation bound — from there the repo is an ordinary Cairn project.
If you've spent real time coding with an AI assistant on a project meant to last, you already know the struggle — and it only grows as the project does:
- knowledge lives in the chat that discovered it, and dies with the tab;
- a later session opens by reconstructing intent;
- a decision from three weeks ago is now a vague memory;
- a rule you set once gets missed the next time;
- docs drift from the code until no one trusts them.
Cairn's answer is to move that knowledge into the repository, next to the code, and change it the way you change code: visible in a diff, reviewed before it lands, versioned, and kept current so nothing stale reads as true.
That is the whole promise, and it is not free. Cairn asks you to run a task lifecycle, to review knowledge changes the way you review code, and to keep the durable tier honest. In return, your project's context survives the session, the machine, and the model. The discipline is real, and the tool cannot supply it for you — it only makes that discipline cheaper to keep than to skip.
Cairn is built for a long-lived, evolving codebase and someone who means to stay responsible for it. It is not a spec-kit, an autonomous-agent framework, or a substitute for engineering judgment: the AI may write the code, but you stay responsible for direction, acceptance, and interpretation.
Cairn separates current operational state from durable project knowledge, across three tiers:
| Tier | Lives in | Answers |
|---|---|---|
| Operational | ai-context/operational/ |
What are we doing right now? |
| General | ai-context/general/ |
What does every task need to know? (broadly-loaded knowledge of any kind — rules, boundaries, terminology, invariants) |
| Situational | ai-context/situational/ |
What does this particular task need? (slice-specific knowledge of any kind — requirements, findings, mappings — loaded on demand) |
Finished task records settle into ai-context/archive/ and are consulted only to answer why something was done.
An agent loads Operational + the relevant General + the selected Situational for a task — not the whole repository of knowledge.
Work moves through four phases, with an optional review gate inside Execution:
Selection -> Definition -> Execution -> Finalization
(advise) (write the (do the work; (promote durable
task brief) optional knowledge, archive,
adversarial reset, commit)
review gate)
The shape has one purpose: making sure you got what you asked for. That takes a bounded definition of the ask — the task brief — and a way to prove the result holds that you defined yourself: the validation commands you bind once, so "done" is measured by your tests, not by the model's confidence. Everything else the lifecycle does — the review gate for what tests can't check, the knowledge promotion at the end — hangs off that spine. Selection draws on candidates — follow-ups the work itself captured along the way — so "what should we do next?" starts from real material instead of memory.
The phases are context-state transitions, not heavyweight project management.
Work generates ideas faster than it can absorb them: a refactor you noticed mid-fix, a stale doc, a question nobody answered.
In Cairn these become candidates — say "save this for later" in chat and the agent captures it into ai-context/operational/candidates.md, with enough context to make sense cold.
When you ask "what should we work on?", the agent reviews the list against the current state of the repository and recommends; do <slug> picks an entry up as a quick ad-hoc job, define <slug> turns it into a full task.
The list maintains itself: entries are pruned as work completes, vague captures are reconciled against evidence when they next matter, and deleting one is a decision that sticks.
The whole feature is optional — your real backlog can stay in your issue tracker, and nothing in the lifecycle requires ever picking up a candidate.
It is simply the cheapest memory in the system: ideas that would otherwise die with the chat get a handle instead.
Cairn ships agent skills — focused, mostly read-only roles the assistant invokes on trigger phrases:
| Skill | Invoke when you say… | Role |
|---|---|---|
task-selection-advisor |
advise on / recommend / review candidates | read-only Selection evidence review |
adversarial-reviewer |
adversarial review / review before Finalization | read-only pre-finalization review |
documentation-auditor |
audit documentation / check docs against code | out-of-cycle doc-integrity audit |
The canonical skill files install under .agents/skills/.
When a target project already has .claude/ — or Claude Code is the assistant doing the onboarding — onboarding also wires Cairn into Claude Code natively — the three skills through .claude/skills/ adapters, namespaced /cairn:* slash commands for the lifecycle gates and verbs (/cairn:candidates, /cairn:define, /cairn:finalize, and so on), and a read-only adversarial-review subagent — each a thin adapter that points back at the canonical methodology rather than creating a second source of truth.
Optional add-ons install separately from the core, on request, each through its own seam list (system/extensions/); none ship in this release.
The install machinery is itself part of the design, and it is not a script: your assistant is the installer. Onboarding, repair, extension installs, and upgrades are all the same semantic operation — read the actual state at every seam, reconcile by meaning, propose before writing, stop and ask on anything unclassifiable. Because the payload is prose you are free to edit, nothing ever assumes pristine files: an upgrade recovers what your copy looked like after the last install (from the provenance note it wrote, or from your repo's own history), tells your edits apart from the methodology's own movement, and shows you any genuine conflict rather than resolving it silently. There is no version database and no lockfile — any fresh clone serves, and the install is self-checking: every seam carries a detect signature, so a walk that finishes has verified itself.
README.md this file
LICENSE MIT-0 — copy, edit, and embed freely; no notice required
ADOPTING.md what onboarding does to your repo — read before pasting
CONTRIBUTING.md what to contribute — field reports first
DESIGN.md the target experience and why it is shaped this way
AGENTS.md instructions for agents opened in THIS repo (points to onboarding)
CLAUDE.md Claude Code entrypoint for THIS repo (imports AGENTS.md)
docs/ the rationale: why the system is shaped the way it is
validation-profiles/ worked validation bindings, one per stack
system/ the framework itself
onboarding.md the procedure your assistant follows to install / repair / upgrade
AGENTS.md the always-loaded router (template; seams filled at onboarding)
CLAUDE.md one-line Claude Code wiring file
ai-context/ the knowledge system
.agents/skills/ the core agent skills
adapters/ per-assistant wiring (Claude Code skills, commands, subagent)
extensions/ optional add-ons
system/ mirrors what your project root will look like after onboarding, so everything that installs reads as it will read installed.
Onboarding's procedure is also the upgrade path: point your assistant at a newer Cairn clone and ask for an upgrade by name.
Clone https://github.com/escogido/knowledge-cairn next to this repository
(a sibling directory, not inside it), then read system/onboarding.md
from that clone and upgrade Knowledge Cairn in this repository against that clone.
You drive; ask me what you need.
Or, with a clone you already have:
Read <path-to-clone>/system/onboarding.md
and upgrade Knowledge Cairn in this repository against that clone.
You drive; ask me what you need.
Your project's own content — identity, boundaries, your knowledge files, task history — is never touched; the methodology's files move to the new version, with any genuine conflict handled as the "No installer program" section above promises: shown to you, never resolved silently. Everything lands as one reviewable commit, so undo is one revert. The same procedure pointed at your current version is a repair: it fills what is missing and asks about what diverged. Prefer a full git clone over a ZIP — upgrades read the clone's history to recover what your repo recorded at install. ADOPTING.md has the full ownership and conflict story; doing it by hand means diffing your installed files against the new payload and reconciling yourself — git holds your history either way.
- Human-gated. Durable knowledge changes only with explicit human approval. New discoveries never silently overwrite accepted knowledge; conflicts are reconciled in the open.
- Code owns facts; docs own reasons. Current implementation detail belongs to the source tree, tests, and schemas. Documentation owns the durable reasons, decisions, boundaries, and evidence trails that code alone does not preserve.
- Always current. Live knowledge states present truth; superseded knowledge is deleted, not left to read as history. The past lives in git and the task archive, never in the live tier.
- Tool-agnostic core. Cairn assumes a git repository and an AI coding assistant. It does not assume your language, test runner, or database. Where a concrete command is needed, the methodology names the moment it runs at and the project binds the command.
DESIGN.md expands this stance — the development experience Cairn is built toward, and the principles behind its shape — without requiring the deep dives in docs/.
Knowledge Cairn is designed and maintained by Yaroslav Berezovskiy. It is young and deliberately shaped by field use: if you adopt it, a report of what worked and what fought you is the most valuable contribution you can make — several design decisions (docs/open-questions.md) are explicitly waiting on exactly that evidence.