OpenSpec: The Spec-Driven Development Revolution
In the age of AI-assisted coding, one problem keeps surfacing: AI doesn’t follow instructions. OpenSpec changes that by introducing spec-driven development—a disciplined workflow where specifications are written before code is generated.
What is OpenSpec?
OpenSpec is a free, open-source CLI tool that brings Spec-Driven Development (SDD) to AI coding assistants like Cursor, Claude Code, Cline, Kilo Code, and Codex. It ensures AI agents strictly follow your requirements by generating detailed markdown specification documents before any code is written.
Think of OpenSpec as the blueprint phase for software construction. Just as architects don’t start pouring concrete without plans, developers shouldn’t ask AI to code without specs.
The Problem OpenSpec Solves
Without OpenSpec, AI coding sessions typically look like this:
Developer: "Add user authentication"
AI: *generates some code*
Developer: "Hmm, also add password reset"
AI: *generates more code*
Developer: "Wait, login is broken now"
AI: *patches things*
Developer: "We need OAuth too..."
AI: *adds OAuth, breaks something else*
Result: Spaghetti code, inconsistent patterns, hidden bugs
OpenSpec replaces this chaos with a structured, auditable workflow.
The OpenSpec Pipeline
Here’s the complete OpenSpec pipeline visualized:
┌─────────────────────────────────────────────────────────────────────┐
│ OPENSPEC PIPELINE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ INIT │────▶│ PROPOSAL │────▶│ APPLY │────▶│ ARCHIVE │ │
│ │ │ │ │ │ │ │ │ │
│ │ Setup │ │ Draft │ │ Execute │ │ Finalize │ │
│ │ Project │ │ Spec │ │ Tasks │ │ & Update │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ project.md proposal.md tasks.md archive/ │
│ specs/ tasks.md code changes updated specs │
│ design.md validated cleaned up │
│ │
└─────────────────────────────────────────────────────────────────────┘
Step-by-Step Breakdown
Step 1: INIT — Initialize the Specification
┌──────────────────────────────────────────────┐
│ INIT PHASE │
├──────────────────────────────────────────────┤
│ │
│ $ openspec init │
│ │
│ Creates: │
│ ┌─ openspec/ │
│ │ ├── project.md ← Project context │
│ │ ├── specs/ ← Current capabilities│
│ │ └── changes/ ← Active proposals │
│ │ │
│ project.md defines: │
│ • Tech stack & conventions │
│ • Code style & patterns │
│ • Testing strategy │
│ • Architectural constraints │
│ │
└──────────────────────────────────────────────┘
The init command sets up your project’s source of truth. This file tells AI assistants how your project is structured and what rules they must follow.
Step 2: PROPOSAL — Draft the Specification
┌──────────────────────────────────────────────────────┐
│ PROPOSAL PHASE │
├──────────────────────────────────────────────────────┤
│ │
│ $ openspec propose add-user-auth │
│ │
│ Generates: │
│ ┌─ changes/add-user-auth/ │
│ │ ├── proposal.md ← Why & what │
│ │ ├── tasks.md ← Step-by-step checklist │
│ │ ├── design.md ← Technical decisions │
│ │ └── specs/ │
│ │ └── user-auth/ │
│ │ └── spec.md ← Requirement deltas │
│ │ │
│ Validate: │
│ $ openspec validate add-user-auth --strict │
│ │
│ Spec delta format: │
│ ## ADDED Requirements │
│ ### Requirement: User Login │
│ The system SHALL authenticate users via email │
│ #### Scenario: Valid credentials │
│ WHEN user provides valid email and password │
│ THEN system grants access and creates session │
│ │
└──────────────────────────────────────────────────────┘
This is where you define the change before any code is written. Every requirement uses normative language (SHALL/MUST) and includes testable Scenario blocks.
Step 3: APPLY — Execute the Specification
┌──────────────────────────────────────────────────────┐
│ APPLY PHASE │
├──────────────────────────────────────────────────────┤
│ │
│ AI Assistant reads the proposal and: │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ tasks.md Checklist: │ │
│ │ │ │
│ │ ☐ Create User model with email/password │ │
│ │ ☐ Implement JWT token generation │ │
│ │ ☐ Add login endpoint POST /api/auth/login │ │
│ │ ☐ Write unit tests for auth service │ │
│ │ ☐ Add integration tests for login flow │ │
│ │ ☐ Update API documentation │ │
│ │ │ │
│ └────────────────────────────────────────────┘ │
│ │
│ AI follows spec EXACTLY: │
│ • Implements each task in order │
│ • Matches defined scenarios │
│ • Respects project conventions │
│ • No hallucination, no deviation │
│ │
│ Progress tracked: │
│ $ openspec show add-user-auth │
│ │
└──────────────────────────────────────────────────────┘
During Apply, the AI coding assistant executes tasks sequentially, checking them off as completed. The spec acts as guardrails—preventing scope creep and ensuring consistency.
Step 4: ARCHIVE — Finalize and Update
┌──────────────────────────────────────────────────────┐
│ ARCHIVE PHASE │
├──────────────────────────────────────────────────────┤
│ │
│ After deployment & verification: │
│ │
│ $ openspec archive add-user-auth --yes │
│ │
│ What happens: │
│ ┌────────────────────────────────────────────┐ │
│ │ 1. changes/add-user-auth/ → archive/ │ │
│ │ 2. specs/ updated with new capabilities │ │
│ │ 3. project state synchronized │ │
│ │ 4. Spec deltas merged into main specs │ │
│ └────────────────────────────────────────────┘ │
│ │
│ Result: │
│ ┌─ openspec/ │
│ │ ├── project.md │
│ │ ├── specs/ │
│ │ │ └── user-auth/ ← NEW capability added │
│ │ │ ├── spec.md │
│ │ │ └── design.md │
│ │ ├── changes/ ← Empty, ready for next │
│ │ └── archive/ │
│ │ └── add-user-auth/ ← Historical record │
│ │ │
│ System truth is now UP TO DATE │
│ │
└──────────────────────────────────────────────────────┘
Archive is the cleanup and synchronization step. Completed changes are moved to history, and the main specification files are updated to reflect the new system state.
Complete Workflow Visualization
┌─────────────────┐
│ DEVELOPER │
│ defines need │
└────────┬────────┘
│
▼
┌─────────────────────────┐
│ 1. INIT │
│ openspec init │
│ Setup project.md │
└────────────┬────────────┘
│
▼
┌─────────────────────────┐
│ 2. PROPOSE │
│ openspec propose │
│ Create spec delta │
│ define requirements │
│ write scenarios │
└────────────┬────────────┘
│
▼
┌─────────────────────────┐
│ VALIDATE │
│ openspec validate │
│ --strict │◀──┐
└────────────┬────────────┘ │
│ │
✓ pass? │
│ │
┌─────┴──────┐ │
│ │ │
YES NO │
│ │ │
▼ └─────────────┘
┌─────────────────────────┐
│ 3. APPLY │
│ AI reads spec │
│ Executes tasks.md │
│ line by line │
└────────────┬────────────┘
│
▼
┌─────────────────────────┐
│ TEST & VERIFY │
│ Run tests │
│ Deploy & verify │
└────────────┬────────────┘
│
▼
┌─────────────────────────┐
│ 4. ARCHIVE │
│ openspec archive │
│ Update specs │
│ Move to archive/ │
└────────────┬────────────┘
│
▼
┌─────────────────────────┐
│ SYSTEM TRUTH │
│ Updated & current │
│ Ready for next change │
└─────────────────────────┘
Directory Structure
OpenSpec maintains a clean, version-controllable structure:
openspec/
├── project.md # Project context, conventions, constraints
├── specs/ # Current system capabilities ("source of truth")
│ └── user-auth/
│ ├── spec.md # Requirements with scenarios
│ └── design.md # Technical decisions
├── changes/ # Active proposals
│ └── add-user-auth/
│ ├── proposal.md # Why this change is needed
│ ├── tasks.md # Implementation checklist
│ ├── design.md # Technical approach
│ └── specs/
│ └── user-auth/
│ └── spec.md # Delta: ADDED/MODIFIED/REMOVED requirements
└── archive/ # Completed changes (historical record)
└── add-user-auth/ # Preserved for audit & reference
Key Commands at a Glance
┌─────────────────────────────────────────────────────────────┐
│ OPEN-SPEC CHEAT SHEET │
├─────────────────────────────────────────────────────────────┤
│ │
│ Initialize $ openspec init │
│ Update spec $ openspec update │
│ List changes $ openspec list │
│ List specs $ openspec list --specs │
│ Show item $ openspec show [change-id] │
│ Diff changes $ openspec diff [change-id] │
│ Validate strict $ openspec validate [id] --strict │
│ Archive completed $ openspec archive [id] --yes │
│ │
│ Change ID format: kebab-case, verb-led │
│ Examples: add-japanese-localization │
│ update-auth-middleware │
│ remove-legacy-api │
│ │
└─────────────────────────────────────────────────────────────┘
Spec Delta Syntax
OpenSpec uses a precise format for defining changes:
## ADDED Requirements
### Requirement: User Registration
The system SHALL allow users to register with email and password.
#### Scenario: Successful registration
WHEN user submits valid registration form
AND email is not already registered
AND password meets complexity requirements
THEN system creates new user account
AND system sends verification email
AND system returns success response
#### Scenario: Duplicate email
WHEN user submits registration form
AND email is already registered
THEN system returns error "Email already in use"
AND no new account is created
## MODIFIED Requirements
### Requirement: Password Policy
[REQUIREMENT] The system SHALL enforce minimum password complexity.
- Password MUST be at least 12 characters
- Password MUST contain uppercase and lowercase letters
- Password MUST contain at least one number
- Password MUST contain at least one special character
## REMOVED Requirements
### Requirement: Legacy Token Format
The system SHALL NO LONGER support JWT tokens with HS256 algorithm.
[REMOVED] All tokens MUST use RS256 algorithm instead
When to Use (and Skip) OpenSpec
┌─────────────────────────────────────────────┐
│ WHEN TO USE OPENSPEC │
├─────────────────────────────────────────────┤
│ │
│ ✓ New features (0 → 1) │
│ ✓ Major refactoring (1 → n) │
│ ✓ Architectural changes │
│ ✓ Multi-step implementations │
│ ✓ Team collaboration & code review │
│ ✓ Compliance & audit requirements │
│ │
│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │
│ │
│ ✗ Simple bug fixes │
│ ✗ Typos and formatting │
│ ✗ Non-breaking config changes │
│ ✗ One-line patches │
│ │
└─────────────────────────────────────────────┘
Why OpenSpec Works
- Single Source of Truth:
project.mdandspecs/define exactly what exists and how it works - AI-Readable Format: Markdown specs are designed for AI assistants to parse and follow
- Strict Validation:
openspec validate --strictcatches missing scenarios and formatting errors - Audit Trail: Every change is documented, validated, and archived
- No Context Rot: AI always reads the current state—no assumptions, no hallucination
Conclusion
OpenSpec represents a paradigm shift from vibe coding to spec-driven development. By requiring specifications before implementation, it ensures AI-generated code is consistent, auditable, and aligned with your project’s architecture.
The pipeline is simple: Init → Propose → Validate → Apply → Archive. But the impact is profound: fewer bugs, cleaner code, and AI that actually follows your instructions.
In a world where AI can generate code in seconds, OpenSpec ensures that code is correct by design.
