Skip to content
jk-standards

Quickstart

Five steps to wire jk-standards into an existing repository. Everything below assumes you already have git, Python 3.11+, and pre-commit installed.

1. Add a config file

Section titled “1. Add a config file”

Create jk-standards.yaml at the repo root. Every field is optional — this minimal shape gets you started:

version: 1


doc_roots:
  - path: docs
    extensions: [".md"]


taxonomy:
  classes: [generated, gated, archived]


drift_map: .github/docs-drift-map.yml

For the full field surface see the Configuration reference.

2. Add a drift map

Section titled “2. Add a drift map”

Create .github/docs-drift-map.yml. Each mapping declares that a change to matching sources must be accompanied by a change to the mapped doc (or a Docs-Not-Affected: trailer):

version: 1


mappings:
  - sources:
      - "src/**"
    doc: "docs/reference.md"
    reason: "reference.md documents the public API surface."

Reasons are shown in the failure message when the check trips — write them for a future engineer, not for you today.

3. Classify existing docs

Section titled “3. Classify existing docs”

Every doc under doc_roots needs a class: frontmatter block. Three values are recognized by default:

  • class: gated — living current-state doc, linted every commit
  • class: archived — frozen dated record, exempt from lint
  • class: generated — machine-produced output, freshness-checked
---
class: gated
title: My doc
---


# ...

Run jk-standards doc-taxonomy — it will name every doc missing a class.

4. Wire the pre-commit hooks

Section titled “4. Wire the pre-commit hooks”

Add jk-standards to your .pre-commit-config.yaml, pinned to a release tag:

- repo: https://github.com/JimAKennedy/jk-standards
  rev: v0.13.0
  hooks:
    - id: doc-taxonomy
    - id: status-prose
    - id: file-line-refs

Then pre-commit install — the hooks will run on every commit.

5. Wire the reusable CI workflow

Section titled “5. Wire the reusable CI workflow”

Add a workflow that calls jk-standards’ shipped one — it runs every check plus doc-drift (which needs the PR merge base):

.github/workflows/doc-discipline.yml
jobs:
  checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ inputs.python-version }}

      - name: Install jk-standards
        run: pip install "git+https://github.com/JimAKennedy/jk-standards@${{ inputs.toolkit-ref }}"

      - name: Run checks
        run: jk-standards all --config "${{ inputs.config }}"

In your consuming repo:

.github/workflows/docs.yml
name: docs
on: [pull_request, push]
jobs:
  discipline:
    uses: JimAKennedy/jk-standards/.github/workflows/doc-discipline.yml@v0.13.0

A second reusable workflow, pre-commit.yml, runs your pre-commit hooks in CI from the same two-line caller — handy when a repo also wants a CI gate on hooks it cannot run on pre-commit.ci:

.github/workflows/pre-commit.yml
name: pre-commit
on: [pull_request, push]
jobs:
  pre-commit:
    uses: JimAKennedy/jk-standards/.github/workflows/pre-commit.yml@v0.13.0

That’s it. The rest of the discipline lands progressively: enable count-drift when you have inventory nouns to gate, enable behavioral-claims when you want prose to cite tests, add entries to generated: when you have generated docs to freshness-check. Adoption is designed to be incremental — checks whose config section is empty report themselves as skipped rather than failing.

What’s next

Section titled “What’s next”