The facts your specs are allowed to cite
A knowledge corpus is a small, committed set of domain facts — plain markdown, versioned in your repo — that a spec can cite. With one in reach, a decision that used to rest on the model's memory (ASSUMED) becomes a grounded, edition-pinned claim you can audit. It's a convention first — a folder shape, an identity scheme, a citation grammar — and spectastic is its reference implementation.
Corpus explorer
A working model of the real thing: a registry of committed facts, and a resolver that decides whether a citation is grounded, stale, or ungrounded. Pick a reference from the registry, choose an edition, and watch the resolver run — the same three outcomes spectastic validate enforces.
| KB-NNNN | Plugin | Slug | Title | Edition | Status |
|---|
The US equities settlement cycle really shortened from T+2 to T+1 on 28 May 2024 (SEC Rule 15c6-1). The corpus retains the prior edition under references/superseded/ — so a citation pinned to the old rule still resolves, and flags as stale rather than silently rotting. Click an edition to resolve against it.
An illustrative model of the real resolver and grounding gates (specs 052–053). It mirrors the shipped settlement example's corpus; the authoritative check is spectastic validate.
What it is
In plain terms — no infrastructure.
Committed markdown, not a database. A pack is a folder — a SKILL.md plus a references/ directory of documents, each carrying provenance frontmatter. It lives in your repo next to the specs it grounds. There is no vector database, no embedding step, and no server to run: the codebase is the index.
It's an Agent Skill. The pack format is a plain Agent Skills folder — the same portable convention agents already understand. Any skills-compatible agent can read it; spectastic just adds the identity registry, citations, and gates on top.
Every fact has an address. A root registry — knowledge/index.md — hands each reference a project-unique id (KB-NNNN) and pins its current edition. A spec cites KB-NNNN@edition; the resolver turns that token back into a document. Full anatomy →
Why it matters
A domain fact your spec needs — the settlement cycle, the accessibility floor, the tax rule — has two possible states. Without a corpus, it can only ever be assumed: taken from the model's memory, plausible, unattributed, and wrong often enough to matter. With a corpus, it can be verified: pinned to a document you committed on purpose.
The answer is confident and uncited. It reads fine in review — the tell isn't a typo, it's a number that's quietly, defensibly wrong. A settlement date off by a day; a WCAG floor set to the AAA figure. Nothing flags it.
The claim points at a committed edition. Validation resolves it, checks it isn't stale, and renders green. The citation isn't decoration — it's evidence: a reviewer, an auditor, or a future you can follow it to the source.
The stakes aren't hypothetical. Grounding research on financial hallucination (FinGround) reports models getting 81% of curated SEC-filing questions wrong or refused, and grounding against curated documents cutting hallucination 70–90%. A corpus is that curated document, committed and cited.
The corpus never invents a citation. A model can hallucinate a fact; it cannot hallucinate a KB-NNNN@edition that resolves — the id has to exist in a registry it didn't write. So the failure mode flips from "confidently wrong and unattributed" to "unresolvable, and it says so." That's the whole point: not that grounding makes the model right, but that it makes ungroundedness visible.
What it doesn't do
A corpus grounds domain facts — externally-true things about the world your software lives in. It does not justify product decisions, architecture choices, or preferences; those belong in a spec decision, argued on their merits. The discipline is deliberate: a corpus asked to justify everything justifies nothing. Keep it to the facts a reasonable expert would agree are simply true, and the green badge keeps meaning something.
- US equities settle T+1 as of 28 May 2024.
- WCAG 2.2 SC 2.5.8 sets a 24×24px target minimum at AA.
- CLS settles FX payment-versus-payment.
- We'll compute ABOR eagerly, not on read.
- We picked a Rust engine over TypeScript.
- Snapshots are cached for five minutes.
The rest of the docs
This page is the overview. Focused pages carry the detail, and the shipped worked examples put it to work end-to-end.
Pack layout, the two-layer identity model, the root registry, reference frontmatter, editions, licensing.
The KB-NNNN@edition grammar, the resolver, the grounding states, and the three validation gates.
Your first pack in five minutes — write from scratch, adapt an existing KB, supersede an edition, publish.
The corpus command group, and how the lifecycle verbs consume the corpus to ground their work.