OpenSpec for Beginners: Keeping Your AI Collaboration Framework Within Clear Boundaries Using Specification Docs

TIP

GitHub: https://github.com/Fission-AI/OpenSpec · MIT License · Node.js 20.19.0+

Beginner-friendly | ~15 minutes | You’ll learn OpenSpec’s core concepts (Delta Specs, the Artifact dependency graph), the initialization flow, the OPSX workflow (propose → apply → archive), and parallel management of multiple changes

Project Overview

First, let’s admit a simple truth: when you use an AI coding assistant, have you ever run into situations like this—chatting away, and the AI changes parts you never intended to touch; or you switch to a different conversation context and the AI completely forgets what it previously said; or every time you ask the AI to build a new feature, the result ends up not really matching what you wanted at all.

These problems aren’t because the AI is “too dumb.” It’s because your requirements have never been 「signed off」. They only exist in the chat log, where the AI has too much room to freestyle.

What OpenSpec does is straightforward: before you start writing code, align humans and the AI on a specification document—then have the AI act according to that document. Developed by Fission-AI, it supports 20+ AI coding tools (Claude Code, Cursor, Windsurf, etc.). In essence, it adds a lightweight spec-management layer on top of AI coding assistants.

Target Audience

Developers who use AI coding assistants day to day
Engineers who struggle in team collaboration because humans and AI don’t share the same understanding of requirements
Product managers who want AI output to be more controllable

Core Dependencies and Environment

Node.js 20.19.0+

TIP

macOS users are recommended to use nvm to manage Node versions—switch in one line: nvm install 20 && nvm use 20

Full Project Structure Tree

openspec/
├── specs/                    # System behavior specs (grouped by domain)
│   └── <domain>/spec.md
├── changes/                 # Change proposals (one folder per change)
│   ├── <change-name>/
│   │   ├── proposal.md      # Motivation + Scope + Approach
│   │   ├── specs/          # Delta Specs (ADDED/MODIFIED/REMOVED)
│   │   │   └── <domain>/spec.md
│   │   ├── design.md        # Technical design
│   │   └── tasks.md         # Implementation checklist
│   └── archive/              # Archived history
└── config.yaml              # Project configuration (optional)

Step-by-Step

Step 1: Install OpenSpec Globally

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

After installation, verify:

openspec --version
# 1.2.0

WARNING

The Node.js version must be >= 20.19.0; lower versions will throw SyntaxError. If you hit this problem, upgrade Node first: nvm install 20 && nvm use 20

Step 2: Initialize Your Project

Go into your project directory and run the initialization command:

cd your-project
openspec init

This command does three things:

Creates the openspec/ directory structure
Generates the AI skill files under .claude/ (so your AI assistant can recognize /opsx:* commands)
Asks whether you want to create the project config file config.yaml (optional, used to inject project context)

After initialization, your project gains these directories:

openspec/
├── specs/       # Current system behavior specs (empty directory; waiting to be filled)
├── changes/     # Change proposal directory (empty directory)
└── config.yaml  # Project configuration (if you chose to create it)

Step 3: Enable the OPSX Expanded Workflow

Freshly installed OpenSpec defaults to the core mode, with only 4 commands: propose, explore, apply, archive. If you want the full workflow (including new, continue, ff, verify, bulk-archive, etc.), run:

openspec config profile
# choose expanded or full
openspec update

openspec update regenerates the AI skill files based on your selected profile, so you can use more commands during your conversations with the AI.

TIP

Not sure which profile you’re on? Run openspec config show to check.

Step 4: Create Your First Change — Add Dark Mode

Now have the AI help you create a change. For example, let’s say “add dark mode to the app”—tell the AI directly:

/opsx:propose add-dark-mode

The AI will automatically create four Artifact files under openspec/changes/add-dark-mode/:

openspec/changes/add-dark-mode/
├── proposal.md     # Why this change? Scope? Approach?
├── specs/
│   └── ui/spec.md  # Delta specs for the UI domain
├── design.md       # How should the technical design work?
└── tasks.md        # What exactly needs to be done? Listed step by step

proposal.md looks like this (generated by AI automatically; you and the AI can edit together):

# Proposal: Add Dark Mode

## Intent
The user requests adding dark mode to reduce eye fatigue during nighttime use.

## Scope
- Add a theme toggle button in settings
- Support system preference detection
- Persist preferences to localStorage

## Approach
Use CSS variables for theming, and manage state with React Context.

specs/ui/spec.md is the key Delta spec, in this format:

# Delta for UI

## ADDED Requirements

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

#### Scenario: Manual toggle
- GIVEN the user is on any page
- WHEN the user clicks the theme toggle button
- THEN the theme switches immediately, and the preference persists across sessions

#### Scenario: System preference
- GIVEN the user has no saved preference
- WHEN the application loads
- THEN the app uses the system’s preferred color scheme

TIP

The core of a Delta spec is “changes”—it only describes what’s added, modified, and removed. When archiving, these Deltas are merged into the main spec file.

tasks.md is your implementation checklist:

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext (light/dark state)
- [ ] 1.2 Add CSS variable definitions for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create a ThemeToggle component
- [ ] 2.2 Add the toggle button on the settings page
- [ ] 2.3 Add a quick toggle in the Header

## 3. Styling
- [ ] 3.1 Define dark theme color palettes
- [ ] 3.2 Make existing components use CSS variables

Step 5: Execute the Implementation Tasks

Once the spec document is confirmed correct, implement:

/opsx:apply

The AI checks tasks in tasks.md one by one; each completed task gets a checkmark. You’ll notice the AI’s behavior changes—it no longer “freestyles,” but strictly progresses according to tasks.md. If you discover design issues during implementation, you can directly edit design.md, then continue with apply—the AI will automatically keep up.

Step 6: Verify and Archive the Change

Verify (optional, but recommended):

/opsx:verify

The AI checks your implementation across three dimensions:

Dimension	What it checks
Completeness	Are all tasks in tasks.md done? Are all scenarios in the specs covered?
Correctness	Does the implementation match the spec’s intent? Are edge cases handled?
Coherence	Do the design decisions in design.md reflect in the code?

Archive:

/opsx:archive

Archiving does two things:

Merge the Delta spec into the main spec file: openspec/specs/ui/spec.md
Move the change folder into openspec/changes/archive/2026-04-11-add-dark-mode/

After archiving, the system spec files are updated, and you also gain a complete history of the change.

Step 7: Parallel Management of Multiple Changes

In real development, you’re often interrupted mid-way to handle other issues. OpenSpec supports parallel changes:

# Suppose you’re working on add-dark-mode, but suddenly you need to fix a bug
/opsx:new fix-login-redirect

# Finish the bug fix normally
/opsx:ff
/opsx:apply
/opsx:archive

# Go back to the dark mode work
/opsx:apply add-dark-mode

When you’ve completed multiple changes, archive them together:

/opsx:bulk-archive

OpenSpec will automatically detect spec conflicts (both changes modified specs/ui/) and merge them in chronological order.

Step 8: Customize the Schema

OpenSpec’s OPSX workflow is defined by Schema, and you can fully customize the types of Artifacts and their dependency relationships. For example, if you want a workflow that “researches first, then proposes,” you can do:

# Fork a new schema from the default schema
openspec schema fork spec-driven research-first

The generated Schema structure:

openspec/schemas/research-first/
├── schema.yaml
└── templates/
    ├── research.md
    ├── proposal.md
    └── tasks.md

The corresponding dependency graph becomes:

research ──► proposal ──► tasks

In schema.yaml, define:

# 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]

TIP

If you place a Schema under the project directory openspec/schemas/, it will be version-controlled along with the project, and everyone on the team can use the same workflow.

Step 9: Quick Reference for Common CLI Commands

# Initialize
openspec init

# Update AI skill files (run this after every upgrade or after changing profile)
openspec update

# View current configuration
openspec config show

# Switch workflow profile
openspec config profile

# View active changes
openspec list

# View details for a specific change
openspec show add-dark-mode

# Validate format
openspec validate add-dark-mode

# Interactive Dashboard
openspec view

# Schema management
openspec schemas              # list available schemas
openspec schema which --all   # see where each schema comes from
openspec schema validate my-schema  # validate schema

Troubleshooting

1. AI can’t find the `/opsx:propose` command

This is the most common issue. After running openspec init, your AI assistant needs to reload the skill files. Run:

openspec update

Then reopen the conversation. If the AI still doesn’t recognize it, manually check whether the .claude/ directory exists.

2. `openspec init` reports a Node.js version error

node --version
# confirm >= 20.19.0

# if your version is too low, upgrade with nvm
nvm install 20 && nvm use 20

3. Conflict when merging Delta Specs

When running /opsx:bulk-archive, if two changes modify the same spec file, OpenSpec will detect it and prompt you. Merging in chronological order is the default behavior; if you need manual handling:

# Archive one change on its own
/opsx:archive fix-login-redirect

# Archive the other change
/opsx:archive add-dark-mode

4. Custom Schema fails to load

Usually this is caused by a syntax error in schema.yaml. Check it by running:

openspec schema validate my-schema

Common errors include incorrect YAML indentation, or the requires field of an artifact referencing an ID that doesn’t exist (circular dependency).

5. The spec format generated by AI doesn’t meet the requirements

You can add rules in openspec/config.yaml:

rules:
  specs:
    - Describe each scenario using the GIVEN/WHEN/THEN format
    - Each Requirement must have at least one Scenario

These rules are injected into the AI’s instructions for generating specs.

6. During `/opsx:apply`, the AI skips some tasks

Tell the AI directly:

Please execute tasks in the order of tasks.md. Task 1.3 is not finished yet—do not skip it.

OpenSpec’s fluid feature lets you edit Artifacts at any time—after modifying tasks.md, run apply again and the AI will continue from where it left off.