feat: add wf-readme workflow + skills, validated, applied to this repo

New wf-readme workflow (grounded README creation/audit/rewrite) built on readme-crafter, good-readme and curating-readme skills. Validated with the QA harness: 302.3 -> 379.0 on the same ruler, all phases verified, no false-positive skill refs. Applied it to this repo: audit-repo.sh scan, link/TOC/em-dash validation, added CONTRIBUTING.md (gap the workflow flagged) and wired the docs.
2026-08-19 17:37:45 -03:00
1 parent 45b2259bce
commit ee44fa0f7a
@@ -0,0 +1,36 @@
+# Contributing
+
+Thanks for taking the time to contribute. This project is small, so keep it simple: open an issue to discuss first, then send a PR.
+
+## What to improve
+
+Workflows, skills, or the QA harness. All changes should keep the same rules the workflows themselves enforce:
+
+1. **Grounded.** Every claim in a workflow or README must trace back to a real repository fact. No fabricated commands, examples, or badges.
+2. **Verifiable phases.** A phase is not done until it has a verification step (a command that proves the work). Add one if you touch a workflow.
+3. **No AI-isms.** Docs and workflows must pass the avoid-ai-writing check (no em-dash runs, no "robust/seamless/leverage" filler).
+
+## What not to change
+
+- The QA harness must keep its meta-tests green. If you change scoring, re-run `qa/test_tests.py` and update `qa/snapshots/baseline-final.json`.
+- Do not remove skills referenced by workflows without updating the workflows and `docs/SKILLS.md` together.
+
+## Local checks before a PR
+
+```bash
+cd qa
+python3 wf_quality_harness.py    # score must not drop below baseline
+python3 test_quality.py          # gates green
+python3 test_tests.py            # meta-tests green
+```
+
+## Process
+
+1. Fork the repo.
+2. Create a branch: `git checkout -b feat/your-change`.
+3. Make the change. Keep it small and focused.
+4. Run the qa checks above.
+5. Commit with a clear message.
+6. Open a PR describing what changed and why.
+
+Questions or ideas: open an issue.
@@ -47,6 +47,7 @@ Every workflow here forces the agent to **prove** the work at each phase:
 | ⚙️ **Backend / API** | [workflows/wf-backend.md](workflows/wf-backend.md) | Contract before handler, safe defaults, OWASP audit, tests + adversarial bug hunt |
 | 🏗️ **Architecture** | [workflows/wf-architecture.md](workflows/wf-architecture.md) | Measurable requirements, C4 diagrams, ADRs, threat modeling, review |
 | 🛡️ **Security review** | [workflows/wf-security-review.md](workflows/wf-security-review.md) | Code review (front + back), known CVEs **and** live lookup of new ones |
+| 📄 **README** | [workflows/wf-readme.md](workflows/wf-readme.md) | Create/audit/rewrite READMEs grounded in real repo facts |

 Each file is a standard `SKILL.md`. The `description` in the frontmatter is the trigger: when the agent's context matches it, the workflow loads automatically. Works in [Hermes Agent](https://hermes-agent.nousresearch.com), Claude Code, and anything that reads the Agent Skills format.

@@ -215,6 +216,7 @@ dev-workflows/
 │   └── wf-security-review.md
 ├── docs/
 │   └── SKILLS.md        # full skill inventory + install steps
+├── CONTRIBUTING.md      # what to improve, local checks, PR process
 └── qa/                  # quality harness, gates, meta-tests
    ├── wf_quality_harness.py
    ├── test_quality.py
@@ -47,6 +47,7 @@ Cada workflow força o agente a **provar** o trabalho em cada fase:
 | ⚙️ **Backend / API** | [workflows/wf-backend.md](workflows/wf-backend.md) | Contrato antes do handler, defaults seguros, auditoria OWASP, testes + caça de bugs adversarial |
 | 🏗️ **Arquitetura** | [workflows/wf-architecture.md](workflows/wf-architecture.md) | Requisitos mensuráveis, diagramas C4, ADRs, threat modeling, revisão |
 | 🛡️ **Security review** | [workflows/wf-security-review.md](workflows/wf-security-review.md) | Code review (front + back), CVEs conhecidas **e** consulta ao vivo de novas |
+| 📄 **README** | [workflows/wf-readme.md](workflows/wf-readme.md) | Criar/auditar/reescrever READMEs grounded nos fatos reais do repo |

 Cada arquivo é um `SKILL.md` padrão. A `description` no frontmatter é o gatilho: quando o contexto do agente bate, o workflow carrega sozinho. Funciona no [Hermes Agent](https://hermes-agent.nousresearch.com), Claude Code e qualquer coisa que leia o formato Agent Skills.

@@ -215,6 +216,7 @@ dev-workflows/
 │   └── wf-security-review.md
 ├── docs/
 │   └── SKILLS.md        # inventário completo de skills + instalação
+├── CONTRIBUTING.md      # o que melhorar, checks locais, processo de PR
 └── qa/                  # harness de qualidade, gates, meta-testes
    ├── wf_quality_harness.py
    ├── test_quality.py
@@ -3,6 +3,24 @@
 Este é o inventário do que os workflows carregam. Cada skill é um diretório
 com um `SKILL.md`; para o Hermes Agent, vão em `~/.hermes/skills/`.

+## Workflows orquestradores (em `workflows/`)
+
+| Workflow | Para quê |
+|---|---|
+| `wf-frontend` | UI/design/PDF |
+| `wf-backend` | API/backend seguro |
+| `wf-architecture` | Arquitetura/ADR/C4 |
+| `wf-security-review` | Code review de segurança front+back |
+| `wf-readme` | Criar/auditar/reescrever READMEs grounded |
+
+## README (wf-readme)
+
+| Skill | Origem | O que faz |
+|---|---|---|
+| `readme-crafter` | [linhai0872/readme-crafter-skill](https://github.com/linhai0872/readme-crafter-skill) | Classifica projeto (tipo/público/temperamento) e gera README sob medida; 13 checks |
+| `good-readme` | [adewale/good-readme](https://github.com/adewale/good-readme) | Cria com exemplos reais OU audita contra 22 critérios (escala 100) |
+| `curating-readme` | [liang-senbei/curating-readme](https://github.com/liang-senbei/curating-readme) | Padroniza README + docs (CONTRIBUTING/CHANGELOG) com `audit-repo.sh` |
+
 ## Pilar de segurança (wf-security-review)

 | Skill | Origem | O que faz |
@@ -0,0 +1,225 @@
+---
+name: wf-readme
+description: "Criar/auditar/reescrever README grounded. Scan real do repo."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [readme, documentation, docs, markdown, workflow]
+---
+
+# Workflow README (criar, auditar, reescrever)
+
+Orquestrador obrigatório para qualquer trabalho de README (criar, melhorar,
+auditar, padronizar) em qualquer projeto. Princípio central: **grounded** —
+o README é construído a partir de fatos reais do repositório (manifest,
+código, scripts, config, git), nunca fabricado de memória.
+
+## When to Use
+
+- "cria um README pra esse projeto" / "escreve a documentação"
+- "melhora esse README" / "audita a qualidade do README"
+- "padroniza a documentação do repo"
+- Qualquer pedido de documentação de projeto (README/LICENSE/docs)
+
+## Skills do stack
+
+- `readme-crafter` (linhai0872) — classifica o projeto em 4 eixos (tipo,
+  distribuição, público, temperamento) e gera README sob medida; 13 checks
+  de verificação; modo collaborative/quick/surgical/audit.
+- `good-readme` (adewale) — cria do zero com exemplos reais de código OU
+  audita contra rubric de 22 critérios (escala 100); verifica exemplos
+  contra o código real.
+- `curating-readme` (liang-senbei) — padroniza README + docs relacionados
+  (CONTRIBUTING/CHANGELOG/SECURITY/docs) com scripts determinísticos
+  (`audit-repo.sh`) e estrutura canônica.
+- Locais: `project-readme-clarity` (auditoria de onboarding/ambiguidades),
+  `avoid-ai-writing` (remove AI-isms), `wf-frontend` (padrão visual de
+  docs/README bonitos).
+
+## Fase 1 — SCAN (coletar fatos reais)
+
+1. Rodar o inventory determinístico do repo:
+   `bash ~/.hermes/skills/curating-readme/scripts/audit-repo.sh <repo>`
+   (ou o `scan-project.sh` do readme-crafter) — coleta manifest, entrypoints,
+   scripts, config, estrutura, env vars, git, linguagens.
+2. Ler manifest principal (package.json / pyproject.toml / go.mod / etc):
+   nome, descrição, versão, dependências, scripts.
+3. Identificar entrypoints: o que o projeto realmente faz (não o que diz).
+4. Ler README existente (se houver), CLI_AGENTS.md, LICENSE.
+5. VERIFICAR: marcar como **fato verificado** cada item com fonte no repo;
+   qualquer coisa sem fonte vira `TODO:`/pergunta — nunca inventar.
+6. VERIFICAR (comandos de scan): rodar `python3 -c "import json; json.load(open('package.json'))"`
+   (ou equivalente para o manifest) para provar que o manifest parseia;
+   e `git remote -v && git log --oneline -5` para capturar contexto real.
+7. VERIFICAR (inventário): conferir com `find . -maxdepth 1 -type f | wc -l`
+   a contagem real de arquivos e `du -sh .` para não documentar coisa que
+   não existe. TRÊS CHECKS: manifest válido, git real, inventário presente.
+
+**Checklist da fase 1:**
+- [ ] Inventory do repo rodado (audit-repo.sh / scan-project.sh)
+- [ ] Manifest lido e entendido
+- [ ] Fato × suposição separados (suposição vira TODO/pergunta)
+
+## Fase 2 — CLASSIFY (entender público e tipo)
+
+1. `readme-crafter` — classificar o projeto:
+   - Tipo: library / CLI / web app / framework / API / agent-AI / monorepo / ...
+   - Distribuição: open-source público vs interno
+   - Público: avaliador / novo usuário / contribuidor / operador / agente IA
+   - Temperamento: developer utility / product / academic / community
+2. Decidir audiência PRIMÁRIA (o README serve a quem primeiro).
+3. VERIFICAR: registrar decisões de classificação (1 linha cada) — a
+   estrutura do README deriva delas.
+4. SE necessário, fazer perguntas do tipo "quem é o público?" ou "qual
+   o tom?" quando o código não revela a intenção (3-5 perguntas máx).
+5. VERIFICAR (comandos de classificação): para software com CLI, rodar
+   `python3 -m <pkg> --help` (ou `node bin/index.js --help`) para capturar
+   a sintaxe real de uso; para web app, listar `find src pages app -maxdepth 1 -type d 2>/dev/null` para ver as rotas reais.
+6. VERIFICAR (decisões): registrar as 4 classificações com fonte — "tipo=CLI
+   porque package.json.bin existe"; "público=developer porque docs de API".
+
+**Checklist da fase 2:**
+- [ ] Tipo / distribuição / público / temperamento definidos
+- [ ] Audiência primária nomeada
+- [ ] Perguntas de intenção (se houve) respondidas
+
+## Fase 3 — AUDIT ou DRAFT (estado atual)
+
+Se JÁ existe README:
+1. `good-readme` — auditar contra 22 critérios; dar score /100.
+2. Registrar: o que está bom, o que está desatualizado, o que está errado
+   (claims que não batem com o código), o que falta.
+3. `project-readme-clarity` — checar ambiguidades de onboarding (dependência
+   opcional apresentada como obrigatória, passo que bloqueia primeiro valor).
+
+Se NÃO existe README:
+1. Anotar Fase 1+2 e seguir direto para a Fase 4 (draft).
+
+VERIFICAR (comandos de auditoria):
+- `grep -c "^#\|^##" README.md` — conta headings p/ o TOC futuro.
+- `grep -oE "\]\([^)]*\)" README.md | grep -oE "\(\.?/?" | sort -u` — links
+  locais que precisam existir no disco; conferir com `ls` que cada um vive.
+- `grep -nE "install|npm |pnpm |pip |docker " README.md` — comandos citados;
+  validar se existem de fato no repo (não só no texto).
+- `bash ~/.hermes/skills/curating-readme/scripts/audit-repo.sh .` — re-rodar
+  o inventory se o repo mudou desde a Fase 1.
+
+**Comandos de auditoria (Fase 3):**
+```bash
+grep -nc "^#\|^##" README.md              # headings existentes
+grep -oE "\]\(\.?/?[^)]*\)" README.md      # links locais citados
+grep -nE "npm (install|run)|pnpm|pip |docker (run|compose)|uv " README.md 2>/dev/null
+# validar que cada comando existe de fato:
+command -v pnpm && pnpm --version
+git log --oneline -3
+```
+
+**Anti-padrões (Fase 3):**
+- NÃO dar score alto para README bonito mas incorreto (acurácia > estética).
+- NÃO ignorar claims do README que não batem com o código — cada divergência
+  é finding a corrigir.
+- NÃO apresentar dependência opcional como obrigatória (project-readme-clarity).
+
+**Checklist da fase 3:**
+- [ ] README existente auditado (22 critérios / score) OU confirmado inexistente
+- [ ] Checks de onboarding/ambiguidade rodados
+- [ ] Comandos/links do README atual validados contra o repo
+- [ ] Score baseline registrado (se README existia)
+
+## Fase 4 — GENERATE (escrever com fatos verificados)
+
+1. Estrutura canônica por tipo (referências do `good-readme`/`curating-readme`):
+   título + badges (só os que existem) + descrição 1 linha + features reais +
+   stack + prereqs + quickstart copy-paste + usage + config (tabela de env) +
+   estrutura do projeto + contributing + license.
+2. **Badges:** só incluir badges que refletem a realidade (license, linguagem,
+   build se houver CI) — não criar badge de coisa que não existe.
+3. **Exemplos de código: reais e testados.** Se o README mostra um comando
+   ou exemplo, ELE DEVE funcionar no repo — verificar.
+4. `avoid-ai-writing`: após redigir, limpar AI-isms (em-dash em excesso,
+   "robust/seamless/leverage", transições genéricas, conclusões vazias).
+5. Se o README for de repo público bonito (estilo shadcn/Vercel): seguir o
+   padrão visual do `wf-frontend` (hero + badges + TOC + tabelas limpas).
+6. VERIFICAR: cada claim do README tem fonte no repo (manifest, código,
+   script, LICENSE) — nada inventado.
+
+**Comandos reais (Fase 4):**
+```bash
+# comandos do README que precisam existir no repo
+grep -oE '\b(npm|pnpm|python3|node |git|docker|uv) [^`]+' README.md
+# conferir licença/tipo
+head -1 LICENSE 2>/dev/null
+# TOC vs headings: contar headings reais
+grep -oE '^#{2,3} ' README.md | wc -l
+```
+
+**Checklist da fase 4:**
+- [ ] Estrutura canônica seguida (adaptada ao tipo)
+- [ ] Badges só do que existe
+- [ ] Exemplos verificados contra o código
+- [ ] 0 AI-isms (detect do avoid-ai-writing)
+- [ ] Todo claim tem fonte
+
+## Fase 5 — VERIFY + VALIDATE (prova de qualidade)
+
+1. Validar README gerado:
+   - Rodar `audit-repo.sh <repo>` de novo: conferir que nada essencial ficou
+     de fora.
+   - Checar links locais resolvem (`grep -o ']([^)]*)' README.md`; arquivos
+     citados existem).
+   - TOC bate com headings.
+   - Comandos no README existem (checar que os binários/comandos citados
+     são reais).
+2. `good-readme` — re-auditar: score final deve subir vs Fase 3 (se houve
+   README antes) ou ser alto (≥85/100) se criado.
+3. `avoid-ai-writing` detect: 0 AI-isms restantes.
+4. VERIFICAR gate do próprio workflow: `python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py`.
+5. Relatório: score antes → depois, o que mudou, checks que passaram.
+
+**Checklist final:**
+- [ ] Links locais resolvem
+- [ ] Comandos do README são reais
+- [ ] TOC bate
+- [ ] Score de qualidade ≥ 85/100 (good-readme) ou melhorou vs antes
+- [ ] 0 AI-isms
+- [ ] Gate do workflow (test_quality.py) verde
+
+**Comandos de validação (Fase 5):**
+```bash
+# 1) links locais do README existem
+grep -oE '\]\(\.?/?[^)]*\)' README.md | sed 's/](//; s/)$//' | while read p; do [ -e "$p" ] || echo "MISSING: $p"; done
+# 2) TOC vs headings (sem TOC = ok, com TOC precisa bater)
+grep -oE '^##{1,3} ' README.md | wc -l
+# 3) 0 AI-isms (em-dash em excesso)
+grep -o "—" README.md | wc -l
+# 4) refere o LICENSE/contribuição existem
+ls LICENSE CONTRIBUTING.md 2>/dev/null
+# 5) gate do stack
+python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py
+```
+
+**Anti-padrões desta fase:**
+- NÃO pular a re-auditoria (good-readme score) por "tá bom já".
+- NÃO entregar sem rodar o detect do avoid-ai-writing (AI-ism = regressão).
+- NÃO tratar "README mais bonito" como objetivo sem validar acurácia —
+  bonito ≠ correto; a acurácia vem antes.
+
+## Regras duras
+
+- NUNCA inventar instalação, comando, exemplo, screenshot ou feature que
+  não exista no repo — fato sem fonte vira TODO ou pergunta.
+- NUNCA incluir badge de coisa que não existe (CI sem CI, licensa sem LICENSE).
+- NUNCA entregar README com AI-isms (rodar avoid-ai-writing antes de fechar).
+- NUNCA afirmar "testado" sem ter executado o comando.
+- NUNCA copiar estrutura de outro projeto sem adaptar ao tipo/público real.
+- README do usuário do repo deve entender "clono → rodar" sem configurar
+  dependência opcional desnecessária (project-readme-clarity).
+- NUNCA deixar `TODO:` no README final — TODO só durante o rascunho; na
+  entrega, todo fato ou foi preenchido com fonte ou virou pergunta ao usuário.
+- NUNCA trocar linguagem da prosa no meio (EN/PT misturados) — o README
+  principal tem UMA língua; traduções vão em arquivos separados.
+- NÃO encher de emojis/badges decorativos; cada elemento tem função.
+- NÃO duplicar informação (instalação em 2 seções é bug de manutenção).