Why it exists
Documentation meant for a coding agent is usually described in prose rules that nothing verifies. docs-bootstrap is the same idea with checks that can fail. Four layers linked by ids, and a fifth above them that says why:
[ Research — why the architecture is this one; verified vs hypothesis ] optional
│
[ Feature — what the system does and why, + BDD scenarios ]
│
[ Client screen or flow — states, actions, navigation ]
│
[ API endpoint — the complete route reference, auth tiers ]
│
[ Service — ownership, dependencies, deploy, quirks ]
Every document carries paths into the code, so a reader — human or agent — gets from a claim to the source in one hop. Nothing in a document duplicates what lives in the code, because a copy is wrong within a sprint and a path is not.
The two rules
maindescribes what exists. An open pull request describes what will be.
A designed but unshipped feature is status: draft and lives in an open pull request; a draft that reaches the default branch is an error.
What was verified is separated from what was assumed, explicitly.
Every status code, error string and limit is read out of the source before it is written down, and a claim that was not verified says so. A document that does not distinguish the two reads as equally authoritative either way.
What the checks do
| Script | Guards |
|---|---|
docs_check.py |
the link graph across the layers, required fields, the status vocabulary, at least one path into the code |
coverage_map.py |
the map in docs/README.md matches the files on disk |
backlog_index.py |
the generated backlog index matches the items; no duplicate numbers; blocked_by resolves |
code_anchors.py |
whether the paths still exist, and whether a member written Type.member is still declared where its type is |
bdd_report.py |
how many scenarios there are, and how many are automated |
What they deliberately do not do: enforce the template's section structure, confuse an empty list with a forgotten one, or block on code anchors by default — an anchor breaks because of a refactor in someone else's repository, and a person reads that report.
The example is the specification you can run
example/ is a small library lending system — a research document, three services, three features, two screens, two endpoint references, six backlog items — over a real, if tiny, code tree, so every anchor resolves. The repository's own CI runs the checks against it, through the same Makefile and action a documented repository uses. A format that claims to be machine-checkable and does not check itself is asking to be taken on faith.
Install
As a Claude Code plugin — the repository is its own marketplace:
claude plugin marketplace add youndie/docs-bootstrap
claude plugin install docs-bootstrap@docs-bootstrap
Then ask your agent to document a repository. SKILL.md is a markdown file of instructions any agent can follow, and the half that is not the skill — the format contract, the templates and six Python scripts behind make check — works for a team writing the documents by hand.
A documented repository runs the checks from here at a pinned tag, uses: youndie/docs-bootstrap@<tag>, rather than as copies; the Makefile reads the same line for a local make check. Copied scripts used to be the route, and that is how 18 copies of one script came to exist in three versions.
The format is spec_version: 1: additive changes keep the version, and anything that would make a v1 reader wrong raises it.