Getting Started with OpenSpec

Get up and running with OpenSpec in minutes. This guide will walk you through installation, initialization, and your first spec-driven change.

Prerequisites

Before you begin, make sure you have:

  • Node.js 20.19.0 or higher - Check your version with node --version
  • npm, pnpm, yarn, or bun - Any package manager works
  • An AI coding assistant - OpenSpec works with 20+ tools including Cursor, Claude Code, GitHub Copilot, and more
  • A project directory - Any existing or new project
Brownfield vs Greenfield: OpenSpec is built for existing codebases (brownfield projects). You can initialize it in any existing project without disrupting your current workflow. Unlike tools optimized for new projects, OpenSpec excels at adding spec-driven development to legacy code.

Installation

Install OpenSpec globally using your preferred package manager:

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

# Using pnpm
pnpm install -g @fission-ai/openspec@latest

# Using yarn
yarn global add @fission-ai/openspec@latest

# Using bun
bun install -g @fission-ai/openspec@latest

Verify the installation by checking the version:

openspec --version

Initialize Your Project

Navigate to your project directory and initialize OpenSpec:

cd your-project
openspec init

This command will:

  • Create an openspec/ directory in your project
  • Generate configuration files
  • Create an AGENTS.md file with instructions for your AI assistant
  • Set up the folder structure for managing changes

Your First Change

Now you're ready to create your first spec-driven change. In your AI coding assistant, use the OpenSpec slash command:

/opsx:new add-dark-mode

This command tells your AI assistant to:

  1. Create a new change folder: openspec/changes/add-dark-mode/
  2. Start preparing a proposal document
  3. Set up the structure for specs, design, and tasks

Workflow Commands

OpenSpec provides several slash commands to manage your development workflow:

/opsx:new <feature-name>

Creates a new change proposal. Start here for any new feature or modification.

/opsx:ff

"Fast-forward" - Generates all planning documents (proposal, specs, design, tasks) at once.

/opsx:apply

Implements all tasks from the current change, following the specs and design documents.

/opsx:archive

Archives the completed change and updates the main specs. Ready for the next feature.

Understanding the Structure

After initialization, your project will have this structure:

your-project/
├── openspec/
│   ├── changes/
│   │   └── add-dark-mode/
│   │       ├── proposal.md
│   │       ├── specs/
│   │       ├── design.md
│   │       └── tasks.md
│   └── archive/
└── AGENTS.md
  • proposal.md - Why you're making this change and what's changing
  • specs/ - Requirements and scenarios
  • design.md - Technical approach and architecture decisions
  • tasks.md - Implementation checklist
  • AGENTS.md - Instructions for your AI assistant

Next Steps

Tips for Success

  • Start small - Begin with a simple feature to understand the workflow
  • Review proposals - Always review the proposal and specs before applying
  • Iterate freely - Update any artifact anytime - no rigid gates
  • Use high-reasoning models - OpenSpec works best with models like Opus 4.5 and GPT 5.2
  • Maintain context hygiene - Clear your context before starting implementation