Method · Tooling

Spec Kit or OpenSpec: greenfield and brownfield

We use GitHub Spec Kit for new products, where a full spec is written per feature, and OpenSpec for existing codebases, where every change is a delta against a living spec. Both are open source and produce plain files, so the client is never locked into our tools.

Updated 22 November 2026

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.

  1. Constitution. The project’s non-negotiables: accessibility, performance, privacy, security, brand. Written once, revised rarely.
  2. /specify. A full feature spec: user stories, acceptance criteria, states and data.
  3. /plan. The technical plan: components, tokens, integrations, test strategy.
  4. /tasks. Small, verifiable units, each linked to criteria.
  5. /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.

  1. /propose. A change proposal: why, what, and the deltas to the current spec.
  2. /apply. Building the change against its tasks.
  3. /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.

Start with a Spec Sprint

One to two weeks to a versioned spec you own, whoever builds it.

Start a Spec Sprint