toyin-software-factory/sync

Style de sortie (mots simples, sans tirets ni traits d'union)

Écrivez tout ce que ce skill produit, fichiers comme messages, dans un langage simple et clair. Adressez-vous au lecteur en utilisant vous, de manière chaleureuse et directe comme un collègue, et présentez chaque étape comme une recommandation qu'il peut exécuter ou ignorer, jamais comme un ordre. Conservez les termes techniques qui ont une signification réelle ; expliquez chacun d'eux en termes simples. N'utilisez jamais de tiret ou de trait d'union comme ponctuation : pas de tiret cadratin, pas de tiret demi-cadratin, et pas de composés avec trait d'union. Écrivez read only, pas read-only. Dites-le en mots simples, ou reformulez la phrase. Le code, les chemins de fichiers, les indicateurs de commande et les valeurs sur lesquels d'autres skills s'appuient conservent leurs traits d'union. Utilisez des phrases courtes, des virgules ou des parenthèses. La clarté prime sur l'ingéniosité.

Ce que fait ce skill

Ferme la boucle sur une modification terminée : synchronise les fichiers AGENTS.md, le scope et les lignes **Status**: des spécifications liées avec ce que le dépôt montre maintenant, et signale ce qu'il ne doit pas modifier (spécifications obsolètes, prose rédigée). Le tableau des limites ci-dessous est le contrat exact.

agent-prompt.md est la source unique de vérité pour les règles de maintenance ; SKILL.md ne couvre que l'orchestration. Le thread principal le lit et effectue la maintenance elle-même (voir Étape 3).

Fichier canonique : le contexte durable réside dans AGENTS.md, indépendant de l'outil ; CLAUDE.md n'est qu'un pointeur vers celui-ci. /sync modifie/crée les deux, en les traitant uniquement comme cibles, jamais comme source de modification.

Limites

Action	/sync	Propriétaire
Modifier un fichier AGENTS.md racine/implanté existant	✅ maintient	/sync
Réconcilier la ligne ## Build approach du AGENTS.md racine avec l'approche de l'en-tête de scope (édition chirurgicale d'une seule ligne, comme la pile)	✅ maintient ; signale une divergence rédigée	/sync
Ajouter une ligne de pointeur vers design.md (le système de conception UI) dans le AGENTS.md le plus proche lorsqu'une modification en établit un	✅ maintient (pointeur uniquement)	/sync
Créer un AGENTS.md implanté <zone>/AGENTS.md pour une zone nouvelle dans cette modification	✅ crée (diff = contexte complet de la zone) + ajoute un pointeur racine	/sync
Créer un document implanté pour une zone déjà existante non documentée (uniquement tranchée par le diff)	❌ signale "exécutez /audit"	/audit
Créer ou restructurer le AGENTS.md racine	❌ signale "exécutez /audit"	/audit
Réconcilier la ligne **Status**: d'une spécification avec le statut de scope de sa fonctionnalité (planned→Proposed, in-progress→In Progress, done→Accepted ; une spécification Assumed fait exception : laissez-la Assumed et signalez-la, ne la réconciliez jamais en Accepted)	✅ Ligne de statut uniquement	/sync
Effacer une spécification Assumed (la sortir de Assumed)	❌ signale comme dette de décision "exécutez /architect pour ratifier" (jamais réconciliée avec le statut de la fonctionnalité ; seule la ratification l'efface)	/architect
Modifier le contenu d'une spécification / la remplacer	❌ signale comme obsolète	/architect
Réconcilier le scope, pour le fichier de scope de l'espace de travail concerné uniquement (pas tout docs/scope/), cocher toute sous-tâche terminée à partir des preuves du dépôt (code, tests, AGENTS.md), avancer le statut	✅ corrige	/sync
Ajouter ou réorganiser des fonctionnalités ou sous-tâches dans le scope	❌ laisse tel quel	/scope
Remplacer ou réécrire une prose rédigée dans AGENTS.md	❌ signale plutôt un conflit	humain

La ligne de partage sur la création est le contexte, pas la politique : créez uniquement lorsque cette modification vous montre la zone entière ; déléguez à /audit lorsque la zone préexiste à la modification et que vous n'en avez vu qu'une partie. En cas de doute, signalez plutôt que de créer.

Demandes vs actions

Agit. Ne fait une pause que lorsqu'il n'y a rien à synchroniser (ensemble de modifications vide). Chaque modification apportée aux fichiers rédigés est listée dans le rapport pour que vous puissiez la vérifier ou l'annuler.

Propriété des artefacts

Possède exactement ce que le tableau des limites accorde et n'écrit rien d'autre. En tant que réconciliateur universel des sous-tâches, il coche toute sous-tâche du scope qu'il peut vérifier à partir des preuves du dépôt (en balayant les sous-tâches /test//audit//sync que d'autres skills ne cochent pas) et avance le statut des fonctionnalités ; règles exactes dans agent-prompt.md.

Base des artefacts. Les spécifications et le scope se trouvent sous docs/ par défaut, ou .workflow/ si docs/ est un site de documentation publié ; utilisez la base qui existe dans le dépôt (les chemins ici supposent docs/).

---

Portabilité (tout OS, tout agent)

• Commandes : git est le seul outil CLI requis et se comporte de la même manière sur tous les OS ; exécutez les lignes git telles qu'elles sont écrites. Les autres extraits shell sont des références POSIX, pas des scripts littéraux : ne supposez pas que find, grep, sed, cat, test/[ ], ls ou xargs existent ; utilisez les outils de fichiers multiplateformes de votre agent et appliquez la logique de branchement vous-même plutôt que les if/variables/redirections shell.
• Fichiers fournis : référencés par des chemins relatifs au dossier de ce skill. Résolvez le dossier en un chemin absolu (vous résolvez déjà ces chemins relatifs) et lisez vous-même agent-prompt.md au moment de l'écriture (Étape 3), pas pendant les étapes précédentes.
• L'ensemble de la maintenance s'exécute en ligne sur le thread principal, en suivant les règles exactes de agent-prompt.md (qui fait autorité).

Exécution

1. Délimiter l'ensemble des modifications (peu coûteux, avec statut par fichier)

Actualité d'abord (équipes) : git fetch --quiet ; si git rev-list --count HEAD..origin/$BASE > 0 vous êtes en retard sur origin/$BASE, avertissez l'ingénieur de d'abord tirer les dernières modifications, un collègue a peut-être déjà synchronisé ces documents.

Base : main si git rev-parse --verify main réussit, sinon master. Branche actuelle : git rev-parse --abbrev-ref HEAD. Utilisez --name-status (pas --name-only) ; la logique de nouvelle zone et de nettoyage des orphelins a besoin de l'état Ajouté vs Modifié vs Supprimé par fichier.

• La branche actuelle est la base, mode uncommitted : git diff --name-status HEAD.
• Sinon, mode branch : git merge-base "$BASE" HEAD, puis git diff --name-status <merge-base>.

Dans les deux cas, ajoutez les fichiers non suivis de git ls-files --others --exclude-standard, chacun précédé d'un statut A (correspondant au format --name-status). Notez le mode, la base et la base de fusion pour l'étape d'écriture.

Supprimez les doublons, puis filtrez pour ne garder que les fichiers source à partir desquels synchroniser :

• Supprimez la documentation et la configuration (AGENTS.md à tous les niveaux, docs/**, *.md, test-preferences.json, les fichiers de verrouillage, la sortie générée) ; /sync les lit comme cibles/contexte, jamais comme source de modification.
• Supprimez les fichiers de test (*.test.*, *.spec.*, __tests__/, etc.) ; les tests ne sont pas des conventions de zone durables.
• Conservez les entrées D (supprimées) dans une liste séparée ; elles guident le nettoyage des orphelins (Étape 3) bien qu'elles ne soient pas synchronisées à partir de.
• Conservez les modifications des manifestes de dépendances dans une liste séparée pour la découverte d'outils, même s'il s'agit de configuration plutôt que de code source : package.json, pyproject.toml, requirements*.txt, go.mod, Cargo.toml, composer.json, Gemfile, pubspec.yaml, mix.exs, *.csproj, et les manifestes de paquets équivalents. Les fichiers de verrouillage ne sont que des signaux ; ne transmettez pas leur contenu.

S'il ne reste aucun fichier source et aucune modification de manifeste de dépendances (seuls des documents/tests/verrouillages/fichiers générés ont été modifiés), arrêtez-vous, rien à synchroniser. Ne démarrez pas.

2. Localiser les fichiers de contexte et les spécifications (chemins uniquement, ne les lisez PAS ici)

En utilisant les outils de recherche/glob de fichiers de votre agent :

• Notez si un AGENTS.md racine existe.
• Trouvez tous les fichier AGENTS.md (racine + imbriqués), en excluant node_modules/ et .git/.
• Trouvez toutes les spécifications sous docs/specs/ dont les noms commencent par un chiffre, triées.
• Trouvez le(s) fichier(s) de scope dont l'espace de travail/fonctionnalités sont réellement touchés par le diff (dans un monorepo, le fichier modifié apps/<x>/… sélectionne docs/scope/<x>/) ; ne lisez ni ne transmettez jamais la totalité de docs/scope/.

Notez les chemins ainsi que la liste des fichiers modifiés et la commande de diff ; lisez les fichiers au moment de l'écriture. Lisez le contenu du AGENTS.md racine maintenant (court et utile pour s'ancrer). Pour chaque fichier modifié, notez son répertoire englobant le plus proche avec un AGENTS.md (racine ou imbriqué) ; c'est le fichier de contexte le plus susceptible d'avoir besoin d'une mise à jour.

2.5 Découvrir les skills d'agent et les MCPs optionnels pour les outils nouvellement ajoutés

À exécuter uniquement lorsque les manifestes de dépendances ont changé ou que le diff ajoute clairement un outil externe significatif. Ignorez les bibliothèques utilitaires ordinaires à moins qu'elles ne définissent un flux de travail ou une intégration durable.

• Identifiez les paquets/outils significatifs nouvellement ajoutés à partir du diff des manifestes, pas du fichier de verrouillage complet : framework, routeur, kit de style/UI, base de données, ORM/couche de requêtes, auth/session, paiements, email/notifications, stockage/téléchargements, recherche, files d'attente/tâches en arrière-plan, fournisseur d'IA/base de données vectorielle, tests de navigateur/runtime, observabilité, hébergement/déploiement. Incluez les noms de paquets et les alias courants des manifestes. Ne vous arrêtez pas après la première technologie.

• Filtrez tout ce qui est déjà couvert par les skills installés, les MCPs connectés ou les entrées refusées dans AGENTS.md.

• Demandez avant de chercher.

  Demander est obligatoire. Chercher ne l'est pas. Rien n'est cherché, récupéré, installé ou lancé pour la découverte de Skills d'Agent et de MCP tant que l'ingénieur n'a pas choisi. Proposez quatre choix : trouve-les pour moi, je nommerai ceux que je veux, non et enregistre le refus, ou pas maintenant. Seul le premier peut exécuter une commande de recherche. Ne sautez jamais l'offre en silence, et n'exécutez jamais de recherche avant que l'ingénieur n'ait accepté.

  Nommez les outils que cette modification a ajoutés, dites en une ligne qu'un Skill d'Agent donne à l'agent les vraies conventions de cet outil et qu'un serveur MCP lui donne un accès en direct au système réel, puis demandez : "Voulez-vous que je trouve des Skills d'Agent et des serveurs MCP pour les outils que cette modification a ajoutés ?" (en-tête Agent skills), avec Oui, trouve-les pour moi (recommandé) · Je nommerai ceux que je veux · Non, ignore · Pas maintenant, plus tard. Sur Oui continuez ci-dessous. Sur Je nommerai ceux que je veux, prenez la liste et allez directement à l'étape d'installation, sans rien chercher. Sur Non, ignore n'exécutez rien et enregistrez le refus. Sur Pas maintenant, plus tard n'exécutez rien et notez les outils candidats dans le rapport.

• Isolez les recherches dans un sous-agent en lecture seule (capacité d'abord, uniquement après Oui). Confiez l'ensemble restant à un sous-agent de découverte plutôt que de chercher sur le thread principal : lancez-le en arrière-plan (il ne bloque pas) si votre agent le permet, sinon en mode bloquant ; définissez son modèle explicitement sur un niveau rapide et peu coûteux (n'héritez pas du modèle de session ; sur Claude Code, lancez-le comme type de sous-agent researcher, qui fixe le modèle) ; il ne renvoie que la liste compacte des candidats. Cela maintient la sortie de recherche en dehors du contexte limité de /sync. Pas de sous-agent → cherchez en ligne ; pas de capacité de recherche → ignorez et notez-le. Le panneau d'offre reste sur le thread principal.

• Pour chaque élément restant, exécutez npx skills find <tool-or-package> ; si le résultat est faible, réessayez avec des alias à partir des noms de paquets/organisations. Collectez chaque candidat crédible de Skill d'Agent et confirmez avec npx skills add <owner>/<repo> --list lorsque c'est pratique. Si le CLI est interactif/indisponible, cherchez "<tool>" "agent skill" et confirmez avant de proposer.

• La recherche MCP est optionnelle : d'abord la liste des connecteurs, sinon "<tool>" "MCP server" par élément. MCP est un avantage recommandé, pas une obligation.

• Limitez la découverte : maximum 5 recherches web et 8 pages récupérées au total, d'abord les registres officiels/documentation. Réutilisez docs/.agent-cache/tool-discovery/<slug>.md datant de moins de 30 jours, après avoir filtré les éléments installés/refusés.

• Proposez toutes les correspondances de Skills d'Agent dans un panneau de sélection multiple, regroupées par technologie : "Installer les Skills d'Agent pertinents pour les outils nouvellement ajoutés ?" plus ignorer/refuser. Proposez ensuite les MCPs séparément : "Serveurs MCP optionnels qui pourraient aider ces outils" plus ignorer/refuser. N'installez et ne connectez jamais automatiquement.

• Installez les skills sélectionnés avec npx skills add <owner>/<repo> -y. Pour les MCPs, pointez vers les paramètres de connecteur/MCP de l'utilisateur ; une fois connectés, les outils sont utilisés automatiquement.

• Transportez le résultat sous forme de INSTALLED_SKILLS_OR_NONE, MCP_SERVERS_OR_NONE et DECLINED_TOOLS_OR_NONE et enregistrez des lignes durables dans le bon fichier AGENTS.md lors de l'écriture. Si rien n'a été trouvé ou qu'aucune capacité n'existe, traitez comme none.

3. Effectuer la maintenance (thread principal)

Le thread principal effectue la maintenance lui-même ; il ne confie jamais les modifications de AGENTS.md / scope / statut de spécification à un sous-agent. Lisez agent-prompt.md maintenant (seulement maintenant, au moment de l'écriture) et suivez-le exactement ; il fait autorité pour les règles de maintenance. La lecture du diff est la seule chose que vous pouvez déléguer, et uniquement pour un grand ensemble de modifications, à un sous-agent scout en lecture seule sur le modèle le moins cher (Claude Code : haiku) qui renvoie une carte compacte. Restez dans les mêmes limites que celles exprimées par l'ancien octroi d'outil : Edit les documents existants, le scope et les lignes **Status**: des spécifications ; Write strictement pour un nouveau AGENTS.md imbriqué de zone ; pas de création racine, pas de modification du contenu des spécifications (ligne de statut uniquement), pas de documents imbriqués superficiels pour les zones établies (ce sont des règles dans agent-prompt.md).

Les entrées à appliquer :

1. MODE, BASE, MERGE_BASE, CHANGED_FILES (liste source modifiée avec statut de nom), DIFF_COMMAND (commande git diff exacte)
2. DELETED_PATHS (chemins supprimés, pour le nettoyage des orphelins)
3. ROOT_AGENTS_MD (contenu du AGENTS.md racine), NESTED_PATHS (chemins des AGENTS.md imbriqués)
4. SPEC_PATHS (tous les chemins de spécifications, pour la réconciliation de la ligne de statut et le signalement d'obsolescence)
5. FILE_TO_CONTEXT_MAP (fichier modifié → fichier de contexte le plus proche)
6. SCOPE_PATH_OR_NONE (chemin(s) de scope de l'espace de travail pertinent, pas tout docs/scope/ ; également la source du statut de chaque fonctionnalité liée pour la réconciliation de la ligne de statut des spécifications)
7. INSTALLED_SKILLS_OR_NONE, MCP_SERVERS_OR_NONE, DECLINED_TOOLS_OR_NONE de l'Étape 2.5

4. Transmettre le résultat

Si la maintenance a échoué ou n'a produit aucun résumé exploitable, signalez-le et recommencez, n'inventez pas de résultat (un NOTHING_TO_SYNC authentique est un succès valide ; un plantage ou une sortie vide ne l'est pas). Sinon, transmettez le résumé compact :

Commencez par ce qui a été réconcilié en une ligne ; listez ensuite uniquement ce qui nécessite l'ingénieur (selon docs/conventions.md). Les modifications elles-mêmes sont dans les fichiers. Modèle :

## /sync terminé · <N> fichiers modifiés réconciliés

**<Fichiers AGENTS.md · fonctionnalités de scope · statuts de spécifications> mis à jour pour correspondre au diff.**   (ou "tout déjà à jour, rien à synchroniser")
Point d'attention (besoin de vous) :
- Spécification obsolète → /architect : `<fichier>` (<pourquoi, ou une divergence de statut que /sync n'a pas pu résoudre en toute sécurité>)