🤔 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

[thlandgraf]

Building a sibling tool (SPECLAN — a free VS Code extension for spec management, creator here), and I hit each of these the same way you described. Sharing what's actually working, less because the tool matters and more because the underlying patterns are what fixed it.

The naming-drift one (Auth vs Authentication vs Login) goes away if the canonical identity isn't the title at all — it's an ID in frontmatter. We use branded IDs per entity type:

---
id: F-2419
type: Feature
parent: G-100
status: approved
---

Titles can drift freely. Cross-references inside spec bodies cite the ID (e.g. "Depends on F-2419"), so renaming the feature title from "Auth" to "Authentication" doesn't break anything downstream. The renames you naturally do over a project's life stop being a maintenance event.

To @charliejacobsen's point about frontmatter as a "mini language" — that's exactly the bet. We treat YAML frontmatter as the typed structure (id, type, parent, status, ac[]) and the Markdown body as the human prose. Validation runs over frontmatter. The body stays natural language + diagrams. Continuum of structure works in practice: you can be loose at the Goal layer and strict at the Requirement layer.

Relationships — we lean on hierarchical containment first, explicit refs second. Goals contain Features (and sub-Features form a tree), Features contain Requirements. So a lot of "this depends on that" is just spatial: it sits in the same parent. For cross-tree dependencies we cite IDs in the body. We've toyed with explicit depends_on: in frontmatter but every time we ship it, it bit-rots faster than the prose refs do, because reviewers see the prose and miss the YAML when reviewing.

On the source-of-truth vs decision-history tension — we resolved this with a status lifecycle: draft -> review -> approved -> in-development -> under-test -> released -> deprecated. An approved spec is current contract. A deprecated spec is decision history (kept, not deleted). Plus a ChangeRequest entity (CR-####) attached to a parent spec, which captures "this approved thing needs to change because of new feature X" without losing the original. So compaction-by-archive isn't the only option — you can keep the old spec as a deprecated node and let the CR carry the rationale.

For the Obsidian-style visualization — we render the tree inside the IDE itself (the spec hierarchy is the file structure, so a TreeView gets you most of the way), but the bigger win was generating a traceability matrix on demand instead of trying to maintain a graph artifact by hand. The hand-maintained graph approach (we tried it) was the first thing to drift.

Happy to share the spec format if useful — docs are at https://speclan.net. Mostly though, the lesson I'd hand to anyone hitting this wall: anchor identity in frontmatter IDs, not titles, and make deprecated a first-class status. Most of the "specs drift" pain folds back to one of those two missing.