How to Use Spec-Kit: The Beginner's Guide (Install, First Spec, the Clarify Gate, and the Implement Loop)

CodexFuse Team · 2026-10-31T18:47:33.111Z · 14 min read

Learn how to use Spec-Kit: install specify-cli, write your constitution, run one feature through the clarify gate, then plan, tasks, and the implement loop.

What is Spec-Kit, exactly?

Spec-Kit is GitHub's open-source toolkit for spec-driven development: instead of telling a coding agent to "just build it," you write a reviewable specification first and the agent implements against it. This github spec kit tutorial answers how to use Spec-Kit from zero: install the specify CLI, initialize one project, write your first constitution and spec, run the feature through the clarify gate, then move through plan, tasks, and the implement loop — on one real small project.

Three facts set expectations before you install. First, Spec-Kit is not an AI that writes code; it is a workflow and template system that structures what you hand to your existing coding agent. Second, it is genuinely open: MIT-licensed, open-sourced around August 2025, carrying roughly 144,234 GitHub stars as of October 31, 2026, with version 1.2.5 released on October 28, 2026 (sources: GitHub spec-kit releases and repository APIs, fetched this run). Third, it is agent-agnostic: the official integrations directory lists 44 integration keys, including Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, and Kimi (source: github.github.com/spec-kit/integrations, fetched this run).

If you already write code with an AI agent, start there: our Codex beginner guide covers the Codex side of the workflow, and Spec-Kit plugs straight into it — Codex users invoke Spec-Kit's skills with a $speckit-* prefix, as the official Command Invocation table documents. This spec-kit for beginners guide is written so it works no matter which of the supported agents you use.

How do you use Spec-Kit for the first time?

You install the CLI once, initialize one repository for your agent, then walk a single small feature through every stage and review each artifact before moving on. Here is the complete arc this spec driven development tutorial follows:

1. Check the prerequisites: Python 3.11 or later, uv, Git, and a coding agent.
2. Install the CLI once per machine with uv tool install specify-cli, then confirm it with specify version.
3. Pick one small, real feature — for example, "export the audit log to CSV" — small enough to review every artifact.
4. Initialize the repository: specify init --here --integration <your-agent> (use --integration copilot, claude, cursor-agent, codex, gemini, or kimi).
5. Launch your coding agent in the project directory.
6. Run the constitution once per project: /speckit-constitution (or your agent's skill form — see the invocation table below).
7. Describe the feature: /speckit-specify — the agent writes spec.md.
8. Answer the agent's questions: /speckit-clarify — the clarify gate, which most teams fail.
9. Approve the technical plan (/speckit-plan), the requirements checklist (/speckit-checklist), and the task breakdown (/speckit-tasks), then run the consistency check (/speckit-analyze).
10. Implement (/speckit-implement), then converge (/speckit-converge); repeat implement → converge until the agent reports "Converged."

The rest of this guide walks through each step, including the one naming trap that breaks beginners: the slash-command spelling changes per agent, and older write-ups use a different form than the current docs.

What do you need before installing Spec-Kit?

You need four things: Python 3.11 or later, uv, Git, and one coding agent with Spec-Kit integration support. The Python requirement comes straight from the PyPI package metadata (requires_python >= 3.11); uv does the actual installing, and Git is expected for the repository workflows the quickstart describes.

You do not need a server or any paid account to practice. Run everything on your own machine for the first feature; if you later want a always-on dev box for a team workflow, our what is VPS hosting guide explains the kind of machine this fits best. Keep your first feature tiny and local — the arc above assumes a laptop and a quiet afternoon.

How do you install specify-cli?

Install it once per machine from PyPI with uv, exactly as the official quickstart instructs — the specify cli install is the same one-liner on every platform uv supports:

uv tool install specify-cli
specify version

If you want the whole team pinned to one release, install from a tag instead — for example, uv tool install specify-cli --from git+https://github.com/github/[email protected] (source: GitHub releases API, fetched this run). Note the one-shot uvx invocation exists but does not update the persistent specify executable on your PATH, per the integration CLI reference — prefer the real install. Keep the CLI current with specify self check (reports a newer release) and specify self upgrade (installs it); the repository ships roughly weekly releases, with v1.2.1, v1.2.2, v1.2.3, v1.2.4, and v1.2.5 all landing in October 2026 alone.

How do you connect Spec-Kit to your coding agent?

Run specify init inside your project and tell it which agent you use. The interactive init prompts you for the agent and the script variant; pass them explicitly for a repeatable setup:

cd your-repo
specify init --here --integration claude --script sh

The --integration flag is the current form — the older --ai flag was removed in 0.10.0. In scripts or CI, use specify init --here --force --integration claude --script sh --non-interactive; without --integration, a non-interactive run defaults to Copilot. The --script sh|ps|py flag selects the Bash, PowerShell, or Python automation-script variant (source: official quickstart and integration CLI reference, both fetched this run).

The naming trap: each agent exposes the same skills with a different spelling. The official Command Invocation table documents three current forms — and older write-ups use a fourth, dotted form (/speckit.specify) that still appears in January-2026 blog posts. Teach your fingers the current table, not the old posts. The canonical skills are speckit specify, speckit plan, and speckit implement — hyphenated in current Copilot, Claude Code, and Cursor skills mode:

Our Gemini CLI beginner guide covers the Gemini side of this workflow if that is your agent of choice. Whatever your editor, the method is the same — spec kit claude code, spec kit cursor, and spec kit copilot users all run the identical nine-phase arc; only the skill spelling changes. And if you prefer a terminal-native agent that already orchestrates tools and browser sessions, our OpenClaw beginner guide covers that sibling lane — OpenClaw is the agent, Spec-Kit is the method, and they are never rivals.

What is the constitution, and why run it first?

The constitution is the project's non-negotiable ground rules — tech stack, architectural constraints, coding standards, performance and security expectations — and every later step is evaluated against it. Run it once per project, before your first spec, by passing your principles as arguments to the skill. Most teams skip this step, and it is the step that saves them later: without a constitution, each new feature's spec renegotiates the same decisions from scratch.

What does /speckit-specify write?

It converts your plain-English feature description into a structured specification — the what and the why — and writes it as spec.md in a new feature directory. The spec carries user stories, requirements, and edge cases in a form your team can review before any code exists. Spec-Kit tracks the active feature through the feature directory recorded in .specify/feature.json (overridable with the SPECIFY_FEATURE_DIRECTORY environment variable) — commands resolve the feature from that state, not from the checked-out Git branch, so no Git is required.

Invoke each skill separately in your agent's chat and review the result before moving to the next step. These are agent skills, not terminal commands; only CLI installation and project setup use the terminal.

What is the clarify gate?

The clarify gate is the step where the agent asks you questions about the gaps in your spec — and it is where teams actually fail. The lesson beginners learn the hard way: teams fail at the specify phase, not the implement phase, because a spec that cannot be wrong is not a spec. If your spec is so vague that no implementation could ever violate it, the clarify gate is your last chance to make it checkable before planning starts.

Treat the agent's questions as the test of your own thinking. If it asks "should expired links return 410 or redirect?" and you cannot answer, your spec was a wish, not a specification. Answer every question, let the agent edit spec.md, and only then move to planning. In the full process, /speckit-clarify sits directly between specify and plan; the shorter path for small features skips it — and that is exactly when you should be most suspicious of skipping it.

How do plan, tasks, checklist, and analyze fit in?

Plan converts the spec into the how: technical stack, architecture, and data flows, written to plan.md. The checklist generates requirements checklists against the plan; tasks breaks the plan into an ordered, reviewable tasks.md. Analyze then runs a consistency check across spec, plan, and tasks — it writes nothing, and that is the point: it is a read-only audit before the agent is allowed to touch code.

For the shorter path on small features, the official quickstart lists just constitution → specify → plan → tasks → implement → converge. The full path adds clarify, checklist, and analyze as quality gates: constitution → specify → clarify → plan → checklist → tasks → analyze → implement → converge (source: official quickstart, fetched this run).

How does the implement loop work?

Implement executes the tasks phase by phase, writing code, marking tasks complete, and validating changes against the spec. Then converge scans for leftover work and appends it to tasks.md. You repeat implement → converge until the agent reports "Converged" — only then is the feature done. The loop ends on the agent's judgment, not on a timer, which is why the spec's checkability from the clarify gate matters: converge can only verify work against requirements that were actually written down.

One real-project habit makes this loop pay off: run the whole arc on the small feature from step 3 of the first-time list before you ever point it at production code. A finished specs/ folder for "export the audit log to CSV" teaches you more about the method than a half-finished enterprise spec ever will. If your agent runs in containers, our Docker beginner guide covers the lab setup this kind of sandboxing pairs well with.

How much extra does Spec-Kit cost in tokens?

Expect to spend more on model tokens per feature than pure vibe coding — the agent re-reads the spec, plan, and tasks on every turn. The honest, sourced range looks like this: a current third-party guide (fundesk.io, updated October 2026, commands verified as of May 2026) advises planning on 20–40% more API spend per feature, with fewer wasted cycles overall. Academic work finds higher numbers in different setups: arXiv 2608.25202 ("Spec-Driven Development as Prescribed and as Practiced," a study of 73,030 repositories) reports a team comparison where spec-driven runs typically consumed two to three times as many tokens as direct prompting, while ISCAP 2026 proceedings describe a controlled experiment with roughly 9.2 percentage points higher test pass rate but about 28 times the tokens.

Read the range for what it is: the 20–40% figure reflects real-world guided use, the research figures reflect controlled comparisons of full spec workflows. The cost you are buying is fewer wasted cycles — rework discovered at the clarify gate is cheap, rework discovered after a full implementation is not.

Spec-Kit vs vibe coding: what's the real difference?

The difference is not who writes the code — it is what survives after the code is written. Vibe coding keeps the intent in the chat transcript; spec-driven development writes it down where humans can review it. This spec driven development vs vibe coding comparison is the question every team asks before adopting the method, so here is the honest version:

This is an original synthesis from the facts verified this run — the token figure is sourced above, the rest follows from the documented workflow.

When should you skip Spec-Kit?

Skip it whenever the ceremony costs more than the drift it prevents. One-line fixes, throwaway spikes, and experiments you plan to delete do not deserve a constitution, a spec, and an implement loop. Spec-Kit's own ecosystem is explicit about this: the developertoolkit.ai practice guide (updated September 2026) closes with a clear rule for when Spec-Kit adds ceremony you should skip — it pays off on features large enough to deserve a written trail, and a feature that small should stay in the chat.

7 beginner mistakes that break a Spec-Kit run

Every one of these is a mistake beginners make in their first week, distilled from the documented workflow:

Sources

Every number, command, and release date in this guide was verified at write time, October 31, 2026: GitHub spec-kit releases API and repository API (v1.2.5 released October 28, 2026; ~144,234 stars; MIT; v1.1.0 October 2, 2026 deprecated /speckit.taskstoissues in favor of the github extension; v1.0.0 August 21, 2026); the official quickstart at github.github.com/spec-kit/quickstart.html (install command, init flags, full and short process paths, per-feature state in .specify/feature.json); the Command Invocation table at github.github.com/spec-kit/integrations/cli.html (per-agent skill spellings: /speckit-*, $speckit-*, /skill:speckit-*); the integrations directory at github.github.com/spec-kit/integrations (44 integration keys); the developertoolkit.ai Spec-Kit practice guide (updated September 2026 — audit-log export walkthrough, --ai removal in 0.10.0, when to skip the ceremony); abhishek-dev on Medium (updated October 30, 2026 — the SDD loop and agent list); shreyashupare on Medium (June 2026 — nine-phase workflow detail); joshtune.com Spec-Kit notes (workflow overview); fundesk.io's Spec-Driven Development Guide (October 2026 — the 20–40% API-spend guidance); arXiv 2608.25202 "Spec-Driven Development as Prescribed and as Practiced" (73,030-repository study — the 2–3× token finding); and ISCAP 2026 proceedings (Taghavi & Bhavani — the matched SDD-vs-vibe experiment with ~9.2pp higher pass rate).

Frequently Asked Questions

Is Spec-Kit an AI coding agent itself?

No. Spec-Kit is a workflow and template system plus agent skills; it does not write code on its own. You still need a coding agent — Claude Code, Codex, Cursor, Copilot, Gemini CLI, Kimi, or any of the other 38 integration targets — and Spec-Kit structures what you hand to it.

Which coding agents work with Spec-Kit?

The official integrations directory lists 44 integration keys, including claude, cursor-agent, copilot, codex, gemini, and kimi, plus amp, auggie, cline, droid, opencode, zed, and a generic fallback. If your agent is not listed, the generic integration is the starting point.

Should I type /speckit.specify or /speckit-specify?

Use your agent's current skill form from the invocation table in this guide: /speckit-specify for Copilot, Claude Code, and Cursor; $speckit-specify for Codex; /skill:speckit-specify for Kimi. The dotted form (/speckit.specify) appears in older write-ups and the documentation references, but current skills mode is hyphenated.

Does Spec-Kit need Git?

No. Spec-Kit tracks the active feature through the feature directory recorded in .specify/feature.json — not through the checked-out Git branch. Git is listed as a prerequisite for the repository workflows in the quickstart, but the feature state itself does not require it.

Is Spec-Kit free to use?

Spec-Kit itself is MIT-licensed open source — the CLI and the skills cost nothing. The spend is on your coding agent's API usage, which runs higher per feature than pure vibe coding (budget the 20–40% figure from the cost section) in exchange for fewer wasted cycles.