From b2ac6554b06b7a72c327cf0798d9bf9afba272eb Mon Sep 17 00:00:00 2001 From: Clay Good Date: Mon, 27 Jul 2026 18:24:46 -0500 Subject: [PATCH 1/5] docs(installation): add an AI-assistant setup prompt Adds a provider-neutral "Install with your AI assistant" section to docs/installation.md with one copyable prompt that detects the runtime and package manager, installs the CLI, runs `openspec init --tools `, and verifies the result. Surfaced from the README Quick Start and the docs map. The manual package-manager instructions stay the source of truth. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 2 ++ docs/README.md | 2 +- docs/installation.md | 39 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 42 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index babff7df44..f2d7a4f859 100644 --- a/README.md +++ b/README.md @@ -137,6 +137,8 @@ cd your-project openspec init ``` +> **Want your AI to do it?** Paste the [setup prompt](docs/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result. + Now talk to your AI: - **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. ([Explore guide](docs/explore.md)) diff --git a/docs/README.md b/docs/README.md index 2e3df67b1c..70a2318395 100644 --- a/docs/README.md +++ b/docs/README.md @@ -45,7 +45,7 @@ That second one matters more than it looks. OpenSpec has two halves: a command l | [Explore First](explore.md) | Use `/opsx:explore` to think through an idea before you commit | | [How Commands Work](how-commands-work.md) | Where slash commands run, what "interactive mode" means, terminal vs chat | | [Core Concepts at a Glance](overview.md) | The whole mental model on one page: specs, changes, deltas, archive | -| [Installation](installation.md) | npm, pnpm, yarn, bun, Nix, and how to verify it worked | +| [Installation](installation.md) | npm, pnpm, yarn, bun, Nix, a prompt that hands setup to your AI assistant, and how to verify it worked | ### Use it day to day diff --git a/docs/installation.md b/docs/installation.md index 3714f187bb..2e669d274e 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -4,6 +4,45 @@ - **Node.js 20.19.0 or higher** — Check your version: `node --version` +## Install with your AI assistant + +Rather not do this by hand? Paste the prompt below into any coding assistant that can run shell commands — Claude Code, Codex, Cursor, Gemini CLI, Copilot, and the rest of the [supported tools](supported-tools.md). It detects your runtime and package manager, installs the CLI, initializes this project, and verifies the result. + +The manual steps below are the source of truth — the prompt just runs them for you. If your assistant gets stuck, do it yourself with [Package Managers](#package-managers). + +```text +Install OpenSpec in this project and set it up for me. + +1. Check that Node.js 20.19.0 or higher is on PATH (`node --version`). If it is + missing or too old, tell me and stop — do not install or switch Node versions + for me. + +2. Detect which package manager this project uses, then install the CLI globally + with it: + npm → npm install -g @fission-ai/openspec@latest + pnpm → pnpm add -g @fission-ai/openspec@latest + yarn → yarn global add @fission-ai/openspec@latest + bun → bun add -g @fission-ai/openspec@latest + Ask me first before running anything with sudo or anything that changes + system-wide configuration. Never edit my shell startup files (.bashrc, + .zshrc, .profile, fish config) — if the global bin directory is not on PATH, + print the line I should add and let me add it. + +3. Ask me which AI coding tool I use, then set up this directory + non-interactively: `openspec init --tools `. Run `openspec init + --help` for the list of tool ids. Tell me before overwriting any existing + file. + +4. Verify, then report back what you found: + - `openspec --version` prints a version + - an `openspec/` directory exists and contains `config.yaml` + - the generated skill and command files for my tool exist — init prints how + many and where; list the actual files + Finish by telling me what to restart or reload before the slash commands work. +``` + +Nothing in the prompt is specific to one vendor: it is plain instructions plus the same commands documented on this page. + ## Package Managers ### npm From 1bf07065944975e5fe324d3f4d577cc46d01c012 Mon Sep 17 00:00:00 2001 From: Clay Good Date: Mon, 27 Jul 2026 18:40:26 -0500 Subject: [PATCH 2/5] docs(installation): harden the AI-assistant prompt and link it from the install paths Adversarial review found the first draft's verify step false-failing on healthy installs and its guardrails unenforceable. The prompt now reports what init actually printed instead of asserting config.yaml and command files (config.yml is equally valid; six tools and delivery=skills correctly generate zero commands), warns that --tools auto-cleans legacy files including opsx-*.md prompts under $HOME, picks the package manager by what's on PATH rather than by lockfile, scopes yarn to 1.x, and stops cleanly on EACCES, a missing pnpm global bin dir, or a version-manager shim. Also links the flow from getting-started, the docs map, troubleshooting, and the website CTA; notes Berry dropped `yarn global`; replaces `npm bin -g` (removed in npm 9) with `npm prefix -g`. Co-Authored-By: Claude Opus 5 (1M context) --- docs/README.md | 2 +- docs/getting-started.md | 2 + docs/installation.md | 85 +++++++++++++++++++++++-------------- docs/troubleshooting.md | 4 +- website/app/(home)/page.tsx | 10 +++++ 5 files changed, 70 insertions(+), 33 deletions(-) diff --git a/docs/README.md b/docs/README.md index 70a2318395..74b066e7bf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,7 +21,7 @@ That second one matters more than it looks. OpenSpec has two halves: a command l **I have a big existing codebase.** You don't document all of it. [Using OpenSpec in an Existing Project](existing-projects.md) shows how to start on real, brownfield code without boiling the ocean. -**I just want to get it working.** [Install](installation.md), run `openspec init`, then read [How Commands Work](how-commands-work.md) so your first slash command lands in the right place. +**I just want to get it working.** [Install](installation.md), run `openspec init`, then read [How Commands Work](how-commands-work.md) so your first slash command lands in the right place. Or hand the setup to your assistant with the [AI-assisted install prompt](installation.md#install-with-your-ai-assistant). **I learn by example.** The [Examples & Recipes](examples.md) page walks through real changes start to finish: a small feature, a bug fix, a refactor, an exploration. diff --git a/docs/getting-started.md b/docs/getting-started.md index caf6bf846b..9eef942ea0 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -24,6 +24,8 @@ 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. +> **Don't want to do the terminal part yourself?** Paste the [setup prompt](installation.md#install-with-your-ai-assistant) into your assistant and it handles both lines, then reports what it created. + > **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](explore.md). ## How It Works diff --git a/docs/installation.md b/docs/installation.md index 2e669d274e..2c17c676da 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -6,42 +6,63 @@ ## Install with your AI assistant -Rather not do this by hand? Paste the prompt below into any coding assistant that can run shell commands — Claude Code, Codex, Cursor, Gemini CLI, Copilot, and the rest of the [supported tools](supported-tools.md). It detects your runtime and package manager, installs the CLI, initializes this project, and verifies the result. +Rather not do this by hand? Paste the prompt below into any coding assistant that can run shell commands — Claude Code, Codex, Cursor, Gemini CLI, Copilot, and the rest of the [supported tools](supported-tools.md). It installs the CLI, initializes this project, and reports back what actually happened. -The manual steps below are the source of truth — the prompt just runs them for you. If your assistant gets stuck, do it yourself with [Package Managers](#package-managers). +The manual steps below are the source of truth — the prompt just runs them for you. If your assistant stops and hands something back, that's by design: it asks before anything privileged and never edits your shell startup files. Finish those bits yourself with [Package Managers](#package-managers) and [Troubleshooting](troubleshooting.md). ```text -Install OpenSpec in this project and set it up for me. - -1. Check that Node.js 20.19.0 or higher is on PATH (`node --version`). If it is - missing or too old, tell me and stop — do not install or switch Node versions - for me. - -2. Detect which package manager this project uses, then install the CLI globally - with it: - npm → npm install -g @fission-ai/openspec@latest - pnpm → pnpm add -g @fission-ai/openspec@latest - yarn → yarn global add @fission-ai/openspec@latest - bun → bun add -g @fission-ai/openspec@latest - Ask me first before running anything with sudo or anything that changes - system-wide configuration. Never edit my shell startup files (.bashrc, - .zshrc, .profile, fish config) — if the global bin directory is not on PATH, - print the line I should add and let me add it. - -3. Ask me which AI coding tool I use, then set up this directory - non-interactively: `openspec init --tools `. Run `openspec init - --help` for the list of tool ids. Tell me before overwriting any existing - file. - -4. Verify, then report back what you found: - - `openspec --version` prints a version - - an `openspec/` directory exists and contains `config.yaml` - - the generated skill and command files for my tool exist — init prints how - many and where; list the actual files - Finish by telling me what to restart or reload before the slash commands work. +Install OpenSpec in this project and set it up for me. Follow these steps in +order, and stop where a step tells you to stop. + +1. RUNTIME. Run `node --version`. OpenSpec needs Node.js 20.19.0 or higher. If + Node is missing or older, say so and stop — don't install Node, switch + versions, or reconfigure my version manager for me. + +2. INSTALL. Use whichever package manager is already on my PATH, preferring npm: + npm install -g @fission-ai/openspec@latest + pnpm add -g @fission-ai/openspec@latest + bun add -g @fission-ai/openspec@latest + yarn global add @fission-ai/openspec@latest (Yarn 1.x only) + Don't pick based on this project's lockfile — a global install has nothing to + do with how this repo's own dependencies are installed. + Stop and ask me first if the install needs sudo or admin rights, fails with a + permissions error, or reports that its global bin directory is missing or + unconfigured. Never edit my shell startup files (.bashrc, .zshrc, .profile, + fish, PowerShell profile), and never run a setup command that edits them for + me — show me the change and let me make it. + +3. PATH. Run `openspec --version`. If the command isn't found, it may just be + missing from this shell: tell me where the package manager installed it and + how to add that directory to PATH for my shell and OS, then stop until I + confirm. If I use a version manager, say so rather than editing PATH around + it: with nvm or fnm the CLI is tied to the Node version that was active when + you installed it, and with asdf or volta a shim may need regenerating. + +4. INITIALIZE. Ask me which AI coding tool or tools I use and map each to an id + from `openspec init --help` (Copilot is `github-copilot`, Zoo Code is + `roocode`). `--tools` takes a comma-separated list, so name all of them. + `openspec init --tools ` deletes leftovers from older OpenSpec versions + automatically, without asking — including `opsx-*.md` prompt files in my home + directory (Codex keeps them in ~/.codex/prompts). Before you run it, look for + those: `.../commands/openspec/` folders, OpenSpec marker blocks in files like + CLAUDE.md or AGENTS.md, and home-directory `opsx-*.md` prompts. List whatever + you find and wait for my go-ahead. An existing `openspec/` folder is not a + problem — init refreshes it and leaves my specs and changes alone. + Confirm I'm in the right folder too: init creates `openspec/` wherever it + runs, including inside a monorepo package. + Then run: openspec init --tools + +5. REPORT. Don't assume what should exist — tell me what init actually printed: + how many skills and/or commands it created and where, the config file line, + any "Setup required" note, and what to restart or reload. Some tools are + skills-only and correctly create zero command files, so missing commands is + not a failure on its own. If init said nothing was generated, relay the fix + it suggested instead of retrying. Finish by telling me how to invoke OpenSpec + in my tool — slash commands like /opsx:propose for most tools, a skill + invocation for skills-only ones. ``` -Nothing in the prompt is specific to one vendor: it is plain instructions plus the same commands documented on this page. +Nothing in the prompt is vendor-specific: it's plain instructions plus the same commands documented on this page. It works on macOS, Linux, and Windows, and it deliberately stops rather than improvising when a step needs your permission. Your assistant does need to be able to run shell commands — a few IDE integrations can't. ## Package Managers @@ -63,6 +84,8 @@ pnpm add -g @fission-ai/openspec@latest yarn global add @fission-ai/openspec@latest ``` +Yarn 2 and later (Berry) removed the `global` command. On those versions, install OpenSpec with npm, pnpm, or bun instead — a global CLI doesn't need to share your project's package manager. + ### bun Bun can install OpenSpec globally, but OpenSpec currently runs on Node.js. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 4d901e0717..6eb61b46de 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -13,7 +13,9 @@ npm install -g @fission-ai/openspec@latest openspec --version ``` -If it installed but still isn't found, your global npm bin directory probably isn't on your `PATH`. Run `npm bin -g` to see where global binaries live, and make sure that path is in your shell profile. +If it installed but still isn't found, your global npm bin directory probably isn't on your `PATH`. Run `npm prefix -g` to see where global packages live — binaries land in that directory's `bin/` — and make sure that path is in your shell profile. (`npm bin -g` was removed in npm 9.) + +If you used the [AI-assisted install](installation.md#install-with-your-ai-assistant), this is the expected hand-off point: that prompt tells your assistant to show you the `PATH` change rather than edit your shell startup files itself. ### "Requires Node.js 20.19.0 or higher" diff --git a/website/app/(home)/page.tsx b/website/app/(home)/page.tsx index 3c8a4d9308..b5bd1928f2 100644 --- a/website/app/(home)/page.tsx +++ b/website/app/(home)/page.tsx @@ -628,6 +628,16 @@ function FinalCta() { cd your-project && openspec init +

+ Or{' '} + + let your AI assistant install it for you + + . +

Date: Mon, 27 Jul 2026 18:59:14 -0500 Subject: [PATCH 3/5] docs(installation): close the gaps two trial runs found in the setup prompt Two assistants (different models) ran the prompt end to end in sandboxes, one on Cursor and one on Codex with deliberately messy legacy files. Both finished with a working, verified setup. Their findings: - Cursor's commands are `/opsx-propose`, not `/opsx:propose`. The prompt named the colon form and init's summary agrees with it, so the assistant would have handed back a command the tool doesn't match. It now takes the spelling from the files init created. - "List whatever you find and wait for my go-ahead" was undefined when the list is empty, i.e. on every fresh project. It now says to carry on. - `openspec --version` succeeding doesn't prove it's the copy just installed; an older one earlier on PATH shadows it. Step 3 now compares the two. - The request asked for confirmation before privileged/global changes; the prompt only stopped reactively on failure. It now shows the global install command and waits. Co-Authored-By: Claude Opus 5 (1M context) --- docs/installation.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 2c17c676da..f3e6fb6903 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -24,8 +24,10 @@ order, and stop where a step tells you to stop. bun add -g @fission-ai/openspec@latest yarn global add @fission-ai/openspec@latest (Yarn 1.x only) Don't pick based on this project's lockfile — a global install has nothing to - do with how this repo's own dependencies are installed. - Stop and ask me first if the install needs sudo or admin rights, fails with a + do with how this repo's own dependencies are installed. Show me the exact + command and let me confirm before you run it; this installs software outside + the project, and I may want a different package manager to own it. + Stop and ask me again if the install needs sudo or admin rights, fails with a permissions error, or reports that its global bin directory is missing or unconfigured. Never edit my shell startup files (.bashrc, .zshrc, .profile, fish, PowerShell profile), and never run a setup command that edits them for @@ -34,9 +36,12 @@ order, and stop where a step tells you to stop. 3. PATH. Run `openspec --version`. If the command isn't found, it may just be missing from this shell: tell me where the package manager installed it and how to add that directory to PATH for my shell and OS, then stop until I - confirm. If I use a version manager, say so rather than editing PATH around - it: with nvm or fnm the CLI is tied to the Node version that was active when - you installed it, and with asdf or volta a shim may need regenerating. + confirm. If it prints an older version than the one the install just + reported, an earlier copy is shadowing it on PATH — tell me both versions + instead of continuing. If I use a version manager, say so rather than editing + PATH around it: with nvm or fnm the CLI is tied to the Node version that was + active when you installed it, and with asdf or volta a shim may need + regenerating. 4. INITIALIZE. Ask me which AI coding tool or tools I use and map each to an id from `openspec init --help` (Copilot is `github-copilot`, Zoo Code is @@ -46,8 +51,9 @@ order, and stop where a step tells you to stop. directory (Codex keeps them in ~/.codex/prompts). Before you run it, look for those: `.../commands/openspec/` folders, OpenSpec marker blocks in files like CLAUDE.md or AGENTS.md, and home-directory `opsx-*.md` prompts. List whatever - you find and wait for my go-ahead. An existing `openspec/` folder is not a - problem — init refreshes it and leaves my specs and changes alone. + you find and wait for my go-ahead; if you find nothing, say so and carry on + without asking. An existing `openspec/` folder is not a problem — init + refreshes it and leaves my specs and changes alone. Confirm I'm in the right folder too: init creates `openspec/` wherever it runs, including inside a monorepo package. Then run: openspec init --tools @@ -58,8 +64,10 @@ order, and stop where a step tells you to stop. skills-only and correctly create zero command files, so missing commands is not a failure on its own. If init said nothing was generated, relay the fix it suggested instead of retrying. Finish by telling me how to invoke OpenSpec - in my tool — slash commands like /opsx:propose for most tools, a skill - invocation for skills-only ones. + in my tool, and take the exact spelling from the files init created rather + than from its summary line: the punctuation differs per tool (/opsx:propose + in some, /opsx-propose in others), and skills-only tools have no slash + command at all. ``` Nothing in the prompt is vendor-specific: it's plain instructions plus the same commands documented on this page. It works on macOS, Linux, and Windows, and it deliberately stops rather than improvising when a step needs your permission. Your assistant does need to be able to run shell commands — a few IDE integrations can't. From 2e96ffe2d09d34c30a52913f3be25611cc19cca1 Mon Sep 17 00:00:00 2001 From: Clay Good Date: Mon, 27 Jul 2026 18:59:20 -0500 Subject: [PATCH 4/5] docs: correct the core profile to six workflows and the tool count to 30+ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two long-standing inaccuracies, found while verifying the install docs. `CORE_WORKFLOWS` (src/core/profiles.ts:14) is six — propose, explore, apply, update, sync, archive — and a real `openspec init` generates six skills and six commands. Eleven pages listed five, omitting `update`; migration-guide listed four and filed `sync` under the expanded set. supported-tools also dropped `update` from the full workflow-ID list. docs/commands.md was already right and is untouched, as are flow diagrams that show a typical path rather than a profile roster. The tool count was written as both "25+" and "30+" against 34 supported tools. Now consistently "30+". Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 2 +- docs/README.md | 2 +- docs/cli.md | 2 +- docs/examples.md | 2 +- docs/explore.md | 2 +- docs/faq.md | 4 ++-- docs/getting-started.md | 2 +- docs/glossary.md | 2 +- docs/how-commands-work.md | 3 ++- docs/migration-guide.md | 9 ++++++--- docs/opsx.md | 2 +- docs/supported-tools.md | 5 +++-- docs/workflows.md | 1 + 13 files changed, 22 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index f2d7a4f859..ed3c1aafea 100644 --- a/README.md +++ b/README.md @@ -147,7 +147,7 @@ Now talk to your AI: Both are in the default profile. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`. > [!NOTE] -> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 25+ tools and growing. +> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 30+ tools and growing. > > Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md). diff --git a/docs/README.md b/docs/README.md index 74b066e7bf..a026250201 100644 --- a/docs/README.md +++ b/docs/README.md @@ -75,7 +75,7 @@ That second one matters more than it looks. OpenSpec has two halves: a command l |-----|-------------------| | [Customization](customization.md) | Project config, custom schemas, shared context | | [Multi-Language](multi-language.md) | Generate artifacts in languages other than English | -| [Supported Tools](supported-tools.md) | The 25+ AI tools OpenSpec integrates with, and where files land | +| [Supported Tools](supported-tools.md) | The 30+ AI tools OpenSpec integrates with, and where files land | ### When you need help diff --git a/docs/cli.md b/docs/cli.md index 3b7f3acfbf..d3e9a19391 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -82,7 +82,7 @@ These options work with all commands: Initialize OpenSpec in your project. Creates the folder structure and configures AI tool integrations. -Default behavior uses global config defaults: profile `core`, delivery `both`, workflows `propose, explore, apply, sync, archive`. +Default behavior uses global config defaults: profile `core`, delivery `both`, workflows `propose, explore, apply, update, sync, archive`. ``` openspec init [path] [options] diff --git a/docs/examples.md b/docs/examples.md index 306c7502f7..80d85611af 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,6 +1,6 @@ # Examples & Recipes -Real changes, start to finish. Each recipe shows the commands you'd type and what you'd see back, so you can match your situation to a pattern and copy it. These use the default **core** commands (`propose`, `explore`, `apply`, `sync`, `archive`); where the expanded set helps, it's noted. +Real changes, start to finish. Each recipe shows the commands you'd type and what you'd see back, so you can match your situation to a pattern and copy it. These use the default **core** commands (`propose`, `explore`, `apply`, `update`, `sync`, `archive`); where the expanded set helps, it's noted. A reminder before you start: slash commands like `/opsx:propose` go in your **AI assistant's chat**, and `openspec` commands go in your **terminal**. If that's new, read [How Commands Work](how-commands-work.md) first. In the transcripts below, `You:` and `AI:` are the chat, and lines starting with `$` are the terminal. diff --git a/docs/explore.md b/docs/explore.md index 6b9493f204..432b0c6272 100644 --- a/docs/explore.md +++ b/docs/explore.md @@ -38,7 +38,7 @@ That's the point. Exploring costs you nothing and commits you to nothing. You ca ## It's already installed -Good news: `/opsx:explore` ships in the default **core** profile, right alongside `propose`, `apply`, `sync`, and `archive`. You don't need to enable anything. If OpenSpec is set up in your project, explore is ready in your AI chat. (As with all `/opsx:*` commands, you type it in your assistant's chat, not the terminal. See [How Commands Work](how-commands-work.md).) +Good news: `/opsx:explore` ships in the default **core** profile, right alongside `propose`, `apply`, `update`, `sync`, and `archive`. You don't need to enable anything. If OpenSpec is set up in your project, explore is ready in your AI chat. (As with all `/opsx:*` commands, you type it in your assistant's chat, not the terminal. See [How Commands Work](how-commands-work.md).) ## A full example diff --git a/docs/faq.md b/docs/faq.md index 9b9198fd32..a76da98823 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -22,7 +22,7 @@ Existing codebases are the main event. OpenSpec is brownfield-first: you do not ### Is it tied to one AI tool? -No. OpenSpec works with 25+ assistants, including Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Codex, and more. The full list and per-tool details are in [Supported Tools](supported-tools.md). +No. OpenSpec works with 30+ assistants, including Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Codex, and more. The full list and per-tool details are in [Supported Tools](supported-tools.md). ## Running commands @@ -66,7 +66,7 @@ Explore to think it through, propose to draft the plan, apply to build it, archi ### What are `core` and expanded profiles? -A profile decides which slash commands get installed. **Core** (the default) gives you `propose`, `explore`, `apply`, `sync`, `archive`. The **expanded** set adds `new`, `continue`, `ff`, `verify`, `bulk-archive`, and `onboard` for finer control. Switch with `openspec config profile`, then apply with `openspec update`. +A profile decides which slash commands get installed. **Core** (the default) gives you `propose`, `explore`, `apply`, `update`, `sync`, `archive`. The **expanded** set adds `new`, `continue`, `ff`, `verify`, `bulk-archive`, and `onboard` for finer control. Switch with `openspec config profile`, then apply with `openspec update`. ### Do I need to run `/opsx:sync`? diff --git a/docs/getting-started.md b/docs/getting-started.md index 9eef942ea0..745efd62ed 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -47,7 +47,7 @@ Start with `/opsx:explore` when you're figuring out what to do, or jump straight /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`. +The default global profile is `core`, which includes `propose`, `explore`, `apply`, `update`, `sync`, and `archive`. You can enable the expanded workflow commands with `openspec config profile` and then `openspec update`. ## What OpenSpec Creates diff --git a/docs/glossary.md b/docs/glossary.md index 397cbe36da..345125f38a 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -54,7 +54,7 @@ Terms are grouped by topic, then alphabetized within each group. **Command file.** A per-tool slash command file (`.../commands/opsx-*`). The older delivery mechanism, still supported alongside skills. You rarely touch these directly. -**Profile.** The set of slash commands installed in your project. **Core** (the default) is `propose`, `explore`, `apply`, `sync`, `archive`. The **expanded** set adds `new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`. Change it with `openspec config profile`. +**Profile.** The set of slash commands installed in your project. **Core** (the default) is `propose`, `explore`, `apply`, `update`, `sync`, `archive`. The **expanded** set adds `new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`. Change it with `openspec config profile`. **Delivery.** Whether OpenSpec installs skills, command files, or both for your tools. Configured globally and applied with `openspec update`. diff --git a/docs/how-commands-work.md b/docs/how-commands-work.md index 175c5a701a..577d6b6d01 100644 --- a/docs/how-commands-work.md +++ b/docs/how-commands-work.md @@ -61,7 +61,7 @@ One thing that *is* genuinely interactive lives in the terminal: `openspec view` ## Why this split exists -It's worth understanding, because it explains why OpenSpec works with 25+ different AI tools. +It's worth understanding, because it explains why OpenSpec works with 30+ different AI tools. The CLI is the **engine**. It knows the rules: what a change folder looks like, which artifacts depend on which, how to merge a delta spec into your source of truth. It's the same everywhere. @@ -116,6 +116,7 @@ By default, OpenSpec installs the **core** set of slash commands: - `/opsx:explore`: think through an idea with the AI before committing to a change (great first step when you're unsure) - `/opsx:propose`: create a change and draft all its planning artifacts in one step - `/opsx:apply`: build the change by working through its task list +- `/opsx:update`: revise a change's planning artifacts and keep them coherent - `/opsx:sync`: merge a change's spec updates into your main specs (usually automatic) - `/opsx:archive`: finish a change and file it away diff --git a/docs/migration-guide.md b/docs/migration-guide.md index 98f8579cbd..477aa5c7af 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -8,7 +8,7 @@ OPSX replaces the old phase-locked workflow with a fluid, action-based approach. | Aspect | Legacy | OPSX | |--------|--------|------| -| **Commands** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | Default: `/opsx:propose`, `/opsx:apply`, `/opsx:sync`, `/opsx:archive` (expanded workflow commands optional) | +| **Commands** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | Default: `/opsx:propose`, `/opsx:explore`, `/opsx:apply`, `/opsx:update`, `/opsx:sync`, `/opsx:archive` (expanded workflow commands optional) | | **Workflow** | Create all artifacts at once | Create incrementally or all at once—your choice | | **Going back** | Awkward phase gates | Natural—update any artifact anytime | | **Customization** | Fixed structure | Schema-driven, fully hackable | @@ -85,7 +85,7 @@ Don't worry about getting it perfect. We're still learning what works best here, Both `openspec init` and `openspec update` detect legacy files and guide you through the same cleanup process. Use whichever fits your situation: -- New installs default to profile `core` (`propose`, `explore`, `apply`, `sync`, `archive`). +- New installs default to profile `core` (`propose`, `explore`, `apply`, `update`, `sync`, `archive`). - Migrated installs preserve your previously installed workflows by writing a `custom` profile when needed. ### Using `openspec init` @@ -290,6 +290,8 @@ Command availability is profile-dependent: | `/opsx:propose` | Create a change and generate planning artifacts in one step | | `/opsx:explore` | Think through ideas with no structure | | `/opsx:apply` | Implement tasks from tasks.md | +| `/opsx:update` | Revise a change's planning artifacts and keep them coherent | +| `/opsx:sync` | Merge delta specs into main specs | | `/opsx:archive` | Finalize and archive the change | **Expanded workflow (custom selection):** @@ -300,7 +302,6 @@ Command availability is profile-dependent: | `/opsx:continue` | Create the next artifact (one at a time) | | `/opsx:ff` | Fast-forward—create planning artifacts at once | | `/opsx:verify` | Validate implementation matches specs | -| `/opsx:sync` | Merge delta specs into main specs | | `/opsx:bulk-archive` | Archive multiple changes at once | | `/opsx:onboard` | Guided end-to-end onboarding workflow | @@ -566,7 +567,9 @@ project/ │ ├── openspec-propose/ # default core profile │ ├── openspec-explore/ │ ├── openspec-apply-change/ +│ ├── openspec-update-change/ │ ├── openspec-sync-specs/ +│ ├── openspec-archive-change/ │ └── ... # expanded profile adds new/continue/ff/etc. ├── CLAUDE.md # OpenSpec markers removed, your content preserved └── AGENTS.md # OpenSpec markers removed, your content preserved diff --git a/docs/opsx.md b/docs/opsx.md index e396890add..cd93e11371 100644 --- a/docs/opsx.md +++ b/docs/opsx.md @@ -65,7 +65,7 @@ openspec init This creates skills in `.claude/skills/` (or equivalent) that AI coding assistants auto-detect. -By default, OpenSpec uses the `core` workflow profile (`propose`, `explore`, `apply`, `sync`, `archive`). If you want the expanded workflow commands (`new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`), configure them with `openspec config profile` and apply with `openspec update`. +By default, OpenSpec uses the `core` workflow profile (`propose`, `explore`, `apply`, `update`, `sync`, `archive`). If you want the expanded workflow commands (`new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`), configure them with `openspec config profile` and apply with `openspec update`. During setup, you'll be prompted to create a **project config** (`openspec/config.yaml`). This is optional but recommended. diff --git a/docs/supported-tools.md b/docs/supported-tools.md index 7fb5c838e7..fc6b261a4c 100644 --- a/docs/supported-tools.md +++ b/docs/supported-tools.md @@ -15,6 +15,7 @@ By default, OpenSpec uses the `core` profile, which includes: - `propose` - `explore` - `apply` +- `update` - `sync` - `archive` @@ -87,9 +88,9 @@ openspec init --profile core OpenSpec installs workflow artifacts based on selected workflows: -- **Core profile (default):** `propose`, `explore`, `apply`, `sync`, `archive` +- **Core profile (default):** `propose`, `explore`, `apply`, `update`, `sync`, `archive` - **Custom selection:** any subset of all workflow IDs: - `propose`, `explore`, `new`, `continue`, `apply`, `ff`, `sync`, `archive`, `bulk-archive`, `verify`, `onboard` + `propose`, `explore`, `new`, `continue`, `apply`, `update`, `ff`, `sync`, `archive`, `bulk-archive`, `verify`, `onboard` In other words, skill/command counts are profile-dependent and delivery-dependent, not fixed. diff --git a/docs/workflows.md b/docs/workflows.md index 82f1e1efa2..b63f7f7491 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -36,6 +36,7 @@ New installs default to `core`, which provides: - `/opsx:explore` - `/opsx:propose` - `/opsx:apply` +- `/opsx:update` - `/opsx:sync` - `/opsx:archive` From f14361fa56886deec1afa5fb32dfc6fcb4e09030 Mon Sep 17 00:00:00 2001 From: Clay Good Date: Mon, 27 Jul 2026 19:09:19 -0500 Subject: [PATCH 5/5] docs: address CodeRabbit review on the AI-assisted install flow - Windows puts global npm binaries directly in the prefix directory, not in a `bin/` subdirectory; the troubleshooting fix I added said otherwise. - Tell the assistant to stop rather than improvise when none of npm/pnpm/yarn/bun is available, and point Nix users at the Nix section. - Drop the blockquote on the getting-started pointer so it isn't a second `>` block adjacent to the explore callout (markdownlint MD028). Two other comments were already fixed in 1bf0706 (stop on a PATH problem; map the user's answer to an exact tool id). Co-Authored-By: Claude Opus 5 (1M context) --- docs/getting-started.md | 2 +- docs/installation.md | 9 ++++++--- docs/troubleshooting.md | 2 +- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 745efd62ed..36cd97cbb6 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -24,7 +24,7 @@ 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. -> **Don't want to do the terminal part yourself?** Paste the [setup prompt](installation.md#install-with-your-ai-assistant) into your assistant and it handles both lines, then reports what it created. +**Don't want to do the terminal part yourself?** Paste the [setup prompt](installation.md#install-with-your-ai-assistant) into your assistant and it handles both lines, then reports what it created. > **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](explore.md). diff --git a/docs/installation.md b/docs/installation.md index f3e6fb6903..e045e4d6e3 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -24,9 +24,12 @@ order, and stop where a step tells you to stop. bun add -g @fission-ai/openspec@latest yarn global add @fission-ai/openspec@latest (Yarn 1.x only) Don't pick based on this project's lockfile — a global install has nothing to - do with how this repo's own dependencies are installed. Show me the exact - command and let me confirm before you run it; this installs software outside - the project, and I may want a different package manager to own it. + do with how this repo's own dependencies are installed. If none of those four + is available, stop and tell me — don't improvise an install. (If I'm on Nix, + point me at the Nix section of the OpenSpec installation docs instead.) + Show me the exact command and let me confirm before you run it; this installs + software outside the project, and I may want a different package manager to + own it. Stop and ask me again if the install needs sudo or admin rights, fails with a permissions error, or reports that its global bin directory is missing or unconfigured. Never edit my shell startup files (.bashrc, .zshrc, .profile, diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 6eb61b46de..b0a56d28c3 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -13,7 +13,7 @@ npm install -g @fission-ai/openspec@latest openspec --version ``` -If it installed but still isn't found, your global npm bin directory probably isn't on your `PATH`. Run `npm prefix -g` to see where global packages live — binaries land in that directory's `bin/` — and make sure that path is in your shell profile. (`npm bin -g` was removed in npm 9.) +If it installed but still isn't found, your global npm bin directory probably isn't on your `PATH`. Run `npm prefix -g` to see where global packages live: on macOS and Linux the binaries are in that directory's `bin/`, and on Windows they sit directly in it. Make sure that path is on your `PATH`. (`npm bin -g` was removed in npm 9.) If you used the [AI-assisted install](installation.md#install-with-your-ai-assistant), this is the expected hand-off point: that prompt tells your assistant to show you the `PATH` change rather than edit your shell startup files itself.