Setting Up OpenSpec with OpenCode: A Practical Guide

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.

What We Are Building

By the end of this guide, you will have:

1. OpenSpec installed and configured in your project
2. An openspec/changes/ directory with at least one complete change artifact
3. A workflow that uses OpenSpec's OPSX protocol before every significant task() delegation
4. An archive of decisions you can search months later

The examples are specific to OpenCode, but the workflow works with any of the 20+ tools OpenSpec supports.

Install OpenSpec

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)

The OPSX Protocol in OpenCode

OpenSpec's OPSX (Open-Prompt Specification Exchange) protocol defines three commands. Here is how each maps to an OpenCode action:

/opsx:propose — Create the Spec

This 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?