When using AI coding tools like Claude Code and Cursor, a common problem emerges: requirements live only in chat history, and the Agent writes code based on vague prompts, resulting in misaligned direction, repeated rewrites, and context windows exhausted by useless iterations.
OpenSpec (github.com/Fission-AI/OpenSpec) addresses this by introducing a lightweight spec layer for AI coding. It gets humans and AI to align on “what to build” before any code is written. The project has reached 43,956 stars, with growing npm downloads, making it the most popular spec-driven development framework on GitHub.
How It Works
OpenSpec’s philosophy: “fluid not rigid, iterative not waterfall” — it doesn’t pursue the cumbersome phase gates of traditional software engineering. Instead, it uses a flexible artifact system that lets specs evolve with the project.
Each feature change maps to a folder under openspec/changes/ containing four artifacts:
- proposal.md — why we’re doing this, what’s changing
- specs/ — requirements and acceptance scenarios
- design.md — technical implementation plan
- tasks.md — implementation checklist
The workflow is intuitive:
You: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
✓ proposal.md — why, what's changing
✓ specs/ — requirements and scenarios
✓ design.md — technical approach
✓ tasks.md — implementation checklist
Ready for implementation!
You: /opsx:apply
AI: Implementing tasks...
✓ 1.1 Add theme context provider
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.After implementation, /opsx:archive files the change away and automatically updates project specs. The entire flow stays within your coding tool.
Comparison with Alternatives
vs. GitHub Spec Kit — Spec Kit is thorough but heavyweight, requiring strict phase gates and Python. OpenSpec is lighter, runs on Node.js, and lets you iterate any artifact at any stage.
vs. AWS Kiro — Kiro is powerful but locks you into their IDE and Claude models. OpenSpec works with 25+ AI coding tools including Claude Code, Codex, Cursor, and Windsurf.
vs. No Specs — AI coding without specs means vague prompts and unpredictable results. OpenSpec adds predictability without ceremony.
Quick Start
# Install (requires Node.js 20.19.0+)
npm install -g @fission-ai/openspec@latest
# Navigate to project and initialize
cd your-project
openspec init
# Start with slash command
# In Claude Code / Codex / Cursor:
/opsx:propose <what-you-want-to-build>Also supports pnpm, yarn, bun, and nix. Disable telemetry: export OPENSPEC_TELEMETRY=0.
What to Watch
OpenSpec recently launched a new artifact-guided workflow (/opsx:propose → /opsx:apply → /opsx:archive), more structured than its initial slash commands. The project is actively maintained with multiple releases per week. The community recommends pairing it with high-reasoning models (Opus 4.5, GPT 5.2) for best results.