Quickstart: empty repo to a validated, merged document.
This walkthrough uses docassert, the reference implementation. Everything is Git, Markdown, and GitHub Actions, with no other tools.
Time to complete: ~20 minutes. Requires: git, Python 3.10+, a terminal, and a GitHub repo.
Prefer to let Claude do it? See Quickstart with Claude Code →
Starting a fresh repo? The template pre-wires steps 1–2 and 8.
Get docassert.
Install it from PyPI. It validates documents, checks cross-document consistency, generates the traceability matrix, and derives per-project status.
pipx install docassert # or: pip install docassertdocassert --version# AI advisory extra: pipx install "docassert[ai]"
Anchor a project.
Everything is organized by project. A project.md anchor gives it a unique id (PRJ-001-AUR), a code that namespaces every document and item, and, optionally, a profile that declares the documents it should carry.
---kind: projectid: PRJ-001-AUR # PRJ-<seq>-<CODE>, unique across all projectscode: AUR # namespaces ids: AUR-charter, AUR-BR-001name: Aurora — Customer Onboarding Overhaulsponsor: jordan.leestatus: active # proposed | active | on-hold | closedprofile: regulated-industry # optional: the expected document set---## Overview## Scope
docassert new project --code AUR --name "Aurora — Customer Onboarding Overhaul"# docassert: created documents/PRJ-001-AUR/project.md # id auto-numbereddocassert projects --out projects.yaml # generate the registry from the anchors# docassert: wrote projects.yaml (1 project)
proposed while you fill it in, so its profile gaps stay advisory, and flip it to active when you want missing required documents to block.Unit-test it.
Structural checks are deterministic and block a merge; AI checks (with a key) advise. The output below is abridged from a real run.
docassert validate documents/PRJ-001-AUR/charter.md documents/PRJ-001-AUR/charter.md ✓ frontmatter-schema: valid against the schema ✓ required-sections: all 6 present and non-empty ✓ measurable-success-criteria: all 3 state a measurable threshold ✓ risks-have-owner-and-mitigation: all risks name an owner + mitigation ✓ dates-consistent: created 2026-01-15 → target 2026-12-15 ✓ unique-id: id 'AUR-charter' is unique○ objective-is-specific: advisory (needs ANTHROPIC_API_KEY)✓ All structural checks passed — clear to merge.
measurable-success-criteria blocks and cites the exact criterion that failed. Completeness checks like this stay advisory while a document is a draft and begin to gate once it is proposed, so work in progress is never punished.Check consistency across documents.
This is where the model pays off. Requirements trace end to end, the registry stays fresh, and each profiled project carries its required documents. Broken links block; the AI judges whether each child fulfils its parent.
docassert consistency consistency (cross-document) ✓ item-id-uniqueness: all 24 item IDs are unique ✓ referential-integrity: all references resolve ✓ required-links: all required upstream links present ✓ coverage: all approved items are covered ✓ profile-completeness: 3 project(s) with advisory gaps (not enforced yet)# AI advisory, e.g.:● AUR-PR-015 —traces→ AUR-BR-002 score 0.40"progress emails don't obviously reduce support tickets"
Generate the traceability matrix.
The matrix is derived from the links on every change, so it is always current and nobody maintains it.
docassert rtm --project PRJ-001-AUR# Requirements Traceability Matrix — AUR | Business Req | Product Req | Func/NFR | Acceptance | Test | |--------------|-------------|-----------|------------|------------| | AUR-BR-001 | AUR-PR-014 | AUR-FR-101| AUR-AC-001 | AUR-TC-001 | | AUR-BR-002 | AUR-PR-015 | AUR-NFR-05| AUR-AC-002 | AUR-TC-002 |Derive status and see what's missing.
Status is derived, never typed. Scope it to one project, roll up the portfolio, or build the whole site. Because Aurora is on a profile, its page also shows which required documents are complete, incomplete, or missing.
docassert status --project PRJ-001-AUR # one project's RAG + document setdocassert status --index # the portfolio tabledocassert pages --out _site # index.html + a page per project# Projects — AMBER | Project | Code | RAG | Docs | Required | Open risks | |------------------------|------|-------|------|----------|------------| | Aurora — Onboarding | AUR | AMBER | 20 | 9/9 | 2 | | Atlas — Partner Portal | ATL | AMBER | 5 | 0/4 | 0 |
Gate it in CI and make it binding.
Two jobs run on every pull request, but GitHub only blocks a merge when branch protection requires them. That setting is what turns advisory checks into a real gate.
on: [pull_request]jobs:audit: # validate each changed documentsteps: - { uses: actions/checkout@v4, with: { fetch-depth: 0 } } - uses: c4g-john/docassert-action@v1with: { command: validate, changed-only: 'true' }consistency: # the graph + registry + profile completenesssteps: - { uses: actions/checkout@v4 } - uses: c4g-john/docassert-action@v1with: { command: consistency }
# make both checks required before a PR can mergegh api -X PUT repos/OWNER/REPO/branches/main/protection --input - <<'JSON' { "required_status_checks": { "strict": true, "contexts": ["audit", "consistency"] } } JSON
audit and consistency on main (above). Without it, the checks run but never block.· GitHub Pages: Settings → Pages → Source: GitHub Actions, so status-pages.yml can publish the live dashboard. It is one-time and manual.
· AI advisory (optional): add
ANTHROPIC_API_KEY as an Actions secret. Structural checks gate without it; this just adds the AI scoring.Let Claude Code scaffold the whole thing from one prompt, convert an existing Word document, or explore the document kinds in the reference.