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