ainova-systems/intelligence-dev-packs

Inicializar o Substrato de Documentação Guiada por Especificações

Estabeleça a base de conhecimento compartilhada do repositório — a camada que tanto humanos quanto agentes leem — para que o restante do pacote de especificações (spec-create, spec-execute) tenha onde escrever. Seguro e aditivo: nada é deletado, os rascunhos são inferidos até confirmação, e o proprietário aprova antes que qualquer informação se torne autoritativa.

Resolver a estrutura alvo (aprender, depois perfil, depois padrão) — nunca impor

1. Aprenda com o projeto primeiro. Se o repositório já possui uma estrutura de documentação (docs/, Documentation/, uma regra de docs, documentação de funcionalidades irmãs), adote-a — pesquise primeiro, leia dois documentos irmãos, imite, não invente. Uma estrutura existente e madura vence o padrão; não reestruture o que já funciona.
2. Perfil define caminhos quando ambíguos: specs_dir, features_dir, rules_dir, decisions_dir, spec_grouping.
3. Padrão para campo verde = a árvore de documentação priorizada para IA (veja references/docs-tree.md): docs/ com model.md, glossary.md, rules/R-NNN-*.md, features/<feature>.md, specs/NNN-<feature>/{requirements,plan,tasks}.md, decisions/NNNN-*.md, architecture/, guides/, _inbox/.

O modelo em camadas (o que este skill possui)

Ordenado por quão fortemente cada camada restringe um agente: um agente segue uma verificação executável de forma mais confiável do que texto em prosa.

• Camada A — restrições executáveis (configurações de lint/limites/testes de contrato, tests/): a mais forte. Fora do escopo aqui — configurado separadamente.
• Camada B — regras legíveis por máquina e conhecimento de arquitetura (regras como contratos rules/R-NNN, mapa de dependências, registro de decisões). spec-init cria esses documentos; o roteador de entrada do agente (AGENTS.md) permanece de propriedade do mecanismo de sincronização — este skill apenas garante que ele aponte para a árvore de documentação, nunca a sobrescreve.
• Camada C — base de conhecimento compartilhada (modelo, glossário, documentação de funcionalidades, especificações, arquitetura, guias). spec-init cria e semeia esta camada.

Passos

1. Inventário da documentação existente: todos os *.md, exportações de wiki, diagramas, anotações espalhadas. Classifique cada um como modelo / glossário / comportamento-de-funcionalidade / fluxo / decisão / arquitetura / guia / não classificado.
2. Criar a estrutura da árvore resolvida — crie apenas o que está faltando (pastas + um índice docs/README.md). Nunca sobrescreva um documento existente.
3. Migrar com segurança — quarentena primeiro. Mova todo o conteúdo pré-existente, não classificado ou legado para _inbox/ (a quarentena) para que apenas a nova estrutura seja lida como autoritativa. Em seguida, reclassifique um item de cada vez com revisão do proprietário: anotações "como X funciona" -> features/, diagramas de fluxo -> architecture/diagrams/, decisões -> decisions/. Nada é deletado; a reclassificação é item por item, nunca em lote automático.
4. Rascunhar os documentos principais a partir do código, marcados como confirmed / inferred: o modelo de domínio (model.md) e glossário (glossary.md) a partir de tipos e nomes de campos; linhas de base de comportamento de funcionalidades (features/) a partir do comportamento real do código hoje + critérios de aceitação EARS; o mapa de dependências a partir de importações reais; regras de negócio numeradas candidatas (rules/R-NNN) que o código já aplica.
5. Aplicar o princípio de nomenclatura. Tudo abaixo da raiz de documentação usa kebab-case minúsculo; séries ordenadas usam prefixos com zeros à esquerda (NNNN- ADRs, NNN- especificações); um conceito, um nome, sem sinônimos. Os únicos arquivos em maiúsculas são AGENTS.md e README.md na raiz (padrões externos exigem esses nomes).
6. Portão do proprietário. Apresente a árvore criada, o conteúdo de _inbox/ pendente de reclassificação e os documentos rascunhados. Nada é autoritativo até que o proprietário confirme cada rascunho; tudo permanece inferred até lá.

Verificar

• A árvore resolvida existe; o índice a lista; todo arquivo pré-existente foi reclassificado ou está em _inbox/ (nenhum perdido); cada documento rascunhado está marcado como confirmado/inferido; AGENTS.md não foi sobrescrito.

Escopo / passagem de bastão

• Criar uma especificação de mudança dentro de specs/ criado — spec-create.
• Restrições executáveis da Camada A (lint, limites, testes de contrato) — fora do escopo; configuração separada.
• Manter a documentação sincronizada com o código depois — spec-audit-docs.

CRÍTICO

• Nunca delete ou sobrescreva documentação existente — coloque em quarentena em _inbox/, reclassifique item por item, revisado pelo proprietário.
• Nunca imponha a árvore padrão sobre uma estrutura de projeto que funcione — aprenda e adote primeiro.
• Ressalva honesta a ser declarada na saída: isto fixa apenas o que já está estruturado no código. Regras de negócio que vivem em configurações, linhas de banco de dados ou extensões registradas em tempo de execução são invisíveis para a criação estática — sinalize-as para testes funcionais ou migração gradual para o código; nunca invente uma regra que o código não mostre.