Contributing to Spec Kit
Relevant source files
The following files were used as context for generating this wiki page:Contributions to Spec Kit are highly encouraged and are released to the public under the project's MIT open source license. This guide provides a comprehensive overview of the development workflow, technical prerequisites, and core principles that contributors must follow. The project revolves around Spec-Driven Development (SDD), a methodology where specifications are executable artifacts that generate code, rather than static documents that merely guide it.
All participation in the project is governed by the Contributor Code of Conduct. By contributing, you agree to abide by its terms. For a deeper understanding of the project's philosophy, contributors should review the Spec-Driven Development Methodology.
Sources: CONTRIBUTING.md:3-6, spec-driven.md:3-10, README.md:183
Prerequisites
Before contributing, you must install the necessary tools to run and test the code locally. These one-time installations are required for the pull request submission process.
| Tool | Required Version | Installation Source | Purpose |
|---|---|---|---|
| Python | 3.11+ | python.org | Core runtime for the CLI and scripts. |
| uv | Latest | docs.astral.sh/uv/ | Python package management. |
| Git | Latest | git-scm.com/downloads | Version control. |
| AI Agent | Any | Claude, Copilot, or Gemini | Core component for SDD workflow. |
Sources: CONTRIBUTING.md:10-15, README.md:105-111
The Spec-Driven Development (SDD) Workflow
Contributing to spec-kit requires adherence to the Spec-Driven Development workflow. This process uses a series of commands to transform a high-level feature description into a structured specification, a detailed technical plan, and an actionable task list.
The diagram below illustrates the high-level SDD workflow.
This diagram shows the progression from an idea to an implemented feature using the core commands.
Sources: spec-driven.md:123-157, README.md:40-54
The Core Commands
The SDD workflow is orchestrated by three main commands, which are typically used within an AI coding agent.
| Command | Input | Output | Purpose |
|---|---|---|---|
/specify | A natural language feature description. | A new feature branch and a spec.md file in specs/<branch-name>/. | Transforms a high-level idea into a structured, non-technical feature specification. |
/plan | The spec.md file and technical stack choices. | plan.md, research.md, data-model.md, and API contracts. | Converts the feature specification into a detailed, actionable technical implementation plan. |
/tasks | The plan.md and other generated design documents. | A tasks.md file containing a list of executable development tasks. | Breaks down the implementation plan into a granular, ordered list of tasks for the AI agent to execute. |
Sources: spec-driven.md:125-157, templates/commands/specify.md, templates/commands/plan.md, templates/commands/tasks.md
Submitting a Pull Request
The process for submitting changes is standardized to ensure code quality and consistency.
The following flowchart outlines the steps for submitting a pull request.
Key Guidelines for a Successful PR:
- Focused Changes: Keep pull requests as focused as possible. Submit independent changes as separate PRs.
- Testing: Write tests for any new functionality.
- Documentation: Update
README.mdandspec-driven.mdif your changes affect user-facing features. - Conventions: Follow the project's existing coding conventions and write good commit messages.
Sources: CONTRIBUTING.md:17-38
Development Internals
Contributors should be familiar with the key scripts and architectural principles that underpin the spec-kit project.
Starting a New Feature: create-new-feature.sh
The /specify command is powered by the create-new-feature.sh script. This script automates the initial setup for any new feature.
The script's execution flow is as follows:
- Determines the next sequential feature number (e.g.,
001,002). - Generates a sanitized, descriptive branch name from the feature description (e.g.,
003-chat-system). - Creates and checks out the new Git branch.
- Creates a corresponding directory under
specs/. - Copies the
spec-template.mdinto the new feature directory asspec.md.
The diagram below shows the logic of the create-new-feature.sh script.
Project Initialization: The specify CLI
The specify CLI, defined in src/specify_cli/__init__.py, is the entry point for users to set up a new project that uses the Spec-Driven Development methodology. The primary command is specify init.
# Example usage
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
The init command performs the following actions:
- Prompts the user to select an AI assistant (
copilot,claude,gemini). - Optionally checks if the required tools for the selected agent are installed.
- Downloads the latest template release from the
github/spec-kitrepository. - Extracts the template into a new project directory (or the current one if
--hereis used). - Initializes a Git repository unless
--no-gitis specified.
The sequence diagram below illustrates the specify init process.
Architectural Governance: The Constitution
The project's development process is governed by a "Constitution" (memory/constitution.md), which outlines a set of non-negotiable principles. These principles are designed to enforce modularity, testability, and simplicity. Contributors must ensure their changes adhere to this constitution.
Key principles include:
- Article I: Library-First: Every feature must begin as a standalone, reusable library.
- Article II: CLI Interface Mandate: Every library must expose its functionality via a command-line interface.
- Article III: Test-First Imperative: A strict Test-Driven Development (TDD) cycle (Red-Green-Refactor) is mandatory. Tests must be written and fail before implementation code is written.
- Article VII & VIII: Simplicity and Anti-Abstraction: Combat over-engineering by starting with the simplest possible solution and avoiding premature abstractions.
These principles are enforced through the project templates. For example, the plan-template.md includes a Constitution Check section that serves as a gate, forcing the planning phase to explicitly verify compliance with these articles.
Sources: spec-driven.md:239-307, memory/constitution.md, templates/plan-template.md:50-86
Conclusion
Contributing to Spec Kit means embracing the Spec-Driven Development methodology and its underlying principles. By following the structured workflow of /specify, /plan, and /tasks, and adhering to the project's constitution, contributors can help build high-quality, maintainable software. The process is designed to leverage AI agents effectively while maintaining strong architectural governance.
Sources: CONTRIBUTING.md, spec-driven.md