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. The split is strict: no contributor-only page is reachable from end-user navigation.

The active release cycle is 4.0.0 (release candidates on main); see the 4.0.0 milestone roadmap. The 3.x line is closed.

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, creating a doctrine artifact, architectural-gate exemptions, and compressing mission history.
• Reference — policy and ledgers: friction points, coverage signals, CI and architectural gate mechanics, issue-matrix verdicts, standing orders, the read-side seam ledger, red-main policy, terminology exemptions, and the version taxonomy.
• Testing — CLI acceptance scenarios, flakiness policy, parallel runs, mutation tests, UI e2e, and time-dependent tests.
• Reporting — the executive debrief styleguide.
• Other records — analysis-report transactions (record-analysis --report-only) and the inline meta-read allowlist baseline deviation.

Archived records

These pages moved to docs/archive/, which is not published. They are kept as records, not current guidance.

• tests/sync/ process-global and thread-seam inventory (#3115) — deprecated; the tests/sync/ cone it maps was deleted with the sync transport.
• Agent-memory migration manifest and agent-memory workflow migration manifest — one-off audit records of a migration of operator memory into doctrine.

Start here

• Contributing to Spec Kitty — developer setup, running tests, submitting PRs, AI-assistance disclosure, and the release process.
• The SkyKitty agent fleet — the company agent fleet that runs missions on this repo, the roles inside it, and the ready-for-squad handshake that hands work to the review squad and CI.

Non-page artifacts

Both files cover every current doc, whatever the release line. Until 2026-09-30 they carried a 3-2- filename prefix from the mission that introduced them.

• 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.
• docs-retrieval-index.yaml — the docs retrieval index, regenerated by scripts/docs/docs_index.py (see below).

Repo-owned workflow commands

Two commands a mission session runs directly, not through a spec-kitty CLI subcommand — plus the regen command for generated agent copies:

• 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/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 consolidation → 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 / skill fixtures. Run spec-kitty regen to rewrite the committed generated fixtures from source, and spec-kitty regen --check to verify them without writing (it exits 1 and prints the diff when they are stale). CI runs the same check as the regen-check job in ci-router.yml. Added under #3447 (automated asset/prompt regeneration). Do not hand-roll a substitute regen path.

See also

• Documentation home
• Guides (end-user zone)