Evolving specs

[Ian1971]

Using the spec kit I create a spec and implement it.
What is the process when I now have a change request. Spec driven development would seem to indicate that the spec is the source of truth for the system, but spec kit leads me to create a new spec with the variation. That doesn't seem to be in keeping with spec driven development, as now to know what the system does I need to read both specs.

Or should I be getting the AI to update the master spec as well?

[simongartz]

You should not change the master spec, if you create a feature you just add the spec with the new feature. If you change you say that you change that in the new spec.

Ex.

spec1 - Todo list with local storage
spec2 - Add login
spec3 - Replace file storage with option to use cloud storage - This one replaces the implementation of the local storage with a cloud storage, to comply with the change request.

[colinmacleod]

Each spec.md is not a meaningful project-level artefact since it's only updated for the life of the feature. Later specs will contradict earlier ones.
You can understand the whole system if you keep all your specs, and read them in turn. But it's an exercise in gymnastics.
If you keep all your old user stories and the order in which they were played, you can understand the implementation. It's not something you really want to do.
When I wrote the comments, I misunderstood the intent; I was hoping it would update an artefact that describes the project, and this would become the new "Source of the truth." As it is, the source of the truth has to be the code since nothing else really tells you what is acheived.

[simongartz]

Agree, after a while when you have a lot of specs it could be nice with a "rollup" or "snapshot" command to merge the growing list of specs.

[colinmacleod]

Or... why not do it iteratively? There doesn't seem to be a completion command - to execute when you finish the feature. This feels like it belongs there.

[euroblaze]

Agree, after a while when you have a lot of specs it could be nice with a "rollup" or "snapshot" command to merge the growing list of specs.

Yes, merge and ..

• check integrity
• remove duplications
• expect contradictions and, resolve them

I guess this should be done at every iteration of the specification by /specify.

Baring the simplest apps, like a todo-list, address-book, habit-tracker etc., specs do evolve over time, and changing real-world / business requirements.
So if a team commits to the SDD approach, and code-gen is (completely?) delegated to AI, the SDD process should not only allow for scope-expansion, but also feature integrity and consistency of database.

Security audit is another topic..

Ps: currently experimenting with spec-kit on a greenfield systems software project.

[odysseyalive]

This is what I was looking for. The examples aren't real clear. What methods do we use to manage multiple specs (like in your example: Spec001, Spec002, etc.)?

[erf1nd0r]

Thank you @simongartz for your explanation. Where I personally have a hard time understanding is, that for each spec one git branch is created. Based on your example: spec1 is the todo list with local storage. So the tasks on a high-level would be like create project structure, create tests, implement the todo list with local storage.
This sounds like a lot of stuff being done in just one branch. Getting a PR like this to review sounds not manageable to me.
Am I missing something? I didn't find a proper explanation in the documentation.

[rafaelassumpcao]

Pardon my ignorance, but what would be your expectations if not a PR containing code + tests (considering project structure as a tight dependency ofc)

[erf1nd0r]

Hehehe. Thank you for your reply. This is exactly what I am expecting. I think, I have a hard time explaining what I don't understand.

Let's go with the example from the documentation.
/specify Real-time chat system with message history and user presence

This creates the branch 003-chat-system.

My point is, shouldn't the implementation of this specification be split into smaller features (and branches)? Especially when the specification is split into tasks (after the planning), shouldn't these tasks be the features that should be put in feature branches?

I know, that I can do this manually and generate my own branches for each task.
What I want to understand is, what is the proposed workflow with SDD? For me right now, it looks like each specification is generating one branch. But this doesn't sound right, especially if I want to build something from scratch and not only specify one feature.

[simongartz]

The first spec can be quite large if you are building a large system from the get go. You could also decide to no put everything into the first spec, create an overarching roadmap for the system you want to build and create a spec for different parts of the system you defined in the roadmap.

Regarding the branching in git. I don't think you should bother too much about the branching, it's not a necessary building block for spec driven development.

[Ian1971]

The way I am thinking about it, for an existing mono repo project, is to have a spec project per broad feature, then each feature will have a trail of specs that will define its truth. I'm not sure yet if speckit in its current form works with that because I'd essentially want many spec projects at the src root (one for each broad feature). Not sure if this is "correct" or not, but currently the only way I can think to get it to work for a large existing brownfield project.

[euroblaze]

I guess the approach and experience of SDD will differ for brownfield and greenfield projects. Super interesting..

[Apocatastasis]

What is missing is a snapshot of the project specification on the memory folder, alongside with the constitution. This master spec should be updated when a feature is complete. I think you can even ask the AI to do that and review the output. This master spec should be the starting point for the next feature.

[simongartz]

I also kind of miss a command in the workflow to update the memory, I don't know if this is by design or just not yet implemented. But of course as you state, you can ask the coding agent to update the constitution.md and create extra spec information for you after a spec is complete.

If it should be a snapshot for the current spec in the memory folder is not needed in my opinion as spec-kit already utilise git branching to save each complete spec. The latest constituion.md and the spec templates that is updated when you run the constitution_update_checklist.md should contain enough information to act as the master for the next spec. This way it's possible to go back in time to pick up a specific spec and regenerate if needed.
I do delete the spec branches, but I squash merge to main so I can still easily go back to a specific spec version.

[Apocatastasis]

I have found that on the /plan task the update-agent-context script is called. Looking at the script seems it tries to update your agent project context file (vg. GEMINI.md) with the current feature plan. I guess this is what we were looking for, altough I didn't found any reference to this in documentation.

[jflam]

+1 on the spec (master or not) being updated when a feature is complete. Those are the valuable artifacts in all of this!

What would you suggest as a good mechanism that would work for you to update the spec?

[jaycangel]

I agre, there should always be a single, consolidated specification that reflects the most current features. Without this, it’s inevitable that, over time, the model could accidentally reference outdated information.

Whenever a feature is updated, the root specification should be updated as well. This ensures there’s always a reliable, up-to-date source. If the specification grows too large, there should also be a logical way to reorganize or structure it for easier navigation.

[Ian1971]

Yes I agree. I do think we need a master spec. The truth of the system being a chain of specs is horrible for humans and probably inefficient for AI. Obviously we can get it to generate that ourselves, but it being the final step in the spec kit flow would be nice.

[euroblaze]

100% agree with the master-spec idea.
But wonder if the LLM is effectively capable of considering all _truth, requirements and situational facts (from existing code), and only accordingly produce new code.

[simongartz]

I'm a bit torn to the idea to the idea of a master spec. If you have a master spec, why do you need to create a spec per feature, why not just add it to the master spec, what would be the difference?
I can see the need for a human being to have documentation generate that reflects the system in it's current state. From the llms perspective the source code is kind of the current state, and if you generate documentation of current state you can refer to it for the llm to read if needed.
I can also see a need to do a cleanup of all specs if the number grows, and that could render in a snapshot in time spec, but the reason for that is not about master spec, its more about too many specs :)

[JuergenSchmid]

Sounds reasonable for smaller project, but how can it scale to medium- or large scale projects. The spec can get very large and I wonder if generating the complete code over and over again for smallish changes is possible. So clustering the spec or any kind of incremental approach would be exciting to explore. Would also help during code reviews, where a small change in the spec could cause a review of the complete codebase (again).

[fabiodouek]

@JuergenSchmid , I agree with your point.
But how about a hybrid approach?
Something similar to how terraform/cloudformation works: The user defines target state, and let the underlying engine figure out the plan on what has to be done to achieve the target state.

In the scope of Spec Driven Development, ideally I would like to manage only the target state spec. And let the LLM to figure out: What changed between target and current state specs. Then create a spec plan (plain english what has to change) -> Then downstream to design plan -> task plan and finally implementation.

[jaycangel]

I think it would have to be a combination of reviewing the specs and code together. The specs will give the motivation and the code will give what has actually been implemented.

…

On Thu, 18 Sept 2025, 09:35 euroblaze, ***@***.***> wrote: 100% agree with the master-spec idea. But wonder if the LLM is effectively capable of considering all _truth, requirements and situational facts (from existing code), and only accordingly produce new code. — Reply to this email directly, view it on GitHub <#152 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJN3SUNWSXWIHKFGKAEC3D3TJVEJAVCNFSM6AAAAACGE55LQWVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTINBUGAYTAOA> . You are receiving this because you commented.Message ID: ***@***.***>

[jflam]

Hello! I'm sorry I'm late to the party - I'd like to chime in with some of my own thoughts around this issue:

One way of thinking about all of this stuff is that the spec or specs are really the source code for the implementation. Something that Sean Grove said (paraphrasing) at the AI Engineer Summit was around how we spend all this time versioning the source code that today is generated from agents, but yet we don't really do any version control management, updating, ensuring that it's consistent as the source of truth of the specs, which seems odd. It would be like if we spent all of our time carefully versioning the binaries produced by our compilers and throwing away the source code.

So it becomes really important, not so much is there a single master spec, a set of feature specs or anything else. It's that those things must be kept in sync with the source code. And that requires a certain amount of discipline to make it effective. I don't think that for any reasonable size project that we could have just one spec. I think there is some kind of natural hierarchy that evolves in your projects.

What I have taken to doing recently is writing a spec for a feature that is more of a unified spec. Both the motivations as well as the implementation details and the research and other things are captured inside of a single document that I can iterate with the AI. But then what I do is I spend cycles in the agentic loop to close the loop between the code that was actually written and the spec because these things naturally diverge as it's pretty rare for the agent to one-shot the code and then call it a day. Oftentimes there's follow-ups and other things, right? Because you underspecified something, there's a bug, etc. And those changes ultimately become material. So unfortunately right now it's on you to fold those things back into the spec or ask the agent. to fold those changes and updates back into the spec.

[fabiodouek]

I'm glad I saw this discussion. I started to evaluate Spec-Kit this week, and I would like to understand the vision on how leveraging the current model will scale overtime in projects where there are multiple iterations.

I've been reasearching, evaluating different Spec Driven Development tools and leveraging them to build greenfield applications.

The way I'm using Spec Driven Development so far which is working for me is:

• Equivalent of the constitution.md, but split into:
  • Company/Team specific steering: e.g: Coding conventions, tech convention
  • Project specific steering
• Features Spec: Here I'm currently breaking into product features. e.g: One per microservice / component

If we focus on the features spec: The way I'm using is very different than SpecKit is designed to work. The model I'm using works extremely well, however it does have limitations for teams who are developing multiple feature branches in parallel. It's not an issue for me at the moment though.

The way SpecKit handles features, by aligning with feature branches is great for incremental work, but it seems to go against the Spec Driven Development principles (at least based on my understanding).
I see the specifications being long lived specs as the source of truth. It should represent the target state rather than the incremental changes. Or maybe we should decouple the requirement/design from the tasks.

I fully agree with @simongartz , the middle ground would be a command to "compact" multiple "specs" into "target state specs".
But then I wonder if the concept of a "spec" should be repurposed to represent the "target compacted state", and what is defined as "spec" today, becomes the "spec change".

A very simple use case:
For a given microservice which implements a REST API, which have a contract for create_customer(name, dob). If the feature is already released and now I want to add a new optional attribute called country, I would then invoke: "/spec-change add attribute called country to create_customer in customer-microservices spec".

The question then is: Should the flow be:

• update the "target state spec" and the "change-spec" (the current spec concept) at the same time, which allows the developer to review both before moving to the next step; OR
• Handle the incremental specs as-is and have a separate process to compact the specs at the end?

I prefer the first option, as it gives more control to the developer and ability to review consistency in near realtime, rather than compacting it at the end. I prefer to interact with target state and review incremental plan, rather than the other way around.

Keen to get others' views on this.

[BurtHarris]

I'm a couple of weeks into seriously trying to use this on a prototype project. I expected there would be a repo-level spec, and then feature specs subordinate to it. For now, the first feature is essentially the project spec, if I understand it correctly.

I think that the specs (beyond the repro-spec) might follow common branching scenarios:

• Feature development (seems like the current model)
• Bug Fixes (perhaps linked to one or more repo issues)
• Experimentation (good to define what question is the basis for experimentation. Often, the goal is NOT to merge into the main branch, it is just a form of research/planning)
• Stabilization/Release process (different teams seem to have different approaches, but it is critical to shipping.)

Each of these developer activities really needs a spec or a mini-spec, using a different template.

[harikrishnan83]

I have been exploring a related angle, specifically the OpenAPI side of evolving specs (fragmentation across feature folders and keeping a unified root spec for frontend–backend alignment). I have shared details in #443 along with links to my write-up and repo. Would love feedback from anyone who’s thought about this.

[diversit]

I understand the concept of SDD and that each feature or change is captured in a new spec file.
However, using Spec Kit I find myself adjusting the specification and plan before running the implementation.
Since this is an AI tool, I would like to be able to use Spec Kit commands to help updating the specification or plan. Now it creates a new spec. It should be 'smart' enough to see the implementation phase had not run yet for a spec and therefore it should modify the specification and/or plan.

[erf1nd0r]

did you already use the "new" commands /clarify and /analyze?

[natemann]

I would think it would be beneficial to know the most up-to-date requirements for a particular feature.

We run into this all the time with QA. QA will log a bug based on an outdated AC.

[Ian1971]

I agree and a human can't be expected to read a chain of specs to figure that out.