Your agent found a spec.
It was never a promise.

Docs folders lie to agents. This system makes every file say what it is — and a blocking check makes sure it keeps telling the truth.

Install the gateRead the source

The trap every docs folder sets by default

A docs tree collects three kinds of files: things you built, things youpromised, and things you merely collected — competitor notes, vendor docs, old ideas. To an agent grepping the tree, all three look identical.

invoices.mdalready built?invoices.mdpromised?invoices.mda competitor's?agentbuilds this one
Three files. Same name, same confident prose. Nothing on any of them says which one is real.

The repo this was built for had 301 files. 208 were competitor notes. Nothing marked them. That is not messy — that is a machine for building the wrong thing.

Move 1 — shelve files by trust, not by topic

trustproduct/what we promised to buildengineering/how this repo works todayplans/work in flightreference/borrowed ideas — never build from herearchive/replaced — kept, not believed
Folders answer one question: how much weight should a reader give this file? Moving a file up a shelf is one git mv.

Move 2 — every file wears a badge

---title: Recurring Invoiceskind: referencestatus: referenceupdated: 2026-05-29---NOT A PROMISEstatus: reference
Like the label on a medicine bottle: the pills all look alike — the label is what keeps you safe. Five statuses, machine-readable, checked on every push.

Move 3 — one map instead of a blind grep

before · grepafter · one file readagent"yes, here's the spec" (wrong)agentindex.json"kind: reference — not built,not promised. skipping."
“Is feature X built?” stops being a treasure hunt. One generated map, cheap enough to read whole, with every file's badge in it.

And a gate that keeps it true

status: active ✓stamped ✓badge ≠ shelfcheck-docs9 assertions✓ badge present✓ badge = shelf✓ links alive✓ map fresh✓ no duplicates…exit 1 — fix it firstmain
Structure nobody checks is a suggestion. The gate blocks the push until the tree tells the truth again — and it only ever fires on a real defect.

What it looks like from the terminal:

$ npx ai-doc-system check
docs/reference/crm/pipelines.md:status — is "active" but everything
  under docs/reference/ is status: reference
check-docs FAILED — 1 violation(s).

$ npx ai-doc-system check   # after the fix
check-docs: OK

Deliberately not checked: document age, prose style, dates versus git. Those go to a non-blocking advisory report — a gate that cries wolf gets bypassed.

Ideas earn their way to shipped

reference/an ideaproduct/a promiseplans/being builtshippedpoints at codegit mv+ rewrite foryour productbuild it
Borrowed ideas stay quarantined until someone promotes them on purpose — and rewrites them to describe your product, not the place they came from.

It eats its own cooking

The gate runs on its own repository, in CI, on every push. On its first self-hosted run it caught a dead pointer in one of its own comments.

Install it, then stop thinking about it

As an agent skill — the full treatment

Your agent surveys the tree, proposes the moves, stamps every badge, and wires the gate in. The skill encodes the judgement calls, not just the mechanics.

# in Claude Code:
> /plugin marketplace add magnifito/ai-doc-system
> /plugin install ai-doc-system@magnifito
# then, in your repository:
> set up the documentation system in this repo

From npm — just the tooling

$ npm install -D @puralex/ai-doc-system
$ npx ai-doc-system init       # fresh tree, gate-clean
$ npx ai-doc-system gen        # the map
$ npx ai-doc-system check      # the gate
$ npx ai-doc-system advisory   # drift report