OpenSpec vs Spec Kit: Choosing a Spec-Driven Framework for AI-Agent Development

AI coding agents write code faster than any human. The bottleneck has shifted: the spec is now the product. If your agent doesn’t have a clear, structured specification to work from, it hallucinates architecture, invents requirements, and produces code that passes tests nobody asked for.

Two frameworks have emerged to solve this: OpenSpec (~28k GitHub stars) and GitHub’s Spec Kit (~75k stars). Both are MIT-licensed. Both generate slash commands that AI agents consume directly. But they make fundamentally different trade-offs between speed and governance — and picking the wrong one costs your team weeks of rework.

Here’s how to choose.

The Core Split: Fluid Iteration vs. Structured Governance

OpenSpec is a Node.js CLI (@fission-ai/openspec) that treats specs as lightweight, repo-native artifacts. It organizes work into change folders containing proposal, specs, design, and task files. The philosophy is minimal ceremony — get a spec in front of the agent fast, iterate, archive when done.

Spec Kit (GitHub’s framework, centered on the specify CLI and /speckit.* commands) anchors everything to a constitution — a project-level document that encodes constraints, coding standards, TDD requirements, and compliance rules. Every feature flows through a structured phase pipeline with templates and checklists at each gate.

The difference isn’t cosmetic. It determines how much overhead your team absorbs per feature, how much context your agents consume per prompt, and whether your audit trail satisfies compliance reviewers.

Workflow Comparison

OpenSpec: Four Commands, Minimal Friction

OpenSpec’s workflow is intentionally short:

graph LR
    A["/opsx:propose"] --> B["/opsx:explore"]
    B --> C["/opsx:apply"]
    C --> D["/opsx:archive"]

1. /opsx:propose — Create a change folder with a proposal document
2. /opsx:explore — Iterate on specs and design within that folder
3. /opsx:apply — Execute the implementation based on finalized specs
4. /opsx:archive — Move completed work to the archive

That’s it. No constitution. No mandatory clarification phase. No task-breakdown gate. You propose, explore, apply, archive. If you need to loop back from apply to explore, you just do it — there’s no phase-gate enforcement stopping you.

OpenSpec enforces a 50KB context limit to prevent prompt bloat. This is a deliberate design choice: agents working with OpenSpec specs won’t choke on oversized context windows, which matters when you’re running multiple agents across a monorepo.

Spec Kit: Six Phases, Constitution-Anchored

Spec Kit’s pipeline is more extensive:

graph LR
    A["/speckit.constitution"] --> B["/speckit.specify"]
    B --> C["/speckit.clarify"]
    C --> D["/speckit.plan"]
    D --> E["/speckit.tasks"]
    E --> F["/speckit.implement"]
    G["/speckit.analyze"] -.-> B

1. /speckit.constitution — Define project-wide rules, constraints, and standards
2. /speckit.specify — Create a detailed feature specification
3. /speckit.clarify — Resolve ambiguities and open questions
4. /speckit.plan — Generate an implementation plan
5. /speckit.tasks — Break the plan into discrete, assignable tasks
6. /speckit.implement — Execute tasks with TDD gates and checklist validation
7. /speckit.analyze (optional) — Analyze existing code before specifying changes

The constitution is the key differentiator. It’s a living document that every subsequent command respects. If your constitution says “all database changes require migration scripts” or “no direct API calls without retry logic,” the agent enforces those rules at every phase. For regulated industries — healthcare, finance, government — this is exactly the mechanism you need to encode compliance requirements into the development workflow itself.

Head-to-Head Comparison

The Context Tax Problem

Spec Kit’s power comes with a cost. Every installed slash command, every template, every constitution rule adds tokens to the agent’s context window. Teams running Spec Kit with multiple extensions report significant context tax — the agent spends tokens parsing framework instructions instead of reasoning about your code.

This matters at scale. If you’re running Claude Code or Codex against a large codebase with Spec Kit’s full command set loaded, you’re burning context on framework overhead. Some teams have reported needing to prune extensions or split constitutions to stay within practical token budgets.

OpenSpec sidesteps this with its 50KB context limit. It’s a blunt instrument — you can’t encode the same depth of governance — but it keeps agents focused on the actual specification rather than framework metadata.

Enterprise takeaway: If your agents are already context-constrained (large codebases, complex system prompts, multi-file changes), measure the token cost of Spec Kit’s command set before committing. OpenSpec’s ceiling is lower but predictable.

When to Use OpenSpec

Choose OpenSpec when:

• You’re doing rapid prototyping or proof-of-concept work where speed matters more than process
• Your team uses multiple AI agent tools and wants a single, lightweight spec layer that works across all of them
• You need to iterate mid-flight — changing specs after implementation has started without fighting phase gates
• Your codebase is large enough that context budget is a real constraint
• You want spec-driven development without adopting a full governance framework

OpenSpec’s “core” profile is the lowest-friction entry point to spec-driven AI development. Install the CLI, create a change folder, and your agent has structured specs to work from. No constitution to write, no extension catalog to curate.

When to Use Spec Kit

Choose Spec Kit when:

• You’re building production systems where governance and repeatability justify the overhead
• Your organization operates in a regulated domain (healthcare, finance, government) and needs compliance rules encoded into the development workflow
• You want TDD enforcement baked into the framework, not bolted on after the fact
• Your team benefits from structured phase gates — clarification before planning, planning before implementation
• You need extensibility via hooks and curated extension catalogs for organization-specific workflows

Spec Kit’s constitution model is genuinely powerful for enterprise contexts. Encoding “every API endpoint requires OpenAPI documentation” or “all state mutations require event sourcing” as constitutional rules means the agent enforces them automatically, every time. That’s not governance theater — it’s governance that actually executes.

Hybrid Approach: Start Light, Add Structure

These frameworks aren’t mutually exclusive in philosophy. A practical path for many enterprise teams:

1. Start with OpenSpec for initial exploration and prototyping. Get the spec habit established without the overhead.
2. Move to Spec Kit when the project graduates to production and needs governance, compliance encoding, and repeatable phase workflows.
3. Keep OpenSpec for side projects, internal tools, and rapid experiments where Spec Kit’s ceremony would slow you down.

The worst outcome is no spec framework at all — agents working from vague prompts, producing code that nobody reviewed against requirements that nobody wrote down.

Actionable Takeaways

1. Spec-driven development is no longer optional. If your AI agents don’t have structured specs, you’re debugging hallucinated requirements. Pick a framework.

2. Measure your context budget first. Run your agent with Spec Kit’s full command set loaded and check how many tokens go to framework overhead. If it’s more than 15-20% of your context window, consider OpenSpec or a trimmed Spec Kit configuration.

3. For regulated industries, Spec Kit’s constitution pays for itself. Encoding compliance rules that agents enforce automatically is worth the extra artifact overhead. The alternative is manual review of every agent-generated change for regulatory compliance.

4. For rapid prototyping, OpenSpec wins on speed. Four commands, 50KB context limit, no constitution to maintain. Get specs in front of agents fast.

5. Don’t skip the archive/cleanup step. Both frameworks support archiving completed work. Stale specs in your repo confuse agents on future runs. Archive aggressively.

6. Evaluate both against your actual stack. Clone each framework’s example repo, run it against your codebase with your preferred AI agent, and compare the output quality and token costs. The right choice depends on your team’s governance needs, not GitHub star counts.