Comandi
Questa è la riferimento per i comandi slash di OpenSpec. Questi comandi vengono invocati nell'interfaccia di chat del tuo assistente di coding AI (ad esempio, Claude Code, Cursor, Devin Desktop).
Per i modelli di flusso di lavoro e quando utilizzare ciascun comando, consulta Workflows. Per i comandi CLI, consulta CLI.
Queste pagine utilizzano /opsx:<command> come nome canonico. Alcuni strumenti lo scrivono in modo diverso — Cursor e GitHub Copilot registrano /opsx-propose, Codex utilizza $openspec-propose — quindi consulta How To Invoke per il tuo strumento. I file generati da OpenSpec utilizzano già l'formato corretto.
Riferimento rapido
Percorso rapido predefinito (profilo core)
| Comando | Scopo |
|---|---|
/opsx:propose | Crea una modifica e genera gli artefatti di pianificazione in un solo passaggio |
/opsx:explore | Rifletti sulle idee prima di impegnarti in una modifica |
/opsx:apply | Implementa i task dalla modifica |
/opsx:update | Rivedi gli artefatti di pianificazione di una modifica e mantienili coerenti |
/opsx:sync | Unisci le specifiche delta nelle specifiche principali |
/opsx:archive | Archivia una modifica completata |
Comandi di flusso di lavoro espansi (selezione flusso di lavoro personalizzato)
| Comando | Scopo |
|---|---|
/opsx:new | Avvia un nuovo scaffold di modifica |
/opsx:continue | Crea l'artefatto successivo in base alle dipendenze |
/opsx:ff | Avanti veloce: crea tutti gli artefatti di pianificazione in una volta sola |
/opsx:verify | Convalida che l'implementazione corrisponda agli artefatti |
/opsx:bulk-archive | Archivia più modifiche in una volta sola |
/opsx:onboard | Tutorial guidato attraverso l'intero flusso di lavoro |
Il profilo globale predefinito è core. Per abilitare i comandi di flusso di lavoro espansi, esegui openspec config profile, seleziona i flussi di lavoro, quindi esegui openspec update nel tuo progetto.
Riferimento Comandi
/opsx:propose
Crea una nuova modifica e genera gli artefatti di pianificazione in un solo passaggio. Questo è il comando di avvio predefinito nel profilo core.
Sintassi:
/opsx:propose [change-name-or-description]Argomenti:
| Argomento | Obbligatorio | Descrizione |
|---|---|---|
change-name-or-description | No | Nome in kebab-case o descrizione della modifica in linguaggio naturale |
Cosa fa:
- Crea
openspec/changes/<change-name>/ - Genera gli artefatti necessari prima dell'implementazione (per
spec-driven: proposta, specifiche, design, task) - Si ferma quando l'artefatto è pronto per
/opsx:apply
Esempio:
You: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
✓ proposal.md
✓ specs/ui/spec.md
✓ design.md
✓ tasks.md
Ready for implementation. Run /opsx:apply.Suggerimenti:
- Utilizza questo comando per il percorso end-to-end più rapido
- Se desideri un controllo passo-passo sugli artefatti, abilita i workflow espansi e usa
/opsx:new+/opsx:continue
/opsx:explore
Inizia qui se non sei sicuro. Explore è un partner di pensiero senza rischi: legge il tuo codice, confronta le opzioni e trasforma un'idea vaga in un piano concreto prima che esista qualsiasi modifica. È incluso nel profilo predefinito. Per il caso d'uso completo e altri esempi, consulta la guida Explore First.
Rifletti sulle idee, indaga i problemi e chiarisci i requisiti prima di impegnarti in una modifica.
Sintassi:
/opsx:explore [topic]Argomenti:
| Argomento | Obbligatorio | Descrizione |
|---|---|---|
topic | No | Cosa desideri esplorare o indagare |
Cosa fa:
- Apre una conversazione esplorativa senza struttura obbligatoria
- Indaga il codice per rispondere alle domande
- Confronta opzioni e approcci
- Crea diagrammi visivi per chiarire il ragionamento
- Può passare a
/opsx:propose(predefinito) o/opsx:new(workflow espanso) quando le intuizioni si concretizzano
Esempio:
You: /opsx:explore
AI: What would you like to explore?
You: How should we handle authentication for the mobile app?
AI: Let me investigate your current auth setup...
[Analyzes codebase]
I see you're using session-based auth for the web app.
For mobile, we have three main options:
1. JWT tokens (stateless, works offline)
2. OAuth2 (if you need third-party login)
3. Extend current sessions (simpler, but requires connectivity)
Your API already has CORS configured. Which direction interests you?
You: Let's go with JWT. Can we start a change for that?
AI: Ready when you are. Run /opsx:propose add-jwt-auth to begin.Suggerimenti:
- Utilizza quando i requisiti non sono chiari o hai bisogno di indagare
- Non vengono creati artefatti durante l'esplorazione
- Utile per confrontare più approcci prima di decidere
- Può leggere file e cercare nel codice
/opsx:new
Avvia una nuova struttura per una modifica. Crea la cartella della modifica e attende che generi gli artefatti con /opsx:continue o /opsx:ff.
Questo comando fa parte del set di workflow espansi (non incluso nel profilo core predefinito).
Sintassi:
/opsx:new [change-name] [--schema <schema-name>]Argomenti:
| Argomento | Obbligatorio | Descrizione |
|---|---|---|
change-name | No | Nome per la cartella della modifica (richiesto se non fornito) |
--schema | No | Schema di workflow da utilizzare (predefinito: dalla configurazione o spec-driven) |
Cosa fa:
- Crea la directory
openspec/changes/<change-name>/ - Crea il file di metadati
.openspec.yamlnella cartella della modifica - Mostra il primo modello di artefatto pronto per la creazione
- Richiede il nome della modifica e lo schema se non forniti
Cosa crea:
openspec/changes/<change-name>/
└── .openspec.yaml # Change metadata (schema, created date)Esempio:
You: /opsx:new add-dark-mode
AI: Created openspec/changes/add-dark-mode/
Schema: spec-driven
Ready to create: proposal
Use /opsx:continue to create it, or /opsx:ff to create all artifacts.Suggerimenti:
- Usa nomi descrittivi:
add-feature,fix-bug,refactor-module - Evita nomi generici come
update,changes,wip - Lo schema può essere impostato anche nella configurazione del progetto (
openspec/config.yaml)
/opsx:continue
Crea l'artefatto successivo nella catena di dipendenze. Crea un artefatto alla volta per un progresso incrementale.
Sintassi:
/opsx:continue [change-name]Argomenti:
| Argomento | Obbligatorio | Descrizione |
|---|---|---|
change-name | No | Quale modifica continuare (dedotto dal contesto se non fornito) |
Cosa fa:
- Interroga il grafo delle dipendenze degli artefatti
- Mostra quali artefatti sono pronti e quali sono bloccati
- Crea il primo artefatto pronto
- Legge i file di dipendenza per il contesto
- Mostra cosa diventa disponibile dopo la creazione
Esempio:
You: /opsx:continue
AI: Change: add-dark-mode
Artifact status:
✓ proposal (done)
◆ specs (ready)
◆ design (ready)
○ tasks (blocked - needs: specs, design)
Creating specs...
[Reads proposal.md, creates specs based on requirements]
✓ Created openspec/changes/add-dark-mode/specs/ui/spec.md
Now available: design
Run /opsx:continue to create the next artifact.Suggerimenti:
- Utilizza quando vuoi rivedere ogni artefatto prima di procedere
- Ideale per modifiche complesse in cui desideri il controllo
- Più artefatti possono diventare pronti simultaneamente
- Puoi modificare gli artefatti creati prima di continuare
/opsx:ff
Avanza rapidamente attraverso la creazione degli artefatti. Crea tutti gli artefatti di pianificazione in una volta sola.
Sintassi:
/opsx:ff [change-name]Argomenti:
| Argomento | Obbligatorio | Descrizione |
|---|---|---|
change-name | No | Quale modifica avanzare rapidamente (dedotto dal contesto se non fornito) |
Cosa fa:
- Crea tutti gli artefatti nell'ordine delle dipendenze
- Traccia i progressi tramite l'elenco delle attività
- Si ferma quando tutti gli artefatti
apply-requiredsono completi - Legge ogni dipendenza prima di creare l'artefatto successivo
Esempio:
You: /opsx:ff add-dark-mode
AI: Fast-forwarding add-dark-mode...
✓ Creating proposal.md
✓ Creating specs/ui/spec.md
✓ Creating design.md
✓ Creating tasks.md
All planning artifacts complete!
Ready for implementation. Run /opsx:apply to begin.Suggerimenti:
- Utilizza quando hai un'idea chiara di cosa stai costruendo
- Più rapido di
/opsx:continueper modifiche semplici - Puoi comunque modificare gli artefatti successivamente
- Ideale per funzionalità di piccole e medie dimensioni
/opsx:apply
Implementa i task della modifica. Lavora attraverso l'elenco dei task, scrivendo codice e spuntando gli elementi.
Sintassi:
/opsx:apply [change-name]Argomenti:
| Argomento | Obbligatorio | Descrizione |
|---|---|---|
change-name | No | Quale modifica implementare (dedotto dal contesto se non fornito) |
Cosa fa:
- Legge
tasks.mde identifica i task incompleti - Lavora sui task uno alla volta
- Scrive codice, crea file, esegue test secondo necessità
- Segna i task completi con le caselle
[x]
Esempio:
You: /opsx:apply
AI: Implementing add-dark-mode...
Reading tasks.md:
- [ ] 1.1 Create ThemeContext
- [ ] 1.2 Add CSS custom properties
- [ ] 1.3 Implement localStorage persistence
Working on 1.1: Create ThemeContext...
[Creates src/context/ThemeContext.tsx]
✓ 1.1 Complete
Working on 1.2: Add CSS custom properties...
[Updates src/styles/globals.css]
✓ 1.2 Complete
...Suggerimenti:
- Può riprendere da dove si era interrotto se interrotto
- Utilizza per modifiche parallele specificando il nome della modifica
- Lo stato di completamento è tracciato nelle caselle di
tasks.md
/opsx:update
Rivede gli artefatti di pianificazione esistenti di una modifica e li mantiene coerenti tra loro. Solo artefatti di pianificazione — non modifica mai il codice.
Sintassi:
/opsx:update [change-name]Argomenti:
| Argomento | Obbligatorio | Descrizione |
|---|---|---|
change-name | No | Quale modifica aggiornare (dedotto dal contesto se non fornito) |
Cosa fa:
- Legge gli artefatti della modifica tramite
openspec status --change <name> --json - Applica la revisione richiesta, oppure rivede gli artefatti per individuare contraddizioni se non ne hai specificata una
- Riconcilia gli altri artefatti esistenti in qualsiasi direzione (una modifica al design può propagarsi fino alla proposta)
- Conferma ogni modifica con te prima di scrivere, un artefatto alla volta
- Si conclude raccomandando il passo successivo:
/opsx:continue(artefatti mancanti),/opsx:apply(portare un piano rivisto nel codice), o/opsx:archive(tutto completato)
Esempio:
You: /opsx:update add-dark-mode - we're storing the theme in a cookie now, not localStorage
AI: Reading add-dark-mode artifacts...
The design references localStorage in two places; tasks 1.3 covers
localStorage persistence; the proposal doesn't mention storage.
Proposed revisions:
1. design.md - swap localStorage decision for cookie storage
2. tasks.md - reword task 1.3 to cookie persistence
Apply revision 1? (design.md)Suggerimenti:
- Non crea artefatti mancanti — quello è
/opsx:continue - Se l'artefatto è già stato implementato, segui con
/opsx:applyin modo che il codice corrisponda al piano rivisto - Se la revisione cambia l'intento della modifica, riparti da zero con una nuova modifica (vedi Quando aggiornare vs. ripartire da zero)
/opsx:verify
Valida che l'implementazione corrisponda agli artefatti della modifica. Verifica completezza, correttezza e coerenza.
Sintassi:
/opsx:verify [change-name]Argomenti:
| Argomento | Obbligatorio | Descrizione |
|---|---|---|
change-name | No | Quale modifica verificare (dedotto dal contesto se non fornito) |
Cosa fa:
- Verifica tre dimensioni della qualità dell'implementazione
- Cerca nel codice prove dell'implementazione
- Reporta i problemi classificati come CRITICAL, WARNING o SUGGESTION
- Non blocca l'archiviazione, ma evidenzia i problemi
Dimensioni di verifica:
| Dimensione | Cosa valida |
|---|---|
| Completezza | Tutti i task completati, tutti i requisiti implementati, scenari coperti |
| Correttezza | L'implementazione corrisponde all'intento delle specifiche, casi limite gestiti |
| Coerenza | Le decisioni di design riflesse nel codice, pattern coerenti |
Esempio:
You: /opsx:verify
AI: Verifying add-dark-mode...
COMPLETENESS
✓ All 8 tasks in tasks.md are checked
✓ All requirements in specs have corresponding code
⚠ Scenario "System preference detection" has no test coverage
CORRECTNESS
✓ Implementation matches spec intent
✓ Edge cases from scenarios are handled
✓ Error states match spec definitions
COHERENCE
✓ Design decisions reflected in code structure
✓ Naming conventions consistent with design.md
⚠ Design mentions "CSS variables" but implementation uses Tailwind classes
SUMMARY
─────────────────────────────
Critical issues: 0
Warnings: 2
Ready to archive: Yes (with warnings)
Recommendations:
1. Add test for system preference detection
2. Update design.md to reflect Tailwind usage, or refactor to use CSS variablesSuggerimenti:
- Esegui prima dell'archiviazione per individuare discrepanze precocemente
- I warning non bloccano l'archiviazione ma indicano potenziali problemi
- Utile per rivedere il lavoro dell'IA prima di commit
- Può rivelare divergenze tra artefatti e implementazione
/opsx:sync
Comando opzionale. Unisce le specifiche delta di una modifica nelle specifiche principali. L'archiviazione chiederà di sincronizzare se necessario, quindi di solito non è necessario eseguirlo manualmente.
Sintassi:
/opsx:sync [change-name]Argomenti:
| Argomento | Obbligatorio | Descrizione |
|---|---|---|
change-name | No | Quale modifica sincronizzare (dedotto dal contesto if not provided) |
Cosa fa:
- Legge le specifiche delta dalla cartella della modifica
- Analizza le sezioni ADDED/MODIFIED/REMOVED/RENAMED
- Unisce le modifiche nella directory principale
openspec/specs/ - Preserva il contenuto esistente non menzionato nel delta
- Non archivia la modifica (rimane attiva)
Esempio:
You: /opsx:sync
AI: Syncing add-dark-mode delta specs...
Reading: openspec/changes/add-dark-mode/specs/ui/spec.md
Target: openspec/specs/ui/spec.md
Changes to apply:
✓ ADDED: Theme Selection requirement (2 scenarios)
✓ ADDED: Accessibility requirement (1 scenario)
Merging...
✓ openspec/specs/ui/spec.md updated
Change remains active. Run /opsx:archive when ready to complete.Quando usarlo manualmente:
| Scenario | Usare sync? |
|---|---|
| Modifica di lunga durata, vuoi le specifiche principali prima dell'archiviazione | Sì |
| Più modifiche parallele necessitano le specifiche base aggiornate | Sì |
| Vuoi anteprima/revisione della fusione separatamente | Sì |
| Modifica rapida, vai direttamente all'archiviazione | No (l'archiviazione se ne occupa) |
Suggerimenti:
- La sincronizzazione è intelligente, non è copia-incolla
- Può aggiungere scenari a requisiti esistenti senza duplicarli
- La modifica rimane attiva dopo la sincronizzazione (non archiviata)
- La maggior parte degli utenti non avrà mai bisogno di chiamarlo direttamente — l'archiviazione lo richiederà se necessario
/opsx:archive
Archivia una modifica completata. Finalizza la modifica e la sposta nella cartella di archivio.
Sintassi:
/opsx:archive [change-name]Argomenti:
| Argomento | Obbligatorio | Descrizione |
|---|---|---|
change-name | No | Quale modifica archiviare (dedotto dal contesto se non fornito) |
Cosa fa:
- Verifica lo stato di completamento degli artefatti
- Verifica il completamento dei task (avvisa se incompleti)
- Offre di sincronizzare le specifiche delta se non già sincronizzate
- Sposta l'artefatto nella cartella
openspec/changes/archive/YYYY-MM-DD-<name>/ - Preserva tutti gli artefatti per la tracciabilità
Esempio:
You: /opsx:archive
AI: Archiving add-dark-mode...
Artifact status:
✓ proposal.md exists
✓ specs/ exists
✓ design.md exists
✓ tasks.md exists (8/8 tasks complete)
Delta specs: Not yet synced
→ Sync now? (recommended)
You: Yes
AI: ✓ Synced specs to openspec/specs/ui/spec.md
✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
Change archived successfully.Suggerimenti:
- L'archiviazione non blocca per task incompleti, ma avviserà
- Le specifiche delta possono essere sincronizzate durante l'archiviazione o prima
- Le modifiche archiviate sono preservate per la storia
- Usa
/opsx:verifyprima per individuare i problemi
/opsx:bulk-archive
Archivia più modifiche completate in una volta sola. Gestisce i conflitti tra specifiche di diverse modifiche.
Sintassi:
/opsx:bulk-archive [change-names...]Argomenti:
| Argomento | Obbligatorio | Descrizione |
|---|---|---|
change-names | No | Modifiche specifiche da archiviare (richiede selezione se non fornite) |
Cosa fa:
- Elenca tutte le modifiche completate
- Convalida ogni modifica prima dell'archiviazione
- Rileva i conflitti tra specifiche di diverse modifiche
- Risolve i conflitti verificando cosa è effettivamente implementato
- Archivia in ordine cronologico
Esempio:
You: /opsx:bulk-archive
AI: Found 3 completed changes:
- add-dark-mode (8/8 tasks complete)
- fix-login-bug (3/3 tasks complete)
- update-footer (2/2 tasks complete)
Checking for spec conflicts...
⚠ add-dark-mode and update-footer both touch specs/ui/
Inspecting codebase to resolve...
Both changes are implemented. Will merge in chronological order:
1. add-dark-mode (created Jan 20)
2. update-footer (created Jan 22)
Archive all 3 changes?
You: Yes
AI: ✓ Archived add-dark-mode
✓ Archived fix-login-bug
✓ Archived update-footer
Specs merged: add-dark-mode → update-footerSuggerimenti:
- Ideale per flussi di lavoro paralleli
- La risoluzione dei conflitti è agentica (verifica il codice)
- Le modifiche vengono archiviate in ordine di creazione
- Richiede conferma prima di sovrascrivere il contenuto delle specifiche
/opsx:onboard
Onboarding guidato attraverso il workflow completo di OpenSpec. Un tutorial interattivo che utilizza il tuo codice reale.
Sintassi:
/opsx:onboardCosa fa:
- Guida attraverso un ciclo completo del workflow con narrazione
- Scansiona il tuo codice per individuare opportunità reali di miglioramento
- Crea una modifica reale con artefatti reali
- Implementa lavoro reale (modifiche piccole e sicure)
- Archivia la modifica completata
- Spiega ogni passo man mano che avviene
Fasi:
- Benvenuto e analisi del codice
- Individuazione di un'opportunità di miglioramento
- Creazione di una modifica (
/opsx:new) - Scrittura della proposta
- Creazione delle specifiche
- Scrittura del design
- Creazione dei task
- Implementazione dei task (
/opsx:apply) - Verifica dell'implementazione
- Archiviazione della modifica
- Riepilogo e prossimi passi
Esempio:
You: /opsx:onboard
AI: Welcome to OpenSpec!
I'll walk you through the complete workflow using your actual codebase.
We'll find something small to improve, create a proper change for it,
implement it, and archive it.
Let me scan your codebase for opportunities...
[Analyzes codebase]
I found a few things we could work on:
1. Add input validation to the contact form
2. Improve error messages in the auth flow
3. Add loading states to async buttons
Which interests you? (or suggest something else)Suggerimenti:
- Ideale per nuovi utenti che imparano il workflow
- Utilizza codice reale, non esempi didattici
- Crea una modifica reale che puoi conservare o scartare
- Richiede 15-30 minuti per il completamento
Sintassi dei comandi per strumento AI
Diversi strumenti AI utilizzano sintassi dei comandi leggermente differenti. Utilizza il formato che corrisponde al tuo strumento:
| File di comando del tuo strumento | Esempio di sintassi | Strumenti di esempio |
|---|---|---|
.../commands/opsx/<id>.* | /opsx:propose, /opsx:apply | Claude Code, Gemini CLI, Crush |
.../opsx-<id>.* | /opsx-propose, /opsx-apply | Cursor, Devin Desktop, Copilot (IDE), Trae, Oh My Pi |
| nessuno — solo competenze | /openspec-propose, /openspec-apply-change | CodeArts, ForgeCode, Hermes, MiniMax Code, Mistral Vibe, Zed Agent, .agents condivisi |
| nessuno — Kimi Code | /skill:openspec-propose | Kimi Code |
| nessuno — Codex CLI | $openspec-propose | Codex |
Devin Desktop vs Devin Local: i file
.devin/workflows/opsx-*.mdforniscono a Devin Desktop/opsx-propose. Devin Local non ha workflow: utilizza le competenze che OpenSpec scrive in.devin/skills/, ad esempio/openspec-propose, che funzionano su entrambi gli agenti.
L'intento è lo stesso tra tutti gli strumenti, ma il modo in cui i comandi vengono esposti può variare in base all'integrazione. Come invocare elenca ogni strumento supportato; questa tabella mostra solo esempi di ciascuna forma.
Nota: I comandi di GitHub Copilot (
.github/prompts/*.prompt.md) sono disponibili solo nelle estensioni IDE (VS Code, JetBrains, Visual Studio). GitHub Copilot CLI non supporta attualmente i file prompt personalizzati: vedere Strumenti supportati per dettagli e soluzioni alternative.
Comandi legacy
Questi comandi utilizzano il vecchio workflow "tutto in una volta". Funzionano ancora, ma si consigliano i comandi OPSX.
| Comando | Cosa fa |
|---|---|
/openspec:proposal | Crea tutti gli artefatti in una sola volta (proposta, specifiche, design, attività) |
/openspec:apply | Implementa la modifica |
/openspec:archive | Archivia la modifica |
Quando utilizzare i comandi legacy:
- Progetti esistenti che utilizzano il vecchio workflow
- Modifiche semplici in cui non è necessaria la creazione incrementale degli artefatti
- Preferenza per l'approccio tutto-o-nulla
Migrazione a OPSX: Le modifiche legacy possono essere proseguite con i comandi OPSX. La struttura degli artefatti è compatibile.
Risoluzione dei problemi
"Modifica non trovata"
Il comando non è riuscito a identificare quale modifica elaborare.
Soluzioni:
- Specificare esplicitamente il nome della modifica:
/opsx:apply add-dark-mode - Verificare che la cartella della modifica esista:
openspec list - Assicurarsi di trovarsi nella directory del progetto corretta
"Nessun artefatto pronto"
Tutti gli artefatti sono completi o bloccati da dipendenze mancanti.
Soluzioni:
- Eseguire
openspec status --change <name>per visualizzare cosa sta bloccando - Verificare se esistono gli artefatti richiesti
- Creare prima gli artefatti delle dipendenze mancanti
"Schema non trovato"
Lo schema specificato non esiste.
Soluzioni:
- Elencare gli schemi disponibili:
openspec schemas - Controllare l'ortografia del nome dello schema
- Creare lo schema se è personalizzato:
openspec schema init <name>
Comandi non riconosciuti
Lo strumento AI non riconosce i comandi OpenSpec.
Soluzioni:
- Assicurarsi che OpenSpec sia inizializzato:
openspec init - Rigenerare le competenze:
openspec update - Verificare che la directory
.claude/skills/esista (per Claude Code) - Riavviare lo strumento AI per caricare le nuove competenze
Generazione non corretta degli artefatti
L'AI crea artefatti incompleti o errati.
Soluzioni:
- Aggiungere contesto del progetto in
openspec/config.yaml - Aggiungere regole specifiche per artefatto per fornire indicazioni mirate
- Fornire maggiori dettagli nella descrizione della modifica
- Utilizzare
/opsx:continueinvece di/opsx:ffper avere un controllo maggiore
Prossimi passi
- Workflow - Pattern comuni e quando utilizzare ciascun comando
- CLI - Comendi terminal per la gestione e la validazione
- Personalizzazione - Creare schemi e workflow personalizzati