1. What OpenSpec Is

OpenSpec is an open-source, lightweight AI-assisted spec-driven development framework. It stores specs and changes in Markdown files, drives the AI assistant with slash commands (such as /opsx:propose and /opsx:apply), and uses a CLI to manage state, validate format, and archive changes.

In short, it turns “requirements talked out in a conversation” into a “traceable, iterable, archivable contract” — align before writing code, correct at any point during implementation, and when you are done, let the change settle into the source of truth for system behavior.

It supports 25+ AI coding tools, including Cursor, Claude Code, GitHub Copilot, Codex, and Windsurf.

• Project repository: https://github.com/Fission-AI/OpenSpec
• npm package: https://www.npmjs.com/package/@fission-ai/openspec

2. Why You Need It

AI coding assistants are already very capable, but the experience is often like this:

• You describe a requirement in the chat, and the AI immediately writes code
• Halfway through implementation you discover a misunderstanding and have to make major changes
• The context fills up with chat history, and key constraints get forgotten
• Several features run in parallel, requirements are scattered across chat logs, and there is no way to review them

The root cause is that requirements exist only in chat history, with no structured “spec layer.”

That is exactly the problem OpenSpec solves — before writing code, the human and the AI first agree on what is to be done; after writing code, the change is archived so the spec keeps updating.

3. Core Design Philosophy

OpenSpec’s four principles:

Traditional spec systems are locked into the phases of “plan first, then implement, then finish.” OpenSpec lets you create or modify any artifact at any moment; if you find a problem with the design mid-implementation, just edit design.md and continue with /opsx:apply.

Most software work is not building from scratch but modifying an existing system. OpenSpec’s Delta Spec mechanism lets you describe only “what changed,” instead of rewriting the whole spec.

4. Directory Structure

OpenSpec creates an openspec/ directory in your project:

openspec/
├── specs/              # source of truth — the system's current behavior spec
│   └── <domain>/
│       └── spec.md
├── changes/            # changes in progress — one folder per feature
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Delta specs
│           └── <domain>/
│               └── spec.md
└── config.yaml         # project configuration (optional)

• Specs describe how the system works now
• Changes describe how the system will change

This separation brings three benefits: several Changes can be developed in parallel; during review, the proposal, design, and delta specs are all clear at a glance; and after archiving, the Change moves into changes/archive/, preserving the full decision context.

5. The OPSX Workflow

OpenSpec’s standard workflow is called OPSX (OpenSpec eXtended workflow), replacing the earlier Legacy workflow (/openspec:proposal and so on).

Artifact dependencies:

proposal (root node)
    ├── specs (requires: proposal)
    └── design (requires: proposal)
            └── tasks (requires: specs, design)

specs and design can be created in parallel; tasks can only be created once both are done — but if you do not need a technical design, you can skip design.

5.1 Two Modes of Use

Default shortcut path (core profile):

/opsx:propose → /opsx:apply → /opsx:sync → /opsx:archive

A single command creates all planning artifacts; suitable for most scenarios.

Expanded workflow:

1
2

openspec config profile   # choose the expanded workflow
openspec update             # refresh the AI instructions

/opsx:new → /opsx:ff or /opsx:continue → /opsx:apply → /opsx:verify → /opsx:archive

• /opsx:new — creates only the Change scaffold
• /opsx:continue — creates artifacts one at a time
• /opsx:ff — fast-forward, creating all planning artifacts at once
• /opsx:verify — verifies that the implementation matches the spec

6. Quick Start

6.1 Requirements

• Node.js 20.19.0 or later
• Any supported AI coding tool (Cursor, Claude Code, etc.)

6.2 Installation and Initialization

1
2
3
4
5
6
7

npm install -g @fission-ai/openspec@latest

cd your-project
openspec init

# configure only specific tools
openspec init --tools cursor,claude

After initialization it generates the openspec/ directory plus the Skills and Commands files for your AI tool (such as .cursor/skills/ and .cursor/commands/).

6.3 Your First Change

In the AI conversation:

/opsx:propose add-user-profile-page

The AI creates openspec/changes/add-user-profile-page/ and generates the four artifacts: proposal, specs, design, and tasks.

Then run in order:

/opsx:apply      # implement item by item per tasks.md
/opsx:archive    # merge Delta Specs into the main Specs, move the Change into archive

7. A Worked Example: Adding Dark Mode

7.1 Proposing the Change

You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we do it, what changes
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist

proposal.md answers intent, scope, and approach:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# Proposal: Add Dark Mode

## Intent
Users report that they need a dark mode to reduce visual fatigue at night.

## Scope
- Add a theme toggle to the settings page
- Support system-preference detection
- Persist the preference to localStorage

Out of scope:
- Custom color themes (a later iteration)

## Approach
Use CSS custom properties for theming and React Context for state.

specs/ui/spec.md is the Delta spec:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

tasks.md is the implementation checklist:

1
2
3
4
5
6
7
8

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page

7.2 Implementation and Archiving

You: /opsx:apply
AI:  Working through tasks... All tasks complete!

You: /opsx:archive
AI:  ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/

If during implementation you find the design needs adjusting — say, switching to Tailwind’s dark: prefix — just edit design.md and continue with /opsx:apply. That is the core value of OPSX’s “fluid actions.”

8. Delta Spec

Delta Spec is OpenSpec’s most important concept and the technical embodiment of its “brownfield-first” philosophy. It uses three sections to describe the type of change:

1
2
3
4
5
6
7
8

## ADDED Requirements
(new behavior — appended to the main Spec on archive)

## MODIFIED Requirements
(modified behavior — replaces the original Requirement on archive)

## REMOVED Requirements
(removed behavior — deleted from the main Spec on archive)

On archive, the Delta Spec inside the Change is merged into the main Spec, and the complete Change context is kept in changes/archive/.

9. About the Artifacts

Each Change contains four kinds of artifact:

proposal → specs → design → tasks → implement
   │          │         │         │
  why       what       how      steps
+ scope    (Delta)  (technical (checkbox
+ approach           decisions)  list)

9.1 Proposal — Intent and Scope

It answers: Intent (what problem is being solved), Scope (what is inside and outside the scope), and Approach (roughly how to solve it).

9.2 Specs — Behavior Contract

A Spec describes observable behavior, not implementation details.

What should go into a Spec: observable behavior that users or downstream systems depend on; input, output, and error conditions; security/privacy/reliability constraints; and testable scenarios (Given/When/Then).

What should not go into a Spec: internal class or function names, library or framework choices, and step-by-step implementation plans (those belong in design.md or tasks.md).

A quick test: if the implementation changes but externally visible behavior does not, it does not belong in the Spec.

9.3 Design — Technical Approach

It records architectural decisions, data flow, and file-change plans in ADR style:

1
2
3
4
5

### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency

9.4 Tasks — Implementation Checklist

Concrete steps with checkboxes, numbered hierarchically (1.1, 1.2, 2.1…), with each group of tasks sized to be completed in a single session.

10. Slash Command Cheat Sheet

When to Update an Existing Change vs. Create a New One

The principle: updating preserves context, creating provides clarity — keep committing to the same feature, and open a new branch for a genuinely new feature.

11. Common CLI Commands

1
2
3
4
5
6
7
8
9

openspec list                              # list Changes in progress
openspec show add-dark-mode                # show Change details
openspec validate add-dark-mode            # validate Spec format
openspec status --change add-dark-mode --json  # JSON status (for the AI to query)
openspec view                              # interactive Dashboard
openspec schemas                           # list available Schemas
openspec schema init my-workflow           # create a custom Schema
openspec schema fork spec-driven my-workflow
openspec update                            # refresh AI instructions after an upgrade

Upgrading OpenSpec:

1
2

npm install -g @fission-ai/openspec@latest
cd your-project && openspec update

12. Comparison with Similar Tools

12.1 vs. GitHub Spec Kit

Spec Kit is comprehensive but heavier: strict phase gates, a large set of Markdown templates, and a Python environment requirement. OpenSpec is lighter: initialization in seconds, no phase lock-in, iterate at any time.

12.2 vs. AWS Kiro

Kiro has powerful spec capabilities, but it locks you into the Kiro IDE and mainly supports Claude models. OpenSpec is more open: it supports 25+ AI tools and works with the toolchain you already have.

12.3 vs. Doing Nothing

AI coding without a spec layer: vague requirements → unpredictable results; context pollution → key constraints forgotten; no way to review → changes scattered across chat history. OpenSpec strikes a balance between predictability and lightness.

13. Custom Workflows

13.1 Project Configuration (config.yaml)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e  

rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format for scenarios
  design:
    - Include sequence diagrams for complex flows

• context is injected into the AI instructions for every artifact
• rules inject extra rules by artifact type
• Schema precedence: CLI flag > Change metadata > config.yaml > default

13.2 Custom Schemas

When the default proposal → specs → design → tasks does not suit your team, you can create a custom Schema:

1
2

openspec schema init research-first
openspec schema fork spec-driven research-first

Example “research first, then propose” workflow:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []
  - id: proposal
    generates: proposal.md
    requires: [research]
  - id: tasks
    generates: tasks.md
    requires: [proposal]

Dependency graph: research → proposal → tasks (skipping specs and design).

13.3 Multi-Repository Collaboration (Workspace Beta)

When work spans multiple repos or several directories in a monorepo, OpenSpec offers a Workspace capability:

1
2
3
4
5
6

openspec workspace setup
openspec workspace setup --no-interactive --name platform \
  --link /repos/api --link web=/repos/web
openspec workspace list
openspec workspace open platform --agent github-copilot
openspec workspace doctor

A Workspace is a local coordination surface; each repo’s openspec/ is still home to its Specs and Changes. Implementation and archiving still happen in each repo.

14. Usage Advice

14.1 Model and Context

OpenSpec works best with high-reasoning models (such as Codex 5.5 and Opus 4.7). Clear the context window before starting implementation — the artifact files themselves are structured context, and there is no need to stuff the entire chat history into the window.

14.2 Spec Strictness

OpenSpec argues against over-documenting; choose the depth according to risk:

Lite Spec (default, most Changes): short behavior-first requirements, clear scope and non-goals, and a few acceptance checks.

Full Spec (high-risk Changes): cross-team/cross-repo changes, API/contract changes, migrations, security/privacy-related work, and scenarios where ambiguity could lead to expensive rework.

14.3 Choosing a Workflow

15. FAQ

Q: How much documentation overhead does OpenSpec add?

A: The goal is the minimum necessary spec. Most Changes are fine with a Lite Spec — a few Requirements plus Scenarios, and a tasks checklist. The AI generates the first draft; you just review and correct.

Q: Do I have to use OpenSpec to do AI coding?

A: No. OpenSpec is an optional structuring layer. But if you have lived through the pain of rework caused by the AI misunderstanding you, this layer has a high return on investment.

Q: How do I adopt it in an existing project?

A: Just run openspec init in the root of the existing project; no code refactoring is needed. Start with your next new feature and accumulate Specs gradually.

Q: What is the relationship between Specs and tests?

A: Scenarios in a Spec should be testable — you can (and should) write automated tests for them. The Spec is the behavior contract, and the tests are its verification.

Q: Which AI tools are supported?

A: 25+ tools, including Cursor, Claude Code, GitHub Copilot, Codex, Windsurf, Cline, Gemini CLI, Amazon Q, and more. See the Supported Tools doc for the full list.

16. Summary

OpenSpec’s core value: align before the AI writes code, and after the code is written, let the change settle into the system spec.

The complete work loop:

1. Specs describe current behavior
2. Changes propose modifications (Delta Specs)
3. /opsx:apply implements the changes
4. /opsx:archive merges the Delta, updating the Specs
5. The Specs describe the new behavior
6. The next Change continues from the updated Specs

If you are using an AI coding assistant for serious project development, OpenSpec is worth a try. Initialization takes only a few seconds, and your first Change starts with /opsx:propose.