vicunav/vicunav-transform-claude-to-gutenberg

Transformar Claude Code para Gutenberg FSE

Objetivo

Converter o projeto aprovado do Claude Code em um site WordPress nativo e sustentável. Preservar design, conteúdo e comportamento acordados sem arrastar a arquitetura do protótipo frontend quando o WordPress já oferecer uma solução editável por meio de blocos.

Tratar o projeto fonte como especificação visual e funcional. Trabalhar apenas no LocalWP autorizado. Não modificar produção, nem apagar conteúdo, personalizações do Site Editor ou dados locais sem aprovação explícita.

Reunir o contexto mínimo

Confirmar ou descobrir antes de editar:

• caminho do projeto exportado ou refinado no Claude Code;
• caminho do site LocalWP e do tema alvo;
• commit, build ou estado exato que constitui o design aprovado;
• páginas, breakpoints, estados e interações incluídas;
• versão real do WordPress e PHP do site local;
• se o objetivo é paridade 1:1, otimização aprovada ou redesign;
• conteúdo e integrações que devem ser editáveis a partir do WordPress;
• restrições de plugins, blocos custom, fontes e licenças de assets.

Se faltar uma decisão que altere conteúdo, arquitetura, funcionalidade ou design, parar e pedi-la. Se faltar um dado recuperável do filesystem, do frontend ou do site local, inspecioná-lo e registrar a suposição.

Carregar as bases reutilizáveis

Aplicar os skills oficiais instalados conforme a fase:

• wp-project-triage: classificar o projeto WordPress e sua toolchain;
• wp-block-themes: implementar theme.json, templates, parts, patterns e estilos FSE;
• wp-block-development: usar apenas se uma interação exigir um bloco custom;
• wp-wpcli-and-ops: inspecionar ou alterar conteúdo e opções com WP-CLI;
• unlazy (se instalado): disciplina de fechamento para uma migração de tamanho substancial (mais de uma página, ou qualquer trabalho que vá ser reportado como concluído sem supervisão constante). Ver "Fechar cada unidade com disciplina de gates" mais abaixo.

Verificar primeiro a versão alvo. Se um skill oficial apontar para uma versão do WordPress posterior à do LocalWP, usar apenas as APIs compatíveis e consultar documentação oficial para resolver diferenças.

Ler recursos próprios quando apropriado:

• source-contract.md: antes de congelar o baseline e definir o contrato de migração;
• migration-manifest.md: antes de capturar o baseline ou implementar qualquer alteração com impacto visual;
• translation-map.md: antes de decidir a arquitetura Gutenberg e durante a tradução de cada componente;
• localwp.md: antes de tocar no site ou em sua base de dados;
• qa-checklist.md: antes da primeira seção visível e novamente antes de declarar o trabalho concluído;
• upstream.md: ao atualizar, auditar ou redistribuir as bases reutilizadas;
• templates/gates-fse-migration.md: ao abrir $unlazy para uma página ou seção, como ledger inicial a copiar e completar em vez de escrever os gates do zero.

Executar o fluxo

1. Ler instruções locais, estado Git e documentação diretamente envolvida em ambos os projetos.
2. Executar scripts/audit_source.mjs <caminho-fonte> e revisar manualmente seus achados. Não tratar o relatório heurístico como uma decisão arquitetônica.
3. Criar o manifesto de migração, indexar todas as combinações esperadas e executar scripts/validate_migration_manifest.mjs <caminho-manifesto>.
4. Levantar o frontend fonte em um ambiente limpo e capturar baseline em desktop, tablet e mobile, incluindo estados interativos relevantes.
5. Criar o contrato de migração: páginas, seções, copy, assets, tokens, interações, fontes de dados, integrações e critérios de aceitação.
6. Separar tokens reutilizáveis de geometria local. Mapear os primeiros para theme.json e conservar a segunda por meio de blocos, layouts e classes semânticas mínimas.
7. Projetar a arquitetura FSE: templates, template parts, patterns, conteúdo de páginas e, apenas quando necessário, blocos custom ou plugins.
8. Implementar primeiro uma seção representativa. Comparar frontend e Site Editor antes de escalar o padrão para o resto do site.
9. Migrar página por página e seção por seção. Manter o projeto fonte visível como referência durante toda a implementação. Se $unlazy estiver disponível, abrir uma unidade copiando templates/gates-fse-migration.md para um GATES.md próprio daquela página ou seção antes de implementá-la, não depois.
10. Instalar ou ativar o tema no LocalWP por meio do fluxo documentado do projeto. Criar ou atualizar conteúdo de forma idempotente e preservando o existente.
11. Executar scripts/validate_fse_theme.mjs <caminho-tema> e corrigir todos os erros. Revisar os avisos aplicáveis.
12. Completar QA visual, estrutural, editorial, responsivo, acessível e de desempenho no frontend e no Site Editor.
13. Executar captura, comparação e gate por meio de capture_visual_evidence.mjs, compare_visual_evidence.mjs e verify_visual_evidence.mjs; revisar manualmente lado a lado e overlay. Para cada página com pelo menos uma seção full-bleed, executar além disso scripts/verify_editor_frontend_parity.mjs (requer um cookie de sessão real gerado com scripts/wp_auth_cookies.php, ver translation-map.md) e exigir PARIDADE_EDITOR_FRONTEND_OK: a comparação visual humana não é suficiente por si só para esta classe de bug, já documentada duas vezes neste projeto. Se a unidade tiver um GATES.md, executar node <dir-skill-de-unlazy>/scripts/gate-check.mjs --reverify GATES.md e exigir ALL MET antes de continuar.
14. Entregar evidências, limitações, rollback e próxima unidade de trabalho. Se $unlazy foi usado, incluir os ids qualificados de gates cumpridos, não cumpridos e abandonados; não descrever como concluída uma unidade com um gate pendente ou abandonado.

Fechar cada unidade com disciplina de gates ($unlazy)

Quando unlazy estiver instalado, tratá-lo como a camada de disciplina de fechamento deste skill, não como uma alternativa a ele: este skill decide o que verificar em uma migração FSE; unlazy obriga a declarar esses critérios como comandos executáveis antes de trabalhar e a reverificá-los com evidência real antes de reportar como concluído, em vez de confiar em uma leitura visual de "parece bom".

• Usar o modo apenas de unlazy para uma página ou seção (um GATES.md por unidade, copiado de templates/gates-fse-migration.md). Usar o modo orquestrado apenas para um site completo com muitas páginas independentes, onde cada página é uma folha da Depth Tree com seu próprio OWNS: (seus próprios arquivos de template/pattern) e um ramo de integração verifica navegação cruzada, cabeçalho/rodapé compartilhados e ausência de regressões entre páginas.
• Não converter cada correção trivial em um ledger de gates. Reservar a disciplina para uma página, uma migração de site completo, ou qualquer unidade cujo custo de ficar silenciosamente incompleta justifique (ver o exemplo real: conteúdo hardcoded em um template que deixou uma página vazia e ineditável durante várias unidades de trabalho antes de o dono do site detectá-lo manualmente).
• Adaptar o gate de conteúdo real (post_content não vazio) à invocação de WP-CLI real do projeto; no LocalWP quase nunca é o binário wp global (ver localwp.md).
• Um gate manual ainda é válido para o que nenhum comando consegue medir bem (fidelidade visual perceptual, revisão editorial de copy). Não forçar uma métrica automática apenas para evitar um gate manual; o contrato deste skill já proíbe converter uma métrica perceptual em aprovação automática de paridade.
• Não instalar o Stop hook opcional de unlazy sem pedi-lo explicitamente ao usuário primeiro; o próprio skill exige.
• Roteirizar o trabalho pelo nível de modelo que corresponda, tanto no modo orquestrado de unlazy quanto na migração página por página deste skill: uma folha mecânica e bem delimitada (tradução direta de um componente já resolvido em outra página, um ajuste de classe, um fix pontual já diagnosticado) vai para um modelo mais leve; uma folha que requer juízo arquitetônico, decidir bloco vs. pattern vs. CPT, ou qualquer verificação visual, é retida pelo modelo da sessão. Não distribuir um agente completo para cada edição pequena quando agrupá-las em uma única passagem atinge o mesmo resultado com menos coordenação.

Manter contratos não negociáveis

• Preferir blocos core, patterns do tema e APIs públicas do WordPress.
• Não usar core/html como atalho para conservar o HTML do protótipo.
• Usar theme.json como fonte da verdade para tokens compartilhados.
• Manter templates e parts para estrutura global; usar conteúdo de página ou patterns para composição editorial.
• Não introduzir React, Tailwind ou o runtime do protótipo no frontend do WordPress, salvo requisito demonstrado e aprovado.
• Criar blocos custom apenas para comportamento ou edição que os blocos core não consigam expressar de forma sustentável.
• Colocar lógica de negócio, reservas, pedidos e modelos de dados em plugins, não no tema.
• Servir fontes e imagens localmente e conservar licença, proveniência e texto alternativo.
• Manter frontend e Site Editor como superfícies obrigatórias.
• Não implementar uma migração visual sem manifesto válido e matriz completa.
• Não converter uma métrica perceptual em aprovação automática de paridade.
• Não depender de estilos globais acidentais salvos na base de dados.
• Respeitar prefers-reduced-motion, teclado, foco visível e WCAG 2.1 AA.
• Não inventar conteúdo, rotas ou funcionalidades para cobrir lacunas do design.

Aplicar o critério do demo de restaurante

• Modelar um menu pequeno e puramente editorial com blocos e patterns.
• Propor um CPT como vicu_menu_item unicamente se o menu precisar de edição estruturada, filtros, reutilização ou crescimento real; registrá-lo em um plugin e testar seu comportamento.
• Tratar reservas, pedidos, pagamentos, horários dinâmicos e disponibilidade como integrações funcionais separadas. Não simulá-los silenciosamente com um formulário estático.
• Reutilizar cabeçalho, rodapé, chamadas para reservar e módulos de contato por meio de parts ou patterns sincronizados com a arquitetura aprovada.

Trabalhar em unidades verificáveis

Fechar uma página ou seção unicamente quando:

• o conteúdo, links e assets coincidirem com o contrato;
• o markup for válido e seus blocos permanecerem editáveis;
• frontend e editor representarem corretamente os estilos;
• desktop, tablet e mobile estiverem comparados contra o baseline;
• os estados hover, focus, active, loading e error aplicáveis estiverem testados;
• não existirem erros de console, recursos remotos inesperados nem dependências do servidor de desenvolvimento do Claude Code;
• a evidência corresponder ao estado exato testado;
• a combinação tiver uma linha única no manifesto e não permanecer pending.

Entregar um estado verificável

Informar:

• páginas e seções concluídas;
• arquitetura e arquivos afetados;
• decisões de core block, pattern, bloco custom ou plugin;
• comandos e verificações executados com seus resultados;
• URLs e viewports usados para comparação;
• diferenças aceitas, riscos residuais e rollback;
• caminho do manifesto validado e resumo de sua matriz de evidências.

Não afirmar paridade visual porque o site renderiza ou porque o HTML contém o mesmo copy. A paridade requer comparação visual e validação de editabilidade.

Exemplos de invocação

Use $transform-claude-to-gutenberg para auditar este projeto do Claude Code e
criar o contrato de migração da homepage para o site LocalWP indicado.

Use $transform-claude-to-gutenberg para transformar o demo de restaurante em
um block theme FSE 1:1, usando blocos core e assets locais.

Use $transform-claude-to-gutenberg para revisar o tema migrado e enumerar o que
impede considerá-lo editável e visualmente equivalente ao protótipo aprovado.