vicunav/vicunav-transform-claude-to-gutenberg

Transformar Claude Code à Gutenberg FSE

Objectif

Convertir le projet approuvé de Claude Code en un site WordPress natif et maintenable. Conserver la conception, le contenu et le comportement convenus sans traîner l'architecture du prototype frontend lorsque WordPress propose déjà une solution éditable par blocs.

Traiter le projet source comme une spécification visuelle et fonctionnelle. Travailler uniquement sur le LocalWP autorisé. Ne pas modifier la production, ni supprimer du contenu, des personnalisations de l'éditeur de site ou des données locales sans approbation explicite.

Rassembler le contexte minimal

Confirmer ou découvrir avant de modifier :

• chemin du projet exporté ou affiné dans Claude Code ;
• chemin du site LocalWP et du thème cible ;
• commit, build ou état exact constituant la conception approuvée ;
• pages, points de rupture, états et interactions inclus ;
• version réelle de WordPress et PHP du site local ;
• si l'objectif est une parité 1:1, une optimisation approuvée ou une refonte ;
• contenu et intégrations devant être modifiables depuis WordPress ;
• restrictions sur les plugins, blocs personnalisés, polices et licences des actifs.

Si une décision manque qui change le contenu, l'architecture, la fonctionnalité ou la conception, s'arrêter et la demander. Si une donnée récupérable du système de fichiers, du frontend ou du site local manque, l'inspecter et enregistrer la supposition.

Charger les bases réutilisables

Appliquer les skills officiels installés selon la phase :

• wp-project-triage : classer le projet WordPress et sa chaîne d'outils ;
• wp-block-themes : implémenter theme.json, templates, parts, patterns et styles FSE ;
• wp-block-development : utiliser uniquement si une interaction exige un bloc personnalisé ;
• wp-wpcli-and-ops : inspecter ou modifier le contenu et les options avec WP-CLI ;
• unlazy (si installé) : discipline de clôture pour une migration de taille conséquente (plus d'une page, ou tout travail qui sera déclaré terminé sans supervision constante). Voir "Clore chaque unité avec la discipline des gates" ci-dessous.

Vérifier d'abord la version cible. Si un skill officiel cible une version de WordPress postérieure à celle de LocalWP, utiliser uniquement les API compatibles et consulter la documentation officielle pour résoudre les différences.

Lire les ressources propres lorsque approprié :

• source-contract.md : avant de figer la baseline et de définir le contrat de migration ;
• migration-manifest.md : avant de capturer la baseline ou d'implémenter tout changement ayant un impact visuel ;
• translation-map.md : avant de décider l'architecture Gutenberg et lors de la traduction de chaque composant ;
• localwp.md : avant de toucher au site ou à sa base de données ;
• qa-checklist.md : avant la première section visible et à nouveau avant de déclarer le travail terminé ;
• upstream.md : lors de la mise à jour, de l'audit ou de la redistribution des bases réutilisées ;
• templates/gates-fse-migration.md : lors de l'ouverture de $unlazy pour une page ou une section, comme ledger initial à copier et compléter au lieu d'écrire les gates depuis zéro.

Exécuter le flux

1. Lire les instructions locales, l'état Git et la documentation directement impliqués dans les deux projets.
2. Exécuter scripts/audit_source.mjs <chemin-source> et examiner manuellement ses constats. Ne pas traiter le rapport heuristique comme une décision architecturale.
3. Créer le manifeste de migration, indexer toutes les combinaisons attendues et exécuter scripts/validate_migration_manifest.mjs <chemin-manifeste>.
4. Lancer le frontend source dans un environnement propre et capturer la baseline sur desktop, tablette et mobile, incluant les états interactifs pertinents.
5. Créer le contrat de migration : pages, sections, copy, actifs, tokens, interactions, sources de données, intégrations et critères d'acceptation.
6. Séparer les tokens réutilisables de la géométrie locale. Mapper les premiers dans theme.json et conserver la seconde via des blocs, mises en page et classes sémantiques minimales.
7. Concevoir l'architecture FSE : templates, template parts, patterns, contenu des pages et, uniquement lorsque nécessaire, blocs personnalisés ou plugins.
8. Implémenter d'abord une section représentative. Comparer le frontend et l'éditeur de site avant d'étendre le motif au reste du site.
9. Migrer page par page et section par section. Maintenir le projet source visible comme référence pendant toute l'implémentation. Si $unlazy est disponible, ouvrir une unité en copiant templates/gates-fse-migration.md vers un GATES.md propre à cette page ou section avant de l'implémenter, pas après.
10. Installer ou activer le thème dans LocalWP via le flux documenté du projet. Créer ou mettre à jour le contenu de manière idempotente et en préservant l'existant.
11. Exécuter scripts/validate_fse_theme.mjs <chemin-theme> et corriger toutes les erreurs. Vérifier les avertissements applicables.
12. Effectuer un QA visuel, structurel, éditorial, responsive, d'accessibilité et de performance sur le frontend et l'éditeur de site.
13. Exécuter la capture, la comparaison et le gate via capture_visual_evidence.mjs, compare_visual_evidence.mjs et verify_visual_evidence.mjs ; examiner manuellement côte à côte et en superposition. Pour chaque page avec au moins une section full-bleed, exécuter en plus scripts/verify_editor_frontend_parity.mjs (nécessite un cookie de session réel généré avec scripts/wp_auth_cookies.php, voir translation-map.md) et exiger PARIDAD_EDITOR_FRONTEND_OK : la comparaison visuelle humaine n'est pas suffisante à elle seule pour cette classe de bug, déjà documentée deux fois dans ce projet. Si l'unité a un GATES.md, lancer node <skill-dir-de-unlazy>/scripts/gate-check.mjs --reverify GATES.md et exiger ALL MET avant de continuer.
14. Fournir la preuve, les limitations, le rollback et la prochaine unité de travail. Si $unlazy a été utilisé, inclure les ids qualifiés des gates accomplis, non accomplis et abandonnés ; ne pas décrire comme terminée une unité avec un gate en attente ou abandonné.

Clore chaque unité avec la discipline des gates ($unlazy)

Quand unlazy est installé, le traiter comme la couche de discipline de clôture de ce skill, pas comme une alternative à celui-ci : ce skill décide quoi vérifier dans une migration FSE ; unlazy oblige à déclarer ces critères comme commandes exécutables avant de travailler et à les revérifier avec une preuve réelle avant de signaler comme terminé, au lieu de se fier à une lecture visuelle de "ça a l'air bien".

• Utiliser le mode seulement de unlazy pour une page ou une section (un GATES.md par unité, copié de templates/gates-fse-migration.md). Utiliser le mode orchestré uniquement pour un site complet avec beaucoup de pages indépendantes, où chaque page est une feuille de l'arbre de profondeur avec son propre OWNS: (ses propres fichiers de template/pattern) et une branche d'intégration vérifie la navigation croisée, l'en-tête/pied de page partagé et l'absence de régressions entre les pages.
• Ne pas convertir chaque correction triviale en un ledger de gates. Réserver la discipline pour une page, une migration de site complet, ou toute unité dont le coût de rester incomplète silencieusement le justifie (voir l'exemple réel : contenu hardcodé dans un template qui a laissé une page vide et inéditable pendant plusieurs unités de travail avant que le propriétaire du site ne le détecte manuellement).
• Adapter le gate de contenu réel (post_content non vide) à l'invocation réelle de WP-CLI du projet ; dans LocalWP ce n'est presque jamais le binaire wp global (voir localwp.md).
• Un gate manuel reste valide pour ce qu'aucune commande ne peut bien mesurer (fidélité visuelle perceptuelle, révision éditoriale du copy). Ne pas forcer une métrique automatique juste pour éviter un gate manuel ; le contrat de ce skill interdit déjà de convertir une métrique perceptuelle en approbation automatique de parité.
• Ne pas installer le hook Stop optionnel de unlazy sans le demander explicitement à l'utilisateur d'abord ; le skill l'exige.
• Router le travail vers le niveau de modèle approprié, aussi bien en mode orchestré de unlazy que dans la migration page par page de ce skill : une feuille mécanique et bien délimitée (traduction directe d'un composant déjà résolu dans une autre page, un ajustement de classe, un correctif ponctuel déjà diagnostiqué) va vers un modèle plus léger ; une feuille qui nécessite un jugement architectural, décider bloc vs. pattern vs. CPT, ou toute vérification visuelle, est retenue par le modèle de la session. Ne pas répartir un agent complet pour chaque petite édition quand les regrouper en un seul passage obtient le même résultat avec moins de coordination.

Maintenir les contrats non négociables

• Préférer les blocs core, les patterns du thème et les API publiques de WordPress.
• Ne pas utiliser core/html comme raccourci pour conserver le HTML du prototype.
• Utiliser theme.json comme source de vérité pour les tokens partagés.
• Maintenir les templates et parts pour la structure globale ; utiliser le contenu des pages ou les patterns pour la composition éditoriale.
• Ne pas introduire React, Tailwind ou l'exécution du prototype dans le frontend de WordPress sauf si un besoin est démontré et approuvé.
• Créer des blocs personnalisés uniquement pour un comportement ou une édition que les blocs core ne peuvent pas exprimer de manière maintenable.
• Placer la logique métier, les réservations, les commandes et les modèles de données dans des plugins, pas dans le thème.
• Servir les polices et les images localement et conserver la licence, la provenance et le texte alternatif.
• Maintenir le frontend et l'éditeur de site comme surfaces obligatoires.
• Ne pas implémenter une migration visuelle sans manifeste valide et matrice complète.
• Ne pas convertir une métrique perceptuelle en approbation automatique de parité.
• Ne pas dépendre de styles globaux accidentels sauvegardés dans la base de données.
• Respecter prefers-reduced-motion, le clavier, le focus visible et WCAG 2.1 AA.
• Ne pas inventer de contenu, de chemins ou de fonctionnalités pour combler les vides de la conception.

Appliquer le critère de la démonstration de restaurant

• Modéliser un menu petit et purement éditorial avec des blocs et des patterns.
• Proposer un CPT comme vicu_menu_item uniquement si le menu a besoin d'une édition structurée, de filtres, de réutilisation ou de croissance réelle ; l'enregistrer dans un plugin et tester son comportement.
• Traiter les réservations, commandes, paiements, horaires dynamiques et disponibilité comme des intégrations fonctionnelles séparées. Ne pas les simuler silencieusement avec un formulaire statique.
• Réutiliser l'en-tête, le pied de page, les appels à réserver et les modules de contact via des parts ou des patterns synchronisés avec l'architecture approuvée.

Travailler en unités vérifiables

Clore une page ou une section uniquement lorsque :

• le contenu, les liens et les actifs correspondent au contrat ;
• le markup est valide et ses blocs restent éditables ;
• le frontend et l'éditeur représentent correctement les styles ;
• desktop, tablette et mobile sont comparés à la baseline ;
• les états hover, focus, active, loading et error applicables sont testés ;
• il n'y a pas d'erreurs de console, de ressources distantes inattendues ou de dépendances du serveur de développement de Claude Code ;
• la preuve correspond à l'état exact testé ;
• la combinaison a une ligne unique dans le manifeste et ne reste pas pending.

Fournir un état vérifiable

Informer :

• pages et sections complétées ;
• architecture et fichiers affectés ;
• décisions concernant les blocs core, patterns, blocs personnalisés ou plugins ;
• commandes et vérifications exécutées avec leurs résultats ;
• URLs et viewports utilisés pour la comparaison ;
• différences acceptées, risques résiduels et rollback ;
• chemin du manifeste validé et résumé de sa matrice de preuve.

Ne pas affirmer la parité visuelle parce que le site s'affiche ou parce que le HTML contient le même copy. La parité nécessite une comparaison visuelle et une validation de l'éditabilité.

Exemples d'invocation

Utilise $transform-claude-to-gutenberg pour auditer ce projet Claude Code et
créer le contrat de migration de la page d'accueil vers le site LocalWP
indiqué.

Utilise $transform-claude-to-gutenberg pour transformer la démonstration de
restaurant en un block theme FSE 1:1, en utilisant des blocs core et des
actifs locaux.

Utilise $transform-claude-to-gutenberg pour réviser le thème migré et lister
ce qui l'empêche d'être considéré comme éditable et visuellement équivalent
au prototype approuvé.