Skills
Chaque skill OpenSpec : arguments, ce qu'il crée et ce qu'il renvoie.
Les skills se présentent en deux ensembles :
- Core : installés par défaut, la boucle de planification principale.
- Optional : installés uniquement lorsque vous les ajoutez, via Profiles.
Chaque skill attend un projet qui utilise déjà OpenSpec. Avant sa première étape qui écrit quelque chose, une skill vérifie la présence d'une racine résolue. Ce qui se passe lorsqu'il n'y en a pas dépend de la façon dont la skill a été atteinte :
- Sélection automatique : votre agent a choisi la skill de lui-même, sans que vous nommiez OpenSpec. Il abandonne OpenSpec et répond à votre demande normalement, comme il le ferait si OpenSpec n'était pas installé.
- Demande OpenSpec explicite : vous avez nommé OpenSpec, nommé la skill ou exécuté sa commande. Elle s'arrête avant d'écrire et demande comment procéder : exécuter
openspec initici, cibler un store avec--store <id>, ou continuer sans OpenSpec. Elle attend votre réponse.
Les commandes relèvent toujours du second cas. Un projet dont openspec/config.yaml nomme un store que cette machine ne peut pas résoudre (non enregistré, ou une ligne store: mal formée) n'est pas traité comme non initialisé : la skill s'arrête et affiche l'erreur de store avec sa correction. Aucune skill ne crée de répertoire openspec/ de son propre chef dans l'un ou l'autre cas. Les entrées ci-dessous décrivent ce que fait chaque skill une fois qu'une racine est en place.
| Skill | Job | Type |
|---|---|---|
| openspec-explore | Réfléchir à une idée avant qu'elle ne devienne une change proposal | Core |
| openspec-propose | Créer une change proposal avec tous ses artefacts de planification en une seule étape | Core |
| openspec-apply-change | Implémenter les tâches d'une change proposal | Core |
| openspec-update-change | Réviser le plan d'une change proposal | Core |
| openspec-sync-specs | Fusionner les mises à jour de spec d'une change proposal dans specs/ | Core |
| openspec-archive-change | Déplacer une change proposal terminée vers l'archive | Core |
| openspec-new-change | Démarrer une change proposal comme un scaffold vide | Optional |
| openspec-continue-change | Créer l'artefact de planification suivant, un par un | Optional |
| openspec-ff-change | Créer une change proposal avec tous les artefacts dont l'implémentation a besoin, en une seule passe | Optional |
| openspec-verify-change | Vérifier que l'implémentation correspond au plan | Optional |
| openspec-bulk-archive-change | Archiver plusieurs change proposals en une fois | Optional |
| openspec-onboard | Apprendre le workflow en réalisant une vraie change proposal de bout en bout | Optional |
Chaque entrée ci-dessous nomme la skill qui possède l'étape suivante. Lorsque votre profil omet cette skill, les fichiers installés ne la nomment jamais : le transfert devient la commande openspec équivalente, ou une simple demande envers vous, et une ligne qui n'existe que pour pointer vers une skill absente n'est tout simplement pas écrite. Ainsi, les skills que vous avez transfèrent toujours vers des skills que vous avez. L'ensemble que vous obtenez dépend de Profiles.
openspec-explore
Réfléchissez à une idée avant qu'elle ne devienne une proposition de changement.
| Contract | Description |
|---|---|
| Arguments | Un sujet : une idée, un problème, une comparaison ou le nom d'une proposition de changement existante à explorer dans son contexte. Sans indication, il entre en mode exploration. |
| Crée | Rien par défaut. Il lit et investigate uniquement. Sur demande, il capture les insights : une nouvelle proposition de changement sous openspec/changes/<name>/, ou des mises à jour de la proposition, du design, des specs ou des tâches d'une proposition existante. Jamais de code. |
| Réponse | Une conversation ouverte sans output requis. Lorsque la réflexion se cristallise, il résume le problème, l'approche, les questions ouvertes et les prochaines étapes, et propose de les capturer. Vous décidez. L'implémentation ne commence jamais ici. |
openspec-propose
Créez une proposition de changement et générez tous ses artefacts de planification en une seule étape.
| Contract | Description |
|---|---|
| Arguments | Un nom en kebab-case (add-dark-mode) ou une description simple. Demande si vous ne fournissez ni l'un ni l'autre. |
| Crée | openspec/changes/<name>/ avec chaque artefact défini par le schéma, dans l'ordre des dépendances (spéc-driven : proposition, deltas de spec, design, tâches). Jamais de code. |
| Réponse | Les artefacts créés, prêts pour révision, et l'étape suivante. Il s'arrête là ; l'implémentation attend openspec-apply-change. |
openspec-apply-change
Implémentez les tâches d'une proposition de changement, en parcourant la liste jusqu'à ce qu'elles soient terminées ou bloquées.
| Contract | Description |
|---|---|
| Arguments | Un nom de proposition de changement (add-auth), optionnel. Si la cible est ambiguë, il liste les propositions de changement actives et vous demande d'en choisir une. |
| Crée | Du code : les changements minimaux que chaque tâche demande, dans vos fichiers de projet. Dans la proposition de changement, il coche chaque tâche terminée (- [ ] vers - [x]) dans le fichier suivi identifié par sourcePath et line basé sur un. Un schéma peut suivre les tâches dans plusieurs fichiers. |
| Réponse | Progression par tâche, puis un décompte global (N/M tâches terminées). Tout est fait : suggère openspec-archive-change. Bloqué par des artefacts manquants : pointe vers openspec-continue-change, ou vers openspec status et openspec instructions lorsque cette compétence n'est pas installée (le profil core l'exclut). Tâches peu claires ou erreurs : fait une pause et demande. |
openspec-update-change
Révisez les artefacts de planification existants d'une proposition de changement et maintenez-les cohérents entre eux.
| Contract | Description |
|---|---|
| Arguments | Un nom de proposition de changement, optionnel, plus la révision souhaitée. Sans révision indiquée, il effectue une revue de cohérence : les artefacts sont vérifiés les uns par rapport aux autres pour détecter les contradictions, les lacunes et les duplications. |
| Crée | Modifie les fichiers d'artefacts qui existent déjà. Une exception : pour un artefact écrit sous forme de glob, comme specs/**/*.md, qui a déjà au moins un fichier, il peut ajouter un fichier compagnon manquant une fois que vous confirmez le chemin. Un artefact sans fichier relève de openspec-continue-change. Sans cette compétence (le profil core l'exclut), il pointe vers openspec status et openspec instructions à la place. Jamais de code. |
| Réponse | Affiche chaque révision proposée et ne l'écrit qu'après votre confirmation, un artefact à la fois. Se termine par ce qui a été révisé et l'étape suivante ; l'implémentation attend openspec-apply-change. |
openspec-sync-specs
Fusionnez les mises à jour de spec d'une proposition de changement dans specs/ sans l'archiver.
| Contract | Description |
|---|---|
| Arguments | Un nom de proposition de changement, optionnel. Vous pouvez également nommer un sous-ensemble de ses deltas de spec, et seuls ceux-ci seront synchronisés. |
| Crée | Modifie ou crée openspec/specs/<capability-path>/spec.md pour chaque delta de spec, en fusionnant les exigences ajoutées, modifiées, supprimées et renommées dans la spec principale. Jamais de code. |
| Réponse | Un résumé par capacité des exigences ajoutées, modifiées, supprimées ou renommées, après validation des specs mises à jour. La proposition de changement reste active ; l'archivage attend openspec-archive-change. |
openspec-archive-change
Déplacez une proposition de changement terminée vers les archives.
| Contract | Description |
|---|---|
| Arguments | Un nom de proposition de changement, optionnel. |
| Crée | Déplace le dossier de la proposition de changement vers openspec/changes/archive/YYYY-MM-DD-<name>/ (aucune date ajoutée si le nom en commence déjà par une). Avec votre approbation, il synchronise d'abord les deltas de spec en attente. Lorsque openspec-sync-specs est installé, il exécute ce workflow. Sinon, il fusionne lui-même les deltas de spec dans les specs principales. Jamais de code. |
| Réponse | Avertit et demande avant d'archiver avec des artefacts ou tâches incomplets, et demande s'il faut synchroniser lorsque des deltas de spec existent. Se termine par un résumé : nom, schéma, emplacement de l'archive, statut de synchronisation des specs et avertissements éventuels. |
openspec-new-change
Démarrez une proposition de changement comme un échafaudage vide.
| Contract | Description |
|---|---|
| Arguments | Un nom en kebab-case (add-user-auth) ou une description simple, plus un nom de schéma uniquement pour un workflow non par défaut. Demande ce que vous souhaitez construire si vous ne fournissez ni l'un ni l'autre. |
| Crée | openspec/changes/<name>/ comme un échafaudage vide : aucun artefact pour le moment, jamais de code. |
| Réponse | Le nom et l'emplacement de l'échafaudage, la séquence d'artefacts du workflow, le statut (0/N terminé) et le modèle du premier artefact. La rédaction des artefacts attend openspec-continue-change. |
openspec-continue-change
Créez l'artefact de planification suivant dans une proposition de changement, un à la fois.
| Contract | Description |
|---|---|
| Arguments | Un nom de proposition de changement, optionnel. Si toujours ambigu, il vous demande de choisir parmi les plus récemment modifiées. |
| Crée | L'unique artefact prêt suivant dans la séquence du schéma, écrit dans le dossier de la proposition de changement. Un artefact par exécution, jamais de code. |
| Réponse | L'artefact créé, la progression (N sur M terminés) et les artefacts débloqués. Lorsque la planification est terminée, il l'indique ; l'implémentation passe à openspec-apply-change. |
openspec-ff-change
Créez une proposition de changement et tous les artefacts de planification dont l'implémentation a besoin, en une seule passe.
| Contract | Description |
|---|---|
| Arguments | Un nom en kebab-case ou une description simple. Demande si vous ne fournissez ni l'un ni l'autre. Si la proposition de changement nommée existe déjà, il suggère de la continuer à la place. |
| Crée | openspec/changes/<name>/ et tous les artefacts de planification dont l'implémentation a besoin, dans l'ordre des dépendances (spéc-driven : proposition, specs, design, tâches), en excluant uniquement les artefacts marqués comme ignorés ou conditionnels. Jamais de code. |
| Réponse | Le nom et l'emplacement de la proposition de changement, chaque artefact créé, et tout artefact conditionnel ignoré avec la raison. Il s'arrête là ; l'implémentation attend openspec-apply-change. |
openspec-verify-change
Vérifiez que l'implémentation correspond aux artefacts de la proposition de changement.
| Contract | Description |
|---|---|
| Arguments | Un nom de proposition de changement, optionnel. En cas d'ambiguïté, il demande en listant les propositions de changement qui ont un artefact de tâches. |
| Crée | Rien. Il lit les artefacts de la proposition de changement et la base de code. La vérification se limite à un rapport. |
| Réponse | Un rapport : un tableau de bord pour l'Exhaustivité, la Correction et la Cohérence, puis des problèmes CRITIQUES, AVERTISSEMENTS et SUGGESTIONS avec recommandations, et une évaluation finale de la maturité pour archivage. Il ne modifie rien et n'archive pas. |
openspec-bulk-archive-change
Archivez plusieurs propositions de changement en une fois.
| Contract | Description |
|---|---|
| Arguments | Aucun. Il liste les propositions de changement actives et vous demande d'en sélectionner un nombre quelconque, avec une option pour toutes. S'il n'y en a aucune d'active, il l'indique et s'arrête. |
| Crée | openspec/changes/archive/YYYY-MM-DD-<name>/ par proposition de changement archivée (les noms déjà datés conservent leur préfixe). Les deltas de spec de chacune sont synchronisés d'abord via openspec-sync-specs. Jamais de code. |
| Réponse | Un tableau de statut par proposition de changement et une confirmation pour l'ensemble du lot, puis un résumé des archivées, ignorées et en échec, plus les résultats de synchronisation des specs. Lorsque deux propositions de changement touchent la même spec, il vérifie la base de code et synchronise les deltas implémentés du plus ancien au plus récent. |
openspec-onboard
Apprenez le workflow en réalisant une vraie proposition de changement de bout en bout.
| Contract | Description |
|---|---|
| Arguments | Aucun. Il analyse votre base de code pour trouver de petites tâches de démarrage et vous demande d'en choisir une ou de décrire la vôtre. |
| Crée | Une vraie proposition de changement pour la tâche choisie, un artefact à la fois, puis du vrai code une fois que vous confirmez l'implémentation. Archive la proposition de changement à la fin. |
| Réponse | Une visite guidée narrée du cycle complet avec des pauses pour votre contribution : explorer, créer, construire chaque artefact, implémenter, archiver. Se termine par un récapitulatif et un pointeur vers openspec-propose. Prend environ 15 à 20 minutes. |