cairn: Command for Claude Code

Run a Cairn Vibe Session: the attended, director-style cousin of /cairn-loop. The human is the director whose hands are off the keyboard, driving worker CLI sessions (a fast low-latency model for mechanical work, a good strong model for judgment) and verifying their output by reading. Never take a worker's word: open the touched files and confirm the change meets the success criterion.

Whereas /cairn-loop is autonomous and works one unit at a time, /cairn-vibe picks a release-sized themed block of work, gets the maintainer's approval of the direction and the release plan together up front, then executes the whole arc hands-off, landing each unit as an independently-reviewed PR, and finishes by releasing per the pre-approved plan.

Input: the argument after /cairn-vibe is an optional theme hint, area, or direction (e.g. /cairn-vibe webui findings). With no argument, derive a theme from live graph state (cairn status, its open-todo list, cairn next, and per-node cairn todos <node>). cairn frontier is an optional secondary signal for ghost-node / architecture pressure only; it is not the todo source.

Setup

Cairn must reflect current source. Do all director build and query work in a dedicated director worktree, never the main checkout. Running cairn scan or a build in the main checkout rewrites the tracked, committed map.json snapshot and dirties it. Create the worktree first. Each tool call is independent: the cwd and environment do not carry across calls. A lone cd or export PATH does not affect the next call, so bind every director command to its concrete path in the same call.

Pick and record a unique concrete director worktree path, never a fixed shared name. This example uses /tmp/cairn-director-1699999999; substitute a unique suffix and reuse that exact literal in every Setup/Orient command and at teardown.

(<main-checkout> is the path to your primary clone, e.g. the repo root; substitute the real path in every command.)

git -C <main-checkout> fetch origin
git -C <main-checkout> worktree add --detach /tmp/cairn-director-1699999999 origin/main
( cd /tmp/cairn-director-1699999999 && cargo build --release )

Use /tmp/cairn-director-1699999999 only for Setup and Orient. Run every Setup/Orient cairn command via /tmp/cairn-director-1699999999/target/release/cairn <args> (or cd /tmp/cairn-director-1699999999 && ./target/release/cairn <args> in each call). Do not rely on an exported PATH, a persisted cwd, or a $DIRECTOR_WT variable across calls.

Roles (RACI)

• Workers: implement the unit, add or extend tests, push the feature branch, and open the unit PR (gh pr create). Mechanical units go to fast; design or judgment units go to good.
• Director: runs Setup and Orient (read-only cairn queries plus the local cargo build --release) in the dedicated director worktree, never the main checkout, and runs a fresh local cargo build --release in each post-merge verification worktree. The director commissions the two reviewer subagents, adjudicates, and squash-merges when CI is green and review is satisfied. For release, the director (directly or via a dedicated release worker) opens the release-prep PR and creates the tag, only after the phase-2 disposition and after confirming no material divergence. The director MUST NOT implement unit or product code.

Steps

Work the six phases in order. Do not advance until a phase's exit criterion is met. Ephemeral in-session phase tracking is fine for this session's own progress. Durable cross-session work items go through cairn todo new <slug> --node <id> and status edits via cairn todo set on the resulting meta/todos/todo.<slug>.md (this repo's native tracker), not bd.

1. Orient - in the dedicated director worktree from Setup, never the main checkout, run /tmp/cairn-director-1699999999/target/release/cairn status, /tmp/cairn-director-1699999999/target/release/cairn change list, /tmp/cairn-director-1699999999/target/release/cairn next, /tmp/cairn-director-1699999999/target/release/cairn lint --json, and (per candidate node) /tmp/cairn-director-1699999999/target/release/cairn todos <node>. Optionally glance at /tmp/cairn-director-1699999999/target/release/cairn frontier as a secondary signal for ghost-node / architecture pressure; do not treat it as a todo backlog. Record the baseline: /tmp/cairn-director-1699999999/target/release/cairn lint has no new findings (the one accepted deferred Info is fine) and exits 0; /tmp/cairn-director-1699999999/target/release/cairn hook all exits 0; and /tmp/cairn-director-1699999999/target/release/cairn scan must be zero findings (run it now if not already clean). Triage any pre-existing scan finding or new lint finding before proposing a block. Name the open unblocked todos and which todos are already blocked on maintainer authorisation or an external dependency. At Orient's end, immediately remove the director worktree: git -C <main-checkout> worktree remove --force /tmp/cairn-director-1699999999. It exists only for Setup and Orient. Exit criterion: if there are no open unblocked todos and no actionable next unit, report the state and stop (do not manufacture work); otherwise proceed to phase 2 with a written backlog snapshot.