Two open approaches to the same idea
Spec Kit and OpenSpec both treat the written spec as the source of truth for code, tests and coding agents. They differ in shape. Spec Kit generates a complete spec for each feature. OpenSpec keeps one living spec and records each change as a delta against it. We use each where its shape fits.
Both are open-source projects with public repositories: GitHub Spec Kit and OpenSpec. Both work with common coding agents. Neither requires a paid service, and both store everything as Markdown in your repository.
| Spec Kit | OpenSpec | |
|---|---|---|
| Best fit | New products (greenfield) | Existing codebases (brownfield) |
| Unit of work | A full spec per feature | A change proposal with deltas |
| Flow | constitution → specify → plan → tasks → implement | propose → apply → archive |
| Spec over time | One spec folder per feature | One living spec, updated by each change |
| Branching | A branch per feature | No branch convention required |
| Output | Markdown in the repository | Markdown in the repository |
How Spec Kit runs
Spec Kit runs a phase-gated flow. It starts from a constitution of project-wide rules, then each feature moves through specify, plan, tasks and implement, each step producing a reviewed document. Every feature gets its own spec folder and usually its own branch. It suits work where most of the product does not exist yet.
- Constitution. The project’s non-negotiables: accessibility, performance, privacy, security, brand. Written once, revised rarely.
/specify. A full feature spec: user stories, acceptance criteria, states and data./plan. The technical plan: components, tokens, integrations, test strategy./tasks. Small, verifiable units, each linked to criteria./implement. Building the tasks, by engineers and supervised agents.
The strength of this flow is completeness. A new product has no existing behaviour to protect, so writing a whole spec per feature costs little and leaves no gaps. The phases also give natural review points: we and the client agree on the spec before planning, and on the plan before building.
How OpenSpec runs
OpenSpec keeps a single spec that describes how the system behaves today. Each change starts as a proposal that lists its deltas against that spec: requirements ADDED, MODIFIED or REMOVED. Once the change is built and accepted, the deltas are merged into the living spec and the proposal is archived.
/propose. A change proposal: why, what, and the deltas to the current spec./apply. Building the change against its tasks./archive. Merging the deltas into the living spec once the change is accepted.
## Change: spending limit cool-down
### MODIFIED Requirement: Raising a spending limit
Raising a limit takes effect after 24 hours (was: immediately).
### ADDED Requirement: Pending limit banner
While a raise is pending, the account header shows the new limit and when it applies.
### REMOVED Requirement: Limit change confirmation email
Replaced by the in-app banner.
The strength of this flow is proportion. Most work on a live product is many small changes. Writing a full spec for each would be slow. Writing a delta is quick, and the reviewer sees exactly what changes against what exists.
When we use which
We choose by the state of the codebase, not by preference. A new product or a new standalone surface gets Spec Kit. An existing frontend, even one being rebuilt route by route, gets OpenSpec. Some engagements use both: Spec Kit for a new section, OpenSpec for changes to the parts already live.
| Situation | We use | Why |
|---|---|---|
| New product from scratch | Spec Kit | Nothing to protect; full specs leave no gaps |
| New standalone surface on an existing product | Spec Kit | It behaves like a new product with known integrations |
| Changes to a live frontend | OpenSpec | Deltas keep each change small and reviewable |
| Audit findings to fix | OpenSpec | Each finding is already a delta |
| Gradual rebuild, route by route | OpenSpec, with Spec Kit for new routes | Protect what exists, specify what is new |
An Audit always ends in OpenSpec deltas, because its findings describe changes to something that already exists. A Spec Sprint can produce either, depending on what we are specifying.
What stays the same in both
Whichever tool we use, the four artifacts of the spec pack are the same: a constitution, specs with Given/When/Then criteria, a plan and tasks. The quality gates, senior review and trace reports do not change. The tool shapes how specs are organised. It does not change the bar.
Why you are never locked in
Both tools are open source and keep everything as Markdown in your repository. The spec pack, tests and trace reports are plain files that any team can read and extend. They work with Claude Code, Cursor, Copilot, Gemini CLI or no agent at all. If your team takes over, it can keep the same workflow, switch tools, or drop tooling and keep the specs.
We also adapt to tooling you already use. If your team has its own spec format, we map our artifacts onto it rather than imposing ours. What matters is that criteria are written down, tested and reported. The file layout is secondary.
Moving from one to the other
The choice can change as the product does. A product specified with Spec Kit usually moves to OpenSpec once it is live and most work becomes small changes: the feature specs become the starting point of the living spec. A large new feature on an OpenSpec project can still get a full Spec Kit spec of its own. We record the reason for each choice in the plan, so the team can see when it no longer holds.
Further reading
The official documentation for each project is the best source on its current commands and conventions, which change between versions. For how we make the choice on a real project, read our note on choosing Spec Kit or OpenSpec.