Dépannage

Des solutions concrètes pour des problèmes concrets. Chaque entrée nomme un symptôme, explique la cause probable en une phrase et vous donne la solution. Si vous ne trouvez pas votre problème ici, la FAQ peut vous aider, et le Discord vous aidera certainement.

Installation et configuration

openspec: command not found

Le CLI n'est pas installé, ou votre shell ne parvient pas à le trouver. Installez-le globalement et vérifiez :

npm install -g @fission-ai/openspec@latest
openspec --version

S'il est installé mais toujours introuvable, il se peut que le répertoire bin global de npm ne soit pas dans votre PATH. Exécutez npm prefix -g pour voir où vivent les packages globaux : sur macOS et Linux, les binaires se trouvent dans le sous-répertoire bin/ de ce répertoire, et sur Windows, ils s'y trouvent directement. Assurez-vous que ce chemin est bien inclus dans votre PATH. (npm bin -g a été supprimé dans npm 9.)

Si vous avez utilisé l'installation assistée par IA, c'est le point de passage attendu : cette invite indique à votre assistant de vous montrer la modification du PATH au lieu de modifier lui-même vos fichiers de démarrage du shell.

"Requires Node.js 20.19.0 or higher"

OpenSpec fonctionne avec Node 20.19.0+. Vérifiez votre version et mettez à niveau si nécessaire :

node --version

Si vous utilisez bun pour installer OpenSpec, notez qu'OpenSpec s'exécute toujours sur Node, donc vous devez avoir Node 20.19.0+ disponible dans votre PATH, indépendamment de bun. Voir Installation.

openspec init n'a pas configuré mon outil IA

Init demande quels outils configurer. Si vous avez ignoré votre outil ou souhaitez en ajouter un autre, exécutez simplement à nouveau la commande, ou utilisez la forme non interactive :

openspec init --tools claude,cursor

La liste complète des identifiants d'outils se trouve dans Outils pris en charge. Utilisez --tools all pour tout installer, --tools none pour ignorer la configuration des outils.

Les commandes n'apparaissent pas

Si /opsx:propose (ou l'équivalent de votre outil) n'apparaît pas ou ne fait rien, parcourez cette liste. Elles sont classées du plus rapide à vérifier au plus lent.

1. Vous êtes peut-être au mauvais endroit. Les commandes slash s'utilisent dans le chat de votre assistant IA, pas dans votre terminal. Si vous avez tapé /opsx:propose dans votre shell, c'est là que réside le problème. Voir Comment fonctionnent les commandes.

2. Régénérez les fichiers. Depuis la racine de votre projet :

   openspec update

   Cela réécrit les fichiers de compétences (skills) et de commandes pour chaque outil que vous avez configuré.

   Les fichiers d'instruction proviennent du CLI installé, donc un CLI obsolète signalera que tout est à jour sans jamais écrire les nouveaux workflows. openspec update vérifie désormais cela et propose une mise à niveau — acceptez l'offre si elle apparaît.

3. Redémarrez votre assistant. La plupart des outils analysent les compétences et les commandes au démarrage. Une nouvelle fenêtre suffit souvent.

4. Confirmez l'existence des fichiers. Pour Claude Code, vérifiez que .claude/skills/ contient des dossiers openspec-*. D'autres outils utilisent leurs propres répertoires, tous listés dans Outils pris en charge.

5. Vérifiez que vous avez initialisé ce projet. Les compétences sont écrites par projet. Si vous avez cloné un dépôt ou changé de dossier, exécutez openspec init (ou openspec update) à cet emplacement.

6. Confirmez que votre outil prend en charge les fichiers de commandes. Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent et la cible partagée .agents ne génèrent pas de fichiers de commandes opsx-* ; ils utilisent des invocations basées sur les compétences, donc /opsx ne sera jamais en auto-complétion pour eux. Tapez $openspec-propose dans Codex, /skill:openspec-propose dans Kimi Code, et /openspec-propose dans les autres. La cible partagée .agents est indépendante du fournisseur, donc /openspec-propose est la forme courante plutôt que garantie — si votre assistant n'y répond pas, consultez sa propre documentation pour savoir comment invoquer une compétence. Amazon Q obtient bien des fichiers de commandes, mais les charge dans sa bibliothèque de invites (prompt library) plutôt que dans son menu slash — tapez @opsx-propose là-bas, pas /opsx. La forme de chaque outil est listée dans Comment invoquer.

Travailler avec les modifications

"Change not found"

La commande n'a pas pu déterminer de quelle modification il s'agissait. Nommez-la explicitement, ou vérifiez ce qui existe :

openspec list                    # voir les modifications actives
/opsx:apply add-dark-mode        # nommer la modification dans le chat

Confirmez également que vous êtes dans le bon répertoire de projet.

"No artifacts ready"

Chaque artefact est soit déjà créé, soit bloqué en attendant une dépendance. Voyez ce qui bloque :

openspec status --change <name>

Créez ensuite la dépendance manquante en premier. Rappelez-vous l'ordre : la proposition permet les spécifications et la conception ; les spécifications et la conception ensemble permettent les tâches.

openspec validate signale des avertissements ou des erreurs

La validation vérifie vos spécifications et vos modifications pour détecter les problèmes structurels. Lisez le message : il nomme le fichier et le problème.

openspec validate <name>           # valider un élément
openspec validate --all            # valider tout
openspec validate --all --strict   # contrôles plus stricts, utiles pour CI
openspec validate --archived       # échouer si les modifications archivées ont des tâches non cochées

Les causes courantes sont une section requise manquante (comme une spécification sans scénarios) ou un en-tête de delta mal formé. Corrigez le fichier et relancez. La référence CLI documente le format de sortie.

Un message mérite une note à part entière :

MODIFIED "<requirement>" omets scenario(s) the current spec still has: "<scenario>"

Une exigence (requirement) MODIFIED remplace entièrement le bloc d'exigences, elle doit donc conserver tous les scénarios qui survivent à la modification, pas seulement ceux que vous avez modifiés. Copiez les scénarios nommés depuis openspec/specs/<chemin-capabilite>/spec.md dans le delta, en préservant les répertoires de domaine dans le chemin. Cela apparaît souvent sur une ancienne modification après qu'une autre modification ait ajouté un scénario à la même exigence — l'archive refuse cette modification de toute façon, et la validation le dit maintenant avant que vous ne la mettiez en œuvre.

L'IA a créé des artefacts incomplets ou incorrects

L'IA n'avait pas assez de contexte. Quelques leviers peuvent aider :

• Ajoutez du contexte de projet dans openspec/config.yaml afin que votre pile et vos conventions soient injectées dans chaque demande. Voir Personnalisation.
• Ajoutez des rules: par artefact pour des directives qui ne s'appliquent qu'à, par exemple, les spécifications.
• Fournissez une description plus détaillée lorsque vous proposez.
• Utilisez /opsx:continue étendu pour créer un artefact à la fois et le revoir, au lieu de /opsx:ff qui les fait tous à la fois.

L'archive ne termine pas, ou avertit de tâches incomplètes

L'archive ne bloquera pas sur des tâches incomplètes, mais elle vous avertit, car archiver signifie généralement que le travail est terminé. Si des tâches restent intentionnellement (vous archivez une modification partielle), continuez. Sinon, terminez d'abord les tâches. L'archive proposera également de synchroniser vos deltas de spécifications dans les spécifications principales si vous ne l'avez pas encore fait ; dites oui sauf si vous avez une raison de ne pas le faire.

"User force closed the prompt with 0 null"

Quelque chose a exécuté openspec archive là où personne ne peut répondre à une question — un agent IA l'appelant depuis un outil, un job CI, ou n'importe quel shell avec l'entrée standard (stdin) fermée. Archive pose jusqu'à trois confirmations, et une confirmation impossible à répondre échouait auparavant avec ce message brut.

Passez --yes pour y répondre d'emblée :

openspec archive <change-name> --yes

Conservez tous les drapeaux (flags) que vous passiez déjà — --skip-specs et --no-validate changent ce que fait l'archive, donc un redémarrage avec uniquement --yes n'est pas la même commande. Les versions actuelles nomment le drapeau pour vous et impriment une ligne Fix: que vous pouvez coller. Si vous vouliez choisir dans une liste, passez explicitement le nom de la modification : le sélecteur a besoin d'une réponse aussi.

Si vous avez au contraire exécuté l'archive avec sa sortie redirigée vers un fichier ou capturée par un outil et que vous avez pipé une réponse (printf 'y\n' | openspec archive …), les anciennes versions écrivaient des codes d'échappement terminal dans cette capture lors de l'affichage de la demande — dans certains environnements, au point de gonfler considérablement le fichier. Les versions actuelles lisent les invites de confirmation comme du texte brut chaque fois que stdout n'est pas un terminal, et un openspec archive sans argument (qui afficherait autrement un sélecteur de modification interactif) vous demande de passer un nom de modification d'emblée au lieu de rendre un menu dans la capture. Dans les deux cas, les exécutions redirigées et par agent restent propres ; passer --yes (avec un nom de modification) saute les invites entièrement.

Configuration

Mon config.yaml n'est pas appliqué

Trois suspects habituels :

1. Mauvais nom de fichier. Il doit être openspec/config.yaml, pas .yml.
2. YAML invalide. Passez-le dans n'importe quel validateur YAML ; le CLI signale également les erreurs de syntaxe avec les numéros de ligne.
3. Vous attendiez un redémarrage. Vous n'en avez pas besoin. Les modifications de configuration prennent effet immédiatement.

"Unknown artifact ID in rules: X"

Une clé sous rules: ne correspond à aucun artefact de votre schéma. Pour le schéma par défaut spec-driven, les identifiants valides sont proposal, specs, design, tasks. Pour voir les identifiants pour n'importe quel schéma :

openspec schemas --json

"Context too large"

Le champ context: est limité à 50 Ko, intentionnellement, car il est injecté dans chaque demande. Résumez-le, ou liez vers des documents plus longs au lieu de les coller. Un contexte léger produit également de meilleurs résultats, plus rapides.

"Schema not found"

Le nom de schéma que vous avez référencé n'existe pas. Listez ce qui est disponible et vérifiez l'orthographe :

openspec schemas                    # lister les schémas disponibles
openspec schema which <name>        # voir d'où un schéma se résout
openspec schema init <name>         # en créer un personnalisé

Voir Personnalisation.

Migration depuis le workflow hérité

"Legacy files detected in non-interactive mode"

Vous êtes en CI ou dans un shell non interactif, et OpenSpec a trouvé d'anciens fichiers à nettoyer mais ne peut pas vous demander. Approuvez automatiquement :

openspec init --force

Pour Codex, OpenSpec peut détecter d'anciens fichiers de prompts gérés dans $CODEX_HOME/prompts ou ~/.codex/prompts. Ce nettoyage se limite aux noms de fichiers de prompts Codex hérités autorisés par OpenSpec, et openspec init non interactif ne supprime que les fichiers dont les compétences de remplacement .agents/skills/openspec-* existent. openspec update non interactif laisse tous les nettoyages hérités intacts sauf si vous passez --force.

Les commandes n'ont pas apparaître après la migration

Redémarrez votre IDE. Les compétences sont détectées au démarrage. Si elles n'apparaissent toujours pas, exécutez openspec update et vérifiez les emplacements des fichiers dans Outils pris en charge.

Mon ancien project.md n'a pas été migré

C'est intentionnel. OpenSpec ne supprime jamais automatiquement project.md car il peut contenir du contexte que vous avez écrit. Déplacez les parties utiles dans la section context: de config.yaml, puis supprimez-le vous-même. Le Guide de migration détaille cette procédure, y compris une invite que vous pouvez donner à votre IA pour effectuer la distillation.

Toujours bloqué ?

• Discord : discord.gg/YctCnvvshC
• GitHub Issues : github.com/Fission-AI/OpenSpec/issues
• Depuis votre terminal : openspec feedback "what went wrong" ouvre un ticket pour vous.

Lorsque vous signalez un problème, incluez votre version d'OpenSpec (openspec --version), votre version de Node (node --version), votre outil IA, ainsi que la commande exacte et la sortie. Cela accélère grandement l'aide.