Native-para-Flutter

Nativo → Flutter

Move um aplicativo nativo em produção para uma única base de código Flutter. Este skill funciona criando documentos primeiro, implementando com base neles, e só avança para a próxima etapa após aprovação de um revisor independente. A entrada é assumida como apenas a pasta de código-fonte nativo. Análises, PRDs, especificações e instruções são todas geradas pelo skill a cada etapa.

Por que fazer assim

• Ambos os apps estão em produção. Se um usuário existente perder login, pagamento ou dados salvos após a migração, é uma falha. Portanto, "nenhum usuário de qualquer SO perde funcionalidades" tem precedência sobre qualquer outra decisão.
• O original é a única verdade. Valores baseados em memória ou suposição sempre estarão errados em dispositivos reais. Todos os números, strings, APIs e comportamentos devem ser referenciados ao arquivo e linha originais (arquivo:linha). Se não houver referência, escreva (estimado).
• Documentos acordados primeiro permitem implementação paralela. Vários agentes de módulo só podem trabalhar simultaneamente se as especificações que cada um lerá estiverem finalizadas. Especificações instáveis causam retrabalho (já houve caso de refazer toda a tela duas vezes: uma para funcionalidade, outra para UI -> este skill cria a especificação de design antes da implementação).
• Separação entre escritor e revisor. Não confiamos no relatório de quem implementou; um revisor em outro contexto compara o código diretamente com a especificação e só aprova o avanço.

Modos de Entrada

No início, o modo é definido. A estrutura das etapas é a mesma, mas o trabalho dentro de cada etapa varia. As diferenças por modo estão na seção "Por Modo" de cada arquivo de referência.

Modo	Entrada	Diferença Principal
BOTH	Projeto iOS + Projeto Android	Encontra diferenças de negócio e UI entre os SOs e decide uma solução. Define o SO de referência para UI e gerencia exceções. Ambos os SOs são alvo de migração de usuários existentes
IOS_ONLY	Apenas projeto iOS	Sem diferenças entre SOs. Em vez disso, projeta "lacunas de nova plataforma" (botão voltar, permissões em tempo de execução, canais de notificação, barra do sistema, ID do app/assinatura/loja) para Android, agora nova plataforma
ANDROID_ONLY	Apenas projeto Android	O oposto. Para iOS como nova plataforma, projeta textos de permissão do Info.plist, APNs/entitlements, gesto de voltar, assinatura/perfil/App Store

Mesmo no modo de SO único, as plataformas alvo do Flutter resultante (apenas o SO original / ambos os SOs) são perguntadas separadamente.

Papéis

Papel	Quem	O que faz
Orquestrador	Esta sessão (eu)	Avança as etapas, instrui e consolida agentes, modifica arquivos comuns, testa e compila tudo, reporta ao usuário
Agente de escrita/implementação	Subagentes (model: opus padrão, ou o modelo especificado pelo usuário)	Escreve análises, documentos e código dentro do escopo atribuído
Revisor	Subagente model: fable padrão (contexto independente). Se o usuário conectar um modelo externo (GPT, Gemini, etc.), esse modelo	Compara documentos e código diretamente com o original e a especificação, aprova ou solicita correções
Usuário	Tomador de decisão	Escolhe políticas e UX, testa em dispositivos reais, gerencia contas, chaves e lojas

Regras de coautoria e revisão (log de acréscimos apenas, aprovação apenas com nome próprio, ambas as aprovações na mesma revisão, transição de revisor) estão em references/collaboration.md. Ao trabalhar com modelos externos, o usuário transmite as mensagens, então a comunicação é baseada em arquivos de log.

Mapa das Etapas

Cada etapa produz artefatos e só avança para a próxima após passar pelo portão. Ao entrar em uma etapa, leia o arquivo de referência correspondente.

#	Etapa	Artefatos (em <ws>/docs/)	Portão	Arquivo a ler
0	Início e verificação de ambiente	00-kickoff.md (modo, plataformas alvo, arquitetura, princípios, lista de decisões pendentes)	Confirmação do usuário	references/00-kickoff.md
1	Análise do original	analysis/<os>_analysis.md, analysis/api_inventory.md, analysis/screen_inventory.md, (BOTH) analysis/business_diff.md / (SO único) analysis/new_platform_gaps.md	Aprovação do revisor	references/01-analysis.md
2	PRD	prd.md (tabela de decisões D-número, contratos de API, requisitos de tela/funcionalidade, migração/segurança, etapas/portões, cenários de aceitação) + logs/prd_log.md	Revisor e eu declaramos a mesma revisão completa + decisões do usuário refletidas	references/02-prd.md
3	Inventário de UI e Especificação de Design	design/<os>_ui_inventory.md, design_spec.md (tokens, componentes, assets, strings, por tela, exceções de plataforma, lista de verificação em dispositivo real), decisions.md (U-número) + logs/design_log.md	Aprovação bilateral por tela	references/03-design-spec.md
4	Instrução de Implementação	impl_plan.md (convenções de arquitetura, IDs de trabalho por fase/módulo/camada, tabela de referência cruzada)	Aprovação do revisor, zero omissões	references/04-impl-plan.md
5	Base comum e POC de plataforma	Projeto Flutter, flavor/env, core (rede, erro, MVI, sistema de design, strings, assets, roteador), adaptadores/plugins de plataforma	POC em dispositivo real aprovado	references/05-build.md
6	Implementação por módulo	Para cada módulo: data → domain → presentation → test, logs/impl_log.md	Aprovação do revisor para cada módulo	references/05-build.md
7	Testes de integração e correções	Todos os testes passam, portão de cobertura, compilação bem-sucedida	Zero falhas	references/05-build.md
8	Loop de QA em dispositivo real	qa_device_checklist.md, feedback do usuário → decisão U → correção → sincronização de documentos	Usuário diz "concluído"	references/06-device-qa.md
9	Assinatura e distribuição	Assinatura, perfis, Firebase, CI, release_runbook.md (novo SO: novo registro)	SO original: mesmo ID do app, certificado, versão superior / Novo SO: nova assinatura, upload possível	references/07-release.md
10	Documentação de manutenção	<flutter>/docs/01~07, README.md	Aprovação do revisor	references/08-maintenance-docs.md

Se o usuário solicitar pular uma etapa (ex.: "a análise já está pronta, comece pelo PRD"), verifique se os artefatos da etapa anterior existem. Se não, informe o que está faltando e prossiga conforme o usuário decidir. Solicitações para ajustar um app Flutter já implementado à UI original seguem o "caminho alternativo" em references/05-build.md.

Princípios a Seguir

Estes princípios devem ser copiados para o início de cada documento de etapa para que todos os agentes julguem com os mesmos critérios.

1. Proibido bloquear usuários existentes. Se uma decisão impede que usuários de um SO possam fazer login, pagar ou usar seus ativos, essa decisão está errada. Validações que tocam dados existentes (ex.: formato de login) devem ser flexíveis; novas políticas de entrada devem seguir o servidor.
2. Sem alterações no servidor como premissa básica. Salvo instrução específica, resolva dentro dos contratos de API atuais. Melhorias que exigem servidor devem ser separadas como "issues em aberto".
3. Não reproduza defeitos. Não carregue bugs originais por "paridade". Defina o resultado esperado e fixe-o com testes de regressão. Se o resultado visível ao usuário mudar, coloque na lista de decisões e confirme com o usuário.
4. SO de referência para UI (BOTH, durante a migração). Se o visual divergir, use o valor do SO de referência. Pergunte ao usuário qual SO será a referência; não defina um padrão. Este princípio é um critério de julgamento durante a migração do original. Quando a migração terminar, a regra muda para "o comportamento atual do Flutter é a referência; alterações dependem de decisão do usuário" (etapa 10). Exceções são apenas três tipos: (a) seguir o SO de referência quebra funcionalidades para usuários do outro SO ou quebra comportamento específico da plataforma, (b) o comportamento do SO de referência conflita com decisões do PRD, (c) o valor do SO de referência é claramente um bug (mantenha o visual, corrija apenas o comportamento).
5. Evidência obrigatória. Referência arquivo:linha do original. Valores sem evidência: (estimado), valores que precisam ser medidos em dispositivo real: (dispositivo real), valores novos não encontrados no original: (nova definição).
6. Não introduza o que não estava no original. Não adicione SDKs externos, serviços externos ou configurações extras (ex.: SDK de segurança comercial, endereço de e-mail de notificação) só porque "parece melhor". Migre primeiro a abordagem original; se quiser mudar, pergunte ao usuário com a justificativa.
7. Não remova textos ou funcionalidades visíveis arbitrariamente. Mesmo que um texto informativo do original pareça incorreto em relação ao comportamento real, não o remova; pergunte ao usuário (manter o texto ou ajustar o comportamento ao texto).
8. Decisões devem ser registradas com ID. Decisão de PRD D-n, decisão de UX do usuário U-n. Se uma decisão mudar, atualize código, testes, especificações e o registro de decisão simultaneamente. Ao final de cada rodada de trabalho, sincronize a documentação com o código.
9. Não exiba valores secretos. Senhas de keystore, segredos de API, etc., devem ser transferidos apenas por arquivo, sem aparecer em diálogos ou logs. A política de commit no repositório segue a decisão do usuário (references/07-release.md).

Regras de Operação de Agentes

• Propriedade de escopo. O agente de módulo só modifica sua própria pasta de módulo. Se precisar de arquivos comuns (core, app, dependências, assets, strings), não os modifica diretamente; em vez disso, registra na seção "Solicitações Comuns" do relatório final. O orquestrador coleta e aplica tudo de uma vez. É a maneira mais barata de evitar conflitos durante o trabalho paralelo.
• Momento dos testes. Ao processar módulos sequencialmente, o agente executa os testes do seu módulo. Ao processar vários módulos em ondas paralelas, o agente só garante que dart analyze passe em sua pasta; o flutter test completo e a compilação são executados pelo orquestrador após o fim da onda. Múltiplos agentes usando o mesmo build/ simultaneamente quebram as ferramentas.
• Revisor não confia em relatórios. Instrução de revisão deve incluir: "compare o código e a especificação diretamente, em vez do relatório do agente de implementação". O revisor não modifica código.
• Relatórios curtos. O relatório final do agente tem limite de linhas (modelos em templates/). Conteúdo longo deve ser escrito em arquivos de log.
• Execução paralela. Análises, módulos e tarefas de documentação independentes podem ser disparados com várias chamadas de agente simultâneas. O fato de este skill ter sido chamado já constitui concordância com o progresso multiagente; portanto, ondas grandes podem usar ferramentas de Workflow (pipeline de escrita → revisão → correção). Informe o tamanho da onda e o modelo ao usuário em uma linha antes de começar.
• Retomada. Cada arquivo de log tem uma tabela de progresso no topo, sempre atualizada. Se a sessão for interrompida, leia apenas 00-kickoff.md e a tabela de progresso de cada log para continuar.

Quando Perguntar ao Usuário

Eu não decido o seguinte. Apresente opções e recomendações curtas com justificativa e aguarde resposta.

• Lista de perguntas iniciais (references/00-kickoff.md)
• Diferenças de negócio que alteram o resultado visível ao usuário ou que exigem confirmação do servidor
• SO de referência para UI e exceções que mudam significativamente funcionalidade ou visual
• Introdução de bibliotecas ou serviços não presentes no original, remoção de funcionalidades ou textos originais
• Tarefas que exigem contas (Apple Developer, Play Console, Firebase Console), localização de valores secretos
• Política de commit no repositório, se o repositório remoto será público

Se o usuário disser "faça como recomendado", registre a recomendação como decisão (U-número) e prossiga.

Relatório de Fim de Etapa

Ao final de cada etapa, reporte apenas o seguinte ao usuário: documentos criados (caminhos), resultado da revisão (número de apontamentos, acatados, rejeitados e motivos), itens que precisam de decisão do usuário (incluindo recomendações), e a próxima etapa. Se algo não foi verificado, escreva que não foi verificado.

Arquivos de Referência

Arquivo	Quando usar
references/00-kickoff.md	No início
references/01-analysis.md	Análise original
references/02-prd.md	Escrita e acordo do PRD
references/03-design-spec.md	Inventário de UI e especificação de design
references/04-impl-plan.md	Instrução de implementação
references/05-build.md	Base comum, implementação de módulo, testes de integração
references/06-device-qa.md	Loop de QA em dispositivo real
references/07-release.md	Assinatura, flavor, Firebase, CI, lançamento
references/08-maintenance-docs.md	Documentação de manutenção
references/collaboration.md	Regras de coautoria, revisão e transição
references/pitfalls.md	Problemas reais de migração e prevenção — use após etapa 5, sempre que necessário
templates/*.md	Modelos de instrução de agente, instrução de revisão e formato de relatório