add-convention

Ajoute une convention — mais seulement après avoir évalué si elle doit exister et où elle doit aller. Cette compétence est un gardien et un aiguilleur, pas un sténographe.

Étape 0 — Préconditions et contexte

Confirmer que le dépôt est initialisé.
Lire CONVENTIONS.md et AGENTS.md en entier pour détecter les recoupements avec les règles existantes et juger de l'adéquation.

Étape 0.5 — Évaluation (à exécuter en premier)

Exécuter le protocole d'évaluation partagé ; les questions de tri (Étape 1) et d'acheminement (Étape 2) sont posées sous celui-ci :

Réutiliser d'abord les réponses fournies. Considérer les choix applicables déjà fournis dans la demande ou cette session, y compris la profondeur, comme répondus. Les résumer sans les redemander ; les valeurs par défaut ne remplacent jamais les choix explicites. Si tous les choix importants sont fournis, passer à la suite. Ne demander que les choix importants manquants ou contradictoires. Une préférence de dépôt seule n'est pas une réponse actuelle ou une autorisation d'exécution.
Sélecteur de profondeur pour les choix non résolus. Si la profondeur n'est pas fournie et qu'il reste des choix, demander jusqu'à quel niveau d'approfondissement cette évaluation doit aller : express — chaque choix prend sa valeur par défaut recommandée ; seules les questions sans valeur par défaut dérivable (les éléments essentiels en texte libre) sont encore posées ; guidé — seules les questions marquées à fort impact ci-dessous, plus les éléments essentiels en texte libre ; complet — toutes les questions ci-dessous. Si le CONVENTIONS.md du dépôt enregistre une Profondeur d'évaluation :, la présélectionner comme option recommandée lors de la demande ; une profondeur enregistrée n'est jamais appliquée silencieusement. Sinon, recommander complet lorsque la demande est arrivée avec peu ou pas de contexte et express lorsqu'elle est déjà entièrement spécifiée. À n'importe quelle question, l'opérateur peut répondre « valeurs par défaut à partir d'ici » ou « aller plus loin » ; honorer le changement immédiatement.
Poser les questions une par une, chacune avec une option recommandée et une raison d'une ligne ; attendre chaque réponse.
Utiliser une sélection structurée (choix unique ou multiples). Si l'hôte expose un outil de question à choix unique/multiples structuré, l'utiliser et marquer l'option recommandée ; sinon, lister les options A/B/C en texte brut et nommer la recommandée. Utiliser le texte libre uniquement lorsqu'un ensemble énumérable est impossible (par exemple, le libellé exact).
L'opérateur décide. Ne jamais passer à une question sans réponse, et ne jamais deviner la portée lors d'une invocation sans contexte.

Questions (ignorer celles auxquelles la demande répond déjà) :

À codifier ? — oui (récurrente, stable, vérifiable) ou non (unique, en double, sujette à changement, vague). Recommandé : selon le tri de l'Étape 1 ; cette question conditionne le reste. (Fort impact — posée en guidé.)
Emplacement — règle stricte AGENTS.md / directive CONVENTIONS.md / terme GLOSSARY.md / en fait une décision (transmettre à la compétence new-adr). Recommandé : selon la nature de la règle (voir Étape 2). (Fort impact — posée en guidé : un mauvais emplacement entraîne de la maintenance pour le déplacer.)
Appliquer dans la porte de vérification ? — oui / non. Recommandé : non, sauf si la règle est mécaniquement vérifiable.
Libellé — texte libre (l'énoncé de la règle lui-même ; demandé à chaque profondeur).

Étape 1 — Évaluer : cela vaut-il la peine d'être codifié ?

Appliquer le tri. Recommander contre l'ajout lorsque :

Cela est déjà couvert (explicitement ou implicitement) par une convention existante — pointer vers celle-ci au lieu de dupliquer.
C'est une décision unique, pas récurrente — la codifier ajoute du bruit.
Cela risque de changer fréquemment — les règles prématurées deviennent des vestiges obsolètes.
C'est trop vague pour être vérifiable ou applicable tel que rédigé.

Recommander pour l'ajout lorsqu'il s'agit d'une décision récurrente dont l'ambiguïté cause des retouches, qu'elle est stable, et qu'elle peut être formulée de manière à ce qu'un agent puisse la suivre sans interprétation supplémentaire. Énoncer votre recommandation et la raison avant de faire quoi que ce soit.

Étape 2 — Acheminer : où doit-elle aller ?

Décider de l'emplacement et expliquer le choix :

Règle stricte que les agents doivent respecter → une puce dans AGENTS.md §Règles strictes, avec le contenu dans CONVENTIONS.md. À utiliser pour des contraintes non négociables.
Directive de rédaction / processus → une section dans CONVENTIONS.md. À utiliser pour « comment nous faisons les choses » qui informe sans bloquer.
Terme / définition partagé → GLOSSARY.md (le créer s'il est absent — l'ajout du premier terme active la couche glossaire ; le placer à la racine des artefacts enregistrés). Lire la section §Glossaire du CONVENTIONS.md du dépôt et inspecter la règle qu'il déclare réellement ; la structure canonique est un en-tête H1 optionnel et un texte d'introduction optionnel, puis exactement un tableau Markdown à deux colonnes dont l'en-tête est Terme | Définition. Chaque terme est sa propre ligne. Ne jamais enregistrer un terme comme un titre, une puce ou un paragraphe, et ne jamais ajouter un deuxième tableau ou une forme de colonne différente. Une section §Glossaire qui énonce une convention de glossaire plus ancienne ou non liée ne constitue pas une adoption de ce tableau : utiliser la forme canonique et proposer la migration séparément consentie de la règle et du fichier de la compétence d'audit plutôt que de copier l'ancienne forme. Un GLOSSARY.md absent reste un état valide ; cette compétence en crée un uniquement parce qu'un terme est effectivement ajouté.
Il s'agit en fait d'une décision, pas d'une convention (un choix architectural, produit ou technologique avec des alternatives et des conséquences) → c'est une ADR. S'arrêter et proposer la compétence new-adr ; ne pas enterrer une décision dans CONVENTIONS.

Si une convention est une règle de tri/processus (par exemple, comment le travail entrant est trié), préférer CONVENTIONS.md avec une puce de règle stricte dans AGENTS.md uniquement pour les parties non négociables.

Étape 3 — Rédiger et confirmer

Rédiger le libellé exact pour son fichier de destination. Le garder concis, vérifiable et dans la langue du dépôt. Montrer la différence. Confirmer avant d'écrire.

Étape 4 — Écrire et valider

Appliquer la ou les modifications. Si une convention devient une règle stricte, s'assurer que AGENTS.md et CONVENTIONS.md restent cohérents. Validation conventionnelle (docs: ...) ; aucune ADR touchée signifie qu'aucun pied Rationale: n'est requis, mais en ajouter un si le contrat du dépôt le demande pour les changements de conventions.

Ajout ou extension d'un glossaire. Utiliser la structure canonique définie ci-dessous et les vérifications de règle déclarée ; la forme ne doit pas dériver entre les exécutions.

D'où vient la règle. Si CONVENTIONS.md n'a pas de section §Glossaire (un dépôt hérité qui la précède, ou une couche activée avant l'enregistrement de la règle), revenir à la forme canonique par défaut du produit ci-dessus : en-tête optionnel # Glossaire et texte d'introduction, puis un tableau Terme | Définition. Ne pas inventer une forme différente pour ce dépôt, et ne pas modifier silencieusement des conventions non liées.
Lecture de la règle déclarée. Lorsqu'une section §Glossaire existe, lire ce qu'elle déclare réellement. Si elle décrit le tableau canonique à deux colonnes Terme | Définition, la suivre et ne la modifier que sur demande explicite. Si elle énonce une convention de glossaire différente ou plus ancienne (puce, texte, autre forme de colonne), le dépôt n'a pas adopté ce tableau : ne pas copier l'ancienne forme, et ne pas réécrire silencieusement la règle. Utiliser la forme canonique pour le terme et proposer la migration de la compétence d'audit, qui couvre la règle et le fichier ensemble comme une seule différence consentie séparément.
Enregistrement de la convention. Lorsqu'une section §Glossaire est absente, proposer — comme sa propre modification confirmée, distincte du terme ajouté — d'enregistrer une section ## Glossaire dans CONVENTIONS.md énonçant la forme réellement utilisée. Montrer cette différence et ne l'écrire que si l'utilisateur l'accepte ; ne jamais réécrire ou réorganiser d'autres sections de CONVENTIONS.md pour faire de la place, et si l'utilisateur refuse, garder le glossaire canonique mais laisser CONVENTIONS.md inchangé.
Création du fichier. Écrire l'en-tête optionnel # Glossaire et tout court texte d'introduction dont le dépôt a besoin, puis le tableau unique à deux colonnes avec l'en-tête Terme | Définition et le nouveau terme comme première ligne. Ne pas inventer de termes fictifs.
Extension d'un fichier existant. Préserver l'en-tête, le texte d'introduction, l'ordre des entrées et chaque ligne existante octet pour octet. Ajouter le nouveau terme comme une nouvelle ligne ; ne jamais reconstruire, retrier ou reformater le fichier, et ne jamais introduire un deuxième tableau.
Ancres. Si la ligne du nouveau terme est accessible depuis une ancre de titre qu'un lien entrant utilise déjà, conserver cette ancre sur la ligne plutôt que de supprimer la cible ; si l'ancre ne peut pas être préservée, s'arrêter et le signaler au lieu de deviner.
Préserver le sens. Garder l'orthographe, les alias, les liens et le code en ligne du terme exactement comme fournis. Échapper une barre verticale littérale sous la forme \|. Si une définition est véritablement multiligne, la garder dans une seule cellule avec <br> pour le saut de ligne plutôt que de déborder sur des lignes supplémentaires.
Doublons et ambiguïté. Si le terme existe déjà, montrer les définitions existante et proposée et demander si mettre à jour ou laisser la ligne existante. Ne jamais fusionner, remplacer ou ajouter silencieusement une deuxième ligne pour le même terme, et ne jamais deviner une définition.
Fichier non canonique. Si le GLOSSARY.md existant est composé de puces, de texte, de titres ou d'une forme mixte, ne pas ajouter une ligne concurrente et ne pas réécrire le fichier comme effet secondaire de l'ajout d'un terme. Signaler la structure non canonique et proposer la migration consentie de la compétence d'audit ; ne l'appliquer que si l'utilisateur accepte la différence concrète. Une migration refusée laisse le fichier tel que l'utilisateur le conserve.

Nommer la règle et la propagation effectuée ; lister les dépôts non mis à jour.

Rapport de clôture

Terminer chaque exécution, y compris les exécutions bloquées, échouées et arrêtées, par une section intitulée exactement Statut en un coup d'œil, contenant ces trois libellés :

Cette exécution : uniquement les actions réellement tentées et leurs résultats ; citer la sortie exacte et le code de sortie de chaque porte de vérification, y compris les délais d'attente ou les interruptions.
Globalement : implémenté, partiellement vérifié, vérifié, bloqué, échoué ou inconnu. Une sous-étape réussie n'est pas une réussite globale ; les preuves incomplètes ou manquantes ne deviennent jamais un succès.
Reste à faire : chaque action restante, constat non résolu, vérification, nettoyage ou entrée requise. Écrire Aucun uniquement lorsque l'ensemble de la tâche est vérifiablement terminé ; ne jamais omettre de travail parce qu'un budget s'est terminé.

Les messages d'avancement de routine n'ont pas besoin de bloc. Garder les résultats finaux concis et distinguer le travail préparé sur une PR du travail confirmé comme livré.

EvolveHQ/docflow

Qu'est-ce que docflow ?

Demander à votre IA préférée

Documentation