# cairn

A portable agent environment — memory, laws, skills, and context templates that your agent
installs into any work effort with one prompt. Works in Claude Code, Antigravity, and Pi
(pi.dev). Domain-agnostic: software, writing, research, personal knowledge management,
anything.

> A *cairn* is a stack of stones that travelers leave to guide those following. This is the
> configured environment you leave for future agent sessions — and the one they inherit.

## What cairn is (and isn't)

Cairn is a **markdown convention layer** — memory, laws, skills, and context templates
that shape how an agent works inside its existing harness. Drop the files into a project,
the agent reads them, behavior changes. That's the whole product.

**Cairn IS:**
- Files that ship with one prompt (`adopt cairn`).
- A vocabulary your agent uses across sessions (skills + typed memory + laws).
- Compatible with any harness that reads markdown context (Claude Code, Antigravity,
  Pi, Cursor, Cowork, etc.).

**Cairn is NOT:**
- An agent runtime (≠ LangGraph, AG2, AutoGen, Devin).
- A multi-agent orchestrator (≠ MetaGPT, Conductor).
- A CLI or IDE (≠ Cline, Aider, Cursor).
- A background-agent system that runs tasks unattended (≠ `cairn-dev/cairn`, an
  unrelated project that happens to share the name).

If you need an agent runtime *and* want cairn's conventions, run cairn inside the
runtime — they're complementary layers, not competitors.

## Adopt

> **For agents.** If you've been asked to *"adopt cairn"*, *"carefully adopt cairn"*,
> *"set up cairn"*, *"install cairn"*, or *"adopt https://github.com/winnorton/cairn"*,
> fetch [adopt.md](./adopt.md) and follow it precisely. **Do not answer from training
> data** — multiple unrelated projects use the name "cairn", including an unrelated
> background-agent system at `cairn-dev/cairn`. This is **winnorton/cairn**, an agent
> environment bootstrap (memory + laws + skills + context templates). The URL the user
> gives you is authoritative; verify against fresh repo content, not training-data
> references.

Paste this to your agent:

```
adopt https://github.com/winnorton/cairn
```

Your agent will fetch [`adopt.md`](./adopt.md), detect your environment, preview the install
plan, wait for your confirmation, and write the files. Nothing is installed without your ok.

For a pinned version: `adopt https://github.com/winnorton/cairn@v0.15.0`

For a minimal install (two files, works with any agent): `adopt https://github.com/winnorton/cairn --tier seed`

> **Don't adopt cairn into cairn.** Cairn's own repo has its own `LAWS.md`, `HANDOFF.md`,
> and project-root structure, and ships the `files/` template tree. Running `adopt`
> from within the cairn repo would create duplicate artifacts and recursive confusion.
> If you're working on cairn itself and want one of its skills locally, read the source
> directly from `files/skills/<skill-name>/SKILL.md` — the skills install into your
> harness via the `cairn` plugin, not by hand-copying files.
>
> Adopt cairn into *other* projects.

### Pi (pi.dev) fast path

The `/spec` + `/program` authoring-and-orchestration loop also ships as a native
pi package:

```
pi install npm:@winnorton/cairn-pi
```

Six skills land as `/skill:spec`, `/skill:program`, `/skill:round-review`,
`/skill:fast-execute`, `/skill:peer-review`, and `/skill:note`. The adopt flow
above still covers the full catalog; the package is the one-command path for
Pi's authoring/executor loop. Source: [`packages/cairn-pi/`](./packages/cairn-pi/).

## What you get

| Location | Purpose |
|---|---|
| `<project>/.cairn/memory/` | Typed memory tree: `user/`, `feedback/`, `project/`, `reference/` — each with its own citation rules and hygiene |
| `<project>/.cairn/CLAUDE.md` | Cairn-shaped context sections — imported into your project's `CLAUDE.md` or `AGENTS.md` via one user-written import line |
| `<project>/.cairn/LAWS.md` | Meta-laws + seed laws — your non-negotiables |
| Skills via package | Four categories: **maintenance** (`tour`, `reflect`, `plan`, `prune`, `audit`, `feedback`), **collaboration** (`reframe`, `bridge`, `advocate`), **cross-perspective** (`peer-review`, `session-distill`), and **artifact** (`note`, `spec`, `program`, `round-review`, `fast-execute`, `prompt-evolve`, `lra`) — installed via the `cairn` Claude Code plugin, `@winnorton/cairn-pi` (Pi), or the native `cairn-agy` plugin (agy). See [skills taxonomy](#skills-taxonomy). |

All files install in `create-if-absent` mode — cairn will never overwrite what you've
customized. Re-adopting later will show diffs and let you choose per-file.

After install, say **`tour`** and your agent will walk you through what was installed
and help you take the first concrete action.

## Why

Agents forget everything between sessions. Cairn is the opposite of forgetting:

- **Memory** persists what's worth remembering — user role, preferences, project state, external references.
- **Laws** encode the rules that must survive across sessions, with *Why* and *How to apply* so edge cases don't unravel them.
- **Skills** package reusable capabilities — reflect, plan — that any agent can invoke.
- **CLAUDE.md** gives every new session the project context it needs.

You build this up over time. Cairn just gives you the scaffold so you don't start from nothing.

### Cross-session continuity — the reflect → HANDOFF loop

Memory, laws, and CLAUDE.md hold what carries forward. The *ritual* that keeps them
alive:

- **`/reflect`** at session-end — proposes memory and law candidates, and writes a
  `HANDOFF.md` describing where the work stands.
- **At session-start** — the agent reads `HANDOFF.md` and the memory index, then
  synthesizes a compact orientation.

Reflect produces, HANDOFF carries, the next session reads. This loop turns "agent
forgets everything between sessions" into "agent picks up where we left off."

## Extend

- Add laws to `LAWS.md` as you hit "never again" or "always do this" moments.
- Add skills via the `cairn` Claude Code plugin update or by contributing to `files/skills/` in the cairn source repo (see [`files/skills/README.md`](./files/skills/README.md) for the frontmatter schema). Skills reach your harness through the package, not by hand-dropping files.
- Add memory entries via the agent when it learns something worth persisting.
- Periodically say **`audit`** to see which laws and memories are actually being cited, then **`prune`** to retire the cold ones.

Contributing a skill-body change also updates a reviewed size contract. Run
`node scripts/check-skill-budgets.mjs --update-body-baseline` from the repository root,
inspect the baseline diff, then run the command again without the flag. A word-count
increase requires explicit review justification; regenerating the baseline does not
approve it. This guards prompt size; Cairn still requires cold review for semantic and
adjacent-document consistency.

## Usage signal (citations)

Citation conventions are type-aware. Laws fire discretely and cite by **slug**:
`[LAW plan]`, `[LAW cadence]`. The slug is each law's only identity — there's no
numeric form. Memory is split into four types with different citation rules:

| Type | Character | Citation | Why |
|---|---|---|---|
| Laws | Discrete triggers | `[LAW <slug>]` (e.g. `[LAW plan]`) | Slug is the law's only identity — stable across reorders, no numeric form |
| `user/` | Always-on background | **None** | Continuous; citing every response is noise |
| `feedback/` | Fires discretely | `[MEM feedback/<name>]` | Acts like a mini-law |
| `project/` | Shapes specific decisions | `[MEM project/<name>]` | Cite when it drove a decision |
| `reference/` | Episodic lookup | `[MEM reference/<name>]` | Cite at the moment of reference |

`/audit` counts the discrete citations — laws and the three citable memory types — to tell
you which habitat entries are earning their keep. `/prune` applies type-appropriate
hygiene (event-driven for user, citation-driven for feedback, time-driven for project,
integrity-driven for reference).

Forcing function: if a `feedback` memory fires often enough to cite every time, promote
it to `LAWS.md`. The types create gravitational pulls.

## Feedback to cairn (agent-driven)

When an agent using cairn notices a gap, bug, or missing piece in cairn itself — not in
your project, in cairn — it can file feedback directly to this repo via the **`/feedback`**
skill. Delivery is three-level with automatic degradation:

1. **POST to [`cairn.winnorton.com/feedback`](https://cairn.winnorton.com/feedback)** — hosted endpoint, creates the issue server-side, returns a URL. Works from any environment the agent can make HTTP calls from (no shell required).
2. **`gh issue create`** — if CLI is available and the endpoint isn't reachable.
3. **Draft-for-paste** — if neither, the agent prepares a formatted issue body and asks you to paste it.

The agent notifies you with the issue URL after filing. You are not required to triage
in your working session.

Scoped strictly to cairn itself: framework gaps, confusing instructions, missing skills,
docs errors. Not for your own project's issues.

See [`plans/v0.3-observation-and-feedback-loop.md`](./plans/v0.3-observation-and-feedback-loop.md) and [`plans/v0.6-feedback-endpoint.md`](./plans/v0.6-feedback-endpoint.md) for design rationale.

## Who cairn serves

Cairn is primarily agent-facing — memory, laws, skills, conventions are optimized for
how an agent works. But the human in the loop has jobs too. Cairn has skills that
serve each:

- **Context provision** (user's main job): feeding the agent facts, history, and
  constraints. Supported via `CLAUDE.md`, `MEMORY.md`, and `LAWS.md`.
- **Reframing** (solution-space rotation): unlocked by `/reframe`. Agents converge
  toward training patterns; reframes generate out-of-distribution alternatives.
- **Cross-session relay** (carrying context between parallel sessions): structured
  by `/bridge`. The human is the inter-session communication layer; the skill makes
  the handoff structured instead of improvised.
- **End-user perspective** (observing how others experience what's shipped): prompted
  by `/advocate`. The builder sees the system they built; the end-user sees a cold
  start. `/advocate` rotates the observer position pre-ship.
- **Pre-emptive intent capture** (filing thoughts that may or may not become real work):
  via `/note`. One paragraph, in-repo, dated. Distinct from `/reflect` (post-hoc) and
  from durable, agent-indexed cross-session memory. Cheap to write, cheap to delete,
  cheap to promote when work materializes.
- **External-perspective review** (catching inconsistency-class bugs the work-author
  missed): via `/peer-review`. Reads the diff PLUS adjacent unchanged files that the diff
  expects to be consistent with. Distinct from `/reflect` (which is same-agent post-hoc).

These are **collaboration**, **cross-perspective**, and **artifact** skills, distinct
from the maintenance skills (reflect, plan, prune, audit, tour, feedback) that service
the habitat itself. See the taxonomy below.

## Skills taxonomy

Cairn's skills fall into four categories with different origins.

**Maintenance skills — service the habitat:**

- `tour` — onboard new users post-install.
- `reflect` — end-of-task retrospective (post-hoc, same-agent).
- `plan` — pre-action behavioral alignment (conversational, no file).
- `prune` — retire stale entries by type.
- `audit` — count citations, surface unused structures.
- `feedback` — file issues to cairn's maintainer (three-level degradation).

**Collaboration skills — service the human-agent pair:**

- `reframe` — generate alternative framings when convergent thinking is stuck.
- `bridge` — structure cross-session context relay (parallel sessions).
- `advocate` — simulate end-user perspective before shipping.

**Cross-perspective skills — rotate the observer:**

- `peer-review` — fresh agent reading a change set cold (catches what the work-author
  missed because they were "too close"). Named `peer-review` to disambiguate from Claude
  Code's built-in `/review` skill.
- `session-distill` — fresh agent reading a past session JSONL transcript cold,
  through cairn's improvement lens. Produces a structured report of patterns
  recognized, skill candidates with 3-instance gate check, law candidates,
  memory candidates, and environment-support gaps. This is the **formalization
  of the methodology that produced cairn itself** — the transcript-analysis
  loop the research papers documented, the same loop that surfaced `/reframe`,
  `/bridge`, `/advocate`, and most of the collaboration-skills taxonomy.

**Artifact skills — produce in-tree planning files:**

- `note` — pre-emptive intent capture; one paragraph, in-repo (`docs/notes/`),
  dated. Cheap to write, cheap to delete, can be promoted to `/spec`.
- `spec` — structured agent execution spec (`docs/specs/`) with phases, steps,
  checkpoints, executor handoff. Distinct from `/plan` (behavioral, no file).
- `program` — author a program-of-specs (one master coordination doc + N
  workstream child stubs in `docs/specs/`) for substantial work that exceeds a
  single spec's scope. Bakes in no-deferral discipline + cross-cutting axes
  coverage. Stubs are elaborated by `/spec --from <stub>`.
- `round-review` — trust-but-verify an autonomous executor's round of work
  against a `/program` master. Walks the master's §5 DoD criterion-by-criterion
  against the diff; drafts R+1 stub specs and a self-contained R+1 round master
  for the gaps. Loop exits when this skill writes zero R+1 stubs.
- `fast-execute` — polling-daemon executor for dispatched specs: watches a
  sentinel-file inbox in `docs/specs/`, executes (single specs or round
  masters), and flips sentinels (`.ready` → `.claimed` → `.done`). The
  consumer-side verb of the artifact loop — pairs with `round-review` to
  close the dispatch seam.
- `prompt-evolve` — extract a version-controlled operational prompt from a
  `/spec` for multi-pass work where execution produces both output and reusable
  insight. Coverage units may be known or discovered; each prompt defines its
  stop and re-run semantics, validates writes, and self-edits at the end of a
  pass. Stable mechanical rules graduate into schemas, validators, or tools.
- `lra` — a `prompt-evolve` specialization for researching a subject over many
  passes, run engine-free as project-local markdown the agent walks. Scaffolds
  a `research/` collection and drives two prompts (researcher + librarian)
  synced verbatim from the lra lab into `.cairn/context/lra/`. Not in the Pi
  package (outside its authoring-loop curation).

The maintenance skills were identified by gap analysis — what the agent noticed it
needed. The collaboration skills came from studying what the *human* does in the
collaboration (see [`docs/research/collaboration-skills.md`](./docs/research/collaboration-skills.md)
for the analysis). The cross-perspective skills emerged from observing where one
agent's session leaves blind spots that only a fresh observer can catch —
`peer-review` defeats the work-author's
mental-model anchoring on what they touched. The artifact skills were imported from
a downstream project's `/plan`-rework arc — they produce durable in-repo files with
explicit lifecycles (folder-as-status), distinct from the maintenance skills'
behavioral/conversational shape.

**Design principle:** *observe the collaboration first, then package what you see.*
Skills designed from observation solve problems that exist; skills designed from
theory often solve problems that don't.

## Design notes

**Multi-agent is supported.** Cairn's habitat is passive data — memory files, LAWS.md,
CLAUDE.md, and skills are just files. Any agent that reads them inherits the context.
Multiple agents sharing one habitat works by design; concurrent writes are handled by git
the same way any shared files are.

**Versioning is git.** Put your habitat in a git repo — every file benefits from commit
history. You can diff, rollback, and branch a habitat exactly like any other tracked
content. Cairn itself versions releases with git tags (`v0.4.1`, etc.); your habitat
versions the customizations you layer on top. No separate snapshot mechanism needed.

**Skills are atomic by design.** One skill, one purpose. Composition happens at the agent
layer: agents invoke multiple skills per session as the task demands. If you find yourself
wanting to "chain" two skills into one flow, either (a) one is actually a step inside the
other — merge them — or (b) your skill descriptions need sharper triggers so the agent
picks the right one at the right moment.

**Migration is a prompt, not a script.** Cairn is agent-targeted software. When the
structure changes (see v0.4.0's memory refactor), migration doesn't require migration
code — a capable agent can read the old layout, read the new manifest, and move what
needs to move. `adopt.md` documents the pattern. This changes the cost model for breaking
changes: they're cheap because agents are capable readers/movers, not because maintainers
ship migration tooling.

**Upstream/downstream workspaces.** A single habitat isn't always self-contained. Research
workspaces produce findings that should inform *other* habitats (e.g. a game-engine
research workspace feeding a cwar-engine build workspace). Cairn supports this via a
`## Downstream consumers` section in `CLAUDE.md` — declare who consumes your work. When
`/reflect` fires in a workspace with declared consumers, it produces **distillate**
(memory entries, laws, plans) shaped for each consumer's habitat, written to
`distillate/<consumer>/...` for transport (copy, symlink, or submodule). Research stays
in its source workspace as long-form reasoning; the distillate is what actually flows
between habitats.

**What matters vs what helps (role).** Every installed file has a `role` in the manifest:

- **`essential`** — load-bearing from day one (`CLAUDE.md`, `MEMORY.md`). The habitat doesn't meaningfully function without these. Fill in first.
- **`scaffolding`** — shape is important, content grows with you (`LAWS.md`, memory type READMEs, growth-dependent skills). Skim at install, customize over time. Hard to skip entirely.
- **`optional`** — ergonomic standardization (`reflect`, `plan`, `feedback` skills). A capable agent does these anyway; the skills just make them consistent and discoverable.

**How deep to go (tier).** A second axis: how cairn-specific do you want your habitat to be?

- **`seed`** — `CLAUDE.md` + `MEMORY.md`. Two files. **Works with any agent** (Claude, GPT, Gemini, local LLM) that can read markdown. Minimum viable habitat = maximally portable habitat.
- **`grow`** — adds `LAWS.md` + maintenance skills (`reflect`/`plan`) + artifact skills (`note`/`spec`) + collaboration skills (`reframe`/`bridge`/`advocate`) + cross-perspective skills (`peer-review`). Durable conventions any careful agent can follow.
- **`structure`** — adds typed memory + hygiene skills (`tour`/`prune`/`audit`). Assumes cairn-aware tooling.
- **`full`** — adds the `feedback` skill (files issues to cairn's own repo). Claude-Code/Cowork-optimized.

Tiers are cumulative. Default install is `full` (everything). Request a smaller tier via
`adopt … --tier seed`/`grow`/`structure`.

**Portability.** The minimum viable habitat (seed tier) is the maximally portable habitat —
two markdown files any LLM can read. Higher tiers progressively add cairn's own conventions
(citation patterns, skill format, feedback-loop integrations). If cross-ecosystem
portability matters to you, stop at `seed` or `grow`. If you're all-in on Claude's
ecosystem, take `full`.

## Agent-readable install instructions

Agents: the canonical install script is [`adopt.md`](./adopt.md). The machine-readable file
list is [`manifest.json`](./manifest.json). Follow `adopt.md` precisely.

## Status

v0.15.0 — **The interim slice, released.** Cuts a tag over the work that accumulated on
`main` since v0.14.0 while `VERSION` stayed pinned, which had left installed plugins with
no signal to update on: the skill-compression campaign, the `lra` skill pack, law-creation
discipline (`check-laws-shape.mjs` plus the gate-not-law and memory-first meta-rules), the
skill-size gate suite (`check-skill-budgets.mjs`, `check-prompt-register.mjs`), the new
`swarm` skill, and `prompt-evolve`'s cold-start mode, project-named coverage table, and
`ACTIVE`/`HELD` lifecycle state. 19 skills.

v0.14.0 — **Cairn ownership migration.** State moves out of vendor namespaces into a
cairn-owned `<project>/.cairn/` directory; skills distribute as cairn-named packages
the vendor's own installer places: the `cairn` Claude Code plugin
(`claude plugin marketplace add winnorton/cairn` + `claude plugin install cairn@cairn`),
`@winnorton/cairn-pi` (npm), and the native `packages/cairn-agy` agy plugin
(`agy plugin install github:winnorton/cairn//packages/cairn-agy@main`). `adopt.md`
does zero agent writes to vendor dirs — the only vendor-file touch is one
user-written `@./.cairn/CLAUDE.md` import line. Adds the non-destructive
v0.13.x → `.cairn/` migration flow, install-integrity checks, the shared
`scripts/sync-skills.mjs` drift guard + CI, and codifies `[LAW own-your-namespace]`.
Program master: `docs/specs/archive/SPEC_CAIRN_OWNERSHIP_00_PROGRAM.md`.

v0.13.1 — Renames `/review` to `/peer-review` to disambiguate from Claude Code's
built-in `/review` skill. The bare `/review` invocation in any Claude Code session
resolves to the built-in — the cairn skill was being silently shadowed for any cairn
adopter on Claude Code. Updates: skill subdirectory rename
(`files/skills/review/` → `files/skills/peer-review/`), frontmatter `name:` field,
manifest src/dest paths, install preview, citations across LAWS.md / HANDOFF.md /
README. New migration section in `adopt.md`: re-adopters from any version that
installed the legacy `~/.claude/skills/review/SKILL.md` get prompted by the agent
during re-adoption to clean up the legacy file. Posture going forward (per
`[MEM project/cairn-blend-strategy-pillars]`): vendor namespace collisions are real;
cairn claims distinct namespace per skill from here on.

v0.13.0 — Slug-only law identity (drops Law N numbering). Completes the v0.9.0 slug
migration — v0.9.0 added slugs as the citation form but never removed the competing
numeric form, leaving two valid-looking identities and a meta-rule trying to suppress
one of them. Numbers also implied blast-radius ordering the laws didn't honor in
practice. Fix: numeric prefixes removed from law headings in both `LAWS.md` and
`files/LAWS.md`; slug becomes the only identity; collection size moves to section
headers (`## Seed laws (6)`). Meta-rule 2 rewritten as "Slug is identity, count is
metadata." Plus connects the reflect↔resume loop in user-facing docs — README's new
"Cross-session continuity" subsection, tour Step 5 names both verbs, and a "Skill
pairings" section in `files/skills/README.md`. Fresh `/review` caught README body-text
drift the author missed (anchored on `LAWS.md`, didn't grep README's own usage-signal
section) — exact gap class `[LAW pre-merge-review]` is built for. Re-adopters with
legacy `[LAW N]` citations: see the migration note in `adopt.md`. The `/audit` skill
flags numeric citations as "legacy needing manual conversion" rather than auto-resolving
(the number-to-slug mapping no longer exists in source-of-truth).

v0.12.3 — Doc patch: fix v0.12.x consistency gaps that a fresh `/review` session
caught after v0.12.2 shipped. (1) `adopt.md` tier counts and install preview were
missing `/spec` — agents installed 21 files but consent + report claimed 20.
(2) `README.md` "What you get" claimed three skill categories; cairn has four
(artifact added in v0.12.0). `/note` was miscategorized as maintenance.
(3) `/review` skill body itself still cited `cwar/.agents/workflows/execute-plan.md`
as the worked example — exactly the cwar-coupling regression v0.12.1 stripped from
`/note` and `/spec` but missed in `/review`. (4) cairn-slug `MEMORY.md` was missing
the index entry for `feedback/habitat-bootstrap-three-surfaces` (file existed; index
didn't list it). (5) `plans/v0.12-cairn-from-cwar-arc.md` still in `plans/` despite
all three v0.12.x releases shipping — moved to `plans/archive/`. The fact that
`/review` caught these in its own surrounding artifacts is the cleanest possible
self-validation of the skill.

v0.12.2 — Doc patch: fix install-report version strings. v0.12.1 shipped with `adopt.md`
hardcoded "v0.12.0" in the install preview, post-install report, and pinned-version
example URL — agents installing v0.12.1 reported "v0.12.0 installed" to users. Fixed
in v0.12.2 along with similar stale references in HANDOFF.md and `files/skills/README.md`.
Doc-only.

v0.12.1 — Skill format migration to canonical `~/.claude/skills/<name>/SKILL.md`
subdirs (Claude Code's official format). Flat `.md` skills don't reliably register
as slash commands; the new format fixes the bug. Adds `/review` (external-agent
review skill, catches inconsistency-class bugs the work-author missed because
they were "too close") — pairs with the v0.12.0 artifact skills. New fourth skill
category: **cross-perspective** (`resume`, `review`) — distinct from maintenance,
collaboration, and artifact. Plus folder-as-state for cairn's own `plans/` (shipped
plans now live in `plans/archive/`). Plus a `/note`-vs-cross-session-memory
disambiguation callout in `files/CLAUDE.md`. Plus `/note` and `/spec` cleaned up
to remove cwar-specific worked-example coupling and use generic `docs/notes/` /
`docs/specs/` paths. Re-adopters: see the migration note in adopt.md for cleanup
of old flat-format skill files.

v0.12.0 — Two new artifact-creation skills imported from a downstream project's
`/plan`-rework arc: `/note` (pre-emptive intent capture — single paragraph,
in-repo, ephemeral) and `/spec` (structured agent execution spec with phases,
steps, checkpoints, executor handoff). New "Artifact skills" category added to
the skill taxonomy alongside maintenance and collaboration. Distinct from cairn's
existing `/plan` (behavioral pre-action alignment, conversational, no file output).
v0.12.1 follows up with the format migration + /review + folder-as-state cleanup.

v0.11.3 — adopt.md gains a second pre-flight check: refuse install in ephemeral
sandboxes (claude.ai web/mobile chat, hosted notebooks, sandboxed evals) where
filesystem writes don't reach the user's machine. Filed after a Claude.ai chat
session walked Step 1, hit "Neither clear? → Ask the user", and surfaced the
spec gap unprompted — the right behavior, but only because the agent was careful;
a less-careful agent could have faked the install into `/home/claude`. The new
pre-flight closes that path explicitly. Doc-only.

v0.11.2 — Doc patch: category disambiguation. Added "What cairn is (and isn't)"
section between the description and Adopt — explicit IS/IS NOT framing because
agents (and search-grounded answers) keep mistaking cairn for a runtime, an
orchestrator, a CLI, or `cairn-dev/cairn`. Surfaced after a Gemini test
returned a peer-comparison list of agent runtimes (LangGraph, AG2, MetaGPT,
Devin) — every project on the list was a wrong-category peer because cairn is
a convention layer, not a runtime. Doc-only.

v0.11.1 — Doc patch: agent-side disambiguation + trigger-phrase callout.
Added a "For agents" block to README's Adopt section and to adopt.md's
top: lists the natural trigger phrases (`adopt cairn`, `carefully adopt
cairn`, `set up cairn`, `install cairn`), and explicitly warns against
substituting training-data references for fresh repo content. Surfaced
after a Gemini test answered from training data — describing an unrelated
`cairn-dev/cairn` background-agent system — without fetching the URL the
user gave it. Doc-only.

v0.11.0 — Project subdirs for cross-project user-global memory stores (#22).
Antigravity's `~/.gemini/antigravity/memory/` shares one tree across every
workspace, so entries from cwar-engine, cairn, and side-projects accumulated
flat under `project/`. New rule: cross-project user-global stores get a
`project/<projectname>/` layer; citation becomes
`[MEM project/<projectname>/<name>]`. Slug-separated stores (Claude Code's
per-slug `~/.claude/projects/<slug>/memory/`) stay flat — the slug already
separates. `/reflect`'s distillate-naming convention updated; the rule is
documented in `files/memory/project/README.md`. Migrated 5 existing
Antigravity entries into `project/cwar-engine/`.

v0.10.9 — Antigravity added to the canonical "Works in X" list (README, adopt.md,
manifest.json description). Validated empirically on 2026-04-25: a Gemini Pro 3.1
session adopted cairn cleanly into the Antigravity workspace, and a follow-up
Opus session ran `/bridge` + `/plan` end-to-end against cairn skills and produced
a shipped feature commit on cwar's main. Anecdotally Antigravity may be the
strongest of the three harnesses for cairn workflows — the agent-relay browser
panel pattern composes well with cairn's HANDOFF.md + memory_query story.
Doc-only release.

v0.10.8 — First end-to-end **distillate-to-production** arc documented. A
research finding from one workspace (game engine research, Cowork) became a
feature-flagged commit on a production codebase's main branch (cwar-engine,
Worker-based simulation Phase 1) — six steps, four sessions, three platforms
(Cowork → Antigravity → Claude Code), two repos. New research paper
[`docs/research/distillate-to-production.md`](./docs/research/distillate-to-production.md)
walks the arc step-by-step with evidence (commit hashes), shows what cairn
primitive each step depends on, and names what's still manual (cp transport,
partly addressed by v0.10.6). Doc-only release.

v0.10.7 — Research docs refreshed with Phase 2 evidence. Cairn-test session
analyzed a second transcript (v0.7.0 → v0.10.5, ~50 messages, cross-platform
testing in Antigravity + Cowork + Claude Code) and updated four research
papers + added `open-questions.md`. New findings: bidirectional verification
(an agent corrected the human with tool-log evidence), experimental design
as a distinct human pattern, ecosystem-coordination as a third candidate
skill category. Removed redundant `cross-session-observation.md`
(consolidated into `habitat-transfer.md`). Doc-only release.

v0.10.6 — Two bridge-test learnings codified. (1) `/reflect` Step 7 added: when consumer
path is locally writable, offer to copy distillate directly — eliminates the manual `cp`
step that's been cross-workspace friction. Cross-machine fallback documented (git transport,
or leave staged). (2) `/bridge` Step 3.5 added: verify load-bearing claims against current
state before integrating. Codifies the Opus agent's exemplary verify-then-integrate
behavior during the 2026-04-25 cross-workspace bridge test.

v0.10.5 — `/bridge` skill: ask direction before guessing. When the user invokes
`/bridge` without a clear direction signal, the skill now requires asking incoming-
or-outgoing first. Validated 2026-04-25: a Gemini Pro 3.1 session produced a
well-formed but wrong-direction outgoing bridge when the user wanted incoming.
Confirmation gate prevents this misfire pattern.

v0.10.4 — Doc fix: don't `git clone` cairn during adopt. `adopt.md` Step 5 gains
an explicit pre-flight forbidding `git clone` of the cairn repo into the workspace.
Adopt fetches manifest-declared files via HTTP — it does NOT pull the framework's
entire source. Validated 2026-04-24 by Gemini Pro 3.1 in Antigravity: the agent's
first instinct on `adopt URL` (no flag) was to `git clone https://github.com/winnorton/cairn .`
— tool-log entry timestamped at 2026-04-25T01:35:24Z. Defensive doc grounded in real
non-Claude-agent behavior, not speculation.

v0.10.3 — Doc fix: don't adopt cairn into cairn. README adopt section gains a warning
+ workaround (copy individual files from `files/skills/` to `.claude/skills/` for
cairn-internal development). `adopt.md` Step 1 has a pre-flight check that detects
cairn's own repo (via `manifest.json` name field or `LAWS.md` title) and stops before
install. Surfaced when the maintainer realized the recursive "adopt cairn into cairn"
case is plausible — and dangerous (would create duplicate `LAWS.md`, `CLAUDE.md`, etc).

v0.10.2 — Slug policy formalized after the second `/resume` validation surfaced the
question: where SHOULD memory live in multi-project workflows? Files that are scope-
local stay at one slug; cross-cutting agent-meta-knowledge picks one slug + declares
a pointer in HANDOFF.md. New `[LAW choose-slug-by-scope]` in cairn's own LAWS.md
codifies this. `files/memory/MEMORY.md` template gains a "Where memory should live"
section. Cairn-native memory entries migrated from cwar's slug to cairn's slug.

v0.10.1 — `/resume` validation surfaced two gaps; both fixed. (1) HANDOFF.md drifted
within one release cycle ("v0.9.1" inside HANDOFF.md while main was on v0.10.0) — new
seed law `handoff-stays-current` in cairn's own `LAWS.md` requires HANDOFF.md to update
in the same commit as VERSION/manifest/README. (2) `/resume` couldn't find memory
written under a different project's slug — extended the skill to read a `## Related
memory paths` section from HANDOFF.md and probe those paths too. cairn's HANDOFF.md
now declares cwar's memory slug explicitly, so a fresh `/resume` in cairn finds the
session's memory entries.

v0.10.0 — `/resume` skill for session-to-session handoff. The first link test (a fresh
session opening in a different worktree, asking "where were we?") FAILED to auto-discover
prior context because: (1) memory is namespaced per-worktree; (2) `HANDOFF.md` requires
explicit knowledge of where to look; (3) transcript junctions are ad-hoc. `/resume`
codifies the probe — checks HANDOFF.md at common paths, memory at multiple project slugs
(worktree-aware), transcript junctions, and recent git activity, then synthesizes a
compact orientation. Agents now have a named protocol for "pick up where we left off."
See `plans/v0.10-session-handoff.md`.

v0.9.1 — Session-close release: cairn's own LAWS.md (at repo root — framework eats its
own dog food), LAWS.md template credit note pointing at `NEW_LAWS_OF_AI_AGENT_ENGINEERING`
as the meta-disciplinary source, `HANDOFF.md` for session-to-session bridging, and #15
closed (userSkills dual-scope path detection parallel to #6's memory fix).

v0.9.0 — Slug-based law identity (#18). Laws now cite by stable slug (`[LAW plan]`,
`[LAW cadence]`) instead of drift-prone numbers. Numbers initially remained as
display-order markers (removed entirely in v0.13.0); `/audit` matched both forms
during the transition. Evidence: cwar's AGENTS.md renumbered
26→22→13 rules in one day, leaving citation debt in ESLint comments and cross-file
references — cairn preempts the same pattern. See `plans/v0.9-law-slugs.md`.

v0.8.0 — Reflection cadence + upstream/downstream distillation (closes #14 + #17).
`/reflect` now triggers proactively at natural checkpoints (not only on explicit user
request) and produces distillate for declared downstream consumer habitats. New
optional `## Downstream consumers` section in `CLAUDE.md` template. Sixth seed law
added: "Pause to reflect at natural checkpoints." Addresses the root cause observed
when a research agent produced 1,600+ lines of work and zero memory entries —
reflection wasn't firing. See `plans/v0.8-upstream-downstream.md`.

v0.7.0 — Collaboration skills + taxonomy (#16). Systematic analysis of the cairn build
transcript surfaced three more skills that serve the human-agent pair: `/bridge`
(cross-session relay), `/advocate` (end-user perspective), and a `/plan` enhancement
for timing awareness. Introduces the maintenance-vs-collaboration taxonomy explicitly
in README and skills/README. Adds `collaboration-skills.md` and `human-interaction-patterns.md`
to `docs/research/`. See `plans/v0.7-collaboration-skills.md`.

v0.6.4 — Cite in durable output, not just in conversation (#13). First cross-session
habitat transfer observation revealed that `[LAW prefer-edit]` (formerly `[LAW 4]`) fired in live transcript but
left no trace on disk — `/audit` was blind despite the habitat actively shaping
behavior. LAWS.md meta-rule 5, memory type READMEs, and audit.md now specify
citations must appear in files/notes/commits to feed the audit loop. Adds
`habitat-transfer.md` and `cross-session-observation.md` to `docs/research/`.

v0.6.3 — Install must fetch files via HTTP, not heredoc inline (#12). adopt.md
Step 5 now explicitly rules out `cat > file << EOF ... EOF` patterns and mandates
`curl -sL {rawBase}/{src} > {dest}` (or equivalent). Adoption time drops from
minutes to seconds when agents follow the correct path.

v0.6.2 — adopt.md no longer invites agents to render a tier picker (#11). First-time
install is default-full with a single y/n confirmation; tier flags documented as
invocation-only forms.

v0.6.1 — Feedback endpoint live + multi-URL fallback. Deployed to Cloud Run;
manifest now lists both the Cloud Run direct URL and `cairn.winnorton.com` (custom
domain, pending CNAME propagation) so agents always have a working primary. Skill
tries URLs in array order, falls through on DNS/network/5xx.

v0.6.0 — Hosted feedback endpoint (cairn-side wiring). Handler code + Cloud Run
deployment guide in `server/feedback-endpoint/`. See `plans/v0.6-feedback-endpoint.md`.

v0.5.1 — `/reframe` skill + "Who cairn serves" framing (#9). Cairn now directly
supports the user's reframing job (not just context provision). Skill generates 2–4
alternative framings on request — helps humans rotate the solution space when
convergent thinking is stuck.

v0.5.0 — Graduated tiers (#8). Every installed file tagged with a `tier` alongside
`role`. Four tiers: `seed` (two-file minimum viable = maximally portable habitat),
`grow` (adds laws + process skills), `structure` (adds typed memory + hygiene),
`full` (adds cairn-ecosystem integration). Default install unchanged (full); users who
want portable minimal now have `--tier seed`. See `plans/v0.5-graduated-tiers.md`.

v0.4.3 — Roles: every installed file tagged `essential | scaffolding | optional` (#7).
Install preview groups by role; README's Design notes explains what matters vs what
helps.

v0.4.2 — Memory path dual-scope detection (#6). `adopt.md` Step 1 and `manifest.json`
now document that Claude Code has two memory conventions (user-global vs project-scoped)
and require probing before installing. Silent-failure gap closed.

v0.4.1 — Agent-driven migration as a first-class path (#5). `adopt.md` now documents the
migration flow (detect → plan → execute → verify) including index-tombstoning for
environments without deletion support. Cowork Step 3 also distinguishes bash mount from
memory store with per-layer tool guidance.

v0.4.0 — Typed memory (#4). Memory splits into `user/`, `feedback/`, `project/`, and
`reference/` subdirectories with per-type citation conventions. `/audit` and `/prune`
are per-type aware. See `plans/v0.4-typed-memory.md`.

v0.3.3 — Version marker + re-adoption fast-path (#3).
v0.3.2 — Explicit doc-only re-adoption case (#2).
v0.3.1 — Cowork `.claude/` write protection + shell fallback (#1).
v0.3.0 — citation convention, `audit`, `feedback`.

## License

MIT — fork it, adapt it, make your own cairn.