OpenSpec Installation and Initialization: 5 Minutes to Get Your Project Spec-Ready

This article is hands-on, no theory — install, initialize, understand the structure, and you're ready to move forward.

Prerequisites

You need Node.js 20.19.0 or later. Check your version:

node --version

If the version is high enough, continue. Otherwise, upgrade Node.js first.

Install OpenSpec

Install globally:

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

Or if you use pnpm / yarn / bun:

pnpm add -g @fission-ai/openspec@latest
yarn global add @fission-ai/openspec@latest
bun add -g @fission-ai/openspec@latest

Verify the installation:

openspec --version

If a version number is printed, you're good.

Initialize Your Project

Navigate to your project directory:

cd your-project
openspec init

Once complete, an openspec/ folder will appear in your project.

What the Directory Structure Looks Like

openspec/
├── specs/              # What your system looks like right now (source of truth)
│   └── <domain>/
│       └── spec.md
├── changes/            # Each pending change (one folder per change)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Delta spec for this change
│           └── <domain>/
│               └── spec.md
└── config.yaml         # Project configuration (optional)

Two core directories:

specs/ is your system's current documentation — it describes how the system behaves today, organized into domain-based folders. You can organize by feature area (auth/, payments/), by component (api/, frontend/), or by business boundary — whatever matches how your project is structured.

changes/ holds in-progress modifications — every feature you want to add or modify lives here in its own folder, containing its proposal, design, task list, and delta spec. Once done, you archive it and the delta spec merges back into specs/.

Start Telling Your AI to Use OpenSpec

Once initialized, open your AI assistant (Cursor, Claude Code, Windsurf, etc.) and type:

/opsx:propose <what you want to do>

For example:

/opsx:propose add-dark-mode

The AI will start building the change folder and related artifacts for you.

Not sure what /opsx:propose does? The next article explains the core concepts first, then we'll walk through the full workflow.

Enabling Advanced Workflows

The default installation uses the core profile, which includes four basic commands (propose, explore, apply, archive). If you want access to more commands like /opsx:new, /opsx:ff, and /opsx:verify, you can switch profiles:

openspec config profile

After selecting a profile, run this in your project:

openspec update

This sends updated command instructions to your AI, making the new slash commands available.

Keeping OpenSpec Up to Date

OpenSpec is actively maintained. Run these two commands periodically to stay current:

npm install -g @fission-ai/openspec@latest  # Upgrade the package
openspec update                              # Update AI command instructions

Environment is ready. The next article explains specs, changes, and artifacts — the three core concepts. Understanding these is what makes every command's purpose clear.

Next: specs, changes, artifacts: OpenSpec's Three Core Concepts