cairn

name	cairn
description	Routes software development work in or around a repo/workspace to the lightest safe workflow that still protects correctness. ALWAYS invoke for build, change, fix, refactor, plan, investigate, research, cleanup, reduce complexity, align with repo patterns, spec, implement, greenfield-in-repo work, or any card/issue/ticket/link/screenshot/bug/rough idea (pt-BR: implementar, criar, corrigir, refatorar, ajustar, planejar, pesquisar, investigar, limpar, reduzir complexidade, analisar). Skip pure/read-only Q&A, explain/summarize/list/open-only requests, one-off shell commands, or tasks owned by a more specific active skill.
when_to_use	Fire when the user says (en): build/change/fix/refactor/plan/research/investigate this; implement this card/issue/ticket; here's a bug/link/screenshot; brainstorm before coding; write a spec; clean this up; reduce complexity; align this with repo patterns; create a new module/tool/feature in this repo; work this repo/workspace. (pt-BR): "implementa/cria/corrige/refatora/ajusta isso"; "esse card/bug/ticket"; "investiga/analisa esse problema"; "pesquisa"; "planeja antes de codar"; "cria spec"; "limpa/reduz complexidade"; "alinha com o padrao do repo"; "trabalha nesse repo". Do NOT fire for: pure/read-only Q&A, explain/summarize/list/open-only requests, card summaries with no implementation/planning, one-off shell commands, or work owned by a more specific active skill.

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).
2. Classify. Pick exactly one mode from the table below.
3. Act. Produce only the artifacts justified by that mode.
4. Verify. Run proof proportional to risk.
5. 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 <mode> <slug> before mutating; tick tasks.md live, never back-fill. No folder first = not that mode.
• Resume: on existing .cairn/changes/<slug>/, read tasks.md + decision-log.md tail first.
• Before saying done, provide fresh proof and run cairn-close.mjs <change-folder> 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: <direct|diagnose|discovery|delta-spec|tracked-change>.

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.