Workflows

Ce guide présente les schémas de workflow courants pour OpenSpec et le moment où utiliser chacun d'entre eux. Pour la configuration de base, consultez Getting Started. Pour la référence des commandes, consultez Commands.

Philosophie : Actions, non phases

Les workflows traditionnels vous contraignent à passer par des phases : planification, puis implémentation, puis terminé. Mais le travail réel ne rentre pas facilement dans des cases.

OPSX adopte une approche différente :

Traditional (phase-locked):

  PLANNING ────────► IMPLEMENTING ────────► DONE
      │                    │
      │   "Can't go back"  │
      └────────────────────┘

OPSX (fluid actions):

  proposal ──► specs ──► design ──► tasks ──► implement

Principes clés :

• Actions, non phases - Les commandes sont des choses que vous pouvez faire, pas des étapes dans lesquelles vous êtes bloqué
• Les dépendances sont des facilitateurs - Elles montrent ce qui est possible, pas ce qui est requis ensuite

Personnalisation : Les workflows OPSX sont pilotés par des schémas qui définissent les séquences d'artefacts. Consultez Customization pour plus de détails sur la création de schémas personnalisés.

Aperçu du flux de travail

Le flux de travail par défaut reste fluide : l'exploration et la vérification sont facultatives, et vous pouvez mettre à jour les artefacts de planification chaque fois que l'implémentation révèle quelque chose de nouveau.

flowchart TD
    Idea["Idea or problem"] --> Explore["/opsx:explore<br/>(optional)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Planning artifacts<br/>ready?"}
    Review -->|"Refine"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Implement"| Apply["/opsx:apply"]
    Apply -->|"Plan changed"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(optional, custom selection)"]
    Apply --> Sync["/opsx:sync<br/>(optional before archive)"]
    Verify --> Verified{"Ready to archive?"}
    Verified -->|"Fix implementation"| Apply
    Verified -->|"Revise plan"| Update
    Verified -->|"Ready"| Sync
    Verified -->|"Ready"| Archive
    Sync --> Archive

L'assistant IA pilote le flux de travail, tandis que l'interface CLI fournit un squelette déterministe, l'état d'avancement et les instructions pour les artefacts :

sequenceDiagram
    actor Human
    participant Assistant as AI assistant
    participant CLI as OpenSpec CLI
    participant Files as Planning and implementation files

    Human->>Assistant: /opsx:propose "change"
    Assistant->>CLI: openspec new change
    CLI->>Files: Scaffold change metadata
    Assistant->>CLI: Request status and artifact instructions
    CLI-->>Assistant: Build order, paths, and templates
    Assistant->>Files: Write schema-defined planning artifacts
    Assistant-->>Human: Present artifacts for review

    Human->>Assistant: /opsx:apply
    Assistant->>CLI: Request apply instructions
    CLI-->>Assistant: Context files and task state
    Assistant->>Files: Implement tasks and update checkboxes
    Assistant-->>Human: Report implementation status

    Human->>Assistant: /opsx:archive
    Assistant->>CLI: Request archive inputs and artifact status
    CLI-->>Assistant: Planning paths and artifact completion
    Assistant->>Files: Read task state and compare delta specs
    opt Delta specs exist
        Assistant-->>Human: Offer to sync before archiving
        alt Sync accepted
            Human->>Assistant: Confirm sync
            Assistant->>Files: Merge delta specs into main specs
        else Sync skipped
            Human->>Assistant: Archive without syncing
        end
    end
    Assistant->>Files: Move the change into the archive
    Assistant-->>Human: Report archive location and sync result

    Note over Human,CLI: CLI alternative: openspec archive change-name --yes skips confirmation prompts. It still validates, then applies any delta specs and archives

Deux modes

Chemin rapide par défaut (profil core)

Les nouvelles installations utilisent par défaut core, qui fournit :

• /opsx:explore
• /opsx:propose
• /opsx:apply
• /opsx:update
• /opsx:sync
• /opsx:archive

Flux typique :

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
  (optional)

Commencez par explorer (l'habitude à former)

/opsx:explore fait partie du profil par défaut, ce n'est pas une extension avancée. C'est l'étape à effectuer chaque fois que vous avez un problème mais pas encore de plan, ce qui est le cas la plupart du temps avec un assistant IA.

Vous : /opsx:explore

IA :   Que souhaitez-vous explorer ?

Vous : Les résultats de notre recherche semblent périmés. Je ne sais pas si c'est dû au cache,
       à l'indexation ou à la requête elle-même.

IA :   Laissez-moi regarder... [lit le service de recherche et la couche de cache]
       C'est l'index : il ne se reconstruit que la nuit, donc les modifications ne s'affichent
       qu'au lendemain. Deux options : reconstruire à l'écriture (simple, plus de charge)
       ou une invalidation de cache à courte durée de vie (plus de composants mobiles,
       moins de charge). Étant donné que votre volume d'écritures est faible,
       la reconstruction à l'écriture est la correction la plus propre. Voulez-vous la délimiter ?

Vous : Oui.

Vous : /opsx:propose rebuild-search-index-on-write

Explore ne crée aucun artefact et n'écrit aucun code. C'est une conversation gratuite, sans enjeu, qui transforme une inquiétude vague en un changement précis, afin que la proposition qui suit soit percutante. Vous savez déjà exactement ce que vous voulez ? Sautez cette étape et passez directement à /opsx:propose. Guide complet : Explorer d'abord.

Flux de travail étendu/complet (sélection personnalisée)

Si vous souhaitez des commandes explicites de squelettage et de construction (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), activez-les avec :

openspec config profile
openspec update

Modèles de flux de travail (Mode étendu)

Fonctionnalité rapide

Lorsque vous savez ce que vous voulez construire et que vous avez juste besoin d'exécuter :

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Exemple de conversation :

Vous : /opsx:new add-logout-button

IA :   Created openspec/changes/add-logout-button/
       Prêt à créer : proposal

Vous : /opsx:ff

IA :   Création de tous les artefacts de planification...
       ✓ proposal.md
       ✓ specs/
       ✓ design.md
       ✓ tasks.md
       Prêt pour l'implémentation !

Vous : /opsx:apply

IA :   Traitement des tâches...
       ✓ Bouton de déconnexion ajouté à l'en-tête
       ✓ Effacement de la session implémenté
       ✓ Boîte de dialogue de confirmation ajoutée
       Toutes les tâches terminées !

Vous : /opsx:archive

IA :   ✓ Spécifications fusionnées
       ✓ Changement archivé

Idéal pour : Petites à moyennes fonctionnalités, corrections de bugs, changements straightforward.

Exploratoire

Lorsque les exigences sont floues ou que vous devez enquêter en premier :

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

Exemple de conversation :

Vous : /opsx:explore

IA :   Que souhaitez-vous explorer ?

Vous : Je veux améliorer les performances de chargement de la page, mais je ne sais pas
       où se trouvent les goulots d'étranglement.

IA :   Laissez-moi vous aider à enquêter...
       [Analyse les tailles des bundles, identifie les requêtes lentes, examine
       les modèles de rendu des composants]

       J'ai trouvé trois principaux goulots d'étranglement :
       1. Images volumineuses non optimisées
       2. Récupération de données synchrone dans ProductList
       3. Rendus multiples dus aux changements de contexte

       Lequel souhaitez-vous traiter en premier ?

Vous : Attaquons le problème de récupération de données.

Vous : /opsx:new optimize-product-list-fetching

IA :   Changement créé. Prêt à créer : proposal

Vous : /opsx:continue

IA :   Création de la proposition basée sur notre exploration...
       [Rédige la proposition en intégrant les insights de l'enquête]

       Prêt à créer : specs, design
       Lequel souhaitez-vous ensuite ?

Vous : /opsx:continue

IA :   Création des spécifications...

Idéal pour : Optimisation des performances, débogage, décisions architecturales, exigences peu claires.

Changements parallèles

Travaillez sur plusieurs changements simultanément :

Changement A : /opsx:new ──► /opsx:ff ──► /opsx:apply (en cours)
                                         │
                                    changement de contexte
                                         │
Changement B : /opsx:new ──► /opsx:ff ──────► /opsx:apply

Exemple de conversation :

Vous : Je travaille sur add-dark-mode mais j'ai été détourné par une correction de bug

Vous : /opsx:new fix-login-redirect

IA :   Created openspec/changes/fix-login-redirect/

Vous : /opsx:ff

IA :   ✓ Artefacts de planification créés

Vous : /opsx:apply

IA :   Travail sur fix-login-redirect...
       [Implémente la correction]
       Toutes les tâches terminées !

Vous : /opsx:archive

IA :   ✓ Archivé fix-login-redirect

Vous : Reprenons le mode sombre

Vous : /opsx:apply add-dark-mode

IA :   Reprise de add-dark-mode...
       Reprend à la tâche 2.3 : Mise à jour de l'en-tête...

Idéal pour : Flux de travail parallèles, interruptions urgentes, collaboration d'équipe.

Lorsque vous avez plusieurs changements terminés, utilisez /opsx:bulk-archive :

Vous : /opsx:bulk-archive

IA :   Trouvé 3 changements terminés :
       - add-dark-mode (toutes les tâches terminées)
       - fix-login-redirect (toutes les tâches terminées)
       - update-footer (toutes les tâches terminées)

       Vérification des conflits de spécifications...
       ⚠ add-dark-mode et update-footer touchent tous deux specs/ui/

       Inspection du codebase pour résoudre...
       Les deux changements sont implémentés. Application dans l'ordre chronologique.

       Archiver les 3 changements ?

Vous : Oui

IA :   ✓ Archivé add-dark-mode
       ✓ Archivé fix-login-redirect
       ✓ Archivé update-footer
       Spécifications fusionnées dans l'ordre : add-dark-mode → update-footer

L'archivage en lot détecte lorsque plusieurs changements touchent les mêmes spécifications et résout les conflits en vérifiant ce qui est réellement implémenté.

Terminer un changement

Le flux de complétion recommandé :

/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              valide          invite à synchroniser
              l'implémentation     si nécessaire

Vérifier : Contrôler votre travail

/opsx:verify valide l'implémentation par rapport à vos artefacts selon trois dimensions :

Vous : /opsx:verify

IA :   Vérification de add-auth...

     COMPLÉTUDE
     ✓ Les 12 tâches de tasks.md sont cochées
     ✓ Toutes les exigences des specs ont du code correspondant
     ⚠ Scénario "Expiration de session après inactivité" non testé

     CORRECTITUDE
     ✓ L'implémentation correspond à l'intention de la spécification
     ✓ Les cas limites des scénarios sont gérés
     ✓ Les états d'erreur correspondent aux définitions des specs

     COHÉRENCE
     ✓ Les décisions de conception sont reflétées dans la structure du code
     ✓ Les conventions de nommage sont cohérentes avec design.md
     ⚠ La conception mentionne "événementiel" mais l'implémentation utilise le polling

     RÉSUMÉ
     ─────────────────────────────
     Problèmes critiques : 0
   Avertissements : 2
     Prêt à archiver : Oui (avec avertissements)

     Recommandations :
     1. Ajouter un test pour le scénario d'expiration de session
     2. Envisager de refactoriser vers événementiel comme conçu, ou mettre à jour design.md

Ce que vérifie verify :

Dimension	Ce qu'elle valide
Complétude	Toutes les tâches faites, toutes les exigences implémentées, scénarios couverts
Correctitude	L'implémentation correspond à l'intention de la spécification, cas limites gérés
Cohérence	Les décisions de conception reflétées dans le code, patterns cohérents

Verify ne bloquera pas l'archivage, mais il signalera les problèmes que vous souhaiterez peut-être adresser en premier.

Archiver : Finaliser le changement

/opsx:archive termine le changement et le déplace vers l'archive :

Vous : /opsx:archive

IA :   Archivage de add-auth...

     État des artefacts :
     ✓ proposal.md existe
     ✓ specs/ existe
     ✓ design.md existe
     ✓ tasks.md existe (12/12 tâches terminées)

     Spécifications delta : Pas encore synchronisées avec la version principale
     → Souhaitez-vous synchroniser maintenant ?

Vous : Oui

IA :   ✓ Spécifications synchronisées vers openspec/specs/auth/spec.md
       ✓ Déplacé vers openspec/changes/archive/2025-01-24-add-auth/

       Changement archivé avec succès.

Archive invitera à synchroniser si les spécifications ne le sont pas. Il ne bloquera pas sur des tâches incomplètes, mais il vous avertira.

Quand utiliser quoi

/opsx:ff vs /opsx:continue

Situation	Utiliser
Exigences claires, prêt à construire	/opsx:ff
Exploration, vouloir revoir chaque étape	/opsx:continue
Vouloir itérer sur la proposition avant les specs	/opsx:continue
Pression temporelle, besoin d'avancer vite	/opsx:ff
Changement complexe, vouloir contrôler	/opsx:continue

Règle générale : Si vous pouvez décrire la portée complète dès le départ, utilisez /opsx:ff. Si vous découvrez au fur et à mesure, utilisez /opsx:continue.

Quand mettre à jour vs recommencer à zéro

Une question fréquente : quand est-il acceptable de mettre à jour un changement existant, et quand faut-il en commencer un nouveau ?

Mettez à jour le changement existant lorsque :

• Même intention, exécution affinée
• La portée se réduit (MVP d'abord, reste plus tard)
• Corrections basées sur l'apprentissage (le codebase n'est pas ce à quoi vous vous attendiez)
• Ajustements de conception basés sur les découvertes lors de l'implémentation

Commencez un nouveau changement lorsque :

• L'intention a fondamentalement changé
• La portée a explosé vers un travail entièrement différent
• Le changement original peut être marqué comme "terminé" de manière autonome
• Les correctifs prêteraient plus à confusion qu'à clarification

                     ┌─────────────────────────────────────┐
                     │     Est-ce le même travail ?        │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          Même intention ?      >50% de chevauchement ?   L'original
          Même problème ?       Même portée ?             peut-il être "terminé" sans
                 │                  │          ces changements ?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      OUI               NON OUI           NON  NON              OUI
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    METTRE À JOUR     NOUVEAU METTRE À JOUR   NOUVEAU METTRE À JOUR    NOUVEAU

Exemple : "Ajouter le mode sombre"

• "Besoin de supporter également les thèmes personnalisés" → Nouveau changement (portée explosive)
• "La détection des préférences système est plus difficile que prévu" → Mettre à jour (même intention)
• "Livrons d'abord le bouton bascule, ajoutons les préférences plus tard" → Mettre à jour puis archiver, puis nouveau changement

Meilleures pratiques

Garder les modifications ciblées

Une unité logique de travail par modification. Si vous faites « ajouter la fonctionnalité X et refactoriser Y », envisagez deux modifications séparées.

Pourquoi c'est important :

• Plus facile à examiner et à comprendre
• Historique d'archivage plus propre
• Peut être déployé indépendamment
• Repli plus simple si nécessaire

Utiliser /opsx:explore pour les exigences peu claires

Avant de vous engager dans une modification, explorez l'espace du problème :

You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle rate limiting for our API?

AI:  Let me investigate your current setup and options...
     [Researches codebase, considers patterns]

     I see three approaches we could take:
     1. Middleware-based (simple, per-endpoint)
     2. Redis-backed (scalable, shared state)
     3. Token bucket per user (fair, complex)

     Your current stack suggests #1 or #2. What's your scale?

L'exploration clarifie la réflexion avant de créer des artefacts.

Vérifier avant d'archiver

Utilisez /opsx:verify pour vérifier que l'implémentation correspond aux artefacts :

You: /opsx:verify

AI:  Verifying add-dark-mode...

     ✓ All tasks in tasks.md are checked
     ✓ Requirements in specs have corresponding code
     ✓ Design decisions are reflected in implementation

     Ready to archive!

Détecte les incohérences avant de clôturer la modification.

Nommer les modifications clairement

De bons noms rendent openspec list utile :

Good:                          Avoid:
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

Référence rapide des commandes

Pour les détails complets et les options des commandes, consultez Commandes.

Commande	Objectif	Quand l'utiliser
/opsx:propose	Créer une modification + artefacts de planification	Chemin par défaut rapide (profil core)
/opsx:explore	Réfléchir aux idées avec l'IA	Commencez ici en cas de doute : exigences peu claires, investigation, comparaison d'options
/opsx:new	Démarrer un squelette de modification	Mode étendu, contrôle explicite des artefacts
/opsx:continue	Créer l'artefact suivant	Mode étendu, création d'artefacts étape par étape
/opsx:ff	Créer tous les artefacts de planification	Mode étendu, périmètre clair
/opsx:apply	Implémenter les tâches	Prêt à écrire du code
/opsx:verify	Valider l'implémentation	Mode étendu, avant archivage
/opsx:sync	Fusionner les spécifications delta	Mode étendu, facultatif
/opsx:archive	Terminer la modification	Tout le travail est terminé
/opsx:bulk-archive	Archiver plusieurs modifications	Mode étendu, travail parallèle

Étapes suivantes

• Rédiger de bonnes spécifications - À quoi ressemblent une exigence et un scénario solides, et comment dimensionner correctement une modification
• Examiner une modification - Le passage de deux minutes sur un plan rédigé avant tout code
• OpenSpec en équipe - Comment les modifications s'intègrent aux branches et aux demandes de fusion
• Commandes - Référence complète des commandes avec options
• Concepts - Approfondissement des spécifications, des artefacts et des schémas
• Personnalisation - Créer des flux de travail personnalisés