Skills
Ogni skill OpenSpec: gli argomenti, cosa crea e cosa restituisce.
Le skill sono disponibili in due insiemi:
- Core: installate per impostazione predefinita, costituiscono il ciclo di pianificazione principale.
- Optional: installate soltanto quando le aggiungete, tramite i Profili.
Ogni skill presuppone un progetto che già usa OpenSpec. Prima del primo passaggio che scrive qualcosa, una skill verifica la presenza di una root risolta. Quando non ce n'è, ciò che accade dipende da come la skill è stata attivata:
- Selezione automatica: il tuo agente ha scelto la skill da solo, senza che tu nominassi OpenSpec. Mette da parte OpenSpec e risponde alla tua richiesta normalmente, come farebbe se OpenSpec non fosse installato.
- Richiesta esplicita di OpenSpec: hai nominato OpenSpec, hai citato la skill o hai eseguito il suo comando. Si ferma prima di scrivere e chiede come procedere: eseguire
openspec initqui, puntare a uno store con--store <id>, oppure continuare senza OpenSpec. Attende la tua risposta.
I comandi rientrano sempre nel secondo caso. Un progetto il cui openspec/config.yaml indica uno store che questa macchina non riesce a risolvere (non registrato, oppure una riga store: malformata) non viene trattato come non inizializzato: la skill si ferma e mostra l'errore dello store insieme alla sua soluzione. In nessuno dei due casi una skill crea da sola una directory openspec/. Le voci seguenti descrivono cosa fa ciascuna skill una volta che una root è presente.
| Skill | Compito | Tipo |
|---|---|---|
| openspec-explore | Ragionare su un'idea prima che diventi una proposta di modifica | Core |
| openspec-propose | Creare una proposta di modifica con tutti i suoi artefatti di pianificazione in un unico passaggio | Core |
| openspec-apply-change | Implementare i task di una proposta di modifica | Core |
| openspec-update-change | Rivedere il piano di una proposta di modifica | Core |
| openspec-sync-specs | Unire gli aggiornamenti di specifica di una proposta di modifica in specs/ | Core |
| openspec-archive-change | Spostare una proposta di modifica completata nell'archivio | Core |
| openspec-new-change | Avviare una proposta di modifica come scaffold vuoto | Optional |
| openspec-continue-change | Creare il prossimo artefatto di pianificazione, uno alla volta | Optional |
| openspec-ff-change | Creare una proposta di modifica con tutti gli artefatti necessari all'implementazione, in un'unica passata | Optional |
| openspec-verify-change | Verificare che l'implementazione corrisponda al piano | Optional |
| openspec-bulk-archive-change | Archiviare più proposte di modifica in una volta sola | Optional |
| openspec-onboard | Imparare il flusso di lavoro portando avanti una proposta di modifica reale dall'inizio alla fine | Optional |
Ciascuna voce seguente nomina la skill a cui spetta il passaggio successivo. Quando il tuo profilo omette quella skill, i file installati non la nominano mai: il passaggio di consegne diventa il comando openspec equivalente, oppure una semplice richiesta rivolta a te, e una riga che esiste solo per puntare a una skill mancante non viene scritta affatto. Così le skill che hai passano sempre il controllo a skill che hai. L'insieme che ottieni è definito dai Profili.
openspec-explore
Ragiona a fondo su un'idea prima che diventi una proposta di modifica.
| Contratto | Descrizione |
|---|---|
| Argomenti | Un argomento: un'idea, un problema, un confronto o il nome di una proposta di modifica esistente da esplorare nel contesto. Se non viene fornito nulla, entra in modalità esplorazione. |
| Crea | Nulla per impostazione predefinita. Legge e indaga soltanto. Su richiesta raccoglie spunti: una nuova proposta di modifica in openspec/changes/<name>/, oppure aggiornamenti alla proposta, al design, alle specifiche o alle attività di una proposta esistente. Non scrive mai codice. |
| Risposta | Una conversazione aperta senza output obbligatorio. Quando il ragionamento si chiarisce, riassume il problema, l'approccio, le questioni aperte e i prossimi passi, e propone di registrarli. Decidi tu. L'implementazione non inizia mai qui. |
openspec-propose
Crea una proposta di modifica e genera in un unico passaggio tutti i suoi artefatti di pianificazione.
| Contratto | Descrizione |
|---|---|
| Argomenti | Un nome in kebab-case (add-dark-mode) o una descrizione semplice. Se non fornisci nessuno dei due, lo chiede. |
| Crea | openspec/changes/<name>/ con ogni artefatto definito dallo schema, in ordine di dipendenza (spec-driven: proposta, specifiche delta, design, attività). Non scrive mai codice. |
| Risposta | Gli artefatti creati, pronti per la revisione, e il passo successivo. Si ferma lì; l'implementazione attende openspec-apply-change. |
openspec-apply-change
Implementa le attività di una proposta di modifica, procedendo lungo l'elenco fino al completamento o a un blocco.
| Contratto | Descrizione |
|---|---|
| Argomenti | Un nome di proposta di modifica (add-auth), facoltativo. Se l'obiettivo è ambiguo, elenca le proposte di modifica attive e ti chiede di scegliere. |
| Crea | Codice: le modifiche minime richieste da ciascuna attività, nei file del tuo progetto. Nella proposta di modifica spunta ogni attività completata (- [ ] a - [x]) nel file monitorato identificato da sourcePath e dalla line con numerazione a partire da uno. Uno schema può tenere traccia delle attività su più file. |
| Risposta | Avanzamento per attività, poi un conteggio complessivo (N/M attività completate). Tutte completate: suggerisce openspec-archive-change. Bloccato da artefatti mancanti: rimanda a openspec-continue-change oppure a openspec status e openspec instructions quando quella skill non è installata (il profilo core la omette). Attività poco chiare o errori: si mette in pausa e chiede. |
openspec-update-change
Rivedi gli artefatti di pianificazione esistenti di una proposta di modifica e mantienili coerenti tra loro.
| Contratto | Descrizione |
|---|---|
| Argomenti | Un nome di proposta di modifica, facoltativo, più la revisione desiderata. Se non viene indicata alcuna revisione, esegue una revisione di coerenza: gli artefatti vengono confrontati tra loro per individuare contraddizioni, lacune e duplicazioni. |
| Crea | Modifica i file degli artefatti già esistenti. Un'eccezione: per un artefatto definito tramite un glob, ad esempio specs/**/*.md, che abbia già almeno un file, può aggiungere un file complementare mancante una volta che confermi il percorso. Un artefatto ancora privo di file è compito di openspec-continue-change. In assenza di quella skill (il profilo core la omette), rimanda invece a openspec status e openspec instructions. Non scrive mai codice. |
| Risposta | Mostra ciascuna revisione proposta e la scrive solo dopo la tua conferma, un artefatto alla volta. Termina con ciò che è stato revisionato e il passo successivo; l'implementazione attende openspec-apply-change. |
openspec-sync-specs
Unisci gli aggiornamenti delle specifiche di una proposta di modifica in specs/ senza archiviarla.
| Contratto | Descrizione |
|---|---|
| Argomenti | Un nome di proposta di modifica, facoltativo. Puoi anche indicare un sottoinsieme delle sue specifiche delta: verranno sincronizzate solo quelle. |
| Crea | Modifica o crea openspec/specs/<capability-path>/spec.md per ciascuna specifica delta, incorporando nella specifica principale i requisiti aggiunti, modificati, rimossi e rinominati. Non scrive mai codice. |
| Risposta | Un riepilogo per capacità dei requisiti aggiunti, modificati, rimossi o rinominati, dopo la validazione delle specifiche aggiornate. La proposta di modifica resta attiva; l'archiviazione attende openspec-archive-change. |
openspec-archive-change
Sposta una proposta di modifica conclusa nell'archivio.
| Contratto | Descrizione |
|---|---|
| Argomenti | Un nome di proposta di modifica, facoltativo. |
| Crea | Sposta la cartella della proposta di modifica in openspec/changes/archive/YYYY-MM-DD-<name>/ (non aggiunge la data se il nome inizia già con una data). Con la tua approvazione, sincronizza prima le specifiche delta in sospeso. Quando openspec-sync-specs è installata, esegue quel flusso di lavoro. Altrimenti, incorpora essa stessa le specifiche delta nelle specifiche principali. Non scrive mai codice. |
| Risposta | Avvisa e chiede prima di archiviare in presenza di artefatti o attività incompleti, e chiede se sincronizzare quando esistono specifiche delta. Termina con un riepilogo: nome, schema, posizione dell'archivio, stato della sincronizzazione delle specifiche ed eventuali avvisi. |
openspec-new-change
Avvia una proposta di modifica come struttura vuota.
| Contratto | Descrizione |
|---|---|
| Argomenti | Un nome in kebab-case (add-user-auth) o una descrizione semplice, più un nome di schema solo per un flusso di lavoro non predefinito. Chiede cosa vuoi realizzare se non fornisci nessuno dei due. |
| Crea | openspec/changes/<name>/ come struttura vuota: ancora nessun artefatto, mai codice. |
| Risposta | Il nome e la posizione della struttura, la sequenza degli artefatti del flusso di lavoro, lo stato (0/N completati) e il template del primo artefatto. La stesura degli artefatti attende openspec-continue-change. |
openspec-continue-change
Crea il successivo artefatto di pianificazione in una proposta di modifica, uno alla volta.
| Contratto | Descrizione |
|---|---|
| Argomenti | Un nome di proposta di modifica, facoltativo. Se è ancora ambiguo, ti chiede di scegliere tra le proposte modificate più di recente. |
| Crea | Il singolo successivo artefatto pronto nella sequenza dello schema, scritto nella cartella della proposta di modifica. Un artefatto per esecuzione, mai codice. |
| Risposta | L'artefatto creato, l'avanzamento (N di M completati) e quali artefatti ha sbloccato. Quando la pianificazione è completa lo dichiara; l'implementazione passa a openspec-apply-change. |
openspec-ff-change
Crea una proposta di modifica e ogni artefatto di pianificazione necessario all'implementazione, in un solo passaggio.
| Contratto | Descrizione |
|---|---|
| Argomenti | Un nome in kebab-case o una descrizione semplice. Se non fornisci nessuno dei due, lo chiede. Se la proposta di modifica indicata esiste già, suggerisce invece di continuarla. |
| Crea | openspec/changes/<name>/ e ogni artefatto di pianificazione richiesto dall'implementazione, in ordine di dipendenza (spec-driven: proposta, specifiche, design, attività), escludendo solo gli artefatti contrassegnati come saltati o condizionali. Non scrive mai codice. |
| Risposta | Il nome e la posizione della proposta di modifica, ogni artefatto creato e ogni artefatto condizionale saltato, con il motivo. Si ferma lì; l'implementazione attende openspec-apply-change. |
openspec-verify-change
Verifica che l'implementazione corrisponda agli artefatti della proposta di modifica.
| Contratto | Descrizione |
|---|---|
| Argomenti | Un nome di proposta di modifica, facoltativo. Quando è ambiguo, chiede di scegliere, elencando le proposte di modifica che hanno un artefatto delle attività. |
| Crea | Nulla. Legge gli artefatti della proposta di modifica e la codebase. La verifica produce solo un report. |
| Risposta | Un report: una scheda di valutazione per Completezza, Correttezza e Coerenza, poi problemi CRITICAL, WARNING e SUGGESTION con raccomandazioni, e una valutazione finale di idoneità all'archiviazione. Non modifica nulla e non archivia. |
openspec-bulk-archive-change
Archivia più proposte di modifica contemporaneamente.
| Contratto | Descrizione |
|---|---|
| Argomenti | Nessuno. Elenca le proposte di modifica attive e ti chiede di selezionarne un numero qualsiasi, con un'opzione per tutte. Se non ce ne sono di attive, lo dichiara e si ferma. |
| Crea | openspec/changes/archive/YYYY-MM-DD-<name>/ per ogni proposta di modifica archiviata (i nomi già datati mantengono il loro prefisso). Le specifiche delta di ciascuna vengono prima sincronizzate tramite openspec-sync-specs. Non scrive mai codice. |
| Risposta | Una tabella di stato per proposta di modifica e una conferma per l'intero gruppo, poi un riepilogo di archiviate, saltate e non riuscite, oltre ai risultati della sincronizzazione delle specifiche. Quando due proposte di modifica interessano la stessa specifica, controlla la codebase e sincronizza i delta implementati partendo dal più vecchio. |
openspec-onboard
Impara il flusso di lavoro portando a termine una vera proposta di modifica dall'inizio alla fine.
| Contratto | Descrizione |
|---|---|
| Argomenti | Nessuno. Analizza la tua codebase alla ricerca di piccole attività iniziali e ti chiede di sceglierne una o di descrivere la tua. |
| Crea | Una vera proposta di modifica per l'attività scelta, un artefatto alla volta, poi codice reale una volta confermata l'implementazione. Archivia la proposta di modifica alla fine. |
| Risposta | Un percorso guidato e commentato dell'intero ciclo, con pause per il tuo intervento: esplora, crea, costruisci ogni artefatto, implementa, archivia. Termina con un riepilogo e un rimando a openspec-propose. Richiede circa 15-20 minuti. |