cairn: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

A plugin (cairn) for Claude Code, Antigravity, and Codex that brings a milestone's important questions up to be decided before work starts, so execution can then be handed to agents. It ships as a set of skills, a few agents, shared procedures, and the stdlib-only Python tools under tools/ (among them the open-question tool and the task-list tool, the only writers of each milestone's open-question document and of its two task files once they are created, and the fold tool through which the answer sweep records its decisions in requirements.md) that move a project from a vague idea through discussion, planning, completion, and archival — one milestone at a time.

Commands

uv run scripts/build_hosts.py                           # rebuild hosts/ from core/ after any change under core/ or scripts/hosts/
uv run scripts/build_hosts.py --check                   # drift gate: fails if the committed hosts/ trees differ from a fresh build
uv run pytest                                           # Python tool suite under the pinned interpreter (.python-version)
uv run --no-project --python 3.9 --with pytest pytest   # the same suite at the 3.9 floor; run both before committing a tool change
uv run pytest agy_tests                                 # on-demand suite driving the installed agy against ~/.gemini/config/plugins/cairn; run before committing an Antigravity integration change
uv run scripts/set_version.py X.Y.Z                     # bump VERSION and its three mirrors; releases go through /release-plugin instead

Repository layout

Each entry names the file that documents itself; read that file rather than expecting the detail here.

AGENTS.md                        — symlink to CLAUDE.md; never edited directly
VERSION                          — bare MAJOR.MINOR.PATCH, the single source of truth; written by set_version.py, read by build_hosts.py
.claude-plugin/marketplace.json  — the maintainer's directory marketplace pointing at ./hosts/claude; users install from the distribution repos
core/                            — the host-neutral runtime layer (skills/, agents/, shared/, tools/); cross-references use {{PLUGIN_ROOT}}, no file names a host
core/skills/<name>/SKILL.md      — one skill per directory
core/agents/*.md                 — the two dispatched subagents (complete-task, provide-alternatives-to-open-question)
core/shared/*.md                 — the shared procedures, each the single source of truth for one unit of work referenced by two or more runners
core/tools/open_questions.py     — the stdlib-only (Python 3.9+) open-question tool; run `--help` for its subcommands and contract
core/tools/define_milestone.py   — the stdlib-only (Python 3.9+) milestone-definition tool: numbers and slugs a new milestone, creates its directory with the four files (the empty open_questions.xml included), prints the commit subject and directory
core/tools/task_list.py          — the stdlib-only (Python 3.9+) task-list tool, the only writer of TASKS_TODO.md and TASKS_DONE.md once created; run `--help` for its subcommands and contract
core/tools/requirements.py       — the stdlib-only (Python 3.9+) fold tool: `fold` splices one decision under a named `###` subsection of requirements.md's `## Decisions` and `replace` rewrites the body of one existing subsection, called by the answer sweep only and not that file's sole writer; run `--help` for its subcommands and contract
scripts/hosts/<host>/            — one declarative host definition per host: settings.toml, a slots/ subdirectory holding one value file per wording slot, and that host's manifest, README, CONTRIBUTING pointer, and traffic-workflow templates
scripts/build_hosts.py           — the one generic host build and validation gate (see its docstring and CONTRIBUTING.md ## Development)
scripts/set_version.py           — writes VERSION and its three mirrors (marketplace.json, pyproject.toml, uv.lock) in lockstep; touches no git
tests/                           — pytest suite of the tools under core/tools/, one flat test_<name>.py per subcommand or concern, golden fixtures under tests/fixtures/, plus test_build_rendering.py, the build's in-process rendering test, which runs under the pinned interpreter only, and the two fixed-call tests (test_sweep_compact_view.py, test_sweep_batched_call.py), which extract the answer sweep's two shell calls from the rendered Claude Code tree, each as the one fence holding a command only it carries (the batched call's conflict section likewise, from the one fence holding `replace`) with nothing added to the runtime file, and run them under bash, under both interpreters
agy_tests/                       — on-demand suite driving the real agy CLI against the global Antigravity copy, outside testpaths and CI, seeded from tests/fixtures/agy_project/; see CONTRIBUTING.md ## Development
hosts/<host>/                    — committed build output, never hand-edited; published verbatim into uHappyLogic/cairn-<host> at release
.claude/skills/release-plugin/   — maintainer-only release skill, outside core/ so no host renders it
milestones/                      — this repo's own milestones (self-dogfooding); milestones/README.md holds the Current milestone: pointer
milestones/answer_decision_principles.md — project-wide principle store read by recommend-procedure.md, written only by capture-milestone-principle-updates
ideas/                           — design drafts that precede any milestone, versioned so they can be revised in the open; holds the benchmark draft
.github/workflows/drift-gate.yml — CI: --check then both pytest runs in one job; actions pinned to SHAs bumped by hand
.github/workflows/traffic-badges.yml — daily traffic-badge workflow; its copies under scripts/hosts/ are kept in sync by hand (grep github-traffic-badge@)
docs/                            — workflow.md (phase narrative, how skills commit, learning loop), skill-reference.md (one entry per skill), design-claims.md, ways-of-using-cairn.md (headless chains)
README.md, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, CHANGELOG.md, LICENSE — landing page, contributor guide (## Development is the build loop), root-only policy files, release notes written by /release-plugin