How do you keep your spec files canonical?

[0xnerdben]

What's your strategies to keep spec files canonical?

Two scenarios I keep running into:

1. Agent and human both edit the same spec
Code agent updates a spec file during a task - e.g. it revises spec.md or a contract. At the same time (or in another branch/session), I edit the same file in the IDE or in another tool. We end up with two versions and no clear “source of truth.” Spec-kit gives us the file layout and workflow, but not a rule for “who wins” or how to merge when both the agent and I touch the same file. How do you avoid drift or silent overwrites in that situation... strict pull-before-run, a single place everyone syncs to, or something else?

2. Same spec, multiple repos or many agent runs
Specs live in the repo with spec-kit structure, but they’re read (and in my case sometimes written) by agents in different repos, or by many separate runs. It’s unclear which copy is authoritative. Do you treat one repo as canonical and have everything else read-only? Or do you use a shared store (server, doc system) that both humans and agents sync to, with the repo as a mirror?
I’d love to hear how you handle this ; whether it’s process (e.g. “we always …”), tooling (versioning, merge strategy, or an external canonical store), or something else.

Thanks.

[mnriem]

Are you saying that you want / are changing the specification after Spec Kit implement completes? Or are you talking about the process of WHEN a new specification is created?

[0xnerdben]

I’m not limiting it to “after Spec Kit implement completes” or to “when a new spec is created.” I mean specs that stay in use and get edited over time - by the agent (e.g. while implementing or revising) and by me (in the IDE or elsewhere). So the two scenarios are: (1) agent and I both touch the same spec file at some point, and (2) that file exists in more than one place (repos/runs). In both cases I’m asking how you keep a single canonical version. Does that match anything you’ve run into?

[mnriem]

Spec Kit avoids both problems by treating specifications as immutable once implementation begins. During the refinement window (specify → clarify), both the agent and user can touch the spec through structured commands — but that window closes at /speckit.plan. After that, the spec and its derived artifacts are frozen on their feature branch. There is no concurrent-edit or multi-location divergence problem because each numbered spec lives in exactly one place (specs/XXX-branch-name/spec.md), versioned by git. If requirements change later, you create the next numbered spec — you never re-open the previous one.

[mnriem]

Think of it like closing a Sprint. Once a Sprint is complete, you don't reopen it and edit its stories — you create new stories in the next Sprint. Spec Kit works the same way: each numbered spec is a closed unit of work, and change flows forward into the next one.

[0xnerdben]

Thanks - the freeze approach is clean and I get why it works for Spec Kit's workflow. However, I want to push back a little, because in practice agents are already co-authoring specs on-the-go, not just consuming them and I'm not sure that the immutable model takes this into account. Maybe I'm wrong; curious what you think.

Let me layout some thoughts:

1. The problem of fragmentation: For example: If I build a new feature - let's call it workspace invitations (spec-005) - then add role permissions a couple of weeks later (spec-012) and then refactor the auth flow (spec-019) after a while: what is the invitation system now? In this case, the answer lives across three specs that you have to read in sequence, mentally merging what's still current. With 100+ specs that compounds. Sprints are disposable work items while specs for core features are closer to architectural docs. Do they really work as closed units?

2. Specs get shared before code even exists: This is something that keeps coming up if you want to keep humans in the loop. Specs aren't just input to implementation, they're shared with the dev team, PMs and other stakeholders before any code exists. A PM reviewing a spec doesn't git pull. An agent in a different repo or session doesn't have your branch. The spec needs to be accessible and canonical outside the git push/pull cycle, often before there's even a branch to push to. Git is great for code versioning, but with specs becoming the major artifact workflows need to adapt to their different sharing pattern; they flow outward earlier and wider than code does.

3. Agents continuously modify specs rather than just reading them. Assume, during implementation the agent discovers the data model needs an extra field or some edge case changes a contract. In my workflow, the agent updates the spec while implementing: marking tasks, revising models, adding notes, reconciling older specs that serve as input. The freeze rule means either

(a) the agent can't touch the spec, losing that feedback loop, or
(b) you break immutability in practice.

A real example: I had a spec for document version history with a defined data model. During implementation the agent introduced content-addressable deduplication, resulting in a new table and foreign key. The spec was now wrong. In Spec Kit's model, I'd create a new spec for the refactor, but between the original and the new one, anyone reading the original gets a wrong state. With a living spec, the agent updates data-model.md in place, I see the change with provenance, and the spec always reflects reality.

4. Cross-repo is unsolved: You said each spec lives in exactly one place, versioned by git which is true within one repo. But what about a shared API contract where one agent implements the server in repo A and another implements the client in repo B? Both need the spec and both might discover changes. Where's the canonical version? Git doesn't give you a single source of truth across repos without significant ceremony.

I believe agentic dev will be changing the economics of spec maintenance in general. Traditionally, keeping specs up-to-date cost more than it was worth, so teams often gave up. If agents can read and write specs as part of their normal workflow while tooling handles conflicts and provenance and keeps the human-in-the-loop, then living specs become viable in a way they weren't before. Maybe that's naive, but the freeze-and-create-new pattern does not convince me when features evolve over months with agents in the loop, and when specs need to be shared before and outside of git.

Has anyone here run into this, share these thoughts or tell me where my argumentation has flaws? How do you keep them canonical once they start evolving past the original plan? Or you just don't see a case for that?

Would appreciate to get some discussion on this topic rolling...

[stn1slv]

Dealing with "artifact drift" (where the human edits the code, the agent edits the spec, and suddenly there is no source of truth) is incredibly frustrating.

I handle this by utilizing a strict "Double-Loop" strategy using two custom extensions I built to enforce canonical state:

1. During Development (spec-kit-reconcile)
If the agent and I get out of sync during implementation, I don't manually edit the markdown. I use the reconcile extension. I feed it a natural language gap report (e.g., /speckit.reconcile.run "I changed the API payload in the IDE, update the docs"). The agent surgically updates the spec.md and appends missing tasks to tasks.md to ensure the feature folder remains the source of truth for that branch.

2. After Merge (spec-kit-archive)
Having multiple feature folders lying around makes it impossible to know which one is canonical for the whole project. After a PR merges, I run the archive extension. It rolls the feature up into a central, living project memory (.specify/memory/spec.md).

If you want to experiment with this setup, you can pull them down via the CLI:

specify extension add reconcile --from https://github.com/stn1slv/spec-kit-reconcile/archive/refs/tags/v1.0.0.zip
specify extension add archive --from https://github.com/stn1slv/spec-kit-archive/archive/refs/tags/v1.0.0.zip

[0xnerdben]

Awesome! Thanks for sharing - I've been structuring it similarly: after each implementation pass (or even mid-iteration), explicitly reconcile the spec with what actually shipped. Not rewrite, just surgical updates, like your reconcile extension does. The alternative is specs that are "correct as of last Tuesday" which is worse than no spec at all. The piece I've been pushing further is making that reconciled state distributable, so when one agent or developer updates a spec, other agents working in the same codebase (or across repos) pick up the canonical version automatically instead of reading a stale local copy. That's been the harder problem: not reconciliation itself, but propagation and making sure there's a canonical version of the specs.