Stop Vibe-Coding Into the Void: How OpenSpec Brings Discipline to AI-Driven Development

You've felt it. You've opened a chat with Claude Code or Cursor, described what you want, watched it generate 300 lines of plausible code — and then three sessions later, none of the AI assistants have any idea what you were originally trying to build. The requirements are scattered across chat logs. The decisions are in your head. The code is in the repo. And none of those three things agree with each other.

That's the actual problem OpenSpec is trying to fix.

What Even Is OpenSpec?

OpenSpec is a spec-driven development (SDD) framework from Fission-AI. It's not an API description format like OpenAPI (different thing entirely — I've seen people confuse the two). It's not a test framework, not a linter, not a code generator in the traditional sense. It's a workflow layer that lives in your repository alongside your code and forces you — and your AI assistant — to agree on what you're building before any code gets written.

The core idea is simple: specs live in your repo as Markdown files. When you want to make a change, you don't just start coding or prompting. You create a structured proposal. The AI helps you think through requirements, design decisions, and tasks. Then — and only then — does implementation begin.

Version control for intent, not just for code.

The Problem It's Actually Solving

There's a failure mode that's become embarrassingly common with AI-assisted development. You describe a feature informally in a chat window. The AI implements something that more-or-less matches your description. You iterate a few times. Three days later, you need to change the behavior — but the AI has no memory, the original requirements are buried in a dead conversation, and you've lost the reasoning behind every architectural choice.

OpenSpec calls this "vibe coding." I'd call it technically bankrupt, but sure, vibe coding.

The deeper issue is the LLM context window problem. Once a chat session exceeds roughly 40% of the model's context capacity, performance degrades noticeably — requirements get forgotten, earlier constraints get violated, and the AI starts hallucinating coherence where there isn't any. Specs stored in the filesystem sidestep this entirely. You load what you need, when you need it, and the AI always has stable ground to stand on.

How It Works

OpenSpec organizes your repository around two directories:

specs/ — The source of truth. Documents what the system currently does, written in structured Markdown with Gherkin-style scenarios.
changes/ — Isolated proposal workspaces. One folder per feature or change. Think Git branches, but for intent.

A change folder contains four artifacts:

proposal.md — What you want to build and why
design.md — Technical approach and architectural decisions
tasks.md — Concrete implementation checklist
specs/ — Delta specs showing only what's changing (ADDED / MODIFIED / REMOVED sections)

The workflow is three commands:

/opsx:propose  — Generates the full change folder: proposal, design, tasks, spec deltas
/opsx:apply    — Works through the task checklist and implements the code
/opsx:archive  — Merges spec deltas back into main specs and moves the change to archive

The delta spec format is worth calling out specifically, because it's clever. Instead of rewriting entire spec files every time something changes, you only describe what changed. This keeps diffs readable, reduces merge conflicts, and — critically — makes code review actually useful. Reviewers can see requirement changes alongside code changes, which is something that almost never happens in normal development.

Here's what a spec requirement looks like:

### Requirement: Session expiration
The system SHALL expire sessions after configured duration.

#### Scenario: Default timeout
- GIVEN a user has authenticated
- WHEN 24 hours pass without activity
- THEN invalidate the session token

RFC 2119 keywords (SHALL, MUST, SHOULD, MAY) make the intent unambiguous. The Gherkin-style scenarios give the AI enough structure to generate meaningful tests and validate behavior.

Brownfield First — This Matters

Most spec-driven tools are designed for greenfield development. Start fresh, define everything up front, generate code from specs. It's a clean model for a clean world that doesn't exist.

OpenSpec is explicitly brownfield-first. It has a "retrofitting" mode where you reverse-engineer existing code into a baseline set of specs. You point it at your existing codebase, and it generates a starting point you can refine. It's not magic — you'll still need to review and fill gaps — but it means you can adopt this on a three-year-old monolith, not just on a new side project.

This alone separates it from most competitors in the SDD space.

OpenSpec vs. the Alternatives

The closest competitors right now are SpecKit and Kiro (Amazon's IDE-integrated SDD tool).

SpecKit is stronger for 0-to-1 greenfield development — it has more scaffolding and opinionated project setup. OpenSpec is lighter and more flexible for iterating on existing systems. If you're building a new app from scratch, SpecKit might fit better. If you're maintaining a mature codebase with an AI assistant helping you extend it, OpenSpec is the better default.

Kiro is interesting but requires buy-in to specific IDEs and Amazon's SaaS infrastructure. OpenSpec is pure filesystem + Markdown — it works with Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, and 20+ other tools. No API keys required beyond whatever you're already using. No lock-in.

I genuinely don't understand why anyone builds spec tooling that requires a specific IDE. That's exactly the kind of dependency that kills adoption in heterogeneous teams.

Getting Started

Install via npm (requires Node.js 20.19.0+):

npm install -g @fission-ai/openspec

For Claude Code, it installs as a slash command skill. You can also pull it from the GitHub repo directly at github.com/Fission-AI/OpenSpec if you want to inspect what you're running.

The recommended bootstrap for an existing project:

Run /opsx:propose on a small, well-understood feature first — don't start with your most complex domain
Let OpenSpec generate the change folder and review each artifact before running /opsx:apply
After your first archived change, you'll have enough context to understand what baseline specs/ entries to write for your existing system

The openspec validate command can be added to CI/CD to catch malformed specs before implementation. That's worth doing early.

Honest Take on Maturity

It's v1.3 as of mid-2026. Active maintenance, regular releases, 52k GitHub stars — that's real traction, not just hype. But it's still emerging infrastructure.

Real-world usage shows that for straightforward features, the AI-generated proposals are 80-85% there. For complex domains — multi-tenant authentication, conditional response shapes, middleware-based authorization — the generated specs are often too generic to be useful and need significant manual work. The tool is a strong first pass, not a complete replacement for thinking.

The state machine discipline also has a learning curve. Developers who are used to just opening a chat and saying "add pagination to this endpoint" will initially resist the structure. That friction is partly the point — but it means adoption on a team requires actual buy-in, not just one person installing an npm package.

No hallucination prevention, either. OpenSpec reduces the surface area for AI mistakes by giving it stable context, but the AI can still produce nonsense specs that look plausible. Human review before /opsx:apply is not optional.

Should You Adopt It Now?

If you're working solo or in a small team with heavy AI assistant usage — yes, try it. The overhead is low, the payoff for context persistence is real, and brownfield support means you can start on your actual codebase.

If you're on a larger team, the case is stronger but the adoption path is harder. Spec files need to be treated as first-class artifacts, code reviews need to include spec deltas, and everyone needs to internalize the workflow. That's a process change, not just a tool change.

If you're building greenfield and want maximum scaffolding, look at SpecKit first. If you're locked into a specific IDE ecosystem, Kiro might integrate more smoothly.

But the underlying idea — that requirements should live in your repo, be versioned, be readable by both humans and AI, and be explicitly reviewed before implementation — that idea is right. The "vibe coding" era produces unmaintainable systems almost by design. OpenSpec is one of the more practical answers to that problem that exists today.

The tool will keep evolving. The workflow concept won't go away.

OpenSpec GitHub: github.com/Fission-AI/OpenSpec

Official site: openspec.dev