If you have spent any time doing AI-assisted development or vibe coding, you already know the problem.
- You open a new chat.
- Start building something.
- The AI just runs with it.
No alignment, no scope, no shared understanding of what you are actually trying to do.
That works fine for small throwaway tasks. But when you are working on a real codebase, things go sideways fast.
The AI makes assumptions. Scope creeps. You end up with code that technically works but does not match what you had in mind.
OpenSpec fixes this by introducing one simple idea
agree on what you are building before any code gets written.
It gives you and your AI coding assistant a lightweight structure to follow for every change you make. Before implementation starts, you define the intent, the scope, and the approach. The AI reads that and works within those boundaries instead of guessing.
The result is more predictable output, less back and forth, and something that matters a lot in fast-paced development ~ the reasoning behind your decisions is actually preserved instead of disappearing into chat history.
What is OpenSpec?
OpenSpec is a spec-driven development framework. It sits between you and your AI coding assistant as a lightweight planning layer.
The idea is simple. Before your AI writes a single line of code, you and the AI agree on a spec. What you are building, why you are building it, how you are going to build it, and what is out of scope. Everything is written down and locked in before implementation starts.
It works with the tools you already use ~ Claude Code, Cursor, Codex, Copilot, Antigravity and more. No API keys, no complex setup. Your specs live right inside your repository as markdown files.
Every change you make in OpenSpec goes through four artifacts:
- Proposal ~ the why. What you want to build and why it matters
- Specs ~ the what. The requirements and expected behavior
- Design ~ the how. The technical approach and decisions
- Tasks ~ the steps. Broken down implementation plan
Installation and Setup
Prerequisites
Node.js 20.19.0 or higher
Install
npm install -g @fission-ai/openspec@latest
Initialize
cd <your-project>
openspec init
Once initialized, it will ask you to select which AI tools you want to set up. OpenSpec supports 28 tools including Claude Code, Cursor, Codex, Copilot and more. Use Space to toggle and Enter to confirm.
After selecting your tools, OpenSpec sets everything up automatically ~ agent skills, slash commands, and config files for each tool you selected.
Once setup is complete, restart your IDE for the slash commands to take effect. Then you are ready to start your first change with /opsx:propose <what-you-want-to-build>
The Four Artifacts
Every change in OpenSpec progresses through four artifacts.
Each artifact builds on the previous one, ensuring implementation starts only after the change is fully understood.
1. Proposal
The Why
The proposal captures the intent behind the change.
Questions answered here:
- Why are we doing this?
- What problem are we solving?
- What value does this provide?
This is where intent gets locked in.
2. Specs
The What
Specs define the requirements and expected behavior.
Questions answered here:
- What should happen?
- What should the system do?
- How should it behave?
These become the source of truth during implementation.
3. Design
The How
Design documents describe the technical approach.
Questions answered here:
- Which architecture should we use?
- What tradeoffs are involved?
- What technical decisions need to be made?
This phase often prevents expensive mistakes before they reach production.
4. Tasks
The Steps
Tasks break the implementation into manageable pieces.
Questions answered here:
- What needs to be done?
- In what order?
- How do we know we're finished?
This becomes the execution plan for both humans and AI agents.
Your First Change
Let's walk through a real example. We are going to add a new User Profile API endpoint using OpenSpec from start to finish.
Step 1: Start the Change
Run the propose command in your AI coding assistant:
/opsx:propose "add-user-profile-api-endpoint"
Your AI will generate all four artifact files automatically:
Created openspec/changes/add-user-profile-api-endpoint/
✓ proposal.md — why we're doing this, what's changing
✓ specs/ — requirements and scenarios
✓ design.md — technical approach
✓ tasks.md — implementation checklist
Ready for implementation!
Here is what each artifact looks like:
proposal.md
# Proposal: Add User Profile API Endpoint
## Intent
Users need a way to retrieve and update their profile information
through a dedicated API endpoint.
## Scope
- GET /api/users/:id endpoint
- PUT /api/users/:id endpoint
- Input validation and error handling
## Approach
Use existing REST conventions with JWT authentication middleware.
specs/api/spec.md
# Delta for API
## ADDED Requirements
### Requirement: User Profile Retrieval
The system MUST expose a GET endpoint to retrieve user profile data.
#### Scenario: Fetch profile
- GIVEN an authenticated user
- WHEN GET /api/users/:id is called
- THEN the user profile is returned
design.md
# Design: Add User Profile API Endpoint
## Approach
- Use Express router for route handling
- JWT middleware for authentication
- Joi for input validation
- Return 404 if user not found
tasks.md
# Tasks
## 1. Route Setup
- [ ] 1.1 Create user profile route file
- [ ] 1.2 Register route in main router
## 2. Handlers
- [ ] 2.1 Implement GET /api/users/:id handler
- [ ] 2.2 Implement PUT /api/users/:id handler
## 3. Validation and Error Handling
- [ ] 3.1 Add input validation
- [ ] 3.2 Add error handling middleware
Step 2: Implement
Once you are happy with all the artifacts, run:
/opsx:apply
Your AI now works through the tasks one by one following the spec exactly:
Working through tasks...
✓ 1.1 Created user profile route file
✓ 1.2 Registered route in main router
✓ 2.1 Implemented GET /api/users/:id handler
✓ 2.2 Implemented PUT /api/users/:id handler
✓ 3.1 Added input validation
✓ 3.2 Added error handling middleware
All tasks complete!
No guessing, no assumptions, no scope creep. Your AI follows the spec and nothing else.
Step 3: Archive
Once everything is verified, run:
/opsx:archive
This closes the change completely. It merges your delta specs into the main specs folder and moves the change to the archive permanently.
Archiving add-user-profile-api-endpoint...
✓ Merged specs into openspec/specs/api/spec.md
✓ Moved to openspec/changes/archive/2025-01-24-add-user-profile-api-endpoint/
Done! Ready for the next feature.
The reasoning behind every decision is now preserved in your repository forever. Next time anyone touches this code ~ including an AI agent ~ the why is already there.
Tips from Real Usage
After using OpenSpec for a few months in fast paced AI driven development, here are a few things I have learned.
Always review the proposal before moving on
The proposal is where intent gets locked in. If something is off there, it carries through to every other artifact. Spend an extra minute here and save yourself a lot of back and forth later.
Be specific with your scope
The more specific you are about what is out of scope, the better your AI performs. Writing "out of scope: custom error pages" is more useful than leaving it vague. AI agents take boundaries seriously when they are written down.
Do not skip the design artifact
It is tempting to jump straight to implementation. But the design phase is where you catch bad technical decisions before they become bad code. Many times the design phase alone has saved me from going down the wrong path.
Use it on existing codebases
OpenSpec is brownfield first. You do not need a fresh project to get value from it. Drop it into an existing codebase and start using it for your next change. The value shows up immediately.
Your specs are living documentation
Every time you archive a change, your specs folder gets more complete. Over time it becomes a genuine source of truth for how your system works and why decisions were made. That is valuable for your whole team, not just for AI agents.
Conclusion
AI coding assistants are powerful. But power without direction is just noise.
OpenSpec is not about slowing down. It is about making sure that when you move fast, you are moving in the right direction. In vibe coding and fast paced AI driven development, the biggest risk is not writing bad code. It is building the wrong thing confidently.
After using OpenSpec for a few months, the biggest shift I noticed was not in the code quality. It was in how much context was being preserved. The why behind decisions no longer lives in chat history or someone's head. It lives in the repository, right next to the code it describes.
If you are doing any kind of AI assisted development and you are not using a spec driven approach, give OpenSpec a try. It takes five minutes to set up and the value shows up on your very first change.
Start with:
/opsx:propose "your-first-change"
And see what happens.
Top comments (0)