# Cairn

> 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, refato…

- **Type:** Skill
- **Install:** `agentstack add skill-tavaresgmg-cairn-cairn`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tavaresgmg](https://agentstack.voostack.com/s/tavaresgmg)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tavaresgmg](https://github.com/tavaresgmg)
- **Source:** https://github.com/tavaresgmg/cairn/tree/main/plugins/cairn/skills/cairn

## Install

```sh
agentstack add skill-tavaresgmg-cairn-cairn
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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  ` 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](https://github.com/tavaresgmg)
- **Source:** [tavaresgmg/cairn](https://github.com/tavaresgmg/cairn)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tavaresgmg-cairn-cairn
- Seller: https://agentstack.voostack.com/s/tavaresgmg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.