productofamerica/cairn/using-cairn

What cairn is

Cairn is a verification substrate for AI-coordinated software development. See PLAN.md §"What this is / is not" for the full substrate summary. This skill teaches when to invoke cairn's three wrappers, how YAML specs derive silently from prose, and which spoke to load for specific tasks.

When this skill applies

Three scenarios trigger this skill:

1. YAML lifecycle — Is there a specs/ dir with cairn YAML? YAML derives from prose. Read spoke yaml-authoring.md.
2. Wrap routing — Is the agent executing an implementation plan inside a cairn-tracked claim? Route to the appropriate wrap.
3. Code reviewer dispatch — Is a reviewer agent being dispatched against a rubric gate? Read code-reviewer-pattern.md.

Wrap routing rules

YAML lifecycle

In a cairn-tracked repo, specs/ YAML is always derived from prose. The human never edits YAML directly. Requirements YAML derives from docs/superpowers/specs/*.md (brainstorming output); task YAML derives from docs/superpowers/plans/*.md (writing-plans output). Derivation is deterministic and byte-identical on re-run. See yaml-authoring.md for the full protocol.

Hash placeholders banner

When binding a verdict, producer_hash and inputs_hash use provisional Ship 3 placeholders.

These hashes are placeholders. They do not reflect toolchain version or input state. Verdicts bound with these values are NOT safe to rely on for cross-run drift detection.

See hash-placeholders.md for the recipe and the future-replacement plan.

Invocation rule

This skill MUST be invoked explicitly by the orchestrating session after each of superpowers:brainstorming and superpowers:writing-plans commits. Agent-noticing is unreliable. For harness-enforced belt-and-suspenders drift detection, enable the cairn Stop hook via cairn hook enable. The hook supplements skill discipline; it does not replace it, and it only catches source-hash drift (not skipped verdicts or orphan claims — those are guaranteed by cairn's mutation path itself).

Routing to spokes

Red flags