/opsx:propose → apply → archive: Running a Complete OpenSpec Workflow

OpenSpec's core workflow is just three commands: /opsx:propose, /opsx:apply, and /opsx:archive. That's not many — but these three steps connect the entire chain from "I want to build this" to "it's built and documented." This article uses "adding dark mode" as an example to walk through a complete cycle.

Step 1: /opsx:propose — State What You're Building

/opsx:propose add-dark-mode

What this command does: AI creates the openspec/changes/add-dark-mode/ folder and generates four artifacts:

openspec/changes/add-dark-mode/
├── proposal.md         ← why we're doing this, what's in scope
├── specs/ui/spec.md    ← delta spec: which behaviors are changing
├── design.md           ← technical approach
└── tasks.md            ← implementation checklist

AI will often ask clarifying questions to help generate these, such as:

• What's the motivation for this feature?
• Should it support system preference (follow OS settings)?
• Should localStorage save the preference?

This is the most important step in the entire workflow — spend time reviewing the four documents AI generates, and confirm they match what you had in mind. Pay special attention to proposal.md and tasks.md. If something looks off, say so immediately and let AI correct it. Changing things here is far cheaper than changing them after implementation.

Once you're satisfied, move forward.

Mid-Point Check: Review tasks.md

Before running /opsx:apply, open tasks.md and read through it — this is the checklist AI is about to execute, and you want to verify the tasks are broken down correctly and nothing is missing:

# Tasks
 
## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext to manage light/dark state
- [ ] 1.2 Add CSS custom properties
- [ ] 1.3 Implement localStorage preference persistence
 
## 2. UI Components
- [ ] 2.1 Build ThemeToggle component
- [ ] 2.2 Add settings page
- [ ] 2.3 Add quick-toggle button in Header
 
## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables

If the list looks good, continue.

Step 2: /opsx:apply — Implement

/opsx:apply

AI works through the tasks.md checklist item by item. You'll see it tick off each task:

✓ 1.1 Create ThemeContext with light/dark state
✓ 1.2 Add CSS custom properties to globals.css
✓ 1.3 Implement localStorage persistence
✓ 2.1 Build ThemeToggle component
✓ 2.2 Add settings page
...
All tasks complete!

If during implementation AI discovers a problem with the original design — say it finds your component library already has a theming mechanism that conflicts with the approach planned in tasks — tell it directly, update design.md or tasks.md, and continue. OpenSpec doesn't lock you out of going back to update artifacts. That's what "fluid not rigid" means.

After Implementation, Verify

Once implementation is complete, manually run through the feature to confirm it works — this isn't a step OpenSpec formally requires, but it's a good habit, especially for anything moderately complex.

If you've enabled an advanced workflow profile, you can use:

/opsx:verify

This lets AI compare the implementation against the artifact specs and catch any obvious gaps.

Step 3: /opsx:archive — Wrap Up

/opsx:archive

AI does three things to close out the change:

1. Merge the delta spec into the main spec — The ADDED/MODIFIED/REMOVED specs in changes/add-dark-mode/specs/ are merged back into the corresponding openspec/specs/ files
2. Move the change folder — changes/add-dark-mode/ is moved to changes/archive/2026-04-01-add-dark-mode/
3. Done — The main spec now reflects the latest state and you can start the next change

At this point, openspec/specs/ui/spec.md will include the requirement "users can toggle between light and dark themes," so anyone building on top of this in the future will have an existing spec to reference and delta from.

The Full Flow at a Glance

/opsx:propose    →   Review artifacts   →   /opsx:apply   →   Verify   →   /opsx:archive
     ↓                      ↓                    ↓                               ↓
Create changes         proposal/specs/       Execute tasks.md            Delta spec merged
folder, generate       design/tasks          item by item                into main specs
four artifacts         review and confirm

What If You Want to Explore Before Proposing?

If you're not sure about the direction yet, start with /opsx:explore:

/opsx:explore How should we handle login for a mobile app?

AI will dig through your existing codebase, explain what's there, and compare a few approaches with their trade-offs — without creating any artifacts. Once you're clear on the direction, run /opsx:propose, and the quality of the generated artifacts will be much higher.

The workflow is clear. The next article covers real-world scenarios — new features, bug fixes, and adding OpenSpec to an existing project each have their own corresponding playbook.

Next: Real-World Usage: New Features, Bug Fixes, Adding OpenSpec to Existing Projects