Schemas

Modifica ciò che OpenSpec produce: gli artifact, il loro ordine e i loro template.

Uno schema definisce ciò che una proposta di modifica produce: quali artifact, in quale ordine, da quali template. Ad esempio, spec-driven, lo schema predefinito incluso, produce questi quattro in quest'ordine approssimativo, ciascuno basandosi su ciò che lo precede:

proposal → specs → design → tasks

Forka uno schema quando vuoi che questi siano documenti diversi, che si tratti di meno documenti, nomi diversi o una struttura diversa.

Dove si trovano gli schemi

OpenSpec cerca uno schema in tre posizioni, in ordine, e utilizza il primo che trova:

1. Il tuo progetto: openspec/schemas/, committato con il repo così che tutto il team lo ottenga.
2. La tua macchina: ~/.local/share/openspec/schemas su macOS e Linux (o sotto $XDG_DATA_HOME se lo imposti), oppure %LOCALAPPDATA%\openspec\schemas su Windows. Gli schemi qui sono disponibili in ogni progetto in cui lavori.
3. Il pacchetto: gli schemi integrati, come spec-driven, sono inclusi nel pacchetto openspec stesso.

Lo stesso nome può esistere in più posizioni, e la posizione più specifica ha la precedenza. openspec schema which mostra quale copia è in uso:

$ openspec schema which spec-driven
Schema: spec-driven
Source: project
Path: /your-project/openspec/schemas/spec-driven

Shadows:
  package: .../openspec/schemas/spec-driven

Cosa contiene uno schema

Uno schema è definito da una cartella di file semplici: uno schema.yaml che dichiara gli artifact, e un template per ciascuno di essi. Ecco lo schema integrato spec-driven:

spec-driven/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md

• schema.yaml: dichiara ciascun artifact, il file che genera, il template da cui parte, ciò che richiede prima, e l'istruzione che l'agente riceve quando lo crea. Il contratto di ogni campo è in schema.yaml.
• templates/: uno scheletro markdown per artifact, che l'agente compila.

Ecco la voce dell'artifact tasks in schema.yaml, ridotta:

artifacts:
  - id: tasks
    generates: tasks.md
    description: Checklist di implementazione con attività tracciabili
    template: tasks.md
    instruction: |
      ...ciò che viene detto all'agente quando crea tasks.md...
    requires:
      - specs
      - design

Gli schemi integrati sono inclusi nel pacchetto openspec, quindi non li modifichi mai in place. Ottieni una tua copia tramite fork.

Creare il proprio schema personalizzato

Esistono due modi per ottenere il proprio schema:

1. Forka uno schema esistente e modifica la tua copia. Inizia da qui quando uno schema esistente è vicino a ciò che vuoi, perché tutto in esso funziona già.
2. Parti da zero quando nessuno di essi si adatta, creando uno schema vuoto con openspec schema init.

Forkare uno schema esistente

1. Forka lo schema da cui vuoi partire, eseguendo dal root del tuo progetto:

   $ openspec schema fork spec-driven
   
   Nota: I comandi schema sono sperimentali e possono cambiare.
   ✔ Forkato 'spec-driven' in 'spec-driven-custom'
   
   Source: .../openspec/schemas/spec-driven (package)
   Destination: /your-project/openspec/schemas/spec-driven-custom

   Passa un secondo argomento per scegliere il nome (openspec schema fork spec-driven team-flow). I nomi sono in kebab-case.

2. Modifica la copia: schema.yaml e i template. Modificare il tuo fork copre cosa cambiare.

3. Validalo:

   openspec schema validate spec-driven-custom

   Questo è il comando che intercetta uno schema rotto (template mancanti, YAML errato, cicli di dipendenza) prima che tu sia nel mezzo di una modifica.

4. Indirizza il tuo progetto ad esso in openspec/config.yaml. Questo passaggio sta a te perché fork lascia config.yaml intatto:

   schema: spec-driven-custom

5. Le nuove proposte di modifica seguono ora il tuo schema. Le modifiche create in precedenza mantengono lo schema con cui sono iniziate.

Per sostituire il predefito ovunque senza toccare config.yaml, forkala con lo stesso nome: openspec schema fork spec-driven spec-driven. La copia del tuo progetto quindi sovrascrive l'integrato, come spiega Dove si trovano gli schemi.

Partire da zero

openspec schema init crea un nuovo schema invece di copiarne uno:

$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks

✔ Schema 'lite' creato
Schema creato in: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks

Lo scaffold è minimale. Gli artifact derivano solo dai quattro id integrati, e i template generati non contengono istruzioni, quindi l'agente riceve meno guida finché non ne scrivi di tue. Da lì i passaggi di fork si applicano invariati: validalo, poi indica config.yaml.

Modificare il tuo fork

Un fork ha due tipi di file da modificare:

• templates/ modifica lo scheletro di ciascun documento. Aggiungi una sezione al template tasks e ogni nuovo tasks.md inizierà con essa. Mantieni il titolo # sulla prima riga: l'artifact lo eredita, così ogni file generato si apre come un documento intitolato.
• schema.yaml modifica il workflow stesso: quali artifact esistono, ciò che ciascuno richiede prima, e l'istruzione che l'agente riceve quando lo crea.

Ad esempio, per eliminare il documento design per un flusso più snello:

1. Elimina la voce design da schema.yaml.

2. Rimuovi design dalla lista requires di tasks.

3. Valida:

   $ openspec schema validate spec-driven-custom
   
   ✓ Schema 'spec-driven-custom' è valido

Salta il passaggio 2 e validate lo intercetta:

✗ Schema 'spec-driven-custom' ha errori:
  error: Riferimento di dipendenza non valido nell'artifact 'tasks': 'design' non esiste

Valida dopo ogni modifica manuale. Altrimenti uno schema rotto emerge nel mezzo di una modifica, quando un workflow richiede un file che non c'è. Come config.yaml, le modifiche allo schema raggiungono l'agente alla successiva esecuzione.

Un fork è un'istantanea

openspec update aggiorna le skill e i comandi installati, e non tocca mai openspec/schemas/. Il tuo fork continua a funzionare esattamente come lo hai lasciato, il che significa anche che smette di ricevere miglioramenti quando lo schema integrato evolve. Per riprenderli in seguito, forka di nuovo l'integrato sotto un nuovo nome e porta le differenze.

Condividere gli schemi

Condividere uno schema significa copiarne la cartella.

• Con il tuo team: committa openspec/schemas/ e tutti nel repo lo usano.
• Tra i tuoi progetti: metti la cartella nella directory a livello utente da Dove si trovano gli schemi.
• Dalla community: il catalogo della community elenca schemi condivisi. Copiane uno in openspec/schemas/<name> e funziona come il tuo.

Stiamo lavorando a un registry di schemi, pubblico e privato, così che gli schemi possano essere installati per nome invece di copiati a mano.

Usa OpenSpec con Superpowers

Lo schema superpowers-bridge mantenuto dalla community collega gli artifact OpenSpec alle skill di esecuzione di Superpowers. Segui le note di installazione e compatibilità del bridge prima di copiarlo nel tuo progetto.

Il bridge è rilasciato fuori da OpenSpec. OpenSpec non testa né versiona la sua integrazione con Superpowers.