A equipe pode pedir para a LLM publicar notas de versao diretamente na Wiki.js usando pedidos simples em linguagem natural, como "subir wiki", "gerar nota de versao" ou "publicar wiki".
Ou seja... Não precisaremos mais ficar editando as notas de versão manualmente na https://wiki.portalsoftcase.com.br/e/pt-br/Desktop/Notas-Atualizacao
Quando esse pedido e feito, a LLM le o commit mais recente e usa o bloco Wiki-* padronizado para montar a nota. Depois confirma o resumo com quem pediu e publica na Wiki.js usando o publicador oficial do repositorio. O contexto do projeto, como OpenSpec, docs ou diff, fica apenas como fallback quando o commit nao estiver no padrao.
Antes desse fluxo, as notas de versao precisavam ser atualizadas manualmente na Wiki.js. Isso funcionava, mas trazia alguns problemas no dia a dia:
Com a publicacao pela LLM, a equipe ganha um fluxo mais rapido e padronizado. A LLM confere OpenSpec e Git, monta uma nota simples, pede confirmacao e publica usando o script oficial. Isso reduz esquecimento, melhora a consistencia das notas e facilita manter a Wiki.js atualizada.
Para deixar a publicacao ainda mais rapida, o commit deve trazer um bloco padronizado com o resumo da nota de versao. Assim, quando alguem pedir subir wiki, a LLM consegue ler a mensagem do commit e saber exatamente o que publicar, sem precisar analisar o diff.
[!IMPORTANT]
Ao terminar uma tarefa, peca para a LLM gerar a mensagem do commit antes de commitar.Esse passo garante que as informacoes da nota de versao fiquem claras no proprio commit e possam ser reaproveitadas depois no
subir wiki.
Esse fluxo nao depende de OpenSpec ou Gill me (criação de especificações). O que alimenta a publicacao e o proprio commit padronizado: a LLM gera a mensagem do commit, o programador cola essa mensagem no commit, e depois a LLM le esse commit para publicar a nota na Wiki.js.
OpenSpec, docs internas ou outros materiais de contexto sao opcionais. Eles ajudam a LLM a escrever uma mensagem de commit melhor, mas nao sao obrigatorios para publicar.
Quando o programador pedir para a LLM criar o commit, ela deve entregar apenas o texto da mensagem para copiar e colar. Ela nao deve executar git commit nem git push, a menos que isso seja pedido explicitamente.
Formato recomendado:
<tipo>(<escopo>): <resumo tecnico curto>
Wiki: sim
Wiki-Versao: <versao ou pendente>
Wiki-Tipo: <Melhorias|Correcoes>
Wiki-Titulo: <titulo curto para cliente>
Wiki-Descricao: <descricao simples para cliente final>
Exemplo:
fix(autoatendimento): ajustar validacao de ticket no ATM
Wiki: sim
Wiki-Versao: 3.5.5.171
Wiki-Tipo: Correcoes
Wiki-Titulo: Validacao no autoatendimento
Wiki-Descricao: Corrigida a validacao de tickets no autoatendimento para deixar a operacao mais confiavel.
Quando o commit nao deve gerar nota de versao, use:
chore(build): atualizar arquivos gerados
Wiki: nao
Exemplos:
me de a mensagem do commit
agora me de o commit
me mostre o commit
me de o commit da wiki
A LLM deve retornar um bloco de texto pronto para o programador copiar e colar no commit.
Antes da primeira publicacao em uma maquina nova, e necessario configurar o token da Wiki.js na variavel de ambiente WIKIJS_TOKEN.
Abra o PowerShell e rode:
setx WIKIJS_TOKEN "SEU_TOKEN_AQUI"
Depois de rodar o comando, feche e abra novamente o PowerShell, o terminal ou a IDE. O setx grava a variavel para novas sessoes; a janela atual pode continuar sem enxergar o token.
Para conferir se a variavel ficou disponivel, rode em uma nova janela:
$env:WIKIJS_TOKEN
Se aparecer o token, a maquina esta pronta para publicar. Nao publique o token em commits, chats, prints ou documentos.
Quando o token nao esta configurado, o publicador para a execucao e mostra a mensagem pedindo para configurar WIKIJS_TOKEN.
Use esse fluxo sempre que uma alteracao ja estiver pronta e precisar aparecer na pagina de notas de versao da Wiki.js.
Exemplos:
O jeito mais rapido e pedir:
subir wiki
ou:
gerar nota de versao
Nesse modo, a LLM vai:
git log -1 --format=%B.Wiki: sim completo, usar esse bloco como fonte principal.git diff quando o commit estiver no padrao.Melhorias ou Correcoes.Antes de publicar, a LLM deve apresentar algo nesse formato:
Versao: 3.5.5.171
Tipo: Melhorias
Titulo: Validacao no autoatendimento
Descricao: Melhorada a consulta de tickets no autoatendimento, permitindo mais controle sobre a validacao e a troca de tabela durante a operacao.
Se estiver tudo certo, responda:
sim
Se quiser mudar alguma coisa, responda com o ajuste:
troque o titulo para "Consulta de tickets no autoatendimento"
ou:
publique como Correcoes, nao Melhorias
Voce pode informar a versao diretamente no pedido:
subir wiki na versao 3.5.5.171
Tambem e possivel publicar em uma versao anterior, quando a nota pertence a uma entrega antiga ou quando a wiki precisa ser complementada:
publique essa nota na versao 3.5.5.166, mesmo sendo uma versao anterior
ou:
gerar nota de versao para 3.5.5.166
Quando a versao e informada, a LLM deve respeitar essa versao em vez de tentar usar a mais recente.
Da para personalizar praticamente tudo no pedido.
Use Melhorias quando a alteracao adiciona, melhora, facilita ou otimiza algo:
subir wiki como Melhorias
Use Correcoes quando a alteracao corrige erro, calculo, falha ou comportamento incorreto:
subir wiki como Correcoes
Voce pode definir o titulo:
subir wiki na versao 3.5.5.171 com o titulo "Consulta de tickets no autoatendimento"
Voce pode definir a descricao:
subir wiki na versao 3.5.5.171 com a descricao "Melhorada a validacao de tickets no autoatendimento para deixar a operacao mais controlada."
Exemplo com tudo definido:
publique na wiki:
versao 3.5.5.171
tipo Melhorias
titulo Validacao no autoatendimento
descricao Melhorada a consulta de tickets no autoatendimento, permitindo mais controle sobre a validacao e a troca de tabela durante a operacao.
Por padrao, a nota deve ser curta e simples para cliente final. Isso significa evitar nomes tecnicos, como nomes de arquivos, tabelas, procedures, commits ou branches.
Bom exemplo:
Melhorada a consulta de tickets no autoatendimento, permitindo mais controle durante a operacao.
Evite publicar assim para cliente final:
Alterada a procedure PROC_AUTOATENDIMENTO_CONSULTA_TICKET_SOFTPARK com novo parametro @MODO_TROCA_TABELA_VALIDACAO.
Se a equipe quiser uma nota tecnica, pode pedir explicitamente:
gere uma nota tecnica mencionando a procedure alterada
Nao e obrigatorio usar OpenSpec ou a skill do Grill me para esse fluxo funcionar. A publicacao pode ser feita apenas com o commit padronizado.
Mesmo assim, vale usar algum material de contexto quando a mudanca tem regra de negocio, comportamento novo ou impacto em operacao. Esse contexto ajuda a LLM a entender o motivo da alteracao, os cenarios atendidos e o vocabulario correto do produto. Isso evita commits genericos demais e reduz o risco de publicar uma descricao que nao representa bem a entrega.
Opcoes de contexto:
docs/.SKILL.md grill-with-docs.Sempre que houver uma spec ou change relacionada, mencione isso no pedido:
subir wiki usando o contexto do OpenSpec ou do Grill da mudanca de fechamento automatico de caixa
ou:
gere a nota com base na spec de ocr-lpr-automacao
Tambem vale pedir para a LLM conferir o OpenSpec antes de escrever:
antes de publicar, leia o OpenSpec relacionado e gere uma nota simples para cliente final
Quando nao houver uma spec clara, a LLM ainda pode usar o Git como fonte principal, mas o ideal e manter specs e changes atualizadas para funcionalidades importantes.
Importante: esse contexto opcional serve para gerar melhor o commit. Depois que o commit ja esta padronizado, o subir wiki deve ler o bloco Wiki-* do commit como fonte principal.
subir wiki
subir wiki na versao 3.5.5.171
publique na versao 3.5.5.166, mesmo sendo uma versao anterior
subir wiki como Correcoes
publique na wiki a versao 3.5.5.171 como Melhorias.
Titulo: Validacao no autoatendimento.
Descricao: Melhorada a consulta de tickets no autoatendimento para permitir mais controle durante a validacao.
gere 3 opcoes de nota para a wiki antes de publicar
deixe a descricao mais simples para cliente final e depois publique
subir wiki usando o OpenSpec da funcionalidade alterada
ja configurei o WIKIJS_TOKEN no PowerShell, pode subir wiki na versao 3.5.5.171
me de o commit da wiki
Antes de publicar, a LLM deve sempre conferir:
git log -1 --format=%B.Wiki: sim completo, usar esse conteudo e nao analisar git diff.Softpark_2.5/openspec/specs/ e Softpark_2.5/openspec/changes/.git status.git diff.git log --oneline -10.Se o commit estiver padronizado, ele e a fonte principal. Se nao estiver, a LLM usa o melhor contexto disponivel como fallback. OpenSpec e util, mas nao e obrigatorio.
A publicacao e feita pelo script:
.\Softpark_2.5\openspec\tools\subir-wiki.bat -Versao "<versao>" -Tipo "<Melhorias|Correcoes>" -Titulo "<titulo>" -Descricao "<descricao>"
Normalmente a equipe nao precisa chamar esse comando manualmente. Basta pedir para a LLM publicar.
O script usa o token configurado em WIKIJS_TOKEN. Se a variavel nao existir na sessao atual, configure com setx WIKIJS_TOKEN "SEU_TOKEN_AQUI" e abra uma nova janela antes de tentar novamente.
Wiki-* quando a alteracao precisar virar nota de versao.Antes de responder sim para publicar, confira:
Melhorias ou Correcoes?Depois da confirmacao, a LLM publica a nota e informa se a Wiki.js foi atualizada com sucesso.