0 Fork 0

Files

T

EvandroandClaude Opus 5.5 f2db2d69da refactor(skills): cut the workflows to ~100 lines and scale phases by tier

Each workflow was ~300 lines of grep-count "VERIFICAR" steps and ran every
phase for every request. Phases now state their minimum tier, checks are the
quality gate plus real tools, detail moved to references/, and machine-specific
paths and non-public skills are gone. Security references move to OWASP Top
10:2025, ASVS 5.0 and the OWASP LLM Top 10.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

2026-09-24 21:52:06 -03:00

4.7 KiB

Raw Permalink Blame History

name, description, license, metadata

name

description

license

metadata

wf-readme

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).

MIT

dev-workflows

uses

external

readme-crafter

good-readme

curating-readme

avoid-ai-writing

Workflow README

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.

Escala pelo tamanho do pedido

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 (se instaladas)

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.

Sem elas, o fluxo abaixo funciona sozinho.

Fase 1: SCAN (fatos reais)

Leia o manifest (package.json, pyproject.toml, go.mod, Cargo.toml...): nome, descrição, versão, scripts, bin, dependências.
Ache os entrypoints e o que o projeto de fato faz (CLI, rotas, exports públicos).
Leia o README atual, LICENSE, CONTRIBUTING.md, a CI (.github/workflows/) e .env.example.
Capture o contexto: git remote -v e git log --oneline -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 (tipo e público)

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.

Fase 3: AUDIT (se já existe README)

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.

Sem README, siga direto para a Fase 4.

Fase 4: GENERATE

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.
Badge só do que existe: licença com LICENSE, build com CI configurada, versão com pacote publicado.
Todo comando e exemplo mostrado precisa rodar neste repo.
Uma língua por arquivo; tradução vai em arquivo separado (README.pt-BR.md).
Passe avoid-ai-writing no texto, se instalada.

Fase 5: VERIFY (antes de entregar)

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.
Links locais resolvem: cada ](caminho) aponta para arquivo que existe.
Links externos respondem: curl -sI -o /dev/null -w '%{http_code}' <url> em cada um.
Referências existem: arquivos, scripts, env vars e flags citados estão no repo.
Índice bate com os headings, se houver índice.
Nenhum TODO: sobrou no texto final.

Comandos prontos: references/verificacao.md.

Relatório

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.

Não faça

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.

Critério de aceite

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.

4.7 KiB Raw Permalink Blame History