On 3 February 2026 I gave a talk at the Epitech Summit in Mulhouse about using Markdown as a programming language when building with AI. The idea is easy to accept. The question that always comes after it is harder: what do I actually run?
In this article I’ll answer that question. The install, the commands in order, and one mistake that will cost you twenty minutes if nobody warns you about it.
A note before we start. I keep this page up to date, so the commands below are the ones that work with Spec Kit 1.2.5, not the ones I showed on the day of the talk. The CLI has changed some names since then, and a guide that doesn’t run is not useful to anyone. If you want the reasons behind this approach rather than the commands, I wrote a separate article about it.
What Spec Kit is
Spec Kit is an open source toolkit from GitHub for spec-driven development. It’s MIT licensed, and it moves fast: version 1.2.5 was released on 28 October 2026. That matters, because a lot of the guides you’ll find online are already out of date.
It also helps to say what it is not. It’s not a model, not an IDE, and not a replacement for your coding agent. It installs a CLI called specify, and it gives the agent you already use a process to follow. Each step produces a Markdown file that you can read and correct before the next step uses it.
It works with any language and any stack. My examples are in .NET, but nothing below depends on that.
Installing it
You need Python 3.11 or later and uv. It runs on Linux, macOS and Windows.
For a new project:
uv tool install specify-cli
specify init my-project --integration copilot
cd my-project
The --integration flag tells Spec Kit which agent you use. There are more than forty values: copilot for GitHub Copilot, claude for Claude Code, cursor-agent for Cursor, gemini for Gemini CLI, codex for Codex CLI, and many others. There is also none if you want the files without connecting the project to one specific agent. That’s useful when your team hasn’t picked one yet.
If you have older notes or slides that use an --ai flag, that flag no longer exists. The current README uses --integration.
Most of the time you’re not starting from an empty folder. For an existing project, run this from the root of the repository:
specify init --here --force --integration claude
--here uses the current directory instead of creating a new one. --force allows the command to run in a directory that is not empty, and it can overwrite files in the paths that Spec Kit manages. So commit or stash your work first, and create a branch before you run it. It won’t touch the rest of your application, but it costs you nothing to be safe.
This is also the more interesting case. Spec Kit reads the patterns already in your repository, so new features come out looking like your existing code instead of looking like a tutorial.
What the command adds is a .specify/ directory and the skill files your agent needs.
One limitation to know before you start: Spec Kit does not write specs for code you already have. It describes what you are going to build, not what you built last year.
The mistake everyone makes first
Here is the part that will save you twenty minutes.
The commands below are not terminal commands. You type them in your agent’s chat window. Only the install and the project setup happen in a shell.
The second problem is the notation, and it depends on the agent you chose. The official documentation is not consistent about it. The reference pages use a dot: /speckit.specify. The README and the quickstart use a hyphen: /speckit-specify, because that is the default syntax for Copilot skills. Codex and ZCode use $speckit-specify. Kimi uses /skill:speckit-specify.
I’m not criticising anyone here. My own two slide decks on this subject don’t use the same notation either.
These are all the same commands. If you copy one from a blog post and your agent doesn’t react, this is almost always the reason, not a broken install. Check what your integration expects and stay with it. I use the hyphen form below.
The commands, in order
The order matters. Each command uses what the previous one produced, and each one gives you a file you can read before continuing.
/speckit-constitution
Run this once per project. It defines the rules you don’t want to repeat for every feature: your testing expectations, your architecture constraints, your documentation standards. Everything after this is checked against it.
/speckit-constitution All public APIs must be documented. Business logic
must be unit tested. We use vertical slice architecture. No logic in
controllers.
Write rules that your repository already follows, not rules you wish it followed. If you give the agent rules your code doesn’t respect, it will argue with you on every file.
/speckit-specify
Describe what you are building and why, in plain language. No technology, no stack, no implementation details. This produces spec.md.
Three things to check in the result. First, the tone: are you describing users, or are you describing code? Second, the constraints: are they written down, or did you assume them? Third, what you left open on purpose. Leaving something open is a decision. Forgetting it is a bug you haven’t found yet.
This is the step people rush, and it’s the step that decides everything else. If the spec is vague, the plan will be vague too, and the code will fill the gaps in a way you didn’t choose.
/speckit-clarify
This one is optional, but I don’t recommend skipping it. The agent reads your spec and asks you about the parts that are not clear: edge cases, permissions, state changes you didn’t think about. It’s not a comfortable step, but it’s a useful one. If you used Spec Kit a while ago, this command used to be called /quizme.
/speckit-plan
Now you can talk about technology. Stack, architecture, data model, API design. This produces plan.md.
/speckit-plan Use .NET 9 with minimal APIs and EF Core against SQL Server.
Vertical slices per feature. xUnit for tests. Expose OpenAPI.
What I like about this step is that the agent explains its choices. You can challenge them, add constraints, or ask for something else. The decision ends up written down instead of guessed. The next developer on the project will thank you for that.
/speckit-checklist and /speckit-tasks
/speckit-checklist creates quality checklists for your requirements. /speckit-tasks turns the design files into tasks.md, an ordered list of tasks that respects the dependencies.
My rule here is simple: one task should be the size of one pull request. Each task should be testable on its own, and the order should tell you something real about what depends on what. This is also the first moment you can count the work. You can estimate from a task list. You can’t estimate from a prompt.
/speckit-analyze
This checks the spec, the plan and the tasks against each other, before any code is written. It’s cheap to run, and it finds the contradictions you created by writing the plan and the spec on different days.
/speckit-implement
This is where the code finally gets written. The agent works task by task: it codes, it tests, it commits. At this point it has your rules, your spec, your plan and your task list. It isn’t guessing what you want anymore. It’s following a document you approved.
Two things to watch. The code should stay readable instead of arriving in one big block. And when the agent goes off the plan, it should tell you instead of hiding it. If the implementation is drifting, fix the spec, not the code.
/speckit-converge
This one is recent. It arrived well after my talk, and most guides still don’t mention it.
converge compares your codebase with the spec, the plan and the tasks, and finds what is missing. It only adds: it never edits or deletes your code, and the only thing it can write is new tasks in tasks.md. If it finds gaps, you run /speckit-implement again, then converge again, until it answers Converged.
I think this is the most important command of the list. “Done” stops being an impression you have when you look at a diff. It becomes something you can check against a file.
When not to use it
For a one-line bug fix, all of this is too much. Just fix the bug. Spec Kit has a separate extension for small fixes:
specify extension add bug
The process is worth it on features that are big enough for a misunderstanding to cost you real time. In my experience, that’s most of them.
