Spec Kit — Spec-Driven Development

Overview

Spec Kit provides a structured, spec-driven development (SDD) workflow for AI coding agents. Instead of jumping straight to code, you create a specification first, then plan, break down tasks, implement, and verify — all guided by slash commands that your agent runs step by step.

Core principles

Specify before you code — define what the feature does before deciding how to build it.
Plan before you task — choose the tech stack and architecture after requirements are clear.
Task before you implement — break work into small, dependency-ordered, independently verifiable steps.
Verify before you ship — analyze artifacts for consistency, then converge to confirm nothing was missed.

Prerequisites

Linux/macOS (or Windows with PowerShell support)
OpenCode AI coding agent
uv for package management (recommended) or pipx for persistent installation
Python 3.11+
Git (optional — required only when the git extension is enabled)

Installation

Spec Kit is distributed through two official channels: the github/spec-kit GitHub repository (source install) and the specify-cli package on PyPI. After installing, run specify version as a local version/runtime sanity check.

Install from source — persistent installation (recommended)

Install once and use everywhere. Replace vX.Y.Z with a release tag from Releases:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Install from PyPI

# Using uv (recommended)
uv tool install specify-cli

# Or using pipx
pipx install specify-cli

To install a specific release, pin the version — for example uv tool install specify-cli==0.12.11.

One-time usage

Run directly without installing:

uvx specify-cli init . --integration opencode --script sh --ignore-agent-tools

Initialize a Spec Kit project

Once the specify CLI is installed, initialize a project with specify init:

specify init . --integration opencode --script sh --ignore-agent-tools

This scaffolds the current directory (.) with the scripts and templates your coding agent needs to run the spec-driven development workflow. The flags do the following:

--integration opencode — targets OpenCode slash commands and conventions
--script sh — generates Bash scripts (.sh) instead of prompting interactively
--ignore-agent-tools — skips the agent tools check when scaffolding templates

What you get after initialization

After running specify init, your project will have:

my-project/
├── .speckit/
│   └── constitution.md
├── .specify/
│   └── scripts/
│       ├── bash/        # .sh scripts (default on Linux/macOS)
│       ├── powershell/  # .ps1 scripts (default on Windows)
│       └── python/      # .py scripts (chosen with --script py)

The following slash commands become available in your coding agent:

/speckit.specify — Create specifications
/speckit.plan — Generate implementation plans
/speckit.tasks — Break down into actionable tasks
/speckit.implement — Execute implementation tasks
/speckit.analyze — Validate cross-artifact consistency
/speckit.clarify — Identify and resolve ambiguities
/speckit.checklist — Generate quality checklists
/speckit.constitution — Create or update project principles
/speckit.converge — Assess codebase against artifacts and append remaining tasks
/speckit.taskstoissues — Convert tasks to issues

Verification

After installation, confirm the CLI is working:

specify version

This confirms the specify command is available and reporting the expected version. Run specify self check periodically to learn whether a newer release is available — it is read-only and never modifies your installation.

Commands reference

The commands are designed to run in order, forming a pipeline:

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

Only /speckit.specify is strictly required before /speckit.plan. The clarify, checklist, and analyze commands are quality gates for features with meaningful ambiguity.

`/speckit.constitution`

Creates or updates the project constitution — the guiding principles evaluated against in every later phase. Run once up front and update when principles change.

/speckit.constitution This project follows a "Library-First" approach. All features must be implemented as standalone libraries first. We use TDD strictly. We prefer functional programming patterns.

Output: .speckit/constitution.md

`/speckit.specify`

Creates or updates a feature specification from a natural-language description. Focus on the what and why — user-facing behavior and goals — not the tech stack.

/speckit.specify Build an application that helps me organize photos into albums grouped by date, re-orderable by drag-and-drop on the main page, with a tile preview inside each album.

Output: specs/<prefix>-<short-name>/spec.md

The spec captures user scenarios, acceptance criteria, functional requirements, success criteria, and key entities.

`/speckit.clarify`

Asks up to five targeted questions about underspecified areas of the current spec and encodes your answers back into spec.md. Run as many times as needed before planning.

/speckit.clarify Focus on the task card behavior: status changes, comment limits, and who can be assigned.

`/speckit.plan`

Generates design artifacts from the spec. Provide your tech stack, architecture, and technical constraints as arguments.

/speckit.plan Use .NET Aspire with Postgres. The frontend is Blazor Server with drag-and-drop boards and real-time updates.

Output: specs/<feature>/plan.md — technology choices, architecture decisions, data models, and component breakdowns.

`/speckit.checklist`

Generates a quality checklist — unit tests for your requirements. Validates the spec is complete, clear, unambiguous, and consistent.

/speckit.checklist

/speckit.checklist Focus on the Kanban board interactions and comment permissions.

If the checklist surfaces gaps, loop back to /speckit.clarify or /speckit.specify.

`/speckit.tasks`

Generates an actionable, dependency-ordered tasks.md from the design artifacts. Tasks are organized into phases:

Phase	Purpose
Setup	Project scaffolding, dependencies, tooling.
Foundational	Blocking prerequisites all user stories depend on.
User Story N	One phase per user story, in priority order.
Polish	Cross-cutting concerns: error handling, logging, docs.

Tests are generated within a user story's phase when requested. Tasks are marked for parallel execution where possible.

/speckit.tasks

Output: specs/<feature>/tasks.md

`/speckit.analyze`

Performs a read-only cross-artifact consistency analysis across spec.md, plan.md, and tasks.md. It never edits files — it produces a report and can optionally suggest remediations.

/speckit.analyze

What it finds: Tasks with no matching requirement, plan choices that contradict the spec, missing acceptance criteria.

`/speckit.implement`

Executes the tasks in tasks.md, running each phase in dependency order and respecting parallel markers.

/speckit.implement

For large features, scope each run:

/speckit.implement Implement only the Setup and Foundational phases. Stop before the user-story features.

/speckit.implement Now implement the Kanban board user story: drag-and-drop between columns.

`/speckit.converge`

Assesses the codebase against the feature's spec, plan, and tasks to confirm nothing was missed. It is append-only: it never edits or deletes code. Its only possible write is adding tasks to tasks.md.

/speckit.converge

Two outcomes:

Converged — no gaps found. Tasks are unchanged. Proceed to review or open a PR.
Tasks appended — gaps found. New tasks are added under a Convergence section. Run /speckit.implement to complete them, then /speckit.converge again. Repeat until converged.

Development workflow

End-to-end flow

Initialize: specify init . --integration opencode --script sh --ignore-agent-tools
Constitution (once per project): Define principles your project follows.
Specify: Write a natural-language description of the feature → spec.md created.
Clarify (optional): Refine ambiguous areas.
Plan: Add tech stack and architectural decisions → plan.md created.
Checklist (optional): Validate the spec is complete and unambiguous.
Tasks: Break work into ordered, parallelizable chunks → tasks.md created.
Analyze (optional): Cross-check all three artifacts for consistency.
Implement: Execute tasks phase by phase.
Converge: Verify nothing was missed.

Quick start

Start with a small, well-defined feature:

specify init . --integration opencode --script sh --ignore-agent-tools

Then in your coding agent:

/speckit.specify Add a health check endpoint that returns status of all dependent services
/speckit.plan Use Express.js with a /health route that checks PostgreSQL and Redis connectivity.
/speckit.tasks
/speckit.implement
/speckit.converge

For more complex features, add clarify and analyze steps between specify and plan.

Troubleshooting

Air-gapped installation

If your environment blocks access to PyPI or GitHub, use locally built wheels from the spec-kit repository.

Stay current

Run specify self check periodically to learn whether a newer release is available.

Overview​

Core principles​

Prerequisites​

Installation​

Install from source — persistent installation (recommended)​

Install from PyPI​

One-time usage​

Initialize a Spec Kit project​

What you get after initialization​

Verification​

Commands reference​

/speckit.constitution​

/speckit.specify​

/speckit.clarify​

/speckit.plan​

/speckit.checklist​

/speckit.tasks​

/speckit.analyze​

/speckit.implement​

/speckit.converge​

Development workflow​

End-to-end flow​

Quick start​

Troubleshooting​

Air-gapped installation​

Stay current​

See also​