JawsomeJason/jawsome-agents

Padrões

Os revisores aplicam as mesmas convenções manualmente, comentário após comentário. Este skill extrai esses comentários para criar padrões escritos e, em seguida, verifica diffs contra eles. Cada padrão combina uma regra que um agente segue ao escrever código com uma lente que um revisor aplica a um diff. Cada § numerado cita os comentários de revisão por trás dele, para que qualquer um possa rastrear uma regra até os revisores que a impuseram.

Princípios fundamentais

• Evidência primeiro. Um § precisa de comentários de revisão de pelo menos 3 alterações distintas e 2 revisores distintos, porque muitos comentários sobre uma única alteração, ou de uma única pessoa, representam o gosto de um único revisor.
• Toda regra carrega seu porquê. Uma razão continua a guiar um agente mesmo depois que o código ao redor da regra muda de forma.
• Um lar por convenção. Duas cópias divergem, e um agente segue aquela que leu primeiro.
• Uma verificação supera um §. Uma convenção que um linter, tipo ou teste pode capturar pertence àquela ferramenta, porque uma verificação é executada toda vez.
• Delete o que os agentes já fazem. Uma regra seguida sem incentivo custa contexto em cada carregamento e não muda nada.
• Scripts são atalhos. Cada arquivo de saída tem um esquema em references/schemas/, então, quando um script está ausente ou falha, escreva o mesmo arquivo manualmente.
• git é a única dependência rígida. Uma CLI de forja, como gh ou glab, adiciona comentários de revisão, e git log supre a falta de uma.

Comandos

Comando	O que faz	Saída	Referência
mine	Extrai comentários de revisão, rotula cada um por convenção, classifica os clusters por frequência vezes severidade	.standards/clusters.json	references/mine.md
write	Transforma clusters classificados em um skill de padrões no repositório, cada § com seu porquê e evidência	o skill de padrões	references/write.md
review	Aplica cada lente que um diff aciona e relata descobertas com o § citado	descobertas na resposta	references/review.md
prune	Testa A/B cada regra em cenários e deleta as que agentes seguem sem incentivo	prune.json	references/prune.md
doctor	Sinaliza deriva: globs que não correspondem a nada, arquivos citados que sumiram, lentes que nunca disparam, dados de poda desatualizados	.standards/doctor.json	references/doctor.md

Roteamento

Invoque como standards [comando] [escopo]. Um escopo é um caminho ou glob, um slug de área do índice gerado, ou um número de § (§2, §2.3). Resolva-o conforme references/scope.md. mine aceita apenas um caminho, porque áreas existem somente após write.

• Nenhum argumento. Mostre o menu abaixo e aguarde uma escolha. Nunca execute um comando automaticamente, porque cada um lê histórico, edita o repositório ou gasta muitas execuções do agente.
• Um escopo sem comando. Execute review desse escopo sem perguntar, porque review apenas lê.
• Um comando explícito ou claramente implícito. Carregue sua referência e siga-a passo a passo.
• Dois comandos se encaixam. Pergunte uma vez qual, nomeando ambos e o que cada um faria. Depois siga a resposta.
• Padrões a partir do zero. Comece com mine, porque write precisa de clusters.json. Ofereça write quando mine terminar.
• Uma pergunta sobre o próprio skill. Responda a partir deste arquivo sem executar um comando.

Menu

standards: o que devo fazer?
  mine    Extrair comentários de revisão em convenções classificadas
  write   Escrever padrões a partir das convenções classificadas
  review  Revisar um diff contra os padrões
  prune   Testar cada regra e deletar as que agentes já seguem
  doctor  Verificar a saúde dos padrões
Cada comando aceita um escopo opcional: um caminho, uma área ou um §.

Quando padrões gerados existirem, liste suas áreas abaixo do menu como número de § e slug.

Pipeline

mine alimenta write, e write produz o que review aplica. prune e doctor mantêm os padrões depois disso.

Arquivos de trabalho ficam em .standards/ na raiz do repositório alvo. Mantenha essa pasta fora do controle de versão, porque comentários de revisão citam código e pessoas. prune.json é a exceção. Ele fica ao lado dos padrões gerados, porque doctor o lê lá.

<skill-dir> nas referências é a pasta que contém este arquivo. Os scripts em <skill-dir>/scripts/ aceleram mine e precisam apenas da biblioteca padrão de um runtime JavaScript.

Modelo de julgamento

mine, prune e doctor fazem muitas perguntas pequenas e tipadas. Um modelo de julgamento é um modelo rápido que responde perguntas tipadas (escolha um de um conjunto, probabilidade sim/não, uma pontuação) com probabilidades calibradas. Se seu ambiente fornecer um modelo de julgamento, responda o arquivo de perguntas com ele; caso contrário, responda você mesmo. As instruções do seu próprio ambiente decidem qual modelo é esse.

Padrões gerados

• A saída padrão é um skill com um índice de frases resumidas, cada uma linkando para um arquivo §. Modelos: index e section.
• Um skill por área é uma opção, decidida por repositório através do experimento de forma em references/write.md.
• Padrões gerados seguem as mesmas regras deste skill: apenas frontmatter de especificação, sem URLs, sem datas, e um porquê para cada regra.