Shared standards, schemas, templates, and tooling for documentation and Python projects across all repositories. This repository is the single source of truth: it defines the standards, and other repositories consume them — the Frontmatter and ADR standards through a small config file plus a reusable CI workflow, the Python Tooling, Markdown Tooling, and CLI Documentation standards by copying their scaffolds (Markdown Tooling adds optional reusable lint and format workflows; CLI Documentation adds a copy-adopted CI drift check), and the Project Specification standard by installing the project-standards package directly (its CLI ships the full spec surface — nothing to copy beyond a spec: config block) — rather than vendoring their own copies.
- Looking for what's standardised here? See Standards.
- Adopting the standards in your own repo? See Consuming the standards.
- Project Standards
project-standards/
├── standards/ # governing standards — one self-contained bundle per standard
│ ├── README.md # index + bundle anatomy
│ ├── markdown-frontmatter/ # standard + adopt + templates/ + examples/
│ ├── adr/ # standard + adopt + templates/ + examples/
│ ├── python-tooling/ # standard + adopt (doc-only)
│ ├── markdown-tooling/ # standard + adopt (doc-only)
│ ├── project-spec/ # standard + adopt + templates/ + examples/ + CLI (spec)
│ ├── cli-documentation/ # standard + adopt + templates/ + examples/ + resources/
│ └── python-coding/ # draft standard (reference-only; README only)
├── meta/ # docs about THIS repo (e.g. versioning) — not governed standards
├── src/project_standards/ # the Python validator + bundled schema
├── tests/ # validator tests
├── scripts/ # optional helper — check.py runs the verification gate
├── docs/ # agent session-handoff state + specs/plans (not consumer-facing)
└── .github/ # reusable CI workflows
Each standard is a self-contained bundle: the deep detail lives in the bundle, and this README stays a map. See standards/README.md for the bundle index and anatomy.
The standards this repository defines. Each lives in its own bundle under standards/ — see the standards index.
A small, portable, tool-neutral set of YAML frontmatter fields for project documentation, giving every Markdown document consistent metadata for discovery, validation, and LLM/human workflows. It is deliberately not an Obsidian, Hugo, Jekyll, Quarto, or Pandoc schema — publishing-tool metadata goes under a publish namespace, never at the top level.
- Standard:
standards/markdown-frontmatter/README.md - Schema:
src/project_standards/schemas/markdown-frontmatter.schema.json(JSON Schema Draft 2020-12) - Templates:
templates/· Examples:examples/· Adopt:adopt.md
The standard defines eleven required fields plus a recommended optional set. Copy a ready-made block from templates/ (frontmatter-minimal.yml or frontmatter-standard.yml); the standard gives the full field definitions and the controlled values for doc_type, status, confidence, visibility, and consumer.
Architecture Decision Records capture significant, hard-to-reverse decisions, using the MADR format on top of the frontmatter profile above.
- Standard:
standards/adr/README.md— when to write an ADR, MADR body structure, the MADR→canonical field/status mappings, ID/filename anddocs/decisions/conventions, and the supersession workflow. - Templates:
templates/adr.md(full) plusadr-minimal.md,adr-bare.md, andadr-bare-minimal.md. - Example:
examples/adr.example.md. · Adopt:adopt.md.
ADRs use doc_type: adr with kebab IDs like adr-0001-repo-name-short-title — the id embeds the repo-name for cross-repo uniqueness, while the filename omits it (adr-0001-short-title.md). ADR-specific roles (decision_makers, consulted, informed) live under the project extension namespace, keeping the universal vocabulary small.
The standard Python stack for agent-authored projects: uv + uv_build, src/ layout, Ruff, basedpyright (strict), pytest + coverage (branch), pip-audit, a one-command verification gate, and the VS Code / agent-instruction conventions. Unlike the Markdown standards it is not validator-enforced and ships no reusable workflow — you adopt it by copying the in-doc scaffolds and running the gate.
- Standard:
standards/python-tooling/README.md - Adopt:
adopt.md
The recommended linting/formatting tools and settings for Markdown and the structured-text files Prettier handles (json/jsonc/yaml): markdownlint for Markdown structure, Prettier for formatting, and EditorConfig as the floor. The tool-specific complement to the tool-neutral Frontmatter standard; markdownlint ships the reusable lint-markdown.yml + a seedable rule set, and Prettier ships the opt-in reusable format.yml alongside its copy-adopt config (since @v4.x).
- Standard:
standards/markdown-tooling/README.md - Adopt:
adopt.md
Tiered format (Light ⊂ Standard ⊂ Full), stable canonical numbering, typed IDs, and a project-standards spec CLI (validate/lint/extract/next/new/upgrade) that operates on a repository's real specs. Unlike the copy-adopt standards, there is nothing to seed into a consumer repo besides a spec: config block — installing project-standards gives the full tool surface directly, and new scaffolds from the package's bundled templates.
- Standard:
standards/project-spec/README.md - Templates:
templates/· Example:examples/spec.example.md· Adopt:adopt.md
User-facing CLI usage documentation — help text, the canonical usage reference, man pages, and the CI checks that catch drift between them. A strict profile ladder (Script ⊂ Packaged ⊂ Packaged-deep) scales the requirement to a CLI's distribution shape, from a single-file script's --help + compact README up to per-command generated pages for large multi-command tools. Copy-adopt like Markdown Tooling: seed docs/usage.md and the cli-docs-check.yml workflow via project-standards adopt cli-documentation.
- Standard:
standards/cli-documentation/README.md - Templates:
templates/· Example:examples/usage.example.md· Adopt:adopt.md
Code-shape and agent-behavior rules for Python — the reference companion to the Python Tooling SSOT (the SSOT standardizes the toolchain; this document standardizes the code the toolchain checks). In-development draft (version 0.4): reference-only, unregistered (no contract version), excluded from frontmatter validation, and not adoptable via the CLI. It ships in the repository for review and early reference until released.
- Standard:
standards/python-coding/README.md
How a repository adopts each standard. The two Markdown frontmatter standards (Frontmatter + ADR) share one mechanism; Python Tooling, Markdown Tooling, Project Specification, and CLI Documentation each adopt on their own. Each bundle's adopt.md is the canonical, step-by-step runbook — this section is the map.
Adopting with an agent? Hand it the relevant
adopt.mdand let it follow the procedure end to end.
Add two files, pinned to a major tag:
.project-standards.ymlat the repo root — declares which Markdown files are managed..github/workflows/validate-standards.yml— calls the reusablevalidate-markdown-frontmatter.yml@v4workflow, withstandards-refpinned to the same major.
ADR enforcement (managed ADR docs, plus the opt-in MADR section check) rides the same workflow — no extra job. Optional Markdown body linting is a separate opt-in workflow (lint-markdown.yml).
- Full runbook (config, workflow, pinning, local validation, body-linting, compliance checklist):
standards/markdown-frontmatter/adopt.md - ADR specifics:
standards/adr/adopt.md
For local tooling, use project-standards fix (formats frontmatter and regenerates ids in one pass), the standalone format-frontmatter command, or the pre-commit hooks (.pre-commit-hooks.yaml) — see src/project_standards/README.md for the full CLI reference.
No config or workflow — copy the in-doc scaffolds and run the verification gate. See standards/python-tooling/adopt.md.
Seed .markdownlint.json + .editorconfig, copy .prettierrc.json, and opt into the reusable lint-markdown.yml@v4 and format.yml@v4 workflows. See standards/markdown-tooling/adopt.md.
Availability:
lint-markdown.ymlis available since@v2; the opt-informat.ymlsince@v4.x. The Frontmatter/ADRvalidate-markdown-frontmatter.ymlworkflow is available on any major tag.
Add a spec: block to .project-standards.yml declaring which files are project specs, then optionally call the reusable validate-specs.yml@v4 workflow (same pinning rules as the Markdown standards). Available from v4.0.0 onward — no earlier tag carries the standard or its workflow. See standards/project-spec/adopt.md for the full procedure, the spec CLI reference, and CI wiring.
Copy-adopt like Markdown Tooling: select a profile (Script/Packaged/Packaged-deep), then run project-standards adopt cli-documentation to materialize a docs/usage.md scaffold and the cli-docs-check.yml drift-check workflow, plus a cli_documentation: config fragment to paste into .project-standards.yml. See standards/cli-documentation/adopt.md for profile selection and the full authoring/review checklist.
Reference reusable workflows by major tag (@v4), never @main: a repo that passed validation yesterday must not fail today because the standard changed. Breaking changes ship only as a new major (@v5); @v4 receives bug fixes and backward-compatible updates. For an immutable pin, use a full version (@v4.0.0) or a commit SHA. The adopt guides explain the full rationale, and UPGRADING.md is the step-by-step runbook for moving an existing repo across a major (e.g. @v3 → @v4).
For private standards repos called by private consumers, enable cross-repository access under this repo's Actions settings.
Releases follow Semantic Versioning, but the contract is the consuming repo's validation outcome — a release's level reflects the worst-case impact of any change across the standard, schema, validator, and workflow.
- PATCH / MINOR → safe to inherit on a moving major pin (
@v4); a repo that passed yesterday still passes today. - MAJOR → may newly-fail a previously-passing repo (a new required field, a stricter rule, even a validator bug fix); old
vN.xtags stay intact, and consumers migrate intentionally.
See meta/versioning.md for the full classification table, the previously-passing rule, and release requirements.
Working on the standards or the validator itself:
uv sync --dev # set up the environment
uv run ruff format --check . && uv run ruff check . && uv run basedpyright && uv run coverage run -m pytest && uv run coverage report && uv run pip-audit
uv run project-standards validate --config .project-standards.yml # dogfood: schema, id, and referencesThis project is licensed under the Apache License 2.0.