cairn

cairn

A cairn is built one stone at a time, and marks the trail for whoever comes next.

A Claude Code plugin for milestone-driven development: a governed LLM Wiki for project state — the agent maintains it, you gate it. One canonical workflow — planning, implementation, review, hotfixes, releases, and expert escalation — with all project state in plain markdown under cairn/, kept honest by weight caps and a self-auditing health check. The core is language-agnostic; each repo declares a toolchain profile (R, Python, Docker image, or generic) that supplies its language-specific commands. Work lands as small stacked milestones, and any session — today's or next month's — can find the path from the files alone.

Born from maintaining many R packages with Claude Code and rebuilding similar-but-diverging tracking systems in each. This plugin centralizes the logic (skills, rules, templates) so every repo works identically; each repo holds only its own state.

Release history lives in CHANGELOG.md; design rationale in cairn/DESIGN.md and the append-only decision log it points to.

Install

Two paths; pick one — running both installs the plugin twice and the duplicates will confuse skill routing.

Dev install (recommended): clone and symlink into your skills directory. The plugin loads from your checkout, so git pull updates it with no re-install step:

git clone https://github.com/jmgirard/cairn
ln -s /path/to/cairn ~/.claude/skills/cairn

Footgun to respect: live means live — whatever branch the checkout has is what loads at your next session start, in every repo, including the enforcement hooks. Keep the checkout on main unless you're developing cairn itself. For a one-off trial without installing anything, use claude --plugin-dir /path/to/cairn (that session only).

Marketplace install: a frozen snapshot; re-install to pick up new releases. In Claude Desktop: Customize → Plugins. From the CLI:

claude plugin marketplace add jmgirard/cairn
claude plugin install cairn@cairn

Either way, the install includes the guardrail hooks: the blocking ones (merge approval, a force-push guard on your default branch), the housekeeping ones (session-start tracking re-injection, the uncommitted-tracking stop guard), and the advisory nudges — when an idea gets captured somewhere other than the roadmap, when something durable is headed for Claude's memory instead of your tracking files, and when a commit on your default branch reaches outside cairn/ — none of which block anything you're doing. They activate at the next session start and are no-ops in repos that aren't cairn-tracked.

Then, in your package repo, run /cairn-init. Fresh repos get scaffolding; repos with an older tracking system get an interactive, PR-based migration. Run /milestone any time you're unsure where things stand.

The core loop

Development is a cycle of milestones — PR-sized units of work with explicit acceptance criteria. You steer at defined gates; Claude works autonomously between them:

idea → /milestone-plan → /milestone-implement → /milestone-review → merged
        (scope gate)      (choices gate)         (approval gate)

You rarely type the next command: each phase ends with clickable options (chips) that route to the natural next step. Typing the slash command directly always works too, e.g. to resume after a break.

A worked example

Say your repo is a small CLI tool and you want a --dry-run flag.

1. Plan it. You say: "plan a milestone: add a --dry-run flag to the sync command." Claude reads the roadmap, decisions, and the relevant code, then asks one short batch of scoping questions, each with a recommendation — should --dry-run cover sync only or every mutating subcommand? is printing the would-be actions enough, or must exit codes match a real run? You click answers (or type your own). Claude writes cairn/milestones/M07-dry-run-flag.md — goal, in/out scope, verifiable acceptance criteria, ordered tasks — registers it in the ROADMAP as planned, commits, and offers a chip: Start implementing M07.

2. Build it. /milestone-implement M07 cuts a branch, asks any implementation choices the plan left open (flag naming, output format), then works the tasks in order: tests first, one checkpoint commit per task, each commit updating the milestone file's checkboxes alongside the code. Between the gate and the finish you aren't asked anything. When all tasks pass, status flips to review and you get a diff summary and a chip: Proceed to review.