hackycy/init-agents-md

Initialiser AGENTS.md

Crée un guide du contributeur à la racine du dépôt ou dans un répertoire existant. La seule source de vérité pour le format de sortie et les sections recommandées est references/agents-md-prompt.md ; cette compétence se charge d'appliquer ces instructions fixes de manière sécurisée au périmètre approprié.

Entrée et périmètre

• Accepte zéro ou un argument de répertoire ; les chemins relatifs sont résolus par rapport au répertoire de travail courant. Sans argument, utilise la racine Git trouvée par git rev-parse --show-toplevel.
• Le répertoire explicite peut ne pas se trouver dans un dépôt Git ; sans argument et si aucune racine Git n'est trouvée, demande à l'utilisateur de spécifier un répertoire et s'arrête. Le chemin doit correspondre à un répertoire lisible ; un chemin manquant, un fichier, un répertoire illisible ou plusieurs arguments de répertoire provoquent l'arrêt.
• Le fichier de sortie candidat par défaut est AGENTS.md dans ce répertoire. Un seul périmètre est traité à la fois ; aucun répertoire n'est créé, aucun autre fichier modifié, aucune opération de staging, commit ou création de branche.
• Le corps du texte suit la langue principale de la documentation locale ; si les indices sont insuffisants, l'anglais est utilisé. Si le répertoire sélectionné n'est pas la racine du dépôt, la sortie commence par ## Scope, indiquant le répertoire relatif et les directives parentes applicables, et ne contient que les nouvelles règles locales ou restrictives.

Reconnaître d'abord, générer ensuite

1. Avant de rédiger, lire le contexte nécessaire du projet : structure du répertoire, manifest/lockfile, scripts, configuration build/test/lint, CI, README/CONTRIBUTING, et jusqu'à 30 commits pertinents si Git est disponible. Identifier les limites des paquets monorepo, le gestionnaire de paquets et la langue principale de la documentation locale.
2. Trouver tous les fichiers AGENTS.md pertinents : le fichier cible, les fichiers ancêtres de la racine du dépôt jusqu'au répertoire parent de la cible, et les fichiers imbriqués dans le sous-arbre de la cible. Pour les répertoires non Git, vérifier la chaîne des ancêtres. Pour le sous-arbre, vérifier d'abord les sous-répertoires immédiats ; étendre uniquement si un manifeste, des limites de paquets ou des guides existants pointent plus profondément. Ignorer .git, les dépendances/vendor, les sorties de build/coverage, le cache et les stockages de secrets ignorés.
3. Marquer les correspondances comme target, ancestor ou nested, et lire les guides pertinents (CLAUDE.md, CONTRIBUTING.md) comme contraintes. Les guides imbriqués sont lus, conservés et liés si nécessaire ; ils ne sont ni fusionnés ni modifiés.
4. Vérifier uniquement le nom et les métadonnées des fichiers potentiellement secrets. Ne jamais lire ni écrire de clés, tokens, identifiants ou contenu de .env.
5. Chaque commande et convention doit pouvoir être vérifiée par des scripts, une configuration, des fichiers existants ou l'historique. Distinguer les règles de dépôt observées des suggestions générales par défaut ; omettre directement toute section, commande ou assertion sans preuve.

Confirmation des correspondances

Avant de générer un brouillon, afficher toutes les correspondances, leurs périmètres respectifs et le chemin de sortie candidat, et vérifier les conflits de casse (par exemple agents.md). Il s'agit d'une barrière solide :

• Si le candidat cible existe déjà, le lire et demander à l'utilisateur de choisir entre merge, replace ou abort.
• Si la cible n'existe pas mais que des guides ancêtres ou imbriqués sont trouvés, demander à l'utilisateur de choisir explicitement entre « créer un nouveau guide pour ce périmètre » ou « mettre à jour un guide existant nommé » ; ne pas ajouter silencieusement de fichier enfant. Si un autre fichier existant est choisi, relancer la reconnaissance pour le répertoire de ce fichier, puis choisir le mode.
• S'il n'y a pas de correspondance, continuer à rédiger un nouveau fichier pour la cible d'origine.
• Si le fichier AGENTS.md sélectionné est un lien symbolique, un répertoire, un fichier spécial ou un fichier ordinaire non inscriptible, s'arrêter et signaler la raison.

Toute question sans réponse, tout choix ambigu ou tout conflit avec des guides comme CLAUDE.md laisse l'espace de travail inchangé.

Lire les instructions fixes

Avant de commencer à rédiger, lire intégralement references/agents-md-prompt.md. Ce fichier est le propriétaire canonique du titre, des exigences de documentation, des sections recommandées, de l'objectif de nombre de mots et du style d'expression. En fonctionnement normal, ne pas le modifier et ne pas copier son corps dans cette compétence.

Fusion, prévisualisation et écriture

La fusion (merge) suit la sémantique des titres Markdown : conserver les faits existants et les sections personnalisées, n'ajouter que ce qui manque et est étayé par des preuves. Présenter tous les conflits de commandes, chemins, priorités ou faits sous forme de tableau, et demander à l'utilisateur de choisir pour chaque élément entre conserver l'existant, adopter la preuve ou fournir un texte personnalisé ; ne pas écrire tant que des conflits non résolus subsistent. Le remplacement (replace) n'affecte qu'un seul fichier sélectionné et ne génère pas automatiquement de sauvegarde.

Pour un nouveau fichier, afficher le brouillon complet ; pour une mise à jour, afficher un diff unifié, avec le chemin, le périmètre, les sections, le nombre de mots, les lacunes de preuves et un résumé du mode. Ne pas créer ou modifier de fichier tant que l'utilisateur n'a pas explicitement confirmé l'écriture finale ; si des modifications sont demandées, revenir à la rédaction et à la prévisualisation. Avant d'écrire, relire la cible ; si le contenu a été modifié en externe, repasser par le processus de confirmation.

Validation et achèvement

Avant d'écrire, vérifier les titres, la hiérarchie des titres, les liens de périmètre des guides imbriqués, les chemins/scripts référencés, les placeholders, les valeurs sensibles et les espaces Markdown. Pour le guide racine, vérifier selon l'objectif de nombre de mots des instructions fixes ; pour les incréments imbriqués, vérifier environ 100–300 mots. Corriger automatiquement uniquement les problèmes mécaniques tels que les espaces de fin, les lignes vides en double, et prévisualiser à nouveau ; pour les problèmes sémantiques ou factuels, laisser l'utilisateur décider. Si la cible se trouve dans un dépôt Git, exécuter git diff --check ; sinon, effectuer une vérification d'espaces équivalente. Ne pas exécuter par défaut de build, test ou lint complet pour cette compétence.

Condition d'achèvement : le fichier AGENTS.md confirmé existe au chemin sélectionné, a passé les vérifications statiques, correspond à la prévisualisation approuvée ; rapport final indiquant le mode, le périmètre, les commandes vérifiées, les éléments omis/incertains et les résultats de validation. En cas d'abort ou d'échec de validation, signaler la raison et laisser la cible inchangée.