refactor(skills): cut the workflows to ~100 lines and scale phases by tier
Each workflow was ~300 lines of grep-count "VERIFICAR" steps and ran every phase for every request. Phases now state their minimum tier, checks are the quality gate plus real tools, detail moved to references/, and machine-specific paths and non-public skills are gone. Security references move to OWASP Top 10:2025, ASVS 5.0 and the OWASP LLM Top 10. Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
EvandroandClaude Opus 5.5 committed
1 parent
c18d3356ae
commit
f2db2d69da
20 files changed
+823
-1176
No files matched your search
+5
-4
@@ -1,7 +1,7 @@
|
||||
# Skills vendorizadas — origem e licença
|
||||
|
||||
Este diretório contém cópias vendorizadas (não forks, não submodules) das
|
||||
skills de terceiros usadas pelo `wf-security-review`. Vendorizar em vez de só
|
||||
skills de terceiros usadas pelo `wf-security-review` e pelo `wf-frontend`. Vendorizar em vez de só
|
||||
linkar (como `docs/SKILLS.md` fazia antes) significa que `git clone
|
||||
dev-workflows` já traz tudo funcional, sem passo manual de instalação externa.
|
||||
|
||||
@@ -26,8 +26,8 @@ repo de origem, ou comparar datas).
|
||||
|
||||
As duas skills do taste-skill são usadas pelo `wf-frontend`. O `LICENSE` do
|
||||
upstream vai dentro de cada diretório, porque a MIT exige que o aviso de
|
||||
copyright acompanhe a cópia. `design-taste-frontend` tem ~87 KB (~22 mil
|
||||
tokens): carregue só para UI nova, não para ajuste pontual.
|
||||
copyright acompanhe a cópia. `design-taste-frontend` tem ~87 KB (~35 mil
|
||||
tokens por carga, medido com `claude plugin details`): carregue só para UI nova, não para ajuste pontual.
|
||||
|
||||
Licença CC-BY-4.0 (OWASP/secure-agent-playbook) exige atribuição — mantida
|
||||
via a tabela acima e o link direto ao repo original em cada menção nos
|
||||
@@ -62,7 +62,8 @@ nos caminhos: as referências `../../../schemas/…` e `../../../docs/…`
|
||||
apontavam para a raiz do repo de origem, que tinha um nível a mais
|
||||
(`skills/<categoria>/<skill>/`). Como aqui o diretório é plano
|
||||
(`skills/<skill>/`), os links foram ajustados para o caminho relativo dentro
|
||||
da própria skill, que é o que sobrevive a `cp -r skills/* ~/.hermes/skills/`.
|
||||
da própria skill, que é o que sobrevive quando a pasta da skill é copiada sozinha (plugin,
|
||||
`scripts/install.py opencode` ou `hermes`).
|
||||
|
||||
## Lacunas conhecidas
|
||||
|
||||
|
||||
@@ -1,6 +1,11 @@
|
||||
---
|
||||
name: dev-router
|
||||
description: Use no início de qualquer pedido de código (feature, bug, refactor, UI, API, migração, review; "implement", "fix", "build", "add", "change"). Classifica o pedido em nível 0 a 3 e decide quais workflows, agentes e checagens rodar, para um pedido pequeno não pagar o custo de um grande.
|
||||
license: MIT
|
||||
metadata:
|
||||
dev-workflows:
|
||||
uses: [lean-code, wf-bugfix, wf-refactor, wf-frontend, wf-backend, wf-architecture, wf-security-review, safedeps]
|
||||
external: []
|
||||
---
|
||||
|
||||
# Dev Router
|
||||
|
||||
@@ -1,6 +1,11 @@
|
||||
---
|
||||
name: lean-code
|
||||
description: Use sempre que for escrever ou mudar código. Escolhe a menor solução que resolve de verdade - reaproveitar antes de escrever, apagar antes de somar, sem abstração especulativa e sem dependência desnecessária.
|
||||
license: MIT
|
||||
metadata:
|
||||
dev-workflows:
|
||||
uses: [safedeps]
|
||||
external: []
|
||||
---
|
||||
|
||||
# Lean Code
|
||||
|
||||
+75
-262
@@ -1,294 +1,107 @@
|
||||
---
|
||||
name: wf-architecture
|
||||
description: "Use p/ arquitetura. Fluxo REQ→DESIGN→DOCS→REVIEW."
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
description: Use para decisões de arquitetura - desenho de sistema ou serviço novo, escolha de stack, mudança de fronteira entre módulos, migração com dado existente, troca de auth, diagrama C4, ADR, threat model, "isso é uma boa ideia arquitetonicamente?". É o workflow do nível 3 do dev-router (e do nível 2 quando surge uma decisão difícil de desfazer). Não use para bug, refactor local, tela ou endpoint isolado sem decisão estrutural (use wf-bugfix, wf-refactor, wf-frontend ou wf-backend).
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [architecture, design, c4, adr, arc42, threat-model, workflow]
|
||||
dev-workflows:
|
||||
uses: []
|
||||
external: [system-design, c4-architecture, isaqb-architecture-governance, secure-architecture-governance]
|
||||
---
|
||||
|
||||
# Workflow Arquitetura
|
||||
|
||||
Orquestrador obrigatório para todo trabalho de arquitetura: desenho de
|
||||
sistemas, decisões (ADR), diagramas C4, threat modeling, revisão de
|
||||
arquitetura. Processo de 4 fases com skills fixas.
|
||||
**Nível 3** do `dev-router`, ou nível 2 quando aparece uma decisão difícil de desfazer (banco,
|
||||
protocolo, fronteira de serviço, modelo de auth). No nível 2, faça só a Fase 3 (um ADR para a decisão)
|
||||
e siga com `wf-backend`/`wf-frontend`. Abaixo disso, este workflow não roda.
|
||||
|
||||
## When to Use
|
||||
Cada fase produz um arquivo versionado. O que não virou arquivo não foi decidido.
|
||||
|
||||
Sempre que a tarefa envolver: arquitetura/design de sistema, escolha de
|
||||
stack, diagramas, ADR, threat model, revisão estrutural, ou "é uma boa
|
||||
ideia arquitetonicamente?".
|
||||
Skills externas, se instaladas: `system-design` (raciocínio de design), `c4-architecture` (diagramas),
|
||||
`isaqb-architecture-governance` (arc42 e ADR), `secure-architecture-governance` (STRIDE e S-ADR).
|
||||
Sem elas, os modelos em [references/](references/) bastam.
|
||||
|
||||
## Skills do stack (carregar conforme a fase)
|
||||
## Fase 1: REQUIREMENTS
|
||||
|
||||
- Design de sistema (raciocínio): `system-design` (HelloInterview framework)
|
||||
- Diagramas: `c4-architecture` (Context/Container/Component/Deployment)
|
||||
- Documentação: `isaqb-architecture-governance` (arc42 + ADR)
|
||||
- Segurança: `secure-architecture-governance` (STRIDE+CIA, S-ADR)
|
||||
- Qualidade de documentação: `avoid-ai-writing` (remove AI-isms de ADRs,
|
||||
docs de arquitetura, RFCs — registros que vão durar anos não devem soar
|
||||
gerados por IA)
|
||||
- Locais: `security-threat-model`, `architecture-diagram` (SVG),
|
||||
`excalidraw`, `brainstorming`, `writing-plans`
|
||||
Entender antes de desenhar. Use o agente `planner` com o mapa do `explorer`.
|
||||
|
||||
## Fase 1 — REQUIREMENTS (entender antes de desenhar)
|
||||
1. Requisitos funcionais em **EARS com ID** (`REQ-001: WHEN ... THE SYSTEM SHALL ...`).
|
||||
Modelo e padrões: [references/ears.md](references/ears.md).
|
||||
2. Não funcionais **com número**: SLO (ex.: p95 < 250 ms, 99,9% ao mês), orçamento de performance
|
||||
(LCP, tamanho de bundle, custo mensal), nível ASVS 5.0 (L2 por padrão no nível 3).
|
||||
"Rápido" ou "escalável" sem número não é requisito.
|
||||
3. Atores, entidades centrais e fronteiras de confiança.
|
||||
4. Stack ou framework novo: consulte a documentação atual e registre URL e data. Não decida pela memória.
|
||||
|
||||
1. `brainstorming` — explorar intenção, requisitos funcionais e NFRs
|
||||
(latência, escala, disponibilidade, custo) antes de qualquer desenho.
|
||||
2. Identificar entidades centrais, limites, fluxos de dados e atores.
|
||||
3. Estado da arte: checar evolução/relevância de stack/framework.
|
||||
4. VERIFICAR: rodar `hermaguard` conceitual no escopo (o que pode dar
|
||||
errado com esta arquitetura?) e validar com o usuário que cada NFR é
|
||||
mensurável (ex: "p95 < 250ms" e não "rápido").
|
||||
5. Checkpoint: listar requisitos validados e SÓ seguir ao DESIGN com
|
||||
aprovação explícita.
|
||||
6. VERIFICAR (comandos de requisitos): escrever FRs/NFRs em
|
||||
`docs/requirements.md` e rodar `grep -c "NFR" docs/requirements.md`
|
||||
para garantir que TODOS os NFRs viraram critério mensurável.
|
||||
7. VERIFICAR (cobertura): usar `search_files` para confirmar que nenhum
|
||||
requisito levantado ficou órfão (cada FR/NFR tem dono e número).
|
||||
8. VERIFICAR (comandos de estado da arte): consultar fontes atuais para
|
||||
stack/framework antes de decidir — usar `web_search`/consultas técnicas
|
||||
e registrar URL + data no requirements.md (não decidir stack do nada).
|
||||
9. VERIFICAR (pontos de risco): listar os 3 maiores riscos técnicos do
|
||||
escopo e checar com `hermaguard` conceitual se algum deles muda a
|
||||
decisão de arquitetura — risco conhecido não vira surpresa depois.
|
||||
10. CHECKPOINT final da Fase 1: apresentar requisitos para aprovação; sem
|
||||
OK explícito não avança para DESIGN.
|
||||
11. VERIFICAR (comandos de requisitos): `python3 -c "import yaml,sys; yaml.safe_load(open('docs/requirements.md'))"` se requisitos em YAML
|
||||
(ou parser equivalente) para provar que o formato é válido; e
|
||||
`curl -s -o /dev/null -w "%{http_code}" URL` quando houver fonte
|
||||
externa de referência citada.
|
||||
12. VERIFICAR (critério de requisito): conferir que cada requisito tem
|
||||
"critério de aceite" ou número alvo — sem requisito "aberto" sem
|
||||
definição de pronto.
|
||||
**Artefato:** `docs/specs/<nome>.md` com os `REQ-` e os não funcionais.
|
||||
**Gate da fase:** o usuário aprova a spec antes do DESIGN.
|
||||
|
||||
**Checklist da fase 1 (validar requisitos):**
|
||||
- [ ] Requisitos funcionais e NFRs (latência, escala, disponibilidade, custo)
|
||||
coletados e mensuráveis (ex: "p95 < 250ms" ao invés de "rápido").
|
||||
- [ ] Entidades centrais, limites e atores identificados.
|
||||
- [ ] Estado da arte de stack/framework verificado.
|
||||
- [ ] Requisitos aprovados pelo usuário antes de desenhar.
|
||||
Rastreabilidade: adicione ao `.dev-workflows.toml` do projeto
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NUNCA desenhar sem requisito mensurável.
|
||||
- NUNCA inventar NFR ("ser escalável") — exigir número e critério.
|
||||
- NÃO pular a aprovação do usuário para "andar logo".
|
||||
- NÃO decidir stack antes de validar requisitos (viés de ferramenta).
|
||||
|
||||
## Fase 2 — DESIGN (modelar o sistema)
|
||||
|
||||
1. `system-design` — percorrer o framework: requisitos → entidades → API →
|
||||
data flow → high-level design → deep dives. Documentar trade-offs.
|
||||
2. `c4-architecture` — gerar diagramas (Context → Container → Component)
|
||||
em Mermaid/Structurizr. Declarar elementos em ordem de leitura, evitar
|
||||
cruzamentos (research-backed).
|
||||
3. `secure-architecture-governance` — mapear trust boundaries e rodar
|
||||
STRIDE+CIA nas decisões de segurança (auth, dados sensíveis).
|
||||
4. VERIFICAR: rodar `c4-architecture` de novo para audit — cada diagrama
|
||||
tem IDs estáveis, setas com rótulo e <=20 elementos por view? Validar
|
||||
com o usuário antes de documentar.
|
||||
5. VERIFICAR (comandos de design): se Structurizr, validar com
|
||||
`python3 -c "import json; json.load(open('workspace.json'))"` que o
|
||||
modelo é parseável; para Mermaid, conferir que os blocos ```mermaid
|
||||
fecham corretamente (contar crases ímpares = erro).
|
||||
6. VERIFICAR (trade-offs): `grep -c "alternativa" docs/design.md` — cada
|
||||
decisão tem pelo menos 1 alternativa documentada com o porquê?
|
||||
7. VERIFICAR (limites): `grep -n "boundary\|trust" docs/design.md` —
|
||||
trust boundaries explícitos nos diagramas; todo fluxo de dado sensível
|
||||
cruza boundary documentada.
|
||||
8. VERIFICAR (comandos de render): se Mermaid, rodar `npx @mermaid-js/mermaid-cli -i d.mmd -o d.svg` (ou Playwright) para provar que o
|
||||
diagrama renderiza sem erro de sintaxe.
|
||||
9. VERIFICAR (comandos de contagem): `grep -c "component\|container" docs/c4.md` — todo container mapeado tem representação; `wc -l docs/c4.md > 10` garante diagrama não-vazio.
|
||||
10. VERIFICAR (critério de design): confirmar com o usuário que cada view
|
||||
reflete os requisitos da Fase 1 (rastreabilidade view→requisito) e
|
||||
que os trade-offs estão anotados — sem view "solta".
|
||||
|
||||
**Checklist da fase 2 (validar o modelo):**
|
||||
- [ ] `system-design` percorrido: requisitos → entidades → API → data flow →
|
||||
high-level → deep dives.
|
||||
- [ ] Diagramas C4 (Context → Container → Component) com IDs estáveis, setas
|
||||
rotuladas e <=20 elementos por view.
|
||||
- [ ] Trust boundaries mapeados; STRIDE+CIA aplicado nas decisões sensíveis.
|
||||
- [ ] Trade-offs documentados (as 2 soluções alternativas + por quê a escolha).
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NUNCA diagramar sem requisitos (Fase 1) — diagrama sem base vira enfeite.
|
||||
- NUNCA deixar seta sem rótulo ou elemento sem ID estável.
|
||||
- NÃO desenhar >20 elementos por view (ilegível = não é documento).
|
||||
- NÃO ignorar trust boundary ao desenhar fluxo de dados sensível.
|
||||
|
||||
## Fase 3 — DOCS (decisões em registros)
|
||||
|
||||
1. `isaqb-architecture-governance` — criar ADR (e S-ADR se decisão for
|
||||
security-driven) com alternativas e consequências. ID estável e
|
||||
reutilizado nos diagramas/docs.
|
||||
2. `avoid-ai-writing` — pós-escrever QUALQUER doc/ADR/RFC: detect+rewrite
|
||||
dos AI-isms (tiers 1/2/3, em-dash, "crucial", "robust", transições
|
||||
genéricas). Arquitetura documentada é lida por anos — não deve soar IA.
|
||||
3. Estrutura de saída: `docs/architecture/` (ADRs, views arc42) e
|
||||
`docs/security/` (S-ADRs, threat models) — sem colisão de nomes.
|
||||
4. NFRs virarem critérios mensuráveis (não frase de efeito).
|
||||
5. VERIFICAR: rodar `avoid-ai-writing` em modo detect em cada ADR (0 AI-isms
|
||||
restantes), confirmar arquivos criados em `docs/architecture/adr/` e
|
||||
`docs/security/adr/` e conferir que IDs de ADR/S-ADR são únicos.
|
||||
6. VERIFICAR (comandos de docs): `ls docs/architecture/adr/ docs/security/adr/`
|
||||
para listar os registros criados e `grep -rL "Consequências" docs/` para
|
||||
achar ADR que esqueceu a seção de consequências.
|
||||
7. VERIFICAR (rastreabilidade): `grep -rc "AD-...-NNN" docs/architecture/`
|
||||
— cada ADR aparece referenciado em pelo menos um diagrama ou decision log.
|
||||
8. VERIFICAR (comandos de docs): confirmar com `find docs/ -name "*.md" -o -name "*.mmd" | sort` que a árvore está organizada; e `wc -l docs/architecture/adr/*.md` para garantir ADR com corpo (não só título).
|
||||
9. VERIFICAR (estilo consistente): `grep -rn "em dash\|—" docs/architecture/adr/ | wc -l` — em-dash em excesso = AI-ism residual (rodar avoid-ai-writing).
|
||||
10. VERIFICAR (comandos de validação de docs): `python3 -m json.tool docs/workspace.json > /dev/null` para Structurizr; `curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/...` se houver visualização local; e `git diff --stat docs/` para conferir o que foi documentado.
|
||||
11. VERIFICAR (critério de aceite de doc): cada ADR responde "por que essa decisão?" e lista consequências — `grep -L "Consequências" docs/architecture/adr/*.md` deve ser vazio.
|
||||
|
||||
**Checklist da fase 3 (documentação):**
|
||||
- [ ] ADR (ou S-ADR se security-driven) criado com alternativas + consequências.
|
||||
- [ ] `avoid-ai-writing` em detect = 0 em cada ADR/RFC.
|
||||
- [ ] Arquivos em `docs/architecture/adr/` e `docs/security/adr/`; IDs únicos.
|
||||
- [ ] NFRs viram critérios mensuráveis no documento (não frase solta).
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NUNCA publicar ADR sem alternativas consideradas.
|
||||
- NUNCA publicar doc com AI-isms não tratados.
|
||||
- NÃO criar 2 ADRs para a mesma decisão; NÃO duplicar decisão geral e S-ADR.
|
||||
- NÃO deixar ID solto (decisão precisa ser rastreável ao diagrama/código).
|
||||
|
||||
## Fase 4 — REVIEW (verificar antes de aprovar)
|
||||
|
||||
1. `secure-architecture-governance` — auditar decisões contra ISO/IEC
|
||||
25010 (performance, segurança, confiabilidade, manutenibilidade).
|
||||
2. Threat model final + gaps de trust boundary (unauthenticated internal
|
||||
paths, implicit service trust) priorizados.
|
||||
3. Checar consistência: IDs batem entre diagramas, ADRs e docs?
|
||||
4. Verdict objetivo: Approved / Approved-with-changes / Needs-revision,
|
||||
com evidência por finding — não gosto pessoal.
|
||||
5. VERIFICAR (gate final): rodar `secure-architecture-governance` como
|
||||
checklist, validar a árvore de arquivos com `search_files`, e dar o
|
||||
verdict com base na evidência — se houver gap de security, reverter ao
|
||||
DESIGN.
|
||||
6. VERIFICAR (comandos de revisão): usar `grep -r "AD-...-NNN" docs/` para
|
||||
provar que IDs aparecem nos diagramas, e `git status` para conferir que
|
||||
tudo que foi modelado virou arquivo versionado.
|
||||
7. VERIFICAR (anti-slop de docs): rodar `node .../avoid-ai-writing/detector/validate.js`
|
||||
nos ADRs e `test_quality.py` no workflow — sem regressão.
|
||||
8. VERIFICAR (todos os arquivos versionados): `git status --porcelain` deve
|
||||
mostrar só o esperado; `find docs/ -name "*.md" | wc -l` confere a
|
||||
contagem de docs criados vs planejados na Fase 1.
|
||||
9. VERIFICAR (comandos de evidência por finding): para cada finding,
|
||||
`grep -rn "<id-do-finding>" docs/security/` deve retornar a evidência —
|
||||
sem achado "sem referência".
|
||||
10. VERIFICAR (conclusão): `git diff --stat` + `git status` para conferir
|
||||
o que o ciclo produziu; nada de diagrama/doc não versionado sendo
|
||||
citado como entregue.
|
||||
11. VERIFICAR (comandos de revisão final): rodar `python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py` (gate) e conferir o
|
||||
`git diff --stat` — a revisão só fecha com gate verificado e sem
|
||||
pendências de arquivo.
|
||||
12. VERIFICAR (não-regressão de nomes): conferir que nenhuma skill do stack
|
||||
foi renomeada/quebrada — rodar o harness (G4) e `test_tests.py`.
|
||||
|
||||
**Checklist da fase 4 (revisão):**
|
||||
- [ ] Auditoria contra ISO/IEC 25010 por decisão (performance, segurança,
|
||||
confiabilidade, manutenibilidade).
|
||||
- [ ] Threat model final com gaps de trust boundary priorizados.
|
||||
- [ ] Consistência de IDs: diagramas × ADRs × docs batem.
|
||||
- [ ] Verdict objetivo emitido: Approved / Approved-with-changes /
|
||||
Needs-revision, com evidência por finding.
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NUNCA dar verdict "approved" sem evidência em cada finding.
|
||||
- NUNCA ignorar gap de trust boundary (unauthenticated internal path).
|
||||
- NÃO confundir opinião estética com achado — achado exige referência.
|
||||
- NÃO deixar segurança como "nota mental" — virar S-ADR ou finding listado.
|
||||
|
||||
## Comandos de Verificação (executáveis)
|
||||
|
||||
```bash
|
||||
# Gate de qualidade do próprio workflow (sem regressão)
|
||||
python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py
|
||||
|
||||
# Verifica consistência da documentação (IDs estáveis em diagramas/docs)
|
||||
# (skill isaqb-architecture-governance + c4-architecture)
|
||||
|
||||
# Threat model: auditoria STRIDE+CIA contra ISO 25010
|
||||
# (skill secure-architecture-governance)
|
||||
|
||||
# Audit de AI-isms nos ADRs/RFCs (detect = só mostra)
|
||||
node ~/.hermes/skills/avoid-ai-writing/detector/validate.js adr.md adr-limp.md
|
||||
```toml
|
||||
[spec]
|
||||
file = "docs/specs/<nome>.md"
|
||||
tests = ["tests"]
|
||||
```
|
||||
|
||||
## Critérios de Aceite (checklist não-regressivo)
|
||||
e o gate nível 3 falha se algum `REQ-` não aparecer em um teste
|
||||
(ver `skills/dev-router/references/quality-gate.md`).
|
||||
|
||||
- [ ] Fase 1 concluída com requisitos/NFRs mensuráveis aprovados pelo usuário.
|
||||
- [ ] Fase 2 gerou diagramas C4 com IDs estáveis e rótulos; validados.
|
||||
- [ ] Fase 3 gerou ADR/S-ADR em `docs/architecture/` e `docs/security/`;
|
||||
`avoid-ai-writing` detect = 0 AI-isms.
|
||||
- [ ] Fase 4 auditou contra ISO 25010 + threat model; verdict emitido.
|
||||
- [ ] Nenhuma skill do stack removida do arquivo.
|
||||
- [ ] Rodar `python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py`
|
||||
→ exit 0 (sem regressão).
|
||||
## Fase 2: DESIGN
|
||||
|
||||
## Exemplos de execução por fase (comandos reais)
|
||||
1. Fluxo de design: requisitos, entidades, API, fluxo de dados, visão geral, pontos críticos.
|
||||
2. **C4** em Mermaid: Context e Container sempre; Component só onde houver decisão.
|
||||
Até 20 elementos por view, setas rotuladas, IDs estáveis. Modelo: [references/c4.md](references/c4.md).
|
||||
3. Modelo de dados e estratégia de migração (reversível; com dado existente, plano de backfill e rollback).
|
||||
4. **Pelo menos uma alternativa** por decisão importante, com o motivo da escolha.
|
||||
|
||||
Fase 1 — requisitos estruturados:
|
||||
**Artefato:** `docs/architecture/design.md` com os diagramas.
|
||||
Confira que o Mermaid renderiza: `npx -y @mermaid-js/mermaid-cli -i docs/architecture/c4.mmd -o /tmp/c4.svg`.
|
||||
|
||||
```bash
|
||||
cat > docs/requirements.md <<'EOF'
|
||||
# Requisitos
|
||||
FR1: usuário cria e gerencia listas
|
||||
NFR1: p95 < 250ms (API)
|
||||
NFR2: disponibilidade 99.9%
|
||||
NFR3: custo mensal < R$ 500
|
||||
EOF
|
||||
```
|
||||
## Fase 3: DOCS (ADR)
|
||||
|
||||
Fase 2 — diagrama C4 (definir estrutura antes):
|
||||
Um ADR por decisão difícil de desfazer: contexto, opções, decisão, consequências (boas e ruins).
|
||||
Modelo: [references/adr.md](references/adr.md).
|
||||
|
||||
```bash
|
||||
# Estrutura do C4 em texto (depois renderizar com c4-architecture/Mermaid)
|
||||
cat > docs/c4.md <<'EOF'
|
||||
Context: [Usuário] -> [Sistema X]
|
||||
Container: [Web] -> [API] -> [Postgres] -> [Redis]
|
||||
EOF
|
||||
```
|
||||
- `docs/architecture/adr/NNNN-<titulo>.md`, numeração sequencial, nunca reescrever um ADR aceito
|
||||
(substitua por um novo com `Substitui: ADR-NNNN`).
|
||||
- Decisão motivada por segurança vira S-ADR em `docs/security/adr/`.
|
||||
- Todo ADR citado no design (`ADR-0003`) existe como arquivo.
|
||||
|
||||
Fase 3 — ADR curto:
|
||||
## Fase 4: THREAT MODEL
|
||||
|
||||
```bash
|
||||
# Criar ADR em docs/architecture/adr/0001-*.md (isaqb-architecture-governance)
|
||||
# S-ADR em docs/security/adr/ quando a decisão for security-driven
|
||||
```
|
||||
STRIDE por fronteira de confiança, cada ameaça ligada a um controle ASVS 5.0 L2.
|
||||
Tabela e mapeamento: [references/stride.md](references/stride.md).
|
||||
|
||||
Fase 4 — validação do conjunto:
|
||||
1. Liste as fronteiras (internet/app, app/banco, serviço/serviço, app/terceiros, app/LLM).
|
||||
2. Para cada fronteira, as seis categorias STRIDE: ameaça concreta, controle, capítulo ASVS, status.
|
||||
3. Caminhos internos sem autenticação e confiança implícita entre serviços são achados, não detalhes.
|
||||
4. Feature que chama LLM: inclua OWASP LLM Top 10 (prompt injection, excessive agency).
|
||||
|
||||
```bash
|
||||
# Consistência de IDs entre diagramas, ADRs e docs (search_files)
|
||||
grep -r "ADR-" docs/ | wc -l # cada referência existe
|
||||
grep -rn "S-ADR" docs/security/ | wc -l # decisões security-driven têm S-ADR
|
||||
# "audite a arquitetura" (secure-architecture-governance: ISO 25010)
|
||||
python3 -m json.tool docs/workspace.json > /dev/null # Structurizr válido?
|
||||
# "rode o avoid-ai nos ADRs" (modo detect)
|
||||
node ~/.hermes/skills/avoid-ai-writing/detector/validate.js adr.md adr-limp.md
|
||||
find docs/ -name "*.md" -o -name "*.mmd" | sort # árvore organizada
|
||||
```
|
||||
**Artefato:** `docs/security/threat-model.md`.
|
||||
|
||||
Gates do workflow (anti-regressão):
|
||||
## Fase 5: REVIEW
|
||||
|
||||
```bash
|
||||
python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py
|
||||
python3 ~/.hermes/skills/software-development/wf-qa/test_tests.py
|
||||
```
|
||||
1. Agente `reviewer` sobre spec, design e ADRs: consistência entre `REQ-`, diagramas e ADRs,
|
||||
requisito sem dono, decisão sem alternativa.
|
||||
2. Agente `security-auditor` sobre o threat model e as decisões de segurança.
|
||||
3. Veredito por escrito: `Aprovado`, `Aprovado com mudanças` ou `Revisar`, cada achado com evidência
|
||||
(arquivo e trecho). Gap de fronteira de confiança volta para o DESIGN.
|
||||
4. O usuário aprova. A implementação segue com `wf-backend`/`wf-frontend`, tarefa a tarefa,
|
||||
e fecha com `"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier 3`.
|
||||
|
||||
## Regras duras
|
||||
## Não faça
|
||||
|
||||
- NUNCA diagramar antes de requisitos claros (Fase 1).
|
||||
- NUNCA entregar ADR sem alternativas consideradas e consequências.
|
||||
- NUNCA publicar ADR/RFC/doc com AI-isms não tratados (passar por
|
||||
`avoid-ai-writing` antes de dar como entregue).
|
||||
- Decisão com load-bearing security → S-ADR em `docs/security/`, nunca nos
|
||||
ADRs gerais.
|
||||
- Diagrama tem que ter declaração em ordem de leitura + alvo de
|
||||
cruzamentos — legibilidade é requisito, não luxo.
|
||||
- Desenhar antes de ter requisito mensurável.
|
||||
- ADR sem alternativa ou sem consequências.
|
||||
- Mais de um ADR para a mesma decisão.
|
||||
- Tratar segurança como nota mental: vira ameaça no threat model ou S-ADR.
|
||||
- Decidir stack sem fonte atual.
|
||||
|
||||
## Checklist de entrega
|
||||
|
||||
- [ ] `docs/specs/<nome>.md` com `REQ-` em EARS e não funcionais com número, aprovado pelo usuário.
|
||||
- [ ] `[spec]` no `.dev-workflows.toml` do projeto.
|
||||
- [ ] `docs/architecture/design.md` com C4 que renderiza e alternativas registradas.
|
||||
- [ ] Um ADR por decisão difícil de desfazer, com consequências.
|
||||
- [ ] `docs/security/threat-model.md` com STRIDE por fronteira e controles ASVS L2.
|
||||
- [ ] Revisão do `reviewer` e do `security-auditor` com veredito e evidência.
|
||||
@@ -0,0 +1,31 @@
|
||||
# Modelo de ADR
|
||||
|
||||
Arquivo: `docs/architecture/adr/NNNN-titulo-curto.md` (S-ADR de segurança em `docs/security/adr/`).
|
||||
Numeração sequencial. ADR aceito não é reescrito: uma decisão nova cria outro ADR com `Substitui:`.
|
||||
|
||||
```markdown
|
||||
# ADR-0003: PostgreSQL como banco de pedidos
|
||||
|
||||
- Status: proposto | aceito | substituído por ADR-NNNN
|
||||
- Data: 2026-09-24
|
||||
- Requisitos: REQ-002, REQ-010
|
||||
- Substitui: (se houver)
|
||||
|
||||
## Contexto
|
||||
O que força a decisão agora. Restrições reais (volume, equipe, custo, prazo), com números.
|
||||
|
||||
## Opções
|
||||
1. PostgreSQL gerenciado: prós, contras.
|
||||
2. MongoDB: prós, contras.
|
||||
3. Manter o SQLite atual: prós, contras.
|
||||
|
||||
## Decisão
|
||||
A opção escolhida e o motivo principal, em duas ou três frases.
|
||||
|
||||
## Consequências
|
||||
- Boas: o que fica mais fácil.
|
||||
- Ruins: o que fica mais difícil ou caro, e o que foi aceito conscientemente.
|
||||
- Como desfazer, se precisar, e quanto custa.
|
||||
```
|
||||
|
||||
Um ADR por decisão. Se duas decisões dependem uma da outra, dois ADRs que se referenciam.
|
||||
@@ -0,0 +1,45 @@
|
||||
# C4 em Mermaid
|
||||
|
||||
Regras: até 20 elementos por view, toda seta com rótulo (o que trafega e por qual protocolo),
|
||||
IDs estáveis reaproveitados em ADRs e no threat model, declaração na ordem de leitura
|
||||
(de quem usa para o que é usado).
|
||||
|
||||
## Context
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
title Contexto: Sistema de Pedidos
|
||||
Person(cliente, "Cliente", "Compra pelo site")
|
||||
System(pedidos, "Sistema de Pedidos", "Cria e acompanha pedidos")
|
||||
System_Ext(pagamento, "Gateway de pagamento", "Cobra o cartão")
|
||||
Rel(cliente, pedidos, "Cria pedido", "HTTPS")
|
||||
Rel(pedidos, pagamento, "Autoriza cobrança", "HTTPS/REST")
|
||||
```
|
||||
|
||||
## Container
|
||||
|
||||
```mermaid
|
||||
C4Container
|
||||
title Containers: Sistema de Pedidos
|
||||
Person(cliente, "Cliente")
|
||||
System_Boundary(sp, "Sistema de Pedidos") {
|
||||
Container(web, "Web", "Next.js", "Interface")
|
||||
Container(api, "API", "FastAPI", "Regras de pedido")
|
||||
ContainerDb(db, "Banco", "PostgreSQL", "Pedidos e itens")
|
||||
Container(worker, "Worker", "Celery", "Cobrança assíncrona")
|
||||
}
|
||||
System_Ext(pagamento, "Gateway de pagamento")
|
||||
Rel(cliente, web, "Usa", "HTTPS")
|
||||
Rel(web, api, "Chama", "HTTPS/JSON")
|
||||
Rel(api, db, "Lê e grava", "SQL/TLS")
|
||||
Rel(api, worker, "Enfileira cobrança", "Redis")
|
||||
Rel(worker, pagamento, "Autoriza", "HTTPS")
|
||||
```
|
||||
|
||||
## Render
|
||||
|
||||
```bash
|
||||
npx -y @mermaid-js/mermaid-cli -i docs/architecture/c4.mmd -o /tmp/c4.svg
|
||||
```
|
||||
|
||||
Se o comando falhar, o diagrama tem erro de sintaxe e não está pronto.
|
||||
@@ -0,0 +1,35 @@
|
||||
# EARS: requisitos com ID
|
||||
|
||||
EARS (Easy Approach to Requirements Syntax) força cada requisito a ter gatilho e resposta
|
||||
verificáveis. Um requisito por linha, ID estável `REQ-NNN`, nunca reaproveitado.
|
||||
|
||||
| Padrão | Forma | Exemplo |
|
||||
|---|---|---|
|
||||
| Ubíquo | THE SYSTEM SHALL <resposta> | `REQ-001: THE SYSTEM SHALL registrar toda alteração de preço com autor e data.` |
|
||||
| Evento | WHEN <evento> THE SYSTEM SHALL <resposta> | `REQ-002: WHEN o usuário envia o formulário de cadastro THE SYSTEM SHALL responder 201 com o ID criado.` |
|
||||
| Indesejado | IF <condição> THEN THE SYSTEM SHALL <resposta> | `REQ-003: IF o token expirou THEN THE SYSTEM SHALL responder 401 sem revelar se a conta existe.` |
|
||||
| Estado | WHILE <estado> THE SYSTEM SHALL <resposta> | `REQ-004: WHILE a fila tiver mais de 1000 itens THE SYSTEM SHALL recusar novos jobs com 429.` |
|
||||
| Opcional | WHERE <recurso> THE SYSTEM SHALL <resposta> | `REQ-005: WHERE o SSO estiver habilitado THE SYSTEM SHALL ocultar o login por senha.` |
|
||||
|
||||
## Não funcionais
|
||||
|
||||
Mesmo formato de ID, sempre com número e forma de medir:
|
||||
|
||||
```
|
||||
REQ-010: THE SYSTEM SHALL responder GET /orders em p95 < 250 ms com 200 req/s (medido com k6).
|
||||
REQ-011: THE SYSTEM SHALL manter 99,9% de disponibilidade mensal (SLO no monitoramento).
|
||||
REQ-012: THE SYSTEM SHALL atender ASVS 5.0 nível L2 nos capítulos de autenticação e sessão.
|
||||
REQ-013: THE SYSTEM SHALL carregar a página inicial com LCP <= 2,5 s e INP <= 200 ms (Lighthouse CI).
|
||||
```
|
||||
|
||||
## Rastreabilidade
|
||||
|
||||
Cada teste cita o ID que prova, no nome ou num comentário:
|
||||
|
||||
```python
|
||||
def test_req_003_token_expirado_retorna_401():
|
||||
...
|
||||
```
|
||||
|
||||
Com `[spec]` no `.dev-workflows.toml`, o gate nível 3 falha se algum `REQ-` da spec não aparecer
|
||||
em nenhum arquivo de teste.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Threat model STRIDE com ASVS 5.0
|
||||
|
||||
Arquivo: `docs/security/threat-model.md`. Uma tabela por fronteira de confiança.
|
||||
|
||||
## Categorias e onde procurar o controle no ASVS 5.0
|
||||
|
||||
| STRIDE | Ameaça típica | Capítulos ASVS 5.0 para o controle |
|
||||
|---|---|---|
|
||||
| Spoofing (identidade falsa) | login forjado, token roubado, serviço se passando por outro | Autenticação, Gerenciamento de sessão, Tokens autocontidos |
|
||||
| Tampering (adulteração) | parâmetro alterado, mensagem na fila modificada, upload malicioso | Validação e lógica de negócio, Manipulação de arquivos, Comunicação segura |
|
||||
| Repudiation (negação) | ação sensível sem rastro | Log e tratamento de erro |
|
||||
| Information disclosure (vazamento) | IDOR, stack trace na resposta, segredo em log | Autorização, Proteção de dados, Log e tratamento de erro |
|
||||
| Denial of service | endpoint sem limite, query sem paginação, arquivo gigante | Validação e lógica de negócio (limites), Manipulação de arquivos |
|
||||
| Elevation of privilege | usuário comum chega em rota de admin, injeção de comando | Autorização, Codificação e sanitização |
|
||||
|
||||
Os nomes dos capítulos seguem o ASVS 5.0 (maio de 2025). Cite o requisito exato (`V<cap>.<seção>.<item>`)
|
||||
consultando https://github.com/OWASP/ASVS, não pela memória.
|
||||
|
||||
## Modelo por fronteira
|
||||
|
||||
```markdown
|
||||
## Fronteira: Internet -> API
|
||||
|
||||
| # | STRIDE | Ameaça concreta | Controle | ASVS | Status |
|
||||
|---|---|---|---|---|---|
|
||||
| T1 | S | Token JWT aceito com alg none | Validar alg fixo e assinatura | Tokens autocontidos | ok |
|
||||
| T2 | I | GET /orders/{id} devolve pedido de outro cliente | Query escopada ao usuário autenticado | Autorização | pendente |
|
||||
| T3 | D | POST /orders sem limite de taxa | Rate limit por usuário e IP | Validação e lógica de negócio | pendente |
|
||||
```
|
||||
|
||||
Fronteiras que costumam faltar: serviço interno sem autenticação ("está na rede privada"),
|
||||
worker que confia em qualquer mensagem da fila, integração com LLM (prompt injection, ferramenta
|
||||
com permissão demais: OWASP LLM01 e LLM06).
|
||||
|
||||
Status `pendente` em ameaça alta bloqueia a aprovação da Fase 5.
|
||||
+65
-253
@@ -1,281 +1,93 @@
|
||||
---
|
||||
name: wf-backend
|
||||
description: "Use p/ backend/API. Fluxo PLAN→BUILD→SECURITY→TEST."
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
description: Use para trabalho de backend e API - endpoint REST/GraphQL, autenticação, schema e migração de banco, integração, fila, webhook, job. Contrato antes do handler, defaults seguros, auditoria OWASP e gate de qualidade no nível que o dev-router definiu. Não use para UI (wf-frontend), para correção pontual sem mudança de contrato (wf-bugfix) nem para desenho de sistema com vários serviços (wf-architecture primeiro).
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [backend, api, security, rest, sql, auth, workflow]
|
||||
dev-workflows:
|
||||
uses: [api-security-review, safedeps, sca-audit, secrets-scan, hermaguard]
|
||||
external: [secure-coding, bola-detector, auth-rbac-scaffold, injection-checker, openapi-hardener, security-test-generator]
|
||||
---
|
||||
|
||||
# Workflow Backend/API
|
||||
|
||||
Orquestrador obrigatório para TODO trabalho backend: APIs REST/GraphQL,
|
||||
autenticação, banco de dados, integrações, serviços, jobs. Processo de 4
|
||||
fases com skills fixas.
|
||||
O `dev-router` define o nível. Cada fase diz a partir de qual nível roda. No nível 1, a mudança segue
|
||||
o `wf-bugfix` (ou `wf-refactor`) com as regras de build seguro abaixo e o gate `--tier 1`.
|
||||
|
||||
## When to Use
|
||||
## Fase 1: PLAN, contrato antes do código (nível 2+)
|
||||
|
||||
Sempre que a tarefa envolver servidor: criar/editar endpoints, auth, schema
|
||||
DB, integrações, filas, webhooks, ou revisar segurança de backend/models.
|
||||
Nível 0 e 1 pulam esta fase. No nível 3, o `planner` escreve a spec EARS e esta fase vira a parte de
|
||||
API dela.
|
||||
|
||||
## Skills do stack (carregar conforme a fase)
|
||||
1. `explorer` mapeia rotas, modelos e validações que já existem. Reaproveite antes de criar.
|
||||
2. Contrato em `docs/contract.md` ou OpenAPI: rotas, métodos, payloads, status codes, erros em
|
||||
RFC 9457 (`application/problem+json`), paginação, rate limit e versionamento.
|
||||
3. Schemas validados na borda (Zod, Pydantic, OpenAPI). `openapi-hardener`, se instalado, saneia.
|
||||
4. Modelo de dados e migração desenhados antes da query: idempotente e reversível.
|
||||
5. Modelo de auth decidido e escrito no contrato (sessão, OAuth, JWT) com o motivo.
|
||||
6. Contrato com decisão de produto passa pelo usuário antes do build.
|
||||
|
||||
- Segurança multi-stack: `secure-coding` (15 stacks)
|
||||
- Segurança de API (OWASP): `api-security-review`, `bola-detector`,
|
||||
`auth-rbac-scaffold`, `injection-checker`, `openapi-hardener`,
|
||||
`security-test-generator`
|
||||
- Bug hunting adversarial: `hermaguard` (pre-scan + 3 agentes — edge cases,
|
||||
ataque, blast radius; read-only, encontra o que está quebrado)
|
||||
- Locais: `fastapi-uvicorn-wiring` (Python), `rest-graphql-debug`,
|
||||
`software-code-quality`, `dependency-cve-audit`, `security-best-practices`,
|
||||
`test-driven-development`, `network-audit`
|
||||
## Fase 2: BUILD com defaults seguros (nível 1+)
|
||||
|
||||
## Fase 1 — PLAN (contrato antes de código)
|
||||
`implementer` com TDD: comportamento novo começa por teste que falha. Regras:
|
||||
|
||||
1. Definir API contract primeiro: rotas, métodos, payloads, status codes,
|
||||
erros (RFC 9457 / RFC 7807), rate limit, versionamento.
|
||||
2. Validar schema: `openapi-hardener` — OpenAPI/Zod/Pydantic saneado antes
|
||||
de escrever handler.
|
||||
3. Definir modelo de dados + migração (idempotente) ANTES de query.
|
||||
4. Decidir auth: sessão/OAuth/JWT com base no contexto; documentar.
|
||||
5. Approved do contrato pelo usuário antes de build.
|
||||
6. VERIFICAR: validar o contrato com `openapi-hardener` (schemas coerentes),
|
||||
conferir rate limit + versionamento definidos, e confirmar que o modelo
|
||||
de dados tem migração idempotente antes de construir.
|
||||
7. VERIFICAR (comandos de plano): usar `curl` para provar o contrato contra
|
||||
um stub (ex: `curl -i localhost:PORT/health`) e `git log`/branches para
|
||||
confirmar que o contrato fica versionado no repo.
|
||||
8. CHECKPOINT: registrar contrato em `docs/contract.md` (ou OpenAPI) para as
|
||||
fases seguintes referenciarem.
|
||||
9. VERIFICAR (comandos de contrato completo): `grep -c "->" docs/contract.md` — todas as rotas têm status codes esperados; e `grep -c "429\|rate" docs/contract.md` para provar que rate limit está no contrato.
|
||||
10. VERIFICAR (auth no contrato): `grep -rn "auth\|bearer\|session" docs/contract.md` — decidir e documentar o modelo de auth ANTES do build (não deixar para a Fase 2/3).
|
||||
11. VERIFICAR (validação de contrato): se OpenAPI, `python3 -m json.tool docs/openapi.json > /dev/null` para provar que o schema é válido em JSON.
|
||||
- Validação de toda entrada externa na borda; nada de confiar em payload, header ou query.
|
||||
- Erros estruturados (RFC 9457); nunca `except: pass` nem `catch` vazio.
|
||||
- Timeout em todo cliente HTTP e conexão de banco; retry só em operação idempotente.
|
||||
- Mutações idempotentes (chave de idempotência em POST que cobra ou cria); transação quando há várias escritas.
|
||||
- Toda listagem com paginação e limite máximo.
|
||||
- Query de dado do usuário escopada ao ID autenticado (ownership), nunca a um ID vindo do cliente.
|
||||
- Senha com Argon2id; sessão em cookie `httpOnly`, `Secure`, `SameSite`; nenhum segredo, token ou senha em log.
|
||||
- CORS com allowlist explícita (nunca `*` com credenciais); configuração por variável de ambiente.
|
||||
- Tipos seguros na fronteira: sem `any` ou cast forçado no que entra ou sai.
|
||||
- `secure-coding`, se instalado, como checklist da stack.
|
||||
|
||||
**Checklist da fase 1 (validar antes do build):**
|
||||
- [ ] Rotas/métodos/payloads/status codes definidos e aprovados.
|
||||
- [ ] Erros no padrão RFC 9457/7807; rate limit e versionamento especificados.
|
||||
- [ ] `openapi-hardener` validou os schemas (Zod/Pydantic/OpenAPI).
|
||||
- [ ] Migração de dados idempotente desenhada antes de qualquer query.
|
||||
Dependência nova: justifique (`lean-code`) e consulte `safedeps` antes de instalar.
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NUNCA escrever handler sem contrato aprovado.
|
||||
- NUNCA deixar schema "se inferir na mão livre" — definir e validar.
|
||||
- NÃO esquecer rate limit/versionamento na fase 1 (correção é cara depois).
|
||||
- NÃO misturar payload v2 com contrato v1 sem versionamento explícito.
|
||||
## Fase 3: SECURITY (nível 2+, ou nível 1 com gatilho)
|
||||
|
||||
## Fase 2 — BUILD (escrever com defaults seguros)
|
||||
Gatilhos do `dev-router` (auth, dinheiro, dado pessoal, SQL montado à mão, upload, shell, LLM) chamam
|
||||
o `security-auditor`, que segue o `wf-security-review` com escopo no diff e no que ele alcança.
|
||||
|
||||
1. `secure-coding` — aplicar padrões da stack em uso (Node/FastAPI/Go/etc).
|
||||
2. Validação na borda (Zod/Pydantic), erros estruturados, timeouts em
|
||||
clientes HTTP e DB, idempotência em mutações.
|
||||
3. Argon2id p/ senhas, httpOnly cookies p/ sessões, nunca logar segredos.
|
||||
4. Type-safe boundaries; evitar `any`/`as` descontrolados em TS.
|
||||
5. VERIFICAR: rodar `secure-coding` como checklist da stack (validação na
|
||||
borda, timeouts, idempotência) e `rest-graphql-debug` para confirmar
|
||||
que os status codes/mensagens batem com o contrato da Fase 1.
|
||||
6. VERIFICAR (timeouts): para todo cliente HTTP do serviço, confirmar
|
||||
`timeout` definido — `grep -rn "requests\|fetch(" src/ | wc -l` contra
|
||||
o número de `timeout` presentes; igual = OK.
|
||||
7. VERIFICAR (redação de segredos): `grep -rniE "password|secret|token" src/ --include="*.py" --include="*.ts" | grep -i "log\|print"` — zero
|
||||
hits é o esperado (nenhum segredo sendo logado).
|
||||
8. VERIFICAR (queries): conferir que toda listagem tem `LIMIT` — checar
|
||||
com `search_files` as chamadas sem paginação antes de seguir.
|
||||
- Referências: OWASP API Security Top 10 (2023) e OWASP Top 10:2025.
|
||||
- ASVS 5.0: L1 no nível 2, L2 no nível 3.
|
||||
- Vendorizadas: `api-security-review` (OWASP API Top 10), `secrets-scan`, `sca-audit`, `safedeps` (CVE ao vivo no OSV.dev).
|
||||
- Externas, se instaladas: `bola-detector` em rotas com `:id`, `auth-rbac-scaffold` em login e papéis, `injection-checker` em SQL/ORM/shell/template.
|
||||
- Achado P0/P1 bloqueia a entrega; depois do fix, rode a auditoria de novo e confirme que sumiu.
|
||||
- Nível 3 ou gatilho disparado: `hermaguard` no diff como passe adversarial (edge cases, ataque, blast radius).
|
||||
|
||||
**Checklist da fase 2 (build seguro):**
|
||||
- [ ] Validação na borda (Zod/Pydantic) em TODA entrada externa.
|
||||
- [ ] Erros estruturados; timeouts em clientes HTTP e DB.
|
||||
- [ ] Mutações idempotentes; transações onde há múltiplas gravações.
|
||||
- [ ] Senhas com Argon2id; sessões httpOnly; nenhum segredo em log.
|
||||
- [ ] Type-safe boundaries; sem `any` solto no que atravessa a fronteira.
|
||||
## Fase 4: TEST + GATE (nível 1+)
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NUNCA logar senha/token/dado sensível.
|
||||
- NUNCA confiar em input externo sem validação na borda.
|
||||
- NÃO fazer query sem LIMIT/paginação em listas não limitadas.
|
||||
- NÃO engolir erro com `except: pass` / catch vazio (mascara falha).
|
||||
1. Testes de validação, auth negativa (outro usuário, sem token, papel errado) e idempotência.
|
||||
`security-test-generator`, se instalado, ajuda a gerar os casos negativos.
|
||||
2. Gate: `"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier N`. Já cobre lint, typecheck, testes,
|
||||
gitleaks, semgrep, cobertura do diff, mutação e osv-scanner conforme o nível.
|
||||
3. Checagens que dependem do app de pé entram como `[[check]]` no `.dev-workflows.toml` do projeto
|
||||
(receitas em [references/checks.md](references/checks.md)):
|
||||
- schemathesis contra o OpenAPI (nível 2+): zero erro 5xx e zero violação de schema;
|
||||
- Pact quando há outro serviço consumindo a API;
|
||||
- migração up, down, up num banco descartável (testcontainers) quando o schema muda;
|
||||
- `EXPLAIN` das queries novas e detecção de N+1 quando há query nova;
|
||||
- k6 com thresholds de p95 quando a mudança toca um caminho quente (nível 3 ou gatilho de performance).
|
||||
4. No nível 2+, `reviewer` revisa o diff; no nível 3, `verifier` roda o gate final e devolve a evidência.
|
||||
|
||||
## Fase 3 — SECURITY (auditar tudo)
|
||||
Detalhes do gate e da configuração: [../dev-router/references/quality-gate.md](../dev-router/references/quality-gate.md).
|
||||
|
||||
1. `bola-detector` em rotas com `:id`/`findUnique` (Object-Level Authz).
|
||||
2. `auth-rbac-scaffold` em qualquer fluxo de JWT/login/roles.
|
||||
3. `injection-checker` em SQL/ORM/shell/templates.
|
||||
4. `api-security-review` no conjunto final (OWASP API Top 10).
|
||||
5. `dependency-cve-audit` nas deps do projeto (local).
|
||||
6. VERIFICAR: consolidar achados P0/P1 por severidade, validar que cada
|
||||
rota sensível tem auth + ownership-scope, e re-auditar depois de
|
||||
qualquer fix (nada de despachar cego).
|
||||
7. VERIFICAR (ownership): para rotas com `:id`, conferir que a query usa o
|
||||
ID autenticado — `grep -rn "user_id\|user.id\|req.user" src/ | wc -l`
|
||||
>= número de rotas protegidas.
|
||||
8. VERIFICAR (rate limit): `grep -rniE "ratelimit|rate_limit|limiter" src/`
|
||||
— toda rota de escrita tem rate limit de referência; se ausente, anotar
|
||||
como P2.
|
||||
9. VERIFICAR (headers/CORS): conferir CSP/CORS configurados (CORS
|
||||
allowlist explícita, não `*` com credenciais); `grep -rn "access-control\|csp\|content-security" src/`.
|
||||
10. VERIFICAR (re-audit pós-fix): após corrigir P0/P1, re-rodar
|
||||
`bola-detector` + `api-security-review` e confirmar que os achados
|
||||
sumiram (não só mudaram de arquivo).
|
||||
11. VERIFICAR (critério de aceite de segurança): para cada achado P0/P1,
|
||||
reexecutar o teste que o reproduzia e confirmar que agora passa;
|
||||
manter o PoC no repositório de testes.
|
||||
12. VERIFICAR (comandos de confirmação): `grep -c "auth\|ownership" src/`
|
||||
deve ser >= número de rotas que mexem em dado de usuário — cada rota
|
||||
sensível tem o controle por objeto documentado no código.
|
||||
## Relatório
|
||||
|
||||
**Checklist da fase 3 (segurança):**
|
||||
- [ ] `bola-detector` limpo em rotas com `:id` (object-level authz).
|
||||
- [ ] Auth/RBAC (`auth-rbac-scaffold`) cobrindo roles e sessions.
|
||||
- [ ] `injection-checker` limpo (SQL/ORM/shell/templates).
|
||||
- [ ] `api-security-review` sem P0/P1 (OWASP API Top 10).
|
||||
- [ ] `dependency-cve-audit` sem CVEs críticas pendentes.
|
||||
Contrato entregue (nível 2+), achados de segurança por severidade e o que foi corrigido, testes que
|
||||
provam (nomes e contagem real), veredito do gate com o que ficou não verificado, e linhas líquidas.
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NUNCA definir query escopada por outro ID que não o autenticado.
|
||||
- NUNCA aceitar finding P0/P1 sem evidência de correção.
|
||||
- NÃO revisar segurança só nos endpoints novos — escopar também os existentes.
|
||||
- NÃO tratar auditoria como checklist burocrático: achado não resolvido bloqueia.
|
||||
## Critérios de aceite
|
||||
|
||||
## Fase 4 — TEST + BUG HUNT (provar antes de entregar)
|
||||
|
||||
1. `hermaguard` no diff do backend — dispachar os 3 agentes adversariais
|
||||
(Edge Case Hunter, Adversarial Reviewer, Blast Radius). Esperar falhar:
|
||||
NUNCA parar em "parece ok"; exigir cobertura de edge cases, races,
|
||||
rollback safety e schema drift. Read-only (não corrige — acha).
|
||||
2. `test-driven-development`: testar o que valida/auth/idempotência.
|
||||
3. `security-test-generator`: testes de segurança (authz negativa,
|
||||
payloads malformados, rate limit).
|
||||
4. Rodar suíte + lint + typecheck; status real, não suposição.
|
||||
5. Corrigir os findings P0/P1 do hermaguard como tarefas separadas; rodar
|
||||
hermaguard de novo se o fix mudou >3 arquivos.
|
||||
6. Relatório: contrato entregue, achados de segurança P0/P1/P2 resolvidos,
|
||||
bugs caçados pelo hermaguard (por severidade), testes passando (contagem).
|
||||
7. VERIFICAR (não-regressão QA): rodar `test_quality.py` (gate do workflow)
|
||||
— score não pode cair em relação ao baseline.
|
||||
8. VERIFICAR (cobertura de classes): para rolls em produção, conferir que
|
||||
o hermaguard cobriu edge cases, races, rollback safety e schema drift —
|
||||
não aceitar "sem achados" sem essa cobertura.
|
||||
9. VERIFICAR (efeito colateral): se a mudança alterou contrato/DB, rodar
|
||||
`rest-graphql-debug` para confirmar status codes e mensagens sem
|
||||
regressão.
|
||||
10. VERIFICAR (cobertura de testes real): `python3 -m pytest --cov=app -q`
|
||||
(ou `npm test -- --coverage`) — anotar % de cobertura e garantir que
|
||||
os módulos críticos (auth, validação, idempotência) têm pelo menos
|
||||
smoke test.
|
||||
11. VERIFICAR (migração reversível): se houve schema change, rodar
|
||||
`alembic downgrade -1`/equivalente em dev para provar rollback; e
|
||||
`git diff --stat` para conferir o escopo do que está indo pra frente.
|
||||
12. VERIFICAR (config por ambiente): `grep -rn "getenv\|os.environ\|process.env" src/` — toda configuração via env, sem valores hardcoded que
|
||||
vazam para prod.
|
||||
13. VERIFICAR (comandos de entrega): `python3 -m pytest -q && npm run build` (ou stack equivalente) como smoke final; e `git status` para
|
||||
confirmar que os artefatos de teste não vazaram pro repo.
|
||||
14. VERIFICAR (critério de entrega): relatório final só fecha quando cada
|
||||
item do checklist da Fase 4 está marcado — sem exceção de última hora
|
||||
não auditada.
|
||||
|
||||
**Checklist da fase 4 (gate de entrega):**
|
||||
- [ ] `hermaguard` rodado; findings CRITICAL/HIGH zero ou com plano de fix.
|
||||
- [ ] TDD: testes de validação, auth e idempotência verdes.
|
||||
- [ ] `security-test-generator`: authz negativa, payloads mal, rate limit.
|
||||
- [ ] Suíte + lint + typecheck verdes (contagem real, não suposição).
|
||||
- [ ] Findings P0/P1 corrigidos e re-verificados (hermaguard rodado de novo
|
||||
se o fix alterou >3 arquivos).
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NUNCA rodar hermaguard em código com testes quebrados (polui o review).
|
||||
- NUNCA dar "suíte passando" sem ter executado a suíte.
|
||||
- NÃO aceitar "hermaguard não achou nada" sem exigir a cobertura por classe
|
||||
(edge cases, races, rollback, schema drift).
|
||||
- NÃO reportar achado P0/P1 como resolvido sem a verificação de volta.
|
||||
|
||||
## Comandos de Verificação (executáveis)
|
||||
|
||||
```bash
|
||||
# Gate de qualidade do próprio workflow (sem regressão)
|
||||
python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py
|
||||
|
||||
# Testes + meta-testes (prova que o harness detecta regressão)
|
||||
python3 ~/.hermes/skills/software-development/wf-qa/test_tests.py
|
||||
|
||||
# Audit OWASP de um endpoint/controller
|
||||
# (skill api-security-review) — veja a skill
|
||||
|
||||
# CVE nas deps do projeto
|
||||
# (skill dependency-cve-audit) — veja a skill
|
||||
|
||||
# Bug hunt adversarial no diff (read-only)
|
||||
# (skill hermaguard: "hermaguard this")
|
||||
```
|
||||
|
||||
## Critérios de Aceite (checklist não-regressivo)
|
||||
|
||||
- [ ] Contrato aprovado (PLAN) antes de qualquer handler.
|
||||
- [ ] BUILD com defaults seguros; `secure-coding` validado na stack.
|
||||
- [ ] SECURITY: bola/auth/injection/api-review/CVE rodados; P0/P1 resolvidos.
|
||||
- [ ] TEST: hermaguard + TDD + security-test-generator; suíte verde com
|
||||
contagem real.
|
||||
- [ ] 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 — validar contrato antes de codar:
|
||||
|
||||
```bash
|
||||
# Lista de rotas planejadas (contrato em aberto)
|
||||
cat > docs/contract.md <<'EOF'
|
||||
POST /api/v1/users -> 201 | 400 | 401 | 409 | 429
|
||||
GET /api/v1/users/:id -> 200 | 404 | 403
|
||||
Erros: RFC 9457 (application/problem+json)
|
||||
EOF
|
||||
```
|
||||
|
||||
Fase 2 — build seguro (exemplo FastAPI + Pydantic):
|
||||
|
||||
```bash
|
||||
# Rodar a stack e conferir a OpenAPI gerada
|
||||
uvicorn app.main:app --reload # ou npm run dev
|
||||
curl -s localhost:8000/openapi.json | python3 -m json.tool > /tmp/openapi.json
|
||||
python3 -c "import sys,json; d=json.load(open('/tmp/openapi.json')); print('schemas:', len(d.get('components',{}).get('schemas',{})))"
|
||||
|
||||
# Validação de contrato contra a OpenAPI real
|
||||
curl -s localhost:8000/health -i | head -5 # status codes do health
|
||||
curl -s -X POST localhost:8000/api/v1/users -d '{}' -i | head -5 # 400 esperado
|
||||
```
|
||||
|
||||
Fase 3 — auditoria de segurança:
|
||||
|
||||
```bash
|
||||
# Rodar as skills de auditoria OWASP (veja cada skill p/ uso exato)
|
||||
# bola-detector: "audite rotas com :id" / auth-rbac-scaffold: "valide o fluxo de login"
|
||||
# injection-checker: "escaneie SQL/ORM" / api-security-review: "revisão OWASP do conjunto"
|
||||
# dependency-cve-audit: "audite as dependências" (skill local)
|
||||
```
|
||||
|
||||
Fase 4 — testes e bug hunt:
|
||||
|
||||
```bash
|
||||
python3 -m pytest -v # ou npm test
|
||||
python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py # gate do workfl
|
||||
# "hermaguard this" (bug hunt adversarial no diff)
|
||||
```
|
||||
|
||||
Gates anti-regressão (rodar junto com o fluxo):
|
||||
|
||||
```bash
|
||||
python3 ~/.hermes/skills/software-development/wf-qa/test_tests.py # teste dos testes
|
||||
# verifica que o harness DETECTA regressão (mutações sempre derrubam o score)
|
||||
python3 -m pytest tests/security/ -x # se existir suíte de segurança
|
||||
```
|
||||
- [ ] Nível 2+: contrato aprovado antes do primeiro handler.
|
||||
- [ ] Toda entrada externa validada na borda; erros em RFC 9457.
|
||||
- [ ] Queries de dado do usuário escopadas ao ID autenticado.
|
||||
- [ ] Nenhum P0/P1 de segurança aberto; CVEs consultados ao vivo, com data.
|
||||
- [ ] Migração reversível provada (up, down, up) quando o schema mudou.
|
||||
- [ ] Gate `pass`, ou `incomplete` com a lista do que não foi verificado dita ao usuário.
|
||||
|
||||
## Regras duras
|
||||
|
||||
- NUNCA escrever handler antes do contrato aprovado.
|
||||
- NUNCA entregar endpoint sem passar pelas 4 fases (security + testes +
|
||||
hermaguard).
|
||||
- Rota que mexe em dado do usuário → ownership-check obrigatório (query
|
||||
escopada ao ID autenticado).
|
||||
- Tests vermelhos = fixar primeiro; hermaguard não roda em código quebrado.
|
||||
- Nunca escrever handler antes do contrato aprovado (nível 2+).
|
||||
- Nunca rodar `hermaguard` ou auditoria em código com testes vermelhos; corrija os testes primeiro.
|
||||
- Nunca dizer "suíte passando" sem ter rodado a suíte.
|
||||
@@ -0,0 +1,63 @@
|
||||
# Checagens de backend que dependem do app de pé
|
||||
|
||||
Estas checagens entram como `[[check]]` no `.dev-workflows.toml` do projeto, porque precisam de
|
||||
servidor, banco ou carga reais. O gate roda cada uma no nível indicado e trata ferramenta ausente
|
||||
como "não verificado".
|
||||
|
||||
## Contrato de exemplo (`docs/contract.md`)
|
||||
|
||||
```text
|
||||
POST /api/v1/users -> 201 | 400 | 401 | 409 | 429
|
||||
GET /api/v1/users/:id -> 200 | 403 | 404
|
||||
Erros: RFC 9457 (application/problem+json)
|
||||
Paginação: ?cursor=&limit= (limit máx. 100)
|
||||
Rate limit: 60 req/min por usuário em escrita; 429 com Retry-After
|
||||
Auth: sessão em cookie httpOnly; rotas /admin exigem papel admin
|
||||
```
|
||||
|
||||
## Receitas de `[[check]]`
|
||||
|
||||
```toml
|
||||
# Fuzz da API a partir do OpenAPI: zero 5xx e zero violação de schema
|
||||
[[check]]
|
||||
name = "api-fuzz"
|
||||
cmd = "schemathesis run http://localhost:8000/openapi.json --checks all"
|
||||
tier = 2
|
||||
|
||||
# Contrato com consumidores (quando outro serviço usa a API)
|
||||
[[check]]
|
||||
name = "pact-verify"
|
||||
cmd = "npx pact-provider-verifier --provider-base-url http://localhost:8000 --pact-broker-url $PACT_BROKER_URL"
|
||||
tier = 2
|
||||
|
||||
# Migração reversível num banco descartável (up -> down -> up)
|
||||
[[check]]
|
||||
name = "migration-roundtrip"
|
||||
cmd = "alembic upgrade head && alembic downgrade -1 && alembic upgrade head"
|
||||
tier = 2
|
||||
|
||||
# Carga no caminho quente, com threshold de p95 no próprio script k6
|
||||
[[check]]
|
||||
name = "load"
|
||||
cmd = "k6 run --quiet load/hot-path.js"
|
||||
tier = 3
|
||||
```
|
||||
|
||||
No k6, o threshold fica no script e faz o comando sair com erro quando estoura:
|
||||
|
||||
```js
|
||||
export const options = {
|
||||
vus: 20, duration: "30s",
|
||||
thresholds: { http_req_duration: ["p(95)<300"], http_req_failed: ["rate<0.01"] },
|
||||
};
|
||||
```
|
||||
|
||||
Para a migração, suba um Postgres descartável (testcontainers ou `docker run --rm -p 5433:5432 postgres`)
|
||||
e aponte a `DATABASE_URL` do comando para ele. Nunca rode o roundtrip num banco com dados reais.
|
||||
|
||||
## Queries novas
|
||||
|
||||
- Rode `EXPLAIN (ANALYZE, BUFFERS)` em cada query nova com volume parecido com o de produção; seq scan
|
||||
em tabela grande pede índice ou filtro.
|
||||
- N+1: conte as queries de uma requisição de listagem (log do ORM ou `django-debug-toolbar`,
|
||||
`nplusone`, `bullet`). O número não pode crescer com o tamanho da página.
|
||||
@@ -1,6 +1,11 @@
|
||||
---
|
||||
name: wf-bugfix
|
||||
description: Use para corrigir bug, erro, exceção, falha, regressão, comportamento errado ("não funciona", "quebrou", "fix"). Reproduz, acha a causa raiz e prova a correção com um teste de regressão que falha antes e passa depois.
|
||||
license: MIT
|
||||
metadata:
|
||||
dev-workflows:
|
||||
uses: []
|
||||
external: []
|
||||
---
|
||||
|
||||
# Workflow Bugfix
|
||||
|
||||
+67
-286
@@ -1,317 +1,98 @@
|
||||
---
|
||||
name: wf-frontend
|
||||
description: "Use p/ frontend/UI. Fluxo DESIGN→BUILD→REVIEW."
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
description: Use para trabalho de frontend e UI - componentes, páginas, layouts, estilos, design system, animação, acessibilidade, redesign de tela existente, e geração de PDF ou documento visual a partir de HTML. Fluxo DESIGN, BUILD, REVIEW com profundidade definida pelo nível do dev-router. Não use para backend ou API (wf-backend), para bug sem mudança visual (wf-bugfix) nem para refactor sem mudança de comportamento (wf-refactor).
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [frontend, ui, ux, design, react, tailwind, workflow]
|
||||
dev-workflows:
|
||||
uses: [design-taste-frontend, redesign-existing-projects, lean-code, dev-router]
|
||||
external: [frontend-design, web-design, vercel-react-best-practices, vercel-composition-patterns, animate, impeccable, avoid-ai-writing]
|
||||
---
|
||||
|
||||
# Workflow Frontend/Design
|
||||
# Workflow Frontend
|
||||
|
||||
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.
|
||||
A profundidade vem do nível que o `dev-router` definiu. Cada fase diz a partir de qual nível roda.
|
||||
|
||||
## When to Use
|
||||
| Nível | O que roda |
|
||||
|---|---|
|
||||
| 0 | só o gate (`--tier 0`) |
|
||||
| 1 | ajuste de UI: siga o design system que já existe; sem DESIGN.md, sem aprovação; BUILD enxuto + gate `--tier 1` |
|
||||
| 2 | tela ou componente novo: DESIGN curto, BUILD, REVIEW com `ui-critic` e `reviewer` |
|
||||
| 3 | fluxo ou design system novo: DESIGN com aprovação do usuário, BUILD por tarefas, REVIEW completo |
|
||||
|
||||
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 (carregar só na fase que usa)
|
||||
|
||||
## Skills do stack (carregar conforme a fase)
|
||||
- **Tela nova:** `design-taste-frontend` (~35 mil tokens; só para tela nova, nunca para ajuste) e, se instalada, `frontend-design`.
|
||||
- **Tela existente:** `redesign-existing-projects` (audita antes de mudar).
|
||||
- **Auditoria anti "UI de IA":** `impeccable` (`/impeccable audit`, externa).
|
||||
- **React/Next:** `vercel-react-best-practices` (performance), `vercel-composition-patterns` (composição).
|
||||
- **Motion:** `animate`. **Microcopy:** `avoid-ai-writing`.
|
||||
- Sempre: `lean-code`.
|
||||
|
||||
- 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
|
||||
Externas são opcionais: se não estiverem instaladas, siga as regras desta página. Instalação em `docs/SKILLS.md`.
|
||||
|
||||
## Fase 1 — DESIGN (decidir antes de codar)
|
||||
## Fase 1, DESIGN (nível 2+, tela ou componente novo)
|
||||
|
||||
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.
|
||||
Nível 1 pula esta fase e usa os tokens, componentes e padrões que o projeto já tem.
|
||||
|
||||
**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.
|
||||
1. `explorer` mapeia o design system existente: tokens (cor, tipografia, espaçamento), componentes reutilizáveis, biblioteca de UI. Reaproveitar vem antes de criar.
|
||||
2. Defina a direção: paleta, tipografia, densidade, claro/escuro. Tela nova usa `design-taste-frontend`; redesign usa `redesign-existing-projects`.
|
||||
3. Registre as decisões em `DESIGN.md` (curto: tokens e o porquê).
|
||||
4. Nível 3, ou decisão que é do usuário (identidade visual, troca de stack): pare e peça aprovação antes de codar. Nível 2 segue sem parar se a direção vem do design system existente.
|
||||
|
||||
**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ó.
|
||||
Evite: gradiente roxo genérico, glassmorphism sem motivo, cards idênticos em grade, ícone decorativo sem função, dois design systems na mesma tela.
|
||||
|
||||
## Fase 2 — BUILD (implementar com padrões de produção)
|
||||
## Fase 2, BUILD (nível 1+)
|
||||
|
||||
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.
|
||||
1. `implementer` (ou você, em mudança pequena) implementa com `lean-code`: componente e hook existentes antes de novos; CSS e HTML nativos antes de JS.
|
||||
2. **Estados em todo fluxo com dados:** carregando, vazio, erro, sucesso.
|
||||
3. **Acessibilidade por padrão:** HTML semântico, foco visível e em ordem, rótulos, contraste de texto >= 4.5:1. ARIA só quando o HTML não resolve.
|
||||
4. **Responsivo mobile-first**, testado em 375 px e 1280 px.
|
||||
5. **Composição:** compound components em vez de explosão de props booleanas (`isX`, `showY`).
|
||||
6. **Motion com propósito** (estado, entrada, feedback) e `prefers-reduced-motion` respeitado.
|
||||
7. React/Next: sem waterfall de dados, sem re-render em cascata, imagem com dimensões, código dividido por rota.
|
||||
8. TypeScript sem `any` nem cast forçado para "passar".
|
||||
9. Rode o gate a cada componente relevante, não só no fim.
|
||||
|
||||
**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.
|
||||
Entrada de usuário renderizada como HTML, `dangerouslySetInnerHTML`, `eval`, `postMessage` ou mudança de CSP disparam `security-auditor` (XSS/CSP).
|
||||
|
||||
**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 (nível 2+)
|
||||
|
||||
## Fase 3 — REVIEW (verificar antes de entregar)
|
||||
1. `ui-critic`: screenshot em 375 e 1280, estados, a11y, padrões genéricos. Se `impeccable` estiver instalada, `/impeccable audit`.
|
||||
2. `reviewer`: correção e simplicidade do diff.
|
||||
3. `avoid-ai-writing` nos textos entregues ao usuário (labels, vazios, erros), se instalada.
|
||||
4. Corrija o que for `bloqueante` ou `importante` e rode os dois de novo só no que mudou.
|
||||
|
||||
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):
|
||||
## Gate
|
||||
|
||||
```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
|
||||
"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier N
|
||||
```
|
||||
|
||||
QA visual de PDF — renderizar páginas e inspecionar bordas (nada cortado):
|
||||
Lint, typecheck, testes, segredos e build rodam sozinhos. O que depende do app de pé (Lighthouse,
|
||||
axe, bundle, regressão visual) entra como `[[check]]` no `.dev-workflows.toml` do projeto: modelos em
|
||||
[references/checks.md](references/checks.md). Lista completa de checagens:
|
||||
`skills/dev-router/references/quality-gate.md`.
|
||||
|
||||
```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
|
||||
```
|
||||
Metas de referência (nível 2+): LCP <= 2,5 s, INP <= 200 ms (TBT como proxy em laboratório),
|
||||
CLS <= 0,1; axe sem violação `serious` ou `critical`; bundle dentro do limite do `size-limit`.
|
||||
|
||||
Qualidade de texto (microcopy, labels, README) — auditoria de AI-isms:
|
||||
O `verifier` roda o gate e devolve a evidência. Ferramenta ausente aparece como "não verificado":
|
||||
diga isso ao usuário, nunca chame de testado.
|
||||
|
||||
```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
|
||||
## PDF e documento visual
|
||||
|
||||
# ou debaixo do wf: pedir "roda o avoid-ai no README" (modo detect/rewrite)
|
||||
```
|
||||
Sempre HTML + CSS renderizado pelo Playwright (`page.pdf()`), depois cada página convertida em PNG e
|
||||
inspecionada com Read: nada cortado na margem, tabela longa quebrando entre páginas. Nunca
|
||||
reportlab platypus direto para tabelas longas. Método completo: [references/pdf.md](references/pdf.md).
|
||||
|
||||
Bug hunt adversarial no diff (comandos da skill hermaguard):
|
||||
## Aceite
|
||||
|
||||
```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.
|
||||
- [ ] Nível declarado; fases puladas coerentes com ele.
|
||||
- [ ] Nível 2+: direção registrada em `DESIGN.md` (aprovada pelo usuário no nível 3).
|
||||
- [ ] Estados carregando, vazio, erro e sucesso em todo fluxo com dados.
|
||||
- [ ] Acessível: semântica, foco, rótulos, contraste >= 4.5:1; axe sem `serious`/`critical` se configurado.
|
||||
- [ ] Responsivo em 375 px e 1280 px, sem corte ou sobreposição.
|
||||
- [ ] `prefers-reduced-motion` respeitado; animação só com propósito.
|
||||
- [ ] Sem explosão de props booleanas; composição com compound components.
|
||||
- [ ] Gate `pass`, ou falhas explicadas; "não verificado" listado ao usuário.
|
||||
- [ ] PDF: páginas renderizadas e inspecionadas, nada cortado.
|
||||
@@ -0,0 +1,91 @@
|
||||
# Checagens de frontend para o `.dev-workflows.toml`
|
||||
|
||||
Estas checagens precisam do app de pé ou de configuração do projeto, por isso entram como
|
||||
`[[check]]`. O gate só roda as do nível pedido ou abaixo.
|
||||
|
||||
```toml
|
||||
[[check]]
|
||||
name = "lighthouse"
|
||||
cmd = "npx lhci autorun"
|
||||
tier = 2
|
||||
|
||||
[[check]]
|
||||
name = "a11y"
|
||||
cmd = "npx playwright test e2e/a11y.spec.ts"
|
||||
tier = 2
|
||||
|
||||
[[check]]
|
||||
name = "bundle"
|
||||
cmd = "npx size-limit"
|
||||
tier = 2
|
||||
|
||||
[[check]]
|
||||
name = "visual"
|
||||
cmd = "npx playwright test e2e/visual.spec.ts"
|
||||
tier = 3
|
||||
```
|
||||
|
||||
## Lighthouse CI com orçamento (`lighthouserc.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"ci": {
|
||||
"collect": { "startServerCommand": "npm run start", "url": ["http://localhost:3000/"], "numberOfRuns": 3 },
|
||||
"assert": {
|
||||
"assertions": {
|
||||
"largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
|
||||
"total-blocking-time": ["error", { "maxNumericValue": 200 }],
|
||||
"cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
|
||||
"categories:accessibility": ["error", { "minScore": 0.9 }]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
INP só existe com usuário real; em laboratório, TBT é o proxy.
|
||||
|
||||
## Acessibilidade com Playwright + axe (`e2e/a11y.spec.ts`)
|
||||
|
||||
```ts
|
||||
import { test, expect } from "@playwright/test";
|
||||
import AxeBuilder from "@axe-core/playwright";
|
||||
|
||||
for (const path of ["/", "/login"]) {
|
||||
test(`a11y ${path}`, async ({ page }) => {
|
||||
await page.goto(path);
|
||||
const { violations } = await new AxeBuilder({ page }).analyze();
|
||||
const graves = violations.filter(v => v.impact === "serious" || v.impact === "critical");
|
||||
expect(graves).toEqual([]);
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Regressão visual (`e2e/visual.spec.ts`)
|
||||
|
||||
```ts
|
||||
import { test, expect } from "@playwright/test";
|
||||
|
||||
for (const width of [375, 1280]) {
|
||||
test(`home ${width}px`, async ({ page }) => {
|
||||
await page.setViewportSize({ width, height: 900 });
|
||||
await page.goto("/");
|
||||
await expect(page).toHaveScreenshot(`home-${width}.png`, { fullPage: true });
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
A primeira execução grava a referência (`--update-snapshots`); as seguintes comparam.
|
||||
|
||||
## Bundle (`size-limit` no `package.json`)
|
||||
|
||||
```json
|
||||
"size-limit": [{ "path": "dist/**/*.js", "limit": "200 KB" }]
|
||||
```
|
||||
|
||||
## Screenshot rápida para o `ui-critic`
|
||||
|
||||
```bash
|
||||
npx playwright screenshot --viewport-size=375,812 http://localhost:3000 /tmp/ui-375.png
|
||||
npx playwright screenshot --viewport-size=1280,800 http://localhost:3000 /tmp/ui-1280.png
|
||||
```
|
||||
@@ -0,0 +1,49 @@
|
||||
# PDF e documento visual: HTML + CSS + Playwright
|
||||
|
||||
Todo PDF passa por aqui: design primeiro, depois render, depois inspeção visual das páginas.
|
||||
|
||||
## Por que não reportlab direto
|
||||
|
||||
`platypus` com tabela longa estoura margem e corta linhas entre páginas. HTML + CSS de impressão
|
||||
resolve quebra de página, cabeçalho repetido e margens com regras declarativas.
|
||||
|
||||
## 1. HTML com CSS de impressão
|
||||
|
||||
```css
|
||||
@page { size: A4; margin: 18mm 16mm; }
|
||||
table { width: 100%; border-collapse: collapse; }
|
||||
thead { display: table-header-group; } /* repete o cabeçalho em cada página */
|
||||
tr, img, figure { break-inside: avoid; }
|
||||
h1, h2 { break-after: avoid; }
|
||||
td { overflow-wrap: anywhere; } /* texto longo não empurra a margem */
|
||||
```
|
||||
|
||||
## 2. Render com Playwright
|
||||
|
||||
```python
|
||||
from playwright.sync_api import sync_playwright
|
||||
|
||||
with sync_playwright() as p:
|
||||
page = p.chromium.launch().new_page()
|
||||
page.goto("file:///caminho/relatorio.html")
|
||||
page.pdf(path="relatorio.pdf", format="A4", print_background=True, prefer_css_page_size=True)
|
||||
```
|
||||
|
||||
## 3. Inspeção visual obrigatória
|
||||
|
||||
Converta cada página em PNG e abra com Read:
|
||||
|
||||
```bash
|
||||
pdftoppm -png -r 110 relatorio.pdf /tmp/qa/pagina
|
||||
ls /tmp/qa/pagina-*.png
|
||||
```
|
||||
|
||||
Em cada imagem, confira:
|
||||
|
||||
- nada cortado nas bordas (texto, tabela, imagem);
|
||||
- tabela longa quebra entre páginas com o cabeçalho repetido;
|
||||
- nenhuma linha órfã de título no pé da página;
|
||||
- fontes carregadas (sem fallback inesperado).
|
||||
|
||||
Achou problema: ajuste o CSS, renderize de novo e inspecione de novo. Só entregue depois de todas as
|
||||
páginas passarem.
|
||||
+68
-195
@@ -1,225 +1,98 @@
|
||||
---
|
||||
name: wf-readme
|
||||
description: "Criar/auditar/reescrever README grounded. Scan real do repo."
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
description: Use para criar, auditar, melhorar, reescrever ou padronizar o README (e docs vizinhos como CONTRIBUTING e CHANGELOG) de um repositório. Tudo que o README afirma vem de um fato real do repo e os comandos mostrados são executados antes da entrega. Não use para docstrings, comentários de código, documentação de API gerada ou textos de UI (esses ficam com wf-frontend).
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [readme, documentation, docs, markdown, workflow]
|
||||
dev-workflows:
|
||||
uses: []
|
||||
external: [readme-crafter, good-readme, curating-readme, avoid-ai-writing]
|
||||
---
|
||||
|
||||
# Workflow README (criar, auditar, reescrever)
|
||||
# Workflow README
|
||||
|
||||
Orquestrador obrigatório para qualquer trabalho de README (criar, melhorar,
|
||||
auditar, padronizar) em qualquer projeto. Princípio central: **grounded** —
|
||||
o README é construído a partir de fatos reais do repositório (manifest,
|
||||
código, scripts, config, git), nunca fabricado de memória.
|
||||
O README é construído a partir do repositório (manifest, código, scripts, config, git), nunca de
|
||||
memória. Fato sem fonte vira pergunta ao usuário.
|
||||
|
||||
## When to Use
|
||||
## Escala pelo tamanho do pedido
|
||||
|
||||
- "cria um README pra esse projeto" / "escreve a documentação"
|
||||
- "melhora esse README" / "audita a qualidade do README"
|
||||
- "padroniza a documentação do repo"
|
||||
- Qualquer pedido de documentação de projeto (README/LICENSE/docs)
|
||||
| Pedido | Fluxo |
|
||||
|---|---|
|
||||
| Ajuste pontual (corrigir um comando, um link, uma seção) | editar e rodar a Fase 5 só no trecho tocado |
|
||||
| README novo, reescrita ou padronização | Fases 1 a 5 |
|
||||
|
||||
## Skills do stack
|
||||
## Skills (se instaladas)
|
||||
|
||||
- `readme-crafter` (linhai0872) — classifica o projeto em 4 eixos (tipo,
|
||||
distribuição, público, temperamento) e gera README sob medida; 13 checks
|
||||
de verificação; modo collaborative/quick/surgical/audit.
|
||||
- `good-readme` (adewale) — cria do zero com exemplos reais de código OU
|
||||
audita contra rubric de 22 critérios (escala 100); verifica exemplos
|
||||
contra o código real.
|
||||
- `curating-readme` (liang-senbei) — padroniza README + docs relacionados
|
||||
(CONTRIBUTING/CHANGELOG/SECURITY/docs) com scripts determinísticos
|
||||
(`audit-repo.sh`) e estrutura canônica.
|
||||
- Locais: `project-readme-clarity` (auditoria de onboarding/ambiguidades),
|
||||
`avoid-ai-writing` (remove AI-isms), `wf-frontend` (padrão visual de
|
||||
docs/README bonitos).
|
||||
- `readme-crafter`: classifica o projeto e sugere estrutura sob medida.
|
||||
- `good-readme`: cria com exemplos reais ou audita contra uma rubrica de 22 critérios.
|
||||
- `curating-readme`: padroniza README e docs vizinhos; traz o script `audit-repo.sh`.
|
||||
- `avoid-ai-writing`: remove AI-isms do texto final.
|
||||
|
||||
## Fase 1 — SCAN (coletar fatos reais)
|
||||
Sem elas, o fluxo abaixo funciona sozinho.
|
||||
|
||||
1. Rodar o inventory determinístico do repo:
|
||||
`bash ~/.hermes/skills/curating-readme/scripts/audit-repo.sh <repo>`
|
||||
(ou o `scan-project.sh` do readme-crafter) — coleta manifest, entrypoints,
|
||||
scripts, config, estrutura, env vars, git, linguagens.
|
||||
2. Ler manifest principal (package.json / pyproject.toml / go.mod / etc):
|
||||
nome, descrição, versão, dependências, scripts.
|
||||
3. Identificar entrypoints: o que o projeto realmente faz (não o que diz).
|
||||
4. Ler README existente (se houver), CLI_AGENTS.md, LICENSE.
|
||||
5. VERIFICAR: marcar como **fato verificado** cada item com fonte no repo;
|
||||
qualquer coisa sem fonte vira `TODO:`/pergunta — nunca inventar.
|
||||
6. VERIFICAR (comandos de scan): rodar `python3 -c "import json; json.load(open('package.json'))"`
|
||||
(ou equivalente para o manifest) para provar que o manifest parseia;
|
||||
e `git remote -v && git log --oneline -5` para capturar contexto real.
|
||||
7. VERIFICAR (inventário): conferir com `find . -maxdepth 1 -type f | wc -l`
|
||||
a contagem real de arquivos e `du -sh .` para não documentar coisa que
|
||||
não existe. TRÊS CHECKS: manifest válido, git real, inventário presente.
|
||||
## Fase 1: SCAN (fatos reais)
|
||||
|
||||
**Checklist da fase 1:**
|
||||
- [ ] Inventory do repo rodado (audit-repo.sh / scan-project.sh)
|
||||
- [ ] Manifest lido e entendido
|
||||
- [ ] Fato × suposição separados (suposição vira TODO/pergunta)
|
||||
1. Leia o manifest (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`...): nome, descrição,
|
||||
versão, scripts, `bin`, dependências.
|
||||
2. Ache os entrypoints e o que o projeto de fato faz (CLI, rotas, exports públicos).
|
||||
3. Leia o README atual, `LICENSE`, `CONTRIBUTING.md`, a CI (`.github/workflows/`) e `.env.example`.
|
||||
4. Capture o contexto: `git remote -v` e `git log --oneline -5`.
|
||||
5. Monte a lista de fatos, cada um com a fonte (`arquivo:linha` ou comando). O que não tem fonte vira pergunta.
|
||||
|
||||
## Fase 2 — CLASSIFY (entender público e tipo)
|
||||
## Fase 2: CLASSIFY (tipo e público)
|
||||
|
||||
1. `readme-crafter` — classificar o projeto:
|
||||
- Tipo: library / CLI / web app / framework / API / agent-AI / monorepo / ...
|
||||
- Distribuição: open-source público vs interno
|
||||
- Público: avaliador / novo usuário / contribuidor / operador / agente IA
|
||||
- Temperamento: developer utility / product / academic / community
|
||||
2. Decidir audiência PRIMÁRIA (o README serve a quem primeiro).
|
||||
3. VERIFICAR: registrar decisões de classificação (1 linha cada) — a
|
||||
estrutura do README deriva delas.
|
||||
4. SE necessário, fazer perguntas do tipo "quem é o público?" ou "qual
|
||||
o tom?" quando o código não revela a intenção (3-5 perguntas máx).
|
||||
5. VERIFICAR (comandos de classificação): para software com CLI, rodar
|
||||
`python3 -m <pkg> --help` (ou `node bin/index.js --help`) para capturar
|
||||
a sintaxe real de uso; para web app, listar `find src pages app -maxdepth 1 -type d 2>/dev/null` para ver as rotas reais.
|
||||
6. VERIFICAR (decisões): registrar as 4 classificações com fonte — "tipo=CLI
|
||||
porque package.json.bin existe"; "público=developer porque docs de API".
|
||||
- Tipo: biblioteca, CLI, web app, API, framework, monorepo, agente.
|
||||
- Distribuição: público ou interno. Público primário: novo usuário, contribuidor, operador ou avaliador.
|
||||
- Cada decisão com a fonte ("CLI porque `package.json` tem `bin`").
|
||||
- Para CLI, rode o `--help` real e use essa saída como base da seção de uso.
|
||||
- Se o código não revela a intenção, até 3 perguntas ao usuário.
|
||||
|
||||
**Checklist da fase 2:**
|
||||
- [ ] Tipo / distribuição / público / temperamento definidos
|
||||
- [ ] Audiência primária nomeada
|
||||
- [ ] Perguntas de intenção (se houve) respondidas
|
||||
## Fase 3: AUDIT (se já existe README)
|
||||
|
||||
## Fase 3 — AUDIT ou DRAFT (estado atual)
|
||||
- Compare cada afirmação com o repo: comandos, caminhos, variáveis de ambiente, versões, badges.
|
||||
- Registre o que está certo, desatualizado, errado e faltando. Divergência com o código é achado, mesmo em README bonito.
|
||||
- Dependência opcional apresentada como obrigatória e passo que bloqueia o primeiro uso são achados.
|
||||
- Com `good-readme`, registre a nota de partida.
|
||||
|
||||
Se JÁ existe README:
|
||||
1. `good-readme` — auditar contra 22 critérios; dar score /100.
|
||||
2. Registrar: o que está bom, o que está desatualizado, o que está errado
|
||||
(claims que não batem com o código), o que falta.
|
||||
3. `project-readme-clarity` — checar ambiguidades de onboarding (dependência
|
||||
opcional apresentada como obrigatória, passo que bloqueia primeiro valor).
|
||||
Sem README, siga direto para a Fase 4.
|
||||
|
||||
Se NÃO existe README:
|
||||
1. Anotar Fase 1+2 e seguir direto para a Fase 4 (draft).
|
||||
## Fase 4: GENERATE
|
||||
|
||||
VERIFICAR (comandos de auditoria):
|
||||
- `grep -c "^#\|^##" README.md` — conta headings p/ o TOC futuro.
|
||||
- `grep -oE "\]\([^)]*\)" README.md | grep -oE "\(\.?/?" | sort -u` — links
|
||||
locais que precisam existir no disco; conferir com `ls` que cada um vive.
|
||||
- `grep -nE "install|npm |pnpm |pip |docker " README.md` — comandos citados;
|
||||
validar se existem de fato no repo (não só no texto).
|
||||
- `bash ~/.hermes/skills/curating-readme/scripts/audit-repo.sh .` — re-rodar
|
||||
o inventory se o repo mudou desde a Fase 1.
|
||||
1. Estrutura por tipo: título, badges do que existe, uma linha de descrição, o que faz, pré-requisitos,
|
||||
quick start copiável, uso, configuração (tabela de env vars do `.env.example`), estrutura,
|
||||
contribuição, licença. Detalhe em [references/estrutura.md](references/estrutura.md).
|
||||
2. Badge só do que existe: licença com `LICENSE`, build com CI configurada, versão com pacote publicado.
|
||||
3. Todo comando e exemplo mostrado precisa rodar neste repo.
|
||||
4. Uma língua por arquivo; tradução vai em arquivo separado (`README.pt-BR.md`).
|
||||
5. Passe `avoid-ai-writing` no texto, se instalada.
|
||||
|
||||
**Comandos de auditoria (Fase 3):**
|
||||
```bash
|
||||
grep -nc "^#\|^##" README.md # headings existentes
|
||||
grep -oE "\]\(\.?/?[^)]*\)" README.md # links locais citados
|
||||
grep -nE "npm (install|run)|pnpm|pip |docker (run|compose)|uv " README.md 2>/dev/null
|
||||
# validar que cada comando existe de fato:
|
||||
command -v pnpm && pnpm --version
|
||||
git log --oneline -3
|
||||
```
|
||||
## Fase 5: VERIFY (antes de entregar)
|
||||
|
||||
**Anti-padrões (Fase 3):**
|
||||
- NÃO dar score alto para README bonito mas incorreto (acurácia > estética).
|
||||
- NÃO ignorar claims do README que não batem com o código — cada divergência
|
||||
é finding a corrigir.
|
||||
- NÃO apresentar dependência opcional como obrigatória (project-readme-clarity).
|
||||
1. **Rode os comandos** de instalação e quick start num ambiente limpo (clone novo ou diretório
|
||||
temporário). O que não der para rodar (precisa de credencial, serviço externo, hardware),
|
||||
liste no relatório com o motivo. Nunca escreva "testado" sobre o que não rodou.
|
||||
2. **Links locais resolvem**: cada `](caminho)` aponta para arquivo que existe.
|
||||
3. **Links externos respondem**: `curl -sI -o /dev/null -w '%{http_code}' <url>` em cada um.
|
||||
4. **Referências existem**: arquivos, scripts, env vars e flags citados estão no repo.
|
||||
5. **Índice bate** com os headings, se houver índice.
|
||||
6. Nenhum `TODO:` sobrou no texto final.
|
||||
|
||||
**Checklist da fase 3:**
|
||||
- [ ] README existente auditado (22 critérios / score) OU confirmado inexistente
|
||||
- [ ] Checks de onboarding/ambiguidade rodados
|
||||
- [ ] Comandos/links do README atual validados contra o repo
|
||||
- [ ] Score baseline registrado (se README existia)
|
||||
Comandos prontos: [references/verificacao.md](references/verificacao.md).
|
||||
|
||||
## Fase 4 — GENERATE (escrever com fatos verificados)
|
||||
## Relatório
|
||||
|
||||
1. Estrutura canônica por tipo (referências do `good-readme`/`curating-readme`):
|
||||
título + badges (só os que existem) + descrição 1 linha + features reais +
|
||||
stack + prereqs + quickstart copy-paste + usage + config (tabela de env) +
|
||||
estrutura do projeto + contributing + license.
|
||||
2. **Badges:** só incluir badges que refletem a realidade (license, linguagem,
|
||||
build se houver CI) — não criar badge de coisa que não existe.
|
||||
3. **Exemplos de código: reais e testados.** Se o README mostra um comando
|
||||
ou exemplo, ELE DEVE funcionar no repo — verificar.
|
||||
4. `avoid-ai-writing`: após redigir, limpar AI-isms (em-dash em excesso,
|
||||
"robust/seamless/leverage", transições genéricas, conclusões vazias).
|
||||
5. Se o README for de repo público bonito (estilo shadcn/Vercel): seguir o
|
||||
padrão visual do `wf-frontend` (hero + badges + TOC + tabelas limpas).
|
||||
6. VERIFICAR: cada claim do README tem fonte no repo (manifest, código,
|
||||
script, LICENSE) — nada inventado.
|
||||
O que mudou, os achados da auditoria (antes e depois), os comandos executados com o resultado e o
|
||||
que não pôde ser verificado.
|
||||
|
||||
**Comandos reais (Fase 4):**
|
||||
```bash
|
||||
# comandos do README que precisam existir no repo
|
||||
grep -oE '\b(npm|pnpm|python3|node |git|docker|uv) [^`]+' README.md
|
||||
# conferir licença/tipo
|
||||
head -1 LICENSE 2>/dev/null
|
||||
# TOC vs headings: contar headings reais
|
||||
grep -oE '^#{2,3} ' README.md | wc -l
|
||||
```
|
||||
## Não faça
|
||||
|
||||
**Checklist da fase 4:**
|
||||
- [ ] Estrutura canônica seguida (adaptada ao tipo)
|
||||
- [ ] Badges só do que existe
|
||||
- [ ] Exemplos verificados contra o código
|
||||
- [ ] 0 AI-isms (detect do avoid-ai-writing)
|
||||
- [ ] Todo claim tem fonte
|
||||
- Inventar instalação, comando, exemplo, screenshot ou feature.
|
||||
- Copiar a estrutura de outro projeto sem adaptar ao tipo e ao público.
|
||||
- Duplicar a mesma informação em duas seções.
|
||||
- Encher de emojis ou badges decorativos.
|
||||
|
||||
## Fase 5 — VERIFY + VALIDATE (prova de qualidade)
|
||||
## Critério de aceite
|
||||
|
||||
1. Validar README gerado:
|
||||
- Rodar `audit-repo.sh <repo>` de novo: conferir que nada essencial ficou
|
||||
de fora.
|
||||
- Checar links locais resolvem (`grep -o ']([^)]*)' README.md`; arquivos
|
||||
citados existem).
|
||||
- TOC bate com headings.
|
||||
- Comandos no README existem (checar que os binários/comandos citados
|
||||
são reais).
|
||||
2. `good-readme` — re-auditar: score final deve subir vs Fase 3 (se houve
|
||||
README antes) ou ser alto (≥85/100) se criado.
|
||||
3. `avoid-ai-writing` detect: 0 AI-isms restantes.
|
||||
4. VERIFICAR gate do próprio workflow: `python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py`.
|
||||
5. Relatório: score antes → depois, o que mudou, checks que passaram.
|
||||
|
||||
**Checklist final:**
|
||||
- [ ] Links locais resolvem
|
||||
- [ ] Comandos do README são reais
|
||||
- [ ] TOC bate
|
||||
- [ ] Score de qualidade ≥ 85/100 (good-readme) ou melhorou vs antes
|
||||
- [ ] 0 AI-isms
|
||||
- [ ] Gate do workflow (test_quality.py) verde
|
||||
|
||||
**Comandos de validação (Fase 5):**
|
||||
```bash
|
||||
# 1) links locais do README existem
|
||||
grep -oE '\]\(\.?/?[^)]*\)' README.md | sed 's/](//; s/)$//' | while read p; do [ -e "$p" ] || echo "MISSING: $p"; done
|
||||
# 2) TOC vs headings (sem TOC = ok, com TOC precisa bater)
|
||||
grep -oE '^##{1,3} ' README.md | wc -l
|
||||
# 3) 0 AI-isms (em-dash em excesso)
|
||||
grep -o "—" README.md | wc -l
|
||||
# 4) refere o LICENSE/contribuição existem
|
||||
ls LICENSE CONTRIBUTING.md 2>/dev/null
|
||||
# 5) gate do stack
|
||||
python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py
|
||||
```
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NÃO pular a re-auditoria (good-readme score) por "tá bom já".
|
||||
- NÃO entregar sem rodar o detect do avoid-ai-writing (AI-ism = regressão).
|
||||
- NÃO tratar "README mais bonito" como objetivo sem validar acurácia —
|
||||
bonito ≠ correto; a acurácia vem antes.
|
||||
|
||||
## Regras duras
|
||||
|
||||
- NUNCA inventar instalação, comando, exemplo, screenshot ou feature que
|
||||
não exista no repo — fato sem fonte vira TODO ou pergunta.
|
||||
- NUNCA incluir badge de coisa que não existe (CI sem CI, licensa sem LICENSE).
|
||||
- NUNCA entregar README com AI-isms (rodar avoid-ai-writing antes de fechar).
|
||||
- NUNCA afirmar "testado" sem ter executado o comando.
|
||||
- NUNCA copiar estrutura de outro projeto sem adaptar ao tipo/público real.
|
||||
- README do usuário do repo deve entender "clono → rodar" sem configurar
|
||||
dependência opcional desnecessária (project-readme-clarity).
|
||||
- NUNCA deixar `TODO:` no README final — TODO só durante o rascunho; na
|
||||
entrega, todo fato ou foi preenchido com fonte ou virou pergunta ao usuário.
|
||||
- NUNCA trocar linguagem da prosa no meio (EN/PT misturados) — o README
|
||||
principal tem UMA língua; traduções vão em arquivos separados.
|
||||
- NÃO encher de emojis/badges decorativos; cada elemento tem função.
|
||||
- NÃO duplicar informação (instalação em 2 seções é bug de manutenção).
|
||||
- [ ] Toda afirmação tem fonte no repo ou virou pergunta respondida.
|
||||
- [ ] Comandos de instalação e quick start executados, ou listados como não verificáveis com motivo.
|
||||
- [ ] Links locais e externos resolvem; arquivos citados existem.
|
||||
- [ ] Badges só do que existe; nenhum `TODO:` no texto final.
|
||||
@@ -0,0 +1,30 @@
|
||||
# Estrutura do README por tipo
|
||||
|
||||
Ordem base. Corte a seção que não se aplica em vez de preencher com texto genérico.
|
||||
|
||||
| Seção | Fonte no repo | Obrigatória para |
|
||||
|---|---|---|
|
||||
| Título e uma linha de descrição | `name`/`description` do manifest | todos |
|
||||
| Badges | `LICENSE`, `.github/workflows/`, registro do pacote | só o que existe |
|
||||
| O que faz | entrypoints, exports, rotas | todos |
|
||||
| Pré-requisitos | `engines`, `requires-python`, `go` no `go.mod`, Dockerfile | todos |
|
||||
| Quick start | scripts do manifest, `Makefile` | todos |
|
||||
| Uso | saída real do `--help`, exemplos que rodam | CLI, biblioteca |
|
||||
| API | exports públicos, OpenAPI | biblioteca, API |
|
||||
| Configuração | `.env.example`, arquivo de config | quem tem env vars |
|
||||
| Estrutura do projeto | árvore real (`git ls-files`) | monorepo, app |
|
||||
| Contribuição | `CONTRIBUTING.md`, comandos de teste e lint | open source |
|
||||
| Licença | `LICENSE` | todos |
|
||||
|
||||
## Por tipo
|
||||
|
||||
- **Biblioteca**: instalação pelo gerenciador, um exemplo mínimo que roda, link para a API.
|
||||
- **CLI**: instalação, `--help` real, dois ou três comandos comuns com a saída.
|
||||
- **Web app**: pré-requisitos, `.env`, como subir em dev, como rodar os testes.
|
||||
- **API**: como subir, onde está o OpenAPI, autenticação, um `curl` que funciona.
|
||||
- **Monorepo**: tabela de pacotes com uma linha cada e o comando para rodar todos.
|
||||
|
||||
## Quick start
|
||||
|
||||
Copiável de ponta a ponta: clonar, instalar, configurar, rodar, ver o primeiro resultado.
|
||||
Dependência opcional fica fora do caminho principal, numa seção à parte.
|
||||
@@ -0,0 +1,25 @@
|
||||
# Comandos de verificação do README
|
||||
|
||||
Rode da raiz do repositório.
|
||||
|
||||
```bash
|
||||
# Links locais que não existem no disco
|
||||
grep -oE '\]\([^)#]+' README.md | sed 's/^](//' | grep -vE '^(https?:|mailto:)' \
|
||||
| while read -r p; do [ -e "$p" ] || echo "FALTA: $p"; done
|
||||
|
||||
# Links externos que não respondem 2xx/3xx
|
||||
grep -oE 'https?://[^) >"]+' README.md | sort -u | while read -r u; do
|
||||
c=$(curl -sIL -o /dev/null -w '%{http_code}' --max-time 10 "$u")
|
||||
case "$c" in 2*|3*) ;; *) echo "$c $u";; esac
|
||||
done
|
||||
|
||||
# TODO esquecido
|
||||
grep -n 'TODO' README.md
|
||||
|
||||
# Quick start num clone limpo (troque pelos comandos do README)
|
||||
tmp=$(mktemp -d) && git clone -q . "$tmp/repo" && cd "$tmp/repo"
|
||||
# ... cole aqui os comandos de instalação e quick start, na ordem do README
|
||||
```
|
||||
|
||||
Para CLI, compare a seção de uso com `<cli> --help`. Para API, rode o `curl` do README contra o
|
||||
servidor local e confira o status. Anote no relatório cada comando e o resultado.
|
||||
@@ -1,6 +1,11 @@
|
||||
---
|
||||
name: wf-refactor
|
||||
description: Use para refatorar, reorganizar, renomear, extrair, simplificar ou limpar código sem mudar o comportamento. Congela o comportamento com testes antes de mexer e mexe em passos pequenos.
|
||||
license: MIT
|
||||
metadata:
|
||||
dev-workflows:
|
||||
uses: []
|
||||
external: []
|
||||
---
|
||||
|
||||
# Workflow Refactor
|
||||
|
||||
@@ -1,209 +1,104 @@
|
||||
---
|
||||
name: wf-security-review
|
||||
description: "Code review de segurança (front+back). OSV/NVD + OWASP."
|
||||
version: 1.0.0
|
||||
author: Hermes Agent
|
||||
description: Use para revisão de segurança de código, diff ou PR (frontend e backend), para varrer dependências atrás de CVE, procurar segredos commitados ou auditar auth, API e injeção; também quando o dev-router dispara um gatilho de segurança (auth, dinheiro, dados pessoais, upload, SQL montado à mão, dependência nova, feature com LLM). Consulta fontes vivas de vulnerabilidade com data. Não use para revisão de correção ou estilo sem aspecto de segurança (isso é o agente reviewer) nem para desenhar arquitetura (wf-architecture).
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [security, code-review, cve, owasp, sast, sca, workflow, devsecops]
|
||||
dev-workflows:
|
||||
uses: [safedeps, sca-audit, code-review-security, secrets-scan, api-security-review, web-security-review, cve-triage, patch-prioritization, dependency-scanning, hermaguard]
|
||||
external: [bola-detector, injection-checker, auth-rbac-scaffold]
|
||||
---
|
||||
|
||||
# Workflow Security Code Review (front + backend)
|
||||
# Workflow Security Review
|
||||
|
||||
Orquestrador obrigatório para todo code review de segurança — frontend E
|
||||
backend. Cobre: revisão de código (OWASP), vulnerabilidades conhecidas em
|
||||
dependências, E consulta de NOVAS vulnerabilidades nos lugares certos
|
||||
(OSV.dev, NVD, GitHub Advisory) para que o review esteja sempre atualizado,
|
||||
não preso ao cutoff de treino do modelo.
|
||||
O conhecimento de CVE do modelo para na data de corte do treino. Por isso toda revisão consulta
|
||||
fontes vivas (OSV.dev, GitHub Advisory Database, NVD, CISA KEV) e registra a data da consulta.
|
||||
**Nunca afirme "sem CVE" sem ter consultado.** Uma revisão sem fonte e sem data já nasce vencida.
|
||||
|
||||
## When to Use
|
||||
Este workflow vem pré-carregado no agente `security-auditor`.
|
||||
|
||||
- "revisa a segurança desse código/PR/diff" (front ou back)
|
||||
- "escaneia dependências por CVEs" / "alguma lib vulnerável?"
|
||||
- "tem vulnerabilidade nova conhecida pra X?" (consulta de atualização)
|
||||
- "audita auth/API/injeção" / "procura segredos commitados"
|
||||
- QUALQUER review de merge que mexa em dado sensível ou rota nova
|
||||
- Pré-commit ou pré-deploy como etapa de segurança
|
||||
## Profundidade por nível (do `dev-router`)
|
||||
|
||||
## Skills do stack (3 principais + auxiliares)
|
||||
| Nível | Escopo | Padrão | Ferramentas |
|
||||
|---|---|---|---|
|
||||
| 1 com gatilho | só o diff | Top 10 no que o diff toca | gate `--tier 1` (gitleaks, semgrep) |
|
||||
| 2 | diff + superfície alcançável (rotas, handlers, queries, componentes que usam o código alterado) | ASVS 5.0 L1 | gate `--tier 2` (+ osv-scanner), `safedeps` em toda dependência nova |
|
||||
| 3 ou auditoria completa | toda a superfície | ASVS 5.0 L2 | gate `--tier 3` (+ trivy), passe adversarial do `hermaguard`, STRIDE contra a arquitetura |
|
||||
|
||||
**As 3 skills de segurança atuais (instaladas de fontes primárias):**
|
||||
1. `safedeps` (Jeneidi) — grounding em OSV.dev em tempo real: consulta
|
||||
`package@version` e traz CVE com severidade e fix. Cobre o gap de o
|
||||
modelo só conhecer vulns até o cutoff. CLI: `check_deps.py`.
|
||||
2. `sca-audit` (OWASP secure-agent-playbook) — SCA (Supply Chain Analysis)
|
||||
de dependências com análise de alcance (reachability), CWE mapping.
|
||||
3. `code-review-security` (OWASP secure-agent-playbook) — code review de
|
||||
segurança sistemático mapeado a OWASP Top 10 + ASVS.
|
||||
Gate: `"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier N`. Checagens e configuração em
|
||||
[../dev-router/references/quality-gate.md](../dev-router/references/quality-gate.md). Os scanners
|
||||
são ponto de partida, não substituem a leitura do código.
|
||||
|
||||
**Auxiliares (carregar por contexto):**
|
||||
- `secrets-scan` (OWASP) — busca credenciais/API keys no código e git history
|
||||
- `api-security-review` + `bola-detector` + `auth-rbac-scaffold` +
|
||||
`injection-checker` (OWASP/API) — revisão de API
|
||||
- `web-security-review` (OWASP) — web app OWASP Top 10
|
||||
- `cve-triage` + `patch-prioritization` (UnitOne/SecuritySkills) — priorizar
|
||||
CVE por CVSS 4.0 / EPSS / CISA KEV
|
||||
- Locais: `dependency-cve-audit`, `hermaguard` (caça bugs adversariais),
|
||||
`security-threat-model`
|
||||
## Fase 1: SCOPE
|
||||
|
||||
## Fase 1 — SCOPE (definir alvo antes de auditar)
|
||||
1. Delimite o alvo: `git diff --stat <base>` e arquivos não rastreados; front, back ou os dois.
|
||||
2. Registre a stack, os gerenciadores de pacote e os lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `requirements.txt`, `poetry.lock`, `go.mod`, `Cargo.lock`).
|
||||
3. No nível 2 ou mais, mapeie a superfície alcançável: quem chama o código alterado e o que fica exposto (rota, fila, webhook, UI).
|
||||
|
||||
1. Identificar o que está no escopo: diff/PR, arquivos, front, back, ambos.
|
||||
2. Registrar stack do projeto (linguagens, frameworks, package managers,
|
||||
se há lockfile: package-lock.json / requirements.txt / go.mod / etc).
|
||||
3. Rodar o código? Identificar se há ambiente local testável.
|
||||
4. VERIFICAR: `git status` + `git diff --stat` para delimitar o alvo real.
|
||||
5. Checkpoint: confirmar escopo com o usuário antes de gastar auditoria.
|
||||
## Fase 2: HUNT (dependências)
|
||||
|
||||
**Checklist da fase 1:**
|
||||
- [ ] Escopo delimitado (arquivos/diff/PR)
|
||||
- [ ] Stack e lockfiles identificados
|
||||
- [ ] Alvo confirmado
|
||||
1. `safedeps` nas dependências novas ou alteradas, com versão e ecossistema:
|
||||
`python3 "${CLAUDE_PLUGIN_ROOT}/skills/safedeps/check_deps.py" [email protected]:npm`
|
||||
ou o manifest inteiro: `python3 "${CLAUDE_PLUGIN_ROOT}/skills/safedeps/check_deps.py" requirements.txt`.
|
||||
2. `sca-audit` para alcance (reachability): a função vulnerável é chamada pelo projeto?
|
||||
3. `cve-triage` e `patch-prioritization` para ordenar por CVSS 4.0, EPSS e CISA KEV.
|
||||
4. Separe **alcançável** (bloqueia) de **não alcançável** (risco residual registrado).
|
||||
|
||||
## Fase 2 — HUNT (vulnerabilidades conhecidas — dimensão de dependências)
|
||||
## Fase 3: CONSULT (fontes vivas)
|
||||
|
||||
1. `sca-audit` — scan de dependências com análise de alcance; mapear CVEs
|
||||
por severidade e reachable/unreachable.
|
||||
2. `safedeps` — para cada dependência-chave do manifest, consultar OSV.dev:
|
||||
`python3 ~/.hermes/skills/safedeps/check_deps.py "pkg@version"` (ou via
|
||||
manifest completo) — traz CVE reais com fix (o modelo NÃO sabe CVE nova
|
||||
do cutoff pra frente; o OSV.dev sim).
|
||||
3. `cve-triage` / `patch-prioritization` — priorizar achados por
|
||||
CVSS 4.0 / EPSS / CISA KEV quando disponível.
|
||||
4. `dependency-cve-audit` (local) — varredura das deps do projeto atual.
|
||||
5. VERIFICAR: consolidar lista de CVE com severidade + versão afetada +
|
||||
versão fixa; separar reachable (devem ser bloqueantes) de non-reachable
|
||||
(registrar como risco residual).
|
||||
6. CHECKPOINT: apresentar sumário de CVE antes de partir para o code review.
|
||||
Responda "há vulnerabilidade nova que eu não conheço?" consultando, com data:
|
||||
|
||||
**Comandos úteis:**
|
||||
```bash
|
||||
python3 ~/.hermes/skills/safedeps/check_deps.py "lodash@4.17.20" # 1 pkg
|
||||
python3 ~/.hermes/skills/safedeps/check_deps.py -f package-lock.json # manifest
|
||||
# veja a skill sca-audit p/ reachability; cve-triage p/ priorização
|
||||
```
|
||||
- OSV.dev (já coberto pelo `safedeps`; batch: `POST https://api.osv.dev/v1/querybatch`).
|
||||
- GitHub Advisory Database: `gh api graphql -f query='{securityAdvisories(first:10, orderBy:{field:PUBLISHED_AT,direction:DESC}){nodes{ghsaId summary severity publishedAt}}}'`.
|
||||
- NVD: `curl -s "https://services.nvd.nist.gov/rest/json/cves/2.0?keywordSearch=<framework>&resultsPerPage=10"`.
|
||||
- CISA KEV para saber se já há exploração ativa.
|
||||
- Página de security ou changelog do framework em uso.
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NUNCA afirmar "sem CVE" sem ter CONSULTADO OSV.dev (memória do modelo é
|
||||
congelada no cutoff).
|
||||
- NÃO tratar CVE de dependência transitiva não-reachable como crítica igual
|
||||
a reachable — reportar com nuance.
|
||||
- NUNCA rodar scan em lockfile sem conferir o package manager certo.
|
||||
Vulnerabilidade nova que afeta a versão do projeto vira achado HIGH, com a versão de correção.
|
||||
|
||||
**Comandos reais (Fase 2):**
|
||||
```bash
|
||||
python3 ~/.hermes/skills/safedeps/check_deps.py "express@4.18.2"
|
||||
python3 ~/.hermes/skills/safedeps/check_deps.py -f package-lock.json
|
||||
# alternatives: npm audit --json / pip-audit -r requirements.txt / trivy fs .
|
||||
```
|
||||
## Fase 4: CODE REVIEW
|
||||
|
||||
## Fase 3 — CONSULT (novas vulnerabilidades — atualização contínua)
|
||||
Referências atuais: **OWASP Top 10:2025**, **OWASP API Security Top 10 (2023)**, **ASVS 5.0** e,
|
||||
se a feature chama um LLM, **OWASP LLM Top 10 (2025)**. As skills OWASP vendorizadas ainda citam o
|
||||
Top 10 de 2021; use o mapa 2021 para 2025 em [references/owasp-2025.md](references/owasp-2025.md).
|
||||
|
||||
O objetivo é responder "há vulnerabilidade NOVA que eu não conheço?" — o
|
||||
modelo só sabe até o cutoff; consultar fontes vivas:
|
||||
**Frontend** (`web-security-review`, `code-review-security`):
|
||||
- renderização de HTML com entrada do usuário (`dangerouslySetInnerHTML`, `v-html`, `innerHTML`);
|
||||
- segredo no bundle do cliente; token em `localStorage` (prefira cookie `httpOnly`, `Secure`, `SameSite`);
|
||||
- CSP, links e redirecionamentos montados com entrada do usuário.
|
||||
|
||||
1. OSV.dev (API aberta, sem key) — já coberto na Fase 2 via safedeps.
|
||||
2. GitHub Advisory Database — via `gh api`:
|
||||
`gh api graphql -f query='{securityAdvisories(first:10, orderBy:{field:PUBLISHED_AT,direction:DESC}){nodes{ghsaId,summary,severity,publishedAt}}}'
|
||||
3. NVD — via API (key opcional): consultar CPE do stack ou CVEs recentes do
|
||||
framework em uso (`curl -s "https://services.nvd.nist.gov/rest/json/cves/2.0?keywordSearch=..."`).
|
||||
4. Registros de framework (ex: changelog/security de Next.js, Express,
|
||||
NestJS, FastAPI) — advisories recentes do framework do projeto.
|
||||
5. VERIFICAR: para LIB versão X e FRAMEWORK Y, registrar qual fonte foi
|
||||
consultada e a data — sem "não tem" sem fonte.
|
||||
6. CHECKPOINT: se alguma vuln nova afeta o stack do projeto, tratar como
|
||||
finding HIGH e sugerir upgrade.
|
||||
**Backend** (`code-review-security`, `api-security-review`; se instaladas, `bola-detector`, `injection-checker`, `auth-rbac-scaffold`):
|
||||
- autenticação e autorização por objeto (BOLA/IDOR): a query é escopada pelo usuário autenticado?
|
||||
- injeção: SQL, ORM cru, shell, template, path traversal; SSRF (agora dentro de A01);
|
||||
- tratamento de condição excepcional (A10:2025): erro que falha aberto, exceção engolida, stack trace na resposta;
|
||||
- rate limit em escrita e login, CORS com allowlist explícita, segredo nunca em log.
|
||||
|
||||
**Comandos úteis:**
|
||||
```bash
|
||||
gh api graphql -f query='{securityAdvisories(first:10, orderBy:{field:PUBLISHED_AT,direction:DESC}){nodes{ghsaId,summary,severity,publishedAt}}}'
|
||||
curl -s "https://services.nvd.nist.gov/rest/json/cves/2.0?keywordSearch=nextjs&resultsPerPage=10"
|
||||
# OSV batch: curl -s -X POST https://api.osv.dev/v1/querybatch -d '@manifests.json'
|
||||
```
|
||||
**Segredos**: `secrets-scan` no diff e no histórico (`git log -p -S "<padrão>"`); o gitleaks do gate cobre os arquivos alterados.
|
||||
|
||||
**Anti-padrões desta fase:**
|
||||
- NUNCA responder "não tem vulnerabilidade nova" sem citar fonte viva + data.
|
||||
- NÃO confiar no cutoff do modelo para saber CVE recente — sempre consultar.
|
||||
- NÃO esquecer de incluir data da consulta (revisão vence se ficar velho).
|
||||
**Cadeia de suprimentos** (A03:2025): dependência nova justificada, lockfile commitado, scripts de
|
||||
instalação suspeitos, versões fixadas no CI.
|
||||
|
||||
## Fase 4 — CODE REVIEW (front + backend, OWASP)
|
||||
**Nível 3**: rode o `hermaguard` no diff (edge cases, ataque, blast radius) e confira o threat model
|
||||
STRIDE do `wf-architecture`: cada ameaça tem mitigação no código?
|
||||
|
||||
Frontend (`web-security-review` + `code-review-security`):
|
||||
1. XSS/injeção em renderização (dangerouslySetInnerHTML, v-html, innerHTML).
|
||||
2. Exposição de segredos no client (API keys, tokens em bundle).
|
||||
3. Containers: loads, links com user input, cookies httpOnly/secure.
|
||||
4. `secrets-scan` — credenciais no código e git history.
|
||||
5. Auth de frontend: fluxo de tokens, storage inseguro (localStorage p/ JWT).
|
||||
Cada achado: severidade (CRITICAL, HIGH, MEDIUM, LOW), CWE, referência OWASP, `arquivo:linha`,
|
||||
passos de exploração, impacto e correção. Diferencie confirmado de suspeita. "Não achei com grep"
|
||||
não é "não existe": siga o fluxo.
|
||||
|
||||
Backend (`code-review-security` + `api-security-review` + `bola-detector` +
|
||||
`auth-rbac-scaffold` + `injection-checker`):
|
||||
1. AuthN/AuthZ: rotas sem auth, IDOR/BOLA (`bola-detector`), RBAC.
|
||||
2. Input validation: SQLi, XSS, command injection, SSRF, path traversal
|
||||
(`injection-checker`).
|
||||
3. Segredos: env vars, nunca logar senha/token.
|
||||
4. Rate limit, erros sem vazar stack trace, CORS correto.
|
||||
5. `hermaguard` (opcional) p/ caça adversarial de bugs no mesmo diff.
|
||||
6. VERIFICAR: para cada rota com `:id`, rodar `bola-detector` de novo (IDOR
|
||||
é o achado nº1 em API) e para cada query, `injection-checker`.
|
||||
7. VERIFICAR: rodar `secrets-scan` no diff E git history antes de fechar —
|
||||
credencial commitada em algum commit antigo ainda vaza.
|
||||
8. VERIFICAR: conferir erros sem stack trace (grep por exceptions/console no
|
||||
cliente) e CORS/headers (`grep -rn "access-control\|csp"`).
|
||||
9. VERIFICAR: `grep -rn "localStorage\|sessionStorage" src/` — nenhum JWT
|
||||
sensível em storage de frontend (usar httpOnly cookie).
|
||||
10. VERIFICAR: confirmar rate limit em rotas de escrita (`grep -rniE "limiter|rate"`) e que respostas não vazam caminho interno.
|
||||
## Fase 5: REPORT + GATE
|
||||
|
||||
**Output por finding:** Severidade (Critical/High/Med/Low) + CWE + OWASP ref +
|
||||
Arquivo:linha + Evidência + Remediação.
|
||||
Relatório com: cabeçalho (nível, escopo, padrão ASVS e a linha "consulta de atualização feita em
|
||||
<AAAA-MM-DD> via <fontes>"), resumo por severidade, decisão do gate, os achados, tabela de
|
||||
dependências (pacote, versão, CVE, severidade, corrigida em, alcançável, fonte), veredito do gate de
|
||||
qualidade com o que ficou não verificado, e riscos aceitos.
|
||||
|
||||
**Anti-padrões desta fase (front + back):**
|
||||
- NUNCA approve sem reportar achado de AuthN/AuthZ ou injection como mínimo.
|
||||
- Padrão de coerência — NÃO misturar "parece ok" com achado sem evidência.
|
||||
- NÃO confundir "não achei com grep" com "não existe" — checar fluxo inteiro.
|
||||
- NÃO focar só no front quando o fix toca o back (IDOR/BOLA vive no back).
|
||||
|
||||
**Comandos de auditoria (Fase 4):**
|
||||
```bash
|
||||
# segredos: busca em código e git history
|
||||
grep -rniE "(api[_-]?key|secret|password|token|bearer)" src/ | grep -v node_modules
|
||||
git log -p --all -S "sk-" --oneline | head # chave vazada em commit antigo
|
||||
# headers/CORS/rate limit
|
||||
grep -rniE "access-control|content-security-policy" src/
|
||||
grep -rniE "ratelimit|rate_limit|limiter|express-rate" src/
|
||||
python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py # gate
|
||||
```
|
||||
|
||||
## Fase 5 — REPORT + GATE (entregar e decidir)
|
||||
|
||||
1. Consolidar tudo: sumário (nº por severidade), findings detalhados,
|
||||
tabela de CVE com fonte/estado/reachable/fix, e status "consulta de
|
||||
atualização feita em <data> via <fontes>".
|
||||
2. GATE: Critical/High reachable → BLOQUEAR merge até corrigir. Medium →
|
||||
tratar no próximo ciclo. Low/residual → registrar risco aceito.
|
||||
3. Re-auditar após fixes: re-rodar as checagens que acusaram P0/P1.
|
||||
4. VERIFICAR: `python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py`
|
||||
(gate não-regressivo do stack de workflows).
|
||||
5. Relatório final em markdown (report.md) + resumo em chat.
|
||||
6. VERIFICAR (comandos de report): gerar `security-report.md` com
|
||||
`find . -maxdepth 2 -name "*.md" | sort` conferindo artefatos, e
|
||||
`grep -c "CVE-" security-report.md` para ter contagem explícita no doc.
|
||||
7. VERIFICAR (data da consulta): `grep -i "data da consulta\|20[2-9][0-9]-" security-report.md` — sem revisão sem carimbo de data (ela vence).
|
||||
|
||||
**Checklist de entrega:**
|
||||
- [ ] Os 3 pilares rodados: safedeps (OSV), sca-audit, code-review-security.
|
||||
- [ ] Consulta de novas vulns feita em fonte viva (OSV/GH Advisory/NVD) com data.
|
||||
- [ ] Findings com CWE + OWASP + evidência + remediação.
|
||||
- [ ] GATE aplicado (block/allow) por severidade/reachability.
|
||||
- [ ] Nenhuma skill do stack removida; test_quality.py passando.
|
||||
Regra do gate: **CRITICAL ou HIGH alcançável em aberto = não aprovado.** MEDIUM entra no próximo
|
||||
ciclo; LOW e residual ficam registrados como risco aceito. Depois de cada correção, rode de novo a
|
||||
checagem que acusou o problema e o gate no mesmo nível.
|
||||
|
||||
## Regras duras
|
||||
|
||||
- NUNCA afirmar "sem vulnerabilidades" sem consultar OSV.dev/GH Advisory
|
||||
(modelo tem cutoff; fonte viva não).
|
||||
- NUNCA reportar CVE sem incluir versão afetada + versão fixa.
|
||||
- NUNCA blocker Critical/High reachable "para depois" — bloquear merge.
|
||||
- NUNCA logar/expor segredo durante o review (nem no relatório).
|
||||
- Re-auditar sempre que o fix tocar >3 arquivos ou mudar dependência.
|
||||
- SQL/queries: sempre parâmetros posicionais, nunca concatenação de input.
|
||||
- Nunca "sem vulnerabilidades" sem consulta a fonte viva com data.
|
||||
- Nunca CVE sem versão afetada e versão corrigida.
|
||||
- Nunca expor um segredo encontrado no relatório: cite arquivo, linha e tipo, com o valor mascarado.
|
||||
- Queries sempre parametrizadas, nunca concatenadas com entrada.
|
||||
- Correção que muda dependência ou mais de 3 arquivos: nova rodada de revisão.
|
||||
@@ -0,0 +1,48 @@
|
||||
# Referências OWASP atuais
|
||||
|
||||
Confira a lista oficial em https://owasp.org/Top10/ se houver dúvida de nome ou ordem.
|
||||
|
||||
## Top 10:2021 (usado pelas skills vendorizadas) para Top 10:2025
|
||||
|
||||
| 2021 | 2025 | Observação |
|
||||
|---|---|---|
|
||||
| A01 Broken Access Control | A01 Broken Access Control | agora inclui SSRF |
|
||||
| A02 Cryptographic Failures | A04 Cryptographic Failures | |
|
||||
| A03 Injection | A05 Injection | XSS continua aqui |
|
||||
| A04 Insecure Design | A06 Insecure Design | |
|
||||
| A05 Security Misconfiguration | A02 Security Misconfiguration | subiu |
|
||||
| A06 Vulnerable and Outdated Components | A03 Software Supply Chain Failures | **ampliada**: build, CI, registro de pacotes, dependências |
|
||||
| A07 Identification and Authentication Failures | A07 Authentication Failures | |
|
||||
| A08 Software and Data Integrity Failures | A08 Software or Data Integrity Failures | |
|
||||
| A09 Security Logging and Monitoring Failures | A09 Security Logging and Alerting Failures | |
|
||||
| A10 Server-Side Request Forgery | (dentro de A01) | |
|
||||
| n/a | A10 Mishandling of Exceptional Conditions | **nova**: erro que falha aberto, exceção engolida, estado inconsistente após falha |
|
||||
|
||||
## API Security Top 10 (2023)
|
||||
|
||||
API1 Broken Object Level Authorization · API2 Broken Authentication · API3 Broken Object Property
|
||||
Level Authorization · API4 Unrestricted Resource Consumption · API5 Broken Function Level
|
||||
Authorization · API6 Unrestricted Access to Sensitive Business Flows · API7 Server Side Request
|
||||
Forgery · API8 Security Misconfiguration · API9 Improper Inventory Management · API10 Unsafe
|
||||
Consumption of APIs.
|
||||
|
||||
## ASVS 5.0 (maio de 2025)
|
||||
|
||||
Checklist por nível, mais de 300 requisitos em 17 capítulos (inclui segurança de frontend web e tokens
|
||||
autocontidos). Use o nível que o `dev-router` definiu:
|
||||
|
||||
- **L1** (nível 2): o mínimo para qualquer aplicação exposta.
|
||||
- **L2** (nível 3): aplicação com dados sensíveis ou transações; o padrão recomendado para a maioria.
|
||||
- **L3**: só com pedido explícito (dado crítico, alto valor).
|
||||
|
||||
Fonte: https://github.com/OWASP/ASVS
|
||||
|
||||
## LLM Top 10 (2025), para features que chamam um LLM
|
||||
|
||||
LLM01 Prompt Injection · LLM02 Sensitive Information Disclosure · LLM03 Supply Chain · LLM04 Data and
|
||||
Model Poisoning · LLM05 Improper Output Handling · LLM06 Excessive Agency · LLM07 System Prompt
|
||||
Leakage · LLM08 Vector and Embedding Weaknesses · LLM09 Misinformation · LLM10 Unbounded Consumption.
|
||||
|
||||
O mais comum em código de aplicação: saída do modelo usada sem validação (LLM05), ferramentas ou
|
||||
permissões demais para o agente (LLM06), segredo ou dado de outro usuário no prompt (LLM02) e custo
|
||||
sem limite (LLM10).
|
||||
Reference in new issue
Block a user