on
Spec-Driven Development with OpenSpec - Source of Truth Specifications
In one of my previous articles I mentioned that I have been experimenting with several Spec-Driven Development (SDD) tools, both to evaluate them and to use them in my own work. Among these, OpenSpec has increasingly become one of my preferred SDD tools. It introduces an interesting idea of having a single top level “source of truth” spec. In this article I will look at the workflow, advantages of the “source of truth” spec and other observations about OpenSpec.
OpenSpec - Change Workflow
OpenSpec Change Workflow • harikrishnan.io • CC BY 4.0 • https://creativecommons.org/licenses/by/4.0/
When I started with GitHub Spec-Kit, a feature workflow diagram by Roslyn Zolandor was immensely helpful. Taking inspiration from the same, I created a workflow diagram for OpenSpec, partly to deepen my own understanding, and partly to articulate the model for others who may be exploring OpenSpec (If you spot any gaps or improvements in the above diagram, I am happy to be corrected.)
The diagram above focuses on the files generated during a change, in addition to the basic workflow already documented in OpenSpec’s README. Here are a few key aspects.
• Change Specification (Delta Spec) - These are the spec files generated when we propose a change. They follow the convention of marking sections as “ADDED,” “MODIFIED,” or “REMOVED.”
• “Source of Truth” Specification - This is the living spec representing the current state of the system. All delta changes eventually merge into this single document (as part of the archive step), which serves as the definitive reference.
• Archived Specifications - As the name suggests, these preserve the historical record of earlier delta specs once they have been merged into the “Source of Truth” spec.
Why the “Source of Truth” Spec Matters?
To understand its importance, it helps to reflect on some of the difficulties I faced with tools like Spec-Kit and Kiro in this context.
Without a top-level spec, feature-level specs are often fragmented across subfolders within the “specs” directory. This fragmentation introduces below issues:
-
Fragmented Understanding - The overall intent of the system becomes scattered across multiple files, making it difficult to maintain a cohesive picture.
-
Evolving specs - There are several questions and confusions that seem to arise in the context of spec evolution which has been well discussed here - Evolving specs #152.
-
Unintended Interactions - Every new feature added risks unintentionally affecting existing behaviour, since there is no unified view for validation. (I had attempted to address this to an extent with an optional “/cross-feature” command to analyse across features).
In my experience, Spec-Kit works best when we keep our changes small and focused (a good idea in general), which also helps manage context length as detailed in my earlier article. And with these small focused changes, I have come to treat the specs folder as a ledger where entries are added but not updated. This means even if we modify or remove capabilities, we are effectively just appending new specs.
If we need an overall spec for the app, we can try to construct an overall spec by sequentially applying all changes. However what we get is only a derivative view, not the primary one. It is difficult to say whether this cumulative spec remains valid or aligned with the real system over time.
This leads naturally to the question of what level of validation we can conceptually expect from such a setup.
Levels of Alignment - Spec and Implementation
I found Birgitta Boeckeler’s article, “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl” (recommended reading) really helpful in this context. She outlines three categories of alignment between specs and implementation.
• Spec-First
• Spec-Anchored
• Spec-As-Source
Even conceptually, when we rely on fragmented specs (as in Spec-Kit or Kiro), we eventually face an alignment problem. As features are deprecated or evolve, related specs become partially invalid. Over time, this makes it impossible to validate all specs against the current system state and expect consistent results. So, this fragment spec approach essentially keeps us in the Spec-First category, where specs are useful for initial exploration and feature definition, but may not remain aligned with the implementation in the long term.
In contrast, by maintaining a top-level spec that continuously represents the live system, OpenSpec is capable of being a Spec-Anchored tool, where validation remains possible at any time against the unified, source-of-truth specification.
I will leave out discussing “Spec-As-Source” in this article in the interest of keeping it focused.
Other observations about OpenSpec
Iterating Quickly - I tend to prefer small, incremental changes, and in this setup, the overall proposal cycle in OpenSpec feels noticeably faster. With Spec-Kit, the planning phase often takes longer (not necessarily a bad thing, since it seems to perform deeper analysis) but OpenSpec’s responsiveness helps maintain a steady rhythm of iteration.
Flow State - Because I am able to iterate quickly, I context switch less often and I am able to remain in my zone of focus for longer.
1-N / Brownfield Projects - OpenSpec positions itself as more brownfield-friendly, and so far that seems to hold true. Whether through updates to the “project.md” file or by naturally evolving the source-of-truth spec, it is able to capture the current state of an existing system and support refactoring and incremental change. I have not yet tested it against a large, complex codebase to truly compare it with Spec-Kit and Kiro, but so far, OpenSpec’s workflow feels natural and unobtrusive when extending existing projects.
Recap
OpenSpec stands out as a particularly compelling tool in the growing Spec-Driven Development ecosystem. I would recommend giving it a try.
That said, I am an active committer on both GitHub Spec-Kit and OpenSpec and continue to use Kiro regularly. From experience, frustration often arises not from the tools themselves but from mismatched expectations.
I would love feedback, questions, or pointers to your own experience with OpenSpec and other SDD tools.
Read the full article on LinkedIn →
Originally published on LinkedIn on November 9, 2025