OpenSpec – A lightweight and configurable AI spec framework | AI Paper Digest

TL;DR Highlight

OpenSpec has agents write specs first, then implement and verify; reactions are split

Who Should Read

Developers building large features with coding agents like Claude Code or Codex who struggle with scattered requirements

Core Mechanics

A framework that centers on specs
- OpenSpec captures what you want to build in a spec to keep your team and coding agents aligned.
- It aims to refine requirements, validate them, and verify the implementation matches.
Five slash-command workflow
- /opsx:explore maps the problem and codebase.
- /opsx:propose drafts proposal.md, specs/, design.md, tasks.md.
- /opsx:apply implements, /opsx:verify checks against the spec, /opsx:archive archives finished changes.
Install with one npm line
- Run npm install -g @fission-ai/openspec@latest.
- npm, pnpm, bun, yarn, and nix are listed.
Works with many agent tools
- Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode are on the compatibility list.
- The page says 33 more tools are supported.

Community Reactions

Specs rot, and code is the real spec
- One commenter used OpenSpec on two large solo projects over 6-9 months.
- An LLM check in both directions showed huge divergence between specs and code, so they dropped the specs.
- They kept the proposal-review-implement-review flow, ADRs, and invariant logs.
Too many documents to review
- A commenter whose org adopted it says every medium or larger change produces many AI-written markdown files.
- They find a small human-written spec more effective.
- Others also asked how to verify so many files reflect the requirement.
Positive experiences and alternatives
- One commenter said it scored well in internal evals and has sane ceremony.
- Another used it in an agent fleet planner and found it lighter than SpecKit.
- A comment says GSD uses about 4x the tokens but buys traceability.
Doubts about need and demands for evidence
- Some say modern tools like Codex or Claude Code make it unnecessary.

How to Apply

Run propose on one small feature
- Install it today and run /opsx:propose on a small feature.
- Read proposal.md and tasks.md and check them against your requirements.
Measure spec drift with verify
- After /opsx:apply, run /opsx:verify.
- Record how many items diverge to see how fast specs go stale.
Split process by change size
- Skip specs for 10-line fixes and use the agent's native plan feature.
- Use the proposal flow only for large features.
Trim generated specs before merging
- Cut generated spec files down to core requirements before merge.
- Agree with your team on a cap for files to review.

Try It

copy & run

# Run in a terminal for Claude Code (project root, after install)

npm install -g @fission-ai/openspec@latest

# Type these slash commands in order inside Claude Code
/opsx:explore
/opsx:propose {{describe the feature}}

# Read and edit proposal.md, specs/, design.md, tasks.md, then
/opsx:apply
/opsx:verify

# Next: archive with /opsx:archive and record how many mismatches verify found

Terminology

SDD (Spec-Driven Development)Writing a spec first and implementing against it instead of coding first. Like drawing blueprints before building.

Spec driftSpecs fall out of date as code changes, so the two diverge. Like a map that no longer matches the roads.

ADRArchitecture Decision Record, a short note on why a design decision was made. A diary of decisions.

HarnessThe runtime wrapper around an LLM agent that manages tool calls and workflow.

OpenSpec – A lightweight and configurable AI spec framework