wiki-smith — gérer le `.wiki/` du dépôt

wiki-smith — garder le .wiki/ du dépôt

Un wiki est la mémoire du dépôt, écrite pour les agents : ils y trouvent la règle au lieu de redemander. Le journal contient ce qui s'est passé ; la page thématique contient ce qui est vrai maintenant. Une leçon qui ne vit que dans le journal est perdue. wiki-smith décide lequel des deux une session nécessite, l'écrit selon les règles de ce wiki, et vérifie.

Méthode complète (types de fichiers, format de note, ingestion, liens, dates, commit) : references/method.md. Clés de configuration : references/config.md. Crédits : ATTRIBUTION.md. Modifications : CHANGELOG.md. Sa propre mémoire : .wiki/.

<skill> ci-dessous est le dossier de cette compétence (par exemple ~/.claude/skills/wiki-smith). Chaque script prend -w <répertoire wiki> (par défaut ./.wiki) et -c <config> (par défaut <wiki>/wiki.config).

Étape 0 — Trouver le wiki et ses règles

1. Le wiki est .wiki/ à la racine du dépôt. S'il n'y en a pas, le signaler et proposer d'en créer un à partir de templates/ (wiki.config.example en premier) ; ne jamais le créer sans demande.
2. Lire .wiki/wiki.config s'il existe (noms : dossier journal, boîte de réception, index, étiquette de pied de page, clés de date, branche principale). Par défaut, ce sont des noms anglais génériques : journal/, inbox.md, index.md, Map:, ## History, created/updated.
3. Les règles du wiki prévalent. Si le dépôt a une page sur la façon de le maintenir (rg -n -i 'maintenir|maintain' .wiki -l) ou une règle AGENTS.md concernant le wiki, lire cette section et la suivre là où elle diffère de cette compétence.
4. Si l'utilisateur a demandé « mise à jour du wiki » et que le wiki (généralement l'index) indique de confirmer d'abord, faire les étapes 1 et 2 comme un plan uniquement : une ligne par page avec les modifications, les titres des nouvelles notes, puis demander « Appliquer ? » et ne modifier qu'après un oui. Sinon, agir.

Étape 1 — Examiner ce qui s'est passé, puis acheminer

Lire la session (et git diff, git log pour le travail effectué). Choisir chaque ligne qui s'applique, et rien d'autre :

Ce que la session contenait	Ce qu'il faut faire
Une décision, livraison, changement de cap, incident ou recherche	Une note quotidienne : scripts/note.sh -b "Titre qui dit ce qui a changé" avec le paragraphe passé en entrée. Puis la ligne du jour dans la boîte de réception.
Une règle, leçon ou fait qui vaut au-delà d'aujourd'hui	Aussi corriger la page thématique : la règle telle qu'elle est maintenant, sans historique (l'historique reste dans la note et dans la section History de la page). Corriger ce que la page disait avant ; ne jamais empiler « c'était avant ».
Un nouveau sujet avec plusieurs facettes (il reviendra, et une seule page mélangerait les types)	Une carte de contenu moc-<sujet>.md plus les pages <sujet>-<facette>.md (aide-mémoire, installation, intégration, comparaison avec l'outil actuel…). Voir « Nouveau sujet » ci-dessous.
Rien d'intéressant à enregistrer (seulement des étapes intermédiaires, ou ce qu'un commit dit déjà)	Le dire en une ligne et ne rien créer. Remplir le journal le rend illisible.

Seule une nouvelle note est créée pour le journal ; ne jamais réécrire la note d'un autre agent.

Étape 2 — Écrire

Note quotidienne. scripts/note.sh "<titre>" crée <DIARY_DIR>/<aujourd'hui>/<HHMM>-<slug>.md en UTC et imprime le chemin (règles de slug et -2 en cas de collision dans le script). L'entrée standard n'est lue qu'avec -b : les shells d'agent et CI laissent stdin ouvert indéfiniment, donc sans -b le script n'attend jamais. Envoyer le corps : printf '%s\n' "<paragraphe>" | scripts/note.sh -b "<titre>" ; -b met exactement une ligne vide entre le titre et le corps. Sans -b le fichier n'a que la ligne de titre ; pour ajouter le paragraphe après, commencer par une ligne vide : printf '\n%s\n' "<paragraphe>" >> "$chemin". Le corps est un paragraphe bien écrit : ce qui s'est passé, pourquoi c'est important, où est la preuve (commit, PR, issue), avec un lien vers la page thématique. Les liens sont relatifs au dossier du jour (../../page.md). Modèle : templates/note.md.

Première note du jour : scripts/day-index.sh crée l'index du jour ; puis ajouter le jour en haut des « derniers jours » dans la boîte de réception. Si la note change le fonctionnement du dépôt, ajouter aussi une ligne aux faits marquants de la boîte de réception. La boîte de réception ne contient jamais de note.

Page thématique (ingestion). La trouver (rg -n -i '<mot>' .wiki) ; si elle n'existe pas et que le sujet reviendra, la créer (modèle : templates/page.md) ; si elle est petite, la mettre dans une section d'une page voisine. Écrire la règle telle qu'elle est maintenant. Si un changement modifie ce que la page affirme, ajouter une ligne en haut de sa section History. La note renvoie vers la page.

Nouveau sujet.

1. Écrire d'abord les pages, une par facette, chacune autonome dès la première phrase. Facettes typiques : aide-mémoire (la première à commencer : adresses, commandes, raccourcis), installation, intégration, comparaison avec l'outil utilisé actuellement.
2. Créer moc-<sujet>.md (templates/moc.md) : un paragraphe d'ouverture, « les pages » (une ligne chacune, aide-mémoire en premier), « ce qu'il faut savoir d'abord » (les quelques règles qui coincent).
3. Donner à chaque page le pied de page (Map : [moc-<sujet>](moc-<sujet>.md) · Related : ...), ajouter la carte et chaque page à l'index, et lier la carte depuis au moins une autre carte.
4. Une note dans le journal dit ce qui a été créé et renvoie vers la carte.

Étape 3 — Clôture (toujours, dans cet ordre)

1. scripts/dates.sh — le created/updated des métadonnées, depuis git. Idempotent.
2. scripts/day-index.sh — régénérer l'index du jour. Ne jamais l'éditer à la main.
3. python3 -I scripts/lint.py — corriger chaque fichier:ligne: type: message qu'il imprime jusqu'à ce qu'il se termine par 0 (code 2 signifie problèmes). Ne pas livrer un linter rouge.
4. Commiter uniquement vos propres fichiers, par chemin, jamais git add -A : scripts/sync.sh -m "wiki: <quoi>" <chemins>.... Il commit sur place lorsque la copie de travail est sur <main>, à jour et sans modifications hors de vos chemins ; sinon il transporte vos chemins dans un nouveau git worktree à partir de origin/<main>. Dans les deux cas, il linte exactement ce qu'il commit et refuse un linter rouge (code 1, copie de travail inchangée, worktree supprimé). Lors du transport, l'index du jour généré n'est jamais copié : il est régénéré dans le worktree, donc il liste uniquement les notes qui sont dans le commit. Ajouter les lignes d'attribution que le dépôt ou votre hébergeur exige au message.
   • Fichiers partagés (index, boîte de réception) qu'une autre session a pu modifier aussi : ne pas les passer à un transport. scripts/sync.sh -W crée un nouveau worktree depuis origin/<main> ; faire vos modifications là (le wiki est au même chemin relatif), exécuter dates.sh, day-index.sh, lint.py, puis lancer sync.sh -m ... [-p] <chemins> depuis ce worktree. Il y commit, et avec -p rebase, pousse, avance la copie principale là où possible, et supprime le worktree. Un transport qui embarque les lignes d'une autre session (par exemple un lien vers une page qui n'existe que dans la copie) échoue au linter et s'arrête avant de commiter ; cet échec est le signal pour utiliser -W.
5. Pousser uniquement lorsque l'utilisateur a demandé la synchronisation : le même appel avec -p (fetch, rebase, push HEAD:<main>, avance rapide de la copie, suppression du worktree). Ne jamais forcer, ne jamais toucher aux fichiers modifiés par d'autres : un fichier qui diffère de ce que vous avez poussé et qui peut contenir les modifications d'une autre session (index, boîte de réception) est laissé tel quel. Si la copie de travail ne peut pas être avancée rapidement (le <main> local a divergé, ou des modifications locales se chevauchent), il le dit et se termine quand même par 0, car le push a réussi. Ouvrir une PR uniquement sur demande.

Commiter ce que vous avez écrit dans la même session sans attendre qu'on vous le demande ; la publication est l'appel de l'utilisateur.

Consulter le wiki

rg -n -i '<mot-clé>' .wiki (ou parcourir l'index), puis lire uniquement la page ou section correspondante, jamais tout le wiki. Pour ce qui s'est passé : la boîte de réception (court), puis seulement les jours qui comptent ; un jour = son index et les notes qu'il liste. Si le dépôt a des specs, elles disent ce que le système promet : rg -n -i '<mot-clé>' <répertoire specs>.

Pièges

• Le journal n'est pas la page. Une règle écrite seulement dans une note est perdue ; l'ingérer dans la page thématique dans la même session.
• Règles sans historique. « Avant de créer une carte, chercher les existantes », pas « nous dupliquions les cartes ». L'histoire reste dans la note.
• Une note par fichier. Plusieurs agents écrivent le même jour ; ils ne doivent jamais modifier le même fichier. L'index du jour est généré ; les conflits y sont résolus en réexécutant day-index.sh.
• Fichiers partagés entre sessions. L'index du jour, index.md et la boîte de réception contiennent toutes les modifications non commitées de chaque session dans une même copie de travail. sync.sh ne transporte jamais l'index du jour (il le régénère dans le worktree) et linte avant de commiter, mais il ne peut pas distinguer quelles sections d'un index.md ou d'une boîte de réception édités à la main sont les vôtres : le transport prend tout le diff. Quand une autre session a pu les toucher, utiliser sync.sh -W et éditer dans le worktree. Une ligne étrangère qui, par hasard, ne casse pas le linter est quand même transportée ; c'est la limite documentée du transport.
• Ne jamais attendre sur stdin. note.sh ne lit le corps qu'avec -b ; dans un shell d'agent, une simple lecture bloque indéfiniment. Cela s'applique à tout script que vous ajoutez.
• Ne pas enregistrer le transitoire : une commande qui a échoué une fois et a réussi à la reprise, un pépin d'environnement, une tâche ponctuelle. Capturer la correction fonctionnelle sur la page thématique, jamais « X est cassé » (cela se fige en refus après la disparition de la cause).
• Liens : relatifs, première mention par section uniquement ; une ancre est le slug GitHub du titre (minuscules, sans ponctuation, accents conservés, espace devient trait d'union). Renommer un titre casse ses ancres ; le linter le signale. Mettre un exemple de lien entre accents graves pour que le linter ne le lise pas.
• Renommer ou supprimer une page : rg -l 'ancien-nom' .wiki et corriger chaque lien, ancres incluses ; supprimer seulement après que le contenu a été déplacé.
• Taille de page : passé environ 150 lignes, ou quand règle, procédure, référence et historique se mélangent, diviser par type.
• Les données privées restent dehors. Les pages wiki sont commitées ; garder les secrets, jetons et données personnelles à l'extérieur, et référencer l'endroit où vit le secret à la place.
• Limites du linter : il ne détecte pas les contradictions entre pages ni les affirmations obsolètes ; c'est une revue d'agent lorsque le temps le permet.
• Limite de day-index.sh : un fichier de jour avec des notes manuscrites en ancien format est une erreur (fichier:ligne), non migré ; déplacer chaque note dans son propre fichier avec note.sh, puis réexécuter.

Étape 4 — Tenir son propre wiki

Si cette exécution a appris quelque chose sur le fonctionnement de wiki-smith lui-même (une erreur d'acheminement, un caprice de script), ajouter une ligne à .wiki/lessons.md : - AAAA-MM-JJ — <règle + pourquoi>. Modifier le clone source (biliboss/wiki-smith) et réinstaller (npx skills add biliboss/wiki-smith -g --copy -a claude-code -y), pas la copie installée, qui serait écrasée par une réinstallation. Les décisions de conception vont dans .wiki/design.md.