ParkGiTeak/native-to-flutter

Conversion native → Flutter

Convertit une application native en production en une base de code Flutter unique. Cette compétence fonctionne selon le principe suivant : rédiger d'abord les documents, implémenter sur la base de ces documents, et ne passer à l'étape suivante qu'après approbation par un réviseur indépendant. L'entrée est supposée être uniquement le dossier source natif. Les analyses, PRD, spécifications et instructions sont toutes créées par cette compétence à chaque étape.

Pourquoi cette approche

• Les deux applications sont en production. Si un utilisateur existant, après la mise à jour, perd l'accès à la connexion, aux paiements ou à ses données, c'est un échec. Par conséquent, « aucun utilisateur d'un OS ne doit perdre de fonctionnalité » prime sur toute autre décision.
• L'original est la seule source de vérité. Les valeurs écrites de mémoire ou par supposition seront nécessairement erronées sur un appareil réel. Chaque valeur, chaîne, API et comportement doit avoir une référence fichier:ligne dans l'original. En l'absence de preuve, la mention (estimé) est utilisée.
• Les documents doivent être approuvés d'abord pour permettre une implémentation parallèle. Plusieurs agents modulaires peuvent travailler simultanément seulement si les spécifications qu'ils lisent sont finalisées. Si les spécifications changent, le même écran sera corrigé deux fois (un cas réel où l'UI a dû être reprise entièrement après l'implémentation des fonctionnalités). Cette compétence crée donc les spécifications de design avant l'implémentation.
• Séparation entre l'auteur et le relecteur. On ne se fie pas au rapport de l'implémenteur. Un réviseur, dans un contexte différent, doit comparer directement le code et les spécifications et les approuver avant de passer à l'étape suivante.

Modes d'entrée

Au démarrage, le mode est déterminé. La structure des étapes est identique, mais les tâches à l'intérieur de chaque étape diffèrent. Les différences entre les modes sont détaillées dans la section « Par mode » de chaque fichier de référence.

Mode	Entrée	Différence clé
BOTH	Projet iOS + Projet Android	Trouver les différences métier et UI entre les OS et les unifier. Définir l'OS de référence pour l'UI et gérer les exceptions. Les utilisateurs existants des deux OS sont à migrer
IOS_ONLY	Projet iOS uniquement	Pas de décision de différence. Cependant, si Android est nouveau, il faut concevoir les « lacunes de la nouvelle plateforme » (bouton retour, permissions runtime, canaux de notification, barre système, ID d'application, signature, nouveau store)
ANDROID_ONLY	Projet Android uniquement	L'inverse ci-dessus. Si iOS est nouveau, il faut concevoir les textes de permission Info.plist, APNs/entitlements, retour par balayage, signature, profil et nouveau dépôt App Store

Même en mode mono-OS, le ou les plateformes cibles du livrable Flutter (OS d'origine uniquement / les deux OS) sont demandées séparément.

Rôles

Rôle	Qui	Fait quoi
Orchestrateur	Cette session (moi)	Avancement des étapes, instructions aux agents et consolidation, modification des fichiers communs, tests et builds globaux, rapport à l'utilisateur
Agent rédacteur/implémenteur	Sous-agent (par défaut model: opus, ou le modèle spécifié par l'utilisateur)	Analyse, rédaction de documents et de code dans son périmètre
Réviseur	Sous-agent model: fable par défaut (contexte indépendant). Si l'utilisateur ajoute un modèle externe (GPT, Gemini, etc.), ce modèle	Approuve ou demande des corrections en comparant directement le document/code avec l'original et les spécifications
Utilisateur	Décideur	Choix politiques et UX, validation sur appareil réel, comptes, clés et opérations store

Les règles de révision et de rédaction collaborative (journal d'ajouts uniquement, approbation uniquement sous son propre nom, approbation des deux côtés sur la même révision, passation entre réviseurs) se trouvent dans references/collaboration.md. Lorsqu'on travaille avec des modèles externes, l'utilisateur transmet les messages ; on communique donc via des fichiers journaux.

Carte des étapes

Chaque étape produit un livrable et doit passer une porte (gate) pour passer à l'étape suivante. Au début de chaque étape, le fichier de référence correspondant est lu.

#	Étape	Livrables (sous <ws>/docs/)	Porte	Fichier à lire
0	Lancement et vérification de l'environnement	00-kickoff.md (mode, plateformes cibles, architecture, principes, liste des décisions en attente)	Validation utilisateur	references/00-kickoff.md
1	Analyse du code source	analysis/<os>_analysis.md, analysis/api_inventory.md, analysis/screen_inventory.md, (BOTH) analysis/business_diff.md / (mono-OS) analysis/new_platform_gaps.md	Approbation du réviseur	references/01-analysis.md
2	PRD	prd.md (tableau de décisions D-xxx, contrats API, exigences écrans/fonctionnalités, migration/sécurité, étapes/portes, scénarios de recette) + logs/prd_log.md	Déclaration de complétion de la même révision par le réviseur et moi + prise en compte des décisions utilisateur	references/02-prd.md
3	Inventaire UI et spécification de design	design/<os>_ui_inventory.md, design_spec.md (jetons/composants/ressources/chaînes/par écran/exceptions plateforme/liste de validation sur appareil réel), decisions.md (U-xxx) + logs/design_log.md	Approbation des deux côtés pour chaque écran	references/03-design-spec.md
4	Plan d'implémentation	impl_plan.md (conventions d'architecture, IDs de tâches par Phase/module/couche, table de références croisées)	Approbation du réviseur, zéro omission	references/04-impl-plan.md
5	Base commune et POC plateforme	Projet Flutter, flavor/env, core (réseau/erreurs/MVI/système de design/chaînes/ressources/routeur), adaptateurs et plugins plateforme	POC réussi sur appareil réel	references/05-build.md
6	Implémentation par module	Pour chaque module : data→domain→presentation→test, logs/impl_log.md	Approbation du réviseur pour chaque module	references/05-build.md
7	Tests d'intégration et corrections	Tous les tests passent, portes de couverture, build	0 échec	references/05-build.md
8	Boucle QA sur appareil réel	qa_device_checklist.md, retours utilisateur → décision U → correction → synchronisation des documents	L'utilisateur dit « terminé »	references/06-device-qa.md
9	Signature et déploiement	Signature/profil/Firebase/CI/release_runbook.md (nouvel OS = nouveau dépôt)	OS d'origine : même ID d'appli, mêmes certificats, version supérieure / Nouvel OS : nouvelle signature, upload possible	references/07-release.md
10	Documentation de maintenance	<flutter>/docs/01~07, README.md	Approbation du réviseur	references/08-maintenance-docs.md

Si l'utilisateur demande de sauter une étape (ex. « l'analyse est faite, commence par le PRD »), vérifier si les livrables de l'étape précédente existent. Si non, signaler ce qui manque, puis continuer selon la décision de l'utilisateur. Si l'utilisateur demande d'ajuster l'UI d'une app Flutter déjà implémentée pour qu'elle corresponde à l'originale, suivre le « chemin variante » dans references/05-build.md.

Principes à respecter

Ces principes doivent être recopiés en tête de chaque document d'étape pour que tous les agents jugent sur la même base.

1. Ne pas bloquer les utilisateurs existants. Si une seule décision empêche les utilisateurs d'un OS de se connecter, de payer ou d'utiliser leurs données, cette décision est erronée. Les validations qui touchent aux données existantes (ex. validation du format de connexion) doivent être souples ; les nouvelles politiques de saisie doivent être alignées sur le serveur.
2. Aucune modification serveur par défaut. Sauf instruction contraire, résoudre dans le cadre du contrat API actuel. Les améliorations nécessitant le serveur sont séparées en « issues ouverts ».
3. Ne pas reproduire les défauts. Ne pas reporter les bugs de l'original sous prétexte d'« équivalence ». Déterminer le comportement attendu et le figer avec un test de régression. Si le résultat visible pour l'utilisateur change, le mettre sur la liste des décisions pour validation utilisateur.
4. OS de référence pour l'UI (BOTH, limité à la période de conversion). Si le visuel diffère, utiliser les valeurs de l'OS de référence. Demander à l'utilisateur quel OS utiliser comme référence, sans valeur par défaut. Ce principe est un guide pour la période de conversion. Une fois la conversion terminée, « le comportement Flutter actuel est la référence, les changements sont décidés par l'utilisateur » (étape 10). Seules trois exceptions : (a) suivre l'OS de référence empêche les utilisateurs de l'autre OS d'utiliser une fonctionnalité ou casse un comportement natif, (b) le comportement de l'OS de référence entre en conflit avec une décision du PRD, (c) la valeur de l'OS de référence est un bug évident (le visuel est conservé, seul le comportement est corrigé).
5. Référence obligatoire. fichier:ligne de l'original. Valeur sans preuve : (estimé), valeur à mesurer sur appareil réel : (appareil réel), valeur nouvelle sans équivalent dans l'original : (nouvelle définition).
6. Ne pas introduire ce qui n'existe pas dans l'original. Ne pas ajouter de SDK externe, service externe ou valeur de configuration supplémentaire (ex. SDK de sécurité commercial, adresse e-mail de notification) parce que « c'est mieux ». Importer d'abord la méthode originale ; si on veut la changer, le proposer à l'utilisateur avec justification.
7. Ne pas supprimer arbitrairement des textes ou fonctionnalités visibles. Si un texte d'instruction original semble en décalage avec le comportement réel, ne pas le supprimer mais demander à l'utilisateur (conserver le texte ou aligner le comportement sur le texte ?).
8. Enregistrer les décisions avec un ID. Décision PRD D-n, décision UX utilisateur U-n. Si une décision change, mettre à jour simultanément le code, les tests, les spécifications et l'historique des décisions. À la fin de chaque cycle de travail, synchroniser les documents avec le code.
9. Ne pas afficher les secrets. Mot de passe du keystore, clé secrète API, etc., ne sont transmis que par fichier et ne doivent pas apparaître dans les conversations ou les journaux. Les fichiers à commiter dans le dépôt suivent la politique utilisateur (references/07-release.md).

Règles d'exploitation des agents

• Propriété du périmètre. L'agent module ne modifie que son dossier de module. S'il a besoin de fichiers communs (core, app, dépendances, ressources, chaînes), il ne les modifie pas directement mais les mentionne dans sa « demande commune » de son rapport final. L'orchestrateur les rassemble et les applique en une fois. C'est la méthode la moins coûteuse pour éviter les conflits en parallèle.
• Moment des tests. En mode séquentiel module par module, l'agent exécute également les tests de son module. En mode vague parallèle de plusieurs modules, l'agent ne fait passer que dart analyze dans son dossier ; les flutter test et le build globaux sont exécutés par l'orchestrateur après la vague. Plusieurs agents écrivant simultanément dans le même dossier build/ cassent les outils.
• Le réviseur ne se fie pas aux rapports. L'instruction de révision doit contenir « compare directement le code et les spécifications, ne te fie pas au rapport de l'agent de tâche ». Le réviseur ne modifie pas le code.
• Rapports concis. Le rapport final de l'agent doit être limité en nombre de lignes (template dans templates/). Le contenu long est écrit dans les fichiers journaux.
• Exécution parallèle. Les tâches d'analyse, de module ou de documentation indépendantes sont lancées en plusieurs appels d'agent simultanément. Le fait que cette compétence soit invoquée constitue un accord pour le déroulement multi-agents. Si la vague est grande, on peut utiliser un outil Workflow (pipeline rédaction → révision → correction). La taille de la vague et le modèle sont annoncés à l'utilisateur en une ligne avant le début.
• Reprise. Un tableau d'état d'avancement est placé en haut de chaque fichier journal et toujours tenu à jour. Si la session est interrompue, on lit uniquement 00-kickoff.md et le tableau d'état de chaque journal pour reprendre.

Quand demander à l'utilisateur

Ce qui suit n'est pas décidé par moi. Présenter brièvement les options et une recommandation avec justification, puis attendre une réponse.

• Liste des questions de lancement (references/00-kickoff.md)
• Différences métier qui changent le résultat visible pour l'utilisateur ou qui nécessitent une confirmation serveur
• OS de référence pour l'UI et ses exceptions, surtout si la fonctionnalité ou l'aspect changent significativement
• Introduction d'une bibliothèque ou d'un service inexistant dans l'original, suppression d'une fonctionnalité ou d'un texte original
• Tâches nécessitant un compte (Apple Developer, Play Console, Firebase Console), emplacement des secrets
• Politique de commit dans le dépôt, caractère public du dépôt distant

Si l'utilisateur dit « fais comme recommandé », enregistrer la recommandation comme décision (U-xxx) et continuer.

Rapport de fin d'étape

À la fin de chaque étape, faire un rapport court à l'utilisateur contenant uniquement : les documents créés (chemin), le résultat de la révision (nombre de remarques, nombre acceptées/rejetées avec raisons), les éléments nécessitant une décision utilisateur (avec recommandations), et l'étape suivante. Si quelque chose n'a pas été vérifié, l'indiquer.

Fichiers de référence

Fichier	Quand
references/00-kickoff.md	Au lancement
references/01-analysis.md	Analyse du code source
references/02-prd.md	Rédaction et validation du PRD
references/03-design-spec.md	Inventaire UI et spécification de design
references/04-impl-plan.md	Plan d'implémentation
references/05-build.md	Base commune, implémentation modulaire, tests d'intégration
references/06-device-qa.md	Boucle QA sur appareil réel
references/07-release.md	Signature, flavor, Firebase, CI, release
references/08-maintenance-docs.md	Documentation de maintenance
references/collaboration.md	Règles de rédaction collaborative, révision et passation
references/pitfalls.md	Problèmes rencontrés lors de vraies conversions et prévention — consultable après l'étape 5
templates/*.md	Instructions aux agents, instructions de révision, format de rapport