OpenSpec: The Complete Guide to Spec-Driven Development for AI Coding Assistants
OpenSpec brings spec-driven development (SDD) to AI coding assistants. Agree on what to build before code is written — with proposals, specs, designs, and task checklists via slash commands. Works with 20+ AI tools. 28,800+ stars, TypeScript, MIT.
What Is OpenSpec?
A lightweight spec layer that sits between you and your AI coding assistant. Instead of vague prompts that produce unpredictable results, OpenSpec structures every change as a proposal → specs → design → tasks workflow. Each change gets its own folder. Human and AI align on what to build before any code is written.
- Language: TypeScript
- License: MIT
- Stars: 28,800+ ⭐
- Forks: 1,895
- Releases: 34
- Contributors: 50
- Homepage: openspec.dev
The SDD Workflow
You: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
✓ proposal.md — why we're doing this, what's changing
✓ specs/ — requirements and scenarios
✓ design.md — technical approach
✓ tasks.md — implementation checklist
You: /opsx:apply
AI: Implementing tasks...
✓ 1.1 Add theme context provider
✓ 1.2 Create toggle component
✓ 2.1 Add CSS variables
✓ 2.2 Wire up localStorage
All tasks complete!
You: /opsx:archive
AI: Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
Specs updated. Ready for the next feature.
Core Concepts
Change Folders
Each change gets its own folder with standardized artifacts:
| Artifact | Purpose |
|---|---|
| proposal.md | Why and what — justification and scope |
| specs/ | Requirements and scenarios |
| design.md | Technical approach |
| tasks.md | Implementation checklist |
Slash Commands (Core)
| Command | Purpose |
|---|---|
/opsx:propose | Create a new change proposal |
/opsx:apply | Implement tasks from the spec |
/opsx:archive | Archive completed changes |
Slash Commands (Expanded Workflow)
| Command | Purpose |
|---|---|
/opsx:new | Start a new change |
/opsx:continue | Resume in-progress work |
/opsx:ff | Fast-forward through tasks |
/opsx:verify | Verify implementation |
/opsx:sync | Sync specs with code |
/opsx:bulk-archive | Archive multiple changes |
/opsx:onboard | Onboard to a project |
Core Features
1. Agree Before You Build
Human and AI align on specs before code gets written. No more vague prompts.
2. Organized Change Management
Each change gets its own folder with proposal, specs, design, and tasks.
3. Fluid Workflow
Update any artifact anytime — no rigid phase gates.
4. 20+ AI Tools Supported
Works with Claude Code, Codex, Cursor, Windsurf, and 20+ more AI assistants via slash commands.
5. Multi-Language Support
Specs in your language of choice.
6. Profiles & Customization
Configure workflows with openspec config profile. Choose between core and expanded workflows.
7. CLI & npm
npm install -g @fission-ai/openspec@latest
cd your-project
openspec init
Also works with pnpm, yarn, bun, and nix.
OpenSpec vs Alternatives
Category: This is a spec-driven development framework for AI coding.
| Feature | OpenSpec | Spec Kit (GitHub) | Kiro (AWS) | No Specs |
|---|---|---|---|---|
| Focus | SDD for AI coding | Spec framework | Spec IDE | — |
| Stars | 28.8K ⭐ | ~5K ⭐ | Closed source | — |
| Weight | Lightweight | Heavyweight | Full IDE | None |
| Phase Gates | ❌ Fluid | ✅ Rigid | ✅ Rigid | ❌ |
| AI Tools | 20+ | Manual | Claude only | Any |
| IDE Lock-in | ❌ Any tool | ❌ | ✅ Locked | ❌ |
| Slash Commands | ✅ /opsx: | ❌ | Proprietary | ❌ |
| Change Folders | ✅ Standardized | ✅ | ✅ | ❌ |
| Profiles | ✅ | ❌ | ❌ | ❌ |
| Multi-Language | ✅ | ❌ | ❌ | ❌ |
| npm Install | ✅ One command | Python setup | IDE install | — |
| Predictability | ✅ High | ✅ High | ✅ High | ❌ Low |
When to choose OpenSpec: You want lightweight spec-driven development with any AI tool — agree on specs before coding, with fluid iteration.
When to choose Spec Kit: You want a comprehensive spec framework from GitHub with rigid phase gates and don't mind the heavyweight setup.
When to choose Kiro: You're OK being locked into one IDE and Claude models for a fully integrated spec experience.
Conclusion
OpenSpec solves the fundamental problem of AI coding: vague prompts produce unpredictable results. By adding a lightweight spec layer — propose, align, implement, archive — it brings predictability without ceremony. With 28.8K stars, 20+ tool support, slash commands, multi-language, and customizable profiles, it's the leading spec-driven development framework for AI coding.