repo-standards-kit 0.9.0__tar.gz

repo_standards_kit-0.9.0/.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python scripts/update-handoff/update_handoff.py --check"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python scripts/promote-discovery/promote_discovery.py list --check"
+          }
+        ]
+      }
+    ]
+  }
+}

repo_standards_kit-0.9.0/.claude/skills/new-adr/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: new-adr
+description: Scaffold a new MADR 3.0 ADR with the next NNNN, today's date, and the title filled in.
+---
+
+# new-adr
+
+## When to invoke
+
+Use when the user is about to record an architecture decision — typically because the
+`AGENTS.md` end-of-session contract requires an ADR for a material technical decision,
+or because an RFC's `Follow-ups → ADR to write` field points to a new ADR.
+
+## How to invoke
+
+Run from the repo root:
+
+`python scripts/new-doc/new-adr.py "<Title of the decision>"`
+
+The script creates `docs/decisions/<NNNN>-<slug>.md`, prints the created path, and
+prints a paste-ready row for the manual index in `docs/decisions/README.md`.
+
+## After scaffolding
+
+Open the created file. Fill `deciders`, `consulted`, `informed`, the body sections,
+and paste the printed index row into `docs/decisions/README.md`. Leave
+`status: Proposed` until the decision is accepted. Once `status: Accepted`,
+the body is immutable — reversal is a new ADR.

repo_standards_kit-0.9.0/.claude/skills/new-rfc/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: new-rfc
+description: Scaffold a new RFC folder with rfc.md, the next NNNN, and today as `opened`.
+---
+
+# new-rfc
+
+## When to invoke
+
+Use when the user is about to open a time-boxed investigation that needs a written
+record — typically to satisfy the `AGENTS.md` end-of-session contract item "If you ran
+a time-boxed investigation, write or conclude an RFC", because a question can't be
+resolved inside a single conversation and the team wants to track its approach,
+findings, and recommendation.
+
+## How to invoke
+
+Run from the repo root:
+
+`python scripts/new-doc/new-rfc.py "<Question being investigated>"`
+
+The script creates `docs/rfcs/<NNNN>-<slug>/rfc.md` and prints the created path.
+It does **not** create an `artifacts/` subfolder — add that yourself if the RFC
+collects benchmarks, screenshots, or prototype code.
+
+## After scaffolding
+
+Open the created file. Fill `owner`, `time_box`, and the body sections. Every RFC
+must eventually reach `status: Concluded` or `status: Abandoned`, or its question
+must be moved to `ai/open-questions.md`. RFCs do not sit Open indefinitely.

repo_standards_kit-0.9.0/.claude/skills/promote-discovery/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: promote-discovery
+description: List raw items in docs/discovery/, or flip a specific item from status raw to promoted with a promoted_to target.
+---
+
+# promote-discovery
+
+## When to invoke
+
+Use when:
+- The SessionStart hook surfaced a "N raw items" reminder and you want to see the inventory.
+- You just synthesized a discovery item's content into a PRD, ADR, RFC, or other structured
+  doc — to satisfy the `AGENTS.md` end-of-session contract item "If you used content from
+  `docs/discovery/`, flip its `status: raw` → `promoted`" so the audit trail stays accurate.
+
+## How to invoke
+
+**List raw items** (default verbose mode) from the repo root:
+
+`python scripts/promote-discovery/promote_discovery.py list`
+
+**Promote a specific item** (flip status: raw → promoted; set promoted_to):
+
+`python scripts/promote-discovery/promote_discovery.py promote <path> --to <target>`
+
+Both `<path>` and `--to <target>` are required. `<target>` must be a relative repo path
+(no absolute paths, no `..`). The script does not require `<target>` to exist yet — you
+often promote during the act of writing the target.
+
+## After scaffolding
+
+Verify the diff in the promoted file's frontmatter (`status:` line and `promoted_to:`
+line; everything else preserved). Commit alongside the synthesized target doc.
+
+Promotion is monotonic — once a discovery item is `promoted`, the script refuses to
+re-promote it. If you genuinely need to un-promote, hand-edit the file and explain why
+in the commit message.

repo_standards_kit-0.9.0/.claude/skills/standards-check/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: standards-check
+description: Run the repo's standards checks and fix any findings before pushing or ending a session.
+---
+
+# standards-check
+
+## When to invoke
+
+Run before you finish a session that touched docs, before you push, or when CI's
+"Structural lint" job is red. This satisfies the `AGENTS.md` end-of-session contract
+item "Run `/standards-check` … before ending a session that touched docs."
+
+## How to invoke
+
+Run from the repo root:
+
+`python scripts/standards-check/check.py`
+
+Exit `1` with `ERROR` lines means there is work to fix. `WARN` lines are advisory and
+do not fail CI. The output lists each finding as `[<check_id>] <file>:<line> <message>`.
+
+## After running — how to fix, by check_id
+
+- **`links`** — the relative link or `#anchor` doesn't resolve. Correct the path
+  (relative to the linking file) or fix the fragment to match the target heading slug.
+- **`placeholder`** — a committed ADR/RFC still has template scaffolding. Fill the
+  `<…>`, `YYYY-MM-DD`, or `NNNN`.
+- **`changelog`** — `CHANGELOG.md` has no `## [x.y.z]` version section; add one.
+- **`discovery`** — a `status: promoted` item's `promoted_to:` path is missing or wrong.
+- **`skill-format`** — a skill is missing frontmatter, its `.github/prompts/<n>.prompt.md`
+  twin, or an entry in the `AGENTS.md` `## Available skills` index. Add the missing piece.
+- **`structural`** — a core file is missing, a profile/waiver is unset, or an ADR/RFC
+  filename/status is invalid. Add the file or a `**Waived:**` reason in `docs/STANDARDS-CHECKLIST.md`.
+- **`ai` freshness (WARN)** — `ai/handoff.md`/`current-state.md` is stale. Run `/update-handoff`.
+
+Re-run until `0 error(s)`. (Kit maintainers: version coherence is a separate kit-only
+guard, `tools/check_version_coherence.py`, not covered by this skill.)

repo_standards_kit-0.9.0/.claude/skills/update-handoff/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: update-handoff
+description: Generate a draft ai/handoff.md from git state — frontmatter and "Recently touched" pre-filled; TL;DR, Open threads, and Don't do for the author.
+---
+
+# update-handoff
+
+## When to invoke
+
+Use when the user is about to end a session that produced meaningful change —
+typically to satisfy the `AGENTS.md` end-of-session contract item "Write `ai/handoff.md`
+for the next session", or because the `update-handoff` Stop hook surfaced a reminder
+("N commits + M modified files since last handoff").
+
+## How to invoke
+
+Run from the repo root:
+
+`python scripts/update-handoff/update_handoff.py`
+
+Add `--force` to overwrite an existing handoff. The script:
+- pre-fills frontmatter (`written:` now, `written_by:` from `git config user.name`),
+- pre-fills "Recently touched" from `git log` since the prior handoff,
+- leaves TL;DR, Open threads, and Don't do as placeholders for the author.
+
+## After scaffolding
+
+Open `ai/handoff.md`. Write the TL;DR in plain English (1–3 sentences). Replace
+the Open threads and Don't do placeholders with the real items. Commit alongside
+the slice's other end-of-session updates (`ai/current-state.md`, etc.).

repo_standards_kit-0.9.0/.github/copilot-instructions.md

@@ -0,0 +1,9 @@
+# Copilot Instructions
+
+<!-- BEGIN kit-managed: copilot-pointer (v0.6.0) -->
+See [`AGENTS.md`](../AGENTS.md) — the canonical agent contract for this repo. Read it first.
+<!-- END kit-managed: copilot-pointer -->
+
+## Copilot-specific notes
+
+- Copilot does not yet read `ai/handoff.md` automatically. When suggesting code or docs, treat `AGENTS.md` § "Canonical reading order" as the source of context.

repo_standards_kit-0.9.0/.github/prompts/new-adr.prompt.md

@@ -0,0 +1,18 @@
+---
+mode: agent
+description: Scaffold a new MADR 3.0 ADR with the next NNNN, today's date, and the title filled in.
+---
+
+# new-adr
+
+When the user asks to record an architecture decision, run this from the repo root:
+
+`python scripts/new-doc/new-adr.py "<Title of the decision>"`
+
+The script creates `docs/decisions/<NNNN>-<slug>.md`, prints the created path, and
+prints a paste-ready row for the manual index in `docs/decisions/README.md`.
+
+After scaffolding, open the created file. Fill `deciders`, `consulted`, `informed`,
+the body sections, and paste the printed index row into `docs/decisions/README.md`.
+Leave `status: Proposed` until the decision is accepted. Once `status: Accepted`,
+the body is immutable — reversal is a new ADR.

repo_standards_kit-0.9.0/.github/prompts/new-rfc.prompt.md

@@ -0,0 +1,20 @@
+---
+mode: agent
+description: Scaffold a new RFC folder with rfc.md, the next NNNN, and today as `opened`.
+---
+
+# new-rfc
+
+When the user asks to open a time-boxed investigation that needs a written record,
+run this from the repo root:
+
+`python scripts/new-doc/new-rfc.py "<Question being investigated>"`
+
+The script creates `docs/rfcs/<NNNN>-<slug>/rfc.md` and prints the created path.
+It does **not** create an `artifacts/` subfolder — add that yourself if the RFC
+collects benchmarks, screenshots, or prototype code.
+
+After scaffolding, open the created file. Fill `owner`, `time_box`, and the body
+sections. Every RFC must eventually reach `status: Concluded` or `status: Abandoned`,
+or its question must be moved to `ai/open-questions.md`. RFCs do not sit Open
+indefinitely.

repo_standards_kit-0.9.0/.github/prompts/promote-discovery.prompt.md

@@ -0,0 +1,25 @@
+---
+mode: agent
+description: List raw items in docs/discovery/, or flip a specific item from status raw to promoted with a promoted_to target.
+---
+
+# promote-discovery
+
+When the user wants to see the inventory of raw discovery items, or has just synthesized
+a discovery item's content into a structured doc and wants to flip its status, run one
+of these from the repo root:
+
+**List raw items:** `python scripts/promote-discovery/promote_discovery.py list`
+
+**Promote a specific item:** `python scripts/promote-discovery/promote_discovery.py promote <path> --to <target>`
+
+Both `<path>` and `--to <target>` are required for the promote subcommand. `<target>` must
+be a relative repo path (no absolute paths, no `..`). The script does not require the
+target file to exist yet.
+
+After promoting, verify the diff in the file's frontmatter and commit alongside the
+synthesized target doc. Promotion is monotonic — the script refuses to re-promote.
+
+**Note for Copilot users:** Claude Code's SessionStart hook auto-pings when raw items
+exist at session open; Copilot Chat has no equivalent. Remember to run `list` periodically
+to check the inventory yourself.

repo_standards_kit-0.9.0/.github/prompts/standards-check.prompt.md

@@ -0,0 +1,21 @@
+---
+mode: agent
+description: Run the repo's standards checks and fix any findings before pushing or ending a session.
+---
+
+# standards-check
+
+When finishing a session that touched docs, before pushing, or when CI's structural
+lint is red, run this from the repo root:
+
+`python scripts/standards-check/check.py`
+
+Exit `1` with `ERROR` lines means there is work to fix; `WARN` lines are advisory.
+Each finding is `[<check_id>] <file>:<line> <message>`.
+
+Fix by check_id: `links` → correct the relative path / `#anchor`; `placeholder` → fill
+`<…>`/`YYYY-MM-DD`/`NNNN` in the committed ADR/RFC; `changelog` → add a `## [x.y.z]`
+section; `discovery` → fix the `promoted_to:` path; `skill-format` → add the missing
+frontmatter / `.github/prompts/<n>.prompt.md` twin / `AGENTS.md` index entry;
+`structural` → add the missing file or a `**Waived:**` reason; `ai` freshness → run
+the update-handoff prompt. Re-run until `0 error(s)`.

repo_standards_kit-0.9.0/.github/prompts/update-handoff.prompt.md

@@ -0,0 +1,23 @@
+---
+mode: agent
+description: Generate a draft ai/handoff.md from git state — frontmatter and "Recently touched" pre-filled; TL;DR, Open threads, and Don't do for the author.
+---
+
+# update-handoff
+
+When the user is about to end a session that produced meaningful change, run this
+from the repo root:
+
+`python scripts/update-handoff/update_handoff.py`
+
+(Add `--force` to overwrite an existing handoff.) The script pre-fills the handoff
+frontmatter and "Recently touched" section from git state, leaving TL;DR, Open
+threads, and Don't do as placeholders for the author.
+
+After scaffolding, open `ai/handoff.md` and write the TL;DR in plain English (1–3
+sentences). Replace the Open threads and Don't do placeholders with the real
+items. Commit alongside the slice's other end-of-session updates.
+
+**Note for Copilot users:** Claude Code's `update-handoff` Stop hook auto-reminds
+when work has accumulated; Copilot Chat has no equivalent. Remember to invoke
+this slash command yourself before ending a meaningful session.

repo_standards_kit-0.9.0/.github/pull_request_template.md

@@ -0,0 +1,27 @@
+<!--
+PR template — Standards Impact block at the bottom is enforced by the
+`Standards check` workflow only for repos that have copied this template
+verbatim. If you modify the headings here, update scripts/standards-check/check.py.
+-->
+
+## Summary
+
+<!-- 1–3 sentences. What this PR changes and why. -->
+
+## Test plan
+
+- [ ] <how this was verified locally>
+- [ ] <regressions to watch for>
+
+## Standards Impact
+
+Check each box or replace with `N/A — <reason>`. The Standards check workflow does not parse this section automatically (Slice 4 may add a check), but reviewers will look for it.
+
+- [ ] **Docs:** Numbered doc(s) updated (which: ____) — or `N/A`.
+- [ ] **ADR:** A material decision is captured in `docs/decisions/` — or `N/A — no material decision in this PR`.
+- [ ] **RFC:** Any open RFC concluded by this PR (which: ____) — or `N/A`.
+- [ ] **AI context:** `ai/current-state.md` and/or `ai/handoff.md` updated — or `N/A — state did not change`.
+- [ ] **Discovery promoted:** Any `discovery/` items with `status: raw` synthesized in this PR are flipped to `promoted` — or `N/A`.
+- [ ] **Testing:** New behavior covered by tests (link: ____) — or `N/A — <reason>`.
+- [ ] **Operational:** `06-runbook.md` updated if operability changed — or `N/A`.
+- [ ] **Standards drift:** No undocumented deviation from `docs/STANDARDS.md` introduced (or a new ADR justifies it).

repo_standards_kit-0.9.0/.github/workflows/kit-guards.yml

@@ -0,0 +1,21 @@
+name: Kit guards
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  coherence:
+    name: Version coherence
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Check version coherence
+        run: python tools/check_version_coherence.py

repo_standards_kit-0.9.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    name: Build + publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for PyPI Trusted Publishing (OIDC)
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Verify version coherence + tag
+        env:
+          REF_NAME: ${{ github.ref_name }}
+        run: python tools/check_version_coherence.py --tag "$REF_NAME"
+      - name: Gate on the full test suite
+        run: python tools/run_tests.py
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI (Trusted Publishing — no token)
+        uses: pypa/gh-action-pypi-publish@release/v1

repo_standards_kit-0.9.0/.github/workflows/repo-standards.yml

@@ -0,0 +1,57 @@
+name: Standards check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Structural lint (v1)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Run standards check
+        run: python scripts/standards-check/check.py
+
+  test:
+    name: Tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Run all test suites
+        run: python tools/run_tests.py
+
+  build-smoke:
+    name: Build wheel + init smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Build the wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Install wheel into a clean venv and adopt a temp repo
+        run: |
+          python -m venv /tmp/venv
+          /tmp/venv/bin/pip install dist/*.whl
+          /tmp/venv/bin/standards init --profile library /tmp/adopted
+          test -f /tmp/adopted/docs/STANDARDS.md
+          test -f /tmp/adopted/.standards-kit.json
+          test -f /tmp/adopted/AGENTS.md

repo_standards_kit-0.9.0/.gitignore

@@ -0,0 +1,31 @@
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Editor
+.vscode/*
+!.vscode/extensions.json
+.idea/
+*.swp
+*.swo
+*~
+
+# Logs / scratch
+*.log
+.scratch/
+.tmp/
+
+# AI tool caches (not the committed ai/ context — that ships with the repo)
+.claude/cache/
+.copilot/cache/
+
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Python build artifacts
+dist/
+build/
+*.egg-info/

repo_standards_kit-0.9.0/AGENTS.md

@@ -0,0 +1,74 @@
+# AGENTS.md
+
+<!-- BEGIN kit-managed: agents-core (v0.9.0) -->
+Single source of truth for AI agents working in this repository. Tool-specific files (`CLAUDE.md`, `.github/copilot-instructions.md`) are thin pointers to this document.
+
+- Kit version: **0.9.0**
+
+## Canonical reading order
+
+When you start a session in a repo that follows this kit, read in this order before taking action:
+
+1. **`docs/00-overview.md`** — what this repo is, in 1 page.
+2. **`ai/handoff.md`** — what the last session left for you. If `written` is older than 7 days, treat as "no handoff available".
+3. **`ai/current-state.md`** — the current truth about what works, what's in progress, what's blocked.
+4. **`docs/STANDARDS.md`** — which profile this repo follows and any local deviations.
+5. **`ai/next-actions.md`** — the next 1–7 things on deck.
+6. **`ai/open-questions.md`** — unresolved questions you may need to factor in.
+
+Only after that, dive into the code or the user's specific request.
+
+## End-of-session contract
+
+Before you finish a session that produced meaningful change:
+
+- [ ] Update `ai/current-state.md` if any of the four sections changed (What works · What's in progress · What's blocked · Active environments).
+- [ ] Write `ai/handoff.md` for the next session — TL;DR, recently touched, open threads, and **Don't do** (dead-ends to spare the next session).
+- [ ] If you opened a new question while working, add it to `ai/open-questions.md` with a unique anchor (`#q-N`).
+- [ ] If you closed an `ai/open-questions.md` entry, flip status to `answered` and link the ADR (if one was produced) or the resolution.
+- [ ] If you made a material technical decision, write an ADR in `docs/decisions/` (MADR 3.0 format — see `docs/templates/adr-template.md`).
+- [ ] If you ran a time-boxed investigation, write or conclude an RFC in `docs/rfcs/<NNNN-slug>/rfc.md`.
+- [ ] If you used content from `docs/discovery/`, flip its `status: raw` → `promoted` and set `promoted_to:`.
+- [ ] Run `/standards-check` (or `python scripts/standards-check/check.py`) and fix any findings before ending a session that touched docs.
+
+## How to author each artifact type
+
+- **ADRs:** `docs/templates/adr-template.md`. Immutable once `Accepted`. Reversal = new ADR + flip old to `Superseded by NNNN`.
+- **RFCs:** `docs/templates/rfc-template.md`. One folder per RFC under `docs/rfcs/NNNN-slug/`. Every RFC must either spawn an ADR, be `Abandoned` with reason, or its question must be tracked in `ai/open-questions.md`.
+- **Discovery items:** `docs/templates/discovery-meeting-notes.md` or `discovery-use-case.md`. Filename: `YYYY-MM-DD-source-topic.md`. Place in the right subfolder. Optional but encouraged frontmatter (`source`, `date_captured`, `topic`, `status`, `promoted_to`).
+- **Skills:** `docs/templates/skill-template.md` (Claude) + `docs/templates/skill-prompt-template.md` (Copilot). Name must equal the skill's directory; add a row to the `## Available skills` index.
+- **Numbered docs:** see `docs/STANDARDS.md` for which docs are Required/Expected/Optional/N/A for this profile.
+
+## Standard conventions
+
+- Date format everywhere: ISO 8601 (`YYYY-MM-DD`).
+- Filename conventions: lowercase kebab-case for slugs.
+- Don't edit files in `docs/decisions/` whose status is `Accepted` — write a superseding ADR instead.
+- Don't create numbered docs marked **N/A** for this profile. If a doc is **Optional** and you skip it, no waiver is needed. If it's **Required** or **Expected** and you skip it, add a `**Waived:** <reason>` line in `docs/STANDARDS-CHECKLIST.md`.
+<!-- END kit-managed: agents-core -->
+
+## Available skills
+
+| Skill | When to use |
+|---|---|
+| `new-adr` | Recording a material architecture decision |
+| `new-rfc` | Starting a time-boxed investigation |
+| `promote-discovery` | Marking a discovery item promoted |
+| `update-handoff` | Writing the end-of-session handoff |
+| `standards-check` | Running the standards checks + fixing findings before pushing |
+
+## About this repository
+
+This is the **Team Repository Standards Kit** — a versioned set of documentation standards, templates, AI Skills + a `standards` CLI, and CI checks that other repositories adopt.
+
+- Profile: **library** (this kit ships templates; it has no runtime, no deployment, no runbook)
+
+### Local conventions
+
+- This kit follows itself. Every Slice 1 decision (profile model, ADR format, RFC format, `ai/` contract, AGENTS.md pattern) is captured as an ADR in `docs/decisions/`.
+
+### What's out of scope right now (queued slices)
+
+- **Slice 4 (delivered):** Deeper CI enforcement — content/link/placeholder linting, SKILL.md format + parity + index guards, version-coherence, discovery checks.
+
+Genuinely-future work (open an RFC or `ai/open-questions.md` entry before starting): external-link liveness, richer doc-freshness reporting, a `new-skill` scaffolder.