The Five Pillars
Every Doc Type Has Exactly One Home
Each pillar is a path contract: a folder shape relative to a repository root. Where a doc goes is decided by what it is — never by who wrote it.
Requirements
docs/requirements/What the system does today. One folder per document, the living body under specs/, statements written with RFC 2119 keywords and Gherkin acceptance scenarios.
Design & ADRs
docs/design/adr/Why the system is the way it is. Architecture Decision Records named ADR-NNN-kebab-title.md — numbered, immutable once accepted, superseded never deleted.
Specs
specs/changes/The change workspace. One folder per non-trivial change — proposal, requirement deltas, tasks. Finished changes fold into the requirements and move to specs/archive/.
Fitness tests
scripts/check_*.shArchitecture decisions enforced as code. Small checks that run in your own CI on every pull request, each citing the decision it enforces.
Component docs
docs/ in every repoLow-level design living beside the code it describes: architecture notes, runbooks, an api.md for the service contract — in each component repository.
What a Conformant Repo Looks Like
The default topology — docs beside the code they describe, so documentation ships in the same pull request as the change:
product-repo/
├── README.md # front door: what it is, how to run it, links into docs/
├── AGENTS.md # entry point for AI coding agents
├── openapi/openapi.yaml # the API contract lives with the service, not under docs/
├── docs/
│ ├── requirements/ # what the system does (living)
│ │ └── Authentication/specs/dual-path-login.md
│ ├── design/adr/ # why it is this way (immutable records)
│ │ └── ADR-007-dual-path-auth.md
│ ├── architecture/ # system prose + C4 context/container diagrams
│ ├── runbooks/ # one failure mode per file, owner + last-reviewed
│ └── api.md # markdown page linking the contract
├── specs/
│ ├── changes/ # in-flight change folders
│ │ └── add-two-factor-auth/ (proposal.md · specs/ · tasks.md)
│ └── archive/ # completed changes, moved wholesale
└── scripts/
├── run_all.sh # runs every check_*.sh in CI
└── check_no_cross_app_imports.shNothing here needs a generator or a CLI. An absent pillar is fine — folders exist when they have content, never as empty scaffolding.
Topology-Invariant
Same Shapes, Any Repo Layout
The pillar shapes never change — only the repository boundary moves. Each pillar binds to whichever repo owns it.
Docs alongside code
The default. All five pillars point at the product repo; docs ship in the same pull request as the change they describe.
Dedicated docs repo
Requirements, design, and specs in a docs-only repo for a single review surface; contracts and component docs stay with the code.
Everything in one repo
A small team or monorepo. Identical to the default — one repo simply plays every role. Nothing structural changes.
Federated, org scale
Each pillar binds to its natural owner: a central decision log, per-component docs, one fitness catalog. The portal aggregates it back into one site.
Key Conventions
Rules That Keep Docs Honest
Records vs. living docs
ADRs and proposals are point-in-time records: once resolved, never silently rewritten — a reversal is a new ADR that supersedes the old one, with links both ways. Requirements, component docs, and runbooks are living: they must always describe the system as it is today.
Testable requirement grammar
Requirements use bold RFC 2119 keywords — MUST, SHOULD, MAY — one capability per statement, with acceptance criteria as Given/When/Then scenarios. Both humans and AI agents can verify a claim written this way.
Changes graduate, then retire
When a change ships, its requirement deltas fold into the living requirements and the change folder moves to specs/archive/. The spec pile never becomes a second, stale copy of the system.
References that survive reorgs
Cross-repo references are logical identifiers — repo#ADR-016, repo#specs/add-sso — not raw GitHub URLs. Move docs between repos and the references still resolve.
Decisions enforced in CI
Every fitness check cites the decision it enforces, so a failing check explains why the rule exists instead of getting deleted. Severities critical and high block the merge; medium and low warn.
Git is the source of truth
The default branch is canonical; portals and rendered sites are derived from it. Wikis and doc silos don’t hold engineering records — they drift, skip review, and are invisible to CI. Diagrams are Mermaid in Markdown, so they render right on GitHub.
Adopt It in 15 Minutes
Day one, one repo, no tools. Everything else arrives when its content arrives — an absent pillar is conformant.
- 1
Write a
README.mdthat orients — what this is, how to run it, links intodocs/— and anAGENTS.mdso AI agents find the structure too. - 2
Record your first decision:
docs/design/adr/ADR-001-record-architecture-decisions.md— the ADR that says you’re keeping ADRs. - 3
Start your next non-trivial change as
specs/changes/<verb-led-slug>/spec.md— problem, requirements, tasks in one file. - 4
If you have an API, commit its contract at
openapi/openapi.yaml. - 5
Backfill nothing. Existing docs stay where they are and migrate incrementally, with redirect stubs when something moves.
Where SystemDox Comes In
The standard is plain git and works without any tool. SystemDox is what makes it self-enforcing: in your workspace’s Repository roles settings you bind each pillar to the repo that hosts it, and SystemDox takes it from there.
Scans and classifies by path — requirements, ADRs, specs, and architecture docs are recognised by where they live and indexed into your knowledge base
Publishes into the convention — documents created in SystemDox land at the standard’s paths, as commits or reviewable PRs
Ships fitness checks to CI — “Publish to CI” opens PRs that install check_*.sh scripts in the governed repo, and check results feed back into the console
Feeds AI agents — the MCP server serves the same pillars as context, so your agents read the requirements and decisions you actually adopted
See Publishing Documentation for how the portal is built, and Checks for the fitness-test workflow.
FAQ
Common Questions
Do I need SystemDox to use the standard?
No. The standard is plain Markdown, folders, and git — every rule can be followed with any editor and enforced by hand or with your own scripts. SystemDox automates the scanning, publishing, enforcement, and AI-context delivery on top of the same layout.
We already have ADRs in a different folder. Do we move them?
No. An existing ADR sequence is grandfathered where it stands — renumbering or moving 30 decision records breaks every inbound link for zero gain. The rule is one ADR directory per repo; new repos start at docs/design/adr/.
We’re a monorepo / we have fifty repos. Which layout applies?
The same one. The pillar shapes are identical in every topology; only the repository boundary moves. A monorepo plays every role itself; a fifty-repo org binds each pillar to its natural owner and lets the portal aggregate. Switching later is moving folders wholesale — nothing inside them changes.
Where do OpenAPI specs go — docs or code?
With the code, always: openapi/openapi.yaml in the service repo, never duplicated into a docs repo. A small docs/api.md page links the contract so it shows up on the docs portal.
Why does this matter more now that AI agents write code?
Agents act on whatever context they find. A predictable layout means an agent (or a new engineer) can always locate the requirements, the decisions, and the in-flight changes before touching code — and testable RFC 2119 requirements give it something it can actually verify against. Unstructured docs read as suggestions; a standard reads as ground truth.