Kappaemme-git/codex-phone-lab

Codex Phone Lab

Use esta habilidade para transformar um prompt de produto em um aplicativo React Native/Expo que o usuário pode abrir em um telefone físico com o Expo Go. Otimize para um ciclo rápido "prompt -> app -> telefone" antes de considerar simulador, builds nativas, TestFlight ou distribuição na loja de aplicativos.

Modelo de Operação

Prefira este caminho, a menos que o usuário explicitamente precise de módulos nativos iOS/Android:

1. Verifique os pré-requisitos locais com scripts/doctor.sh.
2. Se nenhum projeto móvel existir, crie um aplicativo Expo com scripts/new-expo-app.sh <nome-do-app>. Isso usa como padrão expo-template-default@sdk-54 para que abra na versão atual do Expo Go usada neste fluxo de trabalho.
3. Crie rapidamente a primeira tela utilizável; não crie uma página de destino.
4. Inicie a visualização no telefone com scripts/start-phone-preview.sh [lan|tunnel|local].
5. Mantenha o servidor de desenvolvimento em execução enquanto edita. Use os logs do Metro/Expo para corrigir erros de tempo de execução.
6. Diga ao usuário para instalar o Expo Go, escanear o QR e manter o telefone na mesma rede para o modo LAN.
7. Itere com pequenas mudanças visíveis: edite, observe os logs, recarregue, corrija.

Detecção de Projeto

Antes de criar um novo aplicativo, inspecione o diretório atual:

• package.json com dependência expo: trate como um aplicativo Expo existente.
• app.json, app.config.*, app/ ou expo-router: trate como aplicativo Expo mesmo que as dependências precisem ser instaladas.
• ios/ e android/ sem Expo: pergunte apenas se o usuário precisa de migração para Expo; caso contrário, mantenha a pilha existente.
• Diretório vazio: crie um novo aplicativo Expo com o template SDK 54.

Visualização no Telefone

Use o Expo Go para a primeira demonstração "uau" porque evita o atrito da App Store/TestFlight.

Use SDK 54 por padrão. O Expo Go atual neste fluxo de trabalho rejeita projetos SDK 55 com "Projeto é incompatível com esta versão do Expo Go". Substitua apenas quando o Expo Go do usuário for conhecido por suportar um SDK mais recente:

CODEX_PHONE_LAB_EXPO_TEMPLATE=expo-template-default@sdk-55 <diretorio-habilidade>/scripts/new-expo-app.sh my-app

Execute:

<diretorio-habilidade>/scripts/start-phone-preview.sh lan

Use tunnel quando o telefone não estiver na mesma rede Wi-Fi ou o modo LAN não puder conectar. O modo túnel pode pedir ao Expo para instalar uma dependência de tunelamento.

O fluxo de trabalho do usuário:

1. Instale o Expo Go no telefone.
2. Execute o comando de visualização.
3. Escaneie o código QR com o Expo Go ou a câmera do telefone.
4. Mantenha o terminal aberto; as edições no aplicativo são atualizadas ao vivo.

Orientações para Construir o Aplicativo

Faça a primeira tela parecer um aplicativo real:

• Use áreas seguras e layouts de tamanho móvel.
• Construa interação real: formulários, listas, navegação, alternadores, temporizadores, dados fictícios ou estado.
• Inclua estados de carregamento, vazio e erro quando o fluxo de trabalho os implicar.
• Mantenha a tipografia compacta o suficiente para dispositivos móveis.
• Evite padrões de página de destino da web, seções hero superdimensionadas, cartões aninhados e texto explicativo dentro do aplicativo.
• Prefira o Expo Router para aplicativos com várias telas quando o template já o incluir.

Decisão de Distribuição

Escolha a rota mais leve que corresponda ao objetivo do usuário:

• Protótipo rápido no telefone do usuário: QR do Expo Go.
• Aplicativo com módulos nativos personalizados: build de desenvolvimento Expo.
• Usuários beta no iPhone: TestFlight via EAS/conta de desenvolvedor Apple.
• Lançamento público: submissão à App Store / Play Store.

Não indique que o Expo Go é distribuição de produção. É uma visualização de desenvolvimento ao vivo.

Referências

Leia references/expo-phone-workflow.md ao decidir entre Expo Go, builds de desenvolvimento, TestFlight e lançamento na loja de aplicativos.