2026 Spec Kit Complete Guide: Install and Practice Spec-Driven Development on Windows, macOS, and Linux

Spec Kit, maintained by GitHub, turns spec-driven development into a CLI you install and a set of agent skills you invoke. The PyPI package is specify-cli. The source repository is github/spec-kit. It does not replace Cursor, Claude Code, GitHub Copilot, or Codex. It tells those agents to write the observable behavior first, the technical choices second, and the repository edits last. As of November 2026, Windows uses PowerShell scripts directly. You do not install WSL first. This page is the install, the directory layout, and the command order. For why a spec has to exist before code, read the spec-driven development guide. For where skill files live, read the Agent Skills guide.

Why “build me a board” is already the wrong start

The conflict between the old way and the new way is concrete. The old way is session-first. You pack the goal, the stack, and the folder layout into one chat. The agent guesses and edits files. Change the machine or the person, and the context is gone. The new way is artifact-first. Principles go in .specify/memory/constitution.md. Behavior and the reason for it go in specs/<feature>/spec.md. The stack waits for plan.md. The executable order waits for tasks.md. The active feature is whatever .specify/feature.json points at, not whatever you remember from the last thread.

In 2026 this is an install problem, not an attitude problem, for three reasons. First, the invocation spelling forks by agent. Cursor, Claude Code, and Copilot’s default skills mode use /speckit-specify. Codex uses $speckit-specify. The dotted form in the docs is reference notation. Second, installing once with uv and again with pipx leaves two specify binaries. The old one on PATH rejects --integration. Third, the optional git extension can create numbered branches, but git checkout itself does not switch the active feature. All three happen before the first line of product code.

How Spec Kit splits spec-driven work into layers

Do not treat the nine slash skills as one flat checklist. They land on three kinds of artifact, and only two paths are legal.

The principle layer is once per repository. /speckit-constitution records hard constraints on quality, tests, permissions, and experience. Later steps are judged against that file. The feature layer is once per feature. /speckit-specify answers only what a user can observe and why it should exist. /speckit-clarify asks about the vague parts and writes the answers back into the spec. The implementation layer is the first place a framework or a directory is allowed. /speckit-plan produces the plan, research notes, data model, and contracts. /speckit-tasks breaks the plan into dependency order and marks parallel work with [P]. /speckit-implement edits files in that order. /speckit-converge compares the code with the artifacts, appends missing tasks, and repeats until it reports Converged.

Two quality gates sit in the middle. Do not confuse them with “the code is done.” /speckit-checklist builds a reviewer-owned list of requirement quality. A check mark means the requirement is clear, not that the feature is implemented. /speckit-analyze is read-only. It reports conflicts among spec.md, plan.md, and tasks.md and does not edit the repo. The built-in checklists/requirements.md is maintained by specify and clarify. Custom checklists stay with the reviewer. Implement will stop and ask if boxes are unchecked. It will not check them for you.

The short path fits a small change whose boundary is already clear: specify, plan, tasks, implement, converge. The full path fits anything you intend to ship: constitution once per project, then specify, clarify, plan, checklist, tasks, analyze, implement, converge. A defect follows the official bug-fixing quickstart. An idea you have not committed to follows idea assessment. Neither is a prerequisite of this spec-driven path.

Install on Windows, macOS, and Linux

The shared prerequisites are Python 3.11 or newer, Git only if you enable the git extension, and the agent you will actually write code with. Use uv for a persistent install. The terminal runs the CLI. Slash skills run in the agent chat.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script ps

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script sh

After install, check two things. specify version only proves the command runs and prints a version. It does not prove the binary came from PyPI rather than GitHub. specify self check is read-only. It tells you whether a newer release exists and does not modify the install. The docs illustrate release tags with a leading v, such as v0.12.11. To pin a source install, run uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z and keep the v. A PyPI pin is uv tool install specify-cli==X.Y.Z. Upgrade with the same tool you used originally: uv tool install --force specify-cli, pipx install --force specify-cli, or pip install --upgrade specify-cli.

Do not initialize a repository that already has code on a dirty worktree. Commit or back up first, then run specify init --here --force --non-interactive --integration claude. --force only means you accept that templates will merge into existing files. CI without a keyboard needs --non-interactive, or init stops on an arrow-key menu. If the agent executable lives on another machine, add --ignore-agent-tools to skip the local binary check. Non-interactive init defaults to Copilot unless you pass another --integration.

Do not guess the integration key. Cursor is cursor-agent, not cursor. Other common keys are claude, copilot, gemini, pi, omp, and codebuddy. An interactive terminal will ask if you omit --integration. A script or a pipe must pass it.

Nine commands: where they run, what they may change, who they are for

The next two tables share one column set. The real difference is the entry point and the execution boundary, not the model name.

Pick the short path or the full path by the situation

The worked example is a note board that stays on one machine. Nothing is uploaded. The first phase has no password. Three preset members. Four columns under a project: To do, In progress, Needs confirmation, Done. Drag a card to change its column. A comment can be edited only by its author. Specify records that behavior and the reason. Plan is where you write “local SQLite, no remote API.” Putting the database into specify turns the first technical hunch into a requirement nobody is allowed to challenge.

A stack that matches the agent, the script type, and an isolated machine

If you already write this repository in Cursor, use cursor-agent and the script type of the machine: ps on Windows, sh on macOS and Linux. After init, invoke one skill at a time in chat, on either the short path or the full path. Read the artifact before the next skill. Do not paste all nine commands into one prompt.

If you mainly use Claude Code, the integration key is claude. When many skill descriptions crowd the context, init with --integration-options="--no-model-invocation" so the core commands run only when you type /speckit-specify. Copilot users can keep the default skills layout. Add --commands only when you specifically want the older agent files.

Implement edits files and runs commands. Do not take the first pass on a laptop that holds production keys. Put the repository on a remote Mac, read the diff, then merge it back. For how to order a node, see Mac mini rental. For the budget, see pricing. If the spec includes a macOS build or signing, run that phase on a real Mac node and keep it off the daily laptop with OpenClaw cloud automation. If install fails, check connection and system requirements in the help center before you blame Spec Kit.

Five mistakes that force the rest of the work to be redone

1. Writing the framework and the database inside specify. The stack belongs in plan. Once the spec says “must use this library,” clarify and analyze spend their time defending that choice.
2. Typing /speckit-specify in the terminal. Slash skills exist only in the agent chat. The terminal runs specify itself.
3. Pasting the dotted doc command into Cursor. The Cursor skill is /speckit-specify. The dotted form is reference notation.
4. Installing with both uv and pipx. An old 0.1.x binary reports No such option: --integration, or No matching release asset found on --ai. Run which specify before you decide which copy to remove.
5. Using git checkout as the feature switch. Change .specify/feature.json, or set SPECIFY_FEATURE_DIRECTORY. A branch switch alone leaves the commands pointed at the previous feature directory.

Seven steps

1. Install uv and specify-cli. Run specify version and specify self check. Confirm PATH resolves a single binary.
2. Pick --script for the operating system and --integration for the agent you actually use, then run specify init. On an existing repo, commit first and add --here --force.
3. Run /speckit-constitution once in the agent chat. Principles only: validate input, comments are editable only by their author, the first phase does not upload.
4. Describe the note board’s behavior and reason with /speckit-specify. If you will ship it, run /speckit-clarify and finish the questions on drag-and-drop, permissions, and an empty project.
5. Only after the spec is stable, run /speckit-plan. Then checklist, tasks, and analyze. If analyze reports a conflict, fix the source artifact. Do not patch it during implement.
6. Run /speckit-implement on an isolated Mac or a clean directory. If the task list is long, do it by phase. Do not swallow all of tasks.md in one pass.
7. Run /speckit-converge until it reports Converged. Then read the diff: files outside the spec, and any secret written into the repo.

Questions that decide the install

How is Spec Kit different from chatting in Cursor?

A chat transcript stays in that session. Change the person or the machine and it is gone. Spec Kit writes principles, the spec, the plan, and the tasks into the repository as Markdown. The active feature is the directory in .specify/feature.json, not your memory of the last thread.

Is the command /speckit-specify or /speckit.specify?

Cursor, Claude Code, and GitHub Copilot’s default skills mode use the hyphen form, in the agent chat, not in the terminal. Codex skills mode uses $speckit-specify. The dotted form in the docs is reference notation. Do not paste it into Cursor.

Does Windows need WSL first?

No. In 2026 Spec Kit defaults to PowerShell on Windows. Pass --script ps at init. macOS and Linux default to bash, which is --script sh.

Can I install with both uv and pipx?

No. You will keep two specify binaries. Whichever old copy ranks first on PATH will reject --integration or report No matching release asset found. Upgrade with the original tool, using --force or --upgrade.

Does git checkout switch the active feature?

No. The active feature is .specify/feature.json. Override it with SPECIFY_FEATURE_DIRECTORY. The optional git extension can create numbered branches, but checking out a branch does not update that state.

Install the right command, then let the agent edit the repo

Spec Kit is not valuable because it adds one more slash command. It is valuable because “spec, then plan, then edit files” becomes files in the repo that someone else can review. Windows uses PowerShell. macOS and Linux use bash. Cursor uses cursor-agent and hyphen skills. A small change takes the short path. A feature you will ship takes the full path. Implement runs on an isolated node. The next step is not another prompt collection. Run specify version and confirm the binary in front of you is the one you just installed.

Further reading

• Spec-driven development guide: the method, not the installer →
• Agent Skills: what to install and where →
• OpenClaw cloud automation on a remote Mac →