aitormf/agent-skills

Transforme une idée vague ou à moitié définie en un cahier des charges (problème, utilisateurs, récits utilisateur, exigences, cas limites et critères d'acceptation) grâce à un entretien par cycles. À utiliser lorsqu'on vous demande de rédiger un cahier des charges, de définir une fonctionnalité, de clarifier des exigences ou de passer d'une idée à quelque chose de réalisable.

Qu'est-ce que agent-skills ?

Cette compétence d'agent AI permet de passer d'une idée floue à un cahier des charges structuré, prêt pour la planification. L'agent mène une conversation par cycles de questions ciblées, en commençant par les questions bloquantes, couvrant le problème, les utilisateurs, les récits utilisateur, le périmètre, les cas limites, les contraintes non fonctionnelles, la sécurité et les critères d'acceptation. L'agent ne suppose jamais une réponse silencieusement : pour toute question non résolue, il présente plusieurs options (dont la sienne) et laisse la personne décider ou laisser la question ouverte. Le résultat est sauvegardé dans des fichiers `spec.md` et `plan.md` avec un statut `draft`, `approved` ou `obsolete`, en respectant une nomenclature de dossier basée sur la date et le type de Conventional Commits. Cette compétence est conçue pour des outils comme Claude Code, Cursor ou Codex, et s'arrête dès que les informations suffisent à décrire l'objectif, le problème, les utilisateurs, les récits, le périmètre, les exigences fonctionnelles et non fonctionnelles, les cas limites et les critères d'acceptation.

Compatible avec~Claude Code~Codex CLI~Cursor

npx skills add https://github.com/aitormf/agent-skills/tree/HEAD/skills/idea-to-spec

Documentation

De l'idée au cahier des charges

Aidez la personne à transformer une idée en un cahier des charges prêt pour la planification. Vous menez la conversation ; la personne donne les réponses.

Artefacts et statut

Chaque élément de travail se trouve dans docs/specs/<AAAAMMJJ>-<type>-<nom>/. Le type suit les Conventional Commits (feat, fix, refactor, docs…) et le nom est en kebab-case. Si ce répertoire existe déjà, ajoutez -2.
spec.md et plan.md portent status: draft | approved | obsolete dans leur en-tête. Seule une personne peut définir approved.
Si vous modifiez un artefact approuvé, repassez-le en draft et mentionnez-le.
La gestion du travail (priorité, responsable, terminé) n'est pas du ressort de cette compétence : elle relève du gestionnaire de tâches. Si une issue existe, son identifiant va dans issue:.

Comportement

Commencez par résumer l'idée en un court paragraphe.
Identifiez ce qui manque pour rédiger un bon cahier des charges et posez le nombre minimum de questions utiles, en commençant par les questions bloquantes.
Concentrez-vous sur le quoi et le pourquoi, pas le comment : pas de frameworks ni d'architecture, sauf si la personne le demande. Cela relève de spec-to-plan.
Si docs/ARCHITECTURE.md existe, lisez-le pour utiliser le vocabulaire du glossaire et repérer les conflits avec les principes.

Questions par cycle

Problème et résultat attendu.
Utilisateurs et acteurs.
Récits utilisateur (ce dont chacun a besoin et pourquoi).
Périmètre et hors périmètre.
Comportement et cas limites : données vides, invalides ou massives ; pannes des dépendances externes ; actions concurrentes.
Contraintes non fonctionnelles.
Sécurité, si cela touche aux données, à l'authentification ou aux entrées externes : sensibilité des données, qui peut faire quoi, quelles entrées ne sont pas fiables et quels tests négatifs sont nécessaires.
Critères d'acceptation (« Étant donné…, quand…, alors… »).

Si quelque chose reste ambigu après un cycle, demandez uniquement cette partie.

Questions ouvertes

Ne supposez jamais une réponse en silence. Pour chaque question non résolue :

[Question]

A) [Votre proposition par défaut, le cas échéant]

B) [Alternative évidente]

C) Laisser comme question ouverte dans le cahier des charges

D) Autre réponse

Elle n'est résolue que lorsque la personne répond ou choisit de la laisser ouverte.

Format de chaque réponse : Ce que je comprends · Questions ouvertes · Prochaine étape.

Taille

Adaptez la profondeur à la modification. Proposez le chemin et laissez la personne décider :

Modification	Artefacts
Bogue d'une ligne	Aucun, ou seulement `tasks.md`
Bogue complexe	`spec.md` + `tasks.md`
Petite fonctionnalité	`spec.md` + `plan.md` + `tasks.md`
Fonctionnalité de production ou refonte architecturale	Tout, avec révision du cahier des charges et du plan

Quand s'arrêter

Arrêtez-vous lorsqu'il y a suffisamment d'informations pour : objectif, problème, utilisateurs, récits utilisateur, périmètre et hors périmètre, exigences fonctionnelles et non fonctionnelles, cas limites et critères d'acceptation.

Ensuite :

Proposez le nom du répertoire et le brouillon de spec.md à partir de assets/spec-template.md, avec status: draft. Supprimez les sections optionnelles qui ne s'appliquent pas.
Affichez le brouillon et ne l'écrivez qu'une fois la personne approuvée.
Prochaine étape suggérée : le réviser avec review-spec. Si la modification est petite et que la personne est satisfaite, elle peut le marquer approved et passer à spec-to-plan.