Bootstrap once, then use the project-local command.

Existing project with npm

cd existing-project
npx spectra-pack@latest adopt .
./.spectra/bin/spectra onboard
./.spectra/bin/spectra check
./.spectra/bin/spectra status

Use adopt for a repository that already has application code. Spectra writes its own layer under .spectra/ and leaves the product structure alone. It records repository evidence. It does not run your tests. It does not change what the code does into business truth.

New project with npm

mkdir my-product
cd my-product
git init
npx spectra-pack@latest init .
./.spectra/bin/spectra check

macOS or Linux without Node

curl -fsSL https://raw.githubusercontent.com/yunusakin/spectra/main/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
spectra --version
spectra adopt .  # init . for a new project

The native installer downloads the matching release artifact and verifies its checksum. Keep the PATH export in your shell profile if you want spectra available in new terminals.

Local or shared Git mode

The default local mode keeps .spectra/ out of your repository. It uses .git/info/exclude and does not change .gitignore. Nothing that Spectra writes goes into a company repository unless you add it. Pass --git-mode shared to init or adopt when your team wants to review and commit Spectra state. Derived caches and verification evidence stay uncommitted.

Update, migrate and uninstall are separate

Installing the application (once per machine) and setting up a project (init or adopt, once per project) are different steps, and so are changing the application and changing a project.

spectra update            # the application on this machine
spectra migrate --check   # what this project would need, no writes
spectra migrate --yes     # apply it to this one project
spectra uninstall --yes   # remove the native application

spectra update updates a verified native installation only. It never reads or changes a project. npm users do npm install -g spectra-pack@latest. npx users do npx spectra-pack@latest to get a newer CLI. spectra migrate advances one project's layout or schema only when you ask for it, and nothing migrates silently. spectra uninstall removes verified native files and leaves every project unchanged. Derived caches rebuild on their own and never need a migration.

After an update, run spectra doctor in a project. It shows if the generated runtime files or agent guidance are old. doctor --fix refreshes the safe generated files. spectra adapters --agents <csv> regenerates the agent guidance when you ask.

The shipped guides are in .spectra/docs/spectra/. Compatible plugin artifacts use .spectra/docs/<project-name>/<plugin-or-skill>/. Spectra does not move existing files automatically. See command effects for preservation and repair details.