Metadata-Version: 2.4
Name: repo-standards-kit
Version: 0.16.0
Summary: Team Repository Standards Kit — adopt and stay current with the standards via a single CLI.
Project-URL: Repository, https://github.com/swanson-dev/Repo-Standards-Kit
Author: swanson-dev
License-Expression: MIT
License-File: LICENSE
Keywords: adr,governance,rfc,scaffold,standards
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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`](https://pypi.org/project/repo-standards-kit/) package on PyPI — a zero-dependency `standards` CLI.
- **Authoritative spec:** [`docs/STANDARDS.md`](./docs/STANDARDS.md)
- **Agent contract:** [`AGENTS.md`](./AGENTS.md)
- **Version history:** [`CHANGELOG.md`](./CHANGELOG.md)

## Installation

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

```sh
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:

```sh
standards --version
```

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

## Quickstart

```sh
# 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 .
```

Pick the profile that fits the repo: `application` | `library` | `infra` | `data`. Each profile has its own Required / Expected / Optional / N/A doc matrix — see [`docs/STANDARDS.md`](./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 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. Four **repo profiles** (application, library, infra, data) 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/`** — drop raw stakeholder material (incl. PDFs/JSON) into gitignored intake folders, **capture** it into tracked markdown notes, then promote to durable docs.
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, discovery capture + promotion, handoffs, and running the check.

## The information flow

```
docs/discovery/    →    docs/rfcs/        →    docs/decisions/    →    docs/0X-*.md
(raw intake)            (investigated)          (decided)               (synthesized & durable)
meetings, reqs,         time-boxed,             MADR 3.0 ADRs,          PRD, architecture,
use case drafts         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`](./docs/STANDARDS.md): copy `docs/templates/`, pick a profile, fill in `docs/STANDARDS.md` + `docs/STANDARDS-CHECKLIST.md`, seed `ai/*.md` from `docs/templates/ai-starters/`, adopt the `.github/` workflow + PR template, and point your AI tools at `AGENTS.md`.

## 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** (through v0.15.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`](./docs/05-implementation-plan.md). Design rationale is
captured as ADRs under [`docs/decisions/`](./docs/decisions/) and investigations under
[`docs/rfcs/`](./docs/rfcs/).
