Library / SDK
Fission-AI/OpenSpec avatar
Fission-AI/OpenSpec

OpenSpec: A Spec-First Workflow for Coding Assistants

OpenSpec structures requirements and change proposals so coding assistants can implement and verify work against an explicit specification.

74,914 stars5,134 forksTypeScriptMIT

At a glance

What is it?
OpenSpec structures requirements and change proposals in plain Markdown so coding assistants can implement and verify work against an explicit specification. This review covers its mechanism, setup, limitations, and alternatives.
Who is it for?
Adopt OpenSpec if you are a solo developer or a team that wants a lightweight, git-based way to make AI coding assistants work against explicit requirements and scenarios, especially on brownfield projects. Do not adopt it if you need a heavyweight requirements management tool or if your team cannot commit to reviewing AI-generated specs before code is written.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Fission-AI/OpenSpec74,914 ★ · +11,981
Star history
Repository2026-07-282026-11-15
Fission-AI/OpenSpec62.9k74.9k

11,981 Stars in the last 110 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The Problem: AI Coding Without a Contract

Coding assistants are good at generating code, but they are less good at knowing what to build and whether they built it correctly. Without an explicit specification, an assistant can drift, invent features, or miss requirements. OpenSpec addresses this by introducing a structured way to capture requirements and change proposals in plain Markdown. The intended users are solo developers who want to keep their AI honest on a single repo, and teams where a feature spans multiple repos, requirements are owned by one team and consumed by others, and planning starts before any code exists. The README's philosophy is explicit: fluid not rigid, iterative not waterfall, easy not complex. This is not a formal requirements tool; it is a lightweight convention that fits into an existing git workflow.

How It Works: Artifacts and Slash Commands

OpenSpec works through a set of slash commands that your coding assistant executes. The core command is `/opsx:propose`, which creates a structured change proposal. The README shows the output: a `proposal.md` explaining why the change is happening, a `specs/` folder with requirements and scenarios, a `design.md` for the technical approach, and a `tasks.md` as an implementation checklist. The specs themselves are plain Markdown with a specific format. A requirement is written with a `## ADDED Requirements` heading, followed by a `### Requirement:` block. Each requirement includes scenarios written as `WHEN` and `THEN` steps. There is no special syntax to learn. The assistant writes these artifacts; the human reviews the plan before any code is written. There is also `/opsx:explore`, described as a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written.

Installation and First Steps

Installation is straightforward. The README states that the npm install needs Node.js 22.12.0 or higher. You install the CLI globally with `npm install -g @fission-ai/openspec@latest`. Then, in your project directory, you run `openspec init`. This command sets up the `openspec/` directory and prints the correct form of the slash command for your tool. The canonical name is `/opsx:propose`, but the actual invocation varies by tool: `/opsx-propose` for Cursor and GitHub Copilot, `@opsx-propose` for Amazon Q, and `$openspec-propose` for Codex. The README notes that 30+ tools are supported. You can also use `openspec config profile` to select an expanded workflow that includes `/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, and `/opsx:onboard`. After selecting a profile, apply it with `openspec update`. The README also mentions a setup prompt you can paste into your coding assistant to automate installation and initialization. This low-friction setup is a deliberate design choice, consistent with the project's philosophy of being easy not complex.

The Stores Beta: Cross-Repo Planning

The most interesting part of OpenSpec is Stores, currently in beta. The README describes Stores as planning in a repo of its own. Instead of keeping specs and changes in the same repo as your code, you create a separate repository with the same `openspec/` shape, shared by `git push`. This allows cross-repo features: one change, one plan, even when the code lands in three repos. It also enables shared requirements, where a platform team owns the specs and product teams reference them read-only, right where their coding agent can read them. The README frames this as the answer to the hard part of team adoption: a feature spans the API server, the web app, and a shared library. Stores are in beta, which means the feature is not yet stable. The Stores guide is at openspec.dev/docs/stores. This is a significant architectural shift from the single-repo model, and it is worth evaluating carefully before relying on it for production work. The beta label is a genuine limitation, not a marketing term.

Limitations and Failure Modes

OpenSpec has several limitations that are visible from the README. First, it relies on your coding assistant to generate the spec artifacts. If your assistant produces vague requirements or incomplete scenarios, the verification step will be weak. Second, the tool is only as good as the review process. The README says 'you review the plan before any code is written.' A developer who skips the review and lets the AI implement directly will negate the entire point. Third, the Stores feature is in beta, so cross-repo planning may change or break. Fourth, the npm install requires Node.js 22.12.0 or higher, which may be a constraint for older projects. For a team that already has a robust requirements process, OpenSpec may feel redundant or restrictive.

A Real Alternative: ADRs and Conventional Commits

An alternative approach is to use Architecture Decision Records (ADRs) combined with conventional commits. ADRs capture a decision, its context, and its consequences in a Markdown file, similar to OpenSpec's `proposal.md`. Conventional commits provide a structured commit message format that can be used to trigger verification. The difference is that ADRs are typically written by humans for humans, and they do not include machine-readable scenarios like OpenSpec's `WHEN`/`THEN` blocks. Conventional commits do not include any specification at all; they only describe what changed. OpenSpec goes further by providing a structured format for requirements and scenarios that a coding assistant can both generate and verify against. ADRs are more lightweight and do not require a specific tool or a Node.js runtime. But they also do not give your AI a checklist to follow. If your team already uses ADRs, OpenSpec might feel like a heavier version of the same idea, but with the added benefit of being AI-native.

Maintenance and Upgrade Cost

The maintenance cost of OpenSpec is tied to the artifacts it generates. Once you create a change proposal, you must keep it updated as the code evolves. Upgrading the CLI is a simple `npm install -g @fission-ai/openspec@latest` command, but each release may change command behavior. The latest release is v1.16.0, published 2026-10-30. The license is MIT, which means you can modify and redistribute the tool without restriction, but you must include the original copyright notice. The project is actively maintained, with the last push on 2026-11-02, but the maintenance burden falls on you to keep your specs current.

Editorial conclusion

Adopt OpenSpec if you are a solo developer or a team that wants a lightweight, git-based way to make AI coding assistants work against explicit requirements and scenarios, especially on brownfield projects. Do not adopt it if you need a heavyweight requirements management tool or if your team cannot commit to reviewing AI-generated specs before code is written. Before adopting, verify that your coding assistant is among the 30+ supported tools, that your Node.js version is 22.12.0 or higher, and that you are comfortable with the beta status of Stores for cross-repo planning. OpenSpec is a practical, low-friction layer for AI-assisted development, but its value depends entirely on your willingness to review and maintain the specs it generates.

Frequently asked questions

What does OpenSpec do?

It structures requirements and change proposals so a coding assistant implements and verifies work against an explicit specification. Running `/opsx:propose` creates a directory under `openspec/changes/` containing proposal.md, a specs folder of requirements and scenarios, design.md and tasks.md, all before any code is written.

How do I install OpenSpec?

The npm route needs Node.js 22.12.0 or higher. Install it with `npm install -g @fission-ai/openspec@latest` or, on macOS or Linux, `brew install openspec`, then run `openspec init` in your project directory. A setup prompt is also provided for assistants to run the steps for you.

How do I use OpenSpec explore?

`/opsx:explore` is a no-stakes thinking partner that reads your code, weighs options and shapes a plan before any code gets written. It ships in the default profile alongside `/opsx:propose`, so it is available immediately after `openspec init`.

How do I use OpenSpec with Claude Code?

The canonical command is `/opsx:propose`, and the spelling depends on your tool: Cursor and GitHub Copilot use `/opsx-propose`, Amazon Q uses `@opsx-propose` and Codex uses `$openspec-propose`. The README does not give a separate spelling for any particular assistant, and `openspec init` prints the correct form for the tools you selected.

Who owns OpenSpec?

The package is published as `@fission-ai/openspec` under the MIT license with the author field set to OpenSpec Contributors, and the code lives in the Fission-AI GitHub organisation. The repository root carries MAINTAINERS.md, CONTRIBUTING.md, SECURITY.md and a CHANGELOG.md, and releases are published through changesets.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
  4. Release notes
Community

Where developers are discussing it

Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 2 in the last 30 days; newest first.

Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/fission-ai-openspec.svg)](https://hysenlabs.com/projects/fission-ai-openspec)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/fission-ai-openspec.svg)](https://hysenlabs.com/projects/fission-ai-openspec)

Was this useful?