Sagan
Extraordinary claims require extraordinary evidence.
Sagan is a standard for shipping work with AI agents where “done” has to be proven, not claimed. Specialist agents build; independent agents check; nothing ships until the checks ran against real output — and a human makes the final call.
npx skills add https://github.com/thewhatmatters/sagan --skill sagan-wire
Get started
Three steps, one directory.
- Install The command above adds the sagan-wire installer to your Claude Code setup.
- Wire your project Say “wire this project to sagan.” It probes your repo, captures your real test/build commands, and installs a self-contained .sagan/ folder. One directory in; delete it to walk away.
- Run your first ticket Copy the example ticket, write what “done” means, then say /sagan-plan to bring your tickets into the repo and refuse any that don’t say what done means — and /sagan-run to drive the circuit: build, critique, verify, and a promote decision that stays yours. Tickets can live as files in your repo or in Linear.
Already wired? One command keeps your project current: /sagan-wire --update. It asks before changing anything you edited — your edits survive — and running it again is safe. Sagan tells you when the toolkit itself is behind.
--- id: T-000 title: Marketing hero (shadcn primitives) status: Backlog # repo-owned — set by the run, kept across fetches builder_id: frontend-claude-r1 verifier_id: verify-claude-r1 # never the builder evidence_sha: 9be4459 # proof binds here --- <!-- your prompt, verbatim (abridged) --> Build the hero for sagan.run. Headline eight words or fewer, a subhead, one CTA saying “Get started” → /docs. No secondary. Only the shadcn primitives we have installed. One accent, used once. Everything from tokens. … Any one you can’t hit, stop and tell me which and why. <!-- the PM compiled everything below from it; you confirmed at a gate before any work --> ## AC 1. `h1` exact text `Ship work you can prove.` — proposed at the gate, approved; the page’s only h1; ONE CTA `Get started` → /docs. 2. Only installed primitives; tokens only — no new hex, accent exactly once, no load animation. 3. Buttons are buttons; one h1, order in sequence; focus visible; targets ≥ 44px; axe zero critical. 4. Craft, on verify’s captures: accent-stripped still reads premium; nothing fills space; a stranger gets it from headline + subhead. ## Method items: copy · CTA · tokens · a11y lane: quality (cap 3) round-1 evidence: 375/1440 light+dark · accent-off · axe ## Frontend r1 build note — built what, key choices, no self-approval. ## QA r1 verify — per-AC PASS/FAIL, evidence at `9be4459`. ## Decisions 2026-08-08 — promote gate (human): promote. <!-- sagan:repo-owned:end -->
How it works
Every piece of work travels the same circuit:
- Acceptance criteria come first. Before any agent starts, the ticket says exactly what “done” means. You brief in plain words; the PM drafts the criteria and you confirm them. No criteria, no work.
- A builder builds. One specialist agent does the work and hands over the result — it doesn’t grade itself.
- A fresh critic reviews. A separate agent, which never saw the builder’s reasoning, judges the result against the criteria. If judging requires running the thing, it says so and demands proof.
- A verifier runs it. A third agent — never the builder — executes the work: runs the tests, loads the page, takes the screenshots, and records the results against the exact git commit.
- You decide. Approved work reaches you with its proof attached. You promote it or send it back.
A critic answers with one of four words:
APPROVED (verified, not plausible),
REVISE (here’s what’s wrong),
NEEDS_EVIDENCE (run it and show me), or
ESCALATE (a human needs to look at
this). Each verdict is a file the critic writes, checked where it
lands — nobody retypes it.
Tickets from a tracker are mirrored into the repo as files, so every agent reads the same words you wrote — not a version retyped into a prompt along the way. Each agent writes its own file — none can touch another’s — and notes travel back to the tracker word for word.
The rules
Nine rules make it hold:
- Criteria before work. A review without criteria is an opinion.
- An adjective is not a criterion. Quality bars name a reference and are judged blind — “looks great” never ships anything.
- Critics flag, builders fix. Nobody grades their own homework.
- The verifier is never the builder. Separation is structural, not polite.
- Reading is not judging. Claims about how something runs require running it.
- Approved means verified. Sign-off needs proof recorded at a git commit.
- Limits are circuit breakers. When rounds run out, a human is asked — work never quietly ships. Rounds cap the critic’s fix loops, never your changes — redirect the work without tripping a breaker.
- Decisions come to you as questions. Open calls are surfaced as clear options, never buried in a wall of text.
- Personas are hired, contracts rule. Each dispatch hires its persona; no role owns one — the role’s contract always wins.