OpenSpec (52,863 stars, #11 on GitHub Trending) shifts AI coding assistants from reactive code completion to proactive planning agents. Instead of generating code directly from prompts, it generates structured specification artifacts (proposals, specs, design docs, task lists) that persist in version control. The AI assistant becomes a workflow engine that operates on these artifacts, maintaining project memory and architectural context across sessions.
The core insight: ephemeral prompts are a terrible coordination layer for multi-session development. OpenSpec replaces them with a durable, version-controlled knowledge base stored in openspec/changes/.
The Artifact-Guided Workflow
OpenSpec introduces two primary commands that bracket the specification-to-code lifecycle:
/opsx:propose "your idea"
Generates a change directory containing:
proposal.md: rationale, scope, and impact analysisspecs/: requirements, acceptance criteria, edge casesdesign.md: technical approach, architecture decisions, trade-offstasks.md: implementation checklist with dependencies
/opsx:apply
Executes the task list, writing code against the specification artifacts. The AI can reference the design doc for architectural constraints and the specs for validation logic.
This two-phase workflow creates a natural checkpoint. You review the specification artifacts before any code changes. If the AI misunderstood your intent, you iterate on the specs, not the code.
State Management and Conflict Resolution
Each change lives in its own directory under openspec/changes/. This isolation prevents specification conflicts when multiple features are in flight. The directory structure looks like:
openspec/
changes/
add-dark-mode/
proposal.md
specs/
requirements.md
scenarios.md
design.md
tasks.md
api-rate-limiting/
proposal.md
specs/
design.md
tasks.mdWhen you run /opsx:apply, the AI reads the task list and executes items sequentially. If a task fails (tests break, linter errors, merge conflicts), the workflow halts. You can:
- Fix the issue manually and resume
- Regenerate the task list with updated constraints
- Roll back to the last passing task
The artifact directory becomes the source of truth for rollback. You can revert code changes but keep the specification artifacts, then re-apply with different implementation choices.
Integration with Version Control
OpenSpec artifacts are plain Markdown files, so they integrate naturally with Git workflows:
- Feature branches: Create a branch, run
/opsx:propose, commit the artifacts, open a PR for spec review before implementation - Blame and history:
git log openspec/changes/add-dark-mode/design.mdshows the evolution of architectural decisions - CI validation: Run linters or custom validators against spec files to enforce documentation standards
The key difference from traditional docs-as-code: these artifacts are not documentation of existing code. They are the input to code generation. The AI assistant reads them during /opsx:apply to maintain consistency.
Observability and Debugging
When an AI assistant generates incorrect code, the failure mode is usually invisible. You see bad output but not the reasoning chain that produced it. OpenSpec externalizes that reasoning into the specification artifacts.
If the AI generates a bug, you can trace it back:
- Check
tasks.mdto see which task introduced the bug - Review
design.mdto see if the architectural approach was flawed - Update the spec and regenerate the task list
This creates an audit trail. You can see not just what the AI did, but what it was supposed to do according to the specs.
Deployment Shape
OpenSpec is a TypeScript package that integrates with AI coding assistants (Cursor, GitHub Copilot, Windsurf, etc.). It does not run as a separate service. The workflow commands (/opsx:propose, /opsx:apply) are custom instructions that you add to your AI assistant’s configuration.
Installation:
npm install @fission-ai/openspec
npx openspec initThis creates the openspec/ directory structure and adds configuration files. You then configure your AI assistant to recognize the /opsx:* commands and read from the artifact directories.
The lightweight deployment model means no additional infrastructure. The artifacts live in your repo, and the AI assistant reads them during normal coding sessions.
Failure Modes and Mitigation
| Failure Mode | Impact | Mitigation |
|---|---|---|
| AI generates incorrect specs | Entire change is based on wrong assumptions | Review artifacts before /opsx:apply, iterate on specs |
| Task dependencies are wrong | Later tasks fail because earlier tasks didn’t create expected state | Explicit dependency declarations in tasks.md, halt on first failure |
| Specification drift | Specs become outdated as code evolves | Treat specs as living documents, update during refactoring |
| Merge conflicts in artifact directories | Multiple developers propose overlapping changes | Use feature branches, merge artifacts before code |
| AI ignores specs during implementation | Generated code doesn’t match design doc | Validate code against specs in CI, regenerate with stricter prompts |
The biggest risk is treating the artifacts as write-only. If you generate specs but never reference them during code review or debugging, you lose the coordination benefits. The workflow only works if the specs remain the authoritative source of intent.
Brownfield vs. Greenfield
OpenSpec positions itself as “built for brownfield not just greenfield.” The artifact workflow shines when:
- You need to explain existing architecture to an AI assistant
- You want to document why a change was made (not just what changed)
- Multiple developers (or AI sessions) need shared context
For greenfield projects, the overhead of generating specs before code might feel heavy. But even small projects benefit from the checkpoint: you catch misunderstandings before they become code.
For brownfield projects, the artifacts become a knowledge base. New team members (human or AI) can read openspec/changes/ to understand the evolution of the system.
Technical Verdict
Use OpenSpec when:
- You work on multi-session projects where AI assistants lose context between conversations
- You need an audit trail of architectural decisions
- You want to review AI-generated plans before code changes
- You integrate AI coding into team workflows with code review
Avoid OpenSpec when:
- You write throwaway scripts or one-off automation (the spec overhead isn’t worth it)
- Your AI assistant already has strong project context (e.g., you use a tool with persistent memory)
- You prefer visual workflow builders over Markdown artifacts
- Your team doesn’t use version control or code review
The artifact-guided workflow is most valuable when the cost of an incorrect code change is high. If you can afford to let the AI generate code and fix it iteratively, skip the specs. If you need to understand the plan before execution, OpenSpec provides the coordination layer.