OpenSpec vs Spec Kit: Choosing a Spec-Driven Development Framework

Disclaimer. This comparison was made in December of 2025 based on the latest versions of both frameworks. Both projects are actively evolving, so some details may change over time.

The rise of AI coding assistants has introduced a new problem: "vibe coding." You describe what you want, the LLM generates code, and you ship it—until the project grows and you realize nobody understands how it works anymore. The intent behind architectural decisions lives in transient chat logs, not documentation.

Spec-Driven Development (SDD) addresses this by treating specifications as the primary artifact. The spec exists before the code, and the code is generated from it. Two frameworks have emerged as the dominant approaches: GitHub Spec Kit and OpenSpec.

The Problem with Vibe Coding

Vibe coding—a term coined by Andrej Karpathy—describes development where you focus entirely on outcomes and let the AI handle implementation details. This works for prototypes but fails in production for several reasons:

• Context drift: As chat sessions lengthen, the model's understanding of constraints degrades
• Intent opacity: The "why" behind decisions is lost in chat history
• Architectural inconsistency: The same problem solved three different ways across the codebase
• Debugging difficulty: You can't fix code you don't understand

SDD flips this: write the specification first, then generate code from it. If the implementation is wrong, you fix the spec and regenerate—ensuring documentation and code never diverge.

GitHub Spec Kit

Spec Kit is GitHub's open-source toolkit for structured spec-driven development. It represents a "Constitutional" approach—rigorous governance through explicit rules and gated phases.

The Constitution

Spec Kit's defining feature is the constitution.md file (.specify/memory/constitution.md). This document defines non-negotiable engineering principles that constrain the AI throughout the project:

## Architectural Mandates
- Every feature must be implemented as a standalone library
- All state management must use Redux Toolkit
- No implementation code until unit tests are defined

## Quality Gates
- Test coverage must not fall below 85%
- All public API methods must include JSDoc comments

The AI cannot proceed without validating against these rules, preventing architectural drift across developers and sessions.

Four-Phase Workflow

Spec Kit enforces a linear workflow where each phase produces artifacts that must be reviewed before proceeding:

The Specify phase explicitly forbids technical details if you try to specify "Use a React useEffect hook," the framework pushes back, asking for the desired user behavior instead.

Installation

uvx --from git+https://github.com/github/spec-kit.git specify init

Spec Kit uses Python and the uv package manager, creating a .specify directory with prompt templates and scripts.

OpenSpec

OpenSpec is Fission AI's community-driven alternative. It represents a "Transactional" approach lightweight, token-efficient, and optimized for iterative changes to existing systems.

The Delta Model

OpenSpec rejects monolithic document regeneration. Instead of rewriting the entire specification for every change, it uses "Change Proposals" with explicit deltas:

openspec/
├── specs/           # Permanent source of truth
├── changes/         # Active proposals (staging area)
│   └── add-dark-mode/
│       ├── proposal.md
│       ├── tasks.md
│       └── specs/   # Delta files only
└── archive/         # Completed changes (audit trail)

Delta files use headers like ## ADDED Requirements, ## MODIFIED Requirements, and ## REMOVED Requirements to describe only what changed not the full specification.

Three-Step Workflow

OpenSpec streamlines the process into conversational commands:

The Archive step is critical: it merges the delta back into openspec/specs/, keeping the canonical documentation current as the codebase evolves.

Installation

npm install -g @fission-ai/openspec
openspec init

OpenSpec scaffolds an AGENTS.md file in the project root human-readable instructions for any AI agent on how to use the OpenSpec structure.

Head-to-Head Comparison

Greenfield vs Brownfield

The most significant differentiator is project lifecycle stage.

Spec Kit excels at Greenfield (0→1). When building from scratch, the volume of decisions is immense. Spec Kit's rigid workflow forces the AI to generate database schemas, API contracts, and component hierarchies before writing code. It acts as a "Senior Architect in a Box."

OpenSpec excels at Brownfield (1→n). In a mature 50,000-line codebase, regenerating a full technical plan for a "Delete" button is overkill. OpenSpec treats the existing code as an immutable baseline and focuses on the incremental change surgical precision for day-to-day feature work.

Token Economics

In LLM workflows, tokens equal cost and latency.

Spec Kit is context-heavy. A single plan.md can run hundreds of lines. When fed back to the LLM for implementation, this consumes significant context window space, increasing API costs and inference time.

OpenSpec is context-light. Delta specs are minimal diffs. The AGENTS.md instruction file is concise. This makes OpenSpec cheaper to run and faster to interact with smaller input prompts mean faster time-to-first-token.

When to Use Which

Choose Spec Kit if:

• Starting a new, complex project from scratch
• Working with a large team (5+ developers) requiring consistent standards
• Your team is comfortable with Python tooling
• You're integrated into the GitHub Enterprise ecosystem
• Architectural safety is more important than speed

Choose OpenSpec if:

• Maintaining or extending an existing codebase
• Working as a solo developer or small team
• Your stack is JavaScript/TypeScript
• You value speed and token efficiency
• You want minimal workflow overhead

Criticism

A recurring critique of Spec Kit is that for simple features, the workflow feels bureaucratic. Spending 20 minutes refining a constitution.md and generating a 10-page plan.md to add a modal window is counter-productive.

However, developers who've struggled with AI agents destroying codebases through unstructured vibe coding find relief in Spec Kit's constraints. The rigidity is a feature, not a bug—for the right use cases.

OpenSpec is frequently cited as hitting a "sweet spot" between chaos and bureaucracy—structure without bloat. The tradeoff: it requires discipline. If you forget to archive changes, your specs/ directory becomes stale.

Outlook (my personal beliefs without any source except 'it occured to me in a dream')

Both frameworks operate at "Level 2 SDD"—spec and code are separate artifacts kept in sync. The trajectory is "Level 3 SDD" where the specification becomes the only artifact humans touch.

In this future, code is treated like a compiled binary—an intermediate representation generated by AI and never edited by hand. Spec Kit's increasingly detailed plan.md and OpenSpec's change-as-fundamental-unit both position for this evolution.

The skill shift for developers is clear: from writing syntax to articulating intent, governing context, and reviewing architectural proposals.

References

• GitHub Spec Kit Repository
• OpenSpec Repository
• GitHub Blog: Spec-Driven Development with AI
• Hashrocket: OpenSpec vs Spec Kit
• LogRocket: Exploring Spec-Driven Development with GitHub Spec Kit