dev-workflows/README.pt-BR.md

Issues · Inventário de skills · Aviso das skills vendorizadas · Como contribuir

English · Português (BR)

Saída do harness depois de instalar os workflows e as skills vendorizadas no layout do Hermes (execução real; impeccable é uma skill de terceiros que não foi instalada, por isso o harness sai com código 1):

$ cd qa && python wf_quality_harness.py
wf-frontend        score= 385.5  refs=18 sem_match=['impeccable'] fases_sem_verif=[]
wf-backend         score= 424.0  refs=15 sem_match=[] fases_sem_verif=[]
wf-architecture    score= 413.7  refs=11 sem_match=[] fases_sem_verif=[]
wf-security-review score= 390.0  refs=14 sem_match=[] fases_sem_verif=[]

TOTAL: 1613.2 / 400.0  (403.3%)

O que é

Cinco workflows de agente escritos como arquivos SKILL.md padrão. A description no frontmatter de cada um é o gatilho: o workflow carrega quando o contexto do agente bate com ela. O corpo dos workflows está em português.

Workflow	Arquivo	Fases	Cobre
Frontend / UI	wf-frontend.md	DESIGN, BUILD, REVIEW	Direção de design antes do código, anti-AI-slop, performance React, QA visual de PDFs
Backend / API	wf-backend.md	PLAN, BUILD, SECURITY, TEST + BUG HUNT	Contrato antes do handler, defaults seguros, auditoria OWASP, testes e caça de bugs adversarial
Arquitetura	wf-architecture.md	REQUIREMENTS, DESIGN, DOCS, REVIEW	Requisitos mensuráveis, diagramas C4, ADRs, threat modeling
Security review	wf-security-review.md	SCOPE, HUNT, CONSULT, CODE REVIEW, REPORT + GATE	Code review de front e back, CVEs conhecidas e consulta ao vivo das novas
README	wf-readme.md	SCAN, CLASSIFY, AUDIT ou DRAFT, GENERATE, VERIFY + VALIDATE	Criar, auditar ou reescrever READMEs com base em fatos reais do repositório

O repositório também vendoriza dez skills de segurança em skills/ e traz um harness de QA em qa/.

Por que usar

Agente gera código bem e admite que não sabe muito mal. Cada workflow obriga o agente a provar o trabalho em cada fase:

• Passos de verificação: rodar o build, rodar os testes, chamar a API, consultar o registry.
• Critérios de aceite: checkboxes que precisam estar marcados para a fase fechar.
• Regras duras: "nunca faça merge com build vermelho", "nunca afirme 'sem CVE' sem consultar o OSV.dev".

Não use se você quer skills autossuficientes. Os workflows de frontend, backend, arquitetura e README carregam skills de terceiros que não estão neste repositório, o de segurança também espera duas skills locais que não foram vendorizadas, e o harness de QA só lê o layout do Hermes Agent.

Como funciona

O workflow de segurança parte de um fato: o conhecimento de CVEs de um modelo para na data do treinamento, então "sem vulnerabilidades" vindo da memória é chute.

1. SCOPE define o alvo antes da auditoria.
2. HUNT checa CVEs conhecidas nas dependências (safedeps consulta o OSV.dev para um pacote@versão).
3. CONSULT busca vulnerabilidades novas em fontes vivas: OSV.dev, GitHub Advisory DB e NVD.
4. CODE REVIEW revisa o código de front e back contra OWASP Top 10 e ASVS.
5. REPORT + GATE entrega o relatório com fontes e data carimbadas e decide.

O harness de QA pontua wf-frontend, wf-backend, wf-architecture e wf-security-review (não o wf-readme) em mais de 30 critérios estáticos extraídos de cada SKILL.md: estrutura, passos numerados por fase, verbos de verificação, skills referenciadas e densidade de AI-isms. O test_tests.py tem meta-testes que quebram o harness de propósito e conferem se a nota muda.

Skills que os workflows carregam

Vendorizadas em skills/ (security review). Origem, commit e licença de cada cópia estão em skills/NOTICE.md; a CC-BY-4.0 exige atribuição, mantida nesse arquivo.

Skill	O que faz	Origem	Licença
safedeps	Consulta o OSV.dev ao vivo: CVE, severidade e versão corrigida de um pacote@versão (script check_deps.py)	Jeneidi/safedeps	MIT
sca-audit	Auditoria da cadeia de dependências com análise de alcançabilidade e mapeamento CWE	OWASP/secure-agent-playbook	CC-BY-4.0
code-review-security	Code review de segurança sistemático mapeado para OWASP Top 10 + ASVS	OWASP/secure-agent-playbook	CC-BY-4.0
secrets-scan	Credenciais e chaves de API hardcoded no código e no histórico do git	OWASP/secure-agent-playbook	CC-BY-4.0
api-security-review	Revisão de API contra o OWASP API Security Top 10	OWASP/secure-agent-playbook	CC-BY-4.0
web-security-review	Revisão de app web contra o OWASP Top 10	OWASP/secure-agent-playbook	CC-BY-4.0
cve-triage	Prioriza CVEs com CVSS 4.0, EPSS e CISA KEV	UnitOneAI/SecuritySkills	MIT
patch-prioritization	Decide a ordem de correção	UnitOneAI/SecuritySkills	MIT
dependency-scanning	Varredura da árvore de dependências	UnitOneAI/SecuritySkills	MIT
hermaguard	Revisão adversarial: pré-varredura estática mais 3 agentes especialistas (casos de borda, ataque, raio de impacto)	Sahil-SS9/hermaguard	MIT

Não vendorizadas (instale à parte; inventário completo em docs/SKILLS.md):

Workflow	Skill	Origem
Frontend	frontend-design	anthropics/skills
Frontend	web-design	KAOPU-XiaoPu/web-design
Frontend	vercel-react-best-practices, vercel-composition-patterns	vercel-labs/agent-skills
Frontend	animate	emilkowalski/skill
Frontend	impeccable	pbakaus/impeccable
Frontend	avoid-ai-writing	conorbronsdon/avoid-ai-writing
Frontend	anti-ai-slop	skill local, não publicada aqui
Backend	secure-coding	securityreviewai/secure-coding-skill
Backend	bola-detector, auth-rbac-scaffold, injection-checker, openapi-hardener, api-security-review, security-test-generator	apisec-inc/apisec-skills
Arquitetura	system-design, c4-architecture, isaqb-architecture-governance, secure-architecture-governance	Kotivskyi/architecture-governance-skills
README	readme-crafter	linhai0872/readme-crafter-skill
README	good-readme	adewale/good-readme
README	curating-readme	liang-senbei/curating-readme
Security review	dependency-cve-audit, security-threat-model	skills locais, não publicadas aqui

Início rápido

# 1. Copie os workflows para o diretório de skills do seu agente

# Hermes Agent
cp workflows/*.md ~/.hermes/skills/software-development/

# Claude Code: cada skill precisa do próprio diretório (um .md solto não carrega)
mkdir -p ~/.claude/skills
for f in workflows/*.md; do
  name=$(basename "$f" .md)
  mkdir -p "$HOME/.claude/skills/$name"
  cp "$f" "$HOME/.claude/skills/$name/SKILL.md"
done

# 2. Security review: as skills de apoio já estão vendorizadas em skills/.
# Hermes:
cp -r skills/* ~/.hermes/skills/
# Claude Code: copie cada diretório skills/<nome>/ para ~/.claude/skills/<nome>/
# (o SKILL.md precisa ficar dentro do próprio diretório, como no passo 1).

# 3. Use
# "revise este PR para segurança"  -> carrega o wf-security-review
# "crie uma página nova"           -> carrega o wf-frontend

As demais skills se instalam com npx skills (formato agentskills.io), por exemplo:

npx skills add anthropics/skills --skill frontend-design
npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices
npx skills add conorbronsdon/avoid-ai-writing
npx skills add https://github.com/pbakaus/impeccable --skill impeccable

Warning

O layout da instalação importa. O Claude Code ignora um .md solto; ele precisa de <skill>/SKILL.md. O harness de QA tem a mesma exigência: ele lê ~/.hermes/skills/software-development/<workflow>/SKILL.md, então o cp plano usado acima para o Hermes não basta para rodá-lo.

Uso

cd qa
python3 wf_quality_harness.py   # pontua cada workflow em mais de 30 critérios
python3 test_quality.py         # gates: sem regressão, skills referenciadas existem, toda fase verificada
python3 test_tests.py           # meta-testes: corrompem harness/workflows e conferem que a nota cai

As notas finais de cada workflow estão versionadas em qa/snapshots/baseline-final.json: wf-frontend 385.5, wf-backend 424.0, wf-architecture 413.7, wf-security-review 390.0, total 1613.2. A execução acima reproduz esses valores.

Estado do projeto

Seis commits entre 2026-08-19 e 2026-10-13; todo workflow declara version: 1.0.0. Não há CI na raiz: skills/hermaguard/.github/workflows/ci.yml pertence ao hermaguard vendorizado e não roda a partir deste repositório.

• O harness lê as cópias instaladas em ~/.hermes/skills/software-development/<nome>/SKILL.md (SKILLS_DIR fixo no código), não os arquivos de workflows/. Sem elas, ele informa SKILL.md não encontrado.
• O harness sai com código 1 quando falta uma skill referenciada, e aí o test_quality.py para com HARNESS FALHOU. Mesmo com todas as skills instaladas, o gate G3 exige que cada workflow chegue ao dobro da própria nota final, então o test_quality.py não passa contra o snapshot atual.
• O test_tests.py altera wf-frontend/SKILL.md na raiz do repositório, arquivo que não existe, então esse meta-teste não faz nada; a mutação do anti-slop continua rodando.
• A checagem de "skills referenciadas existem" também aceita nomes de uma lista fixa no código, sem olhar o disco.
• O wf-security-review cita dependency-cve-audit e security-threat-model como skills locais que não foram vendorizadas e chama ~/.hermes/skills/safedeps/check_deps.py, então pressupõe o layout do Hermes.
• Duas skills diferentes têm o nome api-security-review: a da OWASP, vendorizada, e a da apisec-inc, usada pelo workflow de backend. Instalar as duas no mesmo diretório faz uma sobrescrever a outra.
• Em docs/SKILLS.md, o trecho para o Claude Code coloca o til entre aspas ("~/.claude/skills/$nome"), o que cria um diretório ~ literal; use $HOME como no Início rápido acima.
• O wf-readme não é coberto pelo harness.

As regras de contribuição estão em CONTRIBUTING.md: toda afirmação remete a fatos do repositório, toda fase tem um passo de verificação e a documentação evita AI-isms.

Licença

MIT, (c) 2026 Evandro Fonseca Junior. As skills vendorizadas mantêm as próprias licenças (skills/NOTICE.md).

---

_{Feito por Evandro Fonseca Junior · git.evandro.dev.br}