docs(installation): add an AI-assistant setup prompt - #1466
Merged
Conversation
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 <id>`, 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) <noreply@anthropic.com>
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
🚧 Files skipped from review as they are similar to previous changes (3)
📝 WalkthroughWalkthroughThe documentation adds a copy/paste workflow for AI assistants to install the OpenSpec CLI, initialize it with selected tools, and verify generated artifacts. Installation compatibility and troubleshooting guidance are updated, and core workflow references now include ChangesDocumentation updates
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Deploying openspec-docs with
|
| Latest commit: |
f14361f
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://d7340397.openspec-docs.pages.dev |
| Branch Preview URL: | https://docs-llm-assisted-install.openspec-docs.pages.dev |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/installation.md`:
- Around line 31-34: Update the installation instructions in step 3 to require
mapping the user’s display-name response to an exact tool ID from openspec init
--help, then confirm the canonical ID before constructing the non-interactive
openspec init command. Preserve the existing overwrite warning.
- Around line 20-25: Update the package-manager detection instructions to
explicitly handle Nix projects by directing the user to the documented Nix
installation section, and stop rather than selecting npm, pnpm, yarn, or bun
when the manager is unsupported or cannot be identified.
- Around line 26-29: Update the PATH-handling instructions in the installation
guidance so the assistant stops before running openspec init or verification
when the global bin directory is missing from PATH. Require resuming only after
the user updates PATH, or alternatively invoke the installed binary through the
package manager.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: bf11740f-7cb0-4d7d-8d07-7494e0ada5dd
📒 Files selected for processing (3)
README.mddocs/README.mddocs/installation.md
…he 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>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/getting-started.md`:
- Line 28: Remove the standalone empty blockquote marker on line 28 in the
documentation, while preserving the blank separation between the two adjacent
callouts.
In `@docs/troubleshooting.md`:
- Line 16: Update the global npm PATH guidance in the troubleshooting
documentation to separate Unix-like and Windows instructions. Keep the npm
prefix lookup for both platforms, but direct Unix users to the prefix’s bin
subdirectory and Windows users to the prefix itself, including
platform-appropriate shell profile guidance.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: c6dc19c4-bb13-41b0-afa7-8a3335c33ec5
📒 Files selected for processing (5)
docs/README.mddocs/getting-started.mddocs/installation.mddocs/troubleshooting.mdwebsite/app/(home)/page.tsx
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/README.md
- docs/installation.md
…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) <noreply@anthropic.com>
… 30+ 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) <noreply@anthropic.com>
- 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) <noreply@anthropic.com>
alfred-openspec
approved these changes
Jul 28, 2026
alfred-openspec
left a comment
alfred-openspec
left a comment
Collaborator
There was a problem hiding this comment.
Reviewed at f14361f. The provider-neutral install prompt safely stops for runtime, privilege, PATH, version-manager, package-manager, legacy-cleanup, and monorepo decisions; the Windows npm prefix correction is now accurate. Vocabulary, lint, the 26-page/87-route docs build, typecheck, cross-platform suite, Cloudflare, CodeQL, audit, dependency review, and release tracking all pass.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Status
Ready for review. Docs plus one line of website copy — no CLI, template, or test changes.
What was missing
Installing OpenSpec meant reading the manual flow and translating it yourself: pick a package manager, install globally, run
openspec init, then figure out whether it worked. Plenty of people would rather hand that to the coding agent already sitting in their terminal, but the docs gave them nothing to paste.What it does
Adds an Install with your AI assistant section to docs/installation.md with one copyable, provider-neutral prompt. Five steps: check Node 20.19.0+ and stop if the runtime is wrong → show the global install command and wait for your okay → confirm the CLI on PATH is the one just installed → ask which tool(s) and run
openspec init --tools <ids>→ report what init actually printed.The manual npm/pnpm/yarn/bun/Nix instructions stay the source of truth. They sit directly below the new section, which links back to them and to Troubleshooting for anything the assistant hands off.
Discovery, at every place installation is taught: README Quick Start, the docs map, Getting Started, Troubleshooting (the PATH entry — the flow's designed hand-off point), and the website's final CTA.
Proof it works
Two assistants ran the prompt end to end, in sandboxes, on different models and different tools. Both finished with a working, verified setup:
.claude/commands/openspec/, an OpenSpec marker block in CLAUDE.md,~/.codex/prompts/opsx-propose.md, and apnpm-lock.yamlplanted to mislead.cursor/,openspec/config.yaml.codex/, 0 commands — correctly reported as success, not failuremy-own.mdalonepnpm-lock.yamlTheir findings are fixed in
06065a4: Cursor's commands are/opsx-propose, not/opsx:propose(the prompt and init's own summary both said the colon form, so the assistant would have handed back a command Cursor doesn't match — it now reads the spelling off the generated files); "wait for my go-ahead" was undefined when nothing is found, i.e. on every fresh project;openspec --versionsucceeding doesn't prove it's the copy just installed; and the global install now asks first, which the original request called for.Three adversarial reviews ran against the first draft. Everything below was reproduced against the built CLI in isolated temp dirs, and each fix is in the diff:
openspec/config.yaml, but an existingconfig.ymlis honored and never renamed — false failure on a healthy projectdelivery=skillsfor any tooldelivery=commands+ a skills-only tool creates nothing at all, and init prints the fix--toolsdisables prompting, so legacy cleanup runs unattended — including deletingopsx-*.mdunder~/.codex/promptsopenspec/is a harmless refreshyarn global addwas removed in Yarn 2+ (Berry)(Yarn 1.x only); the yarn section now says sopnpm add -gdead-ends withoutPNPM_HOME, and the standard fix (pnpm setup) edits the shell rc files the prompt forbids touchingEACCESon system Node — the common Linux setup — had no legal moveopenspec/wherever it runs, including inside a monorepo package"--toolstakes a comma-separated list; the prompt asked for one toolAlso verified:
github-copilotandroocodeare real ids;openspec init --helpreally prints the id list (generated fromAI_TOOLS, so it can't drift); a wrong id fails loudly with the full list; re-running init preserves existing specs; every command in the prompt matches the manual sections byte for byte.Build and tests:
pnpm run buildandpnpm run types:checkinwebsite/pass (26 doc pages, 87 routes). Theinstall-with-your-ai-assistantanchor renders, and all four in-repo links to it resolve in the built HTML.test/vocabulary-sweep.test.tspasses.website/content/docs/andwebsite/out/are generated and git-ignored.Second commit: two doc inaccuracies found along the way
2e96ffeis a separate, independently reviewable commit — check it againstsrc/core/profiles.ts:14andsrc/core/config.ts:CORE_WORKFLOWSispropose, explore, apply, update, sync, archive, and a realopenspec initgenerates six skills and six commands. Eleven pages listed five, omittingupdate.migration-guide.mdlisted four and filedsyncunder the expanded set.supported-tools.mdalso droppedupdatefrom the full workflow-ID list.docs/commands.mdwas already correct and is untouched, as are flow diagrams that show a typical path rather than a profile roster.Notes
nix runneeds no install step. The Nix section is untouched.npm bin -gin Troubleshooting, which was removed in npm 9 (confirmed working on npm 8, gone on npm 9 — nownpm prefix -g).🤖 Generated with Claude Code
Summary by CodeRabbit
update; refreshed related examples, migration guidance, FAQ, glossary, and supported-tools info.