AI coding assistants have changed the way software is written, but they have also exposed a new problem: when requirements live only in chat, development becomes harder to control. A long conversation can start with a clear idea and end with an implementation that does not quite fit the product, breaks an internal convention, or solves a different problem from the one originally intended.
OpenSpec was created precisely to fill that gap. The project, published on GitHub by Fission AI under the MIT licence, presents itself as a spec-driven development framework for coding assistants. Its goal is not to replace tools such as Claude Code, Codex, Cursor, Gemini CLI or similar platforms, but to add a lightweight layer of planning and traceability before AI starts touching the code.
The idea is simple: before implementation begins, the team agrees on what will be built, why it is being built, what requirements it must meet, what technical design it will follow and which specific tasks the agent will need to execute. Instead of launching a generic prompt and trusting the model to understand the full context, OpenSpec organises the work into artefacts inside the repository.
Specifications before code
OpenSpec is based on a very practical philosophy: fluid rather than rigid, iterative rather than sequential, easy rather than complex, and designed for existing projects, not just new repositories. That last point matters. Many AI-assisted development tools work very well in clean demos, but struggle when they enter a real product with years of decisions, legacy modules, internal conventions and partial changes.
The basic workflow starts with commands such as /opsx:explore and /opsx:propose. The first allows developers to explore an idea without commitment. For example, a developer can say: “I want to add dark mode, but I’m not sure what the cleanest approach is.” The assistant reviews the project, studies the styling setup and proposes a technical path. If the user accepts it, they can move on to /opsx:propose add-dark-mode.
From there, OpenSpec creates a change folder with several documents: proposal.md, to explain the reason and scope; specs/, with requirements and scenarios; design.md, with the technical approach; and tasks.md, with the implementation checklist. The agent can then apply the tasks with /opsx:apply and, once everything is complete, archive the change with /opsx:archive.
| Artefact | Purpose |
|---|---|
proposal.md | Explains why the change is being made and what it should achieve |
specs/ | Defines requirements, scenarios and expected behaviour |
design.md | Describes the technical approach before implementation |
tasks.md | Breaks the work into verifiable steps |
archive/ | Stores the completed change and updates the specifications |
This approach reduces one of the most common problems with coding agents: improvisation. AI can be very effective at writing, modifying or reviewing code, but it needs boundaries. OpenSpec tries to make those boundaries written, versioned and available both to the agent and to the team.
Designed for real projects, not just demos
One of the most interesting parts of OpenSpec is its focus on existing repositories. In a real project, the problem is rarely creating a function from scratch. More often, it is changing something without breaking the rest. There may be several packages, an API, a web app, a shared library and different teams with separate responsibilities.
For this kind of scenario, OpenSpec introduces the concept of stores, currently in beta. A store allows planning to live in a separate repository, with the same openspec/ structure, shared through Git across multiple teams and repositories. This becomes useful when a feature affects three different codebases, or when a platform team defines requirements that other teams consume in read-only mode.
The usual alternative is a mix of wiki pages, tickets, Slack threads, pull request comments and team memory. That model works until AI enters the workflow. An agent cannot easily read a decision lost in a meeting or a convention buried in an old page. If the specification lives in the repository, the agent can consult it and work with better context.
Here, OpenSpec connects with a broader trend in engineering: turning decisions into versioned artefacts. Just as infrastructure as code brought configuration into Git, development with agents needs requirements and plans to become machine-readable too.
The difference from working only with prompts
AI development without specifications depends too much on the initial prompt. If the user asks “add dark mode”, the model may choose a reasonable solution, but not necessarily the best one for that project. It may add an unnecessary dependency, ignore system preferences, duplicate styles or fail to account for accessibility.
With OpenSpec, the conversation moves before implementation. First, the idea is explored. Then a proposal is created. Then the artefacts are reviewed. Only after that does implementation begin. This does not turn the process into heavy bureaucracy, because the documents can be edited at any time and there are no closed phase gates like in a rigid methodology. The intention is to preserve the flexibility of chat, but with more reliable memory.
The project compares itself with other approaches. Against GitHub’s Spec Kit, it presents itself as lighter and less rigid. Against AWS Kiro, it highlights that it does not force developers into a specific IDE or limit them to particular models. Compared with using nothing, it offers a minimal layer so that the assistant does not depend only on a volatile conversation.
| Approach | Advantage | Limitation |
|---|---|---|
| Direct prompt | Fast and flexible | Little traceability and less predictable results |
| OpenSpec | Lightweight, editable and versioned plan | Requires minimal specification discipline |
| Spec Kit | More structured and complete | Can feel heavier |
| Kiro | Strong integration in its own environment | Greater dependence on a specific platform |
How it is installed and where it fits
OpenSpec requires Node.js 20.19.0 or higher. It can be installed globally with npm install -g @fission-ai/openspec@latest, and then initialised inside a project with openspec init. From that point on, the user can work with slash commands such as /opsx:explore or /opsx:propose.
The project says it works with more than 30 AI assistants through commands and profiles. It also recommends using high-reasoning models for planning and implementation, and keeping good context hygiene: clearing the window before starting implementation and avoiding old conversations that could contaminate the task.
That last recommendation is very realistic. Many coding agent failures do not happen because the model is incapable, but because it is working with dirty context, contradictory instructions or requirements that changed during the conversation. OpenSpec tries to anchor the important parts in files.
It makes sense for personal projects where a developer wants to keep order while working with an assistant, but also for teams that want more control over AI-assisted development. A change can be reviewed not only by looking at the final code, but also by reading the proposal, the specification and the tasks that led to it.
Why it matters for the new AI engineering workflow
Coding agents are entering a more mature phase. The question is no longer just whether they can write a function, but whether they can be integrated into the full cycle: understanding requirements, exploring solutions, planning changes, modifying repositories, running tests, opening pull requests and documenting decisions.
That shift requires more than powerful models. It requires processes that humans can review and machines can read. OpenSpec points directly at that intermediate layer between the chat and the repository.
The benefit is not writing more documents. It is preventing the specification from disappearing when the session closes. If another developer, another agent or the same team needs to understand tomorrow why a change was made, the artefacts are still there.
It also helps reduce the risk of AI implementing too much. A poorly scoped request can turn into excessive changes. With a proposal and a task list, the scope becomes clearer. And if the plan changes, it can be edited before code is written.
OpenSpec does not solve every problem in AI-assisted development. Human review, tests, architecture judgement, security, dependency control and good engineering practices are still required. But it does address an obvious gap: agents need to work with specifications that are more stable than a conversation.
AI-assisted programming is not just about generating code faster. It is about building systems where humans and models can share context, intent and limits. OpenSpec tries to make that coordination a natural part of the repository.
Frequently asked questions
What is OpenSpec?
It is an open source framework for spec-driven development with AI coding assistants.
What is it used for?
It helps define proposals, requirements, design and tasks before AI implements changes in a repository.
Does it replace tools like Claude Code or Codex?
No. OpenSpec integrates with AI assistants and adds a specification and workflow layer.
Is it only for new projects?
No. One of its strengths is that it is also designed for existing projects and repositories with history.
What are OpenSpec stores?
They are separate repositories used to plan changes and share specifications across multiple teams or codebases. They are currently in beta.