OpenSpec gives AI-assisted development a repository-owned description of what should change and how you will judge it. Instead of letting an implementation conversation become the only record of a feature, you maintain explicit requirements, scenarios, design decisions and tasks alongside the code.
It is not another coding model and does not turn an agent’s self-review into proof. Its useful role is coordination: the human and the coding assistant can inspect the same change boundary before implementation, during a handoff, and before merging.
This guide is based on the project’s documentation, not a claim that we have tested every integration. See the official site and repository for current commands and supported tools.
When a specification workflow helps
The strongest use case is a change that crosses several files or behavior boundaries. Examples include adding an approval gate to an AI agent, changing a model-provider fallback policy, or introducing a streaming endpoint with explicit cancellation behavior. Those changes need agreement about outcomes before an assistant starts editing.
For a typo or an isolated copy change, the additional artifacts may cost more than they help. Keep the process proportional. OpenSpec should reduce ambiguity, not replace a small clear task with an elaborate planning ritual.
Our Coding Agents foundation provides the wider context: scope, permissions, review and accountable human ownership remain necessary even when a planning tool organizes the work.
Install and initialize in the right repository
The current README requires Node.js 20.19.0 or later and documents:
npm install -g @fission-ai/openspec@latest
cd your-project
openspec initCheck your Node version and the package source before installation. Initialize from the intended project root, not an arbitrary parent containing several repositories. Review generated integration files before committing them. Some teams will prefer a pinned, reviewed tool version to an automatic latest-version workflow.
openspec init asks which coding tools you use and prints the matching invocation forms. That matters because the same conceptual workflow does not imply identical slash commands in every assistant.
For assistant setup, use our Claude Code guide, Codex CLI guide and Claude Code versus Cursor comparison. OpenSpec adds a shared planning layer; it does not erase their differences in permissions or execution environments.
The four artifacts
| Artifact | Purpose | Human review question |
|---|---|---|
proposal.md | Why this change exists and its boundary | Are we solving the right problem? |
specs/ | Requirements and observable scenarios | Could someone test these outcomes? |
design.md | Technical approach and tradeoffs | Is the implementation safe and maintainable? |
tasks.md | Work checklist | Does the plan cover failures and validation? |
The documented change directory is openspec/changes/<change-name>/. These are repository artifacts, not hidden reasoning belonging to one assistant. Treat them as reviewable project input: they can be wrong, stale or overbroad just like a code diff.
Explore before proposing
The explore stage is useful when you need to understand existing architecture without prematurely choosing a solution. Ask the assistant to inspect current behavior, locate the canonical owner and list constraints. Make the non-goals explicit: no migrations, no dependency changes, or no production access unless separately approved.
A useful exploration outcome is a short description of the existing system and the smallest plausible change. If the assistant instead produces a broad rewrite plan, tighten the boundary before moving forward.
Propose requirements that can fail
The README’s /opsx:propose workflow creates the proposal, specs, design and tasks. Write scenarios that distinguish success from failure. For an agent approval gate, include unauthorized actions, stale approvals, cancellation and retried requests, not only the happy path.
Example requirement for your own project:
Requirement: consequential tool calls need approval
When the agent requests an external side effect without approval,
the service rejects it and records a bounded audit event.
An approved retry must not duplicate the side effect.This example is an acceptance criterion, not a ready-made security implementation. A requirement that merely says “the agent handles errors safely” is too vague to verify.
Apply without losing the boundary
The apply stage implements the reviewed tasks. Use an isolated branch or worktree and examine the resulting diff. Completing a checklist is not permission to alter unrelated files, disable checks or expand credentials.
If implementation exposes a real architectural problem, revise the relevant design and scenarios deliberately. Do not let a coding assistant silently change the specification to match whatever it happened to build. The Git workflow foundation explains how branches, review and rollback make these boundaries durable.
Verify before archive
The expanded workflow includes /opsx:verify; select the expanded profile with openspec config profile and apply it with openspec update when needed. The README distinguishes this from the default workflow. Invocation spelling also varies: Cursor/Copilot, Codex and other tools can use different command forms. Follow what initialization generates.
Regardless of profile, run real project checks. Compare requirements with executed tests, inspect important failure paths and record unresolved items. Our testing AI-generated code workflow covers independent evidence. AI Testing & Evaluation covers variable model behavior that ordinary deterministic tests do not capture.
Archive only after implementation and acceptance are complete. Archiving reconciles the change with the lasting specifications; it is not the event that authorizes a production deployment. Keep release approval and operational validation explicit.
Cross-agent handoffs
The practical benefit of plain repository artifacts is that a second assistant can read the reviewed requirements without receiving the first assistant’s entire chat history. Before a handoff, record current branch, completed tasks, test evidence and remaining decisions.
Ask the receiving assistant to inspect the actual code and specifications rather than trust a summary claiming “all done.” If two assistants run concurrently, isolate their work and reconcile changes through review. A shared task list does not prevent filesystem races or conflicting edits.
For CI acceptance gates, connect the workflow with GitHub Actions for AI applications. For access boundaries, use AI agent security.
Limitations and maturity
OpenSpec cannot enforce every specification at runtime, guarantee agent correctness, or establish that a generated test covers an important failure. The repository also documents beta cross-repository Stores; do not assume that feature has the same maturity as a simple single-repository workflow.
Self-reported adoption counts are not evidence that a particular team will benefit. Try one bounded change and measure review clarity, requirement drift and rework. If your existing issue and pull-request process already captures these well, add only the artifacts that solve a real coordination problem.
My take
OpenSpec is most useful when it makes requirements portable between people and assistants. Its success criterion is not how many documents an agent generates. It is whether reviewers can determine what changed, why it changed, and what execution evidence supports shipping it.
Start with a small feature, keep the specification testable, and retain human ownership. That is a stronger workflow than treating a planning framework as another source of automatic approval.
FAQ
Is OpenSpec a coding agent?
No. It organizes a specification-driven workflow used with coding assistants. Your assistant and execution environment remain separate choices.
Can I use it with Claude Code, Codex and Cursor?
The project documents integrations for those tools and others. Select your tools during initialization and use their generated invocation forms.
Is verify part of every default workflow?
The README places /opsx:verify in the expanded workflow. Real test execution is still necessary whichever profile you select.
Does an archived change mean it is safe to deploy?
No. Archive manages the specification lifecycle. Passing required checks, review and deployment authorization remain separate gates.
Should every small change use all four artifacts?
Not necessarily. Apply the process where ambiguity or coordination costs justify it; keep trivial tasks proportionate.