Why OpenSpec, Not Spec Kit

«Constitution is a large document read once at plan time and then gone from context. When the agent reaches the push step, it constructs the command from recall rather than from the constitution, gets the flags wrong, and hits a 403.»

— github/spec-kit#2219

That is not a tactical bug. It is a structural failure mode: a constitution-based approach requires the agent to hold your governing rules in working memory for the entire lifetime of every task. When the context window turns over, the constitution is gone. The agent guesses — and sometimes guesses wrong by exactly the margin that produces a 403 and a corrupted push.

This article is the data behind our tooling choice. We use OpenSpec internally and we arrived at that choice through comparison, not default. What follows is the honest version: the setup numbers, the failure catalogue, the health metrics, and the cases where Spec Kit genuinely wins.

Measured 2026-05-10; not re-checked since. Benchmark run on macOS 14, Node 22.17.1, spec-kit 0.8.7, @fission-ai/openspec 1.7.0. Every issue state, star count and health metric below is as of May 2026. Model pricing has moved since. Treat the structural findings — the memory model, the brownfield delta model, the constitution failure mode — as durable, and every number as a snapshot with a date on it.

Claims below carry a label where the register shifts: [our benchmark] is something we measured on one machine on one day, [reported] is a third-party issue or practitioner post, [inference] is our reading of what the architecture implies. They are not equally strong and should not read as though they were.

The SDD landscape in three categories

Spec-driven development in 2026 breaks into three philosophical camps, and picking a tool without placing it in this frame leads to the wrong choice for the wrong reasons.

Axis	Spec-first	Spec-anchored	Spec-as-source
Core idea	Spec drives plan; plan drives code	Spec lives alongside code; deltas track changes	Code regenerates from spec; spec is the maintained artifact
Primary tools	Spec Kit, Kiro	OpenSpec, Augment Code Intent	Tessl
Bias	Greenfield, waterfall-shape	Brownfield, iterative	Radical bet on AI-as-compiler
Maturity in 2026	Most-tested	Most momentum (YC W26)	Smallest user base

Within spec-first, Spec Kit is GitHub-blessed and enterprise-distributed. Within spec-anchored, OpenSpec is the dominant CLI.

This article focuses on OpenSpec and Spec Kit because they are the live decision for most developers considering SDD in 2026: both CLI-based, both agent-agnostic, both at the top of the community discussion with a combined 142,000+ stars. The pair where the choice has the biggest cost implication. Tessl, Kiro, and BMAD belong in the picture — they appear near the end — but they are not the decision most readers are facing.

Token economy: the floor

The cost difference starts before you write a single spec.

Setup time

Measured on 2026-05-10 in a clean /tmp/sdd-benchmark/ environment, macOS 14, Node 22.17.1:

Step	OpenSpec	Spec Kit
Prerequisite install	0s (Node already present)	10.5s (`brew install uv`)
Tool install	4.5s (`npm install -g @fission-ai/openspec`)	5.0s (`uvx --from git+https://...`)
Init in repo	1.5s	5.0s
End-to-end cold start	6.0s	20.5s

[our benchmark] Spec Kit setup is 3.4× longer on a fresh developer machine. There is also a trap embedded in the official instructions: the PyPI package specify-cli — the path most developers try first — is not the official Spec Kit. The first install attempt in the benchmark failed silently with «No matching release asset found for claude (expected pattern: spec-kit-template-claude-sh)». The correct command is uvx --from git+https://github.com/github/spec-kit.git. On a real team, this costs 5–15 minutes per developer before someone finds the resolution buried in a closed GitHub issue. Multiply by onboarding size.

Base footprint

After init, both tools place permanent files on disk that the agent loads at the start of every session:

Metric	OpenSpec	Spec Kit	Ratio
Files placed on disk	9	27	3.0×
Total lines	1,276	4,221	3.3×
Total bytes	45 KB	185 KB	4.1×
Estimated always-loaded tokens	~11,200	~25,800	2.3×

[reported] Spec Kit's own issue tracker confirms this tax is real: #1401 reports «Spec-kit commands consume approximately 18.6K tokens across all commands combined». Our benchmark's 25.8K is worst-case (lazy-load brings it closer to 18K in practice, matching the issue's claim). On Cursor's approximately 20K context window, Spec Kit alone consumes 93% of available space before the user types a single word. On Claude Code's 200K context the ratio is more manageable — 9.3% — but the tax is non-zero on every session, for every feature, across every developer.

[inference] This is not a configuration problem. It is the structural cost of a 7-phase workflow that materializes full artifacts on every init.

Per-feature spec floor

The session tax compounds with the artifact floor — the minimum spec size required to describe a feature meaningfully in each format. Benchmark used the same feature for both tools: «Add author field to lab posts with multi-author and i18n display».

Artifact	OpenSpec	Spec Kit
proposal.md / spec.md	27 lines	94 lines
design.md / plan.md	38 lines	92 lines
tasks.md	10 lines	61 lines
Total per feature	94 lines / 4.3 KB	247 lines / 10.9 KB

This is the floor. Published third-party benchmarks show actual agent-generated specs run 2–10× the minimum:

Hashrocket: 250 lines (OpenSpec) vs 800 lines (Spec Kit) — 3.2×
Scott Logic: 689 lines of code vs 2,577 lines of Spec Kit markdown — agent execution 33.5 min vs 8 min, code review 3.5 hours vs 24 minutes

Token cost economics

At Sonnet 4.6 input pricing ($3 per million tokens), the per-feature economics:

	OpenSpec	Spec Kit
15 spec-reads × floor size	~$0.049	~$0.123
3 session-loads × always-loaded context	~$0.101	~$0.232
Total per feature (floor)	~$0.15	~$0.36 (2.4×)

Scale to a 5-developer team shipping 100 features per month:

	OpenSpec	Spec Kit
Monthly	$75	$180
Annual	$900	$2,160
Difference	—	+$1,260/year

[our benchmark] This is the floor scenario. With real agent-generated specs running 2–10× the minimum, the practical annual spread becomes $2,500–$7,000 per 5-developer team. That is a line-item decision for any startup where model costs are already tracked.

Brownfield reality

Most real projects are brownfield. There is always a prototype, technical debt, an MVP that shipped and was never fully refactored. The two tools have fundamentally different answers to this common condition.

OpenSpec was designed for it. Every change is expressed as deltas — ADDED, MODIFIED, REMOVED markers applied against capability specs that persist across branches and sessions. When you begin work on an existing system, you describe what changed, not what exists. The delta archive accumulates: full proposal → design → tasks history, date-prefixed, always readable in the repository root.

Spec Kit was not designed for it. After switching from Spec Kit to OpenSpec, Rida Kaddir wrote: «Spec Kit assumes you're building something new.» The issue tracker provides the evidence:

#2506 — specify init silently fails on existing NX monorepos after a branch switch, producing no spec files. Reproduces on spec-kit 0.8.7, Claude Code, macOS. Open as of May 2026.

#337 — /specify and /plan run, print output to the console, write nothing to disk. Described by the reporter as «pure token burning.» Closed as «not planned.» Not fixed.

Discussion #331 — a brownfield user asked for guidance. Maintainer response: «Have the agent go and research your existing codebase and write it down in a research doc. Then you refer to that research doc from the specs.» That is a workaround, not a solution; the workaround is also unbounded in scope on large codebases.

Discussion #746 — a second brownfield user posted three pain points. Zero replies.

The deeper structural problem is described precisely by jjmasse in The Brownfield Problem: a reverse-engineered spec is a derived artifact. When the underlying code drifts and the spec does not, new features built against the stale spec introduce regressions the spec cannot catch. This is not a bug specific to Spec Kit — it is the consequence of applying a spec-first model to a codebase that was not born from a spec.

[inference] OpenSpec's delta model is architecturally safer here. You never claim to have fully described the whole system. You describe only the changes to it, which is exactly what you know.

The memory thesis

The second structural difference: what survives between sessions.

With OpenSpec, capability specs live at openspec/specs/<capability>/spec.md on disk, updated via delta-merge on every archive. Every agent session that needs to reference the capability reads it fresh from the filesystem. The spec is durable across branches, across sessions, across weeks.

With Spec Kit, specs live at .specify/specs/[NNN-feature]/ — branch-bound and per-feature. Starting a new branch resets what the agent knows about the feature. The constitution mechanism partially fills this gap, but it cannot fill it fully. The headline failure mode of this entire catalogue, #2219, is worth reading in full detail:

«Constitution is a large document read once at plan time and then gone from context. When the agent reaches the push step, it constructs the command from recall rather than from the constitution, gets the flags wrong, and hits a 403.»

This is not an edge case. It is what happens architecturally when a long-running task causes context to turn over: the governing document disappears, and the agent substitutes recall. The 403 in that issue is a specific outcome; the general pattern is agent completes task with wrong assumptions because the spec it was governed by is no longer in context.

A separate and equally revealing data point: Discussion #152, in which a Spec Kit user documented their own workaround — «Treating specs as session deltas rather than permanent truth has been the thing that finally removed the friction we kept hitting.» They arrived at OpenSpec's memory model independently while working inside Spec Kit's architecture. This is not coincidence; it is convergent evolution toward the same structural insight. The parts of SDD that work are the durable artifacts. The parts that cause friction are the ones that reset.

Failure-mode catalogue: the top five

The full catalogue across both tools is 14 categories and 30+ documented issues assembled from GitHub issues, discussions, and practitioner posts. Five are worth naming explicitly because they are structural — not fixable by a new patch release, not addressable by changing configuration.

F1 — Constitution loss mid-execution (Spec Kit)

#2219. CRITICAL. Described above. Root cause: the spec-first model reads the governing document once at plan time. Long-running tasks exceed the context window. The architecture has no mechanism to re-inject the constitution when context turns over. The agent guesses.

OpenSpec's structural answer: durable spec on disk. Every agent step that needs the capability spec can read it fresh. No recall required. No loss.

B1 — Brownfield silent failure (Spec Kit)

#2506. CRITICAL. specify init fails silently on existing NX monorepos, leaving the developer with zero spec files and no error message after a branch switch. Real cost on adoption: 10–30 minutes of debugging before the issue is found. Still open May 2026.

A1 — 18.6K-token session tax (Spec Kit)

#1401. HIGH. Spec Kit loads approximately 18.6K tokens of commands, skills, and templates at the start of every session regardless of task scope. On a 20K-context IDE, 93% of available space is pre-consumed before work begins. The issue was opened, acknowledged, and remains open with no structural resolution — because the fix would require redesigning the artifact model.

J1 — Arbitrary shell execution in workflows (Spec Kit)

#2440. CRITICAL. Spec Kit workflows can contain arbitrary shell commands. When a workflow originates from a catalog, URL, or third-party source, there is no opt-in gate before execution. The attack surface covers supply-chain compromise, privilege escalation, and implicit execution of commands the developer never reviewed. Nine comments, a security-hardening proposal on record, open.

C1 — New spec breaks prior spec (Spec Kit)

#876. HIGH. After building a working agent UI feature under one spec, a second spec for a new feature silently broke the first feature's behavior. «I ended up struggling with vibe code» — the outcome SDD is supposed to prevent. Root cause: Spec Kit has no first-class capability concept. Features are defined in isolation; there is no cross-spec integrity check. Marked stale. Open.

Severity summary

Category	Spec Kit	OpenSpec
Token session tax	🔴 CRITICAL	🟢 minimal
Brownfield install	🔴 CRITICAL, structural	🟢 native delta-model
Cross-spec breakage	🔴 documented (#876)	🟡 manual workaround
Multi-repo	🔴 unsolved	🟡 paid SKU (Workspaces)
Agent integration regressions	🔴 systemic	🔴 systemic
Constitution drift	🔴 CRITICAL (#2219)	🟢 durable spec on disk
Implementation false-positive	🔴 documented	🟡 less data
Validation and parser bugs	🟡 less data	🔴 multiple open issues
Archive and lifecycle	n/a	🔴 path bugs, missing hooks
Security (shell injection)	🔴 CRITICAL (#2440)	🟡 not documented
Localization	🟡 community fork only	🟢 native (config.yaml)
Cost waste	🔴 documented 10× slower	🟡 less data

Spec Kit: 9 critical or high categories. OpenSpec: 4. The one category both share equally is agent-integration systemic instability: every new agent release breaks something in each tool. This is shared terrain, not a differentiator.

Empirical benchmark

Setup: macOS 14, Node 22.17.1, Python 3.9 (system). Test feature: «Add author field to lab posts with multi-author and i18n display» — a representative brownfield task touching database schema, API layer, and UI rendering. Both tools initialized from scratch in separate /tmp/sdd-benchmark/ directories on the same machine on the same day.

Setup time

	OpenSpec	Spec Kit
Cold install end-to-end	6.0s	20.5s
Ratio	1×	3.4×
Notable gotcha	none	PyPI `specify-cli` is not the official tool

Artifact floor

	OpenSpec	Spec Kit
Files on disk after init	9	27
Always-loaded tokens	~11,200	~25,800
Per-feature spec minimum	94 lines / 4.3 KB	247 lines / 10.9 KB

Cost per feature (Sonnet 4.6 input, floor)

	OpenSpec	Spec Kit
Per feature	$0.15	$0.36
Ratio	1×	2.4×
5-dev team, 100 features/month, annual	$900	$2,160
Real-world estimate (2–10× floor)	~$2,000–4,500	~$4,500–11,500

The benchmark cannot yet measure what requires a live Claude Code session with both tools running actual tasks: true token counts per agent run, wall-clock time to feature completion, and iteration count to a passing test suite. The floor-based numbers above are the minimum; published third-party measurements from Hashrocket and Scott Logic confirm the 2–10× multiplier is real on agent-generated artifacts.

Health metrics: the honest twist

The narrative that circulates in some corners of the SDD community — that Spec Kit is dying — is factually wrong as of May 2026.

Discussion #1482, which captured a quiet December–January period, is outdated. The May data says something entirely different:

Windows below are relative to the 2026-05-10 measurement date, not to today:

Dimension	Spec Kit	OpenSpec
Commits, last 4 weeks	159	28
Releases, last 30 days	17	2
PR merge median	23.3 hours	1.0 hour
Issue triage median	unclear — stale-bot dominated	3.3 days
Top contributor share	mnriem: 23%	TabishB: 58%
Top 3 contributors share	41%	69%

Spec Kit shipped 8.5× more releases and 5.7× more commits in the last 30 days. That is not stagnation by any measure.

But velocity is not the same as character. Looking at the 10 most-recent commits to each project:

Spec Kit: community catalog version updates, dependabot dependency bumps, release ceremonies, extension catalog churn. Ecosystem-maintenance mode. No core architectural work in the sample.

OpenSpec: TabishB shipping the Workspaces paid feature — multi-repo collaboration, the commercial SKU from the YC launch. Focused product work on the revenue vehicle. A deliberate pivot from open-core growth to commercialization.

OpenSpec's 1-hour PR merge median is founder self-merge: TabishB pushes his own PRs, not an analogue of community code review. Spec Kit's 23-hour median reflects distributed team review across multiple contributors.

Spec Kit's issue-close median is misleading in a different direction: all 30 most-recently closed issues in the sample carried a stale label — bulk mass-close by stale-bot. Real human-triage close time is not visible in this sample without filtering to -label:stale. OpenSpec's 3.3-day triage median uses diverse labels (bug, enhancement, P2-medium) — genuine human review.

The bus-factor disclosure that belongs in every honest comparison: TabishB writes 58% of recent OpenSpec commits. The next contributor is the automated release bot. If Tabish stops committing, the project stalls. This is the normal shape of a YC-stage startup — it is not evidence of project illness — but it is a real adoption risk that deserves disclosure. Spec Kit's top contributor writes 23%; the top five share 41%. Distributed by comparison.

Health ≠ velocity. Spec Kit's activity is real and accelerating, but it is catalog and dependency churn. OpenSpec's low commit count hides a strategic pivot, not decay. Both projects are alive and neither is dying. The structural failure modes documented above are not healed by velocity: a dependabot bump does not repair #2219; a catalog update does not fix brownfield silent failure.

Why not Tessl, Kiro, or BMAD

The landscape has four other credible tools. Each belongs in its own conversation, but each deserves a structural summary here so the comparison is honest about what it is not covering.

Tessl is the radical bet: code regenerates from the spec permanently. The spec is the maintained artifact; the code is the output. This is not a methodology choice — it is a philosophical commitment to AI-as-compiler. If that model is correct at scale and across complex domains, Tessl wins the long game. If AI code generation remains unreliable on domain-specific edge cases, Tessl users are trapped in a regeneration loop with no escape hatch. Smallest user base in 2026. Longest time horizon. Highest risk in both directions.

Kiro is AWS-native IDE-based SDD. The form factor lost significant ground in 2026 to CLI tools for a simple reason: IDE lock-in is a tax that founders and senior engineers consistently refuse to pay. An AWS-platform dependency and a pricing-bug incident compounded the distrust. The spec-first philosophy is shared with Spec Kit. Without the IDE lock-in, Spec Kit is the more portable choice within that philosophical category. Kiro makes sense for teams already fully committed to the AWS development platform and willing to accept the lock-in in exchange for native integration.

BMAD-Method (Be My Agile Developer) is the multi-agent variant of spec-anchored development. Where OpenSpec is a single-agent workflow, BMAD orchestrates a swarm: product owner agent, architect agent, developer agent, reviewer agent. The adversarial review pass — one agent critiquing another's output — is a genuine capability neither OpenSpec nor Spec Kit has. BMAD is the right choice when what you are buying is multi-agent coordination with adversarial review built in. It is overkill for an individual developer's iteration loop, and it introduces coordination overhead that raises costs substantially. The studio tracks BMAD as the likely path forward when team-scale agent orchestration matures.

Verdict

Three contexts, three answers:

Founder-stage / senior IC. Choose OpenSpec. The 3-phase workflow (propose → apply → archive) and delta-first memory model are built for the iteration-heavy, brownfield-heavy reality of real product work. Setup in 6 seconds. The $900/year model cost matters at startup scale. The failure modes in OpenSpec — parser bugs on markdown edge cases, archive path confusion, 58% bus factor — are present but manageable. The community is dense with signal: 46K stars represent people who actively chose OpenSpec after explicit comparison, not distributional pull. OpenSpec is a YC W26 product that speaks the founder dialect.

Enterprise / procurement-locked. Default answer today: Spec Kit. Microsoft has an official Learn module for it. GitHub Copilot is at 90% of Fortune 100; Spec Kit rides that distribution. The constitution-driven, 7-phase-gated workflow maps onto the PO / architect / developer / QA role separation typical of large teams. The critical structural bugs documented above (#2219, #2440, #2506) are known and navigable for teams with a dedicated tooling engineer. Worth noting: Thoughtworks Tech Radar rates SDD at Assess — not Trial, not Adopt — a caution signal for enterprise procurement decisions. Zero Fortune 500 case studies exist as of 2026; all published material remains principles, not production deployments.

Government / regulated. Neither tool natively satisfies the EU AI Act Article 9, 10, 12, 15 or 27 obligations that took full force on 2 August 2026 — a deadline that was ahead of us when this article was written and is now behind us. Spec Kit's constitution + clarify + analyze phases map marginally better to Articles 11, 12, and 14, but the gap between «spec-driven development» and a compliant AI system is a services engagement, not a CLI choice. The structural opportunity is methodology + tooling + service layer together. Neither CLI closes that gap alone; both are starting points for a compliance-track implementation, not the full answer.

The structural failure modes that neither OpenSpec nor Spec Kit closes — constitution drift, cross-spec breakage, broken implementation detected late, archive lifecycle fragility — are the methodology layer above the tool. The CLI is where that methodology starts, not where it ends.

Sources

Practitioner analysis

Authoritative references

GitHub issues and discussions cited

Spec Kit: #2219, #2440, #2506, #1401, #876, #337
Spec Kit discussions: #152, #331, #746, #1482
OpenSpec: #890, #911

Official

Проверено частично — у цифр указана дата замера