OpenSpec is a spec-driven development (SDD) framework designed to align humans and AI coding assistants by creating reviewable specifications before any code is written. It acts as “version control for intent,” helping to prevent “vibe coding” and maintain consistency.

1. Setup & Installation

Get started by installing the CLI globally and initializing your project:

• Install: npm install -g @fission-ai/openspec@latest
• Initialize: openspec init (Prompts you to select your AI tool, e.g., Claude Code, Cursor, Copilot)
• Update: openspec update (Regenerates tool configs after a CLI upgrade)

2. Core Workflow Commands (/opsx)

These slash commands are used within your AI assistant to manage the lifecycle of a feature or change.

3. Essential CLI Commands

Run these in your terminal to manage the state of your project:

• List Changes: openspec list (Shows all active and archived changes).
• Validate: openspec validate <change-id> --strict (Checks for structural or requirement issues).
• Show Specs: openspec list --specs (Displays current project specifications).

4. File Structure

The openspec/ directory organizes your project’s technical “source of truth”:

• project.md: High-level details about the project, tech stack, and conventions.
• AGENTS.md: A managed hand-off file for various AI assistants.
• changes/: Contains subfolders for each feature, including its proposal.md, design.md, and tasks.md.

5. Pro-Tips for Success

• Verb-Led IDs: Use kebab-case and verb-led IDs for changes (e.g., add-dark-mode, update-auth-api).
• Deltas Matter: Focus on “Delta Specs” to describe exactly what is changing, rather than rewriting the entire spec from scratch.
• Customization: Edit openspec/config.yaml to inject custom project rules or specific tech stack context for the AI to follow.