sergeylopukhov/context-cartographer

Context Cartographer

Construye un sistema de documentación pequeño que permita a los agentes futuros cargar solo el contexto que necesitan.

Límite de Alcance

• Usa esta habilidad para la configuración del sistema de documentación, auditoría, migración, limpieza, reestructuración o propiedad de documentos poco clara.
• No la uses para una edición rutinaria cuando el archivo propietario de destino ya sea conocido.
• No la uses para el mantenimiento duradero automático ya requerido por AGENTS.md, CLAUDE.md, reglas de Cursor, docs/architecture.md o docs/code_rules.md. Aplica esas instrucciones locales directamente.
• Úsala siempre que el usuario invoque explícitamente context-cartographer.

Reglas Principales

• Resuelve la raíz del proyecto e inventaria las rutas reales antes de leer archivos del proyecto. No adivines rutas desde el directorio actual u otro proyecto.
• Reutiliza archivos ya leídos durante la tarea. Vuelve a leer solo un archivo cambiado, una salida truncada o un rango específico no leído.
• Mantén los archivos de instrucciones raíz del agente cortos. Coloca los detalles duraderos de los temas en los archivos propietarios dentro de docs/.
• Usa AGENTS.md para Codex, CLAUDE.md para Claude Code, .cursor/rules/context-cartographer.mdc para Cursor, o adaptadores ligeros para objetivos multi-agente seleccionados.
• Inspecciona en modo solo lectura antes de proponer cambios.
• Preserva las reglas existentes específicas del proyecto y edita quirúrgicamente.
• Nunca sobrescribas, muevas, combines o elimines archivos de instrucciones o documentación existentes sin aprobación.
• Crea solo archivos respaldados por la evidencia del proyecto y las necesidades actuales.
• Marca hechos desconocidos como TODO: aclarar; nunca inventes hechos del proyecto.
• Mantén los documentos de memoria del proyecto solo locales por defecto y agrégalos al archivo de ignorados del repositorio a menos que el usuario solicite explícitamente rastrearlos o publicarlos.
• Verifica enlaces, enrutamiento de propietarios, reglas de ignorados y referencias obsoletas después de las ediciones.

Decisiones Requeridas

Antes de crear o reemplazar instrucciones raíz del agente, resuelve:

• objetivo del agente;
• modo de reglas de código: usar docs/code_rules.md o no usarlo;
• modo de mantenimiento de documentación: mantenimiento duradero automático o mantenimiento solo a solicitud;
• manejo de documentos existentes: mantener tal cual, solo auditar, migrar después de aprobación, o dejar que el agente decida;
• si los documentos de memoria del proyecto permanecen solo locales o se rastrean.

No infieras el modo de reglas de código ni el modo de mantenimiento de documentación. Cuando falten más de dos decisiones, usa el cuestionario incluido.

Las instrucciones raíz generadas deben mantener el mantenimiento rutinario independiente de esta habilidad:

• Bajo mantenimiento duradero automático, actualiza el documento propietario correspondiente en la misma tarea cada vez que el trabajo completado cambie el comportamiento duradero, la arquitectura, la configuración, el despliegue, el staging, los datos de prueba, el acceso, la importación/exportación, las URLs públicas, el flujo de trabajo del operador, el modelo de datos, las interfaces públicas, el flujo de trabajo del agente o la propiedad de la documentación.
• Bajo mantenimiento solo a solicitud, actualiza los documentos solo cuando se solicite explícitamente y marca los documentos probablemente obsoletos.
• Indica que el mantenimiento rutinario utiliza las instrucciones raíz y los documentos propietarios existentes directamente sin invocar context-cartographer.
• Si ningún archivo propietario existente encaja, invoca esta habilidad y sigue el protocolo de propietario faltante. Bajo mantenimiento duradero automático, clasifica y crea el propietario más pequeño justificado automáticamente sin solicitar solo permiso para crear un archivo Markdown.
• Invoca esta habilidad más tarde solo para configuración, auditoría, migración, limpieza, reestructuración, uso explícito o propiedad genuinamente poco clara.

Enrutamiento de Referencias

• Para la configuración inicial, lee siempre references/setup-workflow.md; enruta las demás referencias requeridas.
• Para auditoría, migración, limpieza, reestructuración o propiedad poco clara, lee siempre references/existing-docs-workflow.md; enruta las demás referencias requeridas.
• Lee references/doc-map.md antes de elegir archivos o propiedad.
• Lee references/file-templates.md antes de crear instrucciones raíz o docs/*.md.
• Lee references/audit-checklist.md antes de auditar un repositorio existente.
• Lee references/cleanup-rules.md antes de dividir, fusionar, eliminar o renombrar documentos.
• Lee references/question_schema.md antes de crear el JSON del cuestionario.
• Lee references/questionnaire_usage_examples.md solo al adaptar el flujo del cuestionario.

Flujo de Trabajo

1. Resuelve la raíz del proyecto y las rutas de inventario con rg --files.
2. Clasifica el perfil del proyecto, el objetivo del agente seleccionado, los documentos existentes, la propiedad, el modo de reglas de código y el modo de mantenimiento.
3. Para documentos existentes, muestra un mapa compacto de los archivos actuales, propietarios de temas y acciones planificadas de creación/actualización/eliminación antes de editar.
4. Aplica el cambio más pequeño justificado al sistema de documentación dentro del alcance autorizado por el usuario.
5. Verifica enlaces, nombres de archivo obsoletos, cobertura de propietarios, reglas de ignorados solo locales y las instrucciones independientes de mantenimiento rutinario.

Para un sistema nuevo, sigue references/setup-workflow.md.

Para auditoría, limpieza, migración, reestructuración o propiedad poco clara, sigue references/existing-docs-workflow.md.

Cuestionario

Para un trabajo de configuración amplio con más de dos decisiones faltantes:

1. Crea .project-questionnaire/questions.json a partir de references/question_schema.md.
2. Establece language en el idioma del usuario o del proyecto.
3. Valida con python3 <this-skill>/scripts/questionnaire_server.py --input .project-questionnaire/questions.json --validate-only.
4. Ejecuta el servidor en 127.0.0.1 con un puerto automático.
5. Después de que el usuario guarde y diga que ha terminado, lee ambos archivos de respuestas antes de continuar.

El modo de reglas de código y el modo de mantenimiento de documentación deben ser opciones requeridas sin valores predeterminados ni opciones de recomendación.

Verificación de Actualizaciones

Ejecuta python3 <this-skill>/scripts/check_update.py --json como máximo una vez al día. Pregunta antes de instalar una actualización disponible. Aumenta VERSION al publicar un cambio que los usuarios instalados deban recibir.

Criterios de Salida

Informa:

• archivos creados o modificados;
• enlaces, enrutamiento y referencias obsoletas verificados;
• política de ignorados solo locales verificada;
• enrutamiento independiente de mantenimiento automático verificado;
• validación realizada y cualquier verificación no ejecutada.