Setting It Up

What the toolkit puts on your disk, how to install it, and — the part most write-ups skip — an honest account of when not to bother.

1.5 What lands on disk

FIGURE 4 — What lands on disk, and who owns it. The split matters on upgrade day: one side is replaced, the other is never touched.

Two directories, and the distinction between them is the one to remember.

.specify/ is spec-kit's own. Templates, helper scripts, the extension registry, and memory/constitution.md. When you upgrade the toolkit, this is what gets replaced — with the exception of your constitution, which survives. Anything else you customise in here should be backed up first.

specs/ is yours. One folder per feature, holding everything the commands produced. It is never modified by an upgrade. This is the folder that is worth more than the code in five years, because it is the only record of why the code is the way it is.

Two details that trip people up, both of which changed in recent versions:

• The active feature is tracked in .specify/feature.json, not by your Git branch. Older write-ups say otherwise. Git is not required to use spec-kit at all.
• Git branching is an opt-in extension, installed with specify extension add git. specify init does not create a repository or a branch.

Nothing here is a proprietary format. It is Markdown, JSON and shell scripts. Abandon spec-kit tomorrow and the specifications you wrote remain readable and remain yours.

1.6 Setting it up

spec-kit is a Python CLI called specify. It requires Python 3.11 or later, and it is MIT-licensed.

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.15.1

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

Pin the version. The @v0.15.1 is not decoration — spec-kit moves quickly, and this document is written against v0.15.1 specifically. Keep the leading v.

specify check verifies your coding agent is available. specify self upgrade --dry-run shows what an upgrade would change before it changes it.

Which agent. spec-kit supports 35 integrations, chosen with --integration. Claude Code, GitHub Copilot, Cursor, Gemini CLI, Codex CLI, Zed, Cline and Amp are among them, and --integration generic covers anything not on the list. For Claude Code the commands install as skills under .claude/skills/.

Invocation differs slightly by agent — most use /speckit.specify, Codex CLI uses $speckit-specify, and a few use other forms. The commands themselves are identical.

Avoid: assuming the flag is --ai. It was, in earlier releases. It is now --integration, and the value is an integration key rather than a display name.

No screenshots of this are reproduced here, because the project does not exist yet. An invented screenshot of a system that has not been built is the fastest way to lose a reader's trust in everything around it.

1.7 When it is worth it — and when it is not

spec-kit describes three situations it is designed for:

The brownfield case has its own documented loop, because it splits into two jobs that are easy to confuse: upgrading the toolkit, and evolving the specifications as the product's intended behaviour changes. They are kept deliberately separate.

When to skip it. A one-line fix does not need a constitution. Neither does a spike you intend to throw away, or a change you can describe completely in a single sentence and verify by looking at it. The overhead is real, and applying it to trivial work is how a good method acquires a bad reputation.

The rough test: if getting it wrong would be expensive, or if somebody other than the author will need to understand it later, it is worth the structure. The pipeline used as the worked example meets both conditions — it touches a live website and it will outlive whoever builds it.