OpenSpec

OpenSpec is a convention for writing down what you intend to build before an AI coding assistant builds it. It puts an openspec/ directory in the repository and keeps two things there: specs/, the requirements that currently hold, and changes/, the work in flight. A proposed change is a folder — proposal.md for why and what, design.md for the technical approach, tasks.md as the implementation checklist, and a specs/ folder carrying the requirement deltas. When the work lands, the folder moves to changes/archive/ under a dated name and the specs it changed are folded into the standing set. It is MIT licensed and maintained by Fission AI, who describe the approach as spec-driven development (SDD).

• Requirements are structured Markdown, not a schema - A requirement is a ### Requirement: heading with a SHALL statement, followed by #### Scenario: blocks written as **WHEN** / **THEN** bullets. Deltas are marked with headings like ## ADDED Requirements. There is no JSON Schema or formal grammar to conform to — the OpenSpec CLI validates the conventions, and the agent does the writing.
• Driven by slash commands - The workflow runs as /opsx:explore, /opsx:propose, /opsx:apply, /opsx:verify and /opsx:archive. The project claims support across 30+ assistants, each spelling the commands to its own taste — /opsx-propose in Cursor and Copilot, @opsx-propose in Amazon Q, $openspec-propose in Codex.
• A CLI, not just files - Installed as the Node package @fission-ai/openspec, openspec init scaffolds the directory and writes the agent instructions, and openspec update regenerates them as the tool moves.
• Stores put planning in its own repo - A beta feature lets the same openspec/ shape live in a separate repository, so one change can span several code repos and a platform team can own requirements that product teams read. Shared by git push like anything else.

For API teams the interesting part is the scenario grammar, which is BDD wearing new clothes: the Given/When/Then that never quite escaped the test suite, relocated to the place where the work is actually specified and pointed at an agent rather than a runner. OpenSpec sits alongside AGENTS.md and Agent Skills in the markdown control layer agents read, but answers a different question — those say who the agent is and how this project works, while OpenSpec says what is being built right now and what done looks like.

It is worth being clear about what this is not. OpenSpec is a single-vendor project with no standards body, no foundation, and no formal specification document behind it; the conventions are defined by the CLI and the documentation, and a version bump can move them. It is also one of at least three competing takes on the same idea, against GitHub’s Spec Kit and AWS’s Kiro, and the category has no interoperability story — a change folder written for one does not read in another. Note too that the name is contested: Microsoft has published protocol documentation under Open Specifications for years, and “open spec” is a generic phrase besides. Resolve this one to openspec.dev before citing it.