Zions-store/project-ledger

Copyright (C) 2026 ZionXiaoxiSuOGLocGo SPDX-License-Identifier: GPL-3.0-or-later

project-docs

Cria e mantém um sistema de três documentos de conhecimento do projeto. Suporta todos os tipos de projeto detectados pelo project-onboard — seleciona automaticamente o modelo correto com base no tipo do seu projeto.

Sistema de Três Documentos

Arquivo	Propósito	Frequência de Atualização
AGENTS.md	Visão geral do projeto: identidade, estrutura de diretórios, arquitetura de classes, pontos de entrada, dependências, Notas	Por milestone (~3-5 novos arquivos/classes)
PROJECT_STATE.md	Documento vivo: espectro completo de classes/código-fonte (com parâmetros), configuração, mapa de módulos, fluxos do sistema, lista de tarefas feitas/a fazer	Ao final de cada sessão
DEVLOG.md	Registro de desenvolvimento: entradas cronológicas — o que foi feito, por quê, o que foi aprendido	Por dia ou por milestone de recurso

Consulte maintenance-spec.md para regras detalhadas sobre gatilhos de atualização, limites de conteúdo e verificações de consistência.

Seleção de Modelo

Os modelos seguem o mesmo padrão de descoberta automática dos pacotes de regras do project-onboard. A skill tenta carregar templates/<tipo>/PROJECT_STATE.md.tmpl onde <tipo> é o valor do campo Type (em minúsculas) de Informações Básicas do AGENTS.md. Se nenhum modelo específico para o tipo existir, ela usa o modelo genérico templates/PROJECT_STATE.md.tmpl.

templates/<tipo>/PROJECT_STATE.md.tmpl existe? → use-o
                                             não → use templates/PROJECT_STATE.md.tmpl (fallback genérico)

Adicionar suporte a um novo motor ou framework: crie templates/<tipo>/PROJECT_STATE.md.tmpl. Nenhuma alteração de código é necessária — a skill o descobre automaticamente.

Todos os tipos compartilham templates/DEVLOG.md.tmpl (independente do tipo de projeto).

Mapeamento de Campos AGENTS.md → PROJECT_STATE.md

Ao pré-preencher o PROJECT_STATE.md a partir dos dados do AGENTS.md, use este mapeamento:

Seção do AGENTS.md	Campo do AGENTS.md	Seção do Modelo STATE	Placeholder do STATE
Informações Básicas	Type, Language, Framework/Engine, Key Dependencies	§1 Identidade do Projeto	{{PROJECT_TYPE}}, {{LANGUAGE}}, {{FRAMEWORK}}, {{KEY_DEPENDENCIES}}
Informações Básicas	Engine (para projetos de jogo)	§1 Identidade do Projeto	{{ENGINE_VERSION}}
Estrutura de Diretórios	Diretórios e descrições	§2 Estrutura de Diretórios	{{DIRECTORY_TREE}} (genérico) ou Source/{{MODULE_NAME}}/... (UE)
Arquitetura Principal	Arquivos/classes-chave e funções	§3 Espectro de Código-Fonte/Scripts	{{CLASS_NAME}}, {{RESPONSIBILITY}}, {{FILE_NAME}}
Dependências	Resumo de pacotes	§4 Configuração / §7 Dependências	{{CONFIG_KEY}}, {{DEP_NAME}} (dependente do contexto)
Build & Run	Comandos de build/teste	§9 Build & Run	{{BUILD_CMD}}, {{RUN_CMD}}, {{TEST_CMD}}
Pontos de Entrada	Arquivo/cena de inicialização e função	§1 Identidade do Projeto (Módulo)	{{MODULE_NAME}}

Para saída em idioma não inglês: traduza cabeçalhos de seção, rótulos e descrições de placeholders, mas mantenha os marcadores {{PLACEHOLDER}} intactos.

Quando Usar Esta Skill

• O usuário diz "init project docs" / "estabelecer sistema de documentos" / "project-docs"
• Um novo projeto precisa de PROJECT_STATE.md e DEVLOG.md
• Um projeto existente tem AGENTS.md, mas está sem os outros dois
• O usuário pede para atualizar o status do projeto após uma sessão

Fluxo de Trabalho

1. Inicializar (novo projeto / documentos ausentes)

0. Pergunte ao usuário em qual idioma gerar os documentos. Padrão: inglês. Se ele pular ou disser "não me importo", use inglês. Qualquer idioma que o LLM possa gerar é suportado — o agente lida com a tradução no momento da geração:

   "Em qual idioma os documentos do projeto devem ser escritos? Padrão: inglês. Qualquer idioma que o LLM possa gerar é suportado."

1. Verifique se AGENTS.md existe.

   • Se não: Ofereça-se para executar a skill project-onboard primeiro para gerar AGENTS.md. Pare aqui.
   • Se sim: Leia AGENTS.md e extraia:
     • Nome do projeto
     • Tipo (de Informações Básicas — ex.: "unreal", "unity", "nodejs", "python")
     • Arquitetura principal (classes, arquivos, funções)

2. Detectar modelo: Com base no Tipo extraído (em minúsculas), tente carregar um modelo específico para aquele tipo. Se não houver correspondência, use o modelo genérico:

   • Primeiro tente templates/<tipo>/PROJECT_STATE.md.tmpl
   • Se esse arquivo não existir, use templates/PROJECT_STATE.md.tmpl (genérico)

3. Gerar PROJECT_STATE.md a partir do modelo selecionado:

   • Pré-preencha §1-§3 com dados do AGENTS.md usando a tabela de mapeamento de campos acima.
   • Deixe as seções restantes com sua estrutura de placeholders para atualizações futuras.

4. Gerar DEVLOG.md a partir de templates/DEVLOG.md.tmpl:

   • Preencha o nome do projeto.
   • Deixe o modelo de entrada pronto para a primeira entrada do registro de desenvolvimento.

5. Adicione o seguinte bloco ao topo do AGENTS.md, imediatamente após a linha do cabeçalho # Nome do Projeto (mas antes do restante do conteúdo):

   ## Leia Primeiro Isto
   
   1. Leia `PROJECT_STATE.md` — status atual das tarefas e itens a fazer (§10)
   2. Leia `DEVLOG.md` — histórico de desenvolvimento recente
   
   ---
   

6. Relate o que foi criado, qual modelo foi usado e em qual idioma.

2. Atualizar (documentos existentes)

1. Leia PROJECT_STATE.md → identifique a lista de tarefas §10
2. Pergunte ao usuário o que foi concluído / o que mudou
3. Atualize as seções afetadas:
   • §1-§2: se a identidade do projeto ou a estrutura de diretórios mudou
   • §3: novas classes, arquivos ou membros-chave
   • §4: alterações de configuração (propriedades de blueprint, configurações de prefab ou configuração genérica)
   • §5: bindings de entrada, mapeamentos de ação ou alterações de módulo/pacote
   • §6: lógica do sistema, fluxo da arquitetura ou alterações de sistema do jogo
   • §7: configuração de cena/nível ou alterações de serviços externos
   • §8: quaisquer alterações de parâmetros numéricos
   • §9: problemas de build, novos erros de compilação ou alterações de comando
   • §10: sempre atualize — lista de concluídos, lista de tarefas, problemas conhecidos
4. Acrescente entrada ao DEVLOG.md (de acordo com o formato de maintenance-spec.md)
5. Se a arquitetura mudou (novas classes, plugins, diretórios) → atualize AGENTS.md

3. Verificação de Consistência

Após qualquer atualização, verifique:

• Não há dados sobrepostos entre AGENTS.md e PROJECT_STATE.md (visão geral da arquitetura vs. detalhes de parâmetros)
• As entradas da estrutura de diretórios no AGENTS.md têm contrapartes no PROJECT_STATE.md
• Os valores de parâmetros de §8 do PROJECT_STATE.md coincidem com os padrões reais da fonte (ex.: padrões em .h, valores de arquivos de configuração, substituições BP CDO)
• A lista de tarefas de §10 do PROJECT_STATE.md não contradiz a entrada mais recente do DEVLOG.md (se DEVLOG diz "concluído", STATE deve corresponder)
• Não há informações duplicadas entre os três documentos (um fato = um local)

Modelos

Os modelos são descobertos automaticamente por tipo de projeto — sem tabela de mapeamento fixa. O diretório espelha a estrutura de referência do project-onboard:

templates/
├── DEVLOG.md.tmpl              ← Todos os tipos (genérico)
├── PROJECT_STATE.md.tmpl       ← Fallback (genérico)
├── unreal/PROJECT_STATE.md.tmpl     ← Unreal Engine
└── unity/PROJECT_STATE.md.tmpl      ← Unity

Arquivos templates/<tipo>/PROJECT_STATE.md.tmpl são opcionais. A skill tenta carregar um que corresponda ao Type do AGENTS.md; se ausente, usa o modelo genérico raiz.

Adicionar um novo tipo: crie templates/<tipo>/PROJECT_STATE.md.tmpl com seções específicas do tipo. A skill o descobrirá na próxima execução — zero alterações de código.

Regras

• Nunca sobrescreva arquivos existentes. Se um documento existir, atualize-o no local.
• Respeite os limites de conteúdo: AGENTS.md = visão geral da arquitetura. PROJECT_STATE.md = detalhes de parâmetros + status. DEVLOG.md = narrativa cronológica.
• Especificação de manutenção: Consulte maintenance-spec.md para gatilhos exatos de atualização, limites de conteúdo e práticas proibidas.
• Caminhos/nomes de classe específicos do projeto em STATE/DEVLOG são esperados — são documentos do projeto, não manuais reutilizáveis.