cairn
Skill1 starsChanged 26 days agoMITView on GitHub
cairn — repo-native project memory in markdown + git. Use when the user explicitly asks for cairn, history lookup, progress logging, wrap-up/governance, SOP/pitfall/decision capture, installation, cross-repo reuse, or route-finding. Ordinary task execution should follow the short AGENTS.md protocol without loading this full skill. Base dir: .cairn or .trellis.
5 other projects use a version of this.
Adopted by
Most recently taken up by
- zilet/cairntheir own version, first seen Oct 20, 2026
- CheswickDEV/cairntheir own version, first seen Oct 13, 2026
- CarriedWorldUniverse/nexustheir own version, first seen Oct 12, 2026
- z91772524-ai/pojia-next-mactheir own version, first seen Sep 28, 2026
- mhd-nasher/cairntheir own version, first seen Jun 17, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- z91772524-ai/pojia-next-mac★ 39same name
- zilet/cairn★ 12same name
- CheswickDEV/cairn★ 1same name
- mhd-nasher/cairn★ 1same name
- CarriedWorldUniverse/nexus★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
We split this skill into the rules it gives an agent
10 rules. 0 are common, 4 are distinctive, and 6 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
Base dir: check for .cairn/ first, then .trellis/.
- Very specific: line 40
No hit → start a task: cd "$(./<base>/scripts/mktmp.sh payment-timeout-storm)".
- Very specific: line 52
Read that task's progress.md "Next/Blocked" and continue — no scrollback needed.
- Very specific: line 75
Work: all throwaway artifacts into scratch/ (the root-guard hook enforces this).
- Distinctive: line 93
If reusable: write a summary md at the task's top level (personal layer).
- Very specific: line 102
All in-flight work: grep "^- 🚧\|^- ⏸" <base>/tasks/INDEX.md (anchored, so header text doesn't match) — that's the dashboard, zero upkeep.
- Distinctive: line 109
On-demand memory consolidation: when asked to distill recent experience or find missed memories, read memory-consolidation.md.
- Very specific: line 125
Not in INDEX ≠ never done (no backfill): fall back to ls <base>/tasks/ | grep <kw>.
- Distinctive: line 173
No backfilling old empty task dirs.
- Distinctive: line 174
No standalone state pointer files, ever.
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
cairn — repo-native project knowledge & progress conventions
A cairn is a stack of stones on a trail: it doesn't tell you how to walk, it tells whoever comes next — someone was here, this path works.
Base dir: check for .cairn/ first, then .trellis/; all paths below use <base>.
Quickstart (use it first, understand it later)
Cheat sheet — the three everyday commands:
| Want to | Run | |
| Start a task (Bash) | cd "$(./<base>/scripts/mktmp.sh <topic>)" | |
| Start a task (PowerShell) | $p = & .\<base>\scripts\mktmp.ps1 <topic>; Set-Location $p | |
| Check prior art | `rg -i 'term1 | term2' <base>/tasks/INDEX.md` |
| See what's in flight | `rg "^- (🚧 | ⏸)" <base>/tasks/INDEX.md` |
Three typical scenarios, start to finish (full multi-file example in examples/sample-trail/; a desensitized Chinese version in examples/sample-trail-zh/):
A — Check history before starting (the common case)
User: "Dig into why payment timeouts spike every ~45 min."
- Feels familiar, grep first:
grep -i timeout <base>/tasks/INDEX.md - Hit → Read that task's summary and reuse the fix instead of re-investigating.
- No hit → start a task:
cd "$(./<base>/scripts/mktmp.sh payment-timeout-storm)"; all debug dumps go in thatscratch/(writing them at repo root gets blocked by the hook).
B — Wrap up (≤2 min total)
User: "That's it, wrap it up."
- Gate first: keep a line only if you can name a plausible future task, the action this conclusion changes, and the evidence/applicability boundary. If any answer is missing, delete the placeholder; the dated folder remains as the trail. Otherwise grep INDEX for similar existing lines, then stack one reusable conclusion on top — not a delivery log:
- 03-18-payment-timeout-storm — our own idempotent replay had no jitter/cap → retry storm; capped + jittered [payment][retry-storm] - Three-question check: ① Do this again? yes → distill
sop/investigate-payment-timeouts.md(and: could a hook/lint catch it automatically instead?). ② Six-months-why? no architecture choice → no decision entry. ③ Which recalled line materially changed this task? In the consuming task's summary/progress add- Reused [<source-slug>](<path>): <action changed / work avoided>; never mutate the frozen source line for a counter. - Got bitten? one line in
spec/pitfalls.md, trigger → correct move → why the old way fails:- 2026-03-18 fixed-schedule retry jobs synchronize into storms → always add jitter + cap (bare retries all fire at once) [retry][cron]
C — Resume across sessions
User (new session): "Where did the timeout thing land?"
grep "^- 🚧\|^- ⏸" <base>/tasks/INDEX.md→ hit🚧 03-22-checkout-ab-migration- Read that task's
progress.md"Next/Blocked" and continue — no scrollback needed.
0. Six principles (why this shape)
Distilled from a 5-month / 148-task autopsy of a heavyweight framework: everything that needed discipline to feed (JSONL injection, agent pipelines, lifecycle pointers) rotted; the dated-folder conventions survived. ①trail lives in the repo, split personal/team ②a task is a dated folder ③separate dirt from record (scratch + root guard) ④index + detail, grep-then-read ⑤retrieve on demand, inject nothing (measured: 22KB/session nobody read) ⑥conventions over machinery; state lives on the task. Full version: docs/philosophy.md.
1. Six content types
| Type | Answers | Location | Index | Updated |
| Task trail / reusable memory | what happened / what changes future work | dated task dir / tasks/INDEX.md | INDEX contains only reusable conclusions plus active placeholders | wrap-up |
| Progress | where are we | task's progress.md + 🚧 in INDEX | INDEX markers | session end |
| SOP | how to do X | sop/<verb-topic>.md | sop/index.md | 2nd time doing X |
| Decision | why is it like this | docs/decisions/NNN-<topic>.md | numbered filenames | wrap-up check |
| Pitfall / spec | what bites / detailed conventions | spec/pitfalls.md + spec/<topic>.md | itself / pointer in AGENTS.md | when bitten / when conventions form |
| Docs | designs, write-ups | docs/ | optional | on completion |
2. Task lifecycle (start → work → log → wrap up)
Locate the project first (multi-project rule): walk up from the cwd to the nearest .cairn/ or .trellis/ — the task belongs to that project (same scoping as .git; one instance per project, no cross-pollution). Parent repo + sub-repos: cross-repo tasks go to the parent; single-repo tasks go to that sub-repo if it has cairn installed, else fall up to the parent. Nothing found → offer to bootstrap. 🔴 CHECKPOINT: when one session touches multiple projects, state the target project before ANY write — a stone stacked in the wrong project is worse than none.
Start: Bash cd "$(./<base>/scripts/mktmp.sh <topic>)"; PowerShell $p = & .\<base>\scripts\mktmp.ps1 <topic>; Set-Location $p. Whichever script you call determines where the task lands. It stacks a 🚧 <slug> — TBD placeholder so forgotten wrap-up is visible debt. If the topic feels familiar, do §5 history lookup first.
Work: all throwaway artifacts into scratch/ (the root-guard hook enforces this).
Authorization boundary: Cairn records prior facts, judgments, and approvals; it never carries authority forward. Destructive actions, publishing, production writes, permission changes, and external messages still require authorization from the current user instruction and runtime policy. A historical "approved" note is evidence, not permission.
Sensitive-data boundary: secrets, tokens, personal data, and data the user explicitly asked to delete do not become audit memory. Stop propagation and follow the current security/deletion policy; purging shared history still requires current authorization. This exception overrides frozen-history and "mark stale, do not delete" conventions.
Log progress (user says "log progress" / natural session end on long tasks): create/update progress.md (goal / acceptance and proof / done / next / blocked / settled-no / reversals / incidents, all dated; incremental, never delete). For multi-file, risky, or externally visible work, define observable acceptance criteria before implementation; at completion attach the exact command/test/screenshot/log and state what remains unverified. Treat Next as the current frontier: only decisions/tasks that are clear, unblocked, and immediately claimable; do not force still-vague "fog" into premature tasks. Write every Next item as - [ ]; when done, check it in place as [x] and do not delete the line. A 🚧 task must retain at least one unchecked frontier item; otherwise mark it ⏸ or wrap up. If this round rejected a route, overturned an earlier judgment, or collided with another session, record it in the matching section — those three never go in an INDEX line.
Path unclear? Switch to route-finding, not a bigger progress file. If the destination is clear but multiple dependent decisions must be resolved before implementation, read route-finding.md and create task-local route-map.md + route/ tickets. Its open, dependency-cleared tickets are the computed frontier. This optional mode replaces using progress.md as both roadmap and execution log; ordinary tasks do not create it.
Route each record to exactly one place: a rename/move/delete/config change that alters what others should believe right now → tasks/ENV-LOG.md, written immediately; a conclusion that will change a named future action → one INDEX line; process, evidence, reflection, routine delivery status, and follow-ups → the task's summary/progress. A completed task is not automatically a memory item.
Wrap up (user says "wrap up" / "we're done"; total ≤2 min):
- Write gate (entry bar, not optional): keep the placeholder only if you can name (a) a plausible future task, (b) the concrete action this changes, and (c) the evidence or applicability boundary. Any missing answer → delete the placeholder; the dated folder remains as the record. This makes INDEX a reusable-conclusion index, not a delivery log.
- Confront before writing: grep INDEX for lines on the same subject. Hit → an in-place UPDATE is allowed only while that line is the mutable 🚧 placeholder; a frozen conclusion permits only mark old
[stale:MM-DD reason]+ add the new line, or NOOP (old line already covers it). ⚠️ Contradiction ≠ obsolescence: two conclusions that appear to clash may simply hold under different conditions (different branch, environment, data scale — both were true where they were written). When you can't tell "the old one is wrong" from "the situation changed", keep both and annotate each with its applicable condition instead of force-merging; the mechanism's job is to surface the conflict, the human's job is to adjudicate (the half you merge away is gone when someone reopens the question six months later). No hit → ADD: rewrite the 🚧 placeholder into the conclusion and drop the marker:- MM-DD-<topic> — one-sentence conclusion [kw1][kw2](≤120 chars, conclusion not topic-restatement). Write it searchable — the words you'd grep for later: the user's phrasing and the technical anchor (error text / table / function), with synonyms & aliases in[keywords]. (If mktmp didn't run, just stack a fresh line on top.) Roll-over: if the lane continues after this wrap-up, do not keep appending to the old line. Wrap each completed sub-delivery as its own dated slug and INDEX line; open a fresh slug with 🚧 for unfinished work. If it will not fit in one ≤120-character line, it is not one task — it is a lane. - Close acceptance: record the evidence for each criterion and the unverified boundary. "Implemented", "reviewed", or a green unit test alone does not prove external behavior unless that was the criterion.
- If reusable: write a summary md at the task's top level (personal layer). 🔴 CHECKPOINT: before
git add -f-ing any personal-layer file (tasks/, INDEX, pitfalls) into the shared repo, confirm with the user first — shared history is irreversible; default is stay personal. - Three-question self-check (the feedback hook): ① Will we do this again? → create/update an SOP; bitten → one pitfall line — and if a hook/lint could catch it automatically, build that instead. ② Will someone ask "why" in six months? → register a decision. ③ Which recalled conclusion materially changed or misled this task? → helpers get
- Reused [<source-slug>](<path>): <action changed / work avoided>in the consuming task's summary/progress. Misleaders get- Correction [<source-slug>](<path>): <trigger> -> <old conclusion exceeded its boundary>; evidence: <test/log/user correction>. The review ritual decides whether to mark the source[stale:MM-DD reason], narrow its boundary, or retain it; never silently auto-edit the source. Legacy[used:N]remains readable but is no longer written. - Impact check (
seek.sh --inflightfor family-wide work) — two kinds, different timing:- State impact (rename/move/delete/schema/config/index rebuild — you mutated shared state): log it to
tasks/ENV-LOG.mdthe moment you make the change, rename must carry the ID; don't wait for wrap-up (by then a parallel session has reasoned from a stale picture for hours). 🔴 Conversely: when metrics drop or something's missing, read ENV-LOG and the family's in-flight tasks before suspecting your own change. - Conclusion impact (your finding changes someone's judgment): tell them at wrap-up — append to their task's
progress.mdunder Blocked/Waiting:- MM-DD affected by <repo>/<this-slug>: <one line>, details: Read <path>; if their session is still open, optionally one session message (pointer only, never the full text). No impact → no push; targeted, never broadcast. - The pool is distributed: every session registers in its own nearest
.cairn; the global view is computed on demand. Details incross-repo.md§5.
- State impact (rename/move/delete/schema/config/index rebuild — you mutated shared state): log it to
3. Progress ("where are we?")
- All in-flight work:
grep "^- 🚧\|^- ⏸" <base>/tasks/INDEX.md(anchored, so header text doesn't match) — that's the dashboard, zero upkeep. - Resume a task: if
route-map.mdexists, read its computed frontier and corresponding ticket first; then readprogress.md"Next"/"Blocked". Otherwise read progress directly. - Stale 🚧 markers surface in one grep; fix on sight. Never create a separate current-task pointer file.
- Actively self-check with
./.cairn/scripts/doctor.sh(zero-dep bash): flags 🚧 lines that are stale (14d), oversized (>600 characters), missingprogress.md, or missing an actionable frontier (warnings for the last two), plus stale ⏸ markers (60d), missing task targets, duplicate slugs, dead relative links, INDEX capacity/line-length breaches, and unindexed task directories. Deliberately kept out of the session hook so it costs nothing per conversation. - Visual panel (when you'd rather look than grep):
./.cairn/scripts/panel.shrenders the current Cairn to.cairn/panel.html; add--scope familyfor the topmost parent plus nested child Cairns (default discovery depth 3; raiseMAXDEPTHexplicitly). Family identity isrepo-relative path + slug, never slug alone. The default Do now tab shows one next step per in-flight task, meaningful blockers, and executable frontiers; full cards are collapsed, while Knowledge, History (newest 40 first), and Health are separate tabs. The repo picker recomputes every view and Health lists Git projects without Cairn, but never installs one. Promotion support counts distinct consuming tasks; repeated links in one task count once. Zero-dep, read-only snapshot; regenerate to refresh. - Review ritual (every 2–4 weeks): 🔴 read
review-ritual.mdbefore acting. Entry:doctor.sh --review(single repo) /seek.sh --review(family) — returns wrapped-up entries with no inbound Reused/复用 evidence (legacy[used:N]still counts) plus in-flight 🚧 entries ready to unmark. It produces a proposed diff for human sign-off; deletion and consolidation outrank additions.
On-demand memory consolidation: when asked to distill recent experience or find missed memories, read memory-consolidation.md. Scan a bounded set of finished tasks, return evidence-backed proposals, and use the existing review gate before applying them; never run on every session exit.
4. SOPs and decisions (the upgrade chain)
SOP = repeatable step sequence (agents are reliable when SOP-driven). Template: when-to-use / pre-checks / numbered steps with expected output / verify / rollback. Distill on the second time you do a thing; update on the spot when steps drift. Before doing anything, check sop/index.md — follow, don't re-explore.
Decision = why the system is the way it is. Born in a task, registered in docs/decisions/NNN-<topic>.md (status/date/source/context/options-with-rejections/rationale/consequences, one page). Narrow bar: choices affecting multiple future tasks, rejected options that will be re-proposed, cross-repo agreements. Never edit a superseded decision — write a new one and mark the old superseded by NNN.
Chain: scratch notes → task summary → SOP (project) → agent skill (cross-project); pitfall line → repeated? → agent rule or SOP pre-check. The panel may surface a conclusion after repeated cross-task reuse, but that count only opens human review: verify trigger / procedure / evidence / boundary before promotion. Keep the SOP's Source: tasks/<slug>/ link so the panel can show the completed promotion without semantic guessing.
5. History lookup ("have we dealt with this?")
grep -i <keyword> <base>/tasks/INDEX.md- No hit? Don't stop — widen the query, not the machinery (query-time, no stored synonym list): generate 4–6 variants of what you're after — the symptom, the business noun, the technical identifier / error string, and EN↔CN — then OR them:
grep -iE 'timeout|超时|429|retry.?storm' <base>/tasks/INDEX.md. Lexical grep only finds words you actually type, so type the synonyms. (This is why wrap-up lines carry aliases in[keywords].) - Also check
sop/index.md,spec/pitfalls.md,docs/decisions/(it may have graduated). - Hit → read that task's summary/progress (never dig through
scratch/). - Not in INDEX ≠ never done (no backfill): fall back to
ls <base>/tasks/ | grep <kw>. - Repo-family search (the default path for cross-project reuse):
./<base>/scripts/seek.sh <kw1> <kw2>— family-scoped by default (walk the ancestor chain, take the topmost.cairnas family root, cover parent + all sub-repos); multiple keywords auto-OR = the query-widening convention. Another repo may have already hit the pitfall you're about to. The surface is mode × scope, orthogonal:- Modes:
(search)·--inflight·--review·--links(pointers + related + symmetry) ·--repos(distance tags + this repo's declarations) - Scope
--scope self|up|pair|family(default family; shorthands--self/--up/--pair):up= self + ancestors (hunting conventions),pair= self + related repos (paired frontend/backend work) - Across families:
CAIRN_ROOTS="<root>" - Rationale:
docs/decisions/001-跨仓协作设计.md
- Modes:
5.5 Repo families (cross-project reuse & dedup)
Root repo + sub-repos = a family. Three rules:
- Look up before you dig:
seek.sh <kw>(family-scoped, nearest-first) — a hit in the parent's or a sibling's SOP/pitfalls is yours to reuse. - One owner per piece of work: cross-repo tasks belong to the parent; the other repo gets a pointer line
[→<repo>/<slug>], never a copy. - Conflicts resolve nearest-wins; a parent's conventions are not blanket-inherited by sub-repos.
🔴 When you touch parent/sibling repos, related-repo registration, cross-repo dedup, or state-type impact: read
cross-repo.mdfirst (scope table / inheritance table / related-repo registration / ENV-LOG rules).
6. Routing table ("where does this go?")
| Content | Destination | git |
| throwaway debug artifacts | tasks/<slug>/scratch/ | ❌ disposable |
| routine task result | dated task summary/progress; remove placeholder at wrap-up | ❌ personal |
| conclusion that changes a future action | summary md + INDEX line | ❌ personal; git add -f to share |
| evidence that an old conclusion helped | consuming task summary/progress: - Reused [slug](path): changed action | ❌ personal; derived on demand |
| progress/next steps | progress.md + 🚧 | ❌ personal |
| repeatable procedure | sop/ + index line | ✅ team |
| a pitfall | spec/pitfalls.md line | ❌ personal; graduate to share |
| detailed conventions (coding standards, domain rules, API contracts) | spec/<topic>.md + one pointer line in AGENTS.md | ✅ team |
| rationale for a major choice | docs/decisions/NNN | ✅ team |
| always-on rules | CLAUDE.md / AGENTS.md (keep <200 lines) | ✅ |
| designs/write-ups | docs/ | ✅ |
Always-on vs on-demand — draw the line hard: rules that MUST hold every session go in CLAUDE.md/AGENTS.md (always injected); <base>/spec/ and SOPs are the on-demand layer. Don't demote a must-follow rule to the on-demand layer expecting the agent to grep for it — measured compliance drops from ~100% (always-on) to ~53% (retrieval-dependent), because agents often never issue the lookup.
7. Bootstrap & recovery — on-demand appendix
Two situations that don't happen often; their details live in setup-and-recovery.md (kept out of the every-trigger SKILL body to save tokens). When you hit one, read that appendix first:
- Install / bootstrap cairn ("install cairn", "set up work-trail conventions"): fast path is
./install.sh <repo>(idempotent, never overwrites); the appendix has the two follow-up steps, the 🔴 append-only settings merge, and the manual fallback. - Troubleshooting cairn (mktmp / INDEX / guard not firing / dashboard noise / a committed personal-layer file / broken settings merge — the if-fail table) — all in the appendix.
8. Hard rules
- Zero throwaway files at repo root;
scratch/and >1MB data files never in git. - Personal layer not committed by default; sharing must be explicit
git add -f, never bulk. - INDEX lines: ≤120 chars, conclusions not logs, 2–4
[keywords], newest on top; doctor errors above 400 chars — if it won't fit, it belongs in a classifiedprogress.mdsection, not INDEX; ≤200 entry lines total (doctor enforces — over cap, consolidate, don't raise the cap). - Delta updates only; conclusion lines freeze when written: an INDEX line has two states — mutable
🚧 TBDplaceholder → frozen conclusion with the marker removed (no later session may rewrite it). Continue the lane with a fresh placeholder (new slug and directory); never append to a frozen conclusion line. Correct one by adding a new line and marking the old[stale:MM-DD reason]. Never bulk-rewrite or "tidy up" INDEX / pitfalls in passing. Consolidation happens only in the review ritual, as a human-approved diff; without freezing, the line-length gate merely caps the same repeatedly edited line. - Expired lines get marked
[stale:MM-DD reason], not deleted — keep the archaeology; actual deletion is a review-ritual decision. - No backfilling old empty task dirs; no half-finished migrations.
- No standalone state pointer files, ever.
- Stale = fix on sight (SOP steps, 🚧 markers). Pitfall countermeasure changed → edit the original line in place (
rev:MM-DD), don't append a duplicate. - The only mandatory wrap-up action is the INDEX line (or the gate's "no"); everything else is judgment.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

