SPEC KIT · SPECIFY CLI · SPECKIT COMMANDS

Spec Kit Tutorial: Every /speckit Command, Step by Step

A command-by-command Spec Kit tutorial for the current 1.x release: install the Specify CLI with uv, init any of the 30+ supported agents, and run the full constitution → specify → clarify → plan → checklist → tasks → analyze → implement → converge workflow. Works on Windows without WSL. Takes about ten minutes end to end.

Run it in the free harness What is SDD?

Step 0 — What you need

Spec Kit's Specify CLI is a Python tool, so the prerequisites are short. You need Python 3.11 or newer, uv as the tool installer, and a coding agent (Claude Code, Codex CLI, Gemini CLI, Copilot, Cursor, Zed — Spec Kit supports 30+ integrations; run specify integration list to see what your installed version knows). Git is now optional: Spec Kit tracks the active feature in .specify/feature.json, not the checked-out branch. The opt-in git extension adds numbered feature branches like 001-feature-name, but none of the commands require a repository.

Tool	Minimum	Check
Python	3.11+	`python3 --version`
uv	latest	`uv --version`
Git	optional	`git --version`
Coding agent	any of 30+	`specify integration list`

On Windows install uv with winget install --id=astral-sh.uv -e or powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex". macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh or brew install uv.

Step 1 — Install the Specify CLI

The simplest route is the published PyPI package — one command on every platform:

uv tool install specify-cli
specify --version

Teams that need reproducible installs pin a release tag from the Spec Kit releases page (keep the leading v):

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

Alternatives that also work: pipx install specify-cli, pip install specify-cli, or one-time uvx runs. To upgrade later, use the self-management commands — specify self check tells you if a newer release exists (read-only), and specify self upgrade --dry-run previews what would run before anything changes.

Step 2 — Initialize the project

From your project root (or an empty folder for greenfield work):

specify init my-project --integration claude
# or, into the current directory:
specify init --here --integration copilot
cd my-project

init scaffolds a .specify/ directory with templates and the slash-command definitions your agent reads, then writes the commands into the agent's own config. Four flags matter in practice:

--integration <agent>

Pass your agent explicitly instead of relying on the interactive picker: claude, copilot, gemini, codex, cursor, zed, and more. Documented values vary by version — specify integration list is the source of truth.

--non-interactive

For CI pipelines and agent harnesses (no keyboard): unspecified choices use documented defaults instead of hanging on an arrow-key picker. Combine with --force and --ignore-agent-tools for non-empty directories.

--script sh|ps|py

Automation scripts ship as Bash, PowerShell, and Python variants. Windows defaults to PowerShell — no WSL required. Explicitly pass --script ps in scripts so behavior never depends on the OS default.

--here

Brownfield case: lays .specify/ and the agent command files next to your existing code without touching it. Your code is untouched — you added a workflow, not a rewrite.

Finish with specify check to confirm the CLI found your agent and tooling.

The two paths: short loop vs. full loop

Every command below is a slash command inside your agent. Spec Kit's own docs define two common routes — pick by stakes, not by habit:

Path	Commands	Use when
Short loop	/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement → /speckit.converge	Smaller features where you already know the shape
Full loop	constitution → specify → clarify → plan → checklist → tasks → analyze → implement → converge	Production features — adds /speckit.clarify, /speckit.checklist, and /speckit.analyze as quality gates

Step 3 — The commands, one by one

Examples below use a small team-productivity app (the same shape Spec Kit's official Taskify walkthrough uses) so you can copy-paste and adapt. Exact invocation varies slightly by agent — some skills-based agents use $speckit-* (Codex, ZCode) or /skill:speckit-* (Kimi) — but the steps are identical.

1. /speckit.constitution — set the ground rules (full loop only)

Establishes the project's guiding principles, which every later step is evaluated against. Run it once up front:

/speckit.constitution This is a security-first application. All user inputs must be validated. We use a microservices architecture. Code must be fully documented.

Rough edge: keep it to real, enforceable principles. A constitution stuffed with aspirations dilutes the guardrails every later phase inherits.

2. /speckit.specify — describe what to build

Creates the feature specification from a natural-language description. Focus on the what and why — not the tech stack:

/speckit.specify Build a team productivity platform where predefined users create projects, assign tasks, comment, and move tasks across Kanban columns (To Do, In Progress, In Review, Done). Five users, three sample projects, no login in this phase.

Rough edge: the moment your spec says "use a Redis sorted set," you have stopped specifying and started coding badly in English. Implementation detail belongs in /speckit.plan. Running specify creates a numbered directory like specs/001-taskify/ and writes spec.md inside it.

3. /speckit.clarify — resolve ambiguities (full loop)

Asks targeted questions about anything underspecified and folds your answers back into the spec — so you're not planning on top of ambiguity. Run it before planning:

/speckit.clarify Focus on task card behavior — status changes, comment permissions, and user assignment.

Rough edge: give it a focus area. Unfocused clarify passes tend to produce generic questions; a directed prompt produces decisions you actually need.

4. /speckit.plan — choose the tech stack

Generates the design artifacts from the spec. This is where implementation detail belongs:

/speckit.plan Use .NET Aspire with Postgres. Frontend is Blazor Server with drag-and-drop boards and real-time updates. Expose REST APIs for projects, tasks, and notifications.

The output is plan.md: stack choices, architecture, and structure the tasks will be cut from.

5. /speckit.checklist — validate the spec (full loop)

Generates a custom quality checklist — "unit tests for your requirements" — to confirm the spec is complete, clear, and consistent before work is broken down:

/speckit.checklist

Rough edge: these are reviewer-owned artifacts. Mark an item [x] only when you have verified that requirement-quality criterion yourself — checked checklist items do not mean implementation work is complete. /speckit.implement reads this state as a gate and will ask before proceeding past unchecked items.

6. /speckit.tasks — break the work down

Generates an actionable, dependency-ordered tasks.md from the design artifacts:

/speckit.tasks

Review it like a PR. The task list is the last artifact where reordering is cheap.

7. /speckit.analyze — check consistency (full loop)

Read-only report of conflicts, gaps, and ambiguities across spec.md, plan.md, and tasks.md:

/speckit.analyze

If it flags issues, fix them at the source and re-run — do not implement on top of a red analyze report.

8. /speckit.implement — build it

Executes the tasks in tasks.md in dependency order. It does not change any checklist files or markers:

/speckit.implement

Run it once to build everything, or scope it to one phase at a time on large features. Reviews stay small because each change implements a specific, pre-approved task.

9. /speckit.converge — verify completeness

Checks the codebase against the spec, plan, and tasks. If it finds gaps, it appends new tasks to tasks.md:

/speckit.converge

Then run /speckit.implement and converge again until it reports converged. After that: review the diff or open the PR. The converge loop is what turns "the agent said it was done" into "the artifacts say it matches."

How the artifacts fit together

After a full loop your repo carries a versioned trail: specs/001-<feature>/spec.md (what and why, with acceptance criteria), plan.md (stack and architecture), tasks.md (ordered work), and custom checklists. Because everything is plain markdown, the assets survive an agent switch — start with Claude Code today, move to Codex or Gemini tomorrow, and specs/ plus .specify/ stay reusable as-is. That is the concrete reality behind Spec Kit's "no lock-in" pitch.

One state detail worth knowing before it surprises you: Spec Kit tracks the active feature by the directory recorded in .specify/feature.json — commands resolve from that state, not from the Git branch. If you need to point commands at a different feature, update .specify/feature.json or set the SPECIFY_FEATURE_DIRECTORY environment variable. git checkout alone does not switch features.

Run Spec Kit inside the free harness

The harness layer: Spec Kit documents --non-interactive specifically for AI agent harnesses. VibeFuse is the first ever free widget-based AI harness — run each SDD phase as a widget session on one Windows canvas with Claude Code, Codex, and Gemini side by side, named resumable sessions, spec artifacts on disk where every agent sees them, local voice control keeping your hands on the review instead of the keyboard. New to Claude Code itself? Our Claude Code tutorial covers install, commands, permission modes, and CLAUDE.md memory.

The open-source marketplace closes the loop: publish and sell your constitution templates, SDD workflow presets, and review skills as SKILL.md folders — the format Claude and Codex already read — with 80% payouts to creators. Everything processes locally and offline where possible, and works in any app you already use.

Download the free harness Browse the marketplace

✓ Runs Claude Code + Codex + Gemini
✓ Named resumable sessions
✓ Local Whisper + Piper
✓ 80% creator payouts

Get the free harness Read the SDD guide

Explore VibeFuse & harness guides

Spec Kit tutorial FAQ

How do I install Spec Kit?

Install the Specify CLI with uv, GitHub's fast Python tool manager: uv tool install specify-cli. That single command works on Windows, macOS, and Linux because the package is published on PyPI. Teams that need reproducible installs pin a release tag instead: uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z (keep the leading v). On Windows, install uv itself with winget install --id=astral-sh.uv -e.

How do I initialize Spec Kit in an existing project?

Run specify init --here --integration claude (swap claude for your agent: copilot, gemini, codex, cursor, zed — Spec Kit supports 30+ integrations; specify integration list shows yours). The --here flag lays the .specify/ directory, templates, and slash-command files next to your existing code without touching it. Finish with specify check to confirm the CLI found your agent and tooling.

What are all the Spec Kit slash commands?

Nine: /speckit.constitution (project principles), /speckit.specify (what to build, spec.md), /speckit.clarify (ambiguity questions folded back into the spec), /speckit.plan (stack and architecture, plan.md), /speckit.checklist (requirement-quality gates), /speckit.tasks (dependency-ordered tasks.md), /speckit.analyze (read-only consistency report), /speckit.implement (build from tasks.md), and /speckit.converge (verify implementation matches artifacts). Smaller features skip constitution, clarify, checklist, and analyze — the short path is specify, plan, tasks, implement, converge.

Does Spec Kit work on Windows?

Yes, without WSL. The Specify CLI runs anywhere Python and uv run, automation scripts ship as PowerShell variants (Windows default), and Bash/Python variants are selectable with --script sh|ps|py. The only Windows-specific step is installing uv (winget install --id=astral-sh.uv -e or the PowerShell one-liner from astral.sh).

Why does Spec Kit track features in .specify/feature.json instead of Git branches?

Spec Kit resolves the active feature from the directory recorded in .specify/feature.json — commands read that state, not the checked-out Git branch. Git is optional; the opt-in git extension adds numbered feature branches (001-feature-name) for organizing work, but git checkout alone never switches the active feature. Point commands at a different feature by updating .specify/feature.json or setting the SPECIFY_FEATURE_DIRECTORY environment variable.

What is the difference between the short and full Spec Kit paths?

The short path is five commands — /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement, /speckit.converge — for smaller features. The full path adds /speckit.constitution (once per project) plus /speckit.clarify, /speckit.checklist, and /speckit.analyze as quality gates, and is what the official docs recommend for production features. Same commands either way; the full path just validates more before code is written.

Can I run Spec Kit in a harness like VibeFuse?

Yes — Spec Kit documents --non-interactive specifically for CI and AI agent harnesses so init never hangs on an arrow-key picker. VibeFuse is the first ever free widget-based AI harness: run each SDD phase as a widget session on one Windows canvas (Claude Code, Codex, and Gemini side by side), with named resumable sessions, spec artifacts on disk where every agent sees them, and an open-source marketplace selling spec templates and workflow presets with 80% payouts to creators.