README

The most loved spec framework.







Our philosophy:

text
→ fluid not rigid
→ iterative not waterfall
→ easy not complex
→ built for brownfield not just greenfield
→ scalable from personal projects to enterprises



  Follow @0xTab on X for updates · Join the OpenSpec Discord for help and questions.




 See it in action

text
You: /opsx:explore
AI:  What would you like to explore?
You: I want dark mode but I'm not sure how to do it cleanly.
AI:  Let me look at your styling setup...
     Cleanest path here: CSS variables + a small theme context,
     with system-preference detection. No new dependencies. Scope it?
You: Yes, let's do it.

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
     Ready for implementation!

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.



What do the specs actually look like?

Plain Markdown — requirements with concrete scenarios, no special syntax to learn. Here's what goes in the specs/ folder created above:

markdown
 ADDED Requirements

 Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

 Scenario: User toggles dark mode
- WHEN the user clicks the theme toggle
- THEN the app switches to dark mode and persists the choice


Your AI writes these; you review the plan before any code is written.

OpenSpec is built with OpenSpec — browse this repo's live specs and in-flight changes for real examples at scale.




OpenSpec Dashboard


  




 Why teams adopt OpenSpec

Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the hard part moves: a feature spans the API server, the web app, and a shared library; requirements are owned by one team and consumed by others; planning starts before any code exists.

Stores are the answer — planning in a repo of its own. The same openspec/ shape you already know (specs and changes), shared by git push like anything else. One source of truth your whole team and every coding agent can read, across every repo.

- Cross-repo features — one change, one plan, even when the code lands in three repos.
- Shared requirements — a platform team owns the specs; product teams reference them read-only, right where their coding agent can read them. No drifting wiki.
- Plan before code — capture the plan in the store now; the code repos catch up later.

 Stores are in beta. Start with the Stores guide.

 Quick Start

Install OpenSpec. On macOS or Linux, in your terminal:

bash
curl -fsSL https://

Top issues

Discussions

Latest release

What's New in v1.16.1

A patch release that makes spec validation stricter and more forgiving in the right places, and makes openspec version --check reliable.

 Fixed

- Closed section headings - validate, show, list, view and archive now read headings with a closing  run ( Purpose ,  ADDED Requirements ) the same as their unclosed forms.
- Unrecognized delta sections - validate now fails, and archive refuses, when a delta spec puts a requirement under an unrecognized section such as  DEPRECATED Requirements, instead of passing with a warning and silently dropping that requirement.
- Version