What Is Spec Kit? A Simple Guide to github/spec-kit for Spec-Driven Development

Image extracted from the official github/spec-kit repository, file media/logo_large.webp. This image is WebP, not SVG.¹

Quick summary

Spec Kit is GitHub’s open-source toolkit for getting started with Spec-Driven Development, or SDD. The official repository describes it as a toolkit that lets you focus on product scenarios and predictable outcomes instead of “vibe coding” every piece from scratch.²

In plain terms, instead of opening an AI coding agent and saying “build this app,” you use Spec Kit to follow a structured workflow:

Constitution → Spec → Clarify → Checklist → Plan → Tasks → Analyze → Implement

Each step produces Markdown artifacts that give your AI coding agent structured context. Spec Kit works with many agents, including GitHub Copilot, Claude Code, Codex CLI, Gemini CLI, Cursor, Kiro, Windsurf and others.³⁴

What is Spec-Driven Development?

Spec-Driven Development changes the role of specifications in software development. In the usual workflow, code is the primary truth and documents become secondary. In SDD, the specification becomes the source of truth, and code is generated, checked and evolved from that specification.⁵

The spec-driven.md document explains that SDD makes specifications and implementation plans precise enough to produce working systems, reducing the gap between product intent and implementation.⁵

Simple comparison:

What problem does Spec Kit solve?

AI coding agents are powerful, but they are easy to misdirect. If the request is vague, an agent may invent requirements, choose the wrong architecture, skip edge cases or start coding before understanding what users need.

Spec Kit reduces that risk through structured artifacts:

• Constitution: project principles and guardrails.
• Spec: user requirements, stories and success criteria.
• Clarify: resolves ambiguous requirements.
• Checklist: validates requirements quality.
• Plan: technical architecture and stack decisions.
• Tasks: implementation task list.
• Analyze: cross-checks spec, plan and tasks.
• Implement: runs the implementation process.

The official Quick Start recommends this production workflow:⁶

/speckit.constitution
  → /speckit.specify
  → /speckit.clarify
  → /speckit.checklist
  → /speckit.plan
  → /speckit.tasks
  → /speckit.analyze
  → /speckit.implement

What is inside the github/spec-kit repo?

The github/spec-kit repository is a public MIT-licensed repository described as a toolkit for starting with Spec-Driven Development. At the time accessed, the GitHub page showed more than 100k stars.⁷ The documentation home page says Spec Kit helps you “define what to build before building it” with any AI coding agent.³

Main parts:

What Spec Kit is not

Spec Kit does not design your product for you. It helps you express the product clearly enough that your agent can implement it with fewer wrong assumptions.

When should you use Spec Kit?

Use it when:

• you use AI coding agents for real features;
• requirements include user flows, edge cases or constraints;
• your team wants specs, plans and tasks stored in Git;
• you want fewer AI-generated assumptions;
• projects need testing, security, UX or performance guardrails;
• multiple agents/tools must understand the same workflow;
• your team wants a repeatable way to write specs.

You may not need it when:

• the change is very small;
• you are only editing copy or simple CSS;
• you are doing a throwaway experiment;
• the team is not ready to review spec artifacts;
• you are not using an AI coding agent.

Installation

Prerequisites

The Installation Guide lists these requirements:⁸

• Linux/macOS or Windows; PowerShell scripts are supported without WSL.
• A supported AI coding agent.
• uv recommended, or pipx for persistent installation.
• Python 3.11+.
• Git.

Important package warning

The Installation Guide states that the only official maintained Spec Kit packages come from the github/spec-kit GitHub repository. Packages with the same name on PyPI, such as specify-cli, are not affiliated with the project and are not maintained by Spec Kit maintainers.⁸

So do not install Spec Kit like this:

pip install specify-cli

unless you are using a wheel that you built internally from the official repository.

Persistent installation with uv

Replace vX.Y.Z with the latest release tag:

uv tool install specify-cli --from git+https://github.com/github/[email protected]

Verify:

specify version

The docs say specify version helps confirm that you are running the official GitHub-based build rather than an unrelated package with the same name.⁸

One-time usage with uvx

If you do not want a persistent install:

uvx --from git+https://github.com/github/spec-kit.git specify init my-project

Or initialize the current directory:

uvx --from git+https://github.com/github/spec-kit.git specify init .

The official Quick Start shows these commands as the first step.⁶

pipx installation

pipx install git+https://github.com/github/spec-kit.git

Then run:

specify init my-project
specify init .

Initialize a project

GitHub Copilot:

specify init my-project --integration copilot
cd my-project

Claude Code:

specify init my-project --integration claude
cd my-project

Codex CLI:

specify init my-project --integration codex
cd my-project

Gemini CLI:

specify init my-project --integration gemini
cd my-project

Current directory:

specify init . --integration copilot

Merge into a non-empty directory:

specify init . --force --integration copilot

The Installation Guide says interactive terminals prompt you to choose an integration. Non-interactive sessions default to GitHub Copilot unless you pass --integration.⁸

Bash and PowerShell scripts

Spec Kit generates automation scripts for different shells. The Installation Guide says both Bash .sh and PowerShell .ps1 variants are now provided.⁸

Defaults:

• Windows: ps
• Other OS: sh

Force Bash:

specify init my-project --script sh

Force PowerShell:

specify init my-project --script ps

Generated scripts live in:

.specify/scripts/bash/
.specify/scripts/powershell/

The workflow in plain English

Step 1: Constitution

The constitution is the rulebook for your project.

Example:

/speckit.constitution
This project prioritizes security, test-first development, readable code,
and minimal over-engineering. Every feature needs tests. APIs need validation.

This creates or updates:

.specify/memory/constitution.md

The README explains that the constitution guides later specification, planning and implementation phases.²

Step 2: Specify

This is where you describe what to build and why, without focusing on the technology stack.

Example:

/speckit.specify
Build a team task management app. Users can create projects, create tasks,
drag tasks across To Do, In Progress, In Review and Done, comment on tasks,
and assign tasks to team members.

The Quick Start emphasizes focusing on what and why, not the tech stack, during the specification phase.⁶

Step 3: Clarify

This step reduces ambiguity.

Example:

/speckit.clarify
Clarify comment edit permissions, team member limits, and how unassigned tasks work.

Use this step to prevent the agent from guessing.

Step 4: Checklist

Validate the spec quality:

/speckit.checklist

If the checklist finds problems, refine the spec before planning.

Step 5: Plan

This translates product requirements into technical decisions.

Example:

/speckit.plan
Use Next.js, PostgreSQL, Prisma, REST API and Tailwind CSS. The task board
must support drag and drop. Store project, user, task, comment and activity-log data.

Step 6: Tasks

Generate an implementation task list:

/speckit.tasks

Tasks can later be used by the agent, converted to issues, or reviewed by the team.

Step 7: Analyze

Check consistency between artifacts:

/speckit.analyze

The Quick Start recommends running /speckit.analyze before implementation so gaps are caught while plan and tasks are still easy to adjust.⁶

Step 8: Implement

Only now does the agent build the feature:

/speckit.implement

For large features, the Quick Start recommends phased implementation to avoid overwhelming the agent context.⁶

Core commands

The README lists these main and optional commands:²

AI coding agent integrations

Spec Kit supports many AI coding agents. The integrations docs say specify init sets up the right command files, context rules and directory structure for the chosen agent.⁴

Some integration keys:

List integrations:

specify integration list

Install another integration in an existing project:

specify integration install claude

Switch default integration:

specify integration switch codex

Use an installed integration:

specify integration use copilot

Uninstall:

specify integration uninstall claude

Some integrations are skill-based. The docs state that Claude Code installs skills into .claude/skills, Codex CLI installs skills into .agents/skills and invokes them as $speckit-<command>, and Hermes installs skills globally into ~/.hermes/skills/.⁴

Generic integration

If your agent is not listed, use generic:

specify init my-project --integration generic --integration-options="--commands-dir .myagent/cmds"

Or in an existing project:

specify integration install generic --integration-options="--commands-dir .myagent/cmds"

Use this when your tool supports command/prompt files but does not yet have an official Spec Kit integration.

Extensions and presets

Spec Kit can be customized through extensions and presets.

Extensions

Extensions add new capabilities, commands or workflow phases. The README gives examples such as Jira integration, post-implementation code review, V-Model test traceability and project health diagnostics.²

specify extension search
specify extension add <extension-name>

Use extensions when you want:

• a new command;
• integration with external systems;
• a new review step;
• a domain-specific workflow;
• a new quality gate.

Presets

Presets customize existing templates and workflows. The README says presets can enforce compliance-oriented spec formats, domain terminology, security review gates, test-first task ordering or localization.²

specify preset search
specify preset add <preset-name>

Use presets when you want:

• custom spec/plan/task templates;
• organizational standards;
• domain terminology;
• compliance requirements;
• the same workflow across many repositories.

Which should you choose?

Typical file structure

A project using Spec Kit often contains:

.specify/
  memory/
    constitution.md
  scripts/
    bash/
    powershell/
  templates/
specs/
  001-feature-name/
    spec.md
    plan.md
    tasks.md
    research.md
    data-model.md
    contracts/
    quickstart.md

Not every file appears immediately. Some files are created after /speckit.plan or /speckit.tasks.

Meaning:

• .specify/ contains workflow configuration.
• constitution.md stores project rules.
• specs/<feature>/spec.md stores feature requirements.
• plan.md stores technical decisions.
• tasks.md stores implementation tasks.
• contracts/ stores API contracts when generated.
• quickstart.md stores validation scenarios.

Personal usage guide

Recommended flow:

# 1. Install Specify CLI from the official repo
uv tool install specify-cli --from git+https://github.com/github/[email protected]

# 2. Verify
specify version

# 3. Create a project
specify init my-project --integration copilot
cd my-project

# 4. Open your coding agent
# 5. Run the workflow in chat
/speckit.constitution ...
/speckit.specify ...
/speckit.clarify ...
/speckit.checklist
/speckit.plan ...
/speckit.tasks
/speckit.analyze
/speckit.implement

One-time initialization:

uvx --from git+https://github.com/github/spec-kit.git specify init my-project --integration copilot

Team rollout guide

Phase 1: pilot on one repo

• Choose one medium-size feature.
• Initialize Spec Kit in the repository.
• Choose one default integration: copilot, claude, codex or another supported agent.
• Write a short constitution.
• Run the full flow: spec → clarify → checklist → plan → tasks → analyze → implement.
• Review the generated PR normally.

Phase 2: standardize the constitution

Example constitution rules:

- Every feature needs tests.
- New dependencies require justification.
- APIs must validate input.
- Do not store secrets in the repo.
- Prefer simple, readable code.
- Performance-sensitive paths need measurable criteria.

Use /speckit.constitution to encode these rules in .specify/memory/constitution.md.

Phase 3: standardize branch/spec flow

Recommended pattern:

main
  └── 001-user-auth
        ├── specs/001-user-auth/spec.md
        ├── plan.md
        ├── tasks.md
        └── implementation PR

The Quick Start says Spec Kit commands automatically detect the active feature from the current Git branch, such as 001-feature-name; switching branches switches the active specification.⁶

Phase 4: use analyze as a quality gate

Before implementation:

/speckit.analyze

A team can require:

• no unresolved [NEEDS CLARIFICATION];
• checklist passed;
• plan includes clear constraints;
• tasks are small enough;
• analyze does not find major contradictions.

Phase 5: add presets and extensions

After the basic workflow works:

• use presets to enforce company templates;
• use extensions for Jira, security review, compliance or architecture guard;
• host internal catalogs in enterprise/air-gapped environments.

The docs home says Spec Kit works offline, behind firewalls, and on Windows/macOS/Linux, and organizations can host their own extension and preset catalogs.³

Security and governance notes

Spec Kit creates prompts, command files and process artifacts for AI coding agents. That does not make the workflow automatically safe.

Use these practices:

• Do not put API keys, tokens or private keys in specs, plans or tasks.
• Review .specify/, specs/, .claude/, .agents/ and command files before committing sensitive content.
• Do not let agents run production deploys, migrations or destructive commands without approval.
• Always use feature branches.
• Do not install similarly named packages from PyPI; the Installation Guide warns that those are not official.⁸
• Review community extensions and presets before using them. The README notes that community contributions are independently created and maintained, so you should review source code and use them at your own discretion.²
• Keep CI/tests in place. Spec Kit does not replace test suites.
• In enterprises, prefer internal extension/preset catalogs.

When is the workflow too heavy?

For a very small change, the full process may be more than you need.

Lean path:

/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement

Full path:

/speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.checklist
→ /speckit.plan → /speckit.tasks → /speckit.analyze → /speckit.implement

The Quick Start explicitly says quick experiments can use the lean path, while production features or ambiguous work should treat clarify, checklist and analyze as regular quality gates.⁶

Spec Kit vs direct AI coding

Spec Kit vs RTK, Headroom, MarkItDown and PaddleOCR

Spec Kit operates at the software development process layer, not the token-compression or document-conversion layer.

FAQ

What is Spec Kit?

Spec Kit is GitHub’s open-source toolkit for Spec-Driven Development. It structures AI-assisted software development around specs, plans, tasks and implementation commands.⁷³

What is Spec-Driven Development?

SDD is a development methodology where specifications are the source of truth and code is generated, checked and evolved from those specifications.⁵

Does Spec Kit require GitHub Copilot?

No. Spec Kit supports many AI coding agents, including GitHub Copilot, Claude Code, Codex CLI, Gemini CLI, Cursor, Kiro, Windsurf and others.⁴

Can I install Spec Kit from PyPI?

The official docs warn that packages with the same name on PyPI are not affiliated with the project. The recommended installation path uses the GitHub repository through uv, uvx or pipx.⁸

Does Spec Kit work on Windows?

Yes. The Installation Guide says Windows is supported and PowerShell scripts work without WSL.⁸

Which commands matter most?

The core commands are /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks and /speckit.implement. For production work, add /speckit.clarify, /speckit.checklist and /speckit.analyze.²⁶

Conclusion

github/spec-kit is important because it makes AI coding less ad hoc. Instead of relying on a single prompt and hoping the agent understands, Spec Kit turns the process into a sequence of reviewable Markdown artifacts: constitution, spec, checklist, plan, tasks and analysis.

For beginners, start with one small feature and run the full workflow once. For teams, the main value is that specs, plans and tasks become versioned artifacts that can be reviewed like code, making AI-generated implementation more predictable and less dependent on one-off chat context.

References

Footnotes

1. GitHub raw asset. github/spec-kit/media/logo_large.webp. https://github.com/github/spec-kit/raw/main/media/logo_large.webp ↩

2. GitHub Spec Kit README. https://raw.githubusercontent.com/github/spec-kit/main/README.md ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷

3. GitHub Spec Kit Documentation home. https://github.github.io/spec-kit/ ↩ ↩² ↩³ ↩⁴

4. Spec Kit Supported AI Coding Agent Integrations. https://github.github.io/spec-kit/reference/integrations.html ↩ ↩² ↩³ ↩⁴

5. spec-driven.md, Specification-Driven Development methodology. https://raw.githubusercontent.com/github/spec-kit/main/spec-driven.md ↩ ↩² ↩³

6. Spec Kit Quick Start Guide. https://github.github.io/spec-kit/quickstart.html ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸

7. GitHub. github/spec-kit. https://github.com/github/spec-kit ↩ ↩²

8. Spec Kit Installation Guide. https://github.github.io/spec-kit/installation.html ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸