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), par opposition à la spec courante complète.
• 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.

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

• 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.
• Apply — l'IA implémente tâche par tâche en suivant tasks.md ; tu supervises.
• 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.)

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 trois 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.

À l'archive : ADDED s'ajoute, MODIFIED remplace, REMOVED supprime.

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.

tasks.md — la checklist exécutable. Découpée en phases, cochée au fil de l'eau par l'IA pendant apply.

# Tasks: Add Two-Factor Authentication

## Phase 1 — MVP
- [ ] 1.1 Migration : table `user_2fa_secrets`
- [ ] 1.2 Service `TotpService` (RFC 6238)
- [ ] 1.3 `POST /login` → `202 otp_required` si 2FA active

## Phase 2 — Durcissement
- [ ] 2.1 Rate-limit après 5 échecs OTP
- [ ] 2.2 Lint + build + tests 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.

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.

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 update                               # régénère instructions agent + slash commands

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 25 outils supportés.

9OpenSpec vs Spec Kit vs Kiro

Sources

• Fission-AI/OpenSpec (GitHub) — repo officiel : README, quick start, comparaisons.
• 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.