Migration vers OPSX

Ce guide vous aide à passer du flux de travail OpenSpec legacy à OPSX. La migration est conçue pour être fluide : votre travail existant est préservé et le nouveau système offre davantage de flexibilité.

Que change-t-il ?

OPSX remplace l'ancien flux de travail à phases verrouillées par une approche fluide basée sur les actions. Voici le changement essentiel :

Aspect	Legacy	OPSX
Commandes	/openspec:proposal, /openspec:apply, /openspec:archive	Par défaut : /opsx:propose, /opsx:explore, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive (commandes de flux de travail étendues facultatives)
Flux de travail	Créer tous les artefacts d'un coup	Créer de manière incrémentale ou tout d'un coup — à vous de choisir
Retour en arrière	Portes de phase contraignantes	Naturel — mettre à jour n'importe quel artefact à tout moment
Personnalisation	Structure fixe	Pilotée par schéma, entièrement modifiable
Configuration	CLAUDE.md avec marqueurs + project.md	Configuration propre dans openspec/config.yaml

Le changement de philosophie : Le travail n'est pas linéaire. OPSX cesse de faire semblant que oui.

---

Avant de Commencer

Votre Travail Existant est en Sécurité

Le processus de migration est conçu pour préserver votre travail :

• Les modifications actives dans openspec/changes/ — Complètement préservées. Vous pouvez continuer avec les commandes OPSX.
• Les modifications archivées — Intactes. Votre historique reste inchangé.
• Les spécifications principales dans openspec/specs/ — Intactes. Elles constituent votre source de vérité.
• Votre contenu dans CLAUDE.md, AGENTS.md, etc. — Préservé. Seuls les blocs de marqueurs OpenSpec sont supprimés ; tout ce que vous avez écrit reste.

Ce Qui Est Supprimé

Seuls les fichiers gérés par OpenSpec qui sont remplacés :

Quoi	Pourquoi
Anciens répertoires/fichiers de commandes slash	Remplacés par le nouveau système de compétences
openspec/AGENTS.md	Déclencheur de workflow obsolète
Marqueurs OpenSpec dans CLAUDE.md, AGENTS.md, etc.	Plus nécessaires

Emplacements des commandes héritées par outil (exemples—votre outil peut varier) :

• Claude Code : .claude/commands/openspec/
• Cursor : .cursor/commands/openspec-*.md
• Devin Desktop, anciennement Windsurf : .windsurf/workflows/openspec-*.md
• Cline : .clinerules/workflows/openspec-*.md
• Roo : .roo/commands/openspec-*.md
• GitHub Copilot : .github/prompts/openspec-*.prompt.md (extensions IDE uniquement ; non pris en charge dans Copilot CLI)
• Codex : OpenSpec utilise désormais le chemin canonique .agents/skills/openspec-*. Les fichiers SKILL.md gérés par OpenSpec sous l'ancien chemin .codex/skills ne sont réconciliés qu'après l'existence des remplacements ; les fichiers personnalisés et les copies divergentes restent en place. Si une arborescence .agents non marquée contient déjà des compétences OpenSpec, OpenSpec préserve son rendu Codex existant ($openspec-*) ou générique (/openspec-*) au lieu de deviner à partir du répertoire hérité. Sélectionnez codex explicitement avec openspec init pour changer de propriétaire. Le nettoyage des prompts hérités ne cible toujours que les noms de fichiers autorisés par OpenSpec dans $CODEX_HOME/prompts ou ~/.codex/prompts.
• Et d'autres (Augment, Continue, Amazon Q, etc.)

La migration détecte les outils que vous avez configurés et nettoie leurs fichiers hérités.

La liste des suppressions peut sembler longue, mais ce sont tous des fichiers qu'OpenSpec a créés à l'origine. Votre propre contenu n'est jamais supprimé.

Ce Qui Nécessite Votre Attention

Un fichier nécessite une migration manuelle :

openspec/project.md — Ce fichier n'est pas supprimé automatiquement car il peut contenir du contexte de projet que vous avez écrit. Vous devrez :

1. Examiner son contenu
2. Déplacer le contexte utile vers openspec/config.yaml (voir les conseils ci-dessous)
3. Supprimer le fichier lorsque vous êtes prêt

Pourquoi nous avons fait ce changement :

L'ancien project.md était passif—les agents pouvaient le lire ou non, ou oublier ce qu'ils avaient lu. Nous avons constaté que la fiabilité était inconstante.

Le nouveau contexte config.yaml est activement injecté dans chaque demande de planification OpenSpec. Cela signifie que les conventions de votre projet, la pile technologique et les règles sont toujours présentes lorsque l'IA crée des artefacts. Fiabilité accrue.

Le compromis :

Étant donné que le contexte est injecté dans chaque demande, vous voudrez être concis. Concentrez-vous sur ce qui compte vraiment :

• La pile technologique et les conventions clés
• Les contraintes non évidentes que l'IA doit connaître
• Les règles qui étaient souvent ignorées auparavant

Ne vous inquiétez pas de la perfection. Nous apprenons encore ce qui fonctionne le mieux ici, et nous améliorerons le fonctionnement de l'injection de contexte au fur et à mesure de nos expérimentations.

---

Exécution de la Migration

openspec init et openspec update détectent tous deux les fichiers hérités et vous guident à travers le même processus de nettoyage. Utilisez celui qui correspond à votre situation :

• Les nouvelles installations utilisent par défaut le profil core (propose, explore, apply, update, sync, archive).
• Les installations migrées préservent vos workflows précédemment installés en écrivant un profil custom si nécessaire.

Utilisation de openspec init

Exécutez ceci si vous souhaitez ajouter de nouveaux outils ou reconfigurer les outils configurés :

openspec init

La commande init détecte les fichiers hérités et vous guide à travers le nettoyage :

Mise à niveau vers le nouvel OpenSpec

OpenSpec utilise désormais les compétences d'agent, la norme émergente
des agents de codage. Cela simplifie votre configuration tout en gardant
tout fonctionnel comme avant.

Fichiers à supprimer
Aucun contenu utilisateur à préserver :
  • .claude/commands/openspec/
  • openspec/AGENTS.md

Fichiers à mettre à jour
Les marqueurs OpenSpec seront supprimés, votre contenu préservé :
  • CLAUDE.md
  • AGENTS.md

Nécessite votre attention
  • openspec/project.md
    Nous ne supprimerons pas ce fichier. Il peut contenir du contexte de projet utile.

    Le nouveau openspec/config.yaml a une section "context:" pour le contexte
    de planification. Elle est incluse dans chaque demande OpenSpec et fonctionne
    plus fiablement que l'ancienne approche project.md.

    Examinez project.md, déplacez tout contenu utile vers la section context
    de config.yaml, puis supprimez le fichier lorsque vous êtes prêt.

? Mettre à niveau et nettoyer les fichiers hérités ? (Y/n)

Ce qui se passe lorsque vous répondez oui :

1. Les anciens répertoires de commandes slash sont supprimés
2. Les marqueurs OpenSpec sont retirés de CLAUDE.md, AGENTS.md, etc. (votre contenu reste)
3. openspec/AGENTS.md est supprimé
4. Les nouvelles compétences sont installées dans .claude/skills/
5. openspec/config.yaml est créé avec un schéma par défaut

Utilisation de openspec update

Exécutez ceci si vous souhaitez simplement migrer et actualiser vos outils existants vers la dernière version :

openspec update

La commande update détecte et nettoie également les artefacts hérités, puis actualise les compétences/commandes générées pour correspondre à votre profil et vos paramètres de livraison actuels.

Environnements Non-Interactifs / CI

Pour les migrations scriptées :

openspec init --force --tools claude

Le drapeau --force ignore les invites et accepte automatiquement le nettoyage.

Cela inclut le nettoyage des fichiers de prompts Codex gérés par OpenSpec dans le répertoire global de prompts Codex. Le nettoyage ne cible que les noms de fichiers de prompts Codex hérités autorisés par OpenSpec, les supprime uniquement après l'existence des compétences de remplacement .agents/skills/openspec-*, et préserve tous les autres fichiers.

---

Migration de project.md vers config.yaml

L'ancien openspec/project.md était un fichier markdown libre pour le contexte du projet. Le nouveau openspec/config.yaml est structuré et—crucialement—injecté dans chaque demande de planification afin que vos conventions soient toujours présentes lorsque l'IA travaille.

Avant (project.md)

# Contexte du Projet

Ceci est un monorepo TypeScript utilisant React et Node.js.
Nous utilisons Jest pour les tests et suivons des règles ESLint strictes.
Notre API est RESTful et documentée dans docs/api.md.

## Conventions

- Toutes les API publiques doivent maintenir une compatibilité ascendante
- Les nouvelles fonctionnalités doivent inclure des tests
- Utiliser le format Given/When/Then pour les spécifications

Après (config.yaml)

schema: spec-driven

context: |
  Pile technologique : TypeScript, React, Node.js
  Tests : Jest avec React Testing Library
  API : RESTful, documentée dans docs/api.md
  Nous maintenons la compatibilité ascendante pour toutes les API publiques

rules:
  proposal:
    - Inclure un plan de rollback pour les changements risqués
  specs:
    - Utiliser le format Given/When/Then pour les scénarios
    - Référencer les modèles existants avant d'en inventer de nouveaux
  design:
    - Inclure des diagrammes de séquence pour les flux complexes

Différences Clés

project.md	config.yaml
Markdown libre	YAML structuré
Un bloc de texte	Contexte séparé et règles par artefact
Utilisation incertaine	Le contexte apparaît dans TOUS les artefacts ; les règles n'apparaissent que dans les artefacts correspondants
Aucune sélection de schéma	Le champ explicite schema: définit le workflow par défaut

Quoi Garder, Quoi Supprimer

Lors de la migration, soyez sélectif. Demandez-vous : « L'IA a-t-elle besoin de cela pour chaque demande de planification ? »

Bons candidats pour context:

• Pile technologique (langages, frameworks, bases de données)
• Modèles architecturaux clés (monorepo, microservices, etc.)
• Contraintes non évidentes (« nous ne pouvons pas utiliser la bibliothèque X parce que... »)
• Conventions critiques souvent ignorées

À déplacer vers rules: plutôt

• Formatage spécifique aux artefacts (« utiliser Given/When/Then dans les specs »)
• Critères de révision (« les propositions doivent inclure des plans de rollback »)
• Ils n'apparaissent que pour l'artefact correspondant, allégeant les autres demandes

À laisser de côté entièrement

• Les bonnes pratiques générales que l'IA connaît déjà
• Les explications verbeuses qui pourraient être résumées
• Le contexte historique qui n'affecte pas le travail actuel

Étapes de Migration

1. Créer config.yaml (s'il n'a pas déjà été créé par init) :

   schema: spec-driven

2. Ajouter votre contexte (soyez concis—ceci va dans chaque demande) :

   context: |
     Le contexte de votre projet va ici.
     Concentrez-vous sur ce que l'IA a réellement besoin de savoir.

3. Ajouter les règles par artefact (facultatif) :

   rules:
     proposal:
       - Vos recommandations spécifiques aux propositions
     specs:
       - Vos règles de rédaction de spécifications

4. Supprimer project.md une fois que vous avez déplacé tout le contenu utile.

N'y pensez pas trop. Commencez par l'essentiel et itérez. Si vous remarquez que l'IA manque quelque chose d'important, ajoutez-le. Si le contexte semble gonflé, réduisez-le. C'est un document vivant.

Besoin d'Aide ? Utilisez Cette Invite

Si vous n'êtes pas sûr de savoir comment condenser votre project.md, demandez à votre assistant IA :

Je migre de l'ancien project.md d'OpenSpec vers le nouveau format config.yaml.

Voici mon project.md actuel :
[collez le contenu de votre project.md]

Aidez-moi à créer un config.yaml avec :
1. Une section `context:` concise (elle est injectée dans chaque demande de planification, donc gardez-la serrée—concentrez-vous sur la pile technologique, les contraintes clés et les conventions souvent ignorées)
2. `rules:` pour des artefacts spécifiques si certains contenus sont spécifiques à un artefact (par exemple, « utiliser Given/When/Then » appartient aux règles de specs, pas au contexte global)

Laissez de côté tout ce qui est générique et déjà connu des modèles d'IA. Soyez impitoyable sur la brièveté.

L'IA vous aidera à identifier ce qui est essentiel par rapport à ce qui peut être supprimé.

---

Les Nouvelles Commandes

La disponibilité des commandes dépend du profil :

Par défaut (profil core) :

Commande	Objectif
/opsx:propose	Créer un changement et générer les artefacts de planification en une seule étape
/opsx:explore	Réfléchir à des idées sans structure
/opsx:apply	Implémenter les tâches depuis tasks.md
/opsx:update	Réviser les artefacts de planification d'un changement et les garder cohérents
/opsx:sync	Fusionner les spécifications delta dans les spécifications principales
/opsx:archive	Finaliser et archiver le changement

Workflow étendu (sélection personnalisée) :

Commande	Objectif
/opsx:new	Démarrer une nouvelle structure de changement
/opsx:continue	Créer l'artefact suivant (un à la fois)
/opsx:ff	Avance rapide—créer les artefacts de planification d'un coup
/opsx:verify	Valider que l'implémentation correspond aux spécifications
/opsx:bulk-archive	Archiver plusieurs changements à la fois
/opsx:onboard	Workflow d'intégration guidé de bout en bout

Activez les commandes étendues avec openspec config profile, puis exécutez openspec update.

Correspondance des Commandes Héritées

Héritage	Équivalent OPSX
/openspec:proposal	/opsx:propose (par défaut) ou /opsx:new puis /opsx:ff (étendu)
/openspec:apply	/opsx:apply
/openspec:archive	/opsx:archive

Nouvelles Capacités

Ces capacités font partie de l'ensemble de commandes du workflow étendu.

Création granulaire d'artefacts :

/opsx:continue

Crée un artefact à la fois en fonction des dépendances. Utilisez ceci lorsque vous souhaitez examiner chaque étape.

Mode exploration :

/opsx:explore

Réfléchissez à des idées avec un partenaire avant de vous engager dans un changement.

---

Comprendre la nouvelle architecture

De verrouillé à fluide

L'ancien flux de travail imposait une progression linéaire :

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
│    PHASE     │      │    PHASE     │      │    PHASE     │
└──────────────┘      └──────────────┘      └──────────────┘

Si vous êtes en phase d'implémentation et que vous réalisez que la conception est erronée ?
Dommage. Les portes de phase ne permettent pas de revenir en arrière facilement.

OPSX utilise des actions, et non des phases :

         ┌───────────────────────────────────────────────┐
         │           ACTIONS (pas des phases)            │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    n'importe quel ordre       │
         └───────────────────────────────────────────────┘

Graphique des dépendances

Les artefacts forment un graphe orienté. Les dépendances sont des prérequis, pas des barrières :

                        proposal
                       (nœud racine)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (nécessite :                  (nécessite :
         proposal)                   proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (nécessite :
                     specs, design)

Lorsque vous exécutez /opsx:continue, il vérifie ce qui est prêt et propose l'artefact suivant. Vous pouvez également créer plusieurs artefacts prêts dans n'importe quel ordre.

Compétences vs Commandes

L'ancien système utilisait des fichiers de commandes spécifiques aux outils :

.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md

OPSX utilise la norme émergente skills (compétences) :

.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...

Les compétences sont reconnues par plusieurs outils de codage IA et fournissent des métadonnées plus riches.

Codex est uniquement basé sur les compétences dans OPSX. OpenSpec ne génère plus de fichiers de prompt personnalisés pour Codex ; utilisez plutôt les répertoires générés .agents/skills/openspec-*.

---

Poursuivre les modifications existantes

Vos modifications en cours fonctionnent sans problème avec les commandes OPSX.

Vous avez une modification active issue de l'ancien flux de travail ?

/opsx:apply add-my-feature

OPSX lit les artefacts existants et reprend là où vous vous êtes arrêté.

Vous souhaitez ajouter plus d'artefacts à une modification existante ?

/opsx:continue add-my-feature

Affiche ce qui est prêt à être créé en fonction de ce qui existe déjà.

Besoin de voir le statut ?

openspec status --change add-my-feature

---

Le nouveau système de configuration

Structure de config.yaml

# Requis : Schéma par défaut pour les nouvelles modifications
schema: spec-driven

# Optionnel : Contexte du projet (max 50 Ko)
# Injecté dans TOUTES les instructions d'artefacts
context: |
  Votre contexte projet, pile technique,
  conventions et contraintes.

# Optionnel : Règles par artefact
# Injectées uniquement dans les artefacts correspondants
rules:
  proposal:
    - Inclure un plan de retour arrière
  specs:
    - Utiliser le format Given/When/Then
  design:
    - Documenter les stratégies de repli
  tasks:
    - Découper en tranches de maximum 2 heures

Résolution du schéma

Pour déterminer quel schéma utiliser, OPSX vérifie dans l'ordre :

1. Indicateur CLI : --schema <nom> (priorité la plus élevée)
2. Métadonnées de la modification : .openspec.yaml dans le répertoire de la modification
3. Configuration du projet : openspec/config.yaml
4. Par défaut : spec-driven

Schémas disponibles

Schéma	Artefacts	Idéal pour
spec-driven	proposal → specs → design → tasks	La plupart des projets

Lister tous les schémas disponibles :

openspec schemas

Schémas personnalisés

Créez votre propre flux de travail :

openspec schema init my-workflow

Ou fork-en un existant :

openspec schema fork spec-driven my-workflow

Voir Personnalisation pour plus de détails.

---

Dépannage

"Fichiers legacy détectés en mode non interactif"

Vous exécutez dans un environnement CI ou non interactif. Utilisez :

openspec init --force

Commandes non visibles après la migration

Redémarrez votre IDE. Les compétences sont détectées au démarrage.

"ID d'artefact inconnu dans les règles"

Vérifiez que vos clés rules: correspondent aux IDs d'artefacts de votre schéma :

• spec-driven : proposal, specs, design, tasks

Exécutez ceci pour voir les IDs d'artefacts valides :

openspec schemas --json

Configuration non appliquée

1. Assurez-vous que le fichier se trouve à openspec/config.yaml (et non .yml)
2. Validez la syntaxe YAML
3. Les modifications de configuration prennent effet immédiatement — aucun redémarrage nécessaire

project.md non migré

Le système conserve intentionnellement project.md car il peut contenir votre contenu personnalisé. Examinez-le manuellement, déplacez les parties utiles vers config.yaml, puis supprimez-le.

Vous voulez voir ce qui serait nettoyé ?

Exécutez init et refusez l'invite de nettoyage — vous verrez le résumé complet de la détection sans qu'aucune modification ne soit apportée.

---

Référence rapide

Fichiers après la migration

project/
├── openspec/
│   ├── specs/                    # Inchangé
│   ├── changes/                  # Inchangé
│   │   └── archive/              # Inchangé
│   └── config.yaml               # NOUVEAU : Configuration du projet
├── .claude/
│   └── skills/                   # NOUVEAU : Compétences OPSX
│       ├── openspec-propose/     # profil core par défaut
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-change/
│       └── ...                   # le profil étendu ajoute new/continue/ff/etc.
├── CLAUDE.md                     # Marqueurs OpenSpec supprimés, votre contenu conservé
└── AGENTS.md                     # Marqueurs OpenSpec supprimés, votre contenu conservé

Ce qui a disparu

• .claude/commands/openspec/ — remplacé par .claude/skills/
• openspec/AGENTS.md — obsolète
• openspec/project.md — migrer vers config.yaml, puis supprimer
• Blocs de marqueurs OpenSpec dans CLAUDE.md, AGENTS.md, etc.

Aide-mémoire des commandes

/opsx:propose      Démarrer rapidement (profil core par défaut)
/opsx:apply        Implémenter les tâches
/opsx:archive      Terminer et archiver

# Flux de travail étendu (si activé) :
/opsx:new          Échafauder une modification
/opsx:continue     Créer l'artefact suivant
/opsx:ff           Créer les artefacts de planification

---

Obtenir de l'aide

• Discord : discord.gg/YctCnvvshC
• Problèmes GitHub : github.com/Fission-AI/OpenSpec/issues
• Documentation : docs/opsx.md pour la référence complète OPSX