OpenSpec Deep Dive: The Ultimate Form of Specification‑Driven Development

01 | Why Choose OpenSpec as the Representative of SDD?

OpenSpec is a specification‑driven development (SDD) framework designed for existing (brownfield) codebases. It is not a project scaffold but a spec layer that tells AI what the project is, what can be changed, what cannot, and how to verify changes.

Four reasons make OpenSpec the preferred SDD representative:

Pure Design : Implements the core idea of Delta Spec—write only what changed, unlike other frameworks that wrestle with full‑spec authoring.

Brownfield Friendly : Allows gradual adoption without requiring a complete spec of the whole system.

Tool‑Agnostic : Works with any IDE, AI model, or pure command‑line environment.

Design Migratable : Understanding OpenSpec’s philosophy makes it easy to translate to Spec‑Kit, Kiro, or similar frameworks.

02 | Design Philosophy: Spec Is a Contract, Not a Document

Philosophy 1 – Spec Is a Contract : Specs are mandatory contracts between AI and humans, not optional documentation. The main spec (under specs/) describes the system’s real behavior; any change must first modify the spec, and AI must obey it during the Apply phase.

Philosophy 2 – Change Is a First‑Class Citizen : Each change lives in its own directory with a full audit trail (proposal, specs, design, tasks), similar to how Git treats commits as first‑class objects.

Philosophy 3 – Incremental > Full : Only the delta (added/modified/removed) is written. The three delta sections ( ## ADDED, ## MODIFIED, ## REMOVED) are accumulated to form the complete spec, analogous to a database WAL.

03 | Architecture: Four Key Concepts

Concept 1 – Main Specs : Authoritative description of the current system, organized by domain (e.g., auth/, payments/). Example ( specs/auth/user-login.md):

# User Login Spec

## Feature Description
User logs in with email + password.

## Behavior Contract
- Success: return JWT token (24h)
- Wrong password: 401, lock after 5 attempts for 30 min
- Email not found: 401 (no detail)

Concept 2 – Changes : Each change directory contains four core files: proposal.md – why the change is needed (motivation, impact, risk). specs/*.md – the Delta Spec for this change. design.md – technical design (architecture, data flow, fault tolerance). tasks.md – atomized task list.

Concept 3 – Delta Spec : The core innovation. Three operations are expressed with headings:

## ADDED Requirements
### Dark‑mode toggle
- User can switch dark mode in settings
- Preference saved in localStorage

## MODIFIED Requirements
### Color variable definition [MODIFIED]
- Old: hard‑coded #FFFFFF, #000000
- New: use CSS variables --bg-primary, --text-primary

## REMOVED Requirements
### Forced white theme
(removed, replaced by dark‑mode toggle)

Merging rules: ADDED appends, MODIFIED replaces, REMOVED deletes from the main spec.

Concept 4 – config.yaml : Provides global context (tech stack, coding conventions, AI prompts) and is lighter than Spec‑Kit’s constitution.md.

04 | Workflow Deep Analysis

OpenSpec offers two profiles:

Profile 1 – Quick (default) : Suitable for simple changes, three core commands: /opsx:propose <change‑name> – create a change proposal. /opsx:apply – execute tasks. /opsx:archive – archive the change.

Profile 2 – Expanded : For complex changes, six commands: /opsx:explore – scan existing code, generate initial spec. /opsx:new <name> – scaffold change directory. /opsx:continue – iteratively generate proposal → specs → design → tasks. /opsx:verify – verify implementation matches spec. /opsx:apply – execute implementation. /opsx:archive – archive.

Quick mode step‑by‑step : /opsx:propose: Reads config.yaml, loads current specs, analyses the codebase, creates a changes/ directory with proposal.md, Delta Spec, design.md, and tasks.md. AI first understands the existing system before designing.

Human review: Examine proposal, specs, design, and tasks; edit or ask AI to improve any unsatisfactory part. /opsx:apply: Executes tasks in order, committing each as an atomic Git commit, strictly following the specs. /opsx:archive: Verifies all tasks are done, runs tests, merges Delta Specs into the main spec, moves the change directory to changes/archived/, and updates the “truth source”.

05 | Five Design Highlights Worth Learning

Design 1 – Change Isolation : Each change lives in its own directory, enabling parallel development and easy abandonment.

Design 2 – Archival History : Archived changes are kept under changes/archived/, preserving a full audit trail.

Design 3 – Delta > Diff : Delta Spec expresses intent (e.g., “timeout reduced from 60 min to 30 min”) at a semantic level, easier for humans and AI than raw Git diffs.

Design 4 – Understand Before Design : The /opsx:propose step forces AI to read existing specs and code, avoiding hallucinated designs.

Design 5 – Progressive Adoption : No need to write the whole spec at once; teams can start with new‑feature specs and gradually fill gaps.

06 | Manifestation of the Three Core Principles

Decision Externalization :

Global conventions → config.yaml System state → specs/* Change motivation → changes/*/proposal.md Technical decisions → changes/*/design.md Execution progress → changes/*/tasks.md History → changes/archived/* Structured Workflow :

Quick: Propose → Apply → Archive (3 stages).

Expanded: Explore → New → Continue → Verify → Apply → Archive (6 stages).

Task Atomization : Tasks are listed in tasks.md and executed atomically, though isolation relies on the underlying AI tool’s sub‑agent capabilities.

07 | Limitations, Suitable Scenarios, and Comparison with Spec‑Kit

Limitations

Spec maintenance cost – the main spec can drift if “spec first” is not enforced.

Overkill for tiny changes – even a typo requires the full propose‑apply‑archive cycle.

Limited cross‑service coordination – no built‑in dependency orchestration.

Depends on team culture – without disciplined spec review, OpenSpec becomes ceremonial.

Suitable Scenarios (rating ★)

Existing brownfield projects – ★★★★★

Frequent iterations (multiple weekly changes) – ★★★★★

Frequent refactoring – ★★★★★

Need for change audit – ★★★★★

New greenfield projects – ★★★

Emphasis on rapid prototyping – ★★

Final Comparison with Spec‑Kit

Core data model : OpenSpec uses Delta Spec (incremental); Spec‑Kit uses Full Spec (complete).

Analogy : OpenSpec ≈ Git (snapshot + increment); Spec‑Kit ≈ Word document (direct edit).

Startup cost : OpenSpec low (direct propose); Spec‑Kit high (write constitution first).

Brownfield friendliness : OpenSpec ★★★★★; Spec‑Kit ★★★.

Change audit : OpenSpec ★★★★★; Spec‑Kit ★★★.

Fit for bug fixes : Both strong.

Fit for feature expansion : OpenSpec ★★★★; Spec‑Kit ★★★★★.

Summary

OpenSpec is an engineering infrastructure for AI‑assisted code changes, not an IDE plugin.

Three core philosophies: spec as contract, change as first‑class citizen, incremental > full.

Delta Spec (ADDED/MODIFIED/REMOVED) is the key innovation, offering higher‑level intent than Git diffs.

Progressive adoption lets the main spec emerge over time.

Brownfield‑friendly design makes it more suitable for existing large codebases than Spec‑Kit.

Clear limitations include spec maintenance overhead, heaviness for tiny changes, and reliance on team culture.