Our philosophy:
→ fluid not rigid
→ iterative not waterfall
→ easy not complex
→ built for brownfield not just greenfield
→ scalable from personal projects to enterprises
Requires Node.js 20.19.0 or higher.
Install OpenSpec globally:
npm install -g @fission-ai/openspec@latest
Then navigate to your project directory and initialize:
cd your-project
openspec init
Now tell your AI: /opsx:propose <what-you-want-to-build>
If you want the expanded workflow (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:sync, /opsx:bulk-archive, /opsx:onboard), select it with openspec config profile and apply with openspec update.
OpenSpec helps you and your AI coding assistant agree on what to build before any code is written.
Default quick path (core profile):
/opsx:propose ──► /opsx:apply ──► /opsx:archive
Expanded path (custom workflow selection):
/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive
The default global profile is core, which includes propose, explore, apply, and archive. You can enable the expanded workflow commands with openspec config profile and then openspec update.
After running openspec init, your project has this structure:
openspec/
├── specs/ # Source of truth (your system's behavior)
│ └── <domain>/
│ └── spec.md
├── changes/ # Proposed updates (one folder per change)
│ └── <change-name>/
│ ├── proposal.md
│ ├── design.md
│ ├── tasks.md
│ └── specs/ # Delta specs (what's changing)
│ └── <domain>/
│ └── spec.md
└── config.yaml # Project configuration (optional)
Two key directories:
specs/ - The source of truth. These specs describe how your system currently behaves. Organized by domain (e.g., specs/auth/, specs/payments/).
changes/ - Proposed modifications. Each change gets its own folder with all related artifacts. When a change is complete, its specs merge into the main specs/ directory.
Each change folder contains artifacts that guide the work:
| Artifact | Purpose |
|---|---|
proposal.md |
The "why" and "what" - captures intent, scope, and approach |
specs/ |
Delta specs showing ADDED/MODIFIED/REMOVED requirements |
design.md |
The "how" - technical approach and architecture decisions |
tasks.md |
Implementation checklist with checkboxes |
Artifacts build on each other:
proposal ──► specs ──► design ──► tasks ──► implement
▲ ▲ ▲ │
└───────────┴──────────┴────────────────────┘
update as you learn
You can always go back and refine earlier artifacts as you learn more during implementation.
Delta specs are the key concept in OpenSpec. They show what's changing relative to your current specs.
Delta specs use sections to indicate the type of change:
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.
#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
## MODIFIED Requirements
### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA)
When you archive a change:
The change folder moves to openspec/changes/archive/ for audit history.
Let's walk through adding dark mode to an application.
You: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
✓ proposal.md — why we're doing this, what's changing
✓ specs/ — requirements and scenarios
✓ design.md — technical approach
✓ tasks.md — implementation checklist
Ready for implementation!
If you've enabled the expanded workflow profile, you can also do this as two steps: /opsx:new then /opsx:ff (or /opsx:continue incrementally).
proposal.md - Captures the intent:
# Proposal: Add Dark Mode
## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.
## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage
## Approach
Use CSS custom properties for theming with a React context
for state management.
specs/ui/spec.md - Delta showing new requirements:
# Delta for UI
## ADDED Requirements
### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.
#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions
#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used
tasks.md - Implementation checklist:
# Tasks
## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence
## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle
## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables
You: /opsx:apply
AI: Working through tasks...
✓ 1.1 Created ThemeContext with light/dark state
✓ 1.2 Added CSS custom properties to globals.css
✓ 1.3 Implemented localStorage persistence
✓ 2.1 Created ThemeToggle component
...
All tasks complete!
During implementation, if you discover the design needs adjustment, just update the artifact and continue.
You: /opsx:archive
AI: Archiving add-dark-mode...
✓ Merged specs into openspec/specs/ui/spec.md
✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
Done! Ready for the next feature.
Your delta specs are now part of the main specs, documenting how your system works.
Use the CLI to check on your changes:
# List active changes
openspec list
# View change details
openspec show add-dark-mode
# Validate spec formatting
openspec validate add-dark-mode
# Interactive dashboard
openspec view
It's a fluid, iterative workflow for OpenSpec changes. No more rigid phases — just actions you can take anytime.
The legacy OpenSpec workflow works, but it's locked down:
OPSX opens it up. Now anyone can:
Legacy workflow: OPSX:
┌────────────────────────┐ ┌────────────────────────┐
│ Hardcoded in package │ │ schema.yaml │◄── You edit this
│ (can't change) │ │ templates/*.md │◄── Or this
│ ↓ │ │ ↓ │
│ Wait for new release │ │ Instant effect │
│ ↓ │ │ ↓ │
│ Hope it's better │ │ Test it yourself │
└────────────────────────┘ └────────────────────────┘
This is for everyone:
- Teams — create workflows that match how you actually work
- Power users — tweak prompts to get better AI outputs for your codebase
- OpenSpec contributors — experiment with new approaches without releases
We're all still learning what works best. OPSX lets us learn together.
The problem with linear workflows:
You're "in planning phase", then "in implementation phase", then "done". But real work doesn't work that way. You implement something, realize your design was wrong, need to update specs, continue implementing. Linear phases fight against how work actually happens.
OPSX approach:
- Actions, not phases — create, implement, update, archive — do any of them anytime
- Dependencies are enablers — they show what's possible, not what's required next
proposal ──→ specs ──→ design ──→ tasks ──→ implement
# Make sure you have openspec installed — skills are automatically generated
openspec init
This creates skills in .claude/skills/ (or equivalent) that AI coding assistants auto-detect.
By default, OpenSpec uses the core workflow profile (propose, explore, apply, archive). If you want the expanded workflow commands (new, continue, ff, verify, sync, bulk-archive, onboard), configure them with openspec config profile and apply with openspec update.
During setup, you'll be prompted to create a project config (openspec/config.yaml). This is optional but recommended.
Project config lets you set defaults and inject project-specific context into all artifacts.
Config is created during openspec init, or manually:
# openspec/config.yaml
schema: spec-driven
context: |
Tech stack: TypeScript, React, Node.js
API conventions: RESTful, JSON responses
Testing: Vitest for unit tests, Playwright for e2e
Style: ESLint with Prettier, strict TypeScript
rules:
proposal:
- Include rollback plan
- Identify affected teams
specs:
- Use Given/When/Then format for scenarios
design:
- Include sequence diagrams for complex flows
| Field | Type | Description |
|---|---|---|
schema |
string | Default schema for new changes (e.g., spec-driven) |
context |
string | Project context injected into all artifact instructions |
rules |
object | Per-artifact rules, keyed by artifact ID |
Schema precedence (highest to lowest):
1. CLI flag (--schema <name>)
2. Change metadata (.openspec.yaml in change directory)
3. Project config (openspec/config.yaml)
4. Default (spec-driven)
Context injection:
- Context is prepended to every artifact's instructions
- Wrapped in <context>...</context> tags
- Helps AI understand your project's conventions
Rules injection:
- Rules are only injected for matching artifacts
- Wrapped in <rules>...</rules> tags
- Appear after context, before the template
spec-driven (default):
- proposal — Change proposal
- specs — Specifications
- design — Technical design
- tasks — Implementation tasks
rules generate warnings"Unknown artifact ID in rules: X"
- Check artifact IDs match your schema (see list above)
- Run openspec schemas --json to see artifact IDs for each schema
Config not being applied:
- Ensure file is at openspec/config.yaml (not .yml)
- Check YAML syntax with a validator
- Config changes take effect immediately (no restart needed)
Context too large:
- Context is limited to 50KB
- Summarize or link to external docs instead
| Command | What it does |
|---|---|
/opsx:propose |
Create a change and generate planning artifacts in one step (default quick path) |
/opsx:explore |
Think through ideas, investigate problems, clarify requirements |
/opsx:new |
Start a new change scaffold (expanded workflow) |
/opsx:continue |
Create the next artifact (expanded workflow) |
/opsx:ff |
Fast-forward planning artifacts (expanded workflow) |
/opsx:apply |
Implement tasks, updating artifacts as needed |
/opsx:verify |
Validate implementation against artifacts (expanded workflow) |
/opsx:sync |
Sync delta specs to main (expanded workflow, optional) |
/opsx:archive |
Archive when done |
/opsx:bulk-archive |
Archive multiple completed changes (expanded workflow) |
/opsx:onboard |
Guided walkthrough of an end-to-end change (expanded workflow) |
/opsx:explore
Think through ideas, investigate problems, compare options. No structure required - just a thinking partner. When insights crystallize, transition to /opsx:propose (default) or /opsx:new//opsx:ff (expanded).
/opsx:propose
Creates the change and generates planning artifacts needed before implementation.
If you've enabled expanded workflows, you can instead use:
/opsx:new # scaffold only
/opsx:continue # create one artifact at a time
/opsx:ff # create all planning artifacts at once
/opsx:continue
Shows what's ready to create based on dependencies, then creates one artifact. Use repeatedly to build up your change incrementally.
/opsx:ff add-dark-mode
Creates all planning artifacts at once. Use when you have a clear picture of what you're building.
/opsx:apply
Works through tasks, checking them off as you go. If you're juggling multiple changes, you can run /opsx:apply <name>; otherwise it should infer from the conversation and prompt you to choose if it can't tell.
/opsx:archive # Move to archive when done (prompts to sync specs if needed)
You can always edit your proposal or specs before implementation. But when does refining become "this is different work"?
A proposal defines three things:
1. Intent — What problem are you solving?
2. Scope — What's in/out of bounds?
3. Approach — How will you solve it?
The question is: which changed, and by how much?
Same intent, refined execution
- You discover edge cases you didn't consider
- The approach needs tweaking but the goal is unchanged
- Implementation reveals the design was slightly off
Scope narrows
- You realize full scope is too big, want to ship MVP first
- "Add dark mode" → "Add dark mode toggle (system preference in v2)"
Learning-driven corrections
- Codebase isn't structured how you thought
- A dependency doesn't work as expected
- "Use CSS variables" → "Use Tailwind's dark: prefix instead"
Intent fundamentally changed
- The problem itself is different now
- "Add dark mode" → "Add comprehensive theme system with custom colors, fonts, spacing"
Scope exploded
- Change grew so much it's essentially different work
- Original proposal would be unrecognizable after updates
- "Fix login bug" → "Rewrite auth system"
Original is completable
- The original change can be marked "done"
- New work stands alone, not a refinement
- Complete "Add dark mode MVP" → Archive → New change "Enhance dark mode"
┌─────────────────────────────────────┐
│ Is this the same work? │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
Same intent? >50% overlap? Can original
Same problem? Same scope? be "done" without
│ │ these changes?
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
YES NO YES NO NO YES
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
UPDATE NEW UPDATE NEW UPDATE NEW
| Test | Update | New Change |
|---|---|---|
| Identity | "Same thing, refined" | "Different work" |
| Scope overlap | >50% overlaps | <50% overlaps |
| Completion | Can't be "done" without changes | Can finish original, new work stands alone |
| Story | Update chain tells coherent story | Patches would confuse more than clarify |
Update preserves context. New change provides clarity.
Choose update when the history of your thinking is valuable.
Choose new when starting fresh would be clearer than patching.
Think of it like git branches:
- Keep committing while working on the same feature
- Start a new branch when it's genuinely new work
- Sometimes merge a partial feature and start fresh for phase 2
Legacy (/openspec:proposal) |
OPSX (/opsx:*) |
|
|---|---|---|
| Structure | One big proposal document | Discrete artifacts with dependencies |
| Workflow | Linear phases: plan → implement → archive | Fluid actions — do anything anytime |
| Iteration | Awkward to go back | Update artifacts as you learn |
| Customization | Fixed structure | Schema-driven (define your own artifacts) |
The key insight: work isn't linear. OPSX stops pretending it is.
This section explains how OPSX works under the hood and how it compares to the legacy workflow.
Examples in this section use the expanded command set (new, continue, etc.); default core users can map the same flow to propose → apply → archive.
┌─────────────────────────────────────────────────────────────────────────────┐
│ LEGACY WORKFLOW │
│ (Phase-Locked, All-or-Nothing) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PLANNING │ ───► │ IMPLEMENTING │ ───► │ ARCHIVING │ │
│ │ PHASE │ │ PHASE │ │ PHASE │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ /openspec:proposal /openspec:apply /openspec:archive │
│ │
│ • Creates ALL artifacts at once │
│ • Can't go back to update specs during implementation │
│ • Phase gates enforce linear progression │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX WORKFLOW │
│ (Fluid Actions, Iterative) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ ACTIONS (not phases) │ │
│ │ │ │
│ │ new ◄──► continue ◄──► apply ◄──► archive │ │
│ │ │ │ │ │ │ │
│ │ └──────────┴───────────┴───────────┘ │ │
│ │ any order │ │
│ └────────────────────────────────────────────┘ │
│ │
│ • Create artifacts one at a time OR fast-forward │
│ • Update specs/design/tasks during implementation │
│ • Dependencies enable progress, phases don't exist │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Legacy workflow uses hardcoded templates in TypeScript:
┌─────────────────────────────────────────────────────────────────────────────┐
│ LEGACY WORKFLOW COMPONENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Hardcoded Templates (TypeScript strings) │
│ │ │
│ ▼ │
│ Tool-specific configurators/adapters │
│ │ │
│ ▼ │
│ Generated Command Files (.claude/commands/openspec/*.md) │
│ │
│ • Fixed structure, no artifact awareness │
│ • Change requires code modification + rebuild │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
OPSX uses external schemas and a dependency graph engine:
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX COMPONENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Schema Definitions (YAML) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ name: spec-driven │ │
│ │ artifacts: │ │
│ │ - id: proposal │ │
│ │ generates: proposal.md │ │
│ │ requires: [] ◄── Dependencies │ │
│ │ - id: specs │ │
│ │ generates: specs/**/*.md ◄── Glob patterns │ │
│ │ requires: [proposal] ◄── Enables after proposal │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Artifact Graph Engine │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • Topological sort (dependency ordering) │ │
│ │ • State detection (filesystem existence) │ │
│ │ • Rich instruction generation (templates + context) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Skill Files (.claude/skills/openspec-*/SKILL.md) │
│ │
│ • Cross-editor compatible (Claude Code, Cursor, Windsurf) │
│ • Skills query CLI for structured data │
│ • Fully customizable via schema files │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Artifacts form a directed acyclic graph (DAG). Dependencies are enablers, not gates:
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)
│
▼
┌──────────────┐
│ APPLY PHASE │
│ (requires: │
│ tasks) │
└──────────────┘
State transitions:
BLOCKED ────────────────► READY ────────────────► DONE
│ │ │
Missing All deps File exists
dependencies are DONE on filesystem
Legacy workflow — agent receives static instructions:
User: "/openspec:proposal"
│
▼
┌─────────────────────────────────────────┐
│ Static instructions: │
│ • Create proposal.md │
│ • Create tasks.md │
│ • Create design.md │
│ • Create specs/<capability>/spec.md │
│ │
│ No awareness of what exists or │
│ dependencies between artifacts │
└─────────────────────────────────────────┘
│
▼
Agent creates ALL artifacts in one go
OPSX — agent queries for rich context:
User: "/opsx:continue"
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Step 1: Query current state │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec status --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "artifacts": [ │ │
│ │ {"id": "proposal", "status": "done"}, │ │
│ │ {"id": "specs", "status": "ready"}, ◄── First ready │ │
│ │ {"id": "design", "status": "ready"}, │ │
│ │ {"id": "tasks", "status": "blocked", "missingDeps": ["specs"]}│ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 2: Get rich instructions for ready artifact │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec instructions specs --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "template": "# Specification\n\n## ADDED Requirements...", │ │
│ │ "dependencies": [{"id": "proposal", "path": "...", "done": true}│ │
│ │ "unlocks": ["tasks"] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 3: Read dependencies → Create ONE artifact → Show what's unlocked │
└──────────────────────────────────────────────────────────────────────────┘
Legacy workflow — awkward to iterate:
┌─────────┐ ┌─────────┐ ┌─────────┐
│/proposal│ ──► │ /apply │ ──► │/archive │
└─────────┘ └─────────┘ └─────────┘
│ │
│ ├── "Wait, the design is wrong"
│ │
│ ├── Options:
│ │ • Edit files manually (breaks context)
│ │ • Abandon and start over
│ │ • Push through and fix later
│ │
│ └── No official "go back" mechanism
│
└── Creates ALL artifacts at once
OPSX — natural iteration:
/opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
│ │ │
│ │ ├── "The design is wrong"
│ │ │
│ │ ▼
│ │ Just edit design.md
│ │ and continue!
│ │ │
│ │ ▼
│ │ /opsx:apply picks up
│ │ where you left off
│ │
│ └── Creates ONE artifact, shows what's unlocked
│
└── Scaffolds change, waits for direction
Create custom workflows using the schema management commands:
# Create a new schema from scratch (interactive)
openspec schema init my-workflow
# Or fork an existing schema as a starting point
openspec schema fork spec-driven my-workflow
# Validate your schema structure
openspec schema validate my-workflow
# See where a schema resolves from (useful for debugging)
openspec schema which my-workflow
Schemas are stored in openspec/schemas/ (project-local, version controlled) or ~/.local/share/openspec/schemas/ (user global).
Schema structure:
openspec/schemas/research-first/
├── schema.yaml
└── templates/
├── research.md
├── proposal.md
└── tasks.md
Example schema.yaml:
name: research-first
artifacts:
- id: research # Added before proposal
generates: research.md
requires: []
- id: proposal
generates: proposal.md
requires: [research] # Now depends on research
- id: tasks
generates: tasks.md
requires: [proposal]
Dependency Graph:
research ──► proposal ──► tasks
| Aspect | Legacy | OPSX |
|---|---|---|
| Templates | Hardcoded TypeScript | External YAML + Markdown |
| Dependencies | None (all at once) | DAG with topological sort |
| State | Phase-based mental model | Filesystem existence |
| Customization | Edit source, rebuild | Create schema.yaml |
| Iteration | Phase-locked | Fluid, edit anything |
| Editor Support | Tool-specific configurator/adapters | Single skills directory |
Schemas define what artifacts exist and their dependencies. Currently available:
# List available schemas
openspec schemas
# See all schemas with their resolution sources
openspec schema which --all
# Create a new schema interactively
openspec schema init my-workflow
# Fork an existing schema for customization
openspec schema fork spec-driven my-workflow
# Validate schema structure before use
openspec schema validate my-workflow
/opsx:explore to think through an idea before committing to a change/opsx:ff when you know what you want, /opsx:continue when exploring/opsx:apply, if something's wrong — fix the artifact, then continuetasks.mdopenspec status --change "name"Last modified 07 May 2026