RSS 中文
⌕

Chapter 06 | Install OpenSpec

5 MIN READ | UPDATED: 2026-05-15

Chapter 6: Installing OpenSpec

Learning Objectives

Enable OpenSpec's specification capabilities in your project directory.

Installation

npm install -g @fission-ai/openspec
openspec --version
# 1.3.1 or newer

Initializing in Your Project

cd ~/work/learn-claude
openspec init

After completion, the directory structure will be:

flowchart TB
    Root["~/work/learn-claude/"] --> Specs["openspec/specs/
(empty, awaiting accumulation)"]
    Root --> Changes["openspec/changes/"]
    Changes --> Archive["archive/
(empty, completed changes)"]
    Root --> CC[".claude/
(may already exist)"]

    style Specs fill:#e8f5e9
    style Changes fill:#fff3e0
    style Archive fill:#f3e5f5

Role of each directory:

Path Meaning Who writes/reads
openspec/specs/ System's current committed capabilities Accumulated and merged from archive
openspec/changes/<name>/ A work-in-progress change Created by propose
openspec/changes/archive/ History of completed changes Moved here by archive

4 Core Skills

OpenSpec exists as skills within Claude Code. After installation, you can use:

Skill Purpose When to use
/opsx:explore Explore ideas, thinking phase Ideas are still vague
/opsx:propose Formalize ideas into a change artifact Ideas are clear
/opsx:apply Implement according to tasks.md Ready to start implementation
/opsx:archive Archive upon completion, update specs Implementation is complete

Full lifecycle:

flowchart LR
    Idea["💡 Idea"] -->|opsx:explore| Clear["Clear Requirements"]
    Clear -->|opsx:propose| Change["change folder"]
    Change -->|opsx:apply| Code["Code + Checkmarks"]
    Code -->|opsx:archive| Specs["specs/ accumulation"]

    style Specs fill:#c8e6c9

Verifying Successful Installation

Run:

openspec list --json

The output should be:

{
  "changes": []
}

→ No changes yet, which is expected.

Adding to Git Control

All OpenSpec files should be committed to Git (this is its core value—versionable requirements):

cd ~/work/learn-claude
git init
echo ".env" > .gitignore
git add openspec/ .gitignore
git commit -m "init: openspec scaffold"

What You Can Do Now

  • Initialize a blank OpenSpec project
  • Explain the roles of the specs/, changes/, and archive/ directories
  • Know when to use each of the 4 skills

The next chapter delves into OpenSpec's worldview—why this structure inherently solves the "requirement drift" problem.