Documentation

OpenSpec

OpenSpec dans Motoko Base — pourquoi il existe, structure des dossiers et comment proposer, appliquer et archiver des changements.

Ouvrir dansChatGPT Claude Cursor

OpenSpec est un flux piloté par les specs pour le développement assisté par IA. Motoko Base l’utilise pour que les agents planifient avant de coder — des changements ciblés plutôt que des diffs aléatoires dans le dépôt.

Docs officielles : openspec.dev

Pourquoi OpenSpec ?

Sans OpenSpec	Avec OpenSpec
L’agent modifie beaucoup de fichiers d’un coup	L’agent suit `tasks.md` étape par étape
Les exigences vivent dans l’historique du chat	Exigences dans des fichiers markdown revus
Difficile de savoir ce que « terminé » signifie	Les specs définissent un comportement observable
Les patterns dérivent des conventions du starter	`openspec/config.yaml` applique les règles Motoko

OpenSpec sépare la planification (proposal, design, specs, tasks) de l’implémentation (apply). Vous validez le plan avant tout changement de code produit.

Structure des dossiers

openspec/
├── config.yaml              # Project context + rules for AI artifacts
├── specs/                   # Durable requirements (main specs)
│   └── <capability>/
│       └── spec.md
└── changes/
    ├── <active-change>/     # Work in progress
    │   ├── .openspec.yaml
    │   ├── proposal.md
    │   ├── design.md
    │   ├── tasks.md
    │   └── specs/<capability>/spec.md   # delta spec
    └── archive/
        └── <date>-<change-name>/        # completed changes

Les main specs (openspec/specs/) sont la mémoire produit durable — ce que le starter doit faire par capacité (links, billing, storage, etc.).

Les changes (openspec/changes/) sont des plans de courte durée pour un résultat. Après archive, les exigences durables fusionnent dans les main specs.

Les règles IA spécifiques au projet vivent dans openspec/config.yaml (philosophie, stack, contraintes d’architecture, règles par artefact).

Créer une proposal

Utilisez la slash command Cursor ou demandez à l’agent d’exécuter le skill propose :

/opsx-propose Add a bookmarks demo with user ownership

Cela crée openspec/changes/<name>/ et génère :

Artefact	Objectif
`proposal.md`	Quoi & pourquoi, non-goals, capacités, impact
`specs/<capability>/spec.md`	Exigences delta (scénarios ADDED/MODIFIED)
`design.md`	Comment — fichiers, patterns, décisions (omis si trivial)
`tasks.md`	Étapes d’implémentation à cases à cocher

Planification uniquement — pas de code produit tant que vous n’exécutez pas apply.

Pour réfléchir sans planifier : /opsx-explore. Pour réviser après feedback : /opsx-update.

Design

design.md consigne les décisions d’architecture du change :

Quels patterns existants réutiliser (src/features/links/ comme modèle CRUD)
Schema, routes et points de contact fichiers
Trade-offs et non-goals au niveau design

Les agents lisent proposal.md + le codebase existant avant d’écrire le design. Gardez-le court — préférez réutiliser les patterns du starter plutôt qu’inventer de nouvelles couches.

Tasks

tasks.md est une liste à cases à cocher que l’agent suit pendant apply :

- [ ] 1.1 Add schema in src/lib/db/schema/...
- [ ] 2.1 Create queries.ts with ownership filters
- [ ] 3.1 Wire dashboard route and nav item

Les tâches doivent être petites, ordonnées (schema → server → UI → wiring) et nommer des chemins de fichiers concrets quand ils sont connus.

Apply

Quand le plan vous convient :

/opsx-apply

L’agent :

Lit proposal.md, les delta specs, design.md et tasks.md
Implémente chaque tâche non cochée
Marque les tâches - [x] une fois terminées
Se met en pause si le périmètre est flou ou si le spec doit être mis à jour

Vous pouvez lancer apply sur plusieurs sessions — la progression est suivie dans tasks.md.

Commandes CLI utiles

openspec list                      # active changes
openspec status --change <name>    # artifact progress
openspec validate <name>           # check a change
openspec view                      # browse specs and changes

Installation : OpenSpec installation

Commandes Cursor

Commande	Action
`/opsx-explore`	Réfléchir et investiguer — pas de code
`/opsx-propose`	Créer les artefacts de planification
`/opsx-update`	Réviser les artefacts après feedback
`/opsx-apply`	Implémenter les tâches
`/opsx-archive`	Terminer et synchroniser les specs
`/opsx-sync`	Synchroniser les delta specs vers les main specs

Les skills vivent dans .agents/skills/openspec-* et .cursor/skills/openspec-*.

Flux de développement IA — Flux de bout en bout de l’idée à la revue.

Cursor / agents IA — AGENTS.md et conseils de prompting.