Schémas

Modifiez ce que OpenSpec produit : les artefacts, leur ordre et leurs modèles.

Un schéma définit ce qu'une proposition de changement produit : quels artefacts, dans quel ordre, à partir de quels modèles. Par exemple, spec-driven, le schéma par défaut livré avec, produit ces quatre éléments à peu près dans cet ordre, chacun s'appuyant sur ce qui précède :

proposal → specs → design → tasks

Dupliquez un schéma (fork) lorsque vous souhaitez qu'il s'agisse de documents différents, que ce soit moins nombreux, des noms différents ou une structure différente.

Où vivent les schémas

OpenSpec recherche un schéma à trois emplacements, dans l'ordre, et utilise le premier qu'il trouve :

1. Votre projet : openspec/schemas/, validé avec le dépôt afin que toute votre équipe en bénéficie.
2. Votre machine : ~/.local/share/openspec/schemas sur macOS et Linux (ou sous $XDG_DATA_HOME si vous l'avez défini), ou %LOCALAPPDATA%\openspec\schemas sur Windows. Les schémas présents ici sont disponibles dans tous les projets sur lesquels vous travaillez.
3. Le package : les schémas intégrés, comme spec-driven, sont livrés à l'intérieur d'openspec lui-même.

Le même nom peut exister à plusieurs endroits, et l'emplacement le plus spécifique l'emporte. openspec schema which affiche la copie utilisée :

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

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

Contenu d'un schéma

Un schéma est défini par un dossier de fichiers simples : un schema.yaml qui déclare les artefacts, et un modèle pour chacun d'eux. Voici le schéma intégré spec-driven :

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

• schema.yaml : déclare chaque artefact, le fichier qu'il génère, le modèle de départ, ce qu'il requiert au préalable et l'instruction que l'agent reçoit lors de sa création. Le contrat de chaque champ se trouve dans schema.yaml.
• templates/ : un squelette markdown par artefact, que l'agent remplit.

Voici l'entrée de l'artefact tasks dans schema.yaml, allégée :

artifacts:
  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    instruction: |
      ...what the agent is told when creating tasks.md...
    requires:
      - specs
      - design

Les schémas intégrés sont livrés dans le package openspec, vous ne les modifiez donc jamais directement. Vous obtenez votre propre copie en créant un fork.

Créer votre propre schéma personnalisé

Il existe deux façons d'obtenir votre propre schéma :

1. Dupliquer un schéma existant et modifier votre copie. Commencez ici lorsqu'un schéma existant est proche de ce que vous voulez, car tout y fonctionne déjà.
2. Partir de zéro lorsqu'aucun ne convient, en échafaudant un schéma vide avec openspec schema init.

Dupliquer un schéma existant

1. Dupliquez le schéma à partir duquel vous souhaitez commencer, en exécutant la commande depuis la racine de votre projet :

   $ openspec schema fork spec-driven
   
   Note: Schema commands are experimental and may change.
   ✔ Forked 'spec-driven' to 'spec-driven-custom'
   
   Source: .../openspec/schemas/spec-driven (package)
   Destination: /your-project/openspec/schemas/spec-driven-custom

   Passez un second argument pour choisir le nom (openspec schema fork spec-driven team-flow). Les noms sont en kebab-case.

2. Modifiez la copie : schema.yaml et les modèles. Modifier votre fork couvre ce qu'il faut changer.

3. Validez-le :

   openspec schema validate spec-driven-custom

   C'est la commande qui détecte un schéma défectueux (modèles manquants, YAML invalide, cycles de dépendances) avant que vous ne soyez en plein changement.

4. Pointez votre projet vers lui dans openspec/config.yaml. Cette étape vous incombe car fork ne touche pas config.yaml :

   schema: spec-driven-custom

5. Les nouvelles propositions de changement suivent désormais votre schéma. Les changements créés auparavant conservent le schéma avec lequel ils ont été lancés.

Pour remplacer la valeur par défaut partout sans toucher à config.yaml, dupliquez vers le même nom : openspec schema fork spec-driven spec-driven. La copie de votre projet masque alors le schéma intégré, comme l'explique Où vivent les schémas.

Partir de zéro

openspec schema init échafaude un nouveau schéma au lieu d'en copier un :

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

✔ Created schema 'lite'
Schema created at: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks

L'échafaudage est minimal. Les artefacts proviennent uniquement des quatre ids intégrés, et les modèles générés ne comportent aucune instruction : l'agent reçoit donc moins de guidance jusqu'à ce que vous écriviez les vôtres. À partir de là, les étapes du fork s'appliquent sans changement : validez-le, puis pointez config.yaml vers lui.

Modifier votre fork

Un fork comporte deux types de fichiers à modifier :

• templates/ modifient le squelette de chaque document. Ajoutez une section au modèle tasks et chaque nouveau tasks.md commencera avec elle. Conservez le titre # sur la première ligne : l'artefact en hérite, ainsi chaque fichier généré s'ouvre comme un document titré.
• schema.yaml modifie le workflow lui-même : quels artefacts existent, ce que chacun requiert au préalable et l'instruction que l'agent reçoit lors de sa création.

Par exemple, pour supprimer le document design pour un flux plus léger :

1. Supprimez l'entrée design de schema.yaml.

2. Retirez design de la liste requires de tasks.

3. Validez :

   $ openspec schema validate spec-driven-custom
   
   ✓ Schema 'spec-driven-custom' is valid

Ignorez l'étape 2 et la validation le détecte :

✗ Schema 'spec-driven-custom' has errors:
  error: Invalid dependency reference in artifact 'tasks': 'design' does not exist

Validez après chaque modification manuelle. Un schéma défectueux se manifesterait autrement en plein changement, lorsqu'un workflow demande un fichier qui n'existe pas. Comme pour config.yaml, les modifications de schéma parviennent à l'agent lors de l'exécution suivante.

Un fork est un instantané

openspec update actualise les compétences et commandes installées, et ne touche jamais à openspec/schemas/. Votre fork continue de fonctionner exactement tel que vous l'avez laissé, ce qui signifie également qu'il cesse de recevoir des améliorations lorsque le schéma intégré évolue. Pour les récupérer plus tard, dupliquez à nouveau le schéma intégré sous un nouveau nom et reportez les différences.

Partager des schémas

Partager un schéma revient à copier son dossier.

• Avec votre équipe : validez openspec/schemas/ et tout le monde sur le dépôt l'utilise.
• À travers vos projets : placez le dossier dans le répertoire de niveau utilisateur décrit dans Où vivent les schémas.
• Depuis la communauté : le catalogue communautaire liste les schémas partagés. Copiez-en un dans openspec/schemas/<name> et il fonctionne comme le vôtre.

Nous travaillons sur un registre de schémas, public et privé, afin que les schémas puissent être installés par nom au lieu d'être copiés manuellement.

Utiliser OpenSpec avec Superpowers

Le schéma superpowers-bridge, maintenu par la communauté, connecte les artefacts OpenSpec aux compétences d'exécution de Superpowers. Suivez les notes d'installation et de compatibilité du bridge avant de le copier dans votre projet.

Le bridge est publié en dehors d'OpenSpec. OpenSpec ne teste ni ne versionne son intégration Superpowers.