fswp-architect

FSWP Architect

Aucun code n'est écrit tant que cette étape ne se termine pas par un PRD ou un brief de changement approuvé. Objectif : chaque décision prise en un seul tour de questions et un seul document révisable, zéro allers-retours par la suite.

Étape 0 : Type de travail et tri

• Confirmer le type de travail dans fswp-developer/references/work-types.md : Nouveau plugin, Nouveau thème, Mise à jour, Extension, Patch Core.
• Mise à jour, Extension, Patch Core ou toute base de code inconnue : exécuter d'abord python3 scripts/detect_wp_project.py <chemin>. Il rapporte le type de projet (plugin, thème, thème FSE, checkout Core, site, inconnu), le fichier principal et les champs d'en-tête, les indices de version et de version minimale, les outils (Composer, npm, PHPCS, PHPStan, tests) et les hooks/routes REST/blocs trouvés. Citer les résultats dans le plan. Le script ne fait que lire les fichiers.
• Les demandes en forme de plugin ou de thème comptent même sans le mot "plugin" ou "thème" (types de contenu, intégrations REST, tableaux de bord admin, templates personnalisés, style à l'échelle du site, tout ce qui nécessite un comportement d'activation ou de désinstallation). Les outils à shortcode unique livrés en tant que fichiers FluentSnippets appartiennent à wordpress-mini-app-builder, pas ici.

Étape 0a : Pas encore de PRD

Si l'utilisateur demande à commencer la construction et qu'aucun PRD ni brief de changement n'existe : lui demander d'en fournir un avant de commencer. Ne pas commencer l'implémentation et ne pas passer silencieusement à l'Étape 1 à sa place. Si l'utilisateur insiste explicitement ("construis-le simplement", "saute le PRD"), l'exigence est levée : aller directement à l'Étape 1 et rédiger le document à partir de ce tour de questions.

Étape 0b : PRD fourni par l'utilisateur, AGENTS.md, documentation d'architecture

Les lire avant d'écrire du code et les vérifier par rapport à fswp-plugin-developer/references/standards.md et aux autres règles de la maison.

• Pas de conflit réel : procéder avec la documentation fournie ainsi que les standards de la maison ; les règles de la maison comblent les lacunes.
• Conflit réel (le document demande quelque chose qu'une règle de la maison interdit, comme un raccourci de sécurité ou un schéma de nommage) : nommer les deux côtés clairement et demander lequel prévaut. Ne jamais les mélanger silencieusement.
• Un PRD fourni passe quand même par l'Étape 4 ; il n'en est pas exempté.

Étape 1 : Un tour de questions essentielles

Utiliser l'outil de question structurée lorsqu'il est disponible (Claude Code : AskUserQuestion ; claude.ai : ask_user_input_v0) ; sinon une liste numérotée compacte. Au maximum 3-4 questions, choisies par type de travail :

Type de travail	Demander à propos de
Nouveau plugin	Cible de distribution (WordPress.org, zip privé, les deux) ; surface fonctionnelle (type de contenu, table personnalisée, REST, cron, écran admin, sortie front-end) ; système de design front-end (le vôtre, s'il existe, ou neutre) ; comportement statique ou dynamique ; préfixe/acronyme de code pour ce projet
Nouveau thème	Thème FSE ou classique ; distribution (répertoire de thèmes WordPress.org, privé, site client) ; point de départ (from scratch, enfant d'un thème existant) ; quels types de contenu et mises en page sont requis ; préfixe/acronyme de code pour ce projet
Mise à jour	Objectif (bug, fonctionnalité, compatibilité, refactorisation) ; comment elle est livrée (patch sur un dépôt, zip, modifications directes) ; ce qui ne doit pas changer
Extension	Produit hôte et plage de versions supportées ; ce que l'extension ajoute ; ce qui doit se passer si l'hôte est manquant
Patch Core	Numéro de ticket ou description du bug ; composant cible ; si un ticket Trac existe déjà

Tout ce qui est ouvert (noms de champs, règles métier, cas particuliers, nom de travail) est déduit et listé sous "Hypothèses" du PRD, pas demandé. Pas de second tour à moins que les réponses du premier tour n'aient créé une bifurcation réellement bloquante.

Préfixe/acronyme : pour les travaux de nouveau plugin et nouveau thème, demander quel acronyme ou préfixe court le code du projet doit utiliser ; si l'utilisateur n'en a pas, proposer 2-3 candidats dérivés du nom du projet lui-même et le laisser choisir. Il n'y a pas de valeur par défaut intégrée et le nom ou la marque de cet outil n'est jamais utilisé comme substitut. Règle complète, formulation exacte de la question et exceptions (minimum 4 lettres pour un thème, slug du produit vs. préfixe de code, noms réservés) : fswp-developer/references/brand-naming.md. Jamais WP ou Plugin comme préfixe. Pour les travaux de mise à jour et d'extension, ne pas demander ; conserver le préfixe existant du projet. Versions minimales par défaut : WordPress 6.4, PHP 7.4 ; augmenter uniquement pour un besoin spécifique (par exemple PHP 8.1 pour les énumérations). Confirmer les exigences actuelles dans la documentation officielle quand c'est important.

Informations sur le projet (même tour, jamais un second) : nom de l'entreprise, nom du produit, auteur, contributeurs et liens (site web, documentation, support, dépôt). Demander uniquement ce qui n'est pas déjà indiqué. Ne jamais inventer une valeur manquante : un lien ou un contributeur non indiqué est omis de chaque fichier généré.

Décision sur la pile technologique : pour un nouveau travail, décider le niveau de l'interface d'administration et le niveau JS avant de rédiger le PRD (fswp-plugin-developer/references/standards.md section 2). Pour un travail existant, la pile existante reste en place sauf s'il y a une raison énoncée de la changer.

Étape 2 : Recherche concurrentielle

2-3 produits leaders dans la catégorie (répertoire WordPress.org ou SaaS). Capturer les fonctionnalités de base, les plaintes courantes et les conventions qui méritent d'être imitées. Quelques recherches ; 3-5 puces dans le document. Ignorer pour les patches Core ; rechercher plutôt l'historique du ticket.

Étape 3 : Le document

• Nouveau plugin, nouveau thème : PRD à partir de references/prd-template.md (variantes pour les thèmes à l'intérieur).
• Mise à jour, Extension : brief de changement à partir de references/change-brief-template.md : comportement actuel, comportement demandé, liste de parité (ce qui doit continuer à fonctionner), tableau de compatibilité, risques, plan de test.
• Patch Core : brief centré sur le ticket à partir de references/change-brief-template.md plus les étapes dans fswp-core-contributor.

Passer le comportement front-end à travers la checklist JS en 5 points (fswp-plugin-developer/references/frontend-output.md) et indiquer le niveau. Les comptes dérivés (tokens, blocs, routes, écrans) proviennent des données ou du code, jamais de la mémoire.

Étape 4 : Porte d'approbation (la seule)

Présenter le document. Les décisions sont visibles et déjà prises ; l'utilisateur approuve ou corrige une fois. Si le niveau JS est Alpine, le nommer et obtenir un oui explicite. Pas d'échafaudage ni de modifications avant l'approbation ; les corrections approuvées sont intégrées en premier.

Mode Migration

Pour reconstruire un plugin existant sur une nouvelle pile. Avant toute modification de code :

1. Base de référence : capturer des captures d'écran de chaque écran et état, ainsi que des exports de référence (paramètres, données, fichiers générés) de l'ancienne version. Stocker sous baseline/.
2. Matrice de parité : chaque fonctionnalité, paramètre, hook, shortcode, route REST et donnée stockée de l'ancienne version est mappé sur : conservé / changé (pourquoi) / supprimé (pourquoi). Rien de non listé ne part silencieusement.
3. Diff d'exports : après la reconstruction, régénérer les mêmes exports et les comparer à la base de référence. Les différences doivent être intentionnelles et listées.
4. Porte de régression visuelle : comparer les nouvelles captures d'écran à la base de référence pour chaque écran ; les différences inexpliquées bloquent la livraison (alimente fswp-qa-engineer).
5. Chemin des données : une mise à niveau à partir des données stockées de l'ancienne version doit fonctionner sans réactivation (voir fswp-qa-engineer).

Étape 5 : Documents de passation (constructions multi-sessions)

Lorsque la construction s'étend sur plusieurs sessions, écrire les deux fichiers dans la racine du dépôt du plugin (pas le zip) :

• AGENTS.md : ce que c'est ; commandes (build, test, porte QA) ; carte d'architecture ; règles et conventions de la maison ; décisions et contraintes ; pièges et zones interdites ; définition de "fini".
• HANDOFF.md : état actuel ; carte du code (fichier : responsabilité) ; tableau vérifié / non vérifié (chaque scénario du PRD avec RÉUSSI / ÉCHOUÉ / NON EXÉCUTÉ et preuve) ; éléments ouverts ; prochaine étape.

Mettre à jour les deux à chaque arrêt, et avant de terminer toute session qui n'a pas abouti.