Cairn

Cairn

Cairn routes software development work to the lightest workflow that still protects correctness. It is not card-only and it is not a spec ceremony. It is a decision loop.

Brownfield is the default posture whenever a repo exists: inspect the current system, reuse patterns, and fit changes into the owner boundary. Greenfield work is supported when it is development work in or for a repo/workspace, but it starts in discovery or tracked-change when the wrong scaffold would be costly.

A SessionStart bootstrap routes work here before you respond — you do not need to be invoked by name. Manual override: invoke the cairn skill / /cairn.

Quick Start

1. Observe. Identify cwd, repo root, owner boundary, relevant instructions,

existing docs/specs, code paths, and available proof commands. In multi-repo workspaces, inspect the owner boundary before mutation (see references/workspace.md).

1. Classify. Pick exactly one mode from the table below.
2. Act. Produce only the artifacts justified by that mode.
3. Verify. Run proof proportional to risk.
4. Close. Report outcome, proof, residual risk, and next action.

Modes

| Mode | Use when | Artifact | | --- | --- | --- | | direct | small clear reversible change with obvious target; not broad greenfield/scaffold | none unless useful | | diagnose | concrete failure, bug, flake, slowness | repro notes and proof | | discovery | ambiguous idea, research, greenfield/scaffold, product/domain/architecture uncertainty | brief or decision note | | delta-spec | medium brownfield behavior change | delta, plan, tasks, proof | | tracked-change | multi-phase, high-risk, cross-boundary, customer-visible | durable change folder |

If unsure between two modes, choose the lower ceremony mode unless auth, data, money, production, public/customer impact, or multi-repo coordination is involved. When the user explicitly asks to plan before coding, or asks for a new module/tool/feature from scratch with unclear boundaries, choose discovery or delta-spec, not direct.

Mode Details

Read these references only when needed:

• references/modes.md for detailed mode selection and workflow steps.
• references/artifacts.md for artifact templates and retention rules.
• references/workflow.md for start/middle/close discipline.
• references/research.md for the brainstorm / web-research / docs-grounding stages.
• references/review.md for the proportional review ladder (self-review to adversarial).
• references/memory.md for the .cairn/ state layout and the resume protocol.
• references/workspace.md for the umbrella model, boundary detection, branches & worktrees.
• references/gates.md for what is deterministically enforced vs advisory, and reconciliation.
• references/framework-lessons.md for what Cairn borrows and avoids.

Required Behavior

• Brownfield first: inspect the current system before proposing architecture.
• Not card-only: route rough ideas, no-card tasks, greenfield-in-repo, research, cleanup,

implementation, SDD/spec work, and repo-pattern alignment through the same proportional mode ladder.

• Read-only repo questions are not development work by themselves: explaining a file,

summarizing a card, listing a script, or opening a file without implementation, planning, diagnosis, or investigation should skip Cairn.

• Evidence first: do not invent IDs, dates, owners, card facts, API behavior, or runtime status.
• Reuse before inventing: search existing symbols, helpers, docs, specs, and local patterns

before adding a new path. If you do not reuse the obvious owner, name why.

• Do not expand scope silently. If a side-idea appears mid-work, triage with the user: do now,

enqueue in .cairn/queue.md, replace priority, or drop.

• Non-trivial work starts with workflow preflight and closes with review, proof, lifecycle, and

analysis; see references/workflow.md.

• Research first when external truth can change the plan. Brainstorm, web research, and

official-docs grounding are first-class but intent-gated (see references/research.md): skip them on small clear work; ground new libs on the lockfile version, not the newest.

• Use subagents only for isolated research or adversarial review — never to parallelize coding.
• Ask only when a wrong assumption changes path, risk, owner, cost, public effect, or outcome.
• Do not create PRD/spec/plan artifacts for small direct work.
• Do not implement before discovery when the request is vague and the wrong thing could be built.
• Do not impose TDD universally. Use tests proportional to risk and local patterns.
• delta-spec/tracked-change: scaffold via cairn-scaffold.mjs before mutating; tick

tasks.md live, never back-fill. No folder first = not that mode.

• Resume: on existing .cairn/changes//, read tasks.md + decision-log.md tail first.
• Before saying done, provide fresh proof and run cairn-close.mjs on any change

folder.

• A PreToolUse guard blocks writes outside the active repo; do not work around it without

confirming the target repo is intended.

Output Shape

Every Cairn-routed response must start with Mode: .

For small work, close with Done/Blocked, Proof, Risk, and Next when useful. For planning, include Why, Facts, Open questions, Plan, and Proof strategy. For incomplete work, name the blocker and the next concrete action.

Output Style

Concise per Principle 8 (token economy) — caveman-full for agent output. Never compress safety warnings, irreversible confirmations, public artifacts, or any number/ID/date/path.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tavaresgmg
• Source: tavaresgmg/cairn
• License: MIT

Install and usage instructions live in the source repository linked above.