Fix the local setup before debugging the agent.

spectra command not found

If you used npx spectra-pack@latest adopt ., no global command was installed. Run the repo-local launcher:

./.spectra/bin/spectra status
./.spectra/bin/spectra check

If you installed the native binary, add $HOME/.local/bin to PATH and open a new terminal.

Update does not change my project

spectra update
spectra version
spectra migrate --check

This is expected. spectra update updates only the application on your machine (a managed native install). npm users do npm install -g spectra-pack@latest. The command never reads or changes a project. "Already up to date" refers to the application. If a project reports that it needs a newer layout, spectra migrate --check lists the steps and spectra migrate --yes applies them to that one project.

A command says the project needs migration

spectra migrate --check
spectra migrate --yes

Migration is always explicit and creates a recovery snapshot first. Derived caches (the repo index, Knowledge Map and verification evidence) rebuild on their own and never need a migration.

Evidence shows as stale or unverified

spectra verify --explain <id>
spectra verify --test-target <test-target-id>

verified means that every declared test target passed. stale means that the code or the declarations changed after the recorded run. unverified means that no run is recorded. verify --explain names the missing layer, and verify --test-target records a fresh result.

Doctor reports an unhealthy adapter

spectra doctor
spectra doctor --fix
spectra check

doctor --fix repairs safe generated Spectra files. It does not rewrite application code or business memory. If an agent command is missing from PATH, install that agent CLI or remove it from the configured adapter set.

Use Codex through VS Code

A VS Code extension can be usable even when the standalone codex command is not on PATH. Spectra doctor checks command-line adapter health, so a missing CLI can still show as unhealthy.

Repo index looks too technical

spectra index records modules, dependencies, projects, and test targets. It is technical evidence for context loading and verification. It does not infer business intent. Use onboard and memory-bank files for durable product knowledge.