🤔 How are people managing spec relationships as projects scale?

[kennedy-whytech]

I’ve been using spec-kit more heavily, and I’m starting to hit an issue as the number of specs grows:

It’s getting harder to keep specs connected and in sync as new features are introduced.

A few things I’m noticing:

• Specs tend to become isolated over time
• Naming can drift (e.g. “Auth” vs “Authentication” vs “Login”)
• Relationships between features (dependencies, shared concepts) aren’t always captured
• Older specs don’t get updated when new features affect them

Right now, spec generation works great—but maintaining relationships between specs feels much more manual- no matter to Human or Robot

Curious how others are handling this:

• Do you maintain some kind of canonical naming / registry?
• How do you keep specs from becoming outdated or disconnected? periodic scanning/auditing?
• Do you link specs together (manually or via tooling)?
• Has anyone tried using something like Obsidian (or similar tools) to visualize relationships between specs?
• Or do you treat specs as more “one-time artifacts” rather than something that evolves?

Context

I’ve been exploring ideas like:

• linking specs together (dependencies, related features, etc.)
• keeping naming consistent across a growing system
• using graph-style visualization (e.g. Obsidian) to better understand how features connect

But I’m not sure what the “right” pattern is yet.

Would love to hear how others are approaching this as their spec count grows.

[mnriem]

Archive extension would be one way of looking at it. Another way could be to write a spec that takes say the first 10 specs and creates documentation out of it and then deletes those specs themselves and you have Spec Kit work through that. Or create your own extension! Would love to hear what you decide to do and if you end up doing your own extension, preset or worfklow please do share!

[kennedy-whytech]

Thanks — that’s helpful. I think this also brings up a broader question worth discussing:

Should specs be treated more as source of truth or decision history over time?

The suggestion to combine or archive specs feels like a form of compaction, which might reduce surface area, but could also risk losing some granularity or original context. At the same time, if specs aren’t actively maintained, they naturally drift and behave more like historical artifacts anyway.

So it feels like there’s a bit of tension here depending on which direction Spec Kit is aiming for long-term.

Curious how others are thinking about this — especially as the number of specs grows:

• is the expectation that specs remain continuously maintained as the source of truth?
• or that they eventually get summarized/archived as part of the workflow?

Would love to hear how people are approaching this in practice!

[gabrielisback]

Thank you for raising this topic & I'm interested as well... I think this is also an architecture issue ...

[kennedy-whytech]

@gabrielisback are you hitting the same issue? do you have any solution/direction in mind?

[gabrielisback]

Yes & actually I'm developing a solution (not particularly for this), if you're interested: https://github.com/gabrielisback/spec-kit-ddd
I created a DDD extension and a DDD preset, you can find under extensions/presets.
What relevant to this topic is the architecture.md. I still need to see how well it works.

[charliejacobsen]

I’ve been thinking about a way to introduce more optional structure to support more complicated systems - what if we allowed the YAML frontmatter for specs to be a mini language where you can specify types, requirements, namespaces, interfaces, or other things?

For example, you could describe the names of key components in your system and their requirements (similar to acai.sh), these could be DDD entities, APIs, UI page components, the sky is the limit on extensibility there; acai.sh could be realized as a subset of this functionality (if we also instructed the LLM to annotate code).

And then in the actual markdown you could use natural language and diagrams, possibly referring to those things in the frontmatter (eliminating ambiguity).

Would allow for a “continuum” of structure (could put more in the frontmatter if you want to be more rigorous), and allow us to re-use concepts from programming languages to handle more complicated systems that require name spacing, etc. (The markdown doc is like a sliding window, where the frontmatter at the top can be as large or as small as you want.)

Perhaps we don’t go far in syntax checking of the frontmatter, or type checking, etc - though you could!

We know that virtually anything can be represented with YAML (objects, arrays). So we’d have a lot of expressive power.

How this would all play out with the other concepts, like plans, tasks, etc., I’m not sure.

[kennedy-whytech]

I have been trying out to use "concepts" as a start. At the end of each (spec-kit)feature cycle, use "audit" to link/create new concept/reference old concept in the specs. At the start of each feature, check a registry that contains these concepts.

To visualize it, I use Obsidian

And yes, we can potentially structure them with yaml-similar language/format