Come Funzionano i Comandi

L'unica cosa da sapere: OpenSpec ha due tipi di comandi, e vengono eseguiti in due luoghi diversi.

• I comandi openspec ... vengono eseguiti nel tuo terminale. (Esempio: openspec init.)
• I comandi /opsx:... vengono eseguiti nella chat del tuo assistente AI. (Esempio: /opsx:propose.)

Se mai digiti /opsx:propose nel tuo terminale e non succede nulla, questa pagina è il motivo. Stai parlando con la metà sbagliata di OpenSpec. I comandi slash non sono comandi da terminale. Sono istruzioni che dai al tuo assistente di codifica AI, nella stessa casella di chat dove normalmente scriveresti "aggiungi un modulo di login".

Questa singola distinzione è l'ostacolo più comune per i nuovi utenti, quindi rendiamola assolutamente chiara.

Le due metà

OpenSpec è un unico progetto che indossa due cappelli.

Il CLI (metà terminale). Un programma chiamato openspec che installi ed esegui dalla tua shell. Configura il tuo progetto, elenca e valida le modifiche, mostra una dashboard e archivia il lavoro completato. Li digiti in iTerm, nel terminale di VS Code, in PowerShell, ovunque eseguiresti git o npm.

openspec init        # configura OpenSpec in questo progetto
openspec list        # vede le modifiche attive
openspec view        # apre la dashboard interattiva

I comandi slash (metà chat). Comandi brevi come /opsx:propose e /opsx:apply che digiti nel tuo assistente AI. Questi dicono all'AI di seguire il flusso di lavoro OpenSpec: redigere una proposta, scrivere le specifiche, costruire dalla lista di attività, archiviare quando è finito. Li digiti in Claude Code, Cursor, Devin Desktop, Copilot o qualsiasi assistente usi.

/opsx:propose add-dark-mode    (digitato nella chat AI)
/opsx:apply                    (digitato nella chat AI)
/opsx:archive                  (digitato nella chat AI)

Ecco il modello mentale in un'immagine:

        IL TUO TERMINALE                         LA CHAT DEL TUO ASSISTENTE AI
   ┌──────────────────────┐               ┌──────────────────────────────┐
   │  $ openspec init     │   installa    │  /opsx:propose add-dark-mode  │
   │  $ openspec list     │  ──────────►  │  /opsx:apply                  │
   │  $ openspec view     │   comandi     │  /opsx:archive                │
   └──────────────────────┘    & skills   └──────────────────────────────┘
        esegui openspec qui                       esegui /opsx:* qui

Nota la freccia. Eseguire openspec init nel tuo terminale è ciò che installa i comandi slash nel tuo strumento AI. La metà terminale configura la metà chat. Dopo di che, la guida quotidiana avviene principalmente nella chat.

"Come avvio la modalità interattiva?"

Non esiste una modalità interattiva separata da avviare. Questa domanda viene posta spesso, quindi merita una risposta chiara.

Non entri in una modalità speciale di OpenSpec. Apri semplicemente il tuo assistente di codifica AI come fai sempre e digita un comando slash nella chat. Il comando slash è il modo in cui "entri" in OpenSpec. Il tuo assistente lo riconosce, carica la skill OpenSpec corrispondente e inizia a seguire il flusso di lavoro.

Quindi le istruzioni reali sono:

1. Apri il tuo assistente di codifica AI (Claude Code, Cursor, Devin Desktop e così via) nel tuo progetto.
2. Digita /opsx:propose nella sua chat, nello stesso posto dove digiteresti qualsiasi altra richiesta.
3. Osserva l'autocompletamento: se OpenSpec è installato, vedrai /opsx:propose, /opsx:apply e amici apparire mentre digiti lo slash.

Questo è tutto. Nessuna modalità da attivare, nessun demone da avviare, nessuna finestra separata.

Una cosa che è genuinamente interattiva vive nel terminale: openspec view. Apre una dashboard per sfogliare le tue specifiche e modifiche. Ma è un visualizzatore, non la cosa con cui proponi e costruisci. La costruzione avviene tramite comandi slash nella chat.

Perché esiste questa separazione

Vale la pena capirlo, perché spiega perché OpenSpec funziona con oltre 30 diversi strumenti AI.

Il CLI è il motore. Conosce le regole: come appare una cartella di modifica, quali artefatti dipendono da quali, come unire uno spec delta nella tua fonte di verità. È lo stesso ovunque.

I comandi slash sono il volante, e ogni strumento AI ne ha uno leggermente diverso. Claude Code li chiama comandi. Cursor e Devin Desktop hanno i loro formati. Alcuni strumenti li chiamano skill. Quando esegui openspec init, OpenSpec genera il tipo di file giusto per ogni strumento che hai selezionato, così la stessa intenzione /opsx:propose funziona indipendentemente dall'assistente che preferisci.

Il punto di forza di questo design: impari il flusso di lavoro una volta e lo porti con te tra gli strumenti. Il compromesso: la sintassi esatta di un comando può differire leggermente tra gli strumenti, che è la sezione successiva.

Sintassi dei comandi slash per strumento

L'intento è identico ovunque. L'ortografia segue il file che il tuo strumento carica.

File dei comandi del tuo strumento	Come lo digiti	Esempi di strumenti
.../commands/opsx/<id>.*	/opsx:propose	Claude Code, Gemini CLI, Crush
.../opsx-<id>.*	/opsx-propose	Cursor, GitHub Copilot (IDE), Devin Desktop, Trae, Oh My Pi
.amazonq/prompts/opsx-<id>.md	@opsx-propose	Amazon Q Developer
nessuno — solo skill	/openspec-propose	CodeArts, ForgeCode, Hermes, Mistral Vibe, Zed Agent, .agents condiviso
nessuno — Kimi Code	/skill:openspec-propose	Kimi Code
nessuno — Codex CLI	$openspec-propose	Codex

Devin è l'unico strumento che copre due righe. Devin Desktop legge .devin/workflows/, quindi /opsx-propose funziona lì; Devin Local non lo fa, quindi su quell'agente usa la skill /openspec-propose invece. Le skill che OpenSpec scrive in .devin/skills/ funzionano su entrambi, motivo per cui si riferiscono l'una all'altra per nome di skill.

Ogni strumento è elencato in Come Invocare — quella tabella è quella autorevole. Due righe non sono affatto comandi slash: Amazon Q carica i suoi file in una libreria di prompt invocata con @, e le ultime tre righe usano il nome della skill, che non è l'id del comando (/opsx:apply è la skill openspec-apply-change).

In caso di dubbio, leggi la riga "Per iniziare" stampata da openspec init: usa già la forma che i tuoi strumenti hanno registrato. Anche digitare uno slash e osservare l'autocompletamento funziona, per gli strumenti che mostrano comandi slash.

Come sono arrivati i comandi: skill e comandi

Quando esegui openspec init (o openspec update), OpenSpec scrive piccoli file nel tuo progetto affinché il tuo strumento AI possa trovare il flusso di lavoro. A seconda dello strumento e delle impostazioni, questi sono skill, comandi, o entrambi.

• Le skill vivono in luoghi come .claude/skills/openspec-*/SKILL.md. Sono lo standard emergente tra gli strumenti: una cartella di istruzioni che il tuo assistente rileva automaticamente.
• I comandi vivono in luoghi come .cursor/commands/opsx-<id>.md o .claude/commands/opsx/<id>.md — il layout è dello strumento, ed esso decide come digiti il comando. Sono i vecchi file di comandi slash specifici per strumento. Codex non riceve file di comandi generati; usa .agents/skills/openspec-*.

Non devi preoccuparti di quale usa il tuo strumento. Digiti semplicemente il comando slash e funziona. Ma sapere che questi file esistono aiuta quando qualcosa va storto: se i tuoi comandi scompaiono, di solito significa che questi file mancano o sono obsoleti, e openspec update li rigenera.

Vedi Strumenti Supportati per i percorsi esatti per strumento, e Guida alla Migrazione per come le skill hanno sostituito il vecchio approccio solo-comandi.

Verificare che sia installato

Controlli rapidi, dal più veloce al più lento:

1. Digita uno slash nella chat AI. Inizia a digitare /opsx e osserva i suggerimenti di autocompletamento. Se appaiono, sei a posto. Su uno strumento solo-skill (Codex, Kimi Code, CodeArts, ForgeCode, Hermes, Mistral Vibe, Zed Agent o il target .agents condiviso) /opsx non completa mai anche in un'installazione sana — prova invece il nome della skill dalla tabella sopra.
2. Cerca i file. Per Claude Code, controlla che .claude/skills/ contenga cartelle openspec-*. Altri strumenti usano le proprie directory (Strumenti Supportati le elenca).
3. Esegui di nuovo la configurazione. Dalla radice del tuo progetto, esegui openspec update. Questo rigenera i file di skill e comandi per gli strumenti che hai configurato.
4. Riavvia il tuo assistente. Molti strumenti scansionano le skill e i comandi all'avvio, quindi una nuova finestra può essere il passo mancante.

Quali comandi ho esattamente?

Per impostazione predefinita, OpenSpec installa il set core di comandi slash:

• /opsx:explore: pensa a un'idea con l'AI prima di impegnarti in una modifica (ottimo primo passo quando sei incerto)
• /opsx:propose: crea una modifica e redige tutti i suoi artefatti di pianificazione in un solo passaggio
• /opsx:apply: costruisci la modifica lavorando attraverso la sua lista di attività
• /opsx:update: rivedi gli artefatti di pianificazione di una modifica e mantienili coerenti
• /opsx:sync: unisci gli aggiornamenti dello spec di una modifica nei tuoi spec principali (di solito automatico)
• /opsx:archive: completa una modifica e archiviala

Un buon ritmo predefinito: explore quando stai capendo cosa fare, poi propose, apply, archive. La guida Esplora Prima spiega perché quel passo iniziale ripaga.

C'è anche un set espanso per chi vuole un controllo più fine (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard). Lo attivi con openspec config profile, poi lo applichi con openspec update.

Sei nuovo a tutto questo? /opsx:onboard (nel set espanso) ti accompagna attraverso una modifica completa sul tuo codice, spiegando ogni passaggio. È l'introduzione più amichevole possibile.

Per ciò che ogni comando fa in dettaglio, vedi Comandi. Per quando usare quale, vedi Flussi di Lavoro.

Un primo avvio pulito

Mettendo tutto insieme, ecco l'intera sequenza con ogni passaggio etichettato per dove avviene.

TERMINALE   $ npm install -g @fission-ai/openspec@latest
TERMINALE   $ cd your-project
TERMINALE   $ openspec init
              (installa i comandi slash nel tuo strumento AI)

CHAT AI      /opsx:explore
              (opzionale: pensa all'idea con l'AI prima)

CHAT AI      /opsx:propose add-dark-mode
              (l'AI redige proposta, specifiche, design, attività)

CHAT AI      /opsx:apply
              (l'AI costruisce, spuntando le attività)

CHAT AI      /opsx:archive
              (la modifica viene unita nelle tue specifiche e archiviata)

Due passaggi da terminale per configurare. Poi vivi nella chat. Questo è il ritmo.

Correlati

• Per Iniziare: il tutorial completo per la prima modifica
• Comandi: ogni comando slash in dettaglio
• CLI: ogni comando da terminale in dettaglio
• Strumenti Supportati: sintassi e posizioni dei file per strumento
• FAQ: più risposte rapide
• Risoluzione dei Problemi: soluzioni quando i comandi non compaiono