Documentation

This repository once had no way to detect when its Markdown went stale. Before the September 2026 cleanup, several documents described a layout that no longer existed, and each documentation app stated that it did not publish the content it published.

Keep only the documents that answer a distinct question. Name one owner for each question, and write claims that a check can verify.

Two documentation systems

Published. The documentation site renders these, and readers reach them in a browser:

The Concourse site publishes docs/concourse/** at /docs/.... apps/docs.concourse/lib/source.ts defines this source. Development pages live under docs/concourse/development/. The Applications and Packages pages link to workspace READMEs on GitHub. The site does not publish repository or workspace README content. The Tredis site publishes docs/tredis/**.

Published PRDs own requirements and stories. Published ADRs own significant decisions and rationale. The Planning / Development Process defines their lifecycle and relationship to GitHub Issues.

Every workspace needs a README.md that explains how to work in that workspace. Keep its description and GitHub link in the Applications or Packages directory page.

Agent-facing. No site renders these. They are read in the repository, by people and by agents:

One question, one document

Start here lists which page answers which question. If a question has two answers, one document is wrong. Delete the weaker one and link to the other. Do not restate a rule in two places. Every duplicate is a future contradiction.

Write claims a check can verify

This is the rule that prevents the drift above.

Link, do not restate. Point at the file that owns the truth. A reader can then check it, and a link checker can prove the target exists.

Name the source of any number. A count, a version, or a list changes. When a document must state one, name the file that owns it, so a reader knows where to confirm. The Rackspace documentation once stated a registry of two databases while packages/rsdb/lib/runtime/registry.generated.ts held five. If the sentence names that file, one command shows the gap.

Describe behavior, not line counts. A document that says a file is 400 lines is stale on the next commit. Say what the file is responsible for.

Do not paste another project's text. docs/agents/triage-labels.md once carried a column headed "Label in mattpocock/skills" and an instruction telling the reader to edit it. Adapt vendored material or link to it. Do not commit it half-edited.

Keep a document current or delete it

Delete temporary implementation plans after the work is complete. Git retains their history. Keep PRDs and ADRs that describe the current software. Move a useful earlier choice into a short history note, then delete the obsolete record and repair links. The repository once kept a docs/archive/ directory for superseded pages. Its links rotted, and its file names collided with the live pages.

When you change code, fix the documents that describe it in the same change. A separate documentation pass never happens.

How this is checked

All of these run in tests/scripts/docs-contract.test.ts, through pnpm test:root and CI.

Two exclusions are deliberate and recorded in that file. Vendored skills under .agents/ belong to other repositories. .codex/ holds Codex tool configuration, which is not documentation.

Each check asserts a minimum number of items inspected. Without that minimum, a scanner that matches nothing passes forever.