Skip to content
Get packs

Guide · Open source

How to use spec-kit: install, run the SDD flow and fix bugs

Updated · written with AI from the project's own documentation and checked against our catalogue data

Spec Kit is an open source toolkit that gives AI coding agents structured processes, reusable templates, and documented outcomes, so the agent works from a written specification instead of a loose prompt. It is aimed at developers who already use a supported AI coding agent and want more predictable results. By the end of this guide you will be able to install the Specify CLI, create a project, and run the basic spec-to-code workflow, plus the optional bug-fixing extension.

Spec Kitgithub/spec-kit · ★ 145k · MIT

Quick start

  1. 1Install the Specify CLI. Run uv tool install specify-cli in your terminal. This requires Python 3.11+ and uv.
  2. 2Create a project. Run specify init my-project --integration copilot to create a project for your agent. The example uses GitHub Copilot.
  3. 3Enter the project directory. Run cd my-project, then launch your coding agent from that folder.
  4. 4Create a constitution. In the agent chat, run /speckit-constitution with your project principles. You do this once per project.
  5. 5Specify, plan and break down the work. Run /speckit-specify, /speckit-plan and /speckit-tasks in the agent chat, reviewing each result before continuing.
  6. 6Implement and converge. Run /speckit-implement, then /speckit-converge. Repeat until convergence reports Converged.
  7. 7Optionally add the bug-fixing extension. Run specify extension add bug, then use the bug-fix skills and check that the final verdict is verified.

What do you need before you install Spec Kit?

You need Python 3.11 or newer, uv, and a supported AI coding agent on Linux, macOS, or Windows. The toolkit is built around a coding agent, so it does not do much on its own.

Setup happens in a terminal, and the process assumes some software knowledge. Beginners without a coding background will find it hard going.

  • Python 3.11+
  • uv (installation guide linked from the official docs)
  • A supported AI coding agent. The README example uses GitHub Copilot.

How do you install the Specify CLI and create a project?

Run these commands in your terminal. The example creates a project called my-project and uses GitHub Copilot as the agent.

After installing and creating the project, launch your coding agent in the project directory and choose a process from there.

  • For pinned releases, other installers, CI, and troubleshooting, see the official Installation page.
  • To start with code you already have, see the Existing projects guide.
  • To update an existing installation, see the Upgrade page.
uv tool install specify-cli specify init my-project --integration copilot cd my-project

How does Spec-Driven Development work?

Spec-Driven Development (SDD) moves from a specification to a plan, tasks, and working code. You create a constitution once per project, then repeat the other steps for each feature.

Run these commands in your agent's chat, not in your terminal, one at a time. Review each result before you continue. The example uses GitHub Copilot's default skills syntax; other agents have their own invocation syntax.

Repeat implement and converge until convergence reports Converged. For clarification, checklists, and consistency analysis, see the SDD walkthrough.

  • /speckit-constitution sets the project principles.
  • /speckit-specify describes what to build.
  • /speckit-plan sets the technical approach.
  • /speckit-tasks breaks the plan into tasks.
  • /speckit-implement writes the code.
  • /speckit-converge checks the result.
/speckit-constitution Create principles focused on code quality, testing, and maintainability. /speckit-specify Build a photo organizer with albums grouped by date and a tile preview of each album. /speckit-plan Use Vite with vanilla JavaScript. Keep images local and store metadata in SQLite. /speckit-tasks /speckit-implement /speckit-converge

How do you fix a bug with the bug-fixing extension?

Bug fixing is a separate entry point. It assesses the cause, fixes the bug, and verifies that the original symptom is resolved. No SDD feature workflow is required first.

Install the extension from the project directory, then run the skills in your agent's chat. The reports are saved in .specify/bugs/login-crash/ in the example. The final verdict is verified, partial, or failed; only verified confirms a successful fix.

  • Install the extension: specify extension add bug (optional).
  • Assess the cause, then fix, then test, using the slug to group the reports.
  • Check the verdict in the report folder before treating the bug as fixed.
specify extension add bug /speckit-bug-assess "Submitting an empty password crashes the login form." slug=login-crash /speckit-bug-fix slug=login-crash /speckit-bug-test slug=login-crash

How do you customize Spec Kit for your own process?

Spec Kit provides composable mechanisms for adapting it. Integrations connect to or switch between coding agents. Presets adapt templates, commands, terminology, or methodology. Project-local overrides replace a template for one project. Workflows automate prompts, commands, gates, and shell tasks.

Catalogs let you discover community components. The README notes that catalog listings are not audits or endorsements, so review community source code before you install or run it.

  • Integration: connect to or switch between coding agents.
  • Extension: add a command, quality gate, or complete process.
  • Preset: adapt templates, commands, terminology, or methodology.
  • Workflow: automate prompts, commands, gates, and shell tasks.
  • Catalog: discover community components or host a private catalog.
  • Search commands include specify extension search, specify preset search, specify workflow search, and specify bundle search.

What people use it for

  • Building a new feature or application from a written spec, plan and tasks before the agent writes code.
  • Diagnosing a bug: the agent assesses the cause, applies a scoped fix and records verification.
  • Adapting templates or terminology to your team's methodology with presets.
  • Enforcing organisational standards through a private catalog of approved components.
  • Running a workflow offline or behind a firewall using local sources and self-hosted catalogs.

Frequently asked questions

Is spec-kit free to use?

Spec Kit is released under the MIT licence, as listed in the project's details. Check the LICENSE file in the repository for the full terms.

What do I need to install spec-kit?

You need Python 3.11 or newer, uv, and a supported AI coding agent. The README example installs the Specify CLI with uv tool install specify-cli.

Which AI coding agents does spec-kit support?

The README example uses GitHub Copilot, and the docs link to integration keys for other agents. The toolkit is built around a supported coding agent, so you need one to use it.

Why does spec-kit say to run commands in the chat instead of the terminal?

The /speckit commands are skills that run inside your agent's chat. Only the specify and uv commands run in your terminal.

How do I know if a bug fix really worked?

The bug-fixing extension gives a final verdict of verified, partial, or failed. Only verified confirms a successful fix, so check the reports in the bug folder.

Are the community extensions safe to install?

Catalog listings are not audits or endorsements. The README advises reviewing community source code before installing or running it.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Spec Kit suits developers who already use a supported AI coding agent and want written specifications, plans and verified bug fixes to guide its output. It is less suited to people who want a quick one-off script or who have no coding background, since setup happens in a terminal and the process adds a layer to the project.

Install options & downloads