How-to (contributor & maintainer tasks)
Step-by-step runbooks for the recurring tasks of contributing to and maintaining Spec Kitty. Each page is scoped to one job you can pick up and finish.
- Landing contributor PRs — the claim → isolate → rebase → classify → fold → squad → hand-off maintainer runbook.
- Review gates: pre-PR / pre-review checklist — the hygiene steps to run locally before requesting review.
- Local overrides for cross-package development — dev-only editable installs across
spec-kitty-cli/-events/-trackerthat must never be committed. - Set up a Claude Code cloud session — make the
spec-kittyCLI, test package and CodeGraph available in a cloud session. - Managing the issue tracker — epics vs. meta-trackers, native sub-issue parenting, and triage conventions.
- Contract pinning workflow — pinning the
spec-kitty-eventsenvelope contract in tests. - Cut-over guard: fail-closed pre-merge gate — what
spec-kitty cutover-guardchecks, how it is wired into CI, and how to register it as a required status check. - Consumer census: keep CI fan-out honest — what the committed consumer census is, when its CI gates go red, and how to regenerate it and fix an unrouted consumer.
- Create a doctrine artifact — author a new doctrine artifact end to end, including the loose-contract asset kind.
- Create and activate a pack skill — author a shared
skill, set its namespace, activate it into each configured tool, and check it withdoctor skills. - How to enable the internal charter and skills — register
packs/internal, project thekitty-*maintainer skills, verify them, and work around two known defects. - How to sync and bump the built-in and internal packs — fetch the pinned
packs/built-inandpacks/internaltrees, work offline, and bump a pin after an upstream change. - Add an exemption to an architectural gate — exempt a site by content (descriptor or
CensusKey), never by line number. - Compress mission history — the path-bucket recipe for compressing a noisy mission branch into a clean, reviewable history (not a default landing step).