21KB
Spec Driven Development — Chapter-12: 5 - The complete SDD cycle
- Source: /library/Spec Driven Development/source-file.pdf
- PDF pages: 99–111
- Pages without text: none
5 - The complete SDD cycle Before the first specify , a map In the previous chapter you wrote the To-Do's constitution. The project's rules are set, the ground is prepared, and the temptation now is obvious: open the terminal, run the first specify , and start building. Hold that impulse for one more chapter. Before laying the first brick, an experienced builder opens the house plan and traces the whole path with a finger: where you come in, how the rooms connect, where the plumbing runs. That time pays for itself: it is what keeps you from tearing down a wall later. With specification-guided software the same holds. Before taking on the first feature, it is worth climbing to a high point and seeing, from above, the path a feature travels in full: from nothing, when it is only an idea, to code running and integrated back into the project. That is the map this chapter draws. The question it answers is simple to state and easy to underestimate: what journey does a feature travel, from the first sentence written about it to the line of code that delivers it? What are the points it passes through, in what order, and why that order and not another? What comes out of here is the map: the drawing of the whole path, so that when you come down to the ground and start walking, you always know where you are and what comes next. Whoever sees the path from above doesn't get lost in the middle of it.
What you're learning is the cycle, not the app Here is the thesis that holds up the rest of this material, and it is worth saying plainly: what you are learning is not the To-Do. It is the cycle. The To-Do is a vehicle. It is deliberately simple, so that the mechanics of the flow never stay hidden behind the complexity of the problem. You will see it born feature by feature in the next chapters, but the app itself is disposable: nobody needs one more task app in the world. What is not disposable is the path each of its features travels, because that path is the same for any software. Swapping the To-Do for a banking system, a game, or a logistics dashboard changes the content of each step, but doesn't change the shape of the cycle. It is the shape you are learning. And what is the unit of this cycle? The feature. Not the whole project at once, not a loose line of code, but the feature: a new, coherent capability the system comes to have. “Create and list tasks” is a feature. “Mark a task as done” is another. Each is a unit of work that is born as an idea, travels the whole cycle, and ends up integrated into the rest of the system, ready to use. When one reaches the end, the next restarts the same path from scratch. That is why the cycle matters more than any specific feature. You are not going to memorize how to build “create and list tasks.” You are going to internalize the path, and then you will be able to travel it with any feature, in any project, for the rest of your developing life. Memorizing commands is fragile; understanding the cycle is what stays. The feature lives on a branch: main → branch → merge
This cycle doesn't happen in a vacuum. It happens inside git, which here stops being a technical detail and becomes the frame of the whole feature, from start to finish. It works like this. Your project has a main line, the main : the stable version, the one considered good and sound at any moment. When you go to start a new feature, you don't touch main directly. You create a branch: a parallel, isolated line of work that starts from main and carries the feature's name. Think of it as a separate workbench, where you can saw, sand, and make mistakes freely without spreading sawdust in the main room. The whole cycle of the feature happens inside that branch. When the feature is ready and sound, you do the merge: you join the branch's work back into main . main takes in the new feature and goes back to being the stable version, now a bit more complete. The branch has done its job and can be discarded. The next feature starts from main again, on a new branch, and the path restarts. There are three edges easy to name: leaving main by creating the branch, running the cycle inside it, merging back. That is the frame, and it repeats identically for each feature. An honest caveat: technically spec-kit doesn't force you to work on branches; it is possible to run the cycle straight on main . The “one feature, one branch” frame is a recommendation of this material. But it isn't a loose recommendation: the tool itself ships a git extension that creates, for each new feature, a numbered branch with its name. The structure is optional, and even so the tool considers it valid enough to offer it ready-made. Adopting it is following the path spec-kit itself paves. Inside the branch, the work doesn't become a single undistinguished block. Each important artifact the cycle produces becomes a commit, a saved point in the branch's
history. You will see further on that the core of the cycle produces four artifacts, and the rule of thumb is one commit per artifact: the branch comes to tell its own story, step by step, instead of dumping everything at once at the end. We won't turn this into a git tutorial; what matters is the shape. The feature is born on a branch, matures inside it in successive commits, and integrates through main at the merge. Keep that, and the rest of the map fits together. The map in a single figure Now put it all into a single image. The git you just saw and the cycle we are about to detail aren't two separate subjects: they are the same figure, seen from above. This is the diagram that anchors not only this chapter, but all the next ones. It is worth reading calmly once; after that it becomes a reference.
Read the diagram out loud once. At the top, the constitution, above everything, governing the cycles without being part of them. In the middle, main leaving on a branch and receiving the merge back. Inside the branch, the cycle: a straight line of four steps, the core, and three checks hanging off it as optional. At the bottom, the chain of artifacts that each step writes and the next reads. It is the whole chapter in one figure. Keep the image: the next chapters come back to it and only shine a spotlight on the step at hand, without redrawing the map. The constitution sits above the loop One thing jumps out of the diagram: the constitution is not inside the cycle. It is above it, and that is on purpose. The constitution you wrote in the previous chapter is a once- per-project decision. You write it once, at the start, and it comes to govern all the features that will come. It isn't born again with each feature; it isn't a step that repeats. That is why it lives above the cycle, and not as one more step inside it. The general rules of the project are stable; what repeats is the building of each feature under those rules. From that follows something important for reading the rest of the map: the cycle that repeats with each feature starts at specify , not at constitution . When you go to build the To-Do's first feature, you won't rewrite the constitution; it is already there. You go straight to specifying what you want. The constitution was the founding act of the project, prior to and above the repeated work. But the constitution doesn't stay forgotten in a drawer after being written. It reappears inside the cycle, at a single, precise point: in the plan , as the constitution check. When you plan a feature and decide the technology and the approach, the flow
checks whether that plan respects the principles you fixed in the constitution. If the plan broke the layered architecture, or tried to smuggle in a decision the constitution forbids, it is in that check that the conflict shows up. The rules written once come back to demand conformance, always at the same spot in the cycle. Above the loop as governance, inside the loop only as a check: that is how the constitution takes part. The loop, step by step We reach the heart of the map. The cycle each feature travels has seven steps, in this order: specify → clarify → plan → checklist → tasks → analyze → implement Let's go through them one by one. The depth here is deliberately medium and even: each step gets enough for you to know what it does, what it produces, and when to run it, without any of them stealing the scene. The spotlight on each step, with the fine detail of how it behaves in practice, is what the next chapters will give, one step at a time. Here you are seeing the whole set. Before the names, one piece of guidance that holds for all the steps: each of them is an iterative conversation with the agent, and never a button you press once. You run the command, read what came out, point out what turned out wrong or incomplete, ask for an adjustment, reread. Repeating a step's command to revise it is normal use of the flow, as legitimate as running it the first time. And the posture that most improves the result fits in an instruction worth giving the agent at any step: when in doubt, ask; never assume. An agent that asks hands the decision back to whoever it belongs to, you; an agent that assumes hides the decision inside the artifact, where it costs more to be found.
specify opens the cycle. It is where you describe the what and the why of the feature: the problem it solves, who benefits, what counts as done. It is the anatomy of the specification you saw in Chapter 2, applied to a concrete feature. Notice what specify doesn't do: it doesn't decide technology, it doesn't talk about code. It describes the need. The artifact it writes is the spec. clarify comes right after. Every spec, however good, leaves loose ends: passages that allow more than one reading. clarify is the step that asks about what turned out ambiguous and writes the answers back into the spec, before any planning. Resolving the ambiguity now, on paper, costs a paragraph; resolving it later, in code, costs rework. plan decides the how. It is here that technology enters: the language, the database, the framework, the architecture. The spec said the what; the plan decides with what and in what way to build. And it is inside the plan that the constitution check we saw runs: the plan is born already checked against the project's rules. The artifact written is the plan. Right after the plan (and sometimes also after the specify ), you will notice in the sessions an extra command running on its own: /speckit-agent-context-update . It updates the agent's context file (the CLAUDE.md or the equivalent of the assistant you use), pointing to the most recent plan, so that any future session starts already knowing which feature is under way and with which technical decisions. It is a maintenance step, run as an automatic hook; there is no decision of yours involved, and it is enough to know why it shows up. checklist is a quality gate. Before breaking the work into tasks, it validates whether the spec's requirements are complete and clear enough to build on top of them, reading the plan as supporting context. Think of it as a unit test for the written
requirements: it doesn't check whether the code works, but whether the specification is well written. It is the question “is this ready to become work?” asked systematically, item by item. tasks breaks the plan into executable, ordered steps: the concrete list of what to do, in the right sequence, with dependencies respected. Since this material adopts test-driven development, it is here that the tests enter the list, before the code they cover. A warning is worth it: spec-kit treats tests as optional and only includes them in the tasks when the TDD approach is asked for explicitly, whether by the constitution or by the spec itself. It isn't an automatic effect: it is a consequence of the project having declared that it wants tests. Since the To- Do's constitution adopts TDD, the test tasks show up; in a project that didn't ask for them, they simply wouldn't be generated. The artifact written is the set of tasks. analyze is the last check before building. It checks the consistency among the three artifacts you already have: do the spec, the plan, and the tasks talk to one another? Does a task contradict the spec? Was a requirement left with no task to cover it? analyze catches that kind of mismatch before it becomes wrong code. The analyze report is only worth something if you act on it. The correct practice is to fix every point raised before running implement : ask the agent to apply each correction in the source artifact (the spec, the plan, or the tasks, as the case may be), run analyze again if the change was big, and only then release the build. Implementing with an open report of inconsistencies is paying to turn each inconsistency into code. implement closes the cycle. It executes the tasks and produces the code that delivers the feature and passes the tests. It is the only step in which the software is actually born; all the previous ones exist so that this one is cheap, safe, and free of surprises.
The core and the three checks Look again at the order and notice a skeleton inside it. Four steps form the core loop: the minimum path, without which there is no feature. specify → plan → tasks → implement Specify, plan, break into tasks, build. That is the irreducible route, and it is what produces the four versioned artifacts, one commit each. The other three, clarify , checklist , and analyze , are interleaved checks: control points strongly recommended, but optional with judgment. The default recommendation is to run them; the freedom is being able to omit them when the feature is trivial and crystal clear. Think of them as the safety net you decide to stretch according to the risk (the deep-dive box further on gives the practical criterion of when to skip each one). And it is worth fixing what tells the three apart, because they are easy to confuse. clarify attacks ambiguity (what is misunderstood?). checklist attacks completeness (is everything here, ready to build?). analyze attacks consistency (do the pieces fit together?). Three different questions, at three different moments in the cycle. Whoever understands this division of labor never swaps one for another. A validity warning, finally. These names and this order are spec- kit's at the date this material was produced. Tools evolve: a command may be renamed, the sequence may gain or lose a step. The stable path, the one worth learning, is the shape of the cycle: specify, clarify, plan, validate, break down, check, build. For the exact names and the options of each command in the version you have in hand, the source is always the official spec-kit documentation.
Deep dive (optional). The constitution check runs embedded in the plan , with no command of its own. In practice, when generating the plan, the flow opens the constitution, confronts each principle with the plan's decisions, and records the verdict in the plan's own artifact. That is why it appears in the diagram glued to the plan , and not as a loose box: it is a section of the plan, not a step of the cycle. Deep dive (optional). The pairing between check and commit follows the logic of “one commit per core artifact”. Since clarify , checklist , and analyze don't create a new artifact (they refine or check the existing ones), they don't get a commit of their own: clarify goes into the spec's commit, checklist into the plan's commit, analyze into the tasks’ commit. The branch ends up with four clean commits, one per artifact, and each check travels along with the step it serves. This commit structure is a choice of this material, not an obligation of the tool, but it is a choice spec-kit itself endorses. Its git extension offers automatic commits per step, with ready-made messages like “Add specification”, “Add implementation plan”, “Add tasks”, and “Implementation progress”: exactly one commit per core artifact. The checks, when they have an automatic commit, use messages like “Clarify specification”, which add to the artifact that already exists instead of creating a new one. In other words: the convention is opinion, but opinion the tool considers valid enough to ship built in (off by default, you just turn it on).
Deep dive (optional). When to skip a check? A practical criterion: skip clarify only when the spec has no point you would reread twice; skip checklist only when the spec and plan are short and obvious; skip analyze only when there are few tasks and none touch a sensitive area. When in doubt, run it. The cost of a check is minutes; the cost of skipping the wrong one is redoing work already built. The artifacts talk to each other; that's why you clear the context There is a thread stitching all these steps together, and it is what turns the list of seven steps into a real system. Each step writes an artifact, and the next step reads that artifact and works from it. The spec feeds the plan ; the plan feeds the tasks ; the tasks guide the implement . It is a chain: spec → plan → tasks → code Notice the decisive detail: each step reads the artifact the previous one wrote, not the history of the conversation that produced it. The plan doesn't reread the chat that generated the spec; it reads the spec. The tasks don't reconstruct the reasoning of the planning; they read the plan. The state of the work doesn't live in the memory of the conversation with the agent. It lives in the versioned files. That is why you can switch models, and even agents, in the middle of a loop without losing anything: a more robust model for the complex step, a more economical one for the simple step, and the chain of artifacts stays whole. From that follows the thesis that governs the way of working in SDD: the documentation is the source of truth, not the chat. What counts is what got written in the artifacts, because that is
what the next step will read. The conversation is the scaffolding that helped produce the artifact; once the artifact is good, the scaffolding can come down. That is exactly why the /clear between steps, that habit the previous chapter asked you to adopt, is safe. Clearing the agent's context at the end of each step doesn't throw work away, because the work wasn't in the context: it was in the artifact, written and committed. The next step will restart by reading the file, without dragging along the dead ends of the previous conversation. And since each core step commits its artifact, the branch's own history is the proof that nothing was lost: at any moment, what matters is saved to disk, versioned, and not in the window of a conversation that grows and gets more expensive with each interaction. Assembling that window on purpose, deciding what goes into each call and at what price, 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. You do not need it here: the whole cycle in this book runs on the simple rule I just gave, clear the context at the end of each step and let the artifact speak for the next one. The map is drawn: the bridge to Ch. 6 The map is complete: you have the whole path in your head, seen from above. Now we come down to the ground. The next chapter travels this cycle for the first time, from start to finish, building the To-Do's first real feature: create and list tasks. And it travels it with a spotlight lit on the first step, specify . You will see, in detail and in practice, what it means to specify a feature well: how the spec is
born, what questions it answers, where it tends to fail. The other steps appear, because the cycle runs in full, but it is specify that gets the focus. And that is the shape of the next chapters. Each one travels the complete cycle of a feature and shifts the spotlight one step ahead: one chapter lights up the plan , another the tasks , another the implement . The map you just kept doesn't change; what changes is the step under the light. That is why it was worth drawing it now, calmly, before walking. Among those chapters are the ones with .5 in the number. They redo the same lap file by file, with the real text of each artifact beside the code that came out of it. One of them deserves an explicit address right away: Chapter 10.5 is the one that records the complete lap, from requirement to second iteration, because it was on the fifth feature that manual validation failed something and the fix had to travel back up to the spec before touching the code. If at any point you want to see the whole cycle at once, defect and repair included, that is where you go. From the next chapter on, we walk.