177 lines
12 KiB
Markdown
177 lines
12 KiB
Markdown
<div align="center">
|
|
|
|
<img src="assets/readme/hero.svg" width="100%" alt="dev-workflows: workflows de agente em que toda fase termina num passo de verificação, mostrados como o checklist do SKILL.md wf-security-review de SCOPE a REPORT + GATE">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[Issues](https://git.evandro.dev.br/evandro/dev-workflows/issues) · [Inventário de skills](docs/SKILLS.md) · [Aviso das skills vendorizadas](skills/NOTICE.md) · [Como contribuir](CONTRIBUTING.md)
|
|
|
|
[English](README.md) · **Português (BR)**
|
|
|
|
</div>
|
|
|
|
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):
|
|
|
|
```console
|
|
$ 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`](workflows/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`](workflows/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`](workflows/wf-architecture.md) | REQUIREMENTS, DESIGN, DOCS, REVIEW | Requisitos mensuráveis, diagramas C4, ADRs, threat modeling |
|
|
| Security review | [`wf-security-review.md`](workflows/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`](workflows/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/`](skills/NOTICE.md) e traz um harness de QA em [`qa/`](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.
|
|
|
|
<details>
|
|
<summary>Skills que os workflows carregam</summary>
|
|
|
|
Vendorizadas em `skills/` (security review). Origem, commit e licença de cada cópia estão em [`skills/NOTICE.md`](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](https://github.com/Jeneidi/safedeps) | MIT |
|
|
| `sca-audit` | Auditoria da cadeia de dependências com análise de alcançabilidade e mapeamento CWE | [OWASP/secure-agent-playbook](https://github.com/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](https://github.com/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](https://github.com/Sahil-SS9/hermaguard) | MIT |
|
|
|
|
Não vendorizadas (instale à parte; inventário completo em [`docs/SKILLS.md`](docs/SKILLS.md)):
|
|
|
|
| Workflow | Skill | Origem |
|
|
|---|---|---|
|
|
| Frontend | `frontend-design` | [anthropics/skills](https://github.com/anthropics/skills) |
|
|
| Frontend | `web-design` | [KAOPU-XiaoPu/web-design](https://github.com/KAOPU-XiaoPu/web-design) |
|
|
| Frontend | `vercel-react-best-practices`, `vercel-composition-patterns` | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) |
|
|
| Frontend | `animate` | [emilkowalski/skill](https://github.com/emilkowalski/skill) |
|
|
| Frontend | `impeccable` | [pbakaus/impeccable](https://github.com/pbakaus/impeccable) |
|
|
| Frontend | `avoid-ai-writing` | [conorbronsdon/avoid-ai-writing](https://github.com/conorbronsdon/avoid-ai-writing) |
|
|
| Frontend | `anti-ai-slop` | skill local, não publicada aqui |
|
|
| Backend | `secure-coding` | [securityreviewai/secure-coding-skill](https://github.com/securityreviewai/secure-coding-skill) |
|
|
| Backend | `bola-detector`, `auth-rbac-scaffold`, `injection-checker`, `openapi-hardener`, `api-security-review`, `security-test-generator` | [apisec-inc/apisec-skills](https://github.com/apisec-inc/apisec-skills) |
|
|
| Arquitetura | `system-design`, `c4-architecture`, `isaqb-architecture-governance`, `secure-architecture-governance` | [Kotivskyi/architecture-governance-skills](https://github.com/Kotivskyi/architecture-governance-skills) |
|
|
| README | `readme-crafter` | [linhai0872/readme-crafter-skill](https://github.com/linhai0872/readme-crafter-skill) |
|
|
| README | `good-readme` | [adewale/good-readme](https://github.com/adewale/good-readme) |
|
|
| README | `curating-readme` | [liang-senbei/curating-readme](https://github.com/liang-senbei/curating-readme) |
|
|
| Security review | `dependency-cve-audit`, `security-threat-model` | skills locais, não publicadas aqui |
|
|
|
|
</details>
|
|
|
|
## Início rápido
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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`](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`](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](LICENSE), (c) 2026 Evandro Fonseca Junior. As skills vendorizadas mantêm as próprias licenças ([`skills/NOTICE.md`](skills/NOTICE.md)).
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
<sub>Feito por <a href="https://evandro.dev.br">Evandro Fonseca Junior</a> · <a href="https://git.evandro.dev.br/evandro">git.evandro.dev.br</a></sub>
|
|
</div>
|