docs/getting-started.md
This guide explains how OpenSpec works after you've installed and initialized it. For installation instructions, see the main README or the Installation guide. New to the whole docs set? The documentation home maps everything.
Where do I type these commands? Two places, and mixing them up is the most common early stumble.
openspec ...commands (likeopenspec init) run in your terminal./opsx:...commands (like/opsx:propose) run in your AI assistant's chat, the same box where you'd ask it to write code.There's no separate "interactive mode" to start. You just type the slash command in chat and your assistant takes it from there. Full explanation: How Commands Work.
The whole loop, with each step labeled by where it happens:
TERMINAL $ npm install -g @fission-ai/openspec@latest
TERMINAL $ cd your-project && openspec init
AI CHAT /opsx:explore (optional: think it through first)
AI CHAT /opsx:propose add-dark-mode (AI drafts the plan; you review it)
AI CHAT /opsx:apply (AI builds it)
AI CHAT /opsx:archive (specs updated, change filed away)
Two terminal steps to set up, then you live in chat. The rest of this guide unpacks what each step does and what you'll see.
Not sure what to build yet? Start with
/opsx:explore. It's a no-stakes thinking partner that reads your codebase, weighs options, and sharpens a fuzzy idea into a concrete plan, all before any artifact or code exists. When the picture is clear, it hands off to/opsx:propose. This is the single best habit for working with an AI that will otherwise confidently build the wrong thing. See the Explore guide.
OpenSpec helps you and your AI coding assistant agree on what to build before any code is written.
Default quick path (core profile):
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
(optional)
Start with /opsx:explore when you're figuring out what to do, or jump straight to /opsx:propose when you already know. Explore is in the default profile, so it's always there when you want it.
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, sync, 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
/opsx:explore to think through an idea before you commit