This document covers the policies, processes, and requirements for contributing to the Spec Kit repository. It defines prerequisites, submission workflows, AI assistance disclosure requirements, and quality expectations for pull requests.
For information about local development environment setup, see Local Development Setup. For testing template and command changes, see Testing Template and Command Changes.
The Spec Kit project welcomes contributions that improve the CLI tool, templates, scripts, extensions, and documentation. All contributions must adhere to the project's Contributor Code of Conduct() and follow established workflows. This page documents the technical requirements and processes for submitting changes.
Sources: CONTRIBUTING.md1-151
Contributors must install the following tools before submitting changes:
| Tool | Version | Purpose |
|---|---|---|
| Python | 3.11+ | Core CLI implementation |
| uv | Latest | Package management |
| Git | Any | Version control |
| AI Coding Agent | Any supported | Testing workflow commands |
Sources: CONTRIBUTING.md7-14
For VSCode or GitHub Codespaces users, a pre-configured development container is available at .devcontainer/devcontainer.json The container includes all required tools and eliminates manual setup.
VSCode Setup:
GitHub Codespaces: Automatically uses the devcontainer configuration on launch.
Sources: CONTRIBUTING.md16-31
Sources: CONTRIBUTING.md33-55
Fork and clone the repository
Install dependencies
Verify CLI installation
Create a feature branch
Make changes and add tests
src/specify_cli/templates/scripts/Test with sample project (see Local Testing Process below)
Push and submit PR
Sources: CONTRIBUTING.md38-45
The following factors increase likelihood of PR acceptance:
| Criterion | Description |
|---|---|
| Follows conventions | Adheres to existing code style and patterns |
| Includes tests | New functionality has test coverage |
| Updates documentation | Changes to user-facing features update README.md or spec-driven.md |
| Focused scope | Single PR addresses one change; multiple independent changes submitted separately |
| Good commit message | Clear, descriptive commit messages |
| Workflow compatibility | Tested with Spec-Driven Development workflow commands |
Sources: CONTRIBUTING.md47-54
Pull requests introducing large changes (new templates, CLI arguments, major features) require prior discussion and agreement with maintainers before submission. PRs with large, undiscussed changes will be closed.
Sources: CONTRIBUTING.md35-36
All AI-assisted contributions must be disclosed in the PR or issue. This requirement applies to:
Exemption: Trivial spacing or typo fixes limited to small code portions or short phrases do not require disclosure.
Sources: CONTRIBUTING.md88-103
Sources: CONTRIBUTING.md88-115
Simple disclosure:
Detailed disclosure:
Sources: CONTRIBUTING.md104-112
Maintainers accept AI-assisted contributions that include:
| Requirement | Description |
|---|---|
| Clear disclosure | Transparent about AI use and degree of assistance |
| Human understanding | Contributor has personally tested and understands the changes |
| Clear rationale | Explanation of why the change is needed and how it fits Spec Kit's goals |
| Concrete evidence | Test cases, scenarios, or examples demonstrating the improvement |
| Personal analysis | Contributor's thoughts on end-to-end developer experience |
Sources: CONTRIBUTING.md119-127
Maintainers will close contributions that appear to be:
Contributors who consistently submit low-effort AI-generated changes may be restricted from further contributions.
Sources: CONTRIBUTING.md129-142
Running uv run specify init downloads released packages from GitHub, which do not include local changes. Testing local modifications requires generating release packages manually and copying them to a test project.
Sources: CONTRIBUTING.md65-68
Sources: CONTRIBUTING.md65-87
Generate release packages
This creates 32 package variants in .genreleases/ directory.
Select appropriate package Choose the package matching your test environment:
copilot, claude, gemini, etc.sh (Bash) or ps (PowerShell)Example: .genreleases/sdd-copilot-package-sh/
Copy to test project
Open agent and test Navigate to test project and verify:
/speckit.* commands are registeredSources: CONTRIBUTING.md70-86
When working on Spec Kit, test changes in the appropriate areas:
| Component | Test Method |
|---|---|
| CLI commands | Run uv run specify <command> directly |
| Workflow commands | Test /speckit.* commands in AI agent |
| Templates | Verify template rendering in templates/ directory |
| Scripts | Execute scripts in scripts/ directory |
| Constitution | Check memory/constitution.md for process changes |
Sources: CONTRIBUTING.md56-63
Changes typically affect these directories:
spec-kit/
├── src/specify_cli/ # CLI implementation
│ ├── __init__.py # AGENT_CONFIG dictionary
│ ├── cli.py # Command definitions
│ └── ...
├── templates/ # Specification templates
│ ├── spec-template.md
│ ├── plan-template.md
│ └── tasks-template.md
├── scripts/ # Helper scripts
│ ├── create-new-feature.sh
│ ├── update-agent-context.sh
│ └── *.ps1 # PowerShell equivalents
├── memory/ # Constitutional documents
│ └── constitution.md
└── .github/workflows/ # CI/CD and release scripts
└── scripts/
└── create-release-packages.sh
Sources: CONTRIBUTING.md56-63
Sources: CONTRIBUTING.md45
Pull requests affecting user-facing features must update relevant documentation:
| Change Type | Required Documentation |
|---|---|
| New CLI commands | Update README.md |
| New workflow commands | Update spec-driven.md |
| Template changes | Document in commit message |
| Script modifications | Update inline comments |
| Extension system changes | Update extension docs |
Sources: CONTRIBUTING.md51
Sources: CONTRIBUTING.md33-54 CONTRIBUTING.md88-142
All contributors must abide by the Contributor Covenant Code of Conduct(). The project maintains a harassment-free environment and expects:
Violations may be reported to [email protected].
Sources: CODE_OF_CONDUCT.md1-75 CONTRIBUTING.md5
Sources: CONTRIBUTING.md145-151
Refresh this wiki