OpenSpec — le spec-driven development pour les agents de code

1📖 Glossaire

• SDD (Spec-Driven Development) — méthodologie où la spec écrite, et non le prompt, est la source de vérité de ce qui sera construit.
• OPSX — le workflow standard d'OpenSpec : des actions, pas des phases. On crée, implémente, met à jour, archive — dans l'ordre qu'on veut.
• Change — une modification en cours, isolée dans son dossier openspec/changes/<change-id>/.
• Artefact — un fichier généré par l'IA dans un change : proposal.md, le delta de specs/, design.md, tasks.md.
• Delta spec — la partie modifiée d'une spec (ADDED / MODIFIED / REMOVED / RENAMED), par opposition à la spec courante complète.
• skip_specs — drapeau d'un change qui déclare ne modifier aucune spec (refactor pur, doc). Le change passe validate et archive sans delta (1.7).
• Capability / domaine — une unité de comportement (ex. auth), à laquelle est rattachée une spec.
• Schema — la recette d'un change : quels artefacts il contient, dans quel ordre, et les instructions que l'IA suit pour les générer. spec-driven est le schéma intégré par défaut.
• RFC 2119 — mots-clés (MUST / SHALL / SHOULD / MAY) exprimant la force d'une exigence.

2Le problème : le contexte qui vit dans le chat

Sans spec, l'agent génère du code à partir d'un prompt vague : exigences manquantes, fonctionnalités non demandées, résultat incohérent. Pire pour la review : le relecteur n'a aucun référentiel écrit auquel comparer le code produit. Et au-delà d'un certain remplissage du contexte, l'agent oublie ou altère les détails d'exigence vus plus tôt dans la conversation.

OpenSpec répond par un principe simple : structure avant code. On décrit le changement, on raffine le comportement attendu, on planifie les tâches, puis on implémente contre une spec validée.

3Le fil rouge : un change de bout en bout

Cas concret : on veut ajouter une 2FA sur les comptes admin. Voilà le déroulé. On lance d'abord la proposition — l'IA scaffolde le change et génère les artefacts :

You: /opsx:propose add-two-factor-auth

AI:  Created openspec/changes/add-two-factor-auth/
     ✓ proposal.md — pourquoi & quoi
     ✓ specs/       — requirements & scenarios (le delta)
     ✓ design.md    — approche technique
     ✓ tasks.md     — checklist d'implémentation
     Prêt pour la review.

Depuis la 1.12, propose et ff inspectent le code, les tests et la doc concernés avant de drafter les artefacts. explore fait de même : il vérifie le dépôt avant de te poser une question dont la réponse est déjà dans le code. Ce n'est pas du reverse-engineering de la legacy, mais l'agent ne propose plus à l'aveugle.

Le workflow global tient en quatre temps, et le point qui bloque souvent c'est qui agit à chaque étape :

flowchart LR
    P["1 · PROPOSE<br/>TOI : l'intention<br/>IA : drafte les 4 artefacts"]
    REV{"2 · REVIEW<br/>TOI : valides & corriges"}
    AP["3 · APPLY<br/>IA : implémente tasks.md"]
    AR["4 · ARCHIVE<br/>merge delta → specs/<br/>+ historise"]
    P --> REV --> AP --> AR
    REV -.->|"/opsx:update : révise le plan"| P

• Propose — tu donnes l'intention (add-two-factor-auth + 1-2 phrases) ; l'IA génère les 4 artefacts.
• Review (gate) — tu relis et corriges. Rien ne part en implémentation tant que tu n'as pas validé. C'est l'étape où tu travailles vraiment.
• Update (boucle, depuis la 1.6.0) — quand la review invalide une hypothèse, /opsx:update révise le plan en place et réconcilie les artefacts liés, sans déborder sur l'implémentation.
• Apply — l'IA implémente tâche par tâche en suivant tasks.md ; tu supervises. Depuis la 1.9, la consigne d'apply demande à l'agent de signaler le travail hors périmètre plutôt que de le reporter en silence.
• Archive — le delta est fusionné dans openspec/specs/ (la vérité courante) et le change part, daté, dans archive/. (Entre apply et archive, /opsx:sync peut propager le delta dans specs/ sans archiver — optionnel, utile pour un change long ou des changes en parallèle.)

You: /opsx:update add-two-factor-auth

     Le TOTP seul ne passe pas : les admins terrain n'ont pas de
     smartphone pro. Ajouter des codes de secours à usage unique,
     et répercuter sur la spec, le design et les tâches.

AI:  Updated openspec/changes/add-two-factor-auth/
     ✓ proposal.md, specs/, design.md, tasks.md réconciliés
     Aucune implémentation lancée.

4Les commandes opsx — cœur vs étendu

Par défaut, OpenSpec active le profil core. /opsx:propose y fait tout d'un coup (scaffold + tous les artefacts). Le profil étendu (à activer via openspec config profile puis openspec update) découpe cette étape pour itérer plus finement — créer un artefact à la fois, tester chaque template indépendamment.

5Les deux dossiers : specs/ vs changes/

Toute la mécanique tient dans une séparation état courant / diff en cours :

• openspec/specs/ — la spec vivante, source de vérité de ce que le système fait aujourd'hui. Organisée par domaine (auth/, payments/…).
• openspec/changes/<change-id>/ — un dossier par changement, qui regroupe proposal, delta de specs, design et tasks. Ce regroupement par feature rend le suivi lisible.
• openspec/changes/archive/ — l'historique daté des changements appliqués.

flowchart LR
    subgraph C["openspec/changes/add-two-factor-auth/"]
        P["proposal.md"]
        S["specs/ — delta"]
        D["design.md"]
        T["tasks.md"]
    end
    SP["openspec/specs/auth/ — verite courante"]
    AR["openspec/changes/archive/ — historique date"]
    C -->|"apply : implémente le delta"| SP
    C -->|"sync / archive : fusionne le delta"| SP
    C -->|"archive : déplacement daté"| AR

6Les artefacts générés — et ce que tu vérifies en review

Ces quatre fichiers sont produits par l'IA sur /opsx:propose. Ton rôle n'est pas de les écrire mais de les relire. Voici à quoi chacun ressemble pour notre change add-two-factor-auth, et le point d'attention en review (annotations ←).

proposal.md — le pourquoi / quoi / impact.

# Proposal: Add Two-Factor Authentication

## Why
Les comptes admin sont la cible n°1 de credential stuffing.

## What Changes
- Challenge OTP (TOTP) après validation du mot de passe.

## Out of Scope            ← EN REVIEW : vérifie que l'IA n'élargit pas le périmètre
- SMS comme second facteur (TOTP uniquement).

## Impact
- Specs : `auth`. Breaking : `POST /login` → `202 otp_required`.

En review : le Out of Scope et l'Impact (breaking changes) sont les deux blocs où l'IA dérape le plus. C'est là que tu cadres.

specs/auth/spec.md — le delta (le cœur). Une spec est un contrat de comportement : requirements + scenarios en Given/When/Then, mots-clés RFC 2119. Pas de noms de classes ni de librairie (ça, c'est design.md). On décrit le diff via quatre opérations :

# Delta for Auth

## ADDED Requirements                  ← nouvelle exigence
### Requirement: Two-Factor Authentication
The system SHALL require a second factor (TOTP) for admin login.

#### Scenario: OTP required             ← ≥1 scénario, sinon validation KO
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements               ← requirement RÉÉCRIT en entier
### Requirement: Session Timeout
The system SHALL expire sessions after 15 minutes of inactivity.

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements                ← + Reason / Migration
### Requirement: Remember Me
**Reason**: Deprecated in favor of 2FA.
**Migration**: Tokens révoqués ; ré-auth à chaque session.

## RENAMED Requirements                ← FROM / TO, le contenu ne bouge pas
- FROM: `### Requirement: Password Login`
- TO: `### Requirement: Primary Factor Login`

À l'archive : ADDED s'ajoute, MODIFIED remplace, REMOVED supprime, RENAMED renomme sur place. Depuis la 1.11, un requirement renommé garde sa position dans la spec au lieu d'être déplacé à la fin, ce qui garde le diff d'archive petit.

Pour relire le delta sans te noyer dans le texte répété des MODIFIED, openspec show <change> --diff (1.11) n'affiche que les lignes qui changent.

design.md — l'approche technique (optionnel, changements non triviaux). C'est ici que vivent les décisions d'archi et les alternatives écartées — pas dans la spec.

# Design: Two-Factor Authentication

## Décision : TOTP vs SMS
TOTP (RFC 6238). SMS écarté : coût, SIM-swap, dépendance opérateur.

## Alternatives écartées
WebAuthn/passkeys : meilleure sécu, mais hors scope de cette itération.

En review : les décisions tiennent-elles ? Les alternatives sont-elles justifiées ? C'est souvent ici qu'on découvre « cette approche ne marchera pas » — avant de coder. Quand le verdict tombe ici, c'est le cas d'usage type de /opsx:update : on corrige le plan, on ne repart pas de zéro.

tasks.md — la checklist exécutable. Découpée en phases, cochée au fil de l'eau par l'IA pendant apply. Depuis la 1.10, chaque tâche générée doit dire comment on saura qu'elle est finie : un test, une commande, un résultat observable ou un artefact livré. Et depuis la 1.13.2, chaque groupe de tâches embarque ses propres tests et mises à jour de doc, au lieu de tout reporter dans un groupe final.

# Tasks: Add Two-Factor Authentication

## Phase 1 — MVP
- [ ] 1.1 Migration : table `user_2fa_secrets`
      Done : migration appliquée, `\d user_2fa_secrets` montre les colonnes
- [ ] 1.2 Service `TotpService` (RFC 6238)
      Done : `TotpServiceTest` vert (génération + vérification + fenêtre de dérive)
- [ ] 1.3 `POST /login` → `202 otp_required` si 2FA active
      Done : test d'intégration du endpoint vert, doc OpenAPI mise à jour

## Phase 2 — Durcissement
- [ ] 2.1 Rate-limit après 5 échecs OTP
      Done : test vert sur le 6e échec → 429
- [ ] 2.2 Lint + build + suite complète au vert      ← vérif = une tâche à part entière

7Customisation : du défaut intégré au schéma maison

Point clé : le schéma spec-driven est intégré à OpenSpec. Tu ne l'écris jamais. La config ne sert qu'à le customiser, et elle est facultative. Trois niveaux.

Mode 1 — défaut intégré (recommandé pour démarrer)

openspec init        # et c'est tout

Tu es sur le schéma spec-driven, qui génère proposal → specs → design → tasks avec les conventions vues plus haut. Aucune config nécessaire. Pour le contexte projet (stack, archi), tu remplis simplement project.md.

Mode 2 — config.yaml (optionnel) : contexte + règles

Pour imposer du contexte ou des règles maison à chaque change :

# openspec/config.yaml — UNIQUEMENT si tu veux customiser
schema: spec-driven        # schéma par défaut → évite de passer --schema

context: |                 # injecté dans TOUS les artefacts (limite 50 KB)
  Stack : TypeScript, React, Node, Postgres.
  Rétro-compat obligatoire sur les API publiques.

rules:                     # règles PAR artefact (clé = id d'artefact)
  proposal:                #   → injectées en générant le proposal seulement
    - Inclure un plan de rollback
  specs:                   #   → injectées en générant les specs seulement
    - Au moins un scénario d'erreur en plus du happy-path

Injection : context et rules sont insérés dans le prompt sous forme de blocs <context> / <rules> (puis le <template> du schéma). Le contexte va partout ; une règle seulement sur l'artefact qu'elle cible. Ordre de résolution du schéma : --schema CLI → .openspec.yaml du change → config.yaml → défaut spec-driven.

Depuis la 1.13.1, une valeur de config.yaml ne peut plus injecter de directives dans les instructions agent. Le contexte est traité comme de la donnée, pas comme une consigne. Utile quand on clone un dépôt qu'on n'a pas encore relu.

Mode 3 — schéma custom (cas avancé)

Un schéma, c'est la recette d'un change : la liste des artefacts qu'il doit contenir, leur ordre de dépendance, et les instructions que l'IA suit pour générer chacun. Le défaut spec-driven impose toujours proposal → specs → design → tasks.

La différence avec le Mode 2 est là :

• Mode 2 (config.yaml) — tu gardes la recette par défaut et tu la décores (contexte + règles). La liste des fichiers ne change pas.
• Mode 3 (schéma custom) — tu changes la recette elle-même : tu ajoutes/retires des artefacts, tu changes l'ordre, ou tu réécris leurs instructions/templates.

Trois cas typiques : workflow plus léger (sauter specs/design), plus lourd (ajouter un research avant le proposal), ou changer les prompts (ex. imposer un diagramme de séquence dans chaque design.md — effet immédiat, plus besoin d'attendre une release).

On ne part jamais de zéro : on forke le défaut, puis on édite. Exemple — un workflow rapid réduit à proposal + tasks :

openspec schema fork spec-driven rapid     # copie spec-driven dans openspec/schemas/rapid/

# openspec/schemas/rapid/schema.yaml — édité : on a retiré specs et design
name: rapid
version: 1
description: Workflow léger — pas de specs ni de design

artifacts:
  - id: proposal
    generates: proposal.md
    template: proposal.md
    requires: []                 # rien requis → créable en premier
  - id: tasks
    generates: tasks.md
    template: tasks.md
    requires: [proposal]         # tasks juste après proposal (plus de specs/design entre)

apply:
  requires: [tasks]              # on n'implémente qu'une fois tasks créé
  tracks: tasks.md               # apply coche cette checklist

openspec schema validate rapid                  # vérifie syntaxe, templates, pas de cycle
openspec new change quick-fix --schema rapid    # ou `schema: rapid` dans config.yaml pour en faire le défaut

Champs du schema.yaml, relus sur cet exemple : id (nom de l'artefact, = clé des rules), generates (fichier produit, globs OK), template (squelette dans templates/ que l'IA remplit), instruction (consigne IA), requires (artefacts prérequis), apply.requires / apply.tracks (ce qui doit exister avant d'implémenter + la checklist suivie). Les templates/*.md sont des squelettes avec des commentaires HTML qui guident l'IA.

Deux ajouts depuis : openspec schema fork conserve les commentaires, le style des blocs et l'ordre des clés du YAML (1.9). Et openspec schema init --default écrit bien la clé schema que le loader lit, donc un nouveau schéma prend effet tout de suite (1.11).

8Installation et intégration outils

Prérequis : Node.js ≥ 20.19.0. Package npm @fission-ai/openspec (MIT, open-source).

npm install -g @fission-ai/openspec@latest   # aussi : pnpm, yarn, bun, nix
cd your-project
openspec init                                 # openspec/ + config interactive + skills
openspec init --language fr                   # (1.10) artefacts générés en français, en-têtes et SHALL/MUST restent en anglais
openspec update                               # régénère instructions agent + slash commands, vérifie npm (1.7)

openspec init génère aussi des skills dans .claude/skills/ (ou équivalent) que les agents auto-détectent. Selon l'outil : Claude Code / Cursor → slash commands /opsx:* ; GitHub Copilot CLI → prompts sous .github/prompts/ ; Windsurf → workflows sous .windsurf/ ; le reste → AGENTS.md générique. Plus de 30 outils supportés (compte 1.7+). Depuis la 1.6.0, les skills et commandes générés peuvent pré-approuver la CLI OpenSpec : plus de confirmation à chaque appel, les autres outils restant sous contrôle normal.

Sur --language (1.10) : la langue ne s'applique qu'au contenu généré. Les en-têtes ### Requirement: / #### Scenario: et les mots-clés RFC 2119 restent en anglais, sinon la validation casse.

9OpenSpec vs Spec Kit vs Kiro

Sources

• Fission-AI/OpenSpec (GitHub) — repo officiel : README, quick start, comparaisons.
• Release v1.6.0 — OPSX Update, Tool Support — arrivée de /opsx:update, support Oh My Pi et TRAE, pré-approbation CLI, exit code de l'archive bloquée.
• Release v1.7.0 — New tools, smarter updates — skip_specs: true, openspec update qui vérifie npm, 30+ outils, change-id à préfixe numérique.
• Release v1.8.0 — More agents, sturdier archives — validate détecte la perte de scénario dans un MODIFIED, archive plus parlante sans terminal.
• Release v1.9.0 — validate --archived, résolution de racine stricte, schema fork qui conserve le YAML, consigne d'apply sur le hors-périmètre.
• Release v1.10.0 — Zed support, quieter installs — init --language, critère de done obligatoire dans les tâches.
• Release v1.11.0 — Spec Diffs & Batch Status — show --diff, status --all, Purpose placeholder, ordre conservé sur RENAMED, schema init --default.
• Release v1.12.0 — Findings Reports, SourceCraft — propose / ff / explore ancrés dans le code, validate --report findings.
• Release v1.13.0 — Apply warnings, safer archives — warning d'apply sur un change sans delta, explore qui liste les specs existantes.
• Release v1.13.1 — Hardened CLI, safer archives — durcissement sécurité (config.yaml, fichiers forgés, .npmrc), ligne Next: dans status.
• Release v1.13.2 — Verify and Windows archive fixes — /opsx:verify fiabilisé, tests et doc par groupe de tâches, messages de perte de scénario.
• OpenSpec — docs opsx — workflow OPSX, table des commandes (cœur/étendu), config, dépendances-enablers.
• OpenSpec — docs getting-started — déroulé d'un change, qui fait quoi, deltas, archive.
• OpenSpec — docs concepts — specs, deltas, artefacts, schémas.
• OpenSpec — docs customization — config.yaml, injection, schema.yaml + templates, schema fork/init/validate.