sergeylopukhov/context-cartographer

Context Cartographer

Construa um pequeno sistema de documentação que permite que agentes futuros carreguem apenas o contexto de que precisam.

Limite de Escopo

• Use esta habilidade para configuração de sistema de documentação, auditoria, migração, limpeza, reestruturação ou propriedade pouco clara.
• Não a use para uma edição de rotina quando o arquivo dono alvo já for conhecido.
• Não a use para manutenção durável automática já exigida por AGENTS.md, CLAUDE.md, regras do Cursor, docs/architecture.md ou docs/code_rules.md. Aplique essas instruções locais diretamente.
• Sempre a use quando o usuário invocar explicitamente context-cartographer.

Regras Essenciais

• Resolva a raiz do projeto e os caminhos reais do inventário antes de ler arquivos do projeto. Não adivinhe caminhos a partir do diretório atual ou de outro projeto.
• Reutilize arquivos já lidos durante a tarefa. Releia apenas um arquivo alterado, saída truncada ou um intervalo específico não lido.
• Mantenha arquivos de instrução raiz do agente curtos. Coloque detalhes duráveis de tópicos em arquivos donos sob docs/.
• Use AGENTS.md para Codex, CLAUDE.md para Claude Code, .cursor/rules/context-cartographer.mdc para Cursor, ou adaptadores finos para alvos multiagente selecionados.
• Inspecione em modo somente leitura antes de propor alterações.
• Preserve regras existentes específicas do projeto e edite cirurgicamente.
• Nunca sobrescreva, mova, mescle ou exclua arquivos de instrução ou documentação existentes sem aprovação.
• Crie apenas arquivos suportados por evidências do projeto e necessidades atuais.
• Marque fatos desconhecidos como TODO: esclarecer; nunca invente fatos do projeto.
• Mantenha documentos de memória do projeto como locais por padrão e adicione-os ao arquivo de ignorar do repositório, a menos que o usuário peça explicitamente para rastreá-los ou publicá-los.
• Verifique links, roteamento de donos, regras de ignorar e referências desatualizadas após as edições.

Decisões Necessárias

Antes de criar ou substituir instruções raiz do agente, resolva:

• alvo do agente;
• modo de regras de código: usar docs/code_rules.md ou não usá-lo;
• modo de manutenção da documentação: manutenção automática durável ou manutenção somente sob solicitação;
• tratamento de documentos existentes: manter como está, apenas auditar, migrar após aprovação ou deixar o agente decidir;
• se os documentos de memória do projeto permanecem apenas locais ou são rastreados.

Não infira o modo de regras de código ou o modo de manutenção da documentação. Quando mais de duas decisões estiverem faltando, use o questionário agrupado.

As instruções raiz geradas devem manter a manutenção de rotina independente desta habilidade:

• Sob manutenção automática durável, atualize o documento dono correspondente na mesma tarefa sempre que o trabalho concluído alterar comportamento durável, arquitetura, configuração, implantação, preparação, dados de teste, acesso, importação/exportação, URLs públicos, fluxo de trabalho do operador, modelo de dados, interfaces públicas, fluxo de trabalho do agente ou propriedade da documentação.
• Sob manutenção somente sob solicitação, atualize documentos apenas quando explicitamente solicitado e sinalize documentos provavelmente desatualizados.
• Declare que a manutenção de rotina usa instruções raiz e documentos donos existentes diretamente, sem invocar context-cartographer.
• Se nenhum arquivo dono existente se encaixar, invoque esta habilidade e siga o protocolo de dono ausente. Sob manutenção automática durável, classifique e crie o menor dono justificado automaticamente sem pedir permissão apenas para criar um arquivo Markdown.
• Invoque esta habilidade posteriormente apenas para configuração, auditoria, migração, limpeza, reestruturação, uso explícito ou propriedade genuinamente pouco clara.

Roteamento de Referências

• Para configuração inicial, sempre leia references/setup-workflow.md; ele roteia as outras referências necessárias.
• Para auditoria, migração, limpeza, reestruturação ou propriedade pouco clara, sempre leia references/existing-docs-workflow.md; ele roteia as outras referências necessárias.
• Leia references/doc-map.md antes de escolher arquivos ou propriedade.
• Leia references/file-templates.md antes de criar instruções raiz ou docs/*.md.
• Leia references/audit-checklist.md antes de auditar um repositório existente.
• Leia references/cleanup-rules.md antes de dividir, mesclar, excluir ou renomear documentos.
• Leia references/question_schema.md antes de criar o JSON do questionário.
• Leia references/questionnaire_usage_examples.md apenas ao adaptar o fluxo do questionário.

Fluxo de Trabalho

1. Resolva a raiz do projeto e os caminhos do inventário com rg --files.
2. Classifique o perfil do projeto, alvo do agente selecionado, documentos existentes, propriedade, modo de regras de código e modo de manutenção.
3. Para documentos existentes, mostre um mapa compacto dos arquivos atuais, donos de tópicos e ações planejadas de criação/atualização/exclusão antes de editar.
4. Aplique a menor mudança justificada no sistema de documentação dentro do escopo autorizado pelo usuário.
5. Verifique links, nomes de arquivo desatualizados, cobertura de donos, regras de ignorar apenas local e as instruções independentes de manutenção de rotina.

Para um novo sistema, siga references/setup-workflow.md.

Para auditoria, limpeza, migração, reestruturação ou propriedade pouco clara, siga references/existing-docs-workflow.md.

Questionário

Para trabalho de configuração amplo com mais de duas decisões faltando:

1. Crie .project-questionnaire/questions.json a partir de references/question_schema.md.
2. Defina language para o idioma do usuário ou projeto.
3. Valide com python3 <this-skill>/scripts/questionnaire_server.py --input .project-questionnaire/questions.json --validate-only.
4. Execute o servidor em 127.0.0.1 com uma porta automática.
5. Após o usuário salvar e dizer que terminou, leia ambos os arquivos de resposta antes de continuar.

O modo de regras de código e o modo de manutenção da documentação devem ser escolhas obrigatórias sem padrões ou opções de recomendação.

Verificação de Atualização

Execute python3 <this-skill>/scripts/check_update.py --json no máximo uma vez por dia. Pergunte antes de instalar uma atualização disponível. Atualize VERSION ao publicar uma alteração que usuários instalados devam receber.

Critérios de Saída

Relate:

• arquivos criados ou alterados;
• links, roteamento e referências desatualizadas verificados;
• política de ignorar apenas local verificada;
• roteamento independente de manutenção automática verificado;
• validação realizada e quaisquer verificações não executadas.