chukaofili/agent-plugins

Synchroniser la documentation

Les documents dérivent en silence. Rien n'échoue quand un README nomme un fichier qui a été déplacé. Exécutez ceci après chaque étape de PR empilée ou fonctionnalité terminée, avant l'ouverture de la PR.

Le contrat de ce skill inclut le commit. Il peut effectuer un commit sans demander, toujours sur la branche courante, jamais main.

Quand sauter

• Rien de ce que référence un document n'a changé (logique interne pure). Écrivez quand même « doc vérifiée, pas de dérive » dans la section Test de la PR, pour que le relecteur sache que ça a été fait.
• L'utilisateur ne veut explicitement pas encore de commit de documentation.

L'inventaire : docs/DOCS.md

La liste des documents concernés se trouve dans docs/DOCS.md, pas dans AGENTS.md, afin que le contexte toujours actif ne croisse pas à chaque synchronisation.

# Inventaire des documents

| Chemin | Possède | Généré par |
|---|---|---|
| README.md | Pitch, configuration, variables d'environnement, structure | |
| AGENTS.md | Règles de l'agent + portes du projet | |
| packages/api/README.md | Points d'accès, scripts, variables d'environnement | |
| docs/api/openapi.json | Référence API | `pnpm generate:openapi` |

## Gelé (jamais modifié par une synchronisation)
- docs/plans/

## Contrôles de dérive
<!-- un grep par erreur qui s'est réellement produite, avec un commentaire expliquant pourquoi -->

Première exécution : construisez-le. Parcourez les README.md / AGENTS.md / CLAUDE.md racine et par package, les documents contributeurs, les documents d'API (descriptions OpenAPI, llms.txt), les répertoires de skills et de règles, et les références de variables d'environnement (.env.example, schémas de configuration). Écrivez ce que chacun possède.

Chaque exécution : tout document que vous trouvez et qui n'est pas listé est ajouté, dans le même commit.

Procédure

1. Auditer. Différencier la branche par rapport à sa base (git diff <base>...HEAD --stat), et lister ce qui a changé et qu'un document pourrait mentionner : chemins, noms de packages, routes, commandes et scripts, variables d'environnement, API exportées, comportement, conventions.
2. Vérifier. Pour chaque document de l'inventaire, vérifier chaque affirmation concrète par rapport au code : chaque fichier nommé existe à ce chemin, chaque commande existe dans le manifeste, chaque variable d'environnement est effectivement lue, chaque route et export existe comme décrit. Lisez le code ; ne faites pas confiance au texte, y compris au texte que vous avez écrit plus tôt.
3. Modifier. Corriger la dérive. Décrivez ce que fait le code, et n'inventez jamais de comportement pour améliorer la lecture d'un document. Si le code et le document sont en désaccord et que vous ne pouvez pas dire lequel a tort, signalez-le plutôt que de deviner.
4. Régénérer. Exécutez chaque commande de générateur listée dans l'inventaire. Ne modifiez jamais manuellement un document généré.
5. Exécuter les contrôles de dérive listés dans docs/DOCS.md. Lorsqu'une synchronisation trouve une erreur susceptible de se reproduire (un ancien chemin, une commande renommée), ajoutez un grep pour celle-ci avec un commentaire expliquant pourquoi.
6. Commiter. Stager les fichiers par chemin, jamais git add -A. Faites un commit atomique, docs(<portée>): sync <quoi> avec <changement>, sur la branche courante.
7. Pousser si la branche suit déjà un dépôt distant (git pull --rebase d'abord). Ne jamais pousser vers main.

Règles

• Historique gelé : les conceptions, plans et transferts dans docs/plans/ sont des instantanés de ce qui a été décidé à ce moment-là. Ils apparaîtront dans les greps ; c'est normal, pas une dérive. Ne les modifiez jamais lors d'une synchronisation.
• Les spikes et prototypes sont supprimés une fois que leur direction est livrée ou abandonnée, pas conservés comme référence. Les conclusions d'un spike sont le texte le moins fiable du dépôt une fois que la production en sait plus. Tout ce qui vaut encore la peine d'être connu est déplacé dans la documentation du code livré.
• Budget de taille : les lignes de documentation comptent dans le budget de la PR. Si la synchronisation pousse une étape au-delà de 500 lignes, atterrissez-la comme une étape de documentation seule au sommet de la pile (voir stacked-prs).
• Les fichiers pointeurs restent minuscules. Un CLAUDE.md ou GEMINI.md qui pointe simplement vers AGENTS.md doit rester ainsi. Ne copiez pas le contenu dedans.