Team Repository Standards Kit

A versioned, opinionated set of documentation standards and templates that any repository on the team can adopt. The kit's goal is to keep documentation lean, durable, and useful for both humans and AI-assisted development workflows.

• Distributed as: the repo-standards-kit package on PyPI — a zero-dependency standards CLI.
• Authoritative spec: docs/STANDARDS.md
• Agent contract: AGENTS.md
• Version history: CHANGELOG.md

Installation

The kit installs as a command-line tool. Use whichever installer you prefer:

pipx install repo-standards-kit     # recommended (isolated install)
# or
uvx repo-standards-kit standards --version   # run without installing
# or
pip install repo-standards-kit

This puts a standards command on your PATH. Verify it:

standards --version

The runtime is stdlib-only (Python 3.9+) — no third-party dependencies.

Quickstart

# Adopt the kit into a NEW or empty repo (greenfield):
standards init --profile library .

# Adopt into an EXISTING repo (non-destructive — keeps your files,
# writes <file>.kit-<version> sidecars on conflict):
standards adopt --profile application .

# Verify a repo against the standards (use in CI):
standards check .

# Pull in a newer kit version later (non-destructive reconcile):
standards update .

# Diagnose adoption health and optional next lanes:
standards doctor --recommend .

# Scaffold a paired Claude/Copilot AI skill:
standards new-skill review-docs "Review docs before shipping"

# See the public command list:
standards commands

# Print the standard AI session context brief:
python scripts/session-context/session_context.py

# Capture a compact pre-compaction checkpoint:
python scripts/update-handoff/update_handoff.py --compact-snapshot --force

Pick the profile that fits the repo: application | library | infra | data | documentation. Each profile has its own Required / Expected / Optional / N/A doc matrix — see docs/STANDARDS.md.

• init is for blank/clean repos; it refuses if kit-owned files already exist with different content (it points you at adopt).
• adopt is for repos that already have their own README, docs, or CI; it never clobbers — it keeps your files, sidecars true conflicts, and appends/splices the kit's managed block into an existing AGENTS.md.
• Both seed missing README.md and CHANGELOG.md starter files, but preserve existing ones.
• Both write a .standards-kit.json marker so standards update can keep you current.

What this kit gives you

1. A standard folder layout that scales across repo types.
2. Five repo profiles (application, library, infra, data, documentation) with explicit Required / Expected / Optional / N/A doc requirements.
3. A defined contract for the ai/ directory — four files that carry session-to-session context.
4. MADR 3.0 ADRs with a defined lifecycle.
5. RFCs for time-boxed technical investigations (separate from raw discovery intake).
6. Lightweight conventions for docs/discovery/ — keep stakeholder, research, and reconnaissance notes as normal tracked markdown.
7. A PR template that asks the right questions about documentation, ADRs, AI context, and operational impact.
8. A STANDARDS-CHECKLIST.md with a waiver mechanism so absences are explicit, not silent.
9. A CI check (standards check) that enforces the structural minimum plus content-level lints.
10. AI Skills + hooks (Claude Code + Copilot) for ADRs, RFCs, handoffs, changelog reminders, and running the check.
11. A read-only adoption doctor (standards doctor) for marker health, check findings, sidecar conflicts, managed-region drift, and optional lane recommendations.
12. Optional knowledge-lane templates for discovery notes, meetings, artifact indexes, design notes, incidents, troubleshooting, and guides.
13. Optional AI continuity commands for session context, compact snapshots, standard handoff refreshes, and changelog updates.

The information flow

docs/discovery/    →    docs/rfcs/        →    docs/decisions/    →    docs/0X-*.md
(early context)         (investigated)          (decided)               (synthesized & durable)
notes, reqs,            time-boxed,             MADR 3.0 ADRs,          PRD, architecture,
use cases               spawn-or-abandon        immutable               runbook, etc.

Adopting without the CLI

If you'd rather adopt by hand (or want the full detail of what the CLI does), the manual process is documented in docs/STANDARDS.md: copy docs/templates/, pick a profile, fill in docs/STANDARDS.md + docs/STANDARDS-CHECKLIST.md, seed missing README.md and CHANGELOG.md, seed ai/*.md from docs/templates/ai-starters/, adopt the .github/ workflow + PR template, and point your AI tools at AGENTS.md.

For AI-assisted repos, use the agent-readiness checklist in docs/STANDARDS.md to confirm the agent contract, handoff files, skill pairs, and standards check are in a trustworthy state.

Discovery artifacts are pointer-first: use markdown indexes that link to external files by default. Commit raw binaries only when the local repo has an explicit policy such as Git LFS, release assets, object storage, or another deliberate storage mechanism.

Documentation philosophy

Keep documentation lean but scalable. Add durable docs when they improve onboarding, implementation, review, operations, traceability, or decision quality. Do not create documents only because a structure exists — that's why the kit uses Required / Expected / Optional rather than a single rigid required-doc list.

Roadmap

All six foundational slices are shipped and the kit is released through v1.1.0. The living roadmap — the active milestone and what's planned next — and the full shipped-slice history now live in docs/05-implementation-plan.md. Design rationale is captured as ADRs under docs/decisions/ and investigations under docs/rfcs/.