Setting Up OpenSpec with OpenCode: A Practical Guide
🇩🇪 Auf Deutsch lesen~6 min read
ai-agentsopencodeopenspecopsxagentic-developmentworkflow
Back openDesk Edu for a sovereign, open-source education — every vote counts.
Vote nowSave products you love by clicking the heart icon.
A technical comparison of OpenSpec against OpenAPI, ADRs, RFCs, BDD/Gherkin, and traditional project management — and why the AI agent era demands a fundamentally different approach to change management.
In the companion article comparing AI-assisted development methodologies, OpenSpec stood out for one reason: it is the most practical framework to adopt incrementally. You do not restructure your team or install a pipeline. You add two files and change how you write prompts.
This guide takes that claim and tests it on a real codebase — the very Next.js site you are reading this on. Every example is taken from actual work done on this project: adding articles, modifying components, and fixing issues. You can follow along and end up with a working OpenSpec setup in your own OpenCode project.
By the end of this guide, you will have:
openspec/changes/ directory with at least one complete change artifacttask() delegationThe examples are specific to OpenCode, but the workflow works with any of the 20+ tools OpenSpec supports.
OpenSpec is an npm package. Install it globally or per-project:
npm install --save-dev @fission-ai/openspec
Or globally if you want it available across all your projects:
npm install -g @fission-ai/openspec
Create the directory structure:
mkdir -p openspec/changes openspec/archive
OpenSpec does not require a configuration file. The entire convention is directory-based: openspec/changes/ for active work, openspec/archive/ for completed changes. You can add a .openspec.json if you want to configure telemetry or custom paths, but the defaults work for most projects.
your-project/
├── openspec/
│ ├── changes/
│ │ └── add-dark-mode/
│ │ ├── proposal.md
│ │ ├── specs.md
│ │ ├── design.md
│ │ └── tasks.md
│ └── archive/
│ └── add-dark-mode/ # Moved here after completion
└── (rest of your project)
OpenSpec's OPSX (Open-Prompt Specification Exchange) protocol defines three commands. Here is how each maps to an OpenCode action:
/opsx:propose — Create the SpecThis is the most important command. Instead of telling OpenCode what to implement, you tell it to ask you questions first and produce a structured spec.
In your OpenCode chat:
You: /opsx:propose Add a dark mode toggle to the site header. The toggle
should persist the user's preference and work across page navigations.
OpenCode: I'll draft a proposal. A few questions:
1. Where should the toggle icon live? (header, sidebar, both?)
2. Should the preference be stored in localStorage or a cookie?
3. Should dark mode be the default for users who prefer it via
prefers-color-scheme?
4. Do we need a system theme option in addition to light/dark?
After you answer, OpenCode generates two files:
openspec/changes/add-dark-mode/proposal.md
# Proposal: Add Dark Mode Toggle
## Motivation
Users reading technical content at night need a dark theme to reduce eye
strain. This is a standard feature for content-heavy sites and is the most
requested UX improvement.
## Scope
Add a toggle in the site header that switches between light and dark themes.
Persist the choice in localStorage. Respect the user's system preference on
first visit.
## Key Constraints
- Must work with Tailwind CSS v4 dark mode variant
- Must not cause a flash of wrong theme on page load
- Must be accessible (keyboard operable, high contrast)
openspec/changes/add-dark-mode/specs.md
# add-dark-mode: Specs
## ADDED
- `src/components/ThemeToggle.tsx` — accessible toggle button component
- Renders sun/moon icon based on current theme
- Emits theme change event on toggle
- Keyboard operable (Enter/Space to toggle)
- `src/lib/theme.ts` — theme persistence utility
- `getTheme(): 'light' | 'dark' — reads from localStorage or system pref
- `setTheme(theme)` — writes to localStorage and updates `<html>` class
- `<script>` in `src/app/layout.tsx` — inline script to prevent flash of
wrong theme (runs before React hydrates)
## MODIFIED
- `src/app/layout.tsx` — add `<html>` class based on initial theme, wrap
app in ThemeProvider context
- `src/components/Header.tsx` — render ThemeToggle in the header bar
## REMOVED
- (none)
/opsx:apply — Implement the SpecOnce the spec is written, tell OpenCode to implement it:
You: /opsx:apply
OpenCode: Reading spec from openspec/changes/add-dark-mode/specs.md...
Implementing:
1. Created src/components/ThemeToggle.tsx — accessible toggle with
sun/moon icons, keyboard support, and ARIA labels
2. Created src/lib/theme.ts — localStorage-backed persistence with
system preference detection
3. Modified src/app/layout.tsx — added inline script for flash prevention
and theme class on <html>
4. Modified src/components/Header.tsx — added ThemeToggle to the header
bar
Verifying: checking for flash on page load... pass.
checking keyboard navigation... pass.
checking localStorage persistence... pass.
In OpenCode terms, /opsx:apply is equivalent to delegating via task() with the spec as your prompt. The difference is that the spec was written before implementation, not as part of the prompt. This separation forces you to clarify scope upfront instead of negotiating it mid-implementation.
/opsx:archive — Preserve the DecisionAfter you approve the implementation, archive it:
You: /opsx:archive
This moves openspec/changes/add-dark-mode/ to openspec/archive/add-dark-mode/. The proposal, spec, and design artifacts are now a permanent record. If someone asks in six months why dark mode uses a localStorage cookie instead of server-side detection, the archived proposal has the answer.
Let me walk through an OpenSpec change applied to this actual project. Here is the spec used to add the article you are reading now.
# Proposal: OpenSpec OpenCode Workflow Guide
## Motivation
The main article compared OpenSpec, BMAD, and GSD Core. A companion piece
that shows readers how to actually set up OpenSpec with OpenCode will convert
theory into practice and increase engagement with the methodology.
## Scope
A standalone guide article at content/openspec-opencode-workflow-guide.md
with real examples from this codebase.
## Key Constraints
- Must pass npm run validate:content (frontmatter rules)
- British English spelling consistent with site style
- Same frontmatter format as other articles (title, date, description,
tags, category)
# Article: OpenSpec OpenCode Workflow Guide — Specs
## ADDED
- `content/openspec-opencode-workflow-guide.md` — practical setup guide
- Minimum 800 words
- Installation instructions for @fission-ai/openspec
- OPSX protocol walkthrough with OpenCode-specific dialogue examples
- Real example using this project (article workflow)
- Team patterns and archive usage
- British English, GFM markdown, code blocks with language tags
## MODIFIED
- `content/ai-assisted-development-methodologies.md` — add "see practical
guide" reference in the OpenSpec section (optional, if editor approves)
## REMOVED
- (none)
After implementing and verifying (npm run validate:content passes, npm run build succeeds), archive the change. The complete decision record — why the article was needed, what it covers, and where it lives — is preserved in openspec/archive/.
OpenSpec's default artifact structure supports four files. For OpenCode users, two additions are worth considering:
review.md FileOpenCode has a review-work skill that runs multiple parallel reviews. You can add a review step to your change artifacts:
# review.md
## Momus Review
- [x] Acceptance criteria are verifiable
- [x] Scope boundaries are clear
- [x] No ambiguous language
## Oracle Review
- [x] Architecture approach is sound
- [x] No security concerns
## QA Review
- [x] Spec is implementable as written
- [x] Edge cases documented
This formalises what OpenCode's skill(name="review-work") already does, but ties it to a specific change rather than running it ad-hoc.
tasks.md FileFor complex changes, OpenCode's task decomposition can be documented alongside the spec:
# tasks.md
## Wave 1 (Independent)
- [ ] Create ThemeToggle component
- [ ] Create theme persistence utility
## Wave 2 (Depends on Wave 1)
- [ ] Integrate into Header
- [ ] Add flash-prevention script to layout
## Wave 3 (Verification)
- [ ] Verify no flash on page load
- [ ] Verify keyboard navigation
- [ ] Verify localStorage persistence
## Dependencies
- Tailwind CSS v4 dark mode variant must be enabled in tailwind.config
This maps to GSD Core's wave execution model but within OpenSpec's file structure. You get both frameworks' concepts without adopting either wholesale.
OpenSpec becomes more valuable in team settings. Here are three patterns that work well when multiple people use OpenCode on the same project.
Each developer works in their own change directory:
openspec/changes/
├── alice/add-pagination/
├── bob/dark-mode-toggle/
└── carol/fix-header-responsive/
No locks, no checkouts. If two changes modify the same file, the delta specs make conflicts visible before implementation starts — you can see in specs.md that both Alice and Bob want to modify Header.tsx.
Enforce a team rule: no PR merges without an archived OpenSpec change. The spec in openspec/archive/ serves as the code review attachment — reviewers read the proposal and spec before looking at the diff.
# Pre-merge check
if [ ! -d "openspec/archive/$(git branch --show-current)" ]; then
echo "Error: No archived OpenSpec change for this branch."
echo "Run /opsx:archive before merging."
exit 1
fi
The archive becomes searchable over time:
# Find why a decision was made
grep -r "pagination" openspec/archive/*/proposal.md
# Find all changes that touched a file
grep -r "Header.tsx" openspec/archive/*/specs.md
# Show what was removed recently
grep -r "## REMOVED" openspec/archive/*/specs.md
This is the feature that most OpenCode users lack and do not realise they lack until they need it. OpenCode remembers nothing between sessions. The archive fills that gap with zero tooling — just flat files you can grep.
The most common mistake is writing specs at the wrong granularity:
# BAD — too vague
## ADDED
- Dark mode toggle
# GOOD — implementation-ready
## ADDED
- `src/components/ThemeToggle.tsx` — accessible toggle with sun/moon icons
- Props: none (self-contained)
- Keyboard: Enter/Space to toggle
- ARIA: role="switch", aria-checked reflects current theme
If a subagent could implement the spec without asking clarifying questions, the spec is specific enough. If the agent would need to ask "where should the toggle go?" or "what icon should it use?", the spec needs more detail.
/opsx:archiveThe archive is what gives OpenSpec its long-term value. Skipping it because you are busy is the same failure mode as skipping documentation because you are busy — it feels fine today and causes pain six months later.
Make archiving part of your completion checklist. In OpenCode terms: before marking a todo item completed, run /opsx:archive.
Not every change needs all four files. A one-line bug fix might only need specs.md:
## MODIFIED
- `src/lib/content.ts` line 42 — fix off-by-one in pagination totalPages calc
OpenSpec's philosophy is "fluid not rigid". If an artifact adds no value for a given change, skip it. The framework works best when you use the minimum structure needed for clarity.
OpenSpec fills a specific gap in OpenCode: it provides a standard format for specifying work before delegating it. You can adopt it incrementally — start with just specs.md for your most complex task() delegations, add proposals for changes that involve trade-off decisions, and add the full archive once you have a few changes completed.
The delta spec format is the key insight. Writing ## ADDED / ## MODIFIED / ## REMOVED before implementation forces you to define scope boundaries that a free-form prompt leaves fuzzy. For a project like this one — a content site with frequent article additions, occasional component changes, and multiple contributors — that clarity alone justifies the overhead.
tasks.md wave decomposition pattern shown above