OpenSpec

Installazione ​

Prerequisiti ​

  • Node.js 20.19.0 o superiore — Verifica la tua versione: node --version

Installa con il tuo assistente AI ​

Non vuoi farlo manualmente? Incolla il prompt seguente in qualsiasi assistente di codifica in grado di eseguire comandi shell — Claude Code, Codex, Cursor, Gemini CLI, Copilot e gli altri strumenti supportati. Questo installerà la CLI, inizializzerà il progetto e ti riferirà cosa è effettivamente accaduto.

I passaggi manuali riportati di seguito sono la fonte ufficiale di verità; il prompt li esegue semplicemente per te. Se il tuo assistente si interrompe e ti restituisce qualcosa, è intenzionale: chiede prima di qualsiasi operazione privilegiata e non modifica mai i file di avvio della tua shell. Completa quelle parti da solo utilizzando i Package Managers e la sezione Troubleshooting.

text
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. 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. 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. If none of those four
   is available, stop and tell me — don't improvise an install. (If I'm on Nix,
   point me at the Nix section of the OpenSpec installation docs instead.)
   Show me the exact command and let me confirm before you run it; this installs
   software outside the project, and I may want a different package manager to
   own it.
   Stop and ask me again 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. 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 it prints an older version than the one the install just
   reported, an earlier copy is shadowing it on PATH — tell me both versions
   instead of continuing. 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. 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; if you find nothing, say so and carry on
   without asking. 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, and take the exact spelling from the files init created rather
   than from its summary line: the punctuation differs per tool (/opsx:propose
   in some, /opsx-propose in others, @opsx-propose in Amazon Q), and tools that
   get skills instead of commands are invoked by skill name (/openspec-propose,
   or $openspec-propose in Codex, or /skill:openspec-propose in Kimi Code).

Nessuna parte del prompt è specifica di un fornitore: sono istruzioni generiche più gli stessi comandi documentati in questa pagina. Funziona su macOS, Linux e Windows ed è progettato per fermarsi invece di improvvisare quando un passaggio richiede il tuo permesso. Il tuo assistente deve essere in grado di eseguire comandi shell: alcune integrazioni IDE non lo sono.

Package Managers ​

npm ​

bash
npm install -g @fission-ai/openspec@latest

pnpm ​

bash
pnpm add -g @fission-ai/openspec@latest

yarn ​

bash
yarn global add @fission-ai/openspec@latest

Yarn 2 e versioni successive (Berry) hanno rimosso il comando global. Su queste versioni, installa OpenSpec con npm, pnpm o bun invece — una CLI globale non deve condividere il package manager del tuo progetto.

deno ​

Deno a volte ha problemi nell'analizzare il tag @latest, ma possiamo specificare una versione durante l'installazione iniziale. Se ciò accade, potresti provare a cambiare il tag @latest con la versione, qualcosa come @^1.3.1

bash
deno install --global \
  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
  npm:@fission-ai/openspec@latest
# oppure
deno install --global \
  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
  npm:@fission-ai/openspec@^1.3.1

Nota: Se i tuoi sottocomandi avviano strumenti esterni, come l'editing della configurazione, il feedback o l'apertura dello spazio di lavoro, potresti aver bisogno di un --allow-run=<program> specifico.

bun ​

Bun può installare OpenSpec globalmente, ma OpenSpec attualmente gira su Node.js. Hai comunque bisogno di Node.js 20.19.0 o superiore disponibile nel PATH.

bash
bun add -g @fission-ai/openspec@latest

Nix ​

Esegui OpenSpec direttamente senza installazione:

bash
nix run github:Fission-AI/OpenSpec -- init

Oppure installalo nel tuo profilo:

bash
nix profile install github:Fission-AI/OpenSpec

Oppure aggiungilo al tuo ambiente di sviluppo in flake.nix:

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 ];
    };
  };
}

Verifica dell'installazione ​

bash
openspec --version

Aggiornamento ​

Aggiorna il pacchetto, quindi aggiorna i file generati per ogni progetto:

bash
npm install -g @fission-ai/openspec@latest   # oppure equivalente per pnpm/yarn/bun
openspec update                              # esegui all'interno di ogni progetto

openspec update rigenera i file delle skill e dei comandi per gli strumenti che hai configurato, così che i tuoi slash command rimangano aggiornati rispetto alla versione installata. Controlla anche se è stata pubblicata una versione più recente della CLI e offre di effettuare l'aggiornamento, poiché l'aggiornamento è ciò che rende disponibili nuovi workflow in primo luogo — vedi CLI Reference.

Disinstallazione ​

Non esiste il comando openspec uninstall, perché OpenSpec è solo un pacchetto globale più alcuni file nel tuo progetto. Rimuoverlo richiede pochi passaggi manuali e nulla qui tocca il tuo codice sorgente.

1. Rimuovi il pacchetto globale:

bash
npm uninstall -g @fission-ai/openspec   # oppure: pnpm rm -g / yarn global remove / bun rm -g

2. Rimuovi OpenSpec da un progetto (opzionale). Elimina la directory openspec/ se non vuoi più le sue specifiche e modifiche:

bash
rm -rf openspec/

Pensa bene prima di farlo: openspec/specs/ e openspec/changes/archive/ sono la tua cronologia di come si comporta il sistema e perché è cambiato. Se potresti voler recuperare quella cronologia, mantieni la cartella (o tienila in git) anche dopo la disinstallazione.

3. Rimuovi i file generati per gli strumenti AI (opzionale). OpenSpec scrive file di skill e comandi in directory per strumento come .claude/skills/openspec-*/, .cursor/commands/opsx-*, e così via. Elimina le skill openspec-* e i comandi opsx-* per gli strumenti che hai configurato. I percorsi esatti per ciascun strumento sono elencati in Supported Tools.

Se hai anche blocchi di marcatura OpenSpec in file come CLAUDE.md o AGENTS.md, rimuovi quei blocchi manualmente; il tuo contenuto in questi file resta di tua proprietà.

Prossimi passi ​

Dopo l'installazione, inizializza OpenSpec nel tuo progetto:

bash
cd your-project
openspec init

Vedi Getting Started per una guida completa.