feat: package as a Claude Code plugin with a deterministic quality gate

Workflows move to skills/<name>/SKILL.md so the repo installs as a plugin. scripts/quality-gate runs only the checks of the requested tier on the diff and reports missing tools as unverified instead of passing them. Hooks block stopping on a failed or stale gate, guard destructive shell commands and format edited files with the project's own formatter. Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-09-24 21:41:57 -03:00
1 parent 18c2304575
commit 768b5f6d83
@@ -0,0 +1,317 @@
+---
+name: wf-frontend
+description: "Use p/ frontend/UI. Fluxo DESIGN→BUILD→REVIEW."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [frontend, ui, ux, design, react, tailwind, workflow]
+---
+
+# Workflow Frontend/Design
+
+Orquestrador obrigatório para TODO trabalho de frontend, UI, UX ou design
+(componentes, páginas, landing, apps, re-design, design system). Processo de
+3 fases com skills fixas por fase.
+
+## When to Use
+
+Sempre que a tarefa envolver interface do usuário ou GERAÇÃO DE PDF:
+- Frontend/UI: criar/editar componentes React/Vue/Svelte, páginas, layouts,
+  estilos, animações, acessibilidade, qualquer pedido de "design"
+- **PDF/DOCUMENTOS VISUAIS: SEMPRE via este workflow** (regra do Evandro,
+  ago/2026) — NUNCA reportlab platypus raw (estoura bordas em tabelas
+  longas). Usar HTML+CSS → Playwright headless (`pdf-generator`,
+  `html-css-print-engineer`, `pdf-render-qa`). Design primeiro, depois
+  render, depois QA visual (vision_analyze) antes de entregar.
+- Vale para apps novos e refactors.
+
+## Skills do stack (carregar conforme a fase)
+
+- Direção visual / anti-AI-slop: `frontend-design` (Anthropic), `web-design`,
+  `impeccable` (pbakaus — 23 comandos de design: craft/shape/audit/polish/
+  animate/live; 59 regras determinísticas anti-slop),
+  `design-taste-frontend` (taste-skill: gera UI nova com direção inferida do
+  brief; 3 controles DESIGN_VARIANCE/MOTION_INTENSITY/VISUAL_DENSITY; ~22k
+  tokens, só para tela nova), `redesign-existing-projects` (taste-skill:
+  audita UI existente e sobe o nível sem quebrar funcionalidade), e locais
+  `frontend-award-tier`, `claude-design`, `popular-web-designs`,
+  `anti-ai-slop`
+- React/Next performance + composição: `vercel-react-best-practices`,
+  `vercel-composition-patterns`
+- Motion: `animate` (emilkowalski)
+- Bug hunting: `hermaguard` (pre-scan + 3 agentes adversariais; read-only)
+- Qualidade de texto/UI copy: `avoid-ai-writing` (remove AI-isms de microcopy,
+  textos de componente, a11y labels, README de frontend)
+- Esboço rápido / docs visuais: `sketch`, `design-md` (locais)
+- PDF de qualidade: `pdf-generator` (HTML+CSS LaTeX → Playwright),
+  `html-css-print-engineer`, `pdf-render-qa` (QA), `professional-pdf-director`,
+  `pdf-visual-designer` — todo PDF passa por aqui
+
+## Fase 1 — DESIGN (decidir antes de codar)
+
+1. Carregar `frontend-design` + `frontend-award-tier` + `anti-ai-slop`.
+   Tela nova: somar `design-taste-frontend`. Re-design de tela que já
+   existe: `redesign-existing-projects` (audita antes de mudar).
+2. Definir direção visual explícita: paleta, tipografia, espaçamento,
+   densidade, dark/light — NUNCA gerar "default AI slop".
+3. Se for re-design/variação: `claude-design`/`popular-web-designs` para
+   basear em design systems reais (Stripe/Linear/Vercel) e fugir do genérico.
+4. Documentar decisões em `DESIGN.md` (padrão `design-md` se aplicável).
+5. Parar e validar a direção com o usuário ANTES de implementar.
+6. VERIFICAR: rodar `avoid-ai-writing` em detect no DESIGN.md (0 AI-isms) e
+   confirmar que a direção está registrada (paleta + tipografia + density)
+   antes de codar.
+7. VERIFICAR (gate visual): se for PDF/artefato visual, renderizar um
+   rascunho e inspecionar com `vision_analyze` ANTES de avançar — validar
+   que a direção visual de fato foi aplicada e nada está fora de margem.
+8. CHECKPOINT: gravar decisões (paleta final, fonte, density) num
+   `DESIGN.md` com versionamento, para as fases seguintes referenciarem.
+9. VERIFICAR (comandos de direção): conferir que `DESIGN.md` existe e tem
+   conteúdo — `wc -l DESIGN.md` > 5; e que as cores/fontes estão anotadas
+   (`grep -c "paleta\|fonte\|spacing" DESIGN.md` >= 3).
+10. VERIFICAR (anti-slop real): rodar o `anti-ai-slop` no direção proposta
+    antes de mostrar ao usuário — detectar gradiente/glassmorphism
+    prematuramente economiza retrabalho.
+11. VERIFICAR (comandos de design): validar a direção também contra a
+    ferramenta de design usada — `npx`/CLI do design system (ex:
+    `pnpm tailwindcss` se Tailwind) confirmando tokens aplicáveis; e
+    checar com `grep -rn "palette\|tokens\|--color" DESIGN.md` que os
+    tokens ficaram declarados.
+
+**Checklist da fase 1 (validar todos antes de seguir):**
+- [ ] Direção visual definida e DOCUMENTADA (paleta, tipografia, spacing).
+- [ ] Anti-slop: nenhum padrão "default IA" (gradiente, glassmorphism, ícones genéricos).
+- [ ] `DESIGN.md` existe e está aprovado pelo usuário.
+- [ ] `avoid-ai-writing` detect = 0 no DESIGN.md.
+
+**Anti-padrões desta fase:**
+- NUNCA pular a definição de direção visual "só para ver como fica".
+- NUNCA aprovar design sem a confirmação explícita do usuário.
+- NÃO misturar 2 design systems na mesma tela; se for variação, basear em um só.
+
+## Fase 2 — BUILD (implementar com padrões de produção)
+
+1. Carregar `vercel-react-best-practices` + `vercel-composition-patterns`
+   (React) — aplicar regras de performance (waterfalls, bundle, re-renders)
+   e composição (compound components, sem boolean-prop explosion).
+2. Componentes acessíveis por padrão (WCAG): semântica HTML, foco,
+   contraste — sem depender de ARIA desnecessário.
+3. Animações só quando agregam: `animate` — propósito, duração, easing,
+   reduzir motion para prefers-reduced-motion.
+4. Responsivo mobile-first; estados vazios/loading/erro em todo fluxo.
+5. VERIFICAR: rodar build + lint incrementalmente a cada componente
+   (npm/pnpm build) e `vercel-react-best-practices` como checklist de perf
+   durante o build — não deixar para o fim.
+6. VERIFICAR (a11y atômica): para cada componente novo, conferir semântica
+   HTML, gerenciamento de foco e contraste ANTES de considerar pronto —
+   acessibilidade é parte do build, não polimento final.
+7. VERIFICAR (perf real): medir com DevTools/Lighthouse por tela-chave
+   (LCP, INP, CLS) e registrar os números no relatório de perf.
+8. VERIFICAR (composição limpa): `grep -rn "is[A-Z]\|show[A-Z]" src/components`
+   para caçar boolean-prop explosion (deve ser 0 ou poucos intencionais);
+   se houver, refatorar para compound components.
+9. VERIFICAR (animações justificadas): para cada `animate`/motion adicionada,
+   conferir com `grep -rn "animate\|transition\|motion" src/` que há propósito
+   (hover/estado/entrada) — animação decorativa sem função = cortar.
+10. VERIFICAR (limpeza): `git status` e `git diff --stat` antes de fechar —
+    nada de arquivo órfão/debug commitado.
+11. VERIFICAR (critério de aceite do componente): cada componente novo
+    confirma o critério definido na Fase 1 (estado correto, a11y ok, perf
+    ok) antes de passar para o próximo — validar item a item do checklist.
+12. VERIFICAR (comandos de estado): conferir que loading/erro/vazio são
+    tratados em cada fluxo — `grep -rn "loading\|isLoading\|error\|empty" src/`
+    para provar a presença nos componentes que interagem com dados.
+13. VERIFICAR (anti-padrão visual final): percorrer os componentes com
+    `anti-ai-slop` de novo ao fechar a fase — sombra/glassmorphism que
+    "escapou" no scroll é regressão de qualidade.
+14. VERIFICAR (critério de aceite): validar que cada item do checklist da
+    fase está marcado (sem checkbox em branco) antes de declarar BUILD
+    concluído.
+
+**Checklist da fase 2 (validar antes da REVIEW):**
+- [ ] Build e lint verdes (`npm run build` / `npx tsc --noEmit`).
+- [ ] Componentes acessíveis (semântica HTML, foco, contraste) — auditar com
+      `frontend-design`/a11y antes de considerar pronto.
+- [ ] Estados vazios/loading/erro presentes em todo fluxo.
+- [ ] Animações com propósito + `prefers-reduced-motion` respeitado.
+
+**Anti-padrões desta fase:**
+- NUNCA usar `any`/forçar cast em TS para "fazer passar".
+- NUNCA animar sem propósito — animação decorativa gratuita é anti-padrão.
+- NÃO implementar responsivo só no final; mobile-first desde o início.
+- NÃO duplicar lógica de estado em vários componentes (compor, não copiar).
+
+## Fase 3 — REVIEW (verificar antes de entregar)
+
+1. `anti-ai-slop` sobre o resultado (gradientes-texto, glassmorphism,
+   sombras genéricas, layout previsível).
+2. `avoid-ai-writing` sobre textos entregues ao usuário: microcopy, labels,
+   empty states, mensagens de erro, README/descrições — remover AI-isms
+   (em-dash em excesso, "robust", "seamless", "let's dive in", etc).
+3. `hermaguard` no diff de frontend (JS/TS/TSX/CSS): caça bugs adiversariais
+   no código produzido (lógica de estado, efeitos, a11y que quebra).
+4. `vercel-react-best-practices` como checklist de perf (LCP/INP/CLS,
+   bundle, imagem, Suspense).
+5. Rodar build + lint + testes do projeto; corrigir o que quebrar.
+6. Relatório curto: o que foi decidido na Fase 1, entregue na 2, verificado
+   na 3.
+7. VERIFICAR (regressão visual): se houver, comparar screenshots do antes
+   vs depois (ou `vision_analyze` no render) para garantir que nada quebrou
+   de layout.
+8. VERIFICAR (não-regressão QA): rodar `test_quality.py` (gate do workflow)
+   e conferir que o score do stack não caiu.
+9. VERIFICAR (hermaguard re-audit): se o REVIEW mudou >3 arquivos, rodar
+   `hermaguard` no novo diff antes de fechar.
+10. VERIFICAR (bundle/perf real): rodar `npm run build` e conferir tamanho
+    dos chunks (`ls -lh dist/static/*.js`), anotar LCP/INP/CLS se houver
+    Lighthouse.
+11. VERIFICAR (html válido): para PDF/páginas, validar o HTML antes do
+    render — `python3 -c "from html.parser import HTMLParser; ...
+    "` (ou parser disponível) e `grep -c "</t" arquivo.html` = 0 (sem tag
+    truncada).
+12. VERIFICAR (comandos de acessibilidade): rodar auditoria de a11y no
+    render final — `npx @axe-core/cli http://localhost:PORT` (se houver
+    dev server) ou `pa11y`/equivalente; anotar violações sérias.
+13. VERIFICAR (contraste verificado): para paleta dark/light, conferir
+    contraste com ferramenta (ex: `npx contrast-checker` ou manual) —
+    textos principais >= 4.5:1.
+
+**Checklist da fase 3 (gate de entrega):**
+- [ ] `anti-ai-slop` aplicado e sem ressalvas no resultado final.
+- [ ] `avoid-ai-writing` detect = 0 em microcopy/labels/errors/README.
+- [ ] `hermaguard` rodado no diff (0 findings CRITICAL/HIGH pendentes).
+- [ ] `vercel-react-best-practices` auditado (LCP/INP/CLS, bundle, imagem).
+- [ ] Build + lint + testes verdes com contagem real.
+- [ ] Para PDF: renderização via Playwright + `vision_analyze` sem corte.
+
+**Anti-padrões desta fase:**
+- NUNCA dar como entregue com build vermelho.
+- NUNCA ignorar finding CRITICAL/HIGH do hermaguard "para depois".
+- NÃO pular o QA visual de PDF (conteúdo cortado nas bordas = entrega quebrada).
+- NÃO entregar relatório sem os itens do checklist marcados.
+
+## Comandos de Verificação (executáveis)
+
+Gate de qualidade do stack (rodar SEMPRE antes de entregar):
+
+```bash
+# 1) Não-regressão: valida que os workflows continuam íntegros
+python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py
+
+# 2) Testes-dos-testes: prova que o harness detecta regressão
+python3 ~/.hermes/skills/software-development/wf-qa/test_tests.py
+```
+
+QA visual de PDF — renderizar páginas e inspecionar bordas (nada cortado):
+
+```bash
+cd ~/.hermes/skills/productivity/pdf/scripts
+python pdf_page_image.py /caminho/do.pdf --pages 1-3 --dpi 150 --out-dir /tmp/qa
+# depoiss: vision_analyze em cada PNG — margens ok, sem truncamento
+```
+
+Qualidade de texto (microcopy, labels, README) — auditoria de AI-isms:
+
+```bash
+# detect (só lista) — passa 2 arquivos para comparar original vs limpo
+node ~/.hermes/skills/avoid-ai-writing/detector/validate.js ui-copy.md ui-copy-limp.md
+
+# ou debaixo do wf: pedir "roda o avoid-ai no README" (modo detect/rewrite)
+```
+
+Bug hunt adversarial no diff (comandos da skill hermaguard):
+
+```bash
+# gatilho: "hermaguard this" / "adversarial review" / "bug hunt this"
+# gera relatório em /tmp/hermaguard/hermaguard-<ts>.md + .json
+```
+
+Performance React/Next — checklist durante o build:
+
+```bash
+npm run build   # ou pnpm build — verificar warnings de bundle chunk
+npx tsc --noEmit  # typecheck limpo
+npm run lint     # sem erros
+```
+
+Resumo do fluxo (mapa de navegação do workflow):
+
+```text
+[Fase 1 DESIGN]  -> frontend-design + anti-ai-slop -> DESIGN.md aprovado
+[Fase 2 BUILD]   -> vercel patterns + animate -> build/lint verdes
+[Fase 3 REVIEW]  -> avoid-ai + hermaguard + perf -> QA visual (PDF)
+[Gate final]     -> test_quality.py exit 0
+```
+
+## Critérios de Aceite (checklist não-regressivo)
+
+- [ ] DESIGN.md com direção visual aprovada (Fase 1 validada pelo usuário).
+- [ ] BUILD com perf/a11y; build e lint verdes a cada componente.
+- [ ] REVIEW: anti-ai-slop + avoid-ai-writing + hermaguard + perf checklist.
+- [ ] Para PDF: renderização via Playwright e QA visual (vision_analyze)
+      sem conteúdo cortado nas bordas.
+- [ ] Nenhuma skill do stack removida do arquivo.
+- [ ] Rodar `python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py`
+      → exit 0 (sem regressão).
+
+## Exemplos de execução por fase (comandos reais)
+
+Fase 1 — direção visual documentada:
+
+```bash
+cat > DESIGN.md <<'EOF'
+# Direção visual
+Paleta: fundo #ffffff, acento #1e40af, texto #1a1a1a
+Tipografia: serif corpo (Noto Serif/Georgia), mono p/ código
+Density: padrão; dark/light: light first
+EOF
+```
+
+Fase 2 — build e perf:
+
+```bash
+npm run build        # ou pnpm build
+npx tsc --noEmit     # typecheck
+npm run lint         # sem erros
+# "audite a perf"  (vercel-react-best-practices)
+```
+
+Fase 3 — review/QA:
+
+```bash
+# "rode o anti-ai-slop" / "rode o avoid-ai nos textos"
+# "hermaguard this"  (bug hunt no diff de frontend)
+```
+
+Para PDF (regra do Evandro — SEMPRE este caminho):
+
+```bash
+# HTML+CSS -> Playwright headless
+~/.hermes/venvs/latebra/bin/python /tmp/gen-pdf.py   # ver pdf-generator
+cd ~/.hermes/skills/productivity/pdf/scripts
+python pdf_page_image.py saida.pdf --pages 1-N --dpi 150 --out-dir /tmp/qa
+# depois vision_analyze em cada PNG: NENHUM conteúdo cortado nas bordas
+
+# QA de perfil visual (se tiver origem de design)
+node ~/.hermes/skills/avoid-ai-writing/detector/validate.js ui-copy.md ui-limp.md
+```
+
+Verificação de integridade do workflow (gate anti-regressão):
+
+```bash
+python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py    # não-regressão
+python3 ~/.hermes/skills/software-development/wf-qa/test_tests.py      # teste dos testes
+# "hermaguard this"  -> bug hunt adversarial se o diff >3 arquivos
+# "rode o anti-ai-slop" -> antes de entregar
+```
+
+## Regras duras
+
+- NUNCA pular a Fase 1 (consulta de design) direto para código.
+- NUNCA entregar UI sem passar pelo `anti-ai-slop` + `avoid-ai-writing` +
+  `hermaguard` + build verde.
+- Dúvida de stack (Vite vs Next, Tailwind vs CSS) → decidir na Fase 1 com
+  aprovação do usuário, não no meio do build.