diff --git a/skills/NOTICE.md b/skills/NOTICE.md index 52bd22a..c8c51f3 100644 --- a/skills/NOTICE.md +++ b/skills/NOTICE.md @@ -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///`). Como aqui o diretório é plano (`skills//`), 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 diff --git a/skills/dev-router/SKILL.md b/skills/dev-router/SKILL.md index 2ade19d..24d3faa 100644 --- a/skills/dev-router/SKILL.md +++ b/skills/dev-router/SKILL.md @@ -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 diff --git a/skills/lean-code/SKILL.md b/skills/lean-code/SKILL.md index 1f32098..3c52e27 100644 --- a/skills/lean-code/SKILL.md +++ b/skills/lean-code/SKILL.md @@ -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 diff --git a/skills/wf-architecture/SKILL.md b/skills/wf-architecture/SKILL.md index 6b7b8a3..8ceb9ae 100644 --- a/skills/wf-architecture/SKILL.md +++ b/skills/wf-architecture/SKILL.md @@ -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/.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 "" 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/.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-.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/.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. diff --git a/skills/wf-architecture/references/adr.md b/skills/wf-architecture/references/adr.md new file mode 100644 index 0000000..f40e0df --- /dev/null +++ b/skills/wf-architecture/references/adr.md @@ -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. diff --git a/skills/wf-architecture/references/c4.md b/skills/wf-architecture/references/c4.md new file mode 100644 index 0000000..dac81f2 --- /dev/null +++ b/skills/wf-architecture/references/c4.md @@ -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. diff --git a/skills/wf-architecture/references/ears.md b/skills/wf-architecture/references/ears.md new file mode 100644 index 0000000..2f333d3 --- /dev/null +++ b/skills/wf-architecture/references/ears.md @@ -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 | `REQ-001: THE SYSTEM SHALL registrar toda alteração de preço com autor e data.` | +| Evento | WHEN THE SYSTEM SHALL | `REQ-002: WHEN o usuário envia o formulário de cadastro THE SYSTEM SHALL responder 201 com o ID criado.` | +| Indesejado | IF THEN THE SYSTEM SHALL | `REQ-003: IF o token expirou THEN THE SYSTEM SHALL responder 401 sem revelar se a conta existe.` | +| Estado | WHILE THE SYSTEM SHALL | `REQ-004: WHILE a fila tiver mais de 1000 itens THE SYSTEM SHALL recusar novos jobs com 429.` | +| Opcional | WHERE THE SYSTEM SHALL | `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. diff --git a/skills/wf-architecture/references/stride.md b/skills/wf-architecture/references/stride.md new file mode 100644 index 0000000..5705f9a --- /dev/null +++ b/skills/wf-architecture/references/stride.md @@ -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..`) +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. diff --git a/skills/wf-backend/SKILL.md b/skills/wf-backend/SKILL.md index b48195d..a1700b4 100644 --- a/skills/wf-backend/SKILL.md +++ b/skills/wf-backend/SKILL.md @@ -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. diff --git a/skills/wf-backend/references/checks.md b/skills/wf-backend/references/checks.md new file mode 100644 index 0000000..dfc289f --- /dev/null +++ b/skills/wf-backend/references/checks.md @@ -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. diff --git a/skills/wf-bugfix/SKILL.md b/skills/wf-bugfix/SKILL.md index eda17a4..c5543c3 100644 --- a/skills/wf-bugfix/SKILL.md +++ b/skills/wf-bugfix/SKILL.md @@ -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 diff --git a/skills/wf-frontend/SKILL.md b/skills/wf-frontend/SKILL.md index 16aa6f0..dd6b689 100644 --- a/skills/wf-frontend/SKILL.md +++ b/skills/wf-frontend/SKILL.md @@ -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 "= 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-.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. diff --git a/skills/wf-frontend/references/checks.md b/skills/wf-frontend/references/checks.md new file mode 100644 index 0000000..005f826 --- /dev/null +++ b/skills/wf-frontend/references/checks.md @@ -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 +``` diff --git a/skills/wf-frontend/references/pdf.md b/skills/wf-frontend/references/pdf.md new file mode 100644 index 0000000..f073f7a --- /dev/null +++ b/skills/wf-frontend/references/pdf.md @@ -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. diff --git a/skills/wf-readme/SKILL.md b/skills/wf-readme/SKILL.md index 5592071..286e9fe 100644 --- a/skills/wf-readme/SKILL.md +++ b/skills/wf-readme/SKILL.md @@ -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 ` - (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 --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}' ` 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 ` 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. diff --git a/skills/wf-readme/references/estrutura.md b/skills/wf-readme/references/estrutura.md new file mode 100644 index 0000000..9975fab --- /dev/null +++ b/skills/wf-readme/references/estrutura.md @@ -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. diff --git a/skills/wf-readme/references/verificacao.md b/skills/wf-readme/references/verificacao.md new file mode 100644 index 0000000..323cfba --- /dev/null +++ b/skills/wf-readme/references/verificacao.md @@ -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 ` --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. diff --git a/skills/wf-refactor/SKILL.md b/skills/wf-refactor/SKILL.md index 7aed468..38c120f 100644 --- a/skills/wf-refactor/SKILL.md +++ b/skills/wf-refactor/SKILL.md @@ -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 diff --git a/skills/wf-security-review/SKILL.md b/skills/wf-security-review/SKILL.md index 7d5626f..8466d4f 100644 --- a/skills/wf-security-review/SKILL.md +++ b/skills/wf-security-review/SKILL.md @@ -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 ` 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" express@4.18.2: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=&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 ""`); 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 + via "), 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 via ". -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. diff --git a/skills/wf-security-review/references/owasp-2025.md b/skills/wf-security-review/references/owasp-2025.md new file mode 100644 index 0000000..b0e62d4 --- /dev/null +++ b/skills/wf-security-review/references/owasp-2025.md @@ -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).