ParkGiTeak/native-to-flutter

Conversión Nativa → Flutter

Convierte una aplicación nativa en producción a una única base de código Flutter. Esta habilidad sigue un proceso de documentación primero, implementación basada en la documentación, y solo avanza al siguiente paso con la aprobación de un revisor independiente. Se asume que la entrada es solo la carpeta de código fuente nativo. Los documentos de análisis, PRD, especificaciones e instrucciones son creados por esta habilidad en cada paso.

Por qué se hace así

• Ambas aplicaciones están en producción. Si los usuarios existentes pierden inicio de sesión, pagos o datos guardados después de la actualización, la migración falla. Por eso, "ningún usuario de ningún SO pierde funcionalidad" es la prioridad sobre todas las decisiones.
• El original es la única verdad. Los valores basados en memoria o suposiciones siempre son incorrectos en un dispositivo real. Todos los valores numéricos, cadenas, API y comportamientos deben incluir una referencia al archivo:línea original. Si no hay referencia, se escribe (estimado).
• Los documentos deben acordarse primero para permitir la implementación en paralelo. Para que varios agentes de módulos trabajen simultáneamente, deben tener especificaciones definitivas para leer. Si las especificaciones cambian, una misma pantalla se corrige dos veces (de hecho, hay casos en los que se modificó toda la pantalla dos veces para ajustar la UI después de implementar la funcionalidad → esta habilidad crea las especificaciones de diseño antes de la implementación).
• Se separa al autor del revisor. No se confía en el informe del implementador; un revisor de otro contexto debe comparar directamente el código con las especificaciones y aprobar antes de continuar.

Modos de entrada

Al iniciar, se define el modo. La estructura de pasos es la misma, pero las tareas dentro de cada paso varían. Las diferencias por modo se encuentran en la sección "Por modo" de cada archivo de referencia.

Modo	Entrada	Diferencia clave
AMBOS	Proyecto iOS + Proyecto Android	Se identifican las diferencias de negocio y UI entre SOs para unificarlas. Se define el SO de referencia para la UI y se gestionan las excepciones. Ambos SOs son destino de migración de usuarios existentes
SOLO_IOS	Solo proyecto iOS	No hay determinación de diferencias. En cambio, si se va a dar soporte a Android por primera vez, se diseñan las "brechas de nueva plataforma" (botón atrás, permisos en tiempo de ejecución, canales de notificación, barra del sistema, ID de aplicación, firma, registro en tienda, etc.)
SOLO_ANDROID	Solo proyecto Android	Lo contrario. Si se va a dar soporte a iOS por primera vez, se diseñan los textos de permisos Info.plist, APNs/entitlements, deslizar hacia atrás, firma, perfil y registro en App Store

Incluso en modo de un solo SO, se pregunta por separado la plataforma de destino del resultado Flutter (solo el SO original / ambos SOs).

Roles

Rol	Quién	Qué hace
Orquestador	Esta sesión (yo)	Avanza los pasos, instruye y consolida agentes, modifica archivos comunes, realiza pruebas y compilación completa, informa al usuario
Agente de escritura/implementación	Subagente (por defecto model: opus, o el modelo especificado por el usuario)	Escribe análisis, documentación y código en su ámbito asignado
Revisor	Subagente por defecto model: fable (contexto independiente). Si el usuario conecta un modelo externo (GPT, Gemini, etc.), ese modelo	Compara directamente la documentación y el código con el original y las especificaciones, y solicita aprobación o correcciones
Usuario	Tomador de decisiones	Decide políticas y opciones de UX, verifica en dispositivos reales, gestiona cuentas, claves y tiendas

Las reglas de colaboración y revisión (registro solo de adiciones, aprobación solo con nombre propio, aprobación de ambas partes en la misma revisión, traspaso entre revisores) están en references/collaboration.md. Cuando se trabaja con modelos externos, el usuario transmite los mensajes, por lo que la conversación se realiza mediante registros basados en archivos.

Mapa de pasos

Cada paso crea un entregable y debe pasar una puerta para avanzar al siguiente. Al entrar en un paso, se lee el archivo de referencia correspondiente.

#	Paso	Entregable (bajo <ws>/docs/)	Puerta	Archivo a leer
0	Inicio y verificación del entorno	00-kickoff.md (modo, plataforma destino, arquitectura, principios, lista de decisiones pendientes)	Confirmación del usuario	references/00-kickoff.md
1	Análisis original	analysis/<os>_analysis.md, analysis/api_inventory.md, analysis/screen_inventory.md, (AMBOS) analysis/business_diff.md / (un solo SO) analysis/new_platform_gaps.md	Aprobación del revisor	references/01-analysis.md
2	PRD	prd.md (tabla de decisiones D-número, contratos de API, requisitos de pantallas y funcionalidades, migración y seguridad, pasos y puertas, escenarios de aceptación) + logs/prd_log.md	Declaración de finalización de la misma revisión por parte del revisor y de mí + reflejo de las decisiones del usuario	references/02-prd.md
3	Inventario de UI y especificaciones de diseño	design/<os>_ui_inventory.md, design_spec.md (tokens, componentes, assets, cadenas, por pantalla, excepciones de plataforma, lista de verificación en dispositivo real), decisions.md (U-número) + logs/design_log.md	Aprobación de ambas partes por pantalla	references/03-design-spec.md
4	Instrucciones de implementación	impl_plan.md (convenciones de arquitectura, ID de tarea por fase/módulo/capa, tabla de referencias cruzadas)	Aprobación del revisor, 0 omisiones	references/04-impl-plan.md
5	Base común y POC de plataforma	Proyecto Flutter, flavor/env, core (red, errores, MVI, sistema de diseño, cadenas, assets, enrutador), adaptadores de plataforma y plugins	POC superado en dispositivo real	references/05-build.md
6	Implementación por módulos	Por módulo: data→domain→presentation→test, logs/impl_log.md	Aprobación del revisor por módulo	references/05-build.md
7	Pruebas de integración y correcciones	Todas las pruebas pasan, puerta de cobertura, compilación	0 fallos	references/05-build.md
8	Bucle de QA en dispositivo real	qa_device_checklist.md, feedback del usuario → decisión U → corrección → sincronización de documentos	Usuario "completado"	references/06-device-qa.md
9	Firma y distribución	Firma, perfil, Firebase, CI, release_runbook.md (nuevo registro si es nuevo SO)	SO original: mismo ID de app, certificado, versión superior / Nuevo SO: nueva firma, posibilidad de subida	references/07-release.md
10	Documentación de mantenimiento	<flutter>/docs/01~07, README.md	Aprobación del revisor	references/08-maintenance-docs.md

Si el usuario solicita saltarse un paso (ej. "ya está el análisis, empezar desde el PRD"), se verifica si existen los entregables del paso anterior. Si no existen, se informa qué falta y se procede según lo que decida el usuario. Las solicitudes de ajustar una app Flutter ya implementada a la UI original siguen la "ruta variante" en references/05-build.md.

Principios a seguir

Estos principios se copian al principio de cada documento de paso para que los agentes juzguen con el mismo criterio.

1. No bloquear a usuarios existentes. Si una decisión impide que los usuarios de un SO inicien sesión, realicen pagos o usen sus activos, esa decisión es incorrecta. Las validaciones que tocan datos existentes (ej. verificación de formato de inicio de sesión) deben ser flexibles; las políticas de entrada nuevas deben coincidir con el servidor.
2. Sin cambios en el servidor como premisa por defecto. A menos que se indique lo contrario, resolver dentro del contrato de API actual. Las mejoras que requieran servidor se separan como "problemas abiertos".
3. No reproducir defectos. No trasladar bugs originales por motivos de "equivalencia". Determinar el resultado esperado y fijarlo con pruebas de regresión. Sin embargo, si el resultado visible para el usuario cambia, se incluye en la lista de decisiones para confirmar con el usuario.
4. SO de referencia para la UI (AMBOS, limitado al periodo de transición). Si los aspectos visuales difieren, se usa el valor del SO de referencia. Se pregunta al usuario qué SO usar como referencia, sin establecer un valor por defecto. Este principio es el criterio de juicio durante la migración del original. Una vez finalizada la transición, cambia a "el comportamiento actual de Flutter es la referencia, los cambios son decisión del usuario" (paso 10). Solo tres tipos de excepciones: (a) si seguir el SO de referencia impide que los usuarios del otro SO usen una funcionalidad o rompe un comportamiento nativo de la plataforma, (b) si el comportamiento del SO de referencia entra en conflicto con una decisión del PRD, (c) si el valor del SO de referencia es un bug evidente (se mantiene el aspecto visual, solo se corrige el comportamiento).
5. Referencia obligatoria. archivo:línea del original. Los valores sin referencia se marcan como (estimado), los valores que deben medirse en un dispositivo real como (dispositivo real), y los valores nuevos que no están en el original como (nueva definición).
6. No introducir nada que no estuviera en el original. No añadir SDKs externos, servicios externos o valores de configuración adicionales (ej. SDK de seguridad comercial, dirección de correo de notificación) solo porque "parezcan mejores". Primero移植 la forma original; si se quiere cambiar, preguntar al usuario con la razón.
7. No eliminar textos o funcionalidades visibles arbitrariamente. Aunque un texto informativo original parezca no coincidir con el comportamiento real, no eliminarlo; preguntar al usuario (si mantener el texto o ajustar el comportamiento al texto).
8. Las decisiones se registran con ID. Decisiones de PRD como D-n, decisiones de UX del usuario como U-n. Si una decisión cambia, se actualizan simultáneamente el código, las pruebas, las especificaciones y el registro de decisiones. Al final de cada ronda de trabajo, se sincronizan los documentos con el código.
9. No mostrar valores secretos. Contraseñas de keystore, secretos de API, etc., solo se transfieren mediante archivos; no se imprimen en conversaciones o registros. Los archivos que se confirman en el repositorio siguen la política del usuario (references/07-release.md).

Reglas de operación de agentes

• Propiedad del ámbito. El agente de módulo solo modifica su propia carpeta de módulo. Si necesita archivos comunes (core, app, dependencias, assets, cadenas), no los modifica directamente, sino que los incluye en "solicitudes comunes" de su informe final. El orquestador los recoge y los aplica de una vez. Es la forma más barata de evitar conflictos durante el trabajo paralelo.
• Momento de las pruebas. Cuando los módulos se procesan secuencialmente uno por uno, el agente ejecuta las pruebas de su propio módulo. Cuando se procesan varios módulos en oleadas paralelas, el agente solo pasa dart analyze en su carpeta; las pruebas flutter test completas y la compilación las realiza el orquestador una vez finalizada la oleada. Varios agentes usando el mismo build/ simultáneamente rompen la herramienta.
• El revisor no confía en los informes. En las instrucciones de revisión se incluye "comparar directamente el código y las especificaciones en lugar del informe del agente de trabajo". El revisor no modifica el código.
• Informes breves. Los informes finales de los agentes tienen un límite de líneas (la plantilla está en templates/). El contenido extenso se escribe en archivos de registro.
• Ejecución paralela. Los trabajos de análisis, módulos y documentos independientes se lanzan con múltiples llamadas a Agent a la vez. El hecho de que se haya invocado esta habilidad constituye el consentimiento para el progreso multiagente; si la oleada es grande, se puede usar una herramienta de Workflow (tubería de escritura → revisión → corrección). El tamaño de la oleada y el modelo se comunican al usuario en una línea antes de comenzar.
• Reanudación. Al principio de cada archivo de registro se coloca una tabla de estado de progreso, siempre actualizada. Si la sesión se interrumpe, solo se lee 00-kickoff.md y la tabla de estado de progreso de cada registro para continuar.

Cuándo preguntar al usuario

Lo siguiente no lo decido yo. Se presentan opciones y una recomendación con fundamentos de forma breve, y se espera respuesta.

• Lista de preguntas iniciales (references/00-kickoff.md)
• Diferencias de negocio que afecten el resultado visible para el usuario o requieran verificación del servidor
• SO de referencia para la UI y sus excepciones que cambien significativamente funcionalidad o aspecto visual
• Introducción de librerías o servicios no presentes en el original, eliminación de funcionalidades o textos originales
• Trabajos que requieran cuentas (Apple Developer, Play Console, consola de Firebase), ubicación de valores secretos
• Política de confirmación en el repositorio, si el repositorio remoto es público o no

Si el usuario dice "hazlo como recomiendas", se registra la recomendación como decisión (U-número) y se procede.

Informe de finalización de paso

Al finalizar cada paso, se informa brevemente al usuario solo de lo siguiente: documentos creados (ruta), resultados de la revisión (número de observaciones, reflejadas, rechazadas y motivo), elementos que requieren decisión del usuario (incluyendo recomendaciones), y siguiente paso. Si algo no se ha verificado, se indica que no se ha verificado.

Archivos de referencia

Archivo	Cuándo
references/00-kickoff.md	Al inicio
references/01-analysis.md	Análisis original
references/02-prd.md	Redacción y acuerdo del PRD
references/03-design-spec.md	Inventario de UI y especificaciones de diseño
references/04-impl-plan.md	Instrucciones de implementación
references/05-build.md	Base común, implementación de módulos y pruebas de integración
references/06-device-qa.md	Bucle de QA en dispositivo real
references/07-release.md	Firma, flavor, Firebase, CI, lanzamiento
references/08-maintenance-docs.md	Documentación de mantenimiento
references/collaboration.md	Reglas de escritura colaborativa, revisión y traspaso
references/pitfalls.md	Problemas reales en la migración y cómo evitarlos — consultar con frecuencia a partir del paso 5
templates/*.md	Formato de instrucciones para agentes, instrucciones de revisión e informes