Project Standards

Shared standards, schemas, templates, and tooling for documentation, Python projects, CLI documentation, project specifications, and repository-local agent continuity. This repository is the single source of truth: it defines the standards, and other repositories consume immutable packages through unified config/reconciliation, managed or create-only outputs, reusable workflows, repo-local skills, and the project-standards CLI rather than vendoring their own implementations. Copy-adopt bundles remain v5 migration fallback only.

Looking for what's standardised here? See Standards.
Adopting the standards in your own repo? See Consuming the standards.
Adopting or updating with an agent? Copy the agent adoption/update prompt.
Using the CLI? See the complete project-standards usage reference.
Planning a release? See the roadmap.

Repository layout

project-standards/
├── standards/                 # V2 families: mutable index/landing + immutable versions/
│   ├── README.md              #   family and payload anatomy + Catalog 5 index
│   ├── markdown-frontmatter/  #   family index + immutable versioned payloads
│   ├── adr/                   #   family index + immutable versioned payloads
│   ├── python-tooling/        #   family index + immutable versioned payloads
│   ├── markdown-tooling/      #   family index + immutable versioned payloads
│   ├── project-spec/          #   family index + immutable versioned payloads
│   ├── cli-documentation/     #   family index + immutable versioned payloads
│   ├── agent-handoff/         #   family index + immutable versioned payloads
│   ├── github-workflow/       #   family index + immutable versioned payloads
│   ├── project-toolbox/      #   family index + immutable versioned payloads
│   ├── python-coding/         #   reference-only family + immutable versioned payloads
│   └── standard-bundle-authoring/ # internal family + immutable versioned payloads
├── meta/                      # repository policy, including release/versioning
├── src/project_standards/     # CLI/control plane + installed package projections
├── tests/                     # implementation, package, compatibility, and coherence tests
├── scripts/                   # repository gate, release preparation, and helper tools
├── docs/                      # usage, ADRs, maintained specs, and handoff knowledge
└── .github/                   # repository and reusable consumer workflows

Each standard is a V2 family: mutable root metadata and landing pages index immutable versions/<major.minor>/ payloads. This README stays a map; standards/README.md defines the family and payload anatomy.

Standards

The standards this repository defines. Each lives in a family under standards/, with current authority in the exact versioned payload linked below; see the standards index.

Markdown Frontmatter Standard

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/versions/1.15/README.md
Structure: structure.md · Field values: field-values.md
Schema: schemas/markdown-frontmatter.schema.json (JSON Schema Draft 2020-12)
Skill: skills/markdown-frontmatter/ — installed repo-local as byte-identical copies at .agents/skills/markdown-frontmatter for Codex CLI and .claude/skills/markdown-frontmatter for Claude Code.
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 structure guide gives the hard field and controlled-value contract, and the field-values guide explains ownership, lifecycle, tags, aliases, relationships, and repo-local extensions.

ADR Standard

Architecture Decision Records capture significant, hard-to-reverse decisions, using the MADR format on top of the frontmatter profile above.

Standard: standards/adr/versions/1.6/README.md — when to write an ADR, MADR body structure, the MADR→canonical field/status mappings, ID/filename and docs/adr/ conventions, and the supersession and amendment workflows.
Templates: templates/adr.md (full) plus adr-minimal.md, adr-bare.md, and adr-bare-minimal.md.
Example: examples/adr.example.md. · Adopt: adopt.md.

Package 1.6 keeps the sanctioned partial amendment vocabulary introduced in 1.5: reciprocal project.amends / project.amended_by lists, a blockquote amendment note after the title, and an optional ### Amendments subsection. It adds independent opt-in validation that external relationships are reciprocal and that an amends edge does not target a superseded ADR. Supersession remains the all-or-nothing relationship. The new check is off by default, and the relationship fields remain optional.

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.

Python Tooling SSOT Standard

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, CI, and bounded VS Code / agent-instruction contributions. The V5 package composes these surfaces through the unified executor and preserves explicit repository toolchain intent during migration. Package 1.14 includes scoped ruff.extend_per_file_ignores and adds the closed vscode.task_prefix choice for unprefixed or "python: " task labels. Package 1.15 adds runner_labels for the managed Check workflow's runs-on and ruff.enforce_line_length to make the declared line length a gate.

Standard: standards/python-tooling/versions/1.18/README.md
Adopt: adopt.md

Markdown Tooling Standard

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 V5 package manages the two configs plus lint-markdown.yml and format.yml caller/self-hosted workflows while composing only declared units in shared EditorConfig, VS Code, and instruction containers.

Standard: standards/markdown-tooling/versions/1.16/README.md
Adopt: adopt.md

Project Specification Standard

Tiered format (Light ⊂ Standard ⊂ Full), stable canonical numbering, typed IDs, and provider-backed validate/lint/extract/next/new/upgrade commands. The selected package manages a reusable or self-hosted validation workflow; authoring writes are applied only from typed plans through the unified executor.

Standard: standards/project-spec/versions/1.11/README.md
Templates: templates/ · Example: examples/spec.example.md · Adopt: adopt.md

CLI Documentation Standard

User-facing CLI usage documentation — help text, the canonical usage reference, man pages, shell completion, and CI checks that catch drift. A strict profile ladder (Script ⊂ Packaged ⊂ Packaged-deep) scales the requirement to a CLI's distribution shape across Python, Go, and other implementations. The V5 package creates the usage scaffold once and verifies a reviewed consumer-owned workflow rendered by its selected provider.

Standard: standards/cli-documentation/versions/1.6/README.md
Templates: templates/ · Example: examples/usage.example.md · Adopt: adopt.md

Agent Handoff Standard

Repository-local project knowledge and bounded session continuity for coding agents. Agent Handoff creates consumer-owned status, task, and lifetime-routed knowledge under docs/; installs a repo-local agent-handoff skill; optionally registers one shared SessionStart hook for Claude Code and Codex; and validates layout, drift, provenance, document budgets, and credential references without owning workstation-global state.

Standard: standards/agent-handoff/versions/1.17/README.md
Skill: skills/agent-handoff/ — installed repo-local at .agents/skills/agent-handoff/ and .claude/skills/agent-handoff/.
Adopt: adopt.md · Migration: resources/legacy-migration.md

GitHub Workflow Standard

GitHub work discipline for organization-owned repositories: typed issue contracts, field vocabulary, pull-request evidence, review expectations, and an attention-first operator summary. The package installs a mandatory repo-local github-workflow skill that keeps judgment with the agent, plus gh-workflow — a committed, reproducibly built static linux/amd64 Go binary whose ten subcommands audit the organization schema, render operator summaries and creation receipts, apply validated issue mutations, and admit pull requests. Every subcommand reads the consumer's repository and writes none of it: 1.5 removed the ledger subcommand that generated docs/GH-WORKFLOWS.md, and a repository upgrading from 1.4 or earlier deletes that now-unowned file itself. The organization schema itself is skill-audited and human-applied; the tool never creates or retires an issue type, field, or value.

Standard: standards/github-workflow/versions/1.10/README.md
Skill: skills/github-workflow/ — installed repo-local at .agents/skills/github-workflow/ and .claude/skills/github-workflow/, with the tool at bin/gh-workflow.
Adopt: adopt.md

Project Toolbox Standard

The durable home for proven cross-cutting repository workflows — assets that fit no existing standard, or that span two or more of them. Version 1.0 installs two managed checklist documents, a periodic repository-housekeeping sweep and a claim-versus-reality drift-detection sweep, plus a routing project-toolbox skill that points an agent at the right one. It ships no executable providers: the documents find work, and every fix they prompt is an ordinary reviewed change. The package requires no other standards package, but both sweeps read .standards/config.toml and fold each installed package's own gates into the work instead of duplicating them.

Standard: standards/project-toolbox/versions/1.1/README.md
Skill: skills/project-toolbox/ — installed repo-local at .agents/skills/project-toolbox/ and .claude/skills/project-toolbox/.
Workflows: workflows/ — installed at .standards/packages/project-toolbox/workflows/.
Adopt: adopt.md

Python Coding Standard (draft)

Code-shape and agent-behavior rules for Python — the reference companion to Python Tooling. In-development package 0.6: reference-only and not consumer-selectable.

Standard: standards/python-coding/versions/0.6/README.md

Standard Bundle Authoring Standard (internal/reference)

The "standard for standards" — the V2 family/payload/catalog contract every package declares: immutable releases, option schemas, channels, relationships, resources, providers, migrations, semantic ownership, and integrity. Internal package 2.7: its family availability and catalog role are internal, so it governs this repository and is not consumer-selectable.

Standard: standards/standard-bundle-authoring/versions/2.7/README.md

Consuming the standards

Project Standards 5.29.0 requires Python 3.14 or newer. Install the exact release from its immutable Git tag, then verify the installed command before changing a repository:

uv tool install --force "git+https://github.com/L3DigitalNet/project-standards@v5.29.0"
project-standards --version || project-standards --version

The version command must report project-standards 5.29.0. The first probe immediately after a forced install can fail transiently while the freshly installed environment finishes import wiring; retry once before treating a failure as real. The Git tag is the supported install path; GitHub release assets are convenience copies for browsing, not a supported install source, and carry no rebuild or byte-verify guarantee on every release (see the release runbook for the periodic checks that do cover them). V5 consumers use one catalog/config/lock plane. Initialization is neutral and enables no package:

project-standards init --catalog 5
project-standards standards enable markdown-frontmatter --version 1.15
project-standards reconcile
project-standards reconcile --apply

Commit .standards/config.toml, .standards/catalog.toml, .standards/lock.toml, and reconciled outputs together. The package selector chooses an immutable payload; package options such as contract_version remain independent. Each versioned adoption guide defines the package-specific options, outputs, migration, verification, and troubleshooting.

To restore one missing or changed, exclusively managed whole file, preview the exact lock-backed restore before applying it:

project-standards reconcile --restore-managed path/to/file
project-standards reconcile --restore-managed path/to/file --apply

The path must be one exact repo-relative, non-glob path with exclusive whole-file ownership and matching lock authority. The preview is read-only and reports only structural evidence (owner, digests or absent, action, and the exact apply command); apply never creates parent directories, and a noop writes nothing. This restore path is separate from incomplete-state recovery.

Adopting or updating with an agent? Copy the agent adoption/update prompt and tick the packages you want, or take the everything-selected variant. It routes fresh adoption, V5 updates, and V4 migration; requires preview-before-apply and preservation checks; and requires sanitized upstream issue reports for irregularities.

Current consumer packages

Package	Current payload	Adoption guide
Markdown Frontmatter	`1.15`	`standards/markdown-frontmatter/versions/1.15/adopt.md`
ADR	`1.6`	`standards/adr/versions/1.6/adopt.md`
Python Tooling	`1.18`	`standards/python-tooling/versions/1.18/adopt.md`
Markdown Tooling	`1.16`	`standards/markdown-tooling/versions/1.16/adopt.md`
Project Specification	`1.11`	`standards/project-spec/versions/1.11/adopt.md`
CLI Documentation	`1.6`	`standards/cli-documentation/versions/1.6/adopt.md`
Agent Handoff	`1.17`	`standards/agent-handoff/versions/1.17/adopt.md`
GitHub Workflow	`1.10`	`standards/github-workflow/versions/1.10/adopt.md`
Project Toolbox	`1.1`	`standards/project-toolbox/versions/1.1/adopt.md`

For a V4 repository, do not create .standards/ separately. Preview the complete migration, resolve every ambiguity, then apply the same command explicitly:

project-standards init --catalog 5 --migrate
project-standards init --catalog 5 --migrate --apply

The migration removes .project-standards.yml only after unified validation and lock publication. During v5, legacy-only validation remains a warned read-only fallback; v6 removes it.

Pin to a release tag, not `main`

Reference reusable workflows by major tag (@v5), never @main. For an immutable pin, use a full version (@v5.12.0) or a commit SHA. UPGRADING.md is the v4-to-v5 migration runbook.

Reusable workflow inputs

Workflow	Input	Type	Default	Notes
`lint-markdown.yml`	`markdownlint`	boolean	`true`	Set `false` to skip the job.
`lint-markdown.yml`	`globs`	string	`*/.md`	Newline-delimited Markdown globs.
`lint-markdown.yml`	`config`	string	empty	An empty value auto-discovers the caller's `.markdownlint.json`.
`format.yml`	`prettier`	boolean	`true`	Set `false` to skip the job.
`format.yml`	`globs`	string	`.`	Newline-delimited paths or globs.
`format.yml`	`exclusions`	string	empty	Newline-delimited Prettier ignore patterns.
`validate-markdown-frontmatter.yml`	`standards-ref`	string	`v5`	Git ref to install from this repository.
`validate-specs.yml`	`standards-ref`	string	`v5`	Git ref to install from this repository.
`validate-specs.yml`	`strict-lint`	boolean	`true`	Set `false` to skip strict specification linting.

For either validation workflow, set standards-ref to the same ref used after @ in jobs.<job>.uses; a full-version or SHA pin must be repeated exactly.

jobs:
  lint-markdown:
    uses: L3DigitalNet/project-standards/.github/workflows/lint-markdown.yml@v5
    with:
      config: .markdownlint.json
  format:
    uses: L3DigitalNet/project-standards/.github/workflows/format.yml@v5
    with:
      exclusions: |
        generated/**
  validate-frontmatter:
    uses: L3DigitalNet/project-standards/.github/workflows/validate-markdown-frontmatter.yml@v5
    with:
      standards-ref: v5
  validate-specs:
    uses: L3DigitalNet/project-standards/.github/workflows/validate-specs.yml@v5
    with:
      standards-ref: v5
      strict-lint: true

For private standards repos called by private consumers, enable cross-repository access under this repo's Actions settings.

Pre-commit hooks

.pre-commit-hooks.yaml exposes the standalone frontmatter tools as pre-commit hooks: format-frontmatter-fix / format-frontmatter-check, validate-id-fix / validate-id-check, validate-frontmatter, and validate-references. The per-file hooks receive only staged Markdown; validate-references sets pass_filenames: false because cross-file reference checking needs the whole repository.

repos:
  - repo: https://github.com/L3DigitalNet/project-standards
    rev: v5.29.0 # pre-commit requires an immutable rev — use a full release tag, not a moving major
    hooks:
      - id: format-frontmatter-check
      - id: validate-id-check
      - id: validate-frontmatter

MCP server

project-standards mcp serves the installed Catalog 5 standards to a local MCP client over stdio, read-only. It is optional and replaces nothing: the CLI and the CI workflows remain the enforcement backstop.

See docs/mcp-server.md for prerequisites, per-client stdio configuration, the capability matrix, the resource and tool reference, security rules, equivalent commands, and troubleshooting.

Versioning

Releases use Semantic Versioning syntax with a catalog-composition classifier. The owner designates a matching tool and catalog MAJOR. Otherwise, introducing a package or advertising a version above that package's prior maximum requires exactly MINOR; a release without either requires exactly PATCH. Advertised package versions remain permanent.

See meta/versioning.md for the complete classification and release requirements.

Developing this repository

Repository CI is enumerated in tests/README.md § CI relationship — the developer gate, the coherence gate, the standards-graph gate, and the dogfood caller, plus the reusable consumer workflows. Working on the standards or the validator itself, set up with one command:

scripts/bootstrap-worktree.sh                # ~10s: sync, npm ci, projection check, build, extract, stamp, go tools
export PYTHONPATH="$PWD/build/wheel-runtime"

Rerun it after any change under src/** or to a payload under standards/** — the gate refuses a stale runtime. The steps it performs, should you need one individually:

uv sync --all-groups --locked                                # Python environment
npm ci                                                       # Prettier and markdownlint oracles
uv run project-standards standards sync-payload-projection --root . --check --json # must pass before the build
uv build --clear --wheel --out-dir build/release-wheel
rm -rf -- build/wheel-runtime
uv run python -m zipfile -e build/release-wheel/project_standards-5.29.0-py3-none-any.whl build/wheel-runtime
scripts/wheel-runtime-stamp.sh write         # records what the extraction was built from

Then run the gate:

scripts/verify.sh                    # fast gate: statics, ordinary suite, and compatibility as concurrent lanes
scripts/verify.sh --full             # same lanes, run one at a time (release prep and the last content change of a train)
uv run project-standards validate    # dogfood: schema, id, and references

# Go gate. Install pinned repository-local tools once per checkout.
make go-tools
make go-check

The fast Python gate is the everyday verification; --full runs the same lane selections one at a time (ordinary suite included, still at -n 16) after a train's last content change and at release preparation, where it cross-checks the parallel configuration against the baseline it was proven against, and stops at the first red lane by default (--fail-fast; pass --keep-going to run every lane regardless). The independent Go gate runs locally and in path-filtered CI when Go-owned files change. The release path uses build/release-wheel with --clear and replaces only the generated runtime extraction, so no stale wheel can satisfy the candidate-runtime gate. Require sync-payload-projection --check before uv build: the projection is what puts the catalog and payload bytes inside the distribution, and a wheel built without it serves validate but fails init/reconcile with CP-INIT-STATE.

The release runbook is the durable procedure for cutting a release from this checkout: every gate layer, its commands, its exit evidence, and its rollback.

License

This project is licensed under the Apache License 2.0.

Name		Name	Last commit message	Last commit date
.agents		.agents
.claude		.claude
.codex		.codex
.github/workflows		.github/workflows
.standards		.standards
.vscode		.vscode
catalogs		catalogs
cmd		cmd
docs		docs
internal		internal
meta		meta
scripts		scripts
src/project_standards		src/project_standards
standards		standards
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.markdownlint-cli2.jsonc		.markdownlint-cli2.jsonc
.markdownlint.json		.markdownlint.json
.pre-commit-hooks.yaml		.pre-commit-hooks.yaml
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
.python-version		.python-version
.rexec.toml		.rexec.toml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
ROADMAP.md		ROADMAP.md
UPGRADING.md		UPGRADING.md
go.mod		go.mod
go.sum		go.sum
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Uh oh!

Repository files navigation

Project Standards

Table of Contents

Repository layout

Standards

Markdown Frontmatter Standard

ADR Standard

Python Tooling SSOT Standard

Markdown Tooling Standard

Project Specification Standard

CLI Documentation Standard

Agent Handoff Standard

GitHub Workflow Standard

Project Toolbox Standard

Python Coding Standard (draft)

Standard Bundle Authoring Standard (internal/reference)

Consuming the standards

Current consumer packages

Pin to a release tag, not `main`

Reusable workflow inputs

Pre-commit hooks

MCP server

Versioning

Developing this repository

License

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Project Standards

Table of Contents

Repository layout

Standards

Markdown Frontmatter Standard

ADR Standard

Python Tooling SSOT Standard

Markdown Tooling Standard

Project Specification Standard

CLI Documentation Standard

Agent Handoff Standard

GitHub Workflow Standard

Project Toolbox Standard

Python Coding Standard (draft)

Standard Bundle Authoring Standard (internal/reference)

Consuming the standards

Current consumer packages

Pin to a release tag, not main

Reusable workflow inputs

Pre-commit hooks

MCP server

Versioning

Developing this repository

License

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Pin to a release tag, not `main`