Irnist/website-pipeline

Website pipeline

Você executa um site de cliente desde a entrada bruta até um preview implantado com o mínimo de intervenção do usuário possível. Primeiro, toda execução (nova, retomada ou uma fase única): Leia <pipeline>/RULES.md, as regras do site, a menos que esta sessão já o tenha feito. Elas se aplicam a cada etapa. As ferramentas em tools/ impõem a maioria delas mecanicamente, então execute-as em vez de verificar manualmente.

Workspace

Tudo reside em um workspace, C:\Users\Administrator\Desktop\Claude Workspace (<workspace>). Os caminhos abaixo são relativos a ele; em scripts, derive-os da localização do próprio script (Path(__file__)), nunca um caminho fixo da Área de Trabalho.

O quê	Onde
Pipeline (<pipeline>)	Workflow and Pipeline/website-pipeline/ (~/.claude/skills/website é uma junção para ele)
Ferramentas compartilhadas	<pipeline>/tools/: a cópia única de qa.py, browser_qa.mjs, deploy.py… O tools/ de cada site contém stubs que as executam naquele site (L-052), então uma correção ou nova verificação alcança todos os sites de uma vez. Scripts específicos do site ficam ao lado dos stubs.
Sites de exemplo	Concept Websites/<Nome> Website/
Portfólio do proprietário	Portfolio Site/
Capturas de tela do portfólio	Portfolio Screenshots/: apenas capturas de sites finalizados, nada mais
Arquivos temporários (scripts de teste, capturas de teste, backups, defeitos plantados)	_temp/, nunca a pasta temp do sistema, um projeto ou o template

0. Onde estou?

Decida o ponto de entrada a partir do estado da pasta e dos argumentos:

Estado	Ação
Sem _src/build.py no diretório atual	Scaffold: powershell -NoProfile -ExecutionPolicy Bypass -File "<pipeline>/scaffold.ps1" -Target "<cwd>" -NoLaunch, depois vá para Captação. Se o diretório atual contiver arquivos não relacionados, pare e pergunte (esta é uma pergunta crítica).
PROJECT.md tem todas as fases marcadas (um site finalizado reaberto pelo mesmo nome) e os argumentos estão vazios ou são para captação de novo site, não um argumento de fase ou uma solicitação de alteração	Pergunte primeiro, antes de executar ou alterar qualquer coisa (o usuário, 2026-10-10, L-057). Use um AskUserQuestion: " já está finalizado (preview ). Redesenhar?" com Não, deixar como está e Sim, redesenhar. Não: pare e não faça nada, nem mesmo uma sincronização de ferramentas, QA ou implantação. Sim: inicie exatamente como um novo site; nunca redesenhe por conta própria a partir do briefing antigo (L-058). (1) Faça commit de quaisquer alterações soltas e marque a versão antiga: git tag previous-<data>. Em seguida, mova tudo, exceto client-assets/ e .git/, para <workspace>/_temp/<Nome>-previous-<data>/ (um arquivo, nunca uma exclusão), incluindo o antigo BRIEF.md. A tag mantém o site antigo restaurável após _temp ser limpo. (2) Execute o scaffold novamente, copie o BRIEF.md em branco do template e defina sua linha Business name:. (3) Abra o formulário de briefing, python "<pipeline>/brief-form/brief_form.py" "<project>", como um comando em segundo plano, diga ao usuário que a janela está aberta e aguarde. Não faça nenhum trabalho de direcionamento, aprendizado de biblioteca, pesquisa de estoque ou design enquanto isso. (4) Exit 0 ("Começar a construir"): execute o processo normal de novo site a partir da Captação no novo briefing. Exit 3 (fechado): pare e diga que o briefing foi salvo. Na entrega, substitua a entrada da biblioteca de design do site em vez de adicionar uma segunda.
PROJECT.md tem fases não marcadas	Retome na primeira fase não marcada. Diga uma linha sobre onde está retomando.
Retomando ou alterando qualquer projeto existente	As ferramentas não precisam de sincronização: tools/ contém stubs para as ferramentas compartilhadas. Se o site não tiver .git/, execute git init -b main, git config core.autocrlf false, copie o .gitignore do template e faça commit de uma linha de base primeiro. Se qa.py alertar sobre cópias completas de ferramentas compartilhadas (um site anterior a 2026-10-13), execute python "<pipeline>/dev/use_shared_tools.py" "<project>" e faça commit. Também traga os recursos do template que a solicitação precisar (ex.: GSAP: h_gsap no build.py, {{fn:gsap}}, tools/vendor/, motion.js).
Argumento status	Imprima a lista de verificação de fases mais os placeholders abertos. Não faça mais nada.
Argumento learn	Aprenda as imagens de design e arquivos DESIGN.md colocados em <pipeline>/design-library/inspiration/: siga design-library/LEARN.md, depois relate uma linha por referência. Não faça mais nada.
Argumento qa / deploy / handoff	Execute apenas essa fase.

Argumentos de texto livre são material de captação (nome da empresa, telefone, links, anotações). Trate-os da mesma forma que BRIEF.md.

Modo: amostra ou cliente

BRIEF.md › Project type define o modo. O padrão é amostra, significando uma peça de portfólio. Uma instrução explícita nos argumentos prevalece.

	amostra (portfólio)	cliente (negócio real)
Fatos ausentes	Quando o briefing é enxuto, invente um negócio fictício plausível e consistente: nome, história, serviços, horários. Use números de telefone 555-01xx e e-mails example.com para que nada alcance uma pessoa real.	Nunca invente. Use placeholders e data-todo.
Avaliações, estatísticas, credenciais	Tudo bem para um negócio fictício; liste-os como fictícios na entrega. Se a amostra usar um negócio real, use apenas fatos públicos reais: sem avaliações, alegações ou preços inventados sobre pessoas ou empresas reais.	Apenas o que o cliente fornecer.
Perguntas	Quase nenhuma: apenas sobre exclusão de arquivos, gastar dinheiro, contatar o mundo real (caixas de entrada reais, números de telefone reais) e críticas de design críticas (#5).	A política de perguntas completa abaixo.
Formulários	Modo demo é suficiente.	Um endpoint real é necessário; pergunte se estiver faltando.
Implantação	preview noindex	preview noindex; produção apenas mediante solicitação
Extra de entrega	Captura de tela do portfólio (veja Entrega)	Lista de placeholders escrita para o cliente

Regras operacionais

• Piloto automático. Avance de fase em fase sem perguntar "devo continuar?". Após cada fase, marque-a em PROJECT.md › Status. Isso torna a execução retomável após compactação ou uma nova sessão.
• Git (cada site e o pipeline são repositórios). Faça commit no site após cada fase marcada (<Fase>: <o que foi feito>) e após cada rodada de alterações solicitadas, para que qualquer estado possa ser comparado ou restaurado. Faça commit de alterações do pipeline (ferramentas compartilhadas, template, SKILL.md, LESSONS.md, biblioteca de design) no repositório do pipeline, com o ID da lição na mensagem quando houver uma. dist/, qa/ e caches são gitignorados. Nunca reescreva o histórico, force nada ou faça push; não há remoto.
• Perguntas seguem a política abaixo. Todo o resto é uma decisão: tome-a, adicione uma linha a PROJECT.md › Decisões (o quê + porquê) e continue.
• Modo cliente: nunca invente fatos do cliente. Isso cobre depoimentos, contagens de avaliações, anos no mercado, licenças, certificações, preços, garantias, prêmios e nomes de equipe. Se o material não estiver nas entradas, escreva o texto de forma que não precise do fato. Se for genuinamente necessário, marque o elemento com data-todo="o que é necessário" para que o QA o liste para a entrega. O modo amostra segue a tabela de Modo.
• Registre cada erro no momento em que acontecer em PROJECT.md › Erros. Não espere pela entrega; o contexto pode ser compactado antes disso. Um erro é qualquer coisa que o usuário corrija, qualquer erro de primeiro rascunho que o QA, uma crítica ou o revisor sinalizar (registre uma entrada por tipo, não por instância), e qualquer suposição errada ou ferramenta mal utilizada. Cada entrada registra o que aconteceu, quem pegou, a causa raiz, a correção e como prevenir.
• Fonte da verdade: edite _src/ (páginas, parciais, site_config.py) e assets/, depois execute python _src/build.py. Nunca edite dist/.
• Edições com script (L-027): alterações únicas usam Edit. Várias substituições de uma vez vão em um script Python escrito com Write (em <workspace>/_temp), nunca um heredoc do shell. O script sai a menos que cada contagem de correspondência seja exatamente 1, e verifica cada arquivo antes de escrever qualquer um deles. Depois, py_compile qualquer .py editado e reconstrua.
• Higiene de contexto: execute ferramentas e leia seus relatórios (qa/*.md), não a saída bruta. Consulte relatórios longos, logs e listagens através do modo contexto (ctx_execute_file / ctx_batch_execute com uma pergunta como "apenas erros e avisos") em vez de lê-los por inteiro. Veja capturas de tela com a ferramenta Read. Nunca despeje arquivos HTML inteiros na conversa.

Política de perguntas (apenas assuntos críticos)

Pergunte apenas quando uma destas condições for verdadeira. Isso é para o modo cliente; no modo amostra apenas #2 e #5 se aplicam, e um preview noindex nunca precisa de pergunta.

1. Identidade desconhecível. Você não consegue discernir de nenhuma entrada ou fonte pública o que o negócio faz, onde está ou quem atende. Um palpite errado significaria reescrever o site.
2. Externo ou irreversível. Implantações de produção, domínios personalizados, conectar um formulário a uma caixa de entrada real, qualquer coisa que gaste dinheiro, excluir arquivos do usuário. Uma implantação de preview noindex é pré-autorizada quando BRIEF.md diz Deploy preview: yes.
3. Alegações legais ou factuais que o site faria e que apenas o cliente pode confirmar (licenciamento, preços, garantias). Por padrão, deixe-as de fora. Pergunte apenas se o briefing as tornar centrais.
4. Instruções conflitantes entre o briefing, as mensagens do usuário, RULES.md e CLAUDE.md, onde ambas as leituras são plausíveis.
5. Crítica de design crítica. Uma crítica impecável ou o revisor de finalização relata um problema P0 (Bloqueante) ou P1 (Grande). Siga o portão de crítica abaixo. Esta é a única pergunta permitida durante a construção.

Como perguntar:

• Um lote, ao final da Captação. Use um único AskUserQuestion com 1 a 4 perguntas. Coloque a resposta recomendada primeiro, marcada como "(Recomendado)". Nunca pergunte durante a construção, exceto no portão de crítica (#5). Se um bloqueador surgir mais tarde, use um placeholder claramente marcado, registre-o em Perguntas adiadas e apresente-o na entrega.
• Nunca pergunte sobre: paleta, fontes, layout, tom do texto, lista de páginas, quais fotos de estoque, ordem das seções, pilha de tecnologia, nomes de arquivos ou se deve corrigir uma constatação de QA. Decida essas coisas. A única exceção é uma constatação de crítica P0/P1 (#5).
• Se nada for crítico, não pergunte nada. Diga "Nenhuma pergunta bloqueante; prosseguindo" e continue.

Portão de crítica (constatações impecáveis)

Use a própria escala de gravidade do impecável (P0 Bloqueante, P1 Grande, P2 Pequeno, P3 Polimento). Classifique cada item de constatação-revisor na mesma escala.

• P2/P3 (pequeno): não corrija; prossiga. Registre uma linha por constatação em PROJECT.md › Decisões: "ignorado: pequeno (P2/P3), <constatação>".
• P0/P1 (crítico): pare e pergunte antes de mudar qualquer coisa. Use um lote AskUserQuestion com até 4 perguntas. Escreva uma pergunta por constatação, ou agrupe-as por classe se houver mais de 4. Cada pergunta diz o que está errado e onde (página, seção, arquivo de captura de tela). Oferece 2–3 opções de correção concretas, com a recomendada primeiro e marcada como "(Recomendado)", mais "Deixar como está". Em seguida, aplique a escolha do usuário a toda a classe em todo o site (L-016), reconstrua e registre a escolha em Decisões.
• Re-verificação: execute a mesma crítica novamente uma vez após aplicar as escolhas. Qualquer novo P0/P1 passa pelo portão novamente; constatações pequenas são ignoradas como acima.
• Não faz parte do portão: violações objetivas de regras que qa.py, browser_qa.mjs, LESSONS.md ou RULES.md já proíbem, como contraste abaixo de 4.5:1, transbordamento, uma foto repetida, um brilho que reduz o contraste do texto sobre ele abaixo do permitido (brilhos em si são permitidos), um assunto cortado ou um select pré-preenchido com um valor padrão. Corrija-os automaticamente, independentemente da gravidade que a crítica lhes atribuir, porque são defeitos, não escolhas de design. As sinalizações impeccable detect contam como pequenas, a menos que atinjam uma dessas regras. Anote falsos positivos conhecidos (L-000) como antes.

Fases

1 · Captação

0. Leia <pipeline>/LESSONS-INDEX.md (uma linha por lição, gerada a partir de LESSONS.md). Toda lição se aplica desde o primeiro rascunho. Abra a entrada completa de LESSONS.md para cada uma que for relevante para este projeto e liste seus IDs, cada um com algumas palavras, em PROJECT.md › Erros › "Observar". Liste IDs, nunca texto de lição copiado: cópias ficam obsoletas quando uma lição é substituída (Trevor Travis e Gadget Zone mantiveram "sem brilhos" depois que brilhos foram permitidos).

1. Leia BRIEF.md, os argumentos e tudo em client-assets/. Abra cada foto com Read e catalogue-a em PROJECT.md › Ativos. Registre o assunto, sua qualidade, quaisquer problemas (placas, logotipos, desordem, corte) e o melhor lugar para ela (hero/feature/gallery/skip). Logotipos de marcas de terceiros em uma imagem (placas, sinalização, renders) são lidos como endossos: marque-a como "cortar antes de usar" ou pule (L-028). Observe quais fotos vêm da mesma sessão ou mostram a mesma vista (L-029).

2. Se links foram fornecidos (site existente, Perfil do Google Meu Negócio, Facebook), busque-os e extraia fatos: serviços, área de serviço, horários, história, proprietário, anos, projetos reais. Cite a fonte ao lado de cada fato em PROJECT.md › Fatos.

   • Salve legendas, avaliações e citações do proprietário ipsis litteris em um arquivo de fontes (ex.: client-assets/sources.md). Copie citações dele; nunca redigite ou parafraseie uma de memória (L-007).
   • Registre a linha de crédito de cada projeto (desenhado por / construído por / ano) em Fatos. Um projeto que o negócio apenas construiu nunca é "desenhado por" ele.

3. Otimize as fotos do cliente: python tools/optimize_images.py (client-assets → assets/img/client/, rotacionadas por EXIF, máx. 2000px).

4. Preencha _src/site_config.py: BIZ, HOURS, SERVICES, PRIMARY_CTA, PAGES, FORM_ENDPOINT, SEO. Valores de contato desconhecidos permanecem "". A construção os deixa como placeholders visíveis {{TOKEN}} e o QA os relata.

   • Formulário de contato. Copie Form endpoint: do briefing para FORM_ENDPOINT: em branco = modo demo; netlify = Netlify Forms (apenas com Deploy host: netlify; qa.py gera erro caso contrário); web3forms:<chave de acesso> = Web3Forms em qualquer host (o proprietário da caixa de entrada cria a chave em web3forms.com); ou uma URL estilo Formspree. {{fn:form_fields}} adiciona os campos ocultos correspondentes e a armadilha de spam. Nunca escolha ou conecte uma caixa de entrada real você mesmo: um briefing em branco permanece em modo demo e vai para a lista de entrega. No modo cliente, qual caixa de entrada recebe as mensagens é uma pergunta. Copie Online booking link: para BOOKING_URL; {{fn:booking}} o exibe na página de contato ao lado do botão de chamada.
   • Movimento GSAP. Opcional, desligado por padrão. Apenas quando o briefing diz GSAP motion: yes ou quando o direcionamento o adiciona. Adicione o suporte e use-o, não adicione sem ele. Os placeholders de rota padrão CSS funcionam sem ele.
   • Imagens de herói. A primeira imagem de client-assets/ que se qualifica (assunto forte, nenhum problema grave) vai como HERO_IMAGE. A construção a usa em {{fn:hero}} com sobreposições de gradiente. Fotos de grupo são boas; logotipos de terceiros são um problema (L-028). Nenhuma imagem adequada = sem herói, apenas um gradiente ou padrão. Se o direcionamento pedir uma foto de estoque (uma imagem de marca de 1200 × 675 de <pipeline>/stock/), HERO_IMAGE fica "" e o direcionamento a adiciona em seguida.

5. Se o direcionamento não for necessário, pule para QA.

2 · Direcionamento

Antes de escrever qualquer HTML/CSS/JS, projete o site visualmente e estruturalmente a partir do briefing e ativos. Só implemente depois que o design estiver completo.

• Saída: uma entrada na biblioteca de design (veja abaixo) e anotações de seção em PROJECT.md › Direcionamento.

Pesquise a biblioteca de design primeiro. Leia DESIGN.md de cada entrada em <pipeline>/design-library/site-entries/. Encontre o(s) layout(s) que se encaixam melhor no propósito e estilo do briefing. Reutilize as seções e seus estilos (copie o HTML/editável da entrada). Nunca escreva CSS para uma seção do zero quando uma entrada da biblioteca já a cobre. Se nenhuma entrada for uma boa correspondência, crie uma nova (veja abaixo).

• Encontre uma paleta. Escolha cores que se encaixem no mercado do negócio, personalidade (se conhecida) e fotos. A biblioteca de design pode ter paletas de exemplo. Nomeie-as (ex.: "Dark Teal"). Coloque-as em _src/site_config.py (PALETTE).
• Imagem de estoque. Opcional. Use apenas imagens de <pipeline>/stock/. Duas regras: (1) a imagem deve ser de uma marca conhecida ou licenciada como gratuita; (2) somente imagens de 1200 × 675 – redimensione se necessário, nunca corte. Prefira imagens com cores compatíveis com a paleta. Se for adicionar uma imagem de estoque como herói, defina HERO_IMAGE como vazio na Captação.
• Anote as seções do direcionamento em PROJECT.md. Anote as razões do layout (ex.: "hero: foto + CTA → mostra o trabalho e leva ao contato").

Adicionar uma nova entrada na biblioteca de design

Quando o site exigir um arranjo de seção, estilo ou recurso que não está na biblioteca, crie uma nova entrada:

1. Tire uma captura de tela de tamanho moderado do design finalizado (não precisa ser completa, só a nova parte) e salve-a em <pipeline>/design-library/screenshots/. Use uma convenção de nomenclatura descritiva (ex., agency-hero-cards.jpg).
2. Escreva uma entrada em <pipeline>/design-library/site-entries/ como NOME-DA-ENTRADA.md contendo:

   ---
   name: Nome da Entrada
   screenshot: ../screenshots/nome-da-captura.jpg
   tags: [tag1, tag2, …]
   ---
   
   # Nome da Entrada
   
   (descrição breve, 2–4 frases: para que serve, quando usar, pontos fortes, limitações)
   
   ## Seções
   
   **1. Hero/Sobre** – descrição do layout e comportamento
   
   **2. Serviços** – descrição do layout e comportamento
   
   …
   
   ## Notas
   
   - Dependências: `h_gsap` se usa movimento
   - Alternativas conhecidas: …
   

   Inclua os blocos de construção (o HTML/editável de cada seção) em um diretório _examples/ adjacente, ou inclua trechos na entrada (L-031).
3. Faça commit da nova entrada e da captura de tela no repositório do pipeline.

Se o direcionamento estiver completo: prossiga para a Construção.

3 · Construção

Implemente cada página a partir do direcionamento. Mova de cima para baixo. Depois de cada página, execute verificações de sanidade no navegador: python tools/browser_qa.mjs local (abre a página, tira uma captura de tela, executa verificações visuais). Se falhar, depure e corrija.

Estrutura:

• _src/pages/ → uma página por arquivo .html (jinja). As seções vão em _src/partials/ e são incluídas com {{fn:section_name}}. A página de contato base usa {{fn:contact_form}} e {{fn:booking}}.
• _src/site_config.py → constantes do site (BIZ, HOURS, etc.). {{TOKEN}} placeholders significam que o valor não foi fornecido e é necessário.
• assets/ → CSS, JS, imagens. Arquivos de CSS e JS: um por página para escopo (css/home.css, js/about.js). Imagens otimizadas vão em assets/img/client/.
• _src/build.py → constrói dist/, aplica placeholders, minifica, copia ativos. Execute após cada alteração.

Regras de implementação:

• Contraste: texto sobre imagem: a imagem deve ter uma sobreposição escura. Texto sobre gradiente: verifique o contraste. Ferramentas: browser_qa.mjs sinaliza contraste baixo.
• Imagens: nunca estique uma imagem de proporção fixa. Use object-fit: cover + aspect-ratio ou dimensões explícitas.
• Fontes: use fontes do sistema ou Google Fonts. Carregue Google Fonts via <link> no <head>; nunca @import.
• Margem/Padding: consistente. Use um sistema de espaçamento base (ex., --space-xs, --space-sm, …).
• Links: abra em nova guia se for externo, com rel="noopener noreferrer".
• Responsividade: cada seção deve funcionar em 375px, 768px, 1024px e 1440px. Teste com redimensionamento de navegador ou browser_qa.mjs.

Após a construção: execute ferramentas de QA.

4 · QA

Execute as verificações e corrija os problemas automaticamente, a menos que seja uma pergunta de crítica (P0/P1).

1. python tools/qa.py – verifica site_config.py, placeholders, links quebrados, tags de SEO, meta descrições, contraste de cores, erros de console. Gera relatório em qa/qa_report.md.
2. node tools/browser_qa.mjs – abre cada página, captura tela, executa verificações: layout, contraste, transbordamento, largura mínima, rolagem, interações. Relatório em qa/browser_qa_report.md.
3. Leia os relatórios com a ferramenta Read. Corrija quaisquer problemas sinalizados. Se um problema for P0/P1, pare e use o portão de crítica.

QA limpo: prossiga para a Implantação.

5 · Implantação (Preview)

1. Execute python tools/deploy.py – obtém uma URL de preview (Netlify ou similar).
2. Verifique a URL de preview: execute browser_qa.mjs na URL de preview, verifique se a construção está correta.
3. Registre a URL em PROJECT.md › Implantação.

Implantação bem-sucedida: prossiga para a Entrega.

6 · Entrega

1. Modo amostra: tire uma captura de tela do site finalizado (ferramentas disponíveis: captura de tela do navegador) e salve-a em Portfolio Screenshots/ com o nome do site. Capturas existentes são substituídas.
2. Modo cliente: gere uma lista de placeholders (data-todo) de PROJECT.md e do relatório de QA. Escreva em um arquivo client-assets/handoff.md.
3. Diga ao usuário: "Entrega concluída. Preview: " (ambos os modos). Em modo cliente, adicione: "Placeholders: ".