choism4/oh-my-demo

Oh My Demo

Grave o aplicativo real em uma única tomada. Pule a pós-produção.

Trate esta skill como uma camada de ensaio e configuração em torno do aplicativo hospedeiro, não como um gerador de aplicativos mock. Prepare o estado inicial, dicas para o operador, ritmo, fixtures declaradas e caminho de reset para que o usuário possa pressionar gravar e concluir o passo a passo sem precisar cortar falhas depois. Preserve a UI, navegação, comandos, estado local e lógica de negócio reais da produção. Substitua apenas o menor limite lento, caro, remoto, instável ou inacabado necessário para uma gravação confiável.

Fluxo padrão

Resolva SKILL_ROOT para o diretório que contém este arquivo e execute a CLI empacotada com python3 "$SKILL_ROOT/scripts/oh_my_demo.py".

1. Inspecione o repositório, seu harness de teste, fixtures existentes e o caminho exato visível ao usuário a ser gravado. Inspecione o status do git e diffs relevantes antes de alterar qualquer coisa.

2. Crie um branch dedicado ou worktree isolado. Nunca coloque a substituição de fixtures exclusivas de demonstração no branch de produção.

3. Inicialize o kit do projeto:

   python3 "$SKILL_ROOT/scripts/oh_my_demo.py" init . --name product-tour
   

4. Construa um livro-razão de verdade em .oh-my-demo/manifest.json. Classifique cada declaração como:

   • real: o aplicativo visível utiliza sua implementação de produção.
   • simulated: um limite declarado retorna dados de fixture determinísticos.
   • operator: assistência de gravação como preenchimento de texto, ritmo ou reset; não inclua essas conveniências no percentual de verdade.

5. Mantenha a parcela real ponderada em ou acima de 80%. Reduza a declaração ou implemente mais do caminho real quando uma funcionalidade principal simulada ultrapassaria o orçamento. Não manipule pesos para ocultar isso.

6. Inventarie cada entrada, referência, fixture, resultado e linha de base. Copie recursos de demonstração sob .oh-my-demo/ ou outra raiz do manifesto em vez de vincular a caminhos absolutos específicos da máquina de um operador. Para mídias grandes, escolha Git LFS ou um pacote de artefato autenticado com checksum e materialize-o localmente antes da verificação pré-voo.

7. Dê aos controles visíveis alvos semânticos estáveis. Prefira IDs de acessibilidade, IDs de teste ou um registro hospedeiro em vez de seletores CSS gerados ou coordenadas.

8. Adicione apenas o menor adaptador hospedeiro necessário para semear o estado, restaurar uma linha de base ou satisfazer o contrato do limite de produção. Mantenha substantivos específicos do produto fora do tempo de execução reutilizável do manifesto.

9. Modele a tomada como estágios com reconhecimento de estado, explicitamente acionados. Centralize intervalos de digitação, tempo de carregamento legível, revelações escalonadas e reajustes de viewport. Nunca avance para o próximo estágio narrado sem um gatilho humano.

10. Execute diagnósticos e falhe de forma fechada antes de abrir o aplicativo:

    python3 "$SKILL_ROOT/scripts/oh_my_demo.py" doctor .
    python3 "$SKILL_ROOT/scripts/oh_my_demo.py" status .
    python3 "$SKILL_ROOT/scripts/oh_my_demo.py" check . --record
    

11. Ensaie através do aplicativo real visível na velocidade da narração. Verifique estados pendentes, revelações de resultados, mutações acumuladas, vinculação de áudio/vídeo e resposta do viewport antes de avançar.

12. Resete e repita a tomada idêntica pelo menos duas vezes. Inclua pelo menos uma passagem operada por humano; a automação sozinha não pode provar que o público consegue perceber o comportamento.

13. Vincule as evidências ao manifesto exato e valide-o:

    python3 "$SKILL_ROOT/scripts/oh_my_demo.py" prove .
    

14. Execute uma verificação focada com produção desabilitada. Confirme que a ativação da demonstração está desligada por padrão e que builds normais não resolvem dados de fixture silenciosamente.

15. Relate três listas separadas: comportamento real, limites simulados e conveniências do operador. Registre trabalho de acompanhamento do produto apenas para declarações de produto simuladas, não para controles de demonstração.

Superfícies incorporadas

Use a CLI como a espinha dorsal determinística:

• init: cria .oh-my-demo/manifest.json, evidence.json e fixtures/.
• doctor: diagnostica Python, git worktree, branch, manifesto, ferramentas de mídia e ativação explícita.
• status: mostra o orçamento de verdade ponderado e os limites simulados.
• check: verifica pré-voo de branch, revisão de linha de base, ativos, hashes, duração de mídia, intervalos de rastreamento, metadados de rotação, caminhos Unicode e vínculo de fixture.
• prove: requer duas passagens de reset e repetição, uma passagem de operador visível por humanos, vinculação de digest do manifesto e isolamento com produção desabilitada.

Use o raciocínio da skill para inspecionar e modificar o aplicativo hospedeiro. Não finja que a CLI pode implementar adaptadores específicos de framework por si só.

Contrato de tempo de execução

Mantenha o vocabulário de ações reutilizável pequeno:

focus, set-value, type-text, click, submit, navigate, wait, resolve-fixture, repeat, reset, assert e invoke-adapter.

Mapeie operações de domínio para adaptadores de propriedade do hospedeiro. Uma edição de canvas, semente de banco de dados, inserção de linha do tempo, gesto móvel ou comando TUI permanece como invoke-adapter; a implementação hospedeira possui seus tipos reais e comportamento.

Para campos de texto, resolva um destino de texto declarado ou elemento elegível focado, rejeite campos sensíveis, foque-o, atualize através do caminho de estado controlado do framework quando disponível e envie apenas quando explicitamente solicitado.

Contrato de segurança

• Exija uma ativação explícita em tempo de execução e um branch de demonstração dedicado.
• Exija um gatilho humano para cada etapa gravada.
• Proíba publicação ao vivo, mensagens, faturamento, cobrança ou outros efeitos colaterais remotos de fluxos encenados.
• Nunca ignore autenticação, autorização, política de modelo, contagem de tokens, assinatura ou verificações de lançamento.
• Nunca preencha senhas, tokens, dados de pagamento, códigos de recuperação ou campos semelhantes a segredos.
• Redefina apenas o estado declarado no manifesto ou um snapshot versionado de propriedade do hospedeiro. Nunca atinja um diretório home, raiz do repositório, variável não resolvida, curinga ou caminho fora da raiz declarada.
• Trate uma fixture como prova do caminho do consumidor apenas, nunca como prova de que seu produtor remoto funciona.
• Oculte chrome de depuração apenas quando for irrelevante para a declaração do produto. Nunca oculte um fato material para o que está sendo dito ao público.

Roteamento de referência

Leia references/distribution.md ao decidir como as responsabilidades são divididas entre a skill, CLI, kit do projeto e adaptadores hospedeiros.

Leia references/manifest-schema.md ao criar ou estender .oh-my-demo/manifest.json.

Leia references/adapters-and-safety.md antes de implementar um adaptador hospedeiro, limite de fixture, caminho de reset ou integração de campo de texto.

Leia references/rehearsal.md antes da primeira execução completa, após uma tomada falha, ou quando uma mutação é bem-sucedida mas não é perceptível.

Leia references/evidence-schema.md antes de afirmar que a demonstração é repetível ou preencher .oh-my-demo/evidence.json.

Portão de conclusão

Não considere a configuração completa até que todos os itens a seguir sejam verdadeiros:

• doctor, status e check passem no branch de demonstração dedicado;
• a parcela real ponderada seja de pelo menos 80%;
• cada declaração simulada tenha proveniência, um ponto de injeção estreito, seu equivalente de produção e uma asserção visível;
• o reset restaure o mesmo estado inicial duas vezes;
• pelo menos um ensaio operado por humano seja perceptível na velocidade da narração;
• prove passe contra o digest final do manifesto;
• o modo de demonstração esteja confirmadamente desabilitado no caminho de produção.