wiki-smith

wiki-smith — mantenha o .wiki/ do repositório

Uma wiki é a memória do repositório, escrita para agentes: eles encontram a regra aqui em vez de perguntar de novo. O diário guarda o que aconteceu; a página de tópico guarda o que vale agora. Uma lição que vive apenas no diário está perdida. O wiki-smith decide qual dos dois uma sessão precisa, escreve do jeito que as regras da própria wiki determinam e verifica.

Método completo (tipos de arquivo, formato da nota, ingestão, links, datas, commit): references/method.md. Chaves de configuração: references/config.md. Créditos: ATTRIBUTION.md. Mudanças: CHANGELOG.md. Sua própria memória: .wiki/.

<skill> abaixo é a pasta desta skill (por exemplo ~/.claude/skills/wiki-smith). Todo script aceita -w <wiki dir> (padrão ./.wiki) e -c <config> (padrão <wiki>/wiki.config).

Etapa 0 — Encontre a wiki e suas regras

1. A wiki é .wiki/ na raiz do repositório. Se não houver, informe e ofereça-se para criar uma a partir de templates/ (wiki.config.example primeiro); nunca crie sem ser solicitado.
2. Leia .wiki/wiki.config se presente (nomes: pasta do diário, caixa de entrada, índice, rótulo do rodapé, chaves de data, branch principal). Sem ele, os padrões são em português genérico: journal/, inbox.md, index.md, Mapa:, ## Histórico, created/updated.
3. As regras da própria wiki vencem. Se o repositório tem uma página sobre como mantê-la (rg -n -i 'manter|maint' .wiki -l) ou uma regra em AGENTS.md sobre a wiki, leia essa seção e siga-a onde divergir desta skill.
4. Se o usuário pediu "wiki update" e a wiki (geralmente o índice) diz para confirmar primeiro, faça a Etapa 1 e a Etapa 2 apenas como plano: uma linha por página com o que muda, os títulos das novas notas, então pergunte "Aplicar?" e edite só após o sim. Caso contrário, aja.

Etapa 1 — Veja o que aconteceu, depois direcione

Leia a sessão (e git diff, git log para o trabalho feito). Escolha cada linha que se aplica, e nada mais:

O que a sessão teve	O que fazer
Uma decisão, entrega, mudança de rumo, incidente ou pesquisa	Uma nota diária: scripts/note.sh -b "Título que diz o que mudou" com o parágrafo canalizado. Em seguida, a linha do dia na caixa de entrada.
Uma regra, lição ou fato que vale além de hoje	Também corrija a página de tópico: a regra como vale agora, sem histórico (o histórico fica na nota e na seção de Histórico da página). Corrija o que a página dizia antes; nunca acumule "costumava ser".
Um novo assunto com várias facetas (voltará, e uma página misturaria tipos)	Um mapa de conteúdo moc-<topic>.md mais páginas <topic>-<facet>.md (folha de dicas, instalação, integração, comparação com a ferramenta atual...). Veja "Novo assunto" abaixo.
Nada que valha registrar (apenas passos intermediários, ou o que um commit já diz)	Diga em uma linha e não crie nada. Encher o diário o torna ilegível.

Apenas uma nota nova é criada para o diário; nunca reescreva a nota de outro agente.

Etapa 2 — Escreva

Nota diária. scripts/note.sh "<título>" cria <DIARY_DIR>/<today>/<HHMM>-<slug>.md em UTC e mostra o caminho (regras de slug e -2 em colisão estão no script). Stdin é lido apenas com -b: shells de agente e CI deixam stdin aberto para sempre, então sem -b o script nunca espera. Canalize o corpo: printf '%s\n' "<parágrafo>" | scripts/note.sh -b "<título>"; -b coloca exatamente uma linha em branco entre o título e o corpo. Sem -b o arquivo tem apenas a linha do título; para adicionar o parágrafo depois, comece com uma linha em branco: printf '\n%s\n' "<parágrafo>" >> "$path". O corpo é um parágrafo bem escrito: o que aconteceu, por que importa, onde está a evidência (commit, PR, issue), com um link para a página de tópico. Links são relativos à pasta do dia (../../page.md). Template: templates/note.md.

Primeira nota do dia: scripts/day-index.sh cria o índice do dia; então adicione o dia no topo dos "últimos dias" na caixa de entrada. Se a nota muda como o repositório funciona, adicione também uma linha aos destaques da caixa de entrada. A caixa de entrada nunca contém uma nota.

Página de tópico (ingestão). Encontre-a (rg -n -i '<palavra>' .wiki); se não existir e o assunto retornar, crie-a (template: templates/page.md); se for pequena, coloque-a em uma seção de uma página próxima. Escreva a regra como vale agora. Se uma alteração muda o que a página afirma, adicione uma linha no topo de sua seção de Histórico. A nota linka para a página.

Novo assunto.

1. Escreva as páginas primeiro, uma faceta cada, cada uma auto-contida desde a primeira frase. Facetas típicas: folha de dicas (a primeira: endereços, comandos, atalhos), instalação, integração, comparação com a ferramenta em uso hoje.
2. Crie moc-<topic>.md (templates/moc.md): um parágrafo de abertura, "as páginas" (uma linha cada, folha de dicas primeiro), "o que saber primeiro" (as poucas regras que pegam).
3. Dê a cada página o rodapé (Mapa: [moc-<topic>](moc-<topic>.md) · Relacionado: ...), adicione o mapa e cada página ao índice, e linke o mapa de pelo menos um outro mapa.
4. Uma nota no diário diz o que foi criado e linka o mapa.

Etapa 3 — Fechamento (sempre, nesta ordem)

1. scripts/dates.sh — o frontmatter created/updated, a partir do git. Idempotente.
2. scripts/day-index.sh — regenera o índice do dia. Nunca edite manualmente.
3. python3 -I scripts/lint.py — corrija cada arquivo:linha: tipo: mensagem que ele imprimir até que saia com 0 (saída 2 significa problemas). Não envie um lint vermelho.
4. Commite apenas seus próprios arquivos, por caminho, nunca git add -A: scripts/sync.sh -m "wiki: <o que>" <caminho>.... Ele commita no lugar quando o checkout está em <main>, atual e sem mudanças fora de seus caminhos; caso contrário, ele leva seus caminhos para um git worktree fresco de origin/<main>. De qualquer forma, ele faz lint exatamente do que commita e recusa um lint vermelho (saída 1, checkout intocado, worktree de transporte removido). No transporte, o índice do dia gerado nunca é copiado: é regenerado no worktree, então lista apenas as notas que estão no commit. Adicione as linhas de atribuição que o repositório ou seu host exige à mensagem.
   • Arquivos compartilhados (índice, caixa de entrada) que outra sessão pode ter editado também: não os passe para um transporte. scripts/sync.sh -W imprime um worktree fresco de origin/<main>; faça suas edições lá (a wiki está no mesmo caminho relativo), execute dates.sh, day-index.sh, lint.py, então execute sync.sh -m ... [-p] <caminhos> de dentro desse worktree. Ele commita lá, e com -p faz rebase, push, fast-forward do checkout principal onde possível, e remove o worktree. Um transporte que envie linhas de outra sessão (por exemplo um link para uma página que está apenas no checkout) falha no lint e para antes de qualquer commit; essa falha é o sinal para usar -W.
5. Faça push apenas quando o usuário pedir para sincronizar: a mesma chamada com -p (fetch, rebase, push HEAD:<main>, fast-forward do checkout, remova o worktree). Nunca force, nunca toque em arquivos modificados de outras pessoas: um arquivo que difere do que você enviou e pode conter edições de outra sessão (índice, caixa de entrada) é deixado como está. Se o checkout não puder ser fast-forward ( <main> local divergiu, ou edições locais sobrepostas) ele informa e ainda sai com 0, porque o push funcionou. Abra um PR apenas quando solicitado.

Commite o que escreveu na mesma sessão sem esperar ser solicitado; publicar é decisão do usuário.

Consultando a wiki

rg -n -i '<palavra-chave>' .wiki (ou passe o olho no índice), então leia apenas a página ou seção correspondente, nunca a wiki inteira. Para o que aconteceu: a caixa de entrada (curta), depois apenas os dias que importam; um dia = seu índice e as notas que lista. Se o repositório tem especificações, elas dizem o que o sistema promete: rg -n -i '<palavra-chave>' <diretório de specs>.

Armadilhas

• O diário não é a página. Uma regra escrita apenas em uma nota está perdida; ingira-a na página de tópico na mesma sessão.
• Regras sem histórico. "Antes de criar um cartão, pesquise por existentes", não "costumávamos duplicar cartões". A história fica na nota.
• Uma nota por arquivo. Vários agentes escrevem no mesmo dia; eles nunca devem editar o mesmo arquivo. O índice do dia é gerado; conflitos lá são resolvidos executando day-index.sh novamente.
• Arquivos compartilhados entre sessões. O índice do dia, index.md e a caixa de entrada contêm todas as edições não commitadas de cada sessão em um checkout. sync.sh nunca transporta o índice do dia (regenera-o no worktree) e faz lint antes de commitar, mas não consegue dizer quais pedaços de um index.md ou caixa de entrada editados manualmente são seus: o transporte pega o diff inteiro. Quando outra sessão pode ter tocado neles, use sync.sh -W e edite no worktree. Uma linha estrangeira que por acaso não quebre o lint ainda é transportada; esse é o limite documentado do transporte.
• Nunca espere em stdin. note.sh lê o corpo apenas com -b; em um shell de agente, uma leitura direta bloqueia para sempre. O mesmo se aplica a qualquer script que você adicionar.
• Não registre o transitório: um comando que falhou uma vez e funcionou na repetição, uma falha de ambiente, uma tarefa única. Capture a correção funcional na página de tópico, nunca "X está quebrado" (isso se solidifica como recusa depois que a causa desaparece).
• Links: relativos, primeira menção por seção apenas; uma âncora é o slug do GitHub do título (minúsculo, sem pontuação, acentos mantidos, espaço vira hífen). Renomear um título quebra suas âncoras; o lint avisa. Coloque um exemplo de link entre crases para que o lint não o leia.
• Renomear ou deletar uma página: rg -l 'nome-antigo' .wiki e corrija cada link, âncoras incluídas; delete apenas depois que o conteúdo foi movido.
• Tamanho da página: acima de cerca de 150 linhas, ou quando regra, procedimento, referência e histórico se misturam, divida por tipo.
• Dados privados ficam de fora. Páginas da wiki são commitadas; mantenha segredos, tokens e dados pessoais fora, e referencie onde o segredo vive.
• Limites do lint: ele não pega contradições entre páginas ou afirmações desatualizadas; isso é revisão do agente quando o tempo permite.
• Limite do day-index.sh: um arquivo de dia com notas antigas escritas manualmente é um erro (arquivo:linha), não é migrado; mova cada nota para seu próprio arquivo com note.sh, execute novamente.

Etapa 4 — Mantenha sua própria wiki

Se esta execução ensinou algo sobre executar o wiki-smith (um erro de roteamento, uma peculiaridade de script), adicione uma linha a .wiki/lessons.md: - YYYY-MM-DD — <regra + por que>. Edite o clone fonte (biliboss/wiki-smith) e reinstale (npx skills add biliboss/wiki-smith -g --copy -a claude-code -y), não a cópia instalada, que uma reinstalação sobrescreve. Decisões de design vão em .wiki/design.md.