Skip to Content
OpenSpec
Start

Upgrade to 2.0

What changes in OpenSpec 2.0, and how to move a project over.

Already on 2.0? Upgrade to 2.1 is the short page you need.

To upgrade from 1.x, update the CLI, then run openspec update in each project. OpenSpec refreshes its built-in skills and removes old generated commands. It keeps command files you edited.

update replaces each built-in skill folder in .agents/skills/ whole and keeps no copy. An edit you made inside one, and any file you added to it, is removed without a message. Save them first: Skills you customized. openspec update --dry-run shows what will change.

What changes

1.x2.0
Where skills liveA copy in each tool's own folderOne copy in .agents/skills/, with links for tools that need them
Command files (/opsx:propose)Installed beside the skillsGone. Use the skills, which do the same work
The delivery settingSkills, commands, or bothRetired: everything is skills
Amazon Q DeveloperPrompt files and skillsRetired: it can't load skills. update removes its OpenSpec files; use Kiro

Supported tools shows the new layout and which tools get links.

Upgrade a project

Commit your work first, so you can go back to it. That commit is also the only copy of any edit you made inside a skill in .agents/skills/. git stash can't hold the upgrade itself, because git can't stash a folder that became a link.

1. Update the CLI the way you installed it (Updating).

2. Run update in each project. In your terminal:

openspec update

In a terminal it asks where to keep the skills. Upgrade to 2.1 covers both answers.

3. Commit the result.

Running update again changes nothing.

What update does

  • Project skills: the installer writes to .agents/skills/ and places each skill where the chosen tools can read it. On Windows it uses copies.
  • Old skill copies: the copies earlier versions wrote into each tool's folder are removed.
  • Command files: the command files earlier versions generated are removed.
  • Old commands you edited: update keeps them and lists them for review.
  • Skills OpenSpec installs: refreshed in place, as every 1.x update did. An edit inside one is replaced.
  • Links: never followed out of the project.
  • Outside the project: update changes only your global config, the list of projects OpenSpec keeps on your machine, and old OpenSpec prompts in ~/.codex/prompts/. From 2.1 it also refreshes the global skills, if you installed them. It removes those prompts only with --force or after you confirm.

Old commands and their skills

Each 1.x command has a skill with the same instructions:

1.x command2.0 skill
/opsx:proposeopenspec-propose
/opsx:exploreopenspec-explore
/opsx:applyopenspec-apply-change
/opsx:updateopenspec-update-change
/opsx:syncopenspec-sync-specs
/opsx:archiveopenspec-archive-change
/opsx:newopenspec-new-change
/opsx:continueopenspec-continue-change
/opsx:ffopenspec-ff-change
/opsx:verifyopenspec-verify-change
/opsx:bulk-archiveopenspec-bulk-archive-change
/opsx:onboardopenspec-onboard

You can also ask for the work ("propose a change to add dark mode"). To invoke a skill by name, type /openspec-propose in Claude Code and most other tools, or $openspec-propose in Codex. Supported tools lists the spelling for each tool.

Command files you edited

update removes only command files that match what OpenSpec generated. It keeps one you changed and lists it:

Kept 1 command file that does not match what OpenSpec generated (likely edited):
  .claude/commands/opsx/apply.md
Move anything worth keeping into the skill, then delete by hand.

Your tool may still show a kept file as a command. Delete it once you've moved what you need.

A project set up before 1.0 has older files, such as .claude/commands/openspec/. When they're unchanged from an earlier release, update removes them without asking. Otherwise it asks first, and a non-interactive run leaves them alone. With --force it removes them without asking, edited or not, so back them up first.

Skills you customized

Save edits to built-in skills before updating, along with any file you added inside a built-in skill folder. OpenSpec replaces each of those folders with the instructions from your CLI’s GitHub release tag.

To keep a customization across updates, put it somewhere update doesn't write:

  • Project instructions: context and rules in openspec/config.yaml give the agent your instructions without editing a skill (Project config).
  • A skill of your own: a skill with a different name from any built-in, such as .agents/skills/team-propose/. update never touches it.

The links are committed like any other file. A teammate on Windows needs two settings to check them out as links:

1. Turn on links in git. In your terminal:

git config --global core.symlinks true

Or clone with git clone -c core.symlinks=true <url>.

2. Turn on Developer Mode in Windows settings, so links can be created.

Without these, each link checks out as a small text file. openspec update replaces it with a plain copy of the skill.

Most tools read .agents/skills/ directly. If yours reads only its own folder, Link another tool shows the one command to point it at the shared copy.

Teams on mixed versions

Upgrade the team’s CLIs before switching a repo to global skills. Earlier CLIs only understand project skills. If teammates run different releases against the same installed skills, each update restores the instructions from that CLI’s own version.

Skills you already installed globally

Installed the official skills with npx skills add? Keep that install and run openspec update. It refreshes the built-in workflows for your profile.

Set up global skills by hand? Save any edits and move custom skills to their own names. Remove any links you made from the repo to your home folder before switching. Use openspec init --scope global --tools <id> to set up the tool’s supported paths.

Stay on 1.x

You don't have to upgrade yet. 1.x keeps working as it is. Pin it the way you installed it.

On npm, in your terminal:

npm install -g @fission-ai/openspec@1

With the standalone install, name the release (Install options):

curl -fsSL https://openspec.dev/cli/install.sh | OPENSPEC_VERSION=v1.17.0 sh

On Windows (PowerShell):

$env:OPENSPEC_VERSION = 'v1.17.0'
irm https://openspec.dev/cli/install.ps1 | iex

When openspec update offers to upgrade the CLI, decline. To stop the offer, set OPENSPEC_NO_UPDATE_CHECK=1.

On this page