OpenSpec Guide: Lightweight Spec-Driven Development with Delta Specs
OpenSpec is the lightweight spec-driven development engine: four commands, delta specs, and a brownfield-first philosophy. Setup, workflow, and when to pick it over Spec Kit.
Independent article: published by AI Coding Tools, not official vendor documentation.
OpenSpec Guide: Lightweight Spec-Driven Development with Delta Specs
OpenSpec is the "fluid not rigid" entry in the spec-driven development ecosystem. Built by Fission AI, MIT-licensed, and sitting at ~55k GitHub stars by mid-2026, it's the project that made spec-driven coding approachable: no constitution, no clarification phase, no phase gates. Just four commands and a clever idea — delta specs — and it's installed in minutes on an existing codebase.
Where GitHub Spec Kit is the heavy, standardizing workflow, OpenSpec is the opposite philosophy: "fluid not rigid, iterative not waterfall, easy not complex, brownfield-first." It's the fastest on-ramp to spec-driven coding for teams that would bounce off Spec Kit's ceremony.
Installation and setup
npm install -g @fission-ai/openspec
That's it. No API keys, no MCP server, no configuration file to write. Run /opsx:init (or openspec init) in your existing project and it creates an openspec/ directory with a spec store. Setup is claimed at five minutes on a brownfield codebase — the project's design goal.
The four commands
The whole workflow is four slash commands, designed to loop freely rather than march through gates:
| Command | What it does |
|---|---|
| /opsx:propose | Creates a change folder for a new feature |
| /opsx:explore | Iterates on the spec and design in that folder |
| /opsx:apply | Executes the approved implementation |
| /opsx:archive | Archives the completed change |
You can bounce between propose and explore as many times as you like. There's no "you must finish planning before you may implement" enforcement — if you want to sketch and build, you sketch and build. The structure exists to keep the history and the requirements honest, not to police you.
The key idea: delta specs
OpenSpec's innovation is that every change produces a diff against the existing specs — ADDED, MODIFIED, REMOVED — rather than a new standalone document. Why this matters:
- A reviewer sees what changed in the requirements before a single line of code exists.
- Specs accumulate as living documentation in
openspec/specs/, organized by capability, so the repo itself carries the project's requirements history. - The delta format is validated by a Zod schema, and the CLI does compiler-level conflict detection: two changes to the same spec conflict at proposal time, not at merge time.
In practice this means the spec store behaves like a miniature type system for requirements — and that's a genuinely different model from Spec Kit's linear branch-per-feature spec files.
The OpenSpec workflow in practice
1. Propose
/opsx:propose creates a change folder — a proposal with a spec file, a task list, and a design document. The agent reads your intent, checks the existing spec store, and writes a delta: what this change adds, modifies, or removes in the project's capabilities.
2. Explore
This is the iteration loop: refine the spec, argue with the design, add acceptance criteria. The agent can re-read the whole spec store and check your change against related capabilities. Because specs are deltas, the "spec" of the whole project is always the accumulated result — you never maintain one giant document by hand.
3. Apply
The implementation phase. The agent executes the tasks against the locked spec. OpenSpec enforces a 50KB context budget to prevent prompt bloat — if the spec store outgrows the budget, the tool tells you rather than letting the agent silently work from a truncated view.
4. Archive
The change is archived — closed out with its spec delta and task record intact, so the project's requirements history stays complete without accumulating clutter.
Where OpenSpec fits
Choose OpenSpec when:
- You're on an existing (brownfield) codebase and want SDD without a migration project.
- You want the lightest possible ceremony — four commands, no constitution, no gates.
- You work across many AI tools: OpenSpec supports 20+ coding agents, among the widest coverage in the ecosystem.
- Your team's failure mode is "agents drift from requirements," not "agents write sloppy code."
Skip OpenSpec when:
- You need enforcement: no adversarial review, no strict gates, no institutional memory between sessions. Spec quality depends entirely on developer discipline.
- You're in a regulated/enterprise environment that wants mandated checkpoints. Spec Kit and SpecD bring the governance.
- You want execution discipline built in — pair OpenSpec with Superpowers or a fusion project for that.
OpenSpec vs Spec Kit
| | OpenSpec | GitHub Spec Kit |
|---|---|---|
| Philosophy | Fluid, iterative, change-based | Rigid, gated, spec-as-truth |
| Commands | 4 (propose/explore/apply/archive) | 9 (constitution/specify/clarify/plan/...) |
| Spec format | Delta specs (ADDED/MODIFIED/REMOVED) | Full spec files per feature branch |
| Constitution | None | Semantically versioned rulebook |
| Setup time | ~5 minutes | ~30+ minutes incl. constitution |
| Best for | Brownfield, rapid iteration | Teams standardizing on one workflow |
The deeper discussion is in our Spec Kit vs OpenSpec vs BMad comparison.
The fusion trend
OpenSpec's planning model is so popular that 2026's hottest niche is projects that fuse it with execution discipline: spec-superflow and superspec combine OpenSpec's spec store with Superpowers' TDD and review gates, closing the "planning-execution gap" that critics blame for most AI-generated PR failures.
Getting started
npm install -g @fission-ai/openspec
# cd into your existing project
# run /opsx:init, then /opsx:propose for your next real feature
Pick a real feature, write its delta spec, apply it, and see the difference vs. your old prompting loop. For the broader picture of why specs beat prompts, start with the complete spec-driven coding guide or the spec-driven vs vibe coding comparison.