cairn

cairn

A verification substrate for AI coding agents. Cairn is a small Go binary that gives AI agents durable memory, append-only verdicts, content-addressed evidence, and safe concurrency — the things they need to actually finish work without you re-checking every claim.

Pair it with Superpowers to get methodology + verification end-to-end. Use it standalone if you just want a trustworthy log of what your agents did.

Status: Ship 3 merged (2026-04-19). Plugin scaffold + three skills + REQ-002 (spec init and spec validate envelope) shipped. Ship 4 is the first real-world dogfood.

The problem

AI coding agents fail in four predictable ways:

1. Context loss. Each session starts cold. Yesterday's decision is forgotten.
2. No validation. "Tests passed" is a claim. Nothing checks it.
3. No safe parallelism. Two agents claim the same task, step on each other.
4. No iteration loop. A task marked "done" against a spec that has since been edited is silently stale.

Methodology layers like Superpowers encode discipline as skills, hooks, and subagent roles. Discipline is good — but discipline alone is stateless. When an agent reports "done," nothing verifies it. When a rubric is checked, the verdict isn't recorded anywhere durable. When a spec changes, nothing notices the prior verdict is now lying.

Cairn is the missing layer. With cairn, agents can claim before working, verify before completing, and surface drift between what was promised and what is actually true.

Quick start (5 minutes to your first verdict)

Install the CLI

# Requires Go 1.25+ and git
go install github.com/ProductOfAmerica/cairn/cmd/cairn@latest

Or via a package manager:

# Windows (scoop)
scoop bucket add cairn https://github.com/ProductOfAmerica/scoop-cairn
scoop install cairn

# Windows (winget) — once PR microsoft/winget-pkgs#362607 merges
winget install ProductOfAmerica.cairn

Initialize state + install skills

cd your-repo/
cairn setup           # state bootstrap + installs Claude Code skills

cairn setup does two things:

1. State bootstrap. Same as cairn init — creates the state DB and content-addressed blob store outside git at $CAIRN_HOME/<repo-id>/ (defaults: ~/.local/share/cairn/ on Linux, ~/.cairn/ on macOS, %USERPROFILE%\.cairn\ on Windows). Repo identity is keyed off git rev-parse --git-common-dir so worktrees share state.
2. Writes cairn's Claude Code skills to <repo>/.claude/skills/ — Claude Code auto-loads skills under that path without requiring a /plugin install step. Restart Claude Code (or start a new session) and using-cairn, subagent-driven-development-with-verdicts, and verdict-backed-verification are available.

Re-run cairn setup safely: state is idempotent, and skill files are skipped if already present. Pass --force after upgrading cairn to refresh the skill files.

If you only want the state substrate and intend to register the plugin globally instead, use cairn init (state only, no skill writes). Other agentic harnesses (Cursor, Codex, Gemini, Copilot, OpenCode) drive the CLI directly today; skill-layer wraps for them are tracked in docs/PLAN.md (Ship 5+).

Scaffold spec templates

cairn spec init
# Creates specs/requirements/REQ-001.yaml.example
#         specs/tasks/TASK-001.yaml.example

Write a requirement

specs/requirements/REQ-001.yaml:

id: REQ-001
title: Login is fast
why: p95 login is 800ms
scope_in: [auth/login, auth/session]
scope_out: [auth/signup]
gates:
  - id: AC-001
    kind: test
    producer:
      kind: executable
      config:
        command: [go, test, ./auth/login/...]
        pass_on_exit_code: 0

specs/tasks/TASK-001.yaml:

id: TASK-001
implements: [REQ-001]
depends_on: []
required_gates: [AC-001]

Run the loop

cairn spec validate           # schema + referential checks
cairn task plan               # materializes specs into state DB
cairn task list               # TASK-001 is now "open"

# Claim with a 30-min lease
cairn task claim TASK-001 --agent me --ttl 30m

# Run the gate, capture output
go test ./auth/login/... > /tmp/gate.out 2>&1

# Store evidence (content-addressed, deduped)
cairn evidence put /tmp/gate.out

# Bind a verdict to that evidence
cairn verdict report --gate AC-001 --run <run_id> --status pass \
  --evidence /tmp/gate.out \
  --producer-hash <hash> --inputs-hash <hash>

# Complete the task (cairn refuses if any gate is stale or failing)
cairn task complete <claim_id>

# Audit everything that happened
cairn events since 0

Every mutation emits an event in the same transaction. cairn events since <ts> is the single source of truth for "what happened when."

With Superpowers (the full workflow)

Cairn ships as a Claude Code plugin. After installing both plugins, agents follow this loop: