mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-10-02 05:24:34 +08:00
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) <noreply@anthropic.com>
This commit is contained in:
Clay Good
co-authored by
Claude Opus 5
Claude Opus 5
parent
b2ac6554b0
commit
1bf0706594
+1
-1
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
+50
-27
@@ -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.
|
||||
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. 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.
|
||||
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. 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.
|
||||
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. Ask me which AI coding tool I use, then set up this directory
|
||||
non-interactively: `openspec init --tools <tool-id>`. Run `openspec init
|
||||
--help` for the list of tool ids. Tell me before overwriting any existing
|
||||
file.
|
||||
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. 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.
|
||||
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 <ids>` 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 <ids>
|
||||
|
||||
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.
|
||||
|
||||
@@ -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"
|
||||
|
||||
|
||||
@@ -628,6 +628,16 @@ function FinalCta() {
|
||||
cd your-project && openspec init
|
||||
</div>
|
||||
</div>
|
||||
<p className="mt-4 text-sm text-fd-muted-foreground">
|
||||
Or{' '}
|
||||
<Link
|
||||
href={`${docsRoute}/installation#install-with-your-ai-assistant`}
|
||||
className="underline underline-offset-4 hover:text-fd-foreground"
|
||||
>
|
||||
let your AI assistant install it for you
|
||||
</Link>
|
||||
.
|
||||
</p>
|
||||
<div className="mt-8">
|
||||
<Link
|
||||
href={`${docsRoute}/getting-started`}
|
||||
|
||||
Reference in New Issue
Block a user