0x0w1/jig

README

Use esta habilidade para criar ou atualizar o arquivo README.md do repositório a partir do estado atual do repositório.

Procedimento

1. Escaneie o repositório:
   • Arquivos de manifesto e construção: pyproject.toml, package.json, Cargo.toml, go.mod, Makefile, arquivos de bloqueio.
   • Pontos de entrada, definições de argumentos de CLI, scripts e configurações de serviço (Dockerfile, docker-compose*.yml).
   • Documentação existente em docs/ e exemplos de uso no código.
2. Classifique o tipo de projeto: Ferramenta CLI, Biblioteca, Serviço/aplicativo ou Outro. O tipo seleciona o layout de seções abaixo quando nenhum perfil está definido.
3. Resolva o perfil do README de acordo com o Contrato de Perfil abaixo. Um perfil que resolve substitui os padrões genéricos para este repositório; quando nenhum resolve, proponha um e continue de qualquer maneira.
4. Ramifique com base no estado atual:
   • Sem README.md → caminho de criação: elabore o README com o layout de seções abaixo.
   • README.md existe → caminho de atualização: verifique cada afirmação verificável no README — comandos, opções, caminhos de arquivos, links, declarações de funcionalidades — contra o repositório. Colete as incompatibilidades em uma lista de desvios, relate a lista e aplique as correções. Deixe as seções que ainda estão precisas intactas.
5. Aplique as regras de precisão a cada linha escrita.
6. Execute a passagem de compressão das Regras de Compressão abaixo:
   • Caminho de criação: aplique-a durante a elaboração. Nada foi publicado ainda, então não há nada a propor.
   • Caminho de atualização: colete a duplicação e o exagero em uma proposta — nomeie cada fato, onde ele é repetido e qual documento de detalhes o conteria — então pergunte antes de mover qualquer coisa. Relate a proposta mesmo que o usuário a recuse.
7. Mescle a alteração:
   • Quando o repositório tem a habilidade develop-task-flow (ou a jig-develop-task-flow instalada), siga-a: um branch chore/<slug>, um merge squash com um commit docs:, depois faça push para develop.
   • Caso contrário, proponha um commit normal no branch atual.

Contrato de Perfil

Dois repositórios que são do mesmo tipo de projeto ainda escrevem seus READMEs de forma diferente: um mantém um espelho traduzido, outro move a instalação para um guia, um terceiro tem uma convenção de tabela que seus contribuidores já seguem. Essas são decisões, não fatos que podem ser escaneados no repositório, então são registradas uma vez e lidas em todas as execuções posteriores.

Resolva o perfil nesta ordem:

1. Variável de ambiente JIG_README_PROFILE.
2. git config --local --get jig.readmeProfile.
3. .jig/readme.md.

Quando um perfil resolve, ele substitui o Layout de Seções e as Regras de Idioma abaixo para aquele repositório; qualquer coisa que ele não mencione volta a usar esses padrões. Leia-o, siga-o e nomeie-o no relatório.

Quando nenhum resolve, elabore um a partir da varredura e proponha-o: o tipo classificado, o idioma que o repositório já usa para escrever, se existe um espelho, a ordem de seções que o README atual implica e quais documentos de detalhes já contêm o excesso. Escreva .jig/readme.md somente após o usuário aceitá-lo. Se o usuário recusar ou não responder, continue com os padrões genéricos e diga isso — um perfil ausente é um estado normal, não um bloqueio.

O arquivo registra apenas decisões. Ele não carrega limites nem lista de verificação; a qualidade do README continua sendo um julgamento que esta habilidade faz com o repositório à sua frente.

# Perfil do README

> Base: <como isso foi decidido>, <AAAA-MM-DD>

## Idiomas

Canônico: `README.md` (Inglês). Espelho: `README.ko.md` (Coreano), atualizado na mesma tarefa.

## Seções

Título e linha de links, O Que Isto É, Início Rápido, Habilidades, Documentação, Licença.

## Documentos de Detalhes

Opções de instalação → `docs/installation.md`. Roadmap e registros de design → `docs/roadmap.md`, linkados a partir da página inicial da documentação apenas.

## Convenções

Tabelas de identificadores mantêm células de descrição em uma cláusula. Comandos de contribuidores permanecem em um bloco `<details>`.

Os títulos das seções são o contrato; o texto abaixo deles é do próprio repositório. Um perfil escrito antes desses títulos existirem ainda é lido corretamente se os usar.

Layout de Seções

Seções obrigatórias, nesta ordem:

1. Título mais uma descrição de uma linha.
2. Introdução: o que o projeto faz e por que existe.
3. Instalação.
4. Uso.

Adições por tipo de projeto:

• Ferramenta CLI: uma tabela de comandos e opções.
• Biblioteca: um resumo da API com código de exemplo.
• Serviço/aplicativo: como executá-lo (dev e produção) e as variáveis de ambiente necessárias.

Opcional: links de documentação, licença.

Regras de Layout

• Uma tabela é adequada para identificadores que as pessoas copiam — nomes de habilidades, comandos, opções, caminhos. O que quebra tal nome é a proporção de largura entre colunas: o GitHub dimensiona as colunas pelo conteúdo, então uma coluna de descrição várias vezes maior que a coluna de identificador comprime o identificador até que ele quebre no meio do nome, e o leitor vê um nome que não existe.
• Mantenha as células de descrição aproximadamente tão curtas quanto os identificadores, cerca de uma cláusula. Quando as descrições ficam longas, ou as encurte ou mova tudo para uma lista: - **\nome`** — descrição`.
• Quebras de linha dentro de uma descrição são esperadas e não precisam de trabalho.

Regras de Compressão

Um README é lido antes de o leitor decidir usar o projeto. Tudo nele compete por essa atenção, então comprimento é um sintoma: um README longo é quase sempre um fato escrito em vários lugares, não um projeto com muito a dizer.

Mova, não exclua. Quando o mesmo fato aparece em mais de um lugar, mantenha-o no lugar onde um leitor chega primeiro e mova o restante para o documento de detalhes que já o cobre, criando esse documento apenas se nenhum existir. Nada é perdido; o README para de se repetir. Não há contagem de linhas a atingir — um README de biblioteca com os exemplos de API que realmente precisa não é muito longo, e um README curto que diz a mesma coisa duas vezes ainda está errado.

Lidere com o que o leitor ganha. A introdução diz o que se torna mais fácil, não quais funcionalidades existem. grava um trailer de lançamento classificado no merge é uma funcionalidade; você para de reconstruir por que uma versão foi um patch é o que o leitor ganha. Ordene as afirmações pela força da evidência, da mais forte para a mais fraca, e faça com que qualquer prosa ao redor as liste nessa mesma ordem — um parágrafo e seus marcadores não devem implicar prioridades diferentes.

Afirme apenas o que o repositório pode comprovar, e diga quando se aplica. Uma afirmação que o repositório não pode demonstrar é deixada de fora, não suavizada. Declare a condição sob a qual o valor aparece, para que um leitor fora dessa condição possa descartar o projeto rapidamente, em vez de descobri-lo mais tarde.

Corte o que não é lido antes de instalar. Roadmaps, registros de design e notas de direção são coisas que o projeto mantém para si. Linke-os a partir da página inicial da documentação, não do README.

Dobre o material do contribuidor. Comandos de construção, regeneração e validação atendem a pessoas que já clonaram o repositório. Coloque-os em um bloco <details> ou em um documento de contribuição.

Mescle blocos que diferem por um valor. Blocos de comando separados por plataforma ou alvo que variam apenas em um argumento se tornam um bloco com esse argumento nomeado.

Dê ao leitor uma maneira de passar do topo. Quando o README tem mais de cerca de quatro seções, coloque uma linha de links de uma linha sob o título para que um leitor que retorna pule diretamente para a seção que veio buscar.

Regras de Precisão

• Escreva apenas comandos de instalação e execução verificados contra o repositório: um script, manifesto ou arquivo de bloqueio deve mostrá-los.
• Verifique se cada caminho de arquivo vinculado existe.
• Não descreva funcionalidades, selos ou integrações que o repositório não contém.
• Quando uma afirmação não puder ser verificada, deixe-a de fora e relate-a.

Regras de Segurança

• .jig/readme.md é escrito apenas após o usuário aceitar a proposta, e nunca como efeito colateral de uma atualização comum de README.
• Um .jig/readme.md existente nunca é sobrescrito sem confirmação explícita. Proponha a alteração e nomeie o que ela substitui.
• Nada mais em .jig/ é tocado. version-rubric é dona de .jig/versioning.md.
• Um README publicado nunca é reestruturado silenciosamente; a passagem de compressão propõe e espera.
• Alterações não relacionadas do usuário são preservadas.

Regras de Idioma

• Um README existente mantém seu idioma.
• Um novo README é escrito no idioma que o repositório já usa para seus documentos, padrão Inglês, com termos técnicos em crases.
• Uma solicitação explícita de idioma do usuário substitui ambos.

Relatório

• Tipo de projeto e o caminho tomado (criação ou atualização).
• Perfil do README: caminho e fonte, ou proposto e recusado, ou nenhum e executando nos padrões genéricos.
• No caminho de atualização: a lista de desvios e o que foi corrigido.
• A proposta de compressão: cada fato repetido em mais de um lugar, para onde ele seria movido e se o usuário aceitou.
• Afirmações que não puderam ser verificadas e foram deixadas de fora.