18KB
Spec Driven Development — Chapter-08: 3 - Hands on: the SDD tools
- Source: /library/Spec Driven Development/source-file.pdf
- PDF pages: 64–75
- Pages without text: none
3 - Hands on: the SDD tools From the blueprint to the wall In Chapter 2 you drew the blueprint. You started from a loose sentence, “I want a to-do list app,” and arrived at an anatomy that gives direction: the why, the scope, the behavior, the acceptance criteria, the edges. The two chapters after it settled the handwriting of each requirement and the size of the sheet. The spec is ready to guide. But a blueprint, however careful, raises no wall on its own. At some point someone picks up the blueprint and starts laying brick. That moment arrives now. After three chapters of foundation, you touch a real tool, one that takes the specify → plan → tasks → implement cycle and turns it into commands you type and artifacts that appear on your screen. Leaving the concept and getting your hands dirty changes the question that drives the material. Until now the question was “what is a good spec?". From here on it becomes another: with which tool, and why? There is more than one answer, and none of them is magic. There is a handful of SDD tools mature enough to take on a real project, each with its own way of embodying the same cycle, each strong in one place and heavy in another. This chapter won't shove a choice down your throat in the first line. It will first show the terrain: three tools, side by side, for what they really are. Only then, with the terrain in view, do we decide which one raises the wall of this material, and why.
Three ways of doing the same thing Start by getting to know the three by what matters first: the mental model of each one, that is, the unit of work you reason with, and the real order of the steps it makes you follow. All three are operated through a CLI (command-line interface), the way to command a program by typing instructions in the terminal instead of clicking buttons; and, in practice, through commands you give to the AI assistant itself inside the editor. What changes is the shape the cycle takes in each one. spec-kit, from GitHub, thinks in terms of feature. The unit is a feature, usually isolated on its own Git branch, with a specs folder next to it holding the documents for that feature. The real order of the flow is constitution → specify → (clarify) → plan → (check) → tasks → (analyze) → implement , with a few optional steps in the middle.1 You install a CLI called specify , initialize the project, and then talk to the assistant through commands in the /speckit. format (in some agents they show up with a hyphen, /speckit- ). Hold on to the first step of that order, constitution , because we come back to it in the very next section. OpenSpec, from Fission-AI, thinks in terms of change. A change is OpenSpec's unit of work: a package that describes an alteration (the why, the specs that change, the tasks) before applying it to the project. The real order lives in a set of commands under the /opsx: prefix, and goes /opsx:explore → /opsx:propose → /opsx:apply → /opsx:archive ; you can even skip straight to /opsx:propose when you already know what you want.2 Each change carries only the part that changes, which you could call a spec delta, the altered slice of the specification; when the change is archived, that slice is merged into the project's living spec. It is a lighter, looser approach: there is no rules document governing the whole project, and you iterate proposal by proposal.
BMAD Method, from the bmad-code-org community, thinks in terms of epic and story. An epic is a large block of work; a story is a small, implementable slice of it, handled one at a time. It is the most ceremonious of the three. In the current version, V6, the work goes through four phases, Analysis, Planning, Solutioning, and Implementation, and is driven by agent personas, specialized roles the assistant takes on at each stage (an analyst, an architect, a developer, and so on).3 Along the way comes the PRD (product requirements document), the document that says what you want to build and why before discussing architecture. It is a lot of apparatus, and some projects ask for exactly that. For those who want to look inside: in OpenSpec, a change is literally a folder in openspec/changes/ with a proposal.md , the requirements, and the tasks; archiving moves that folder to a history and updates the living specs. In BMAD V6, the default set is six named personas (Analyst, Product Manager, Architect, Developer, UX Designer, and Technical Writer); separate Scrum Master, QA, or Product Owner roles, which appeared in older versions, are not part of that default. Skipping this box doesn't lose you the thread: what matters above is each tool's mental model, not the name of each file or persona. The cycle is the same, the incarnation changes A doubt may hit here, and it is a healthy one: if each tool has different commands and names, what is left of the specify → plan → tasks → implement cycle you learned at the start of the material? The answer is the key to this chapter: the cycle is the same; the tool is just the shape it takes. Specify, plan, break into tasks, and build are still the four steps, in any of the three. What the tool
does is give that cycle a concrete body: commands, files, an order to follow. Switching tools switches the packaging; the content stays. One detail of spec-kit tends to startle at first sight, and it is worth defusing the startle now. Its flow doesn't open on specify ; it opens on constitution . It looks like a step invented outside the cycle you learned, but it is a governance step that comes before it: the constitution fixes the principles that every later decision has to respect, and it prepares the ground for specify to happen within agreed limits. The next chapter is entirely about it; for now, hold on to why it exists: the AI assistant, left loose, tends to build beyond what was asked, and the constitution is the leash that holds that impulse back. The cycle doesn't change from tool to tool; what changes is the accent each one pronounces it with. The honest comparison You already have the mental model. Now the part that decides the choice: where each tool shines and where each one weighs, by the same criteria, without selling any as the single solution. The table below covers the three by the six criteria that matter most when choosing. Right after it, a paragraph of reading per tool, because the meaning of a comparison can't depend on you memorizing a grid. Criterion spec-kit OpenSpec BMAD Method Unit of work one feature at a time, isolated on a project branch one change proposal at a time epics and stories driven by personas Real order governs, explores, analyzes,
specifies, plans, breaks into tasks, and builds proposes, applies, and archives plans, designs, and implements Weight / ceremony medium; with a governance step up front light; no mandatory steps heavy; four phases and many roles Where it shines organized flow, without tying down the technology, switching assistants with no rework quick, small adjustments on a project that already exists large projects, deep planning, multiple domains Weakness young and experimental; an “eager” agent less governance; risk when merging changes steep learning curve; overkill on a small project Maturity / adoption from GitHub; less than a year old; very popular popular; community asks for more documentation stable V6 version; consolidated adoption spec-kit is the balance. It gives you a structured flow, with one artifact per phase, without locking you into a language or a specific assistant: switch agents without redoing the work. It shines when you want discipline without marrying a stack (the project's pile of technologies: language, database, framework). The price is its youth. It is an experimental project, with less than a year on the road, and it carries the vice the constitution exists
to contain: the agent, left loose, is eager and generates beyond scope. Containing that is a matter of instruction and context, and assembling what the agent sees before it decides belongs to Context Engineering (2026, https://books.kodel.com.br/en/books/context-engineering/), the third volume in this trilogy, which answers what the agent sees right now, in the window of this one call, and at what cost. To pick a tool here you do not need it: it is enough to know that spec-kit answers that vice with the constitution, the gate Chapter 4 lays out. It is more ceremony than OpenSpec asks for, and less than BMAD imposes. OpenSpec is the lightness. No constitution, no phase gates, you open a change, describe what changes, and go. It shines on an existing codebase, in that work of adjusting what is already standing in small, incremental changes, without the ceremony of a full flow. The lightness has its cost: less governance means less safety net. There are reports of scenarios lost in silence when two changes touch the same requirement and are archived, and the documentation is still thin for the more complicated flows. Freedom with fewer rails. BMAD Method is the depth. Four phases, several personas (the specialized roles the assistant takes on at each stage, like analyst, architect, and developer), expensive planning done carefully before a line of code. It shines on a large project, with many people and a lot to coordinate, where skipping the planning costs more than doing it. For a to-do list app, though, it is overkill, and it doesn't hurt to say so plainly: setting up four phases and six roles to record and complete tasks is using a truck to deliver a letter. Calling it overkill here does not diminish BMAD; it just means the tool was made for a scale our example does not have. On the right project, all that weight is precisely its strength.
Notice what the table doesn't have: a “best” column. None of the three is the answer to everything. Each one solves one kind of problem well and gets in the way on another, and choosing is matching the tool to your case, not crowning a universal champion. The choice and why With the terrain in view, the material makes its choice: from here on, it builds with spec-kit. The decision comes with a reason, and there are three explicit criteria holding it up. The first is dogfooding, the practice of using the very tool you recommend. I don't recommend spec-kit secondhand: I actually use it, in the work that matters most, building software. I run several development projects with this methodology, from constitution to implement , and it is in that daily practice, and not in a marketing brochure, that I learned where it helps and where it gets in the way. I saw the structured flow avoid rework on a serious project, and I also saw the agent get eager and want to build beyond what was asked, in the way I described in the weaknesses. When this chapter says something shines or something weighs, it is the account of someone who took hits and got it right with the tool in hand, in code that went to production. This material itself is also built with spec-kit, by the same cycle you will operate, but that is the smallest of the reasons: the weight of the recommendation comes from the software projects, not from the text. Recommending what you use every day is more honest than recommending what you admire from afar. The second criterion is the direct mapping of the vocabulary. The cycle you have carried since the first chapter is specify → plan → tasks → implement , and spec-kit's core commands are exactly specify ,
plan , tasks , and implement . There is no mental translation on the way: what you learned in concept is what you type in practice, with the same name. For a material that teaches the cycle, that one-to-one correspondence is worth gold, because it removes a whole layer of friction between understanding and doing. The third criterion is what I call the middle path: the deliberate choice of the intermediate option, neither the simplest nor the most robust, when both extremes charge too high a price. Look at the comparison. OpenSpec is light, but the lightness becomes a lack of net when the project grows; BMAD is powerful, but the power becomes ceremony that drowns a small project. spec-kit sits in the middle: it has enough structure to contain the eager agent, without the paraphernalia that stalls someone who just wants to start. Far from lukewarm, that balance is the position that serves the widest variety of projects, and it was what, in my practice, made me settle on it and not on the extremes. Now the part that matters as much as the choice: it is a teaching convention. If your case calls for OpenSpec's lightness or BMAD's depth, go with it head held high; the cycle you are learning is the same in all three, and almost everything that follows translates to any of them. Lean setup and first contact Enough talk: time to install. The path here is the minimum to go from zero to a standing project, and it stops exactly at initialization. You won't run any flow command yet; that is a matter for the next chapters. The goal of this section is only to leave the tool installed and the To-Do ready to receive the first command.
One caveat before the steps, and it is important: tools like spec- kit ship versions in a matter of days. That is why the up-to-date installation path lives in the official documentation, not here. What follows is the general shape, checked and working, but the living and definitive source is the official spec-kit repository (https://github.com/github/spec-kit).4 When some detail diverges, trust the documentation, not this page. spec-kit runs on top of a CLI called specify , installed with uv , a package manager from the Python world that downloads and runs tools like this one. It is not this material's job to teach you how to install uv or how to deal with Python and its managers: that would be a detour from the main thread, and they are well- documented steps that you resolve with a quick search or by asking the AI assistant itself to explain what uv is and how to use it. With specify available, initializing the project is a single command: specify init todo --integration claude specify init creates the project and, along the way, asks two questions that matter. The first is which AI assistant you use. In the example above I fixed Claude Code with --integration claude , but that is just an example: spec-kit supports dozens of assistants (Copilot, Gemini, Cursor, Codex, and many others), and changing the value doesn't change anything you learn here. The assistant is your choice, as the app's stack always was. The second question is the project's script type, bash/zsh for Linux and macOS, PowerShell for Windows.
What appears after the command is the scaffolding, the skeleton of files and folders the tool generates for you to start from. It is worth opening it and recognizing what came: todo/ ├── .specify/ # the heart of the tool: scripts, templates, and the pr oject's memory │ └── memory/ │ └── constitution.md # the constitution, still blank, waiting for th e first command ├── .claude/ # the integration with the chosen assistant (here, Clau de Code) └── CLAUDE.md # the project's instructions for the assistant None of this is your app yet. There is no screen, database, or to- do list code; there is the scaffolding that will hold up the build. Notice the constitution.md inside .specify/memory : it is the file the first flow command will fill in, that governance that precedes specifying. It sits there, empty, precisely to remind you that the next step has a name. And the setup ends here, on purpose. The tool is installed, the To-Do is initialized, the scaffolding is in view. You still haven't written a line of spec or run constitution ; you only prepared the ground. For anyone who wants to try the other two: OpenSpec is installed via npm and initialized with openspec init ; BMAD is installed with npx bmad-method install . Both have their own documentation and their own flows, and nothing stops you from initializing a test project with them to feel the difference. Here, we go on with spec-kit.
The bridge to the full cycle You entered this chapter with a blueprint in hand and leave with a tool installed and the To-Do project initialized, ready to receive commands. The ground is prepared, and the first command has a name. The next step is to run constitution , fix the principles that govern the project, and from there carry the spec forward through the entire cycle: specify, plan, break into tasks, and, at last, build. The tool is in hand and the To-Do is waiting for the first command.
Footnotes GitHub Spec Kit, official repository and documentation, flow constitution → specify → (clarify) → plan → tasks → (analyze/checklist) → implement and specify init : https://github.com/github/spec-kit · https://github.github.io/spec-kit/ (checked on 2026-06-25, specify CLI v0.11.8). OpenSpec (Fission-AI), official repository, /opsx: namespace and the explore → propose → apply → archive flow with change/archive: https://github.com/Fission- AI/OpenSpec (checked on 2026-06-25). BMAD Method (bmad-code-org), official repository and documentation, version V6 with four phases (Analysis → Planning → Solutioning → Implementation) and six default personas (Analyst, Product Manager, Architect, Developer, UX Designer, Technical Writer): https://github.com/bmad-code-org/BMAD-METHOD · https://docs.bmad-method.org (checked on 2026-06-25). GitHub Spec Kit, official repository and documentation, flow constitution → specify → (clarify) → plan → tasks → (analyze/checklist) → implement and specify init : https://github.com/github/spec-kit · https://github.github.io/spec-kit/ (checked on 2026-06-25, specify CLI v0.11.8).