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.

Contributing

• Contributing to Spec Kitty — developer setup, running tests, submitting PRs, AI-assistance disclosure, and the release process.
• Review gates: pre-PR / pre-review checklist — the hygiene steps to run locally before requesting review.
• Landing contributor PRs — the claim → isolate → rebase → classify → fold → squad → hand-off maintainer runbook.
• Local overrides for cross-package development — dev-only editable installs across spec-kitty-cli/-events/-tracker that must never be committed.
• Managing the issue tracker — epics vs. meta-trackers, native sub-issue parenting, and triage conventions.

Testing the Spec Kitty codebase

• Test-flakiness handling policy — detection tiers and the never-retry-to-green rule.
• Running the test suite in parallel — the parallel-run workflow and volume gates.
• Run mutation tests locally — mutmut-based assertion-quality checks.
• Write time-dependent tests — inject stable clocks; avoid wall-clock reads in assertions.
• Contract pinning workflow — pinning the spec-kitty-events envelope contract in tests.
• Coverage signals — reconciling the internal diff-coverage gate with SonarCloud coverage / new_coverage.

Release and CI policy

• Red main and release readiness — what a red main means and why CI status is the release authority.
• UI end-to-end tests (Playwright) — the dashboard browser-regression suite.
• Sync daemon orphan cleanup — operator runbook for stale sync daemons.
• Quality & tech-debt standing orders — the eight standing practices for spec-driven missions.
• Terminology guard exemption policy — surfaces exempted from the terminology drift guards.
• Internal hosted-readiness mode (pre-launch) — the hidden SaaS rollout-gate path for internal dogfooding, not for end users.

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.
• mutation-testing-tactic.yaml — a doctrine tactic artifact (non-page).

See also

• Documentation home
• Guides (end-user zone)