OpenSpec: clarify requirements with AI before writing code

Purpose

When you develop with AI, requirements can get scattered across chats. A behavior you agreed to preserve today may be missed in the next change. OpenSpec keeps requirements, design decisions, and tasks in project files so you can review a plan before asking the AI to implement it.

It is a specification-driven development tool that combines a CLI with several agent skills. You can use it in your existing AI development tool without changing editors. The official project publishes its source under the MIT license.

When to use it

We think OpenSpec is worth trying when a feature takes several discussions, spans multiple chats, or has clear acceptance criteria. Keeping the requirements in the project gives you a document to check when you return to the work.

For a one-line copy edit, creating a full change plan may take more effort than making the edit. The size of the change can guide whether to use this workflow. These are editorial judgments based on the official documentation, not findings from our own testing or a performance comparison.

Example

To add an Agent Skills directory, you could first tell your AI assistant:

Help me explore how to build an Agent Skills directory. I want to include our own Skills and selected external ones, with category filters and date sorting. Clarify the requirements first; do not write code yet.

The official quickstart describes a change in five parts:

Explore: Discuss requirements, inspect existing code, and compare approaches without writing code.
Propose: Record the reason for the change, requirements, and tasks; add a design document when technical decisions need one.
Human review: Check the scope and acceptance criteria while the plan is still easy to change.
Apply: Have the AI implement the tasks against the files.
Archive: Update the main specifications and retain the record of the change.

To invoke exploration directly, use $openspec-explore in Codex or /opsx:explore in Claude Code. Invocation varies by tool; check the prompts shown during initialization and the supported tools documentation.

Limitations

Specifications still need human review. A wrong requirement remains wrong when written in a file. OpenSpec cannot guarantee correct AI output and does not replace software tests or human review.

Supported platforms, installation methods, and commands can change. Codex, Claude Code, Cursor, and GitHub Copilot are examples here; consult the official documentation for the complete list.

Installation

For npm installation, first check that you have Node.js 22.12.0 or newer. Then run:

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

Once a version appears, enter the project directory and initialize OpenSpec:

cd your-project
openspec init

Replace your-project with your project path and select the AI tools you use when prompted. You can then ask your assistant to explore requirements or propose a change. The official guide also offers a standalone installer and Homebrew; the standalone installer does not require Node.js. See the installation guide for other methods and updates.