OpenSpec: A Lightweight Spec-Driven Development Framework for AI-Assisted Coding

---

AI coding assistants are powerful but unpredictable when requirements live only in chat history. You ask for a feature, the agent builds something, and six times out of ten it's close but not quite right — because the what and the why were never written down. OpenSpec solves this by adding a lightweight specification layer to your repository so humans and AI agree on what to build before any code is generated.

---

What Is OpenSpec?

OpenSpec is an open-source spec-driven development (SDD) framework created by Fission AI. It lives in your repository as an openspec/ directory containing structured Markdown files that describe how your system behaves and what changes you plan to make.

The core idea is simple: specs are the source of truth, changes are proposed modifications, and both live alongside your code.

---

The Four Principles

OpenSpec is built around four guiding principles:

The brownfield-first principle is what sets OpenSpec apart. Most spec frameworks assume you're starting from scratch. OpenSpec's delta-based approach makes it easy to specify changes to existing behavior, not just describe new systems.

---

How It Works: Specs and Changes

OpenSpec organizes your work into two main areas:

Specs (the source of truth)

Specs describe how your system currently behaves. They are organized by capability into folders under openspec/specs/. Each spec contains requirements, and each requirement has scenarios — concrete examples that make the behavior verifiable.

openspec/
  specs/
    auth/
      spec.md          # Requirements + scenarios for authentication
    billing/
      spec.md          # Requirements + scenarios for billing

A spec is a behavior contract, not an implementation plan. It says what the system does, not how it does it.

Changes (proposed modifications)

A change is a proposed modification packaged as a folder under openspec/changes/. It contains everything needed to understand and implement the change:

openspec/
  changes/
    add-oauth-login/
      proposal.md       # Why you're doing this
      specs/            # Delta specs — what's changing
      design.md         # Technical approach
      tasks.md          # Implementation checklist

This separation is key. You can work on multiple changes in parallel without conflicts. You can review a change before it affects the main specs. And when you archive a change, its deltas merge cleanly into the source of truth.

---

The Workflow: Propose → Apply → Archive

OpenSpec's workflow is intentionally minimal — often reduced to three steps:

1. Propose

You describe a change you want to make. OpenSpec generates everything needed to review it:

• A proposal document explaining the intent
• Spec deltas showing how requirements will change
• A design document with technical decisions
• A task list broken down into implementable steps

You review and refine the plan before any code is written, catching misalignment early.

2. Apply

Once the plan is approved, you (or your AI agent) implement the tasks. The specs serve as a reference throughout — the agent reads the spec to understand what to build, and you can check the work against the scenarios.

3. Archive

When the change is complete, you archive it. The delta specs merge into the main specs, keeping the source of truth up to date. The change folder is preserved for history.

---

Spec Deltas: The Secret Sauce

The most powerful concept in OpenSpec is the spec delta. Instead of rewriting an entire spec when a feature changes, you write a delta that captures only what's changing:

• Added — new requirements or scenarios
• Modified — changed behavior
• Removed — deprecated functionality

This makes reviews dramatically faster. A reviewer doesn't need to read the entire spec — they read the delta and immediately understand the impact. It also makes it easy to see how the system's requirements have evolved over time.

---

Stores: Cross-Repository Planning

For teams working across multiple repositories, OpenSpec introduces Stores — a dedicated planning repo that holds specs and changes shared across all your codebases.

my-openspec-store/
  openspec/
    specs/        # Shared specs owned by the platform team
    changes/      # Cross-repo changes

Stores solve three real problems:

1. Cross-repo features — one change, one plan, even when code lands in three repos.
2. Shared requirements — a platform team owns the specs; product teams reference them read-only.
3. Plan before code — capture the plan now; code repos catch up later.

The store uses the same openspec/ shape you already know, shared by git push like anything else. One source of truth your whole team and every coding agent can read.

---

The Explore Workflow

One of OpenSpec's standout capabilities is the explore workflow. Before modifying an existing system, you can ask OpenSpec to explore the codebase and generate specs that describe how it currently works.

This is genuinely useful for brownfield adoption:

1. Point OpenSpec at a feature area
2. It reads the code and produces a spec describing current behavior
3. You review and correct the spec
4. Now you have a baseline to write changes against

This turns "understanding the existing system" from a manual, error-prone process into a structured, reviewable artifact.

---

OpenSpec vs. Other SDD Tools

The spec-driven development landscape is growing. Here's how OpenSpec compares:

OpenSpec sits at the lowest-friction end of the spectrum. You can start using it immediately without learning elaborate processes or phase gates. The trade-off is less guardrailing — there's no executability mechanism, so specs are documentation artifacts, not verifiable contracts.

---

Getting Started

Install OpenSpec via npm:

npm install -g @fission-ai/openspec

Initialize in your repository:

openspec init

This creates the openspec/ directory structure. From there:

# Propose a change
openspec propose "Add OAuth login"

# Explore existing behavior
openspec explore src/auth

# Archive a completed change
openspec archive add-oauth-login

OpenSpec works with 20+ AI assistants, including Claude Code, Cursor, GitHub Copilot, and Devin. The specs are just Markdown — any tool that can read files can use them.

---

When Should You Use OpenSpec?

OpenSpec shines when:

• You're working on an existing codebase and need to understand current behavior before changing it.
• You're using AI coding agents and want to reduce unpredictability.
• Your team spans multiple repos and needs shared requirements.
• You want lightweight structure without adopting a heavyweight process.

It may not be the right fit when:

• You need executable specs (look at tools with test generation).
• Your team requires strict phase gates and approval workflows.

---

Conclusion

OpenSpec fills a real gap in the AI-assisted development landscape. As coding agents grow more powerful, the bottleneck shifts from writing code to agreeing on what to build. OpenSpec addresses this with a lightweight, brownfield-first approach that adds just enough structure to keep humans and AI aligned — without getting in the way.

The philosophy is refreshing: fluid not rigid, iterative not waterfall, easy not complex. If you've ever been burned by an AI agent building the wrong thing because the requirements lived only in a chat session, OpenSpec is worth a look.

---

Links:

• OpenSpec GitHub
• OpenSpec Website
• Thoughtworks Technology Radar — OpenSpec