Document status:active The full contributor guide for Spec Kitty — developer setup, running tests, submitting pull requests, AI-assistance disclosure, and the release process.
Hi there! We’re thrilled that you’d like to contribute to Spec Kitty. Contributions to this project are released to the public under the project’s open source license.
Spec Kitty is inspired by GitHub’s Spec Kit. Please preserve upstream attribution when referencing historical work or documentation.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
Ways to contribute (no code required)
You don’t need to write code to help shape Spec Kitty. Ideas, use-cases, and objections are genuinely wanted — especially on design decisions still in flight.
Look for the feedback-welcome label. Issues carrying it are open for community input; many contain an Open decision block calling out exactly where we’d like your perspective. Comment freely — a rough thought is more useful than silence.
Filing something new? Use the 💡 Idea / brainstorm / feedback issue template (it auto-applies feedback-welcome), or the bug / enhancement templates for concrete reports. A partial sketch is fine — a maintainer will triage it and, if it’s actionable, turn it into a tracked mission.
No pressure to formalize. You don’t have to write a full proposal; tell us the problem you hit or the outcome you want, and we’ll take it from there.
Well-scoped feedback often becomes the seed of a mission, so this is one of the highest-leverage ways to contribute.
Developer Setup
After cloning, bootstrap your environment:
Terminal window
uvsync--frozen--all-extras
makedev-setup
make dev-setup syncs dependencies and installs all spec-kitty slash commands
for your configured AI agents (including /spec-kitty.specify and related
commands in Claude Code). Re-run after pulling changes or after any
spec-kitty template change.
Without running make dev-setup, planning commands like /spec-kitty.specify
may be absent from your AI coding agent. make dev-setup always repairs this —
it is idempotent, so running it multiple times is safe.
Windows users: make requires WSL or a GNU Make equivalent.
Alternatively, run the setup steps manually:
Terminal window
uvsync--frozen--all-extras
uvrunspec-kittydoctorskills--fix
Contributor Recognition
This repository uses All Contributors to recognize project contributions beyond code.
Recognition is recorded in .all-contributorsrc and rendered into README.md.
There is currently no scheduled sync workflow in .github/workflows/, so
recognition is maintainer-driven. That includes both new
contributions and retroactive backfill for earlier code, docs, design, bug reports,
feature requests, mentoring, or other project help that deserves recognition.
Maintainers can add recognition from an issue or PR comment:
@all-contributors please add @github-username for doc,design,ideas,bug
Supported contribution types are listed in the emoji key.
Supported AI Agents
Spec Kitty supports 17 AI coding agents: 12 slash-command agents (Claude Code,
GitHub Copilot, Gemini, Cursor, Qwen Code, OpenCode, Windsurf, Kilocode, Augment
Code, Amazon Q, Kiro, LLxprt Code) and 5 Agent Skills agents (Codex CLI, Mistral
Vibe, Pi, Letta Code, Google Antigravity) that share .agents/skills/spec-kitty-<command>/. When a
change affects slash commands, migrations, or templates, make sure it applies to
every configured agent.
The directory table lives in the “Supported AI Agents” section of
AGENTS.md; the code source of truth is AGENT_DIRS /
AGENT_DIR_TO_KEY in src/specify_cli/agent_utils/directories.py. Migrations
should call get_agent_dirs_for_project() so they only touch agents configured
in .kittify/config.yaml.
Prerequisites for running and testing code
These are one time installations required to be able to test your changes locally as part of the pull request (PR) submission process.
Contributor tests run from a source checkout, not from a globally installed
spec-kitty binary. Use a global install when you want to run Spec Kitty outside
this repository or when you are explicitly testing install/update behavior.
Use one tool manager for a normal global install; installing with both can put
two spec-kitty binaries on your PATH.
To install the latest main branch from GitHub with uv:
For the latest PyPI release instead of GitHub main, install or upgrade by
package name:
Terminal window
uvtoolinstallspec-kitty-cli
uvtoolupgradespec-kitty-cli
Terminal window
pipxinstallspec-kitty-cli
pipxupgradespec-kitty-cli
After a new PyPI release, CDN caching can make upgrades lag briefly. If that
happens, reinstall the exact version instead:
Terminal window
uvtoolinstall--forcespec-kitty-cli==X.Y.Z
pipxinstall--forcespec-kitty-cli==X.Y.Z
Shared Dependencies
Spec-kitty’s shared libraries are published to PyPI and resolved automatically by
uv sync — no SSH access or special repository permissions are required for
local development:
Compatibility ranges are declared in pyproject.toml; exact pinned versions live
in uv.lock.
spec-kitty-runtime is no longer a dependency: the CLI’s runtime surface is
internalized under src/runtime/next/, and its absence is enforced by
tests/architectural/test_pyproject_shape.py.
Running Tests
Spec Kitty’s test suite is designed to run against source code, not installed packages. This ensures tests verify the current code, not a previously installed version.
Quick Start
Terminal window
# Install dependencies and the dev tooling (one time, and after pulling)
makedev-setup
# Shared fast baseline for an ordinary change
maketest-fast
# Plus the tests that cover what you changed, for example
uvrunpytesttests/status/# a module's own tests
uvrunpytesttests/architectural/test_no_legacy_terminology.py# a specific gate
Do not run the whole suite (pytest with no path, pytest tests/, or
make test-full) for an ordinary change — CI owns the full run. Run
make test-fast, the tests of every module your diff touches, and the specific
architectural gate files your change implicates. The blast-radius rule is spelled
out under “Test policy” in AGENTS.md; how the parallel run
works is in Running the test suite in parallel.
Testing Unreleased Main or a Pull Request
When you need to test the current main branch or a specific pull request
before it is published to PyPI, avoid replacing your normal global
spec-kitty install unless that is the thing you are testing.
For normal contributor work, run from a source checkout:
If you are testing a fork branch or an exact commit, replace the URL/ref with
git+https://github.com/<OWNER>/spec-kitty.git@<BRANCH_OR_SHA>. Hosted
Team Kitty behaviour is gated by team membership and repository admission on
the SaaS side, not by a local sync switch; SPEC_KITTY_ENABLE_SAAS_SYNC is
leftover naming and gates nothing. See Team Kitty.
Test Isolation
Tests use several mechanisms to ensure they run against source code:
PYTHONPATH: Points to src/ directory
SPEC_KITTY_CLI_VERSION: Overrides version detection
SPEC_KITTY_TEST_MODE: Prevents fallback to installed package
isolated_env fixture: Provides consistent environment for all tests
All integration tests use the run_cli fixture which handles this automatically.
Troubleshooting Version Issues
If you see errors like “Version Mismatch Detected”, it means you have a pip-installed version of spec-kitty-cli that doesn’t match your source code version.
Solution:
Terminal window
# Uninstall any installed version
pipuninstallspec-kitty-cli-y
# Run tests again
maketest-fast
This is the most common test issue and is easy to fix. The test isolation system will detect mismatches automatically.
Troubleshooting Shared Package Import Issues
If pytest fails during collection with an error like:
ImportError: cannot import name 'normalize_event_id' from 'spec_kitty_events' (unknown location)
check whether Python is resolving spec_kitty_events as a namespace package:
Healthy output points at spec_kitty_events/__init__.py. Broken output shows
None _NamespacePath(...), which means the local install is corrupted. Rebuild
the project environment with:
Terminal window
uvsync--reinstall-packagespec-kitty-events
If the broken package lives in a global or Homebrew Python environment, remove
the stale spec_kitty_events/ directory and matching .dist-info/ metadata
from that interpreter’s site-packages, then reinstall
spec-kitty-events. See
Diagnose Installation Problems
for the full recovery procedure.
How Test Isolation Works
The test infrastructure guarantees that tests always use source code:
Environment Variables: Set by isolated_env fixture in tests/integration/conftest.py
Test Mode Enforcement: SPEC_KITTY_TEST_MODE=1 forces CLI to use source version
Fail-Fast: If fixtures are misconfigured, tests fail immediately with clear error
CI Verification: GitHub Actions verify version consistency before running tests
For more details, see tests/README.md.
Submitting a pull request
Fork and clone the repository
Configure and install the dependencies: uv sync
Make sure the CLI works on your machine: uv run spec-kitty --help
Create a new branch: git checkout -b my-branch-name
Make your change, add tests, and make sure everything still works
Test the CLI functionality with a sample project if relevant
Push to your fork and submit a pull request
Wait for your pull request to be reviewed and merged.
Here are a few things you can do that will increase the likelihood of your pull request being accepted:
Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
Write a good commit message, and keep your history clean but not over-squashed: compress your own bookkeeping commits (fixups, “wip”, formatting-only) into the related work, but keep genuinely separate logical/code changes as separate commits — each commit should be one coherent, reviewable change.
If a scoped change also carries incidental formatting-only diffs, call that out explicitly in the PR body so reviewers can distinguish behavior changes from formatting churn.
Write a PR body that leads with impact — what changes for a user or operator, in plain language, before any architecture or test-strategy detail. See Review gates: PR body style.
If your change is user-facing, add a consumer-focused changelog fragment, docs/changelog/unreleased/<id>.<section>.md, instead of editing docs/changelog/CHANGELOG.md — impact-first, one line a user understands, not an internal-mechanism summary. See Review gates: Changelog update and style.
Test your changes with the Spec-Driven Development workflow to ensure compatibility.
Don’t request review while your PR title is prefixed WIP / [WIP]. Keep the PR in draft until it is ready, then drop the prefix. See Review Gates.
Label-driven fleet workflow
Status: the SkyKitty fleet is switched off (the CI Fleet Verdict workflow is
disabled). The issue-side status:* labels and taken-by-human stay in use as human
workflow state; the PR-lane labels below (squad:*, needs:implementer) were deleted on
2026-10-19. The rest of this section describes the fleet while it was active.
This repo is one of the programme’s repos worked by the SkyKitty agent fleet,
and the fleet runs on a label-driven queue: GitHub labels are the only admission
control. Agents and humans move work by changing labels, never by out-of-band assignment.
As a contributor, two things follow:
Issues flow through a status:* lifecycle — status:triage → status:ready (the
fleet’s admission queue) → status:claimed (an implementer holds a lease) →
status:blocked. A human-driven contributor may claim work by adding status:claimed
and taken-by-human while beginning it, then commenting
claimed by <harness>/<model> on <machine>; never add a bare claim when nobody is actively
working the issue, because the dispatcher treats the label as occupied capacity.
taken-by-human is the load-bearing half of that pair: it is the only label that keeps the
fleet’s PR-routed fix and recovery lanes off your PR (they read the PR’s own labels, never the
linked issue’s status:claimed), so a claim without it can still collide with a fleet VM.
Pull requests flow through their own lane labels — ready-for-squad (request
adversarial review) → squad:running → squad:passed / squad:majors — plus
needs:implementer, which is mandatory on any fix/rebase request that expects a new
push. The dispatcher admits fix rounds carrying needs:implementerorsquad:majors; a request comment carrying neither label is never seen.
Landing contributor PRs — the maintainer runbook for taking a contributor PR from “open with red CI” to “merge-ready, evidence posted, operator merges”: claim, isolated worktree, rebase, red classification, folds, red-first verification, push discipline, and hand-off.
Managing the issue tracker — epics vs. meta-trackers,
native sub-issue parenting, and triage conventions, including how issue kind (Task /
Bug / Feature, which are GitHub’s native issue types) is set and tracked.
Create a doctrine artifact — includes how to model
relationships between doctrine artifacts, including
design-opposing tension
(in_tension_with / reconciles_tension; the legacy opposed_by field is retired).
Development workflow
When working on spec-kitty:
Test changes with the spec-kitty CLI commands (/spec-kitty.specify, /spec-kitty.plan, /spec-kitty.tasks) in your coding agent of choice
Verify mission templates are working correctly; the source templates live in packs/built-in/missions/ (never edit the generated agent copies)
Test script functionality in the scripts/ directory
Ensure the project charter (.kittify/charter/charter.md) is updated if major process changes are made
Release Process
The repository-root Release Checklist is the canonical release runbook. The summary below is intentionally subordinate to that checklist and must remain consistent with branch protection.
Branch Strategy
Spec Kitty’s active release line is:
main — The release branch. All tags MUST be created from main.
1.x-maintenance — Deprecated, critical-maintenance-only line; no new work or PyPI releases.
The active cycle is 4.0.0, currently at the release-candidate stage on main
(4.0.0rc5 open; rc1–rc4 shipped). Scope and the path to stable are tracked in
the 4.0.0 milestone roadmap; work deferred
past 4.0.0 goes to the GitHub milestone “CLI 4.x stable”. The 3.x line is closed:
its last release was 3.2.7.
Release candidates (X.Y.ZrcN)
A release candidate follows the same steps as a patch release, with three
differences. The Release Checklist has the full
detail, including the release-candidate hygiene runs that must be recorded
before the tag.
Use a Python prerelease version and tag: version = "4.0.0rc5", tag
v4.0.0rc5, and a matching ## [4.0.0rc5] - YYYY-MM-DD changelog heading.
release.yml detects the aN / bN / rcN suffix and marks the GitHub
release as a Pre-release.
pip and uv skip prereleases unless asked. Verify with an exact pin
(pip install "spec-kitty-cli==4.0.0rc5") or --pre.
After the tag, open the next candidate on main (for example 4.0.0rc5 →
4.0.0rc6) exactly as in step 9 below.
Quick Release (Patch)
For a small release whose product changes have already landed on main:
Terminal window
# 1. Create a release branch, then bump version and update changelog
gitcheckout-brelease/X.Y.Zmain
# Edit pyproject.toml: version = "X.Y.Z"
# Edit CHANGELOG.md: add section after [Unreleased]
# 2. Commit on a release branch, push it, and merge its PR
gitaddpyproject.tomlCHANGELOG.md
gitcommit-m"chore(release): prepare X.Y.Z"
gitpushoriginrelease/X.Y.Z
ghprcreate--basemain--title"Release X.Y.Z"--fill
ghprmerge--auto# queues it; the merge queue rebase-merges once the required checks pass
Assemble the pending fragments first: python -m scripts.release.changelog_fragments assemble --write
folds every docs/changelog/unreleased/ fragment into ## [Unreleased] and deletes it. A tag is refused while any fragment remains.
Add a new version section immediately after ## [Unreleased]:
## [X.Y.Z] - YYYY-MM-DD
### <Category>
-**Short bold headline** (#1234).
**Before:** what used to happen. **After:** what happens now.
Use only the category headings the changelog style guard enforces, each at
most once and in this order, with no emoji:
### Breaking — Breaking changes
### Upgrade Notes — Steps users take when upgrading
### Added — New features
### Changed — Changes to existing behavior
### Fixed — Bug fixes
### Internal — Refactoring, dependency updates, other maintainer-only changes
The entry rules (bold headline, **Before:**/**After:**, banned tokens,
length) are in
Changelog update and style.
The Release Readiness Check workflow validates version and changelog metadata. Require the repository test and package checks to pass on the same commit before publishing.
Get approval from a maintainer
Squash-merge the PR so the main-protection workflow can verify its PR marker
Note: unset GITHUB_TOKEN is needed because the env var token may have limited scopes (e.g., only copilot). The keyring token has full repo scope.
Verify the release
Terminal window
unsetGITHUB_TOKEN && ghreleaseviewvX.Y.Z
pipxinstall--forcespec-kitty-cli==X.Y.Z
Open the next development cycle
Right after the tag, open a pull request that moves main to the next development or candidate version: pyproject.toml, the project entry in uv.lock, .kittify/metadata.yaml, and a new ## [Unreleased] - <next version> heading in CHANGELOG.md.
Until it merges, branch-mode release validation on main fails with “Version does not advance beyond latest tag”. The canonical step is step 8 of the Release Checklist.
Clean up
Terminal window
gitbranch-drelease/X.Y.Z
gitpushorigin--deleterelease/X.Y.Z
What the Release Workflow Does
Pushing a v*.*.* tag triggers .github/workflows/release.yml, which:
Requires a green nightly run for the exact tagged commit, plus a green nightly from the last 7 days in which the weekly performance job executed (the newest such run must be green), on that commit or a main ancestor of it (fail-closed; without either, the gate dispatches the nightly by the tag and waits, and publishes nothing unless it goes green)
Installs dependencies with uv sync --frozen (the shared packages come from PyPI; no SSH key is involved)
Verifies test isolation (no version mismatch between source and installed package)
Runs the release-specific tests (tests/release); the broad module matrix stays owned by main CI
Classifies the release channel (a prerelease suffix marks the GitHub release as Pre-release)
Builds wheel and source distributions, checks shared-package drift, and verifies the wheel installs and contains every migration file
Generates an SBOM and records artifact checksums
Extracts the changelog section for the release notes, creates the GitHub Release, and publishes to PyPI
Verifies the exact version installs from PyPI
Release Checklist
Before tagging a release, ensure:
You are on the main branch
Version number follows semantic versioning
Every docs/changelog/unreleased/ fragment is assembled into CHANGELOG.md under the enforced category headings (see Changelog update and style)
The release-candidate hygiene runs in the Release Checklist are recorded
Broad CI, release readiness, and shared-package drift checks are green
After tagging, open the next development cycle on main (Full Release step 9).
Important Notes
Tags MUST be created from main after the release PR lands
Use annotated tags — always use git tag -a, not git tag
Monitor the release workflow — watch for failures and be ready to fix issues
PyPI is immutable — once published, a version cannot be changed (only yanked)
PyPI CDN caching — pipx upgrade may not find the new version immediately; use pipx install --force spec-kitty-cli==X.Y.Z instead
Troubleshooting Releases
Release workflow fails — check the actual error first
The workflow prints a generic error listing three possible causes (“PYPI_API_TOKEN”, “version/changelog mismatch”, “Tests failed”) whenever ANY step fails. Check the actual failing step:
You attempted to release a version that’s already published
Bump to the next version number and retry
Changelog validation fails
Ensure CHANGELOG.md has a section matching the version in pyproject.toml
Check the date format is YYYY-MM-DD
Verify the version number is monotonically increasing
AI contributions in Spec Kitty
We welcome and encourage the use of AI tools to help improve Spec Kitty! Many valuable contributions have been enhanced with AI assistance for code generation, issue detection, and feature definition.
That being said, if you are using any kind of AI assistance (e.g., agents, ChatGPT) while contributing to Spec Kitty,
this must be disclosed in the pull request or issue, along with the extent to which AI assistance was used (e.g., documentation comments vs. code generation).
If your PR responses or comments are being generated by an AI, disclose that as well.
As an exception, trivial spacing or typo fixes don’t need to be disclosed, so long as the changes are limited to small parts of the code or short phrases.
An example disclosure:
This PR was written primarily by GitHub Copilot.
Or a more detailed disclosure:
I consulted ChatGPT to understand the codebase but the solution
was fully authored manually by myself.
Failure to disclose this is first and foremost rude to the human operators on the other end of the pull request, but it also makes it difficult to
determine how much scrutiny to apply to the contribution.
In a perfect world, AI assistance would produce equal or higher quality work than any human. That isn’t the world we live in today, and in most cases
where human supervision or expertise is not in the loop, it’s generating code that cannot be reasonably maintained or evolved.
What we’re looking for
When submitting AI-assisted contributions, please ensure they include:
Clear disclosure of AI use - You are transparent about AI use and degree to which you’re using it for the contribution
Human understanding and testing - You’ve personally tested the changes and understand what they do
Clear rationale - You can explain why the change is needed and how it fits within Spec Kitty’s goals
Concrete evidence - Include test cases, scenarios, or examples that demonstrate the improvement
Your own analysis - Share your thoughts on the end-to-end developer experience
What we’ll close
We reserve the right to close contributions that appear to be:
Untested changes submitted without verification
Generic suggestions that don’t address specific Spec Kitty needs
Bulk submissions that show no human review or understanding
Guidelines for success
The key is demonstrating that you understand and have validated your proposed changes. If a maintainer can easily tell that a contribution was generated entirely by AI without human input or testing, it likely needs more work before submission.
Contributors who consistently submit low-effort AI-generated changes may be restricted from further contributions at the maintainers’ discretion.
Please be respectful to maintainers and disclose AI assistance.