- Notifications
You must be signed in to change notification settings - Fork2.8k
💫 Toolkit to help you get started with Spec-Driven Development
License
github/spec-kit
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
An effort to allow organizations to focus on product scenarios rather than writing undifferentiated code with the help of Spec-Driven Development.
- 🤔 What is Spec-Driven Development?
- ⚡ Get started
- 📽️ Video Overview
- 🤖 Supported AI Agents
- 🔧 Specify CLI Reference
- 📚 Core philosophy
- 🌟 Development phases
- 🎯 Experimental goals
- 🔧 Prerequisites
- 📖 Learn more
- 📋 Detailed process
- 🔍 Troubleshooting
- 👥 Maintainers
- 💬 Support
- 🙏 Acknowledgements
- 📄 License
Spec-Driven Developmentflips the script on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this:specifications become executable, directly generating working implementations rather than just guiding them.
Choose your preferred installation method:
Install once and use everywhere:
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
Then use the tool directly:
specify init<PROJECT_NAME>specify check
Run directly without installing:
uvx --from git+https://github.com/github/spec-kit.git specify init<PROJECT_NAME>
Benefits of persistent installation:
- Tool stays installed and available in PATH
- No need to create shell aliases
- Better tool management with
uv tool list
,uv tool upgrade
,uv tool uninstall
- Cleaner shell configuration
Use the/speckit.constitution
command to create your project's governing principles and development guidelines that will guide all subsequent development.
/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements
Use the/speckit.specify
command to describe what you want to build. Focus on thewhat andwhy, not the tech stack.
/speckit.specify Build an application that canhelp me organize my photosin separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are neverin other nested albums. Within each album, photos are previewedin a tile-like interface.
Use the/speckit.plan
command to provide your tech stack and architecture choices.
/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is storedin alocal SQLite database.
Use/speckit.tasks
to create an actionable task list from your implementation plan.
/speckit.tasks
Use/speckit.implement
to execute all tasks and build your feature according to the plan.
/speckit.implement
For detailed step-by-step instructions, see ourcomprehensive guide.
Want to see Spec Kit in action? Watch ourvideo overview!
Agent | Support | Notes |
---|---|---|
Claude Code | ✅ | |
GitHub Copilot | ✅ | |
Gemini CLI | ✅ | |
Cursor | ✅ | |
Qwen Code | ✅ | |
opencode | ✅ | |
Windsurf | ✅ | |
Kilo Code | ✅ | |
Auggie CLI | ✅ | |
Roo Code | ✅ | |
Codex CLI | ✅ | |
Amazon Q Developer CLI | Amazon Q Developer CLIdoes not support custom arguments for slash commands. |
Thespecify
command supports the following options:
Command | Description |
---|---|
init | Initialize a new Specify project from the latest template |
check | Check for installed tools (git ,claude ,gemini ,code /code-insiders ,cursor-agent ,windsurf ,qwen ,opencode ,codex ) |
Argument/Option | Type | Description |
---|---|---|
<project-name> | Argument | Name for your new project directory (optional if using--here , or use. for current directory) |
--ai | Option | AI assistant to use:claude ,gemini ,copilot ,cursor ,qwen ,opencode ,codex ,windsurf ,kilocode ,auggie ,roo , orq |
--script | Option | Script variant to use:sh (bash/zsh) orps (PowerShell) |
--ignore-agent-tools | Flag | Skip checks for AI agent tools like Claude Code |
--no-git | Flag | Skip git repository initialization |
--here | Flag | Initialize project in the current directory instead of creating a new one |
--force | Flag | Force merge/overwrite when initializing in current directory (skip confirmation) |
--skip-tls | Flag | Skip SSL/TLS verification (not recommended) |
--debug | Flag | Enable detailed debug output for troubleshooting |
--github-token | Option | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable) |
# Basic project initializationspecify init my-project# Initialize with specific AI assistantspecify init my-project --ai claude# Initialize with Cursor supportspecify init my-project --ai cursor# Initialize with Windsurf supportspecify init my-project --ai windsurf# Initialize with PowerShell scripts (Windows/cross-platform)specify init my-project --ai copilot --script ps# Initialize in current directoryspecify init. --ai copilot# or use the --here flagspecify init --here --ai copilot# Force merge into current (non-empty) directory without confirmationspecify init. --force --ai copilot# orspecify init --here --force --ai copilot# Skip git initializationspecify init my-project --ai gemini --no-git# Enable debug output for troubleshootingspecify init my-project --ai claude --debug# Use GitHub token for API requests (helpful for corporate environments)specify init my-project --ai claude --github-token ghp_your_token_here# Check system requirementsspecify check
After runningspecify init
, your AI coding agent will have access to these slash commands for structured development:
Essential commands for the Spec-Driven Development workflow:
Command | Description |
---|---|
/speckit.constitution | Create or update project governing principles and development guidelines |
/speckit.specify | Define what you want to build (requirements and user stories) |
/speckit.plan | Create technical implementation plans with your chosen tech stack |
/speckit.tasks | Generate actionable task lists for implementation |
/speckit.implement | Execute all tasks to build the feature according to the plan |
Additional commands for enhanced quality and validation:
Command | Description |
---|---|
/speckit.clarify | Clarify underspecified areas (recommended before/speckit.plan ; formerly/quizme ) |
/speckit.analyze | Cross-artifact consistency & coverage analysis (run after/speckit.tasks , before/speckit.implement ) |
/speckit.checklist | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") |
Variable | Description |
---|---|
SPECIFY_FEATURE | Override feature detection for non-Git repositories. Set to the feature directory name (e.g.,001-photo-albums ) to work on a specific feature when not using Git branches.**Must be set in the context of the agent you're working with prior to using /speckit.plan or follow-up commands. |
Spec-Driven Development is a structured process that emphasizes:
- Intent-driven development where specifications define the "what" before the "how"
- Rich specification creation using guardrails and organizational principles
- Multi-step refinement rather than one-shot code generation from prompts
- Heavy reliance on advanced AI model capabilities for specification interpretation
Phase | Focus | Key Activities |
---|---|---|
0-to-1 Development ("Greenfield") | Generate from scratch |
|
Creative Exploration | Parallel implementations |
|
Iterative Enhancement ("Brownfield") | Brownfield modernization |
|
Our research and experimentation focus on:
- Create applications using diverse technology stacks
- Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks
- Demonstrate mission-critical application development
- Incorporate organizational constraints (cloud providers, tech stacks, engineering practices)
- Support enterprise design systems and compliance requirements
- Build applications for different user cohorts and preferences
- Support various development approaches (from vibe-coding to AI-native development)
- Validate the concept of parallel implementation exploration
- Provide robust iterative feature development workflows
- Extend processes to handle upgrades and modernization tasks
- Linux/macOS (or WSL2 on Windows)
- AI coding agent:Claude Code,GitHub Copilot,Gemini CLI,Cursor,Qwen CLI,opencode,Codex CLI,Windsurf, orAmazon Q Developer CLI
- uv for package management
- Python 3.11+
- Git
If you encounter issues with an agent, please open an issue so we can refine the integration.
- Complete Spec-Driven Development Methodology - Deep dive into the full process
- Detailed Walkthrough - Step-by-step implementation guide
Click to expand the detailed step-by-step walkthrough
You can use the Specify CLI to bootstrap your project, which will bring in the required artifacts in your environment. Run:
specify init<project_name>
Or initialize in the current directory:
specify init.# or use the --here flagspecify init --here# Skip confirmation when the directory already has filesspecify init. --force# orspecify init --here --force
You will be prompted to select the AI agent you are using. You can also proactively specify it directly in the terminal:
specify init<project_name> --ai claudespecify init<project_name> --ai geminispecify init<project_name> --ai copilot# Or in current directory:specify init. --ai claudespecify init. --ai codex# or use --here flagspecify init --here --ai claudespecify init --here --ai codex# Force merge into a non-empty current directoryspecify init. --force --ai claude# orspecify init --here --force --ai claude
The CLI will check if you have Claude Code, Gemini CLI, Cursor CLI, Qwen CLI, opencode, Codex CLI, or Amazon Q Developer CLI installed. If you do not, or you prefer to get the templates without checking for the right tools, use--ignore-agent-tools
with your command:
specify init<project_name> --ai claude --ignore-agent-tools
Go to the project folder and run your AI agent. In our example, we're usingclaude
.
You will know that things are configured correctly if you see the/speckit.constitution
,/speckit.specify
,/speckit.plan
,/speckit.tasks
, and/speckit.implement
commands available.
The first step should be establishing your project's governing principles using the/speckit.constitution
command. This helps ensure consistent decision-making throughout all subsequent development phases:
/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. Include governance for how these principles should guide technical decisions and implementation choices.
This step creates or updates the.specify/memory/constitution.md
file with your project's foundational guidelines that the AI agent will reference during specification, planning, and implementation phases.
With your project principles established, you can now create the functional specifications. Use the/speckit.specify
command and then provide the concrete requirements for the project you want to develop.
[!IMPORTANT]Be as explicit as possible aboutwhat you are trying to build andwhy.Do not focus on the tech stack at this point.
An example prompt:
Develop Taskify, a team productivity platform. It should allow users to create projects, add team members,assign tasks, comment and move tasks between boards in Kanban style. In this initial phase for this feature,let's call it "Create Taskify," let's have multiple users but the users will be declared ahead of time, predefined.I want five users in two different categories, one product manager and four engineers. Let's create threedifferent sample projects. Let's have the standard Kanban columns for the status of each task, such as "To Do,""In Progress," "In Review," and "Done." There will be no login for this application as this is just the veryfirst testing thing to ensure that our basic features are set up. For each task in the UI for a task card,you should be able to change the current status of the task between the different columns in the Kanban work board.You should be able to leave an unlimited number of comments for a particular card. You should be able to, from that taskcard, assign one of the valid users. When you first launch Taskify, it's going to give you a list of the five users to pickfrom. There will be no password required. When you click on a user, you go into the main view, which displays the list ofprojects. When you click on a project, you open the Kanban board for that project. You're going to see the columns.You'll be able to drag and drop cards back and forth between different columns. You will see any cards that areassigned to you, the currently logged in user, in a different color from all the other ones, so you can quicklysee yours. You can edit any comments that you make, but you can't edit comments that other people made. You candelete any comments that you made, but you can't delete comments anybody else made.
After this prompt is entered, you should see Claude Code kick off the planning and spec drafting process. Claude Code will also trigger some of the built-in scripts to set up the repository.
Once this step is completed, you should have a new branch created (e.g.,001-create-taskify
), as well as a new specification in thespecs/001-create-taskify
directory.
The produced specification should contain a set of user stories and functional requirements, as defined in the template.
At this stage, your project folder contents should resemble the following:
└── .specify ├── memory │ └── constitution.md ├── scripts │ ├── check-prerequisites.sh │ ├── common.sh │ ├── create-new-feature.sh │ ├── setup-plan.sh │ └── update-claude-md.sh ├── specs │ └── 001-create-taskify │ └── spec.md └── templates ├── plan-template.md ├── spec-template.md └── tasks-template.md
With the baseline specification created, you can go ahead and clarify any of the requirements that were not captured properly within the first shot attempt.
You should run the structured clarification workflowbefore creating a technical plan to reduce rework downstream.
Preferred order:
- Use
/speckit.clarify
(structured) – sequential, coverage-based questioning that records answers in a Clarifications section. - Optionally follow up with ad-hoc free-form refinement if something still feels vague.
If you intentionally want to skip clarification (e.g., spike or exploratory prototype), explicitly state that so the agent doesn't block on missing clarifications.
Example free-form refinement prompt (after/speckit.clarify
if still needed):
For each sample project or project that you create there should be a variable number of tasks between 5 and 15tasks for each one randomly distributed into different states of completion. Make sure that there's at leastone task in each stage of completion.
You should also ask Claude Code to validate theReview & Acceptance Checklist, checking off the things that are validated/pass the requirements, and leave the ones that are not unchecked. The following prompt can be used:
Read the review and acceptance checklist, and check off each item in the checklist if the feature spec meets the criteria. Leave it empty if it does not.
It's important to use the interaction with Claude Code as an opportunity to clarify and ask questions around the specification -do not treat its first attempt as final.
You can now be specific about the tech stack and other technical requirements. You can use the/speckit.plan
command that is built into the project template with a prompt like this:
We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should useBlazor server with drag-and-drop task boards, real-time updates. There should be a REST API created with a projects API,tasks API, and a notifications API.
The output of this step will include a number of implementation detail documents, with your directory tree resembling this:
.├── CLAUDE.md├── memory│ └── constitution.md├── scripts│ ├── check-prerequisites.sh│ ├── common.sh│ ├── create-new-feature.sh│ ├── setup-plan.sh│ └── update-claude-md.sh├── specs│ └── 001-create-taskify│ ├── contracts│ │ ├── api-spec.json│ │ └── signalr-spec.md│ ├── data-model.md│ ├── plan.md│ ├── quickstart.md│ ├── research.md│ └── spec.md└── templates ├── CLAUDE-template.md ├── plan-template.md ├── spec-template.md └── tasks-template.md
Check theresearch.md
document to ensure that the right tech stack is used, based on your instructions. You can ask Claude Code to refine it if any of the components stand out, or even have it check the locally-installed version of the platform/framework you want to use (e.g., .NET).
Additionally, you might want to ask Claude Code to research details about the chosen tech stack if it's something that is rapidly changing (e.g., .NET Aspire, JS frameworks), with a prompt like this:
I want you to go through the implementation plan and implementation details, looking for areas that couldbenefit from additional research as .NET Aspire is a rapidly changing library. For those areas that you identify thatrequire further research, I want you to update the research document with additional details about the specificversions that we are going to be using in this Taskify application and spawn parallel research tasks to clarifyany details using research from the web.
During this process, you might find that Claude Code gets stuck researching the wrong thing - you can help nudge it in the right direction with a prompt like this:
I think we need to break this down into a series of steps. First, identify a list of tasksthat you would need to do during implementation that you're not sure of or would benefitfrom further research. Write down a list of those tasks. And then for each one of these tasks,I want you to spin up a separate research task so that the net results is we are researchingall of those very specific tasks in parallel. What I saw you doing was it looks like you wereresearching .NET Aspire in general and I don't think that's gonna do much for us in this case.That's way too untargeted research. The research needs to help you solve a specific targeted question.
[!NOTE]Claude Code might be over-eager and add components that you did not ask for. Ask it to clarify the rationale and the source of the change.
With the plan in place, you should have Claude Code run through it to make sure that there are no missing pieces. You can use a prompt like this:
Now I want you to go and audit the implementation plan and the implementation detail files.Read through it with an eye on determining whether or not there is a sequence of tasks that you needto be doing that are obvious from reading this. Because I don't know if there's enough here. For example,when I look at the core implementation, it would be useful to reference the appropriate places in the implementationdetails where it can find the information as it walks through each step in the core implementation or in the refinement.
This helps refine the implementation plan and helps you avoid potential blind spots that Claude Code missed in its planning cycle. Once the initial refinement pass is complete, ask Claude Code to go through the checklist once more before you can get to the implementation.
You can also ask Claude Code (if you have theGitHub CLI installed) to go ahead and create a pull request from your current branch tomain
with a detailed description, to make sure that the effort is properly tracked.
[!NOTE]Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows theconstitution as the foundational piece that it must adhere to when establishing the plan.
Once ready, use the/speckit.implement
command to execute your implementation plan:
/speckit.implement
The/speckit.implement
command will:
- Validate that all prerequisites are in place (constitution, spec, plan, and tasks)
- Parse the task breakdown from
tasks.md
- Execute tasks in the correct order, respecting dependencies and parallel execution markers
- Follow the TDD approach defined in your task plan
- Provide progress updates and handle errors appropriately
[!IMPORTANT]The AI agent will execute local CLI commands (such as
dotnet
,npm
, etc.) - make sure you have the required tools installed on your machine.
Once the implementation is complete, test the application and resolve any runtime errors that may not be visible in CLI logs (e.g., browser console errors). You can copy and paste such errors back to your AI agent for resolution.
If you're having issues with Git authentication on Linux, you can install Git Credential Manager:
#!/usr/bin/env bashset -eecho"Downloading Git Credential Manager v2.6.1..."wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.debecho"Installing Git Credential Manager..."sudo dpkg -i gcm-linux_amd64.2.6.1.debecho"Configuring Git to use GCM..."git config --global credential.helper managerecho"Cleaning up..."rm gcm-linux_amd64.2.6.1.deb
For support, please open aGitHub issue. We welcome bug reports, feature requests, and questions about using Spec-Driven Development.
This project is heavily influenced by and based on the work and research ofJohn Lam.
This project is licensed under the terms of the MIT open source license. Please refer to theLICENSE file for the full terms.
About
💫 Toolkit to help you get started with Spec-Driven Development
Topics
Resources
License
Code of conduct
Contributing
Security policy
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Uh oh!
There was an error while loading.Please reload this page.