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. Ceremony follows what the work needs, not what it weighs: work you don't need tracked is validated and committed, 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.
Ready to try it? Jump to Onboarding.
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 treat knowledge as code: move that knowledge into the repository, next to the code, and change it the way you change code: visible in a diff, reviewable, versioned, and scrubbed current wherever change reaches.
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, and both from the record of finished work:
| Tier | Lives in | Answers | Contains |
|---|---|---|---|
| Operational | ai-context/operational/ |
What are we doing right now? | the active task contract and execution state, saved follow-ups, pending promotion, and validation bindings |
| General | ai-context/general/ |
How does this project work? | 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 |
| Archive | ai-context/archive/ |
Why was this done? | finalized task records, consulted only on that question |
The split reflects loading: an agent takes the active Operational task files, the entire General tier, and the selected Situational files into a task, never the whole repository of knowledge.
- Operational holds the live task — the brief, the progress notes, and the durable knowledge waiting to be promoted — allowed to be incomplete and reset when the task closes. It also holds saved follow-ups and the project's validation bindings.
- General is read at the start of every session, so it is kept deliberately small under a size budget. It contains the capability and layout orientation an agent would otherwise re-derive, as well as the broadly needed constraints and reasons.
- Situational carries the detail only some work needs, pulled in when a task's shape calls for it; a Situational fact that turns out to matter everywhere is promoted into General.
- The Archive is never loaded by default: it is history, not doctrine.
All of it is markdown in your repository, and it is kept separate from Cairn itself.
ai-context/general/, situational/, operational/, and archive/ hold your project's own knowledge, while the framework lives in ai-context/methodology/ which updates when you upgrade.
You can change any of it; open a file and edit it like anything else in the tree. Or ask in chat, and the agent makes the edit in the tier it belongs in, for you to review as a diff. A new file carries a little structure: frontmatter, and a row in its tier's index so the router can see it; the agent handles all that.
What Cairn does not do is keep the knowledge accurate for you. The lifecycle captures what a task's own diff reaches, and the digest flags what the work superseded. But a rule you outgrew in a corner no task has touched will sit there sounding current until someone reads it, and that someone has to be you. The system is built to make that judgment cheap to exercise — every change arrives as a reviewable diff — not to make it unnecessary.
Work moves through four phases:
Selection -> Definition -> Execution -> Finalization
(you decide; (write the (do the work, (promote new
advice is task brief) capture new knowledge,
available) knowledge) archive, commit)
Filing what work teaches takes a unit of work to file against — a slice with a beginning and an end, not an afternoon of chat. That slice is a task, and it has to be both bounded and verifiable.
- Bounded means it has a brief: one that states the ask, roots it in the durable knowledge the project already holds, and anchors the task to a commit before any edit. That anchor is what gives the end of the task a defined delta to read, instead of a conversation to reconstruct.
- Verifiable means the task does not close until your tests confirm the work, so that what gets filed is settled work.
The agent drafts the brief from your input; you can review it and make changes before telling the agent to start Execution.
When the agent first deems the work done, it runs the tests via validation commands bound for the project to verify completion.
Once validation passes, the agent makes one cold pass to capture new knowledge as a digest, which you can review and revise before proceeding to Finalization.
In the same response, if a wide or hard-to-reverse risk is present, the agent recommends an independent adversarial Review and names the concrete reason.
Either way it presents cairn:review and finalize as alternatives: Review is always optional, finalize proceeds directly, and Review-driven changes make the standing digest stale for one later reconciliation.
At Finalization, Cairn promotes the durable knowledge digest into General and Situational, archives the task record, resets the task files, and commits the finished work.
Not every change needs a slice. Work you do not need tracked is ad-hoc — no brief, no digest — and it skips the ceremony, never the checks: validation scaled to what the change could break, anything durable it surfaces still filed, and the commit as its record. Size does not decide this: a brief is for work that will be built on, explained later, or put through review. When a request shows those signs the agent says so and recommends one, then does what you tell it. Knowledge work usually sits here — with no code delta for a digest to read, stating it and letting it land is the whole job.
The phases are context-state transitions, not heavyweight project management. DESIGN.md works through why the lifecycle has this shape, and what each phase is for.
Candidates are follow-ups the work surfaces and parks for later, in ai-context/operational/candidates.md.
Tell the agent to save something for later in chat and it will capture that with enough context to make sense cold.
When the agent is the one who spots the follow-up, it offers rather than files: an entry you did not author joins the list on your go.
When you ask "what should we work on?", the agent ranks them and recommends one — from what's already loaded, or freshly checked against the repo when you ask to verify.
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 — a task can start from anything you name, your real backlog can stay in your issue tracker, and nothing in the lifecycle requires ever picking up a candidate.
Cairn ships agent skills — focused, mostly read-only roles the assistant invokes on trigger phrases:
| Skill | Invoke when you say… | Role |
|---|---|---|
knowledge-digester |
draft the durable-knowledge digest before finalize | read-only, fresh-context pass over the task delta |
adversarial-reviewer |
adversarial review / review before Finalization | read-only pre-finalization review |
task-selection-advisor |
advise on / recommend / review candidates | read-only Selection evidence review |
documentation-auditor |
audit documentation / check docs against code | out-of-cycle doc-integrity audit |
The canonical skill files install under .agents/skills/.
With Claude Code, onboarding also wires the same four as /cairn:* slash commands and read-only subagents — thin adapters pointing back at the canonical methodology, never a second source of truth (ADOPTING.md has the detail).
Optional add-ons install separately from the core, on request, each through its own seam list (extensions/); none ship in this release.
- Human-gated. Durable knowledge changes only with human approval: new discoveries never silently overwrite accepted knowledge, and a conflict with an existing invariant stops for you rather than being reconciled behind your back.
- 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, and superseded knowledge is deleted rather than 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, not 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 is where each of these is argued rather than asserted — the development experience Cairn is built toward, what each stance buys, and where its guarantee stops — without requiring the deep dives in docs/.
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, then follow its onboarding.md to onboard Knowledge Cairn here.
Clone first. Clone this repository next to your project yourself, open your assistant in your project's root, and paste:
Follow <path-to-cairn-clone>/onboarding.md to onboard Knowledge Cairn here.
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, then 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. It routes any existing AI-instruction files to their Cairn homes on a mapping you approve, and files the highest-value knowledge your existing docs state into the knowledge base as one table you review. Everything lands as a single reviewable commit, and 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, then follow its onboarding.md to create a new project here using Knowledge Cairn.
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. ADOPTING.md, Starting Greenfield, covers what that task settles and where it deliberately stops; from there the repo is an ordinary Cairn project.
README.md this file
DESIGN.md the rationale — problem, requirements, why this shape
ADOPTING.md what onboarding does to your repo — read before pasting
CONTRIBUTING.md how to contribute — field reports first
CHANGELOG.md release history and upgrade notes
.github/ issue templates — the Field report form CONTRIBUTING points to
LICENSE MIT-0 — copy, edit, and embed freely; no notice required
knowledge-cairn.png the banner at the top of this file
docs/ deep dives behind the design decisions
audit/ self-audit protocol and prompts
articles/ long-form writing on knowledge-as-code
system/ what will be copied into your repo during onboarding
AGENTS.md the always-loaded router — names the knowledge, holds none
CLAUDE.md one-line Claude Code wiring file
ai-context/ the knowledge system
methodology/ the framework — lifecycle, tier model, procedures, templates
operational/ the live working state — brief, progress, digest, candidates
general/ always-loaded knowledge — rules, boundaries, terminology
situational/ slice knowledge, loaded on demand
archive/ finalized task records — consulted only to answer why
knowledge-cairn.md what Cairn is, and the installed-version provenance note
.agents/skills/ the core agent skills
adapters/ per-assistant wiring — Claude Code commands and subagents
extensions/ optional add-ons
validation-profiles/ example validation bindings, one per stack
onboarding.md the procedure your assistant follows — install, repair, upgrade
AGENTS.md instructions for agents in THIS repo — points to onboarding
CLAUDE.md Claude Code entrypoint for THIS repo — imports AGENTS.md
system/ mirrors what your project root will look like after onboarding, so everything that installs reads as it will read installed.
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 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.
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 onboarding.md
from that clone and upgrade Knowledge Cairn in this repository against that clone.
Or, with a clone you already have:
Read <path-to-cairn-clone>/onboarding.md
and upgrade Knowledge Cairn in this repository against that clone.
Your project's own content is never touched, the methodology's files move to the new version, and everything lands as one reviewable commit. Use a full git clone rather than a ZIP: repairs and upgrades read the clone's history to recover what your repo recorded at install. ADOPTING.md has the full ownership and conflict story, and covers repair — the same procedure re-run — and the manual route.
Cairn removes itself the way it installs — an agent, your clone, one reviewable commit:
Read <path-to-cairn-clone>/onboarding.md
and uninstall Knowledge Cairn from this repository.
It asks one question: keep the knowledge, or remove it? The skills, the commands, and the router go either way; your own files are never touched. Reverting the install commit is still the undo while that commit is the last thing you did — uninstall is the way out once your own work sits on top of it. ADOPTING.md spells out exactly what each answer leaves behind.
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.