What It Does
OpenSpec is an open-source TypeScript CLI framework that adds a specification layer to AI-assisted development. Created by Fission AI (YC-backed), it organizes each proposed change into a dedicated folder containing a proposal, specs, design document, and task breakdown — all as markdown files stored in an openspec/ directory alongside the source code. AI coding assistants read these files as structured context before generating code, replacing ad-hoc prompting with documented intent.
The framework implements a three-phase workflow (Propose, Apply, Archive) via slash commands. Its primary differentiator is brownfield-first design: delta markers (ADDED/MODIFIED/REMOVED) track specification changes relative to existing functionality, making it purpose-built for iterating on existing codebases rather than only greenfield projects. OpenSpec produces lighter specification output (~250 lines per change vs ~800 lines from competitors like Spec Kit) to reduce review overhead.
Key Features
- Three-phase state machine workflow: Propose (create change proposal with specs, design, tasks), Apply (AI implements following the spec), Archive (merge changes into permanent specs)
- Delta markers (ADDED/MODIFIED/REMOVED) for tracking specification changes relative to existing system state, enabling brownfield iteration
- Filesystem-based storage: all specs are markdown files in
openspec/directory, version-controlled alongside source code - Slash commands (
/opsx:propose,/opsx:apply,/opsx:archive) for AI coding assistants with native support - AGENTS.md fallback for tools that don’t support native slash commands but can read markdown context files
- Profile-based workflow selection for different project types and team preferences
- Integration with 20+ AI coding tools: Claude Code, Cursor, Windsurf, GitHub Copilot, Amazon Q, Cline, RooCode, Trae, Continue, Gemini CLI, and more
- Optional MCP server (non-mandatory) for deeper AI tool integration
- Config-based context injection (
config.yaml) ensuring project conventions and tech stack are always present in planning requests - Anonymous telemetry (command names + version only), auto-disabled in CI, with opt-out via environment variables
Use Cases
- Brownfield feature development: Teams adding features to existing codebases who need change proposals that document what is being modified, not just what is being created. The delta marker system tracks modifications against the current system state.
- Cross-tool AI development teams: Organizations where different developers use different AI coding assistants (Cursor, Claude Code, Copilot) and need a shared specification format that works across all tools.
- Iterative small-to-medium changes: Projects where changes are frequent and incremental, benefiting from OpenSpec’s lighter output (~250 lines) rather than heavy-weight specification frameworks.
- Solo developers using AI assistants: Individual developers who want structured context for AI agents without the overhead of multi-persona frameworks like BMAD.
Adoption Level Analysis
Small teams (<20 engineers): Good fit. Low overhead to install (npm install -g @fission-ai/openspec && openspec init), no API keys required, no server infrastructure. The lightweight output and simple three-phase workflow add structure without excessive ceremony. Solo developers and small teams benefit from organized change tracking without process bloat. Node.js 20.19.0+ is the only requirement.
Medium orgs (20-200 engineers): Reasonable fit. The shared specification format helps coordinate AI-assisted development across team members. However, OpenSpec is file-based and single-repo — multi-repo changes require manual coordination. No built-in collaboration features; concurrent editing of the same change folder will cause merge conflicts. PR-based workflows are the recommended workaround.
Enterprise (200+ engineers): Poor fit currently. No multi-repository support, no SSO/SCIM, no access control, no audit logging beyond git history, no integration with enterprise tools (Jira, Confluence, ServiceNow). No multi-agent orchestration. Enterprise teams needing spec-driven development should evaluate Kiro (AWS) or Intent for governance features.
Alternatives
| Alternative | Key Difference | Prefer when… |
|---|---|---|
| BMAD Method | Full methodology with 6 agent personas, 3 complexity tracks, higher output volume | You need a comprehensive development methodology, not just a spec format |
| GitHub Spec Kit | GitHub-backed, four-phase workflow (specify/plan/tasks/implement), heavier output | You want GitHub ecosystem integration and more thorough specification |
| Kiro (AWS) | Full IDE with built-in SDD, AWS-native, living specs | Your team is AWS-native and wants SDD built into the IDE |
| Intent | Commercial living-spec platform with auto-sync between specs and code | You need specifications that stay synchronized with implementation automatically |
| Cursor Rules (.cursorrules) | Simple markdown rule files, no framework overhead | You only need project-level AI guidance, not change management |
Evidence & Sources
- GitHub Repository (37.4k stars, MIT)
- OpenSpec Official Documentation
- YC Launch: OpenSpec
- OpenSpec Deep Dive: SDD Architecture & Practice (redreamality)
- 6 Best Spec-Driven Development Tools (Augment Code)
- spec-compare: Research comparing 6 SDD tools (cameronsjo)
- Understanding SDD: Kiro, spec-kit, and Tessl (Martin Fowler / Bockeler)
- OpenSpec: A Spec-Driven Workflow for AI Coding Assistants (Medium)
Notes & Caveats
- Static specifications drift. Specs are not updated during implementation. On longer tasks, the proposal will diverge from what was actually built. Unlike Intent’s living specs, OpenSpec has no auto-synchronization. Teams must manually archive and update specs, which requires discipline.
- No codebase comprehension. The brownfield claim is about specification format (delta markers), not about understanding the existing codebase. OpenSpec has no codebase indexing or persistent architectural understanding — it relies entirely on whatever context the AI agent provides.
- Multi-repo limitation. OpenSpec lives in a single repository. Changes spanning multiple microservices require manual coordination of specs across repos.
- Integration quality varies. “Supports 20+ tools” ranges from native slash command support (first-class) to passive AGENTS.md reading (AI may or may not follow instructions). Tool quality differences are not well documented.
- Scope creep risk. Very large changes generating 2,000+ lines of spec and 50+ tasks indicate scope that is too broad. The framework works best for focused, atomic changes.
- Single-founder, early-stage company. Fission AI is a YC-backed startup with Tabish Bidiwale as the primary founder. While the MIT license mitigates vendor risk, ongoing maintenance depends on a small team. Community contribution depth is unclear.
- No independent productivity evidence. No controlled study demonstrates OpenSpec-specific productivity gains. The broader SDD category lacks rigorous evidence; the METR study found experienced developers were 19% slower with AI tools despite perceiving themselves as 20% faster. The “95% effective output rate” claim from affiliated content is unsubstantiated.
- GitHub star count context. The 37.4k stars in ~6 months is impressive but should be evaluated alongside GitHub star inflation trends and the YC marketing boost. npm download counts and active deployment numbers would be more meaningful adoption signals.