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.
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 received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE 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. The v1.11.0 release notes mention Spec Diffs and Batch Status, which suggests the tool has added ways to compare spec changes and check the status of multiple proposals. The exact mechanics of these features are not detailed in the README, so they are worth verifying in the release notes.
Installation and First Steps
Installation is straightforward. The README states that OpenSpec requires Node.js 20.19.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 user guide is at `docs/stores-beta/user-guide.md`. 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. The README shows an example of a well-formed scenario, but it does not describe what happens when the AI produces a poor spec. Second, the tool is only as good as the review process. The README says 'you review the plan before any code is written,' but it does not provide a mechanism to enforce that review. 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 tool requires Node.js 20.19.0 or higher, which may be a constraint for older projects. Finally, the README does not describe how OpenSpec handles non-Markdown requirements, such as diagrams, or how it integrates with existing issue trackers. 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. The README mentions a guide for editing a change, which covers updating artifacts, going back, and reconciling manual edits. This suggests that keeping specs in sync with code is a known pain point. The v1.11.0 release adds Spec Diffs, which likely helps with this, but the details are not in the README. Upgrading the CLI is a simple `npm install -g @fission-ai/openspec@latest` command, but each release may change command behavior. The release notes for v1.10.0 mention Zed support and quieter installs, and v1.9.0 mentions Command Code and safer specs. These are incremental changes, not major rewrites. The license is MIT, which means you can modify and redistribute the tool without restriction, but you must include the original copyright notice. There is no mention of a commercial license or paid tiers. The project is actively maintained, with the last push on 2026-08-26, 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 20.19.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.
Community notes