Most AI coding tools treat specifications as throwaway prompts. You describe what you want, the agent generates code, and the context evaporates. OpenSpec flips this: specifications become first-class artifacts that persist, evolve, and coordinate multi-turn workflows. The project (69K+ stars, #8 trending TypeScript on GitHub) introduces a spec-driven development workflow where agents propose, iterate, and archive specs as living documents rather than ephemeral instructions.
The architecture reveals how agents handle state across sessions, navigate brownfield codebases, and scale from personal projects to enterprise workflows without rigid waterfall processes.
The Artifact-Guided Workflow
OpenSpec introduces three core commands that treat specs as queryable state:
/opsx:propose: Agent generates a specification artifact from your idea/opsx:explore: Agent inspects existing code and suggests implementation paths/opsx:archive: Spec becomes a versioned artifact for reuse or reference
This is not a linear pipeline. You can explore before proposing, iterate on a spec without committing, or archive multiple versions. The key difference: the spec persists as a structured document the agent can query, diff, and reference across turns.
State Management Pattern
Traditional prompt-based agents maintain context in a conversation buffer. OpenSpec externalizes context into spec artifacts stored in .openspec/ directories. Each artifact includes:
- Structured metadata (scope, dependencies, constraints)
- Implementation plan (steps, files, risks)
- Versioning history (what changed, why)
The agent reads these artifacts on every turn, so it can resume work, compare alternatives, or explain past decisions without re-prompting.
Brownfield-First Design
OpenSpec is built for existing codebases, not just greenfield projects. The /opsx:explore command inspects your current architecture before proposing changes:
// Agent scans styling architecture
You: /opsx:explore
AI: Scanning your styling setup...
- CSS modules in use (12 components)
- No global theme system detected
- Tailwind config present but unused for theming
Cleanest path: CSS variables + theme context.
No new dependencies. Scope it?The agent identifies constraints (existing patterns, dependencies, file structure) and proposes solutions that fit. This requires deeper tool integration than greenfield generators: the agent must parse imports, detect conventions, and reason about side effects.
Context Boundaries
OpenSpec’s brownfield approach surfaces a critical trade-off: how much of the codebase should the agent scan? Too narrow and it misses dependencies. Too wide and context windows explode.
The project uses topic-based scoping: you declare areas of interest (authentication, styling, API layer), and the agent indexes only relevant files. Specs reference these topics, so future iterations stay bounded.
| Scope Strategy | Context Size | Accuracy | Use Case |
|---|---|---|---|
| Full codebase scan | Large (10K+ tokens) | High | Small projects, initial setup |
| Topic-based indexing | Medium (2-5K tokens) | High | Modular codebases, feature work |
| File-level hints | Small (<1K tokens) | Medium | Targeted refactors, bug fixes |
| Manual boundaries | Variable | Highest | Complex migrations, security work |
Specifications as Queryable Artifacts
The core insight: if specs are files, you can version, diff, search, and reuse them. OpenSpec stores specs in .openspec/specs/ as Markdown with YAML frontmatter:
---
id: add-dark-mode
status: proposed
scope: [styling, theme]
dependencies: []
created: 2026-09-15
---
# Dark Mode Implementation
## Approach
CSS variables + React context for theme state.
System preference detection via `prefers-color-scheme`.
## Files Affected
- src/styles/theme.css (new)
- src/context/ThemeContext.tsx (new)
- src/App.tsx (modify)
## Risks
- Flash of unstyled content on initial load
- Need to persist user preference (localStorage)The agent can now:
- Compare multiple specs for the same feature
- Reference archived specs when similar work arises
- Generate diffs between proposed and implemented state
- Build a knowledge base of past decisions
This turns specs into a form of institutional memory. When a new developer (or agent) joins, they can query .openspec/ to understand why certain patterns exist.
Observability and Debugging
Because specs are files, you get observability for free:
- Git history shows when specs were proposed, modified, or archived
- Diffs reveal what changed between iterations
- Search finds all specs touching a particular module or dependency
When an agent makes a bad decision, you can trace it back to the spec. Did the agent misunderstand the scope? Did it ignore a constraint? The spec artifact is the audit log.
Failure Modes
OpenSpec’s artifact-driven approach introduces new failure surfaces:
- Stale specs: Archived specs may reference deleted code or outdated patterns
- Scope drift: Agents may expand scope mid-implementation if constraints are vague (for example, proposing authentication changes when only styling was requested)
- Artifact bloat:
.openspec/can accumulate hundreds of specs over time - Merge conflicts: Multiple agents or developers proposing specs simultaneously
The project mitigates these with status flags (proposed, active, archived, deprecated) and a cleanup command that prunes stale artifacts. But you still need discipline: treat .openspec/ like any other source directory.
Deployment Shape
OpenSpec is a TypeScript library, not a hosted service. You install it via npm and integrate it with your existing AI coding assistant (Cursor, Copilot, Cody, etc.):
npm install @fission-ai/openspecThe library provides:
- Command handlers for
/opsx:*workflows - Spec parser and validator
- Context indexer for brownfield codebases
- Artifact storage and retrieval
You configure it with a .openspec.config.js file that defines topics, scope boundaries, and storage paths. The agent calls OpenSpec functions during conversation turns, but the orchestration logic lives in your assistant’s runtime.
Integration Points
OpenSpec assumes your agent can:
- Execute file system operations (read, write, list)
- Parse code (AST analysis for dependency detection)
- Maintain conversation state (to track active specs)
If your agent lacks these capabilities, you’ll need to build adapters. The project includes examples for Cursor and Copilot, but custom assistants require custom glue.
Security Boundaries
Specs are code. If an agent can write to .openspec/, it can inject malicious instructions into future workflows. OpenSpec does not sandbox spec execution, so you need external controls:
- Review specs before archiving: Treat
/opsx:archivelike a pull request - Restrict file system access: Limit agent writes to
.openspec/only - Audit spec content: Scan for suspicious patterns (shell commands, network calls)
The project recommends running OpenSpec in environments where agents already have code write access (local dev machines, CI runners). Do not expose it in production or multi-tenant systems without additional isolation.
When to Use OpenSpec
Good fit:
- Multi-turn coding workflows where context needs to persist across sessions
- Brownfield projects where agents must understand existing patterns
- Teams that want a shared knowledge base of implementation decisions
- Projects where specs are living documents, not one-time prompts
Poor fit:
- One-shot code generation tasks (no need for artifact overhead)
- Greenfield projects with no existing constraints (simpler tools suffice)
- Environments where agents cannot write files (hosted playgrounds, sandboxes)
- Teams that prefer verbal iteration over written specs
Technical Verdict
OpenSpec solves a real problem: most AI coding tools lose context between sessions, forcing you to re-explain constraints every time. By treating specs as queryable artifacts, OpenSpec gives agents institutional memory. The brownfield-first design and topic-based scoping show maturity beyond typical greenfield generators.
The trade-off: you now manage a .openspec/ directory that can bloat, go stale, or conflict. If your workflow already involves written specs (PRDs, ADRs, design docs), OpenSpec fits naturally. If you prefer verbal iteration, the artifact overhead may feel heavy.
Use it when you need agents to remember past decisions and coordinate across multiple turns. Skip it for throwaway scripts or one-shot tasks where context does not matter.