Should specification files generated by OpenSpec pushed to the remote git repository?

[govi20]

In spec-driven development (SDD), particularly with frameworks like OpenSpec, the spec is treated as the source of truth. The prescribed workflow commits all spec artifacts directly to the repository alongside the implementation.

However, this raises a few concerns I'd like to get community input on:

• Code, not spec, runs in production. The spec is a design artifact, it describes intent. The implementation is what actually matters at runtime. Treating the spec as source of truth feels intuitive during development, but once the feature ships, the code is the truth. Isn't storing spec files in the remote repo counter-intuitive in the long run?

• Repository bloat over time. In a repo with many contributors and long-lived projects, the number of spec files can grow substantially over the years. Even with archiving (openspec/changes/archive/), the cumulative volume raises questions about repo hygiene and discoverability.

• Keeping spec and code in sync is hard. Code evolves through bug fixes, refactors, and follow-on features. Specs rarely get updated to reflect those changes. Over time, a committed spec can become misleading, describing a design that no longer reflects the implementation.

[kiad]

Hello, isn't that the purpose of OpenSpec to maintain over the time the capabilities definitions ? (I'm new to OpenSpec and have done only a few evolutions but I can see how it keeps code and specs synced).

[clay-good]

Yes — commit them.

From the FAQ: "Your specs, active changes, and archive are part of your project's history. Commit them like any other source. The archive in particular becomes a durable record of why your system works the way it does."

On your three concerns:

• Code is the truth at runtime — agreed, and the spec isn't competing with it. The spec records why the code is the way it is, which the code cannot state. That's the same reason you commit tests and ADRs.
• Repo bloat — these are small Markdown files, and the volume is tiny next to source and lockfiles. Archived changes live under openspec/changes/archive/ and are never loaded unless something asks for them.
• Drift — real, and it's why the delta workflow exists: a change's spec delta ships in the same PR as the code, so the reviewer sees both together. See OpenSpec on a Team.

Closing as answered — reopen or comment if your case is different.

[phonnollbam]

The spec will compete with the code when the code changes and the spec isn't kept up to date. They are not small files when added up, they are often as large or larger than the actual code.