Evandro Fonseca Junior
ee44fa0f7a
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.
226 lines
10 KiB
Markdown
226 lines
10 KiB
Markdown
---
|
||
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).
|