aigengame/skills

Estado

Mantenha STATE.md na raiz do repositório: um relatório diário leve entre sessões para que o próximo trabalhador aprenda em ~15 linhas onde o projeto está, o que a última sessão fez, qual experiência imediata reutilizar, o que pegar a seguir e quais itens inacabados não devem ser esquecidos. Este é o ciclo de feedback que faz com que a experiência de desenvolvimento se acumule em vez de redescobrir o status do projeto a cada sessão.

STATE.md é transiente ("onde estamos agora / o que vem a seguir", sobrescrito a cada sessão) e autocontido — não é o lugar para decisões duráveis, arquitetura ou glossário, e não deve duplicá-los. É criado preguiçosamente: se ainda não existir, a primeira execução o cria.

Onde o projeto mantém uma autoridade de planejamento (um issue tracker, milestones), essa autoridade define o que é o trabalho; ela não prescreve a ordem e a maneira da execução — as issues são executadas em paralelo, uma issue abrange várias sessões, trabalho inserido antecede trabalho planejado. STATE.md é o relatório do trabalhador sobre a execução: resultados, mais a orquestração atual do trabalho rastreado (o que iniciar a seguir, o que foi interrompido e estacionado). Ele registra o estado da execução; nunca se torna uma segunda autoridade de planejamento.

Esta skill é autossuficiente e ortogonal a qualquer outra coisa que o projeto eventualmente use (controle de versão, issue/task tracker, documentos de design). Assume que tais ferramentas podem existir, mas não depende de nenhuma em particular — leia quaisquer fontes que o projeto tenha, pule o resto.

Escreva com moderação — omita em vez de enganar. Cada bullet de conteúdo no template é opcional. A data de atualização é obrigatória sempre que o arquivo for reescrito. Escreva uma linha de conteúdo apenas quando ela for precisa e útil para a próxima sessão. Se um valor estiver ausente, desatualizado, não verificado ou não claramente útil, deixe-o de fora. Uma linha errada ou de preenchimento é pior do que uma ausente. O Backlog usa uma regra de remoção diferente; siga o passo 4.

Quando executar

• Ao final de uma sessão de trabalho / encerramento — seu runtime de agente pode sugerir isso via um hook de fim de sessão, ou você mesmo executa.
• Sob demanda, invoque a skill state usando a sintaxe explícita de skill do host.

O trabalhador principal atualiza o STATE.md uma vez por sessão. Subtarefas paralelas e subagentes não o atualizam. Esta regra previne escritas concorrentes ou duplicadas.

Guarda de no-op: se a sessão não realizou trabalho material (ex.: uma rodada trivial de perguntas e respostas), deixe STATE.md inalterado — no máximo atualize a data. Não gere ruído no arquivo com não- progresso.

Fluxo de trabalho

1. Reúna o que esta sessão realmente concluiu ou alterou. A fonte primária é a conversa atual. Se o projeto tiver ferramentas de suporte, corrobore levemente (histórico recente de controle de versão, o issue/task tracker) — trate-as como opcionais, não obrigatórias.
2. Declare a macro-fase apenas se você souber a atual. Não carregue a fase do STATE.md anterior por padrão — se ela pode ter avançado, ou você não pode confirmar o estágio atual nesta sessão, omita a linha em vez de afirmar uma desatualizada. (Uma fase concluída escrita como se fosse atual é desorientadora.) Use os próprios termos do projeto.
3. Escolha o próximo trabalho recomendado — os itens abertos com os quais uma nova sessão deve começar, em ordem de execução. Promova itens do Backlog para cá quando eles forem o próximo início correto.
4. Reconcilie o Backlog. Aplique este algoritmo a itens inacabados entre sessões:
   • Herde por filtragem. Comece com o Backlog anterior e quaisquer itens "Próximos" que não foram executados. Remova um item apenas quando evidências mostrarem que ele está concluído, obsoleto, selecionado para "Próximos" ou registrado no tracker do projeto. Uma referência no tracker é evidência de que o item tem um novo lar. Verifique a conversa e corrobore com o tracker quando existir um. Mantenha o item quando seu status for incerto.
   • Rebaixe trabalho inacabado. Mova trabalho deslocado para o Backlog apenas quando não estiver selecionado para "Próximos". Trabalho que deve ser retomado na próxima sessão pertence a "Próximos".
   • Estacione trabalho adiado. Adicione um item recém-aceito quando ele for adiado além da próxima sessão e não tiver outro lar.
   • Dê a cada item um único lar. Coloque-o em "Próximos" ou no Backlog, nunca em ambos.
   • Carimbe cada item do Backlog. Registre sua data de entrada como desde AAAA-MM-DD.
   • Aplique o orçamento de cinco itens. Quando o Backlog exceder cinco itens, ou um item for claramente substancial, mova os itens para o tracker do projeto, começando pelos mais antigos. Remova um item apenas após o tracker fornecer uma referência. Se não existir tracker, mantenha todos os itens. Também mantenha todos os itens quando não houver um escritor autorizado para criar o registro no tracker. O excesso visível é o sinal de que os itens ainda precisam de um lar durável.
5. Adicione experiência apenas se ela servir ao "Próximos". Inclua uma nota apenas quando o trabalho desta sessão for contínuo ou relacionado ao trabalho recomendado a seguir, para que a nota seja realmente reutilizada. Se o próximo trabalho não for relacionado, omita — experiência que não ajuda a próxima tarefa é ruído, não um arquivo de histórias de guerra. Quando o projeto tiver um PITFALLS.md, mantenha orientações duráveis sobre ambiente, ferramenta, permissão, sandbox e invocação de ferramentas lá. STATE.md pode apontar para uma entrada relevante; não deve copiar essa entrada.
6. Reescreva STATE.md a partir do template. Sobrescreva o arquivo; nunca anexe. Mantenha-o com 15 linhas ou menos. Se a regra de não-perda no passo 4 deixar mais de cinco itens no Backlog, permita uma linha extra para cada item extra. Não remova um item para cumprir o limite de linhas. Omita bullets de conteúdo que não forem precisos e úteis. Re-emita o Backlog filtrado como parte do novo snapshot. Carimbe a data atualizada.
7. Não faça auto-commit. Apenas deixe o STATE.md reescrito na árvore de trabalho. Se ele é rastreado ou mantido apenas como auxílio de trabalho local é escolha do projeto — esta skill nunca o comita.

Template

# STATE — <projeto>

_Relatório diário entre sessões (~15 linhas, reescrito a cada sessão via a skill `state`). Decisões duráveis vivem em outro lugar, não aqui._

- **Fase/milestone:** <estágio atual, nos próprios termos do projeto — omita se não puder confirmar o *atual*>
- **Última sessão:** <o que foi concluído/alterado; uma linha, ex.: issue #N>
- **Experiência:** <experiência transitória que ajuda "Próximos", ou um link para uma entrada relevante de `PITFALLS.md`; caso contrário, omita>
- **Próximos:** <itens recomendados para INICIAR a seguir, em ordem de execução, ex.: issue #N>
- **Backlog:** <itens inacabados entre sessões NÃO selecionados para "Próximos"; uma linha por item>
  - <item interrompido ou estacionado, ancorado a uma referência do tracker (#N) quando existir> _(desde AAAA-MM-DD)_
  - <item ainda não no tracker — promova-o para lá, começando pelos mais antigos, quando a lista transbordar> _(desde AAAA-MM-DD)_

_Atualizado: <AAAA-MM-DD>_

(Todo bullet de conteúdo é opcional. _Atualizado é obrigatório sempre que o arquivo for reescrito.)

Guardrails

• Siga o passo 4 para cada alteração no Backlog. Nunca delete trabalho inacabado para cumprir um orçamento.
• Siga o passo 6 para reescrita e limites de linhas. STATE.md é um snapshot atual, não um histórico.
• Registre apenas o delta desta sessão. O Backlog é o único campo que carrega estado filtrado para frente.
• Mantenha o arquivo autocontido. Não duplique decisões duráveis nem dependa de um tracker ou ferramenta específicos.
• Use o vocabulário estabelecido do projeto.