vlv-code/init-meta-project

Inicialização e Upgrade do Ambiente do Agente (Init & Audit do Meta-Projeto)

Skill autônoma para preparar qualquer repositório para fluxos de trabalho com agentes. Verifica automaticamente se existe uma estrutura meta-project, evita sobrescrever dados acumulados e realiza um upgrade seguro para o padrão mais recente, ou cria a estrutura do zero.

Baseia-se no princípio de refresh contínuo e oportunista: ao acessar fatias de meta-conhecimento, o agente deve preencher lacunas e manter uma visão coesa do projeto.

---

Quando invocar a skill

• O usuário solicita: "prepare repo para agentes", "inicialize meta-project", "verifique agents.md", "atualize estrutura do agente", "refresh meta-conhecimento".

---

Passos de execução

Fase 0: Verificar Ambiente de Meta-Projeto Existente

Antes de realizar qualquer escrita, verifique a presença dos componentes do meta-projeto:

1. Verifique se AGENTS.md existe na raiz do repositório.
2. Verifique se os diretórios .agents/project_knowledge/ e .agents/skills/ existem.

Cenário A: Estrutura Já Existe (Modo Auditoria e Upgrade Seguro)

Se AGENTS.md ou a pasta .agents/ já estiver presente no repositório:

1. Proibição de Sobrescrita Destrutiva:
   • É estritamente proibido deletar ou sobrescrever observations.md — todas as observações acumuladas devem ser preservadas.
   • É proibido deletar invariantes personalizados e descrições de usuário do AGENTS.md existente.
2. Auditoria de Conformidade com Padrões:
   • Verifique se AGENTS.md possui a seção "Princípios e Orientações Arquiteturais (North Stars)". Se faltar, adicione-a sem modificar o propósito do serviço e os invariantes.
   • Verifique se AGENTS.md possui o protocolo de diretiva com o link "access + opportunistic refresh". Se desatualizado, atualize a seção.
   • Verifique se boundaries.md utiliza padrões glob, proteção de diretórios de dados (data/**, *.db), atribuição de módulos de formatação/renderização à zona Amarela, e presença do invariante Default Deny (Zona Preta).
   • Verifique se a tabela de observations.md possui a coluna Category. Se estiver usando o formato legado de 4 colunas, atualize o cabeçalho da tabela sem deletar linhas de dados.
   • Verifique a atualidade dos arquivos SKILL.md em .agents/skills/ (record-observation, sync-architecture, ground-meta-project).
3. Melhoria Segura:
   • Crie fatias ausentes (por exemplo, se weak_spots.md estiver ausente).
   • Complemente o registro de skills em AGENTS.md com novas skills de stack especializadas para o repositório.
4. Relatório de Upgrade:
   • Informe ao usuário: "Meta-projeto existente detectado. Auditado e atualizado para o padrão mais recente sem perda de dados acumulados."

---

Cenário B: Configuração Inicial (Modo Scaffold Limpo)

Se nenhuma estrutura existir, execute o algoritmo padrão de dois passos:

Passo 1: Varredura Expressa e Geração do Esqueleto (Rápido e de Alto Nível)

1. Inspeção expressa da raiz do repositório: Liste o diretório raiz e identifique:

   • Manifestos: package.json, pyproject.toml, go.mod, Cargo.toml, requirements.txt, pom.xml, docker-compose.yml.
   • Diretórios principais: src/, app/, tests/, migrations/, scripts/, data/.
   • Regra de Zero Diretórios Não Mapeados: Enumere todos os diretórios fonte de nível superior na raiz do repositório. Filtre estritamente caminhos de .gitignore, metadados de VCS e caches padrão de build/pacote/teste (.git, node_modules, .venv, venv, dist, build, coverage, __pycache__, .pytest_cache, .idea, .vscode). Cada diretório fonte de nível superior restante DEVE ser explicitamente contabilizado e mapeado para as zonas Verde, Amarela ou Vermelha em boundaries.md (diretórios não mapeados caem em Default Deny / Zona Vermelha por padrão).
   • Nome do projeto, propósito e conceitos principais do README.md (se presente).
   • Chaves e dependências necessárias do .env.example (se presente).

2. Identifique a stack de tecnologia e princípios principais:

   • Formule uma string de stack concisa (ex.: Python 3.12, FastAPI, uv, pytest, Docker).
   • Destaque 2-3 orientações de base (ex.: simplicidade arquitetural, tipagem estrita, imutabilidade de dados, offline-first).

3. Crie a estrutura de diretórios: Crie diretórios:

   • .agents/project_knowledge/
   • .agents/project_knowledge/archive/
   • .agents/skills/record-observation/
   • .agents/skills/sync-architecture/
   • .agents/skills/ground-meta-project/
   • scripts/

4. Implante skills de meta-projeto e scripts de runtime: Escreva os arquivos SKILL.md a partir dos modelos incorporados abaixo em:

   • .agents/skills/record-observation/SKILL.md
   • .agents/skills/sync-architecture/SKILL.md
   • .agents/skills/ground-meta-project/SKILL.md Implante scripts de automação de boundary e compactação sem dependências no scripts/ do repositório:
   • scripts/check_boundaries.py (Boundary Gate CLI)
   • scripts/compact_memory.py (Context Rot Shield & Memory Compactor)

5. Crie rascunhos iniciais das fatias de conhecimento: Escreva arquivos em .agents/project_knowledge/:

   • observations.md (tabela de 5 colunas com a primeira linha de inicialização; use exemplos de comando cross-platform, ex.: python -m pytest).
   • boundaries.md (modelo de zonas com padrões glob básicos: formatação na zona Amarela, dados na Vermelha).
   • weak_spots.md (estrutura de registro de riscos de base).
   • architecture.md (scaffold arquitetural de base).
   • tasks.md (objetivo ativo, checklist da equipe e registro de delegação).

Passo 2: Mergulho Profundo no Repositório, Princípios e Skills da Shell

1. Checklist de Inspeção Principal Obrigatória: Proibido popular weak_spots.md e architecture.md com modelos boilerplate sem ler o código fonte dos módulos principais! O agente deve executar chamadas read_file para as seguintes áreas críticas:

   • Armazenamento e Banco de Dados: Leia o módulo principal de acesso a dados (storage.py, repositórios, modelos). Avalie o tamanho monolítico (contagem de LOC), acoplamento de esquema e configuração de migração.
   • API Externa e Clientes de Serviço: Leia módulos de integração (SDKs de modelos de IA, clientes externos). Verifique retries, timeouts, fallbacks e singletons globais.
   • Containerização e Runtime: Leia Dockerfile, docker-compose.yml e workflows de CI (.github/workflows/). Verifique dependências de binários do sistema (FFmpeg, utilitários), permissões de usuário (UID) e montagens de volumes de dados.
   • Interface de Usuário e Entrada: Leia módulos de teclado/roteador. Verifique restrições de plataforma (ex.: limite de 64 bytes para callback_data do Telegram, estados FSM, confirmação para ações destrutivas).

2. Entrevista de Calibração Interativa (Protocolo Codificado de Duas Perguntas): Varreduras automatizadas identificam o que existe no código, mas não podem detectar contexto histórico não escrito, invariantes de negócio ou sensibilidades de produção. O agente realiza uma breve entrevista interativa estruturada (via ferramenta ask_question ou um prompt interativo direto) fazendo exatamente 2 perguntas focadas:

   • Pergunta 1 (North Stars e Invariantes Principais): "Quais invariantes arquiteturais principais, regras de negócio e restrições de produção (North Stars) não podem ser violados em nenhuma melhoria?"
   • Pergunta 2 (Zona Vermelha e Caminhos Sensíveis): "Quais diretórios ou módulos específicos (faturamento, BD, criptografia, chaves, legado) são críticos e devem ser bloqueados na Zona Vermelha?"

   Processando respostas:

   • As respostas do usuário à Pergunta 1 são imediatamente integradas à Seção 1 do AGENTS.md ("Princípios e Orientações Arquiteturais (North Stars)").
   • As respostas do usuário à Pergunta 2 são mapeadas para a Zona Vermelha do boundaries.md antes da gravação única.
   • Se o usuário pular ou fornecer uma resposta vazia, recorra graciosamente às orientações deduzidas do Checklist de Inspeção Principal.

3. Calibre os conceitos e princípios do projeto: Combine as descobertas do checklist e as respostas da entrevista em 2-3 orientações arquiteturais concisas (North Stars) prevenindo ações contraditórias do agente.

4. Combine skills da stack do registro da shell do agente: Mapeie a stack do repositório para skills especializadas disponíveis no ambiente do agente (~/.gemini/config/skills/ e built-in):

   • Python / uv / ruff → python-pro
   • FastAPI → fastapi-pro
   • TypeScript / JavaScript → typescript-expert
   • Next.js → nextjs-best-practices
   • Docker / Dockerfile / Compose → docker-expert
   • PostgreSQL / SQL / migrations → postgresql-optimization, sql-pro
   • Kubernetes / Helm → kubernetes-architect
   • Telegram bot / aiogram → telegram-bot-builder
   • Pipelines CI/CD → github-actions-creator
   • Clean code & review → clean-code, code-reviewer

5. Calibre os boundaries (boundaries.md): Refine os padrões glob em .agents/project_knowledge/boundaries.md para os diretórios reais do projeto:

   • Default Deny / 100% de Cobertura de Caminhos (Zero Diretórios Não Mapeados): Garanta que todo diretório fonte de nível superior não ignorado seja explicitamente atribuído a uma zona. Adicione a regra Default Deny (Zona Preta): qualquer caminho não mapeado é estritamente Zona Vermelha por padrão.
   • Diferenciação da Zona de Teste:
     • Criar novos testes para novas funcionalidades — Zona Verde.
     • Suíte de testes de regressão existente (tests/**, *_test.*, *.spec.*) — estritamente Zona Amarela com invariante proibindo enfraquecimento de asserções (assert/expect).
     • Testes de integridade arquitetural, contrato de API e esquema de dados (*integrity*, *contract*, *schema*, E2E) — estritamente Zona Vermelha.
   • Módulos de formatação/escaping e engines de template — estritamente Zona Amarela.
   • Arquivos e diretórios de banco de dados (data/**, *.db, *.sqlite*) — estritamente Zona Vermelha.
   • Substitua caminhos placeholder por caminhos reais de migração (alembic/versions/**, prisma/migrations/**, etc.).
   • Substitua caminhos de rota/controller por locais reais de subsistemas.

6. Análise de risco e pontos fracos (weak_spots.md): Registre dívida técnica concreta identificada durante a inspeção principal (monólitos, singletons), dependências externas de runtime (Redis, Postgres, message brokers, utilitários de sistema como FFmpeg), restrições de plataforma e variáveis obrigatórias do .env.example.

7. Popule a fatia de arquitetura (architecture.md): Descreva a stack de alto nível, subsistemas, tarefas/schedulers em background e fluxos de dados com base nos módulos principais inspecionados.

   • Fluxos de Dados Condicionais de Ponta a Ponta: Gere o esquema de "Fluxos de Dados de Ponta a Ponta (Rastreamento de Fluxo Pré-Voo)" sempre que componentes multi-camada, cliente-servidor, API ou UI forem detectados (mapeando [Origem: UI/CLI/Evento] ➔ [Transporte: Rota de API / Mensagem] ➔ [Domínio / Armazenamento: Persistência] ➔ [Montagem / Empacotador] ➔ [Consumidor: Cliente / Daemon]). Para bibliotecas CLI puras de camada única ou stdlib sem comunicação externa ou camadas de persistência, omita esta seção para evitar inchaço de contexto.

8. Protocolo de Varredura de Síntese em Memória: O agente não escreve rascunhos intermediários em disco. Todos os invariantes são sintetizados na memória de trabalho durante os Passos 1 e 2, após o que os arquivos são escritos em ordem estrita de baixo para cima:

   • Etapa A: Skills pré-instaladas (.agents/skills/record-observation/, sync-architecture/ e ground-meta-project/) e scripts de automação (scripts/check_boundaries.py, scripts/compact_memory.py se configuração de repositório compartilhado).
   • Etapa B: Fatias de conhecimento (observations.md -> boundaries.md -> weak_spots.md -> architecture.md).
   • Etapa C: Passaporte raiz (AGENTS.md) — estritamente por último, como o agregador de referências às fatias e skills da stack.

---

Finalização e Verificação

1. Verifique os arquivos criados/atualizados usando Get-ChildItem -Recurse .agents ou ls -R .agents.
2. Opção de Sobreposição Invisível Local: Se estiver inicializando em um projeto externo/cliente ou se o modo pessoal sem commits Git for solicitado:
   • Adicione AGENTS.md e .agents/ ao .git/info/exclude no repositório alvo.
   • Verifique git status: os arquivos de meta-projeto não devem aparecer em Arquivos não rastreados.
3. Gere um resumo conciso para o usuário:
   • Modo de execução (configuração inicial vs auditoria com upgrade; sobreposição compartilhada vs invisível).
   • Árvore de arquivos criada/atualizada.
   • Orientações do projeto capturadas (North Stars).
   • Lista de skills da stack vinculadas.

---

Modelos de Referência Incorporados

Modelo: record-observation/SKILL.md

---
name: record-observation
description: >-
  Use esta skill para registrar um bug não documentado, peculiaridade de ambiente, caso extremo de runtime,
  ou solução não óbvia na tabela `.agents/project_knowledge/observations.md` do repositório.
---

# Registrar Observação na Base de Conhecimento do Repositório

1. Verifique se `.agents/project_knowledge/observations.md` existe.
2. Verifique as últimas 20 linhas em busca de duplicatas.
3. Adicione a entrada estritamente como uma única linha de tabela Markdown:
   `| YYYY-MM-DD | [<categoria>] | <Caminho_ou_componente> | <Breve resumo do problema/fato> | <Solução ou contorno> |`
   Categorias: `[build]`, `[runtime]`, `[deps]`, `[db]`, `[api]`, `[test]`, `[env]`, `[ci]`, `[boundaries]`, `[orchestration]`, `[decommission]`, `[incident]`, `[init]`, ou tag de domínio explícita (ex.: `[theme]`).
4. Se o número de linhas > 30–40, arquive registros resolvidos em `.agents/project_knowledge/archive/observations-YYYY.md`.

Modelo: sync-architecture/SKILL.md

---
name: sync-architecture
description: >-
  Use esta skill para analisar módulos do repositório, dependências e pontos de entrada,
  e gerar ou atualizar `.agents/project_knowledge/architecture.md`.
---

# Sincronizar Fatia de Arquitetura do Projeto

1. Leia manifestos de dependência e build.
2. Identifique pontos de entrada e diretórios de nível superior.
3. Identifique 3–5 subsistemas, seus papéis e fluxos de dados.
4. Atualize `.agents/project_knowledge/architecture.md`.
5. Exiba um breve resumo das mudanças para o usuário.

Modelo: ground-meta-project/SKILL.md

---
name: ground-meta-project
description: >-
  Skill de recalibração e aterramento de emergência: interrompe edições descontroladas, força um zoom-out, relê AGENTS.md,
  o passaporte de função ativo, boundaries.md e o mapa de arquitetura, diagnostica desvio de contexto e redefine o age

…

[truncado para tradução]