Cahier des charges à partir des specs

Ce skill part d'un projet de specs (skill

specs-ui

, et le prototype du skill

prototype-ui

s'il existe) et produit le cahier des charges de l'équipe de développement. Les sources sont en Markdown, une par partie. Le build les assemble en deux formats :

un document Markdown, pour un dépôt de code ou un outil de documentation ;
une page HTML publiée comme artifact : sommaire qui suit la lecture, recherche par identifiant, pastilles RF / CA / NF / DT / RQ, diagrammes, thème clair et sombre, boutons « Copier le Markdown », pour le document entier ou une partie. La partie fonctionnelle et UI vient des specs par extraction (aucune réécriture), la partie technique (architecture, stack, infrastructure) est proposée puis validée avec la personne, et le découpage en lots porte des estimations en fourchettes avec leurs hypothèses.

Document et échanges en français. Code des scripts en anglais ; commentaires en français.

<skill>

désigne le dossier de ce skill ; les scripts se lancent depuis le dossier qui contient

specs/ui/

. Aucune dépendance : Node suffit.

Économiser les tokens (à lire en premier)

Les specs d'un produit pèsent souvent plus d'1 Mo de HTML ; le cahier des charges, 150 à 300 Ko de Markdown. Règles :

specs/requirements/REQUIREMENTS.md
est la mémoire : à lire en premier en reprise, et à s'en contenter tant que possible. Elle contient l'avancement par source, les contraintes, les décisions techniques DT, les hypothèses d'estimation et ce qui reste à valider. La tenir à jour à la fin de chaque étape, sous 150 lignes.
Ne jamais lire le HTML des specs :
```
extract.mjs
```
en tire la matière en Markdown dans
```
specs/requirements/sources/generated/
```
(environ 7 fois plus court). Le modèle principal lit
```
generated/inventaire.md
```
et
```
specs/ui/CONTEXTE.md
```
, puis seulement les extraits utiles des lots (par morceaux).

Ne jamais lire les documents assemblés (

specs/requirements/requirements.md

.html

, nommés par

requirements.json

→

output

), ni

specs/requirements/publish/

. On travaille dans

specs/requirements/sources/

(une source par partie), puis

build.mjs

check.mjs

Un fichier par partie : modifier une partie, c'est modifier sa source, pas relire le document.
Déléguer au bon modèle :

Rôle	Modèle	Tâches
Conception	modèle principal	Cadrage, questions, architecture, stack, infrastructure, lots et estimations, exigences non fonctionnelles, présentation, relecture, publication
Rédaction	`sonnet`	Critères d'acceptation d'un lot depuis `generated/lot-<lot>.md` (consigne : `references/redacteur.md` ) ; un rédacteur par lot, en parallèle
Exécution mécanique	`haiku`	Lancer `extract` , `build` , `check` , `trace` et rapporter

Tâche	À lire
Toute étape	`REQUIREMENTS.md`
Plan, identifiants, style	`references/plan.md`
Architecture, stack, infrastructure	`references/architecture.md`
Lots et estimations	`references/estimations.md`

Étape 0 · Prérequis et préparation

Les livrables de la chaîne vivent dans

specs/

à la racine du projet :

specs/ui

(specs),

specs/prototype

(prototype),

specs/requirements

(ce cahier des charges). Un projet à l'ancienne disposition (

specs-ui/

cdc/

à la racine,

cdc.json

CDC.md

) se range avec

migrate-layout.mjs

du skill

specs-ui

; d'ici là, les scripts lisent encore

cdc.json

Il faut un projet

specs-ui

(avec

sources/site.json

). Sinon, proposer d'abord les specs (skill

specs-ui

). D'autres documents fonctionnels donnés par la personne (brief, notes) se lisent au cadrage et se citent en documents de référence.

node <skill>/scripts/init.mjs --specs specs/ui --out specs/requirements [--prototype specs/prototype]

Le script crée

specs/requirements/

(

requirements.json

REQUIREMENTS.md

, une source par partie avec les valeurs connues déjà remplies), un chapitre par lot dans

30-specs.md

, et lance l'extraction. Un dossier existant n'est pas écrasé : c'est une reprise.

Étape 1 · Cadrage

Lire

specs/ui/CONTEXTE.md

specs/requirements/sources/generated/inventaire.md

. Puis demander avec AskUserQuestion les contraintes qui pèsent sur la technique : hébergement imposé ou souhaité, compétences de l'équipe (langages, frameworks), sécurité et conformité (SSO, données en UE, audit), volumes attendus, budget d'infrastructure, échéance. Toujours une option « pas de contrainte ». Noter les réponses dans

REQUIREMENTS.md

Étape 2 · Architecture, stack et infrastructure

Suivre

references/architecture.md

lire les besoins techniques dans les règles RF et les écrans (temps réel, événements externes, traitements longs, exécution isolée, secrets, multi-tenant…), chacun rattaché à sa règle ;
proposer 2 ou 3 options par décision structurante, avec une recommandation, par AskUserQuestion (4 questions par série, 2 séries au plus) ;
noter chaque décision DT-xx dans
```
REQUIREMENTS.md
```
, puis rédiger
```
60-architecture.md
```
,
```
70-stack.md
```
et
```
80-infrastructure.md
```
(hébergement, environnements, réseau, conteneurs, CI/CD, IaC et secrets, observabilité, sauvegardes, sécurité, coûts).

Rien de technique ne s'écrit comme décidé sans validation : une recommandation non tranchée est notée « à valider ».

Étape 3 · Partie fonctionnelle

Critères d'acceptation : un rédacteur
```
sonnet
```
par lot, en parallèle, avec
```
references/redacteur.md
```
, son fichier
```
generated/lot-<lot>.md
```
et la source
```
lots/<lot>-criteres.md
```
à remplir. Lire leurs comptes rendus : une règle floue devient un point « À valider » ou une question à la personne.
Le modèle principal rédige :
- ```
10-presentation.md
```
  ;
- ```
20-utilisateurs.md
```
  (matrice des rôles depuis les RF) ;
- ```
40-interface.md
```
  (principes, composants, mobile, accessibilité ; les tokens sont générés) ;
- ```
50-exigences-non-fonctionnelles.md
```
  (chiffrées, en reprenant d'abord les valeurs des specs).

Étape 4 · Lots, estimations, risques

Suivre

references/estimations.md

lots : lot 0 « Socle », puis les lots des specs ;
estimations : par lot, objectif, périmètre, dépendances, livrables, critères de fin et fourchette en jours ; puis synthèse, hypothèses et planning (
```
gantt
```
) ;
risques et décisions : les risques RQ-xx vont dans
```
95-risques.md
```
(les points ouverts des specs y sont inclus automatiquement), les décisions produit datées dans
```
99-annexes.md
```
.

Étape 5 · Construire, contrôler, publier

node <skill>/scripts/build.mjs specs/requirements
node <skill>/scripts/check.mjs specs/requirements

check.mjs

signale :

les parties manquantes ;
les gabarits
```
{{…}}
```
non remplis ;
les liens internes cassés (ancres en ASCII) ;
les identifiants cités sans définition ;
les lots des specs absents du découpage ou sans fourchette ;
les écrans de l'inventaire absents ;
les diagrammes non refermés ;
les identifiants en double.

Corriger jusqu'à zéro problème.

Le build écrit trois fichiers :

```
specs/requirements/requirements.md
```
: le document Markdown ;
```
specs/requirements/requirements.html
```
: la page complète, ouvrable en local, avec les diagrammes rendus ;
```
specs/requirements/publish/requirements.html
```
: la même page sans enveloppe, pour l'outil Artifact (hors du dépôt git : elle se régénère).

Publier
specs/requirements/publish/requirements.html
avec l'outil Artifact (

prepare-publish.mjs specs/requirements

dit s'il y a quelque chose à publier et vers quelle URL). Le titre vient de la balise

<title>

, et l'outil rend les diagrammes

mermaid

lui-même. Republier ce même fichier garde l'URL ; la noter dans

requirements.json

→

artifacts.requirements

et dans

REQUIREMENTS.md

, puis lancer

prepare-publish.mjs specs/requirements --confirm

(empreinte dans

.published.json

, à commiter).

--check

dit si l'artifact est en retard sur la page locale. La page ne peut pas faire télécharger de fichier (le lecteur l'interdit) : le Markdown se récupère par les boutons « Copier », ou dans le fichier

.md

local. Passer la version et le statut dans

00-titre.md

à chaque publication notable.

Specs modifiées

Relancer

extract.mjs specs/requirements

(la partie fonctionnelle suit seule), puis

check.mjs

: il signale les nouveaux écrans absents et les liens cassés. Mettre à jour les critères des lots touchés (rédacteur), les lots et estimations, les risques ; noter la nouvelle version.

Maintenir pendant les développements

Le cahier des charges vit dans le dépôt de l'application (

specs/requirements/

), avec ses sources, le Markdown construit (

requirements.md

sources/generated/

, que l'équipe et les agents lisent sans rien construire) et

.published.json

. La page HTML (

requirements.html

) se reconstruit et reste hors du dépôt, comme

publish/

: l'ajouter au

.gitignore

du projet. Il suit les specs, qui suivent l'implémentation (skill

specs-ui

, étape 7).

Identifiants stables. Le code et les tests citent les identifiants CA-…, RF-… et NF-… : un identifiant ne change jamais de sens et n'est jamais réutilisé.

Un nouveau critère prend le numéro suivant du lot, même s'il s'insère au milieu de la liste.
Un critère abandonné reste, barré et marqué « Retiré (date, raison) ».
Un critère modifié garde son numéro si la vérification reste la même ; sinon il est retiré et remplacé.

Traçabilité avec le code. Un test cite le critère qu'il vérifie dans son nom (« CA-CONN-27 · refuse une clé d'API »).

node <skill>/scripts/trace.mjs specs/requirements [--code apps,packages] [--write] [--strict]

trace.mjs

donne, par lot, les critères testés, seulement référencés dans le code, ou non couverts. Il signale les identifiants cités dans le code mais définis nulle part (critère retiré, faute de frappe) et les écrans « Livré » dans les specs dont des critères ne sont pas testés. Les dossiers à analyser se règlent dans

requirements.json

→

code

(par défaut, tout le dépôt sauf

specs/

--write

produit

sources/generated/couverture.md

, à inclure dans une annexe (

<!-- include: generated/couverture.md -->

) quand on veut publier l'avancement ;

--strict

sert à la CI.

À chaque évolution : réextraire, mettre à jour les critères touchés,

build

check

trace

, monter la version dans

00-titre.md

, publier, et commiter les sources, le Markdown construit et

.published.json

avec les specs, dans le même changement.

requirements-doc

NPX Install

Tags

SKILL.md Content