bb1f18c483
* docs: comprehensive documentation overhaul (home, mental model, command location, FAQ, glossary, troubleshooting, recipes) Addresses #1228 (docs are fragmented and hard to discover). Additive, docs-only. The single sharpest gap from the issue thread was that nobody explains where slash commands run, hence the new "How Commands Work" page. New docs: - docs/README.md documentation home / index that maps every doc - docs/how-commands-work.md where /opsx:* (chat) vs openspec (terminal) run; "interactive mode" answered - docs/overview.md core concepts at a glance, one page - docs/faq.md consolidated common questions - docs/glossary.md every term in one place - docs/troubleshooting.md concrete fixes for concrete failures - docs/examples.md real changes start to finish (recipes) Small additive edits: - docs/getting-started.md "where do I type this?" callout + first-five-minutes + richer Next Steps - README.md Docs list points at the new home and key new pages Voice: warm, plain, bottom-line-up-front; no em-dashes in prose. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: make /opsx:explore front and center, plus general polish Per maintainer feedback (Tabish): "the docs in general need some work, alongside making the explore option a lot more front and center." explore ships in the default core profile but every doc led with propose and treated explore as a footnote for "unclear requirements." This reframes the canonical loop as explore -> propose -> apply -> archive and gives explore real prominence. - docs/explore.md (new): dedicated "Explore First" guide. When to use it, what it does/doesn't, a full transcript, handoff to propose, tradeoffs. - getting-started.md: explore added to the flow and first-five-minutes, with a featured callout and Next Steps entry. - overview.md: explore featured in the loop and next-links. - docs/README.md: explore in the opening, pick-your-path, 30-second version, and the doc map. - how-commands-work.md: explore leads the command list with a "good rhythm" note and an optional step in the clean-first-run example. - workflows.md: new first-class "Start by exploring" pattern in the default section (was buried under expanded mode); quick-reference row strengthened. - commands.md / faq.md / glossary.md: explore featured as the place to start. - examples.md: top callout pointing at the explore recipe. - README.md: explore opens the "See it in action" demo and Quick Start, and is added to the Docs list. Docs-only and additive. No em-dashes in prose; links verified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: close recurring gaps (existing projects, editing changes, uninstall, context limits) + sync tool list Sweep of open issues and discussions surfaced several questions good docs should answer but didn't. This adds the missing guides and fixes a stale list. New guides: - docs/existing-projects.md: adopting OpenSpec on a large brownfield codebase without documenting everything up front (addresses #510, #1100, #176). Delta-first framing, first-change walkthrough, onboard, importing existing requirements docs, domain organization, monorepo/workspace pointers. - docs/editing-changes.md: how to edit any artifact, update a proposal/spec after starting, go back after implementing, and reconcile manual code edits (addresses #684, #976, #355, #1188, #169, #1206). Enhancements: - installation.md: Updating + Uninstalling sections (addresses #308). - faq.md: new entries for existing codebases, editing artifacts, going back, reconciling manual edits, context limits / long sessions, and uninstalling (addresses #257 among others). - cli.md: --tools list now includes `vibe` and matches AI_TOOLS in src/core/config.ts, with a note pointing at the source (fixes #1213). - Wired the new guides into the docs home, getting-started, and the README. Docs-only and additive. No em-dashes in prose; links and section anchors verified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: reconcile coordinate-across-repos docs with the stores model The merge with main pulled in the stores rename (#1190), which retired the workspaces/initiatives/context-store vocabulary and deleted docs/workspaces-beta/. This updates the three docs still describing the old model so they match the new stores model, fixing the vocabulary-sweep test and dead links: - glossary.md: Workspace/Link/Context store/Initiative -> Store/Reference/ Working context/Workset; link to stores-beta/user-guide.md - README.md: replace deleted workspaces-beta/* links with the Stores User Guide and Agent Contract - existing-projects.md: reframe the multi-repo section as stores; drop the dead concepts.md#coordination-workspaces anchor Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: TabishB <tabishbidiwale@gmail.com> Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>
2.9 KiB
Installation
Prerequisites
- Node.js 20.19.0 or higher — Check your version:
node --version
Package Managers
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 can install OpenSpec globally, but OpenSpec currently runs on Node.js.
You still need Node.js 20.19.0 or higher available on PATH.
bun add -g @fission-ai/openspec@latest
Nix
Run OpenSpec directly without installation:
nix run github:Fission-AI/OpenSpec -- init
Or install to your profile:
nix profile install github:Fission-AI/OpenSpec
Or add to your development environment in flake.nix:
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
openspec.url = "github:Fission-AI/OpenSpec";
};
outputs = { nixpkgs, openspec, ... }: {
devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
buildInputs = [ openspec.packages.x86_64-linux.default ];
};
};
}
Verify Installation
openspec --version
Updating
Upgrade the package, then refresh each project's generated files:
npm install -g @fission-ai/openspec@latest # or pnpm/yarn/bun equivalent
openspec update # run inside each project
openspec update regenerates the skill and command files for the tools you've configured, so your slash commands stay current with the installed version.
Uninstalling
There's no openspec uninstall command, because OpenSpec is just a global package plus some files in your project. Removing it is a few manual steps, and nothing here touches your source code.
1. Remove the global package:
npm uninstall -g @fission-ai/openspec # or: pnpm rm -g / yarn global remove / bun rm -g
2. Remove OpenSpec from a project (optional). Delete the openspec/ directory if you no longer want its specs and changes:
rm -rf openspec/
Think before you do this: openspec/specs/ and openspec/changes/archive/ are your record of how the system behaves and why it changed. If you might want that history, keep the folder (or keep it in git) even after uninstalling.
3. Remove generated AI tool files (optional). OpenSpec writes skill and command files into per-tool directories like .claude/skills/openspec-*/, .cursor/commands/opsx-*, and so on. Delete the openspec-* skills and opsx-* commands for whichever tools you configured. The exact paths per tool are listed in Supported Tools.
If you also have OpenSpec marker blocks in files like CLAUDE.md or AGENTS.md, remove those blocks by hand; your own content in those files is yours to keep.
Next Steps
After installing, initialize OpenSpec in your project:
cd your-project
openspec init
See Getting Started for a full walkthrough.