Development

Runbooks and policy for people contributing to or maintaining the Spec Kitty project itself — as opposed to ../guides/, which documents using Spec Kitty in your own project. This strict split is FR-003: no contributor-only page is reachable from end-user navigation.

This zone is subdivided by concern:

• Getting started — onboarding a co-maintainer and isolated dev environments.
• How-to — task runbooks: landing PRs, review gates, local overrides, the issue tracker, contract pinning, the cut-over guard, and creating a doctrine artifact.
• Reference — policy and ledgers: friction points, coverage signals, the #3115 seam inventory, standing orders, the read-side seam ledger, red-main policy, and terminology exemptions.
• Testing — flakiness policy, parallel runs, mutation tests, UI e2e, and time-dependent tests.

Start here

• Contributing to Spec Kitty — developer setup, running tests, submitting PRs, AI-assistance disclosure, and the release process.

Non-page artifacts

• 3-2-page-inventory.yaml — the page-inventory tooling artifact. It STAYS PUT by operator directive; the freshness/lockfile tooling (scripts/docs/inventory_lockfile.py, check_docs_freshness.py, version_leakage_check.py, _inventory.py) reads it at this stable path. A regression guard (tests/docs/test_inventory_path_stable.py) asserts the path cannot silently move.

Repo-owned workflow commands

Two commands a mission session runs directly, not through a spec-kitty CLI subcommand — plus one not-yet-available regen path:

• Freshen the docs-inventory rollups. After adding or refrontmattering any page under docs/**, regenerate both generated rollups and verify no drift remains:

  # inventory_lockfile.py: --write takes the OUTPUT PATH as its argument (not a bare flag)
  PYTHONPATH=. .venv/bin/python scripts/docs/inventory_lockfile.py \
    --write docs/development/3-2-page-inventory.yaml
  
  # docs_index.py: --write IS a bare flag here (rewrites the default --index path in place)
  PYTHONPATH=. .venv/bin/python scripts/docs/docs_index.py --write
  
  PYTHONPATH=. .venv/bin/python scripts/docs/check_docs_freshness.py --ci   # must report errors=0; external-URL WARNINGS are fine
  

  The two --write flags are not the same shape — a bare --write on inventory_lockfile.py is a usage error (it needs a path argument), while passing a path to docs_index.py --write is rejected as an unexpected positional. These are two separate generators for two sibling artifacts that are never conflated with each other — inventory_lockfile.py only regenerates the page inventory, docs_index.py only regenerates the retrieval index. check_docs_freshness --ci fails closed with a blocking INVENTORY-LOCKFILE-DRIFT / DOCS-INDEX-DRIFT finding if either rollup is stale relative to frontmatter — see Known current friction points. Commit both regenerated YAMLs alongside your doc edit.

• Mission wrap-up sequence. The standing close-out procedure a mission runs between "all work packages approved" and "draft PR handed to the operator": accept → retire/split dev-assist tests → resolve issue verdicts → independent aggregate-diff review → local merge → compact history → rebase onto upstream → draft PR + pre-merge squad → hand off. Canonical source: the mission-wrap-up-sequence procedure. Its three binding quality pillars — linear history, complete scope, independent review — are DIRECTIVE_046 ("Readable and Consistent Pull Requests"). Referenced from the onboarding-run cadence, step 12.

• Regenerating generated agent-command copies / prompt snapshots. Not yet a standalone entrypoint — tracked in #3447 (modular per-package CI plus automated asset/prompt regeneration). Do not hand-roll a substitute regen path; file against or watch that issue instead.

See also

• Documentation home
• Guides (end-user zone)