OpenSpec: write the spec first, let AI code after — lightweight spec-driven development

Tell a coding agent “build Google sign-in” and it will — the way it understands the task. The gap between your intent and the agent’s often only shows up when you read a several-thousand-line diff. Spec-driven development (SDD) flips the order: humans and AI agree on what to build in a short spec first, and only then write code. Fission AI’s OpenSpec is a lightweight SDD framework that runs inside the tools you already use.

What is OpenSpec?

OpenSpec adds a light spec layer to your repo so you and the agent read from the same source of truth. It’s MIT licensed and works with 30+ AI assistants — Claude Code, Cursor, GitHub Copilot, Codex and more — without its own API key. The README’s philosophy:

• Fluid, not rigid; iterative, not waterfall.
• Easy, not complex.
• Built for existing (brownfield) codebases, not just new ones.
• Scales from personal projects to enterprises.

Installation

# Node.js 20.19.0 or later
npm install -g @fission-ai/openspec@latest
# or: brew install openspec

cd your-project
openspec init      # pick your AI tools; generates commands and agent instructions
openspec update    # refresh instructions and slash commands after upgrading

Folder structure

openspec/
├── specs/                      # the system's current specs
└── changes/
    ├── add-google-login/       # one folder per change
    │   ├── proposal.md         # why, and what changes
    │   ├── specs/              # requirements + scenarios (WHEN/THEN)
    │   ├── design.md           # technical approach
    │   └── tasks.md            # implementation checklist
    └── archive/                # completed changes, dated

Specs are plain Markdown, with requirements written as verifiable scenarios, for example:

## ADDED Requirements
### Requirement: Google sign-in
Users can sign in with their Google account.

#### Scenario: First sign-in
- WHEN the user chooses "Continue with Google" and grants access
- THEN the system creates a new account and shows the welcome page

The lifecycle of a change

Syntax varies by tool: /opsx:propose is canonical, Cursor and Copilot use /opsx-propose, Codex uses $openspec-propose. The expanded profile (via openspec config profile) adds /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive and /opsx:onboard.

Compared with the alternatives

This comparison comes from OpenSpec itself — the best test is to try two of them on a small feature and pick.

Tips for using it well

• Clear context before applying: the README advises clearing context after planning so the agent focuses on the spec rather than the earlier discussion.
• Use a strong model for proposing — mistakes in the spec multiply in the code.
• Stores (beta): keep planning in a shared repo that several repos reference — useful for cross-service features.
• Telemetry: only command names and versions, disabled automatically in CI; turn it off with openspec config set telemetry.enabled false or DO_NOT_TRACK=1.

Why PMs should care

• proposal.md plus WHEN/THEN scenarios is a “ticket with acceptance criteria” that agents can read and you can review.
• Reviewing a few hundred lines of spec is much faster than reviewing thousands of lines of diff — and mistakes surface earlier.
• Specs live in the repo next to the code → less tribal knowledge; newcomers read openspec/specs to understand what the system does.

How to apply it

• Developers: Take your next small feature, run /opsx:propose, fix the spec until it matches your intent, then /opsx:apply. Compare the number of correction rounds with your usual approach.
• Tech Leads: Add a “proposal review” step — large changes without a matching change spec don’t get merged.
• PMs: Write the “why” and the WHEN/THEN scenarios in the proposal with the team. It’s the best place for PM input before tokens and effort go into code.