Project Cairn
Turn validated project lessons into reusable knowledge, so your AI agents stop re-learning the same pitfalls in every new session and project.
Per-dimension scores and reasoning
Evidence shows a documentation-first skill: no background hooks, human confirmation required before writing to the long-term knowledge base, read-only preflight scripts (obsidian/notion/lark-preflight) before any write, citation pointers in Cited.md, and provenance fields (graduated_from etc.), scoring 2 for least privilege, confirmation, data flow, external effects, and attribution. Deducted: credential/token handling is not described in visible files; no documented rollback/undo for graduation writes; dependency security limited to a PyYAML mention with no pinning or advisory notes.
Docs are internally consistent (file-responsibility table matches described flow), and prerequisites plus preflight scripts support dependency availability (2 each). The test file shows error messages carrying file path, line, column, and fix hints (e.g., YAML escape suggesting single quotes) and aggregate reporting of all invalid files — failure messages earn 3.
Audience and scenarios are clearly stated (multi-project, cross Claude Code/Codex/WorkBuddy, teams needing durable knowledge) — 3. 'Automation boundaries' delimits capability, and triggering relies on AGENTS.md rules with a documented init phrase — 2 each. Environment fit covers macOS/Linux verification and Windows WSL, but Python version and shell compatibility are one-line remarks, so 2.
Information architecture is strong: docs map, file-responsibility table, and the two-lifecycle split — 3. Install notes cover three hosts plus structural requirements — 3. MIT license text present — 3. Deducted: only one walkthrough example (messaging-bot), no FAQ; known limitations are scattered (no package-manager release, Windows caveat); no CHANGELOG or version scheme; maintainer identity unverified with no governance/update commitment — those score 1.
Outputs are structured Markdown/YAML notes readable by humans and machines — 2. The graduation-plus-search-first-citation mechanism is clearly differentiated from agent memory and superpowers — 2. Cost profile is light (no background service, files generated on demand), but no measured evidence of benefit — 2.
Graduated notes trace people/project/source via frontmatter — 2. Claims like 'verified on macOS and Linux' and self-described verified knowledge-base paths cannot be confirmed in this static review and lack third-party corroboration — 1. Fact/inference separation is decent: explicit non-claims (not full OKF) and audit-reports-does-not-rewrite — 2.
- How credentials (Notion/Lark tokens) are stored and passed is not described in the visible files; review authentication handling in the scripts before connecting a knowledge-base provider.
- No documented rollback exists for knowledge-base graduation writes; back up the target knowledge base before confirming scope.
- Publisher is unverified; manually review SKILL.md, references/, and scripts/ after cloning before trusting the skill.
- No version numbers or changelog; diff repository changes yourself before upgrading.
- All 'verified' claims come from the repository itself; this is a static review and no execution was performed.
What does this agent do, and when should you use it?
Project Cairn (iBlinkQ/project-cairn) is an AI-agent skill for Claude Code, Codex, and WorkBuddy that persists lessons, decisions, and conclusions from project collaboration inside the project itself. It injects rules through a root-level AGENTS.md file, and the agent maintains cairn/LOG.md, cairn/ROADMAP.md, and per-topic notes during normal work turns. When a conclusion proves reusable across projects, the agent proposes a graduation candidate, and only after human confirmation is it written to a long-term knowledge base with verified paths for Obsidian, Notion, and Lark/Feishu. Later projects search the knowledge base first and record a pointer in cairn/Cited.md when a note actually shapes their work, rather than duplicating content. There is no background hook and no after-chat execution — every read and write boundary is explicit.
During initialization, the agent writes AGENTS.md, .cairn/config.yaml, and the cairn/ directory structure based on the project summary, git policy, and migration choice you provide. During ordinary work, the agent follows AGENTS.md to record progress in cairn/LOG.md (reverse-chronological), keep the overall goal and plan in cairn/ROADMAP.md, and maintain the current conclusion per subject in cairn/<topic>.md, archiving external source material in cairn/Reference/. Topic notes use Markdown with YAML frontmatter including at least a type field (a minimal Open Knowledge Format convention), and graduated notes carry provenance via graduated_from, contributors, graduated_by, and authoring_mode. Graduation uses scripts under scripts/, including read-only preflight checks (obsidian-preflight.sh, notion-preflight.sh, lark-preflight.sh) and notion-graduate-batch.py (which requires PyYAML); each provider follows the behavioral contract in references/provider-interface.md with execution paths under references/graduation/. On reuse, the agent searches the knowledge base and writes a pointer in cairn/Cited.md only when a result is actually used.
- A developer running several AI-collaboration projects who wants pitfalls validated in one project to carry into the next.
- A user switching between Claude Code and Codex who wants project rules and conclusions to live with the project, not with a particular agent session.
- A small team where turnover means project knowledge must survive in the repository rather than one person's memory.
- A power user of Obsidian, Notion, or a Lark/Feishu wiki who wants to periodically distill project experience into that knowledge hub.
- A researcher or engineer about to close an exploration branch who wants to salvage useful conclusions before the branch ends.
What are this agent's strengths and limitations?
- Two-sided lifecycle design: the project side (rules, progress, current conclusions) is separate from the knowledge-base side (cross-project distillations), avoiding one ever-growing catch-all file.
- Graduation requires human confirmation, and read-only preflight scripts (obsidian/notion/lark-preflight.sh) run before any write, making write boundaries explicit and controllable.
- Graduated notes carry full provenance (graduated_from, contributors, graduated_by, authoring_mode), so conclusions trace back to the people, project, and source material behind them.
- Three verified graduation paths (Obsidian, Notion, Lark/Feishu), each keeping the platform's native link and index model; reuse happens through Cited.md pointers rather than duplication.
- Documentation-first and signal-driven: beyond the core initialization files, documents appear only when a real signal calls for them — no directory of empty templates.
- No package-manager release; installation is git clone or a manual ZIP download, and upgrades are on you.
- Shell scripts are verified only on macOS and Linux; Windows users must rely on WSL or Git Bash.
- Graduation paths cover only Obsidian, Notion, and Lark/Feishu — users of other knowledge bases have no ready-made execution path.
- There is no background hook, so routine maintenance depends entirely on the agent following AGENTS.md during work turns; if it drifts, contradictions and omissions surface only through the audit process.
- Python scripts carry extra dependencies (Python 3, PyYAML for notion-graduate-batch.py), and some automation lives in standalone scripts the user must set up themselves.
How do you install or deploy this agent?
Prerequisites: git, plus bash for scripts/*.sh (verified on macOS and Linux; Windows users need WSL or Git Bash). Python scripts require Python 3; notion-graduate-batch.py additionally requires PyYAML. Claude Code, user-level: git clone https://github.com/iBlinkQ/project-cairn.git ~/.claude/skills/project-cairn. Codex, user-level: git clone https://github.com/iBlinkQ/project-cairn.git ~/.agents/skills/project-cairn. WorkBuddy: download the main-branch ZIP, then in the sidebar open Skills → Add Skill → Upload Skill and select the ZIP; WorkBuddy configures it automatically. Other skill-compatible agents: clone the repository into the agent's skill-loading directory, ensuring SKILL.md sits at the root of project-cairn/ with no nested folder. There is no package-manager release yet.
How do you use this agent?
1) Ask the agent to "Initialize Project Cairn in this project." It collects the project summary, git policy, and migration choice, then writes the rules and configuration; connecting a knowledge-base provider can be deferred until the first graduation. 2) Keep working normally — the agent maintains progress and current conclusions during ordinary collaboration turns per AGENTS.md; there is no separate recording service to run. 3) When a validated lesson could help another project, ask the agent to prepare a graduation candidate; nothing is written to the long-term knowledge base until you confirm the scope. Later projects search the knowledge base first and add a pointer to cairn/Cited.md only when a result actually influences the work. The full T0–T8 flow (including roadmap maintenance, audit, and re-graduation) is in the interactive guide at https://iblinkq.github.io/project-cairn/.
How does this agent compare with similar options?
Positioning against adjacent tools: LLM Wiki organizes source material you have read into a wiki, while Cairn focuses on knowledge learned through project work; Open Knowledge Format defines the format, while Cairn handles formation, maintenance, graduation, and reuse; agent memory preserves an agent's preferences and working context, while Cairn preserves project-knowledge continuity; superpowers makes delivery more reliable through specs, plans, tests, and review, while Cairn keeps the stable conclusions learned from that process. The core distinction: an agent remembering something is not the same as a project learning it.