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 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, 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.14.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/.

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.

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 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 — 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 and 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 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. The machine-readable file list is manifest.json. Follow adopt.md precisely.

Status

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