OpenSpec (Fission-AI/OpenSpec) accumulated 600+ commits between v1.3.1 and v1.5.0. If you’re still on v1.3.1, the most immediate impression after upgrading will be: the AI understands your project better. Behind this are three fundamental architectural changes.
Before understanding the changes, let’s revisit how things worked in the v1.3.1 era.
A typical OpenSpec workflow: type /opsx:propose "build some feature" in the conversation, the AI generates proposal.md, design.md, specs/, and tasks.md under openspec/changes/, then /opsx:apply implements the tasks one by one, and finally /opsx:archive archives the change.
This flow works, but it has three pain points:
Instructions are hardcoded. The prompt telling the AI “how to write a proposal” lives in TypeScript source code. If your project needs a custom template (e.g., a mandatory “rollback plan” section), you either wait for an official release or repeatedly remind the AI in conversation — and the AI often forgets.
Phases are locked. The proposal must finish before implementation, implementation before archiving. If you discover mid-way that design.md needs adjustment, you must interrupt the flow, manually edit the document, and re-trigger apply. The AI doesn’t proactively sense these changes.
Planning belongs to one repository. openspec/ sits in the project root, naturally assuming one repo per plan. When a feature spans an API service, a frontend, and a shared library, no single repo is the right home for the plan.
The three core changes in v1.5.0 correspond exactly to these three pain points.
v1.5.0 extracted instructions from code into schemas/spec-driven/schema.yaml. This file declares artifact types (proposal, specs, design, tasks), their dependencies, and generation instructions for each artifact.
v1.3.1: AI receives a hardcoded prompt → generates documents
v1.5.0: AI runs openspec instructions <artifact> --json
→ pulls the current project's context + template + rules
→ generates documents based on the latest information
When the AI executes /opsx:propose, it no longer receives static text; instead it first runs openspec instructions proposal --json. The JSON returned includes:
context: project background from openspec/config.yaml (tech stack, architectural constraints)rules: rules defined per artifact type (e.g., “proposal must include SLO metrics”)template: the document structure defined by the current schemadependencies: the list of completed artifactsKey change: you edit the rules in config.yaml, and the next /opsx:propose takes effect immediately — no IDE restart, no waiting for a new version.
A natural consequence of Schema-driven is Fluid Workflow — since the AI queries current state every time, phase locking loses its meaning. You can go back mid-Apply to revise design.md; the next /opsx:apply will automatically sense the change. A batch of extended commands was added for this:
| Command | Purpose |
|---|---|
/opsx:new |
Initialize directory structure only, create documents step by step |
/opsx:continue |
Create the next artifact in dependency order |
/opsx:ff |
Skip documents and go straight to implementation |
/opsx:sync |
Sync delta specs to main specs without archiving |
/opsx:verify |
Verify implementation matches the spec |
/opsx:bulk-archive |
Archive multiple changes at once |
/opsx:onboard |
15-minute interactive full-flow guide |
Now that Schema solved “how the AI understands the project”, the next question is “where should the plan live”.
v1.5.0 introduces the Stores concept. A store is an ordinary Git repository containing an openspec/ directory and a .openspec-store/store.yaml identity file. It does exactly one thing: holds the plan. Team code repositories point to it via --store <id> or a pointer in config.yaml.
# Create a store named team-plans
openspec store setup team-plans --path ~/openspec/team-plans
# From now on, any command can target it
openspec new change add-login --store team-plans
openspec status --change add-login --store team-plans
Other team members:
git clone git@github.com:acme/team-plans.git ~/openspec/team-plans
openspec store register ~/openspec/team-plans
A code repository only needs one line in config.yaml:
store: team-plans
After that, any openspec command run inside the repository automatically targets the team-plans store — no need to pass --store every time.
Stores are a Beta feature with known limitations: one local checkout per store id, and OpenSpec never syncs automatically (you run git pull yourself). But this is deliberate — the store’s version control is entirely Git’s responsibility; OpenSpec doesn’t intervene.
v1.4.0 introduced workspace/initiative as an attempt at cross-repository planning, which v1.5.0 completely replaced with stores. If you used workspace during v1.4.0, migrate to stores; if you upgrade directly from v1.3.1, stores are a brand-new feature with no migration needed.
The first two changes address “how”, the third addresses “what”.
The standard entry point in v1.3.1 was /opsx:propose. The user describes a requirement, and the AI generates documents directly. The problem: the AI’s “understanding” often deviates from the user’s “intent”, and the deviation only surfaces once code is written.
v1.5.0 promoted /opsx:explore from an experimental feature to the recommended starting point. Explore mode creates no files; the AI first investigates the codebase, compares options, and sketches architecture — like a zero-cost brainstorming session. Once key decisions are confirmed, it moves to /opsx:propose.
v1.3.1: propose → apply → archive
↑ deviation risk surfaces late
v1.5.0: explore → propose → apply → sync → archive
↑ ↑
zero-cost intent validation ensure spec sync before archiving
This philosophy runs through v1.5.0’s documentation design — the official docs homepage’s first guidance line is “Not sure what to build yet? Start with /opsx:explore”.
Beyond the three major changes, v1.5.0 brings a batch of infrastructure enhancements:
AI tool ecosystem. New adapters for Claude Code, Mistral Vibe, Oh My Pi, Trae, etc., supporting 25+ AI coding assistants. Each adapter implements the unified CommandContent interface — adding a tool requires just one file.
Global installation. openspec init supports global directories, so teams can share one AI instruction configuration without re-initializing per project.
Configuration enhancements. Container fields in config.yaml support JSON format. The Validator’s SHALL/MUST detection is more accurate, and header parsing is now case-insensitive.
Official documentation. A comprehensive overhaul — from “feature list” style to “scenario-guided” style: explore-first, organized by operation, emphasizing discoverability.
Stores are Beta. Command names, flags, file formats, and JSON output may change in future releases. What’s explicitly not done: automatic clone/pull/push (Git handles it), and multiple checkouts per store id.
Upgrading itself is simple:
npm install -g @fission-ai/openspec@latest
cd your-project
openspec update
openspec update refreshes all AI tool configuration files — no need to re-run init.
From v1.3.1 to v1.5.0, OpenSpec’s core change is not feature stacking but an architectural rethinking: instructions went from code to data, planning went from an attachment to an independent entity, and the workflow went from push to pull. For users, the most direct experience is — the AI finally stopped “guessing”.
Based on analysis of OpenSpec diffs and changelogs from v1.3.1 to v1.5.0. Practice validation: OpenSpec Practise v1.5.0.