vlv-code/init-meta-project

Inicialización y Actualización del Entorno del Agente (Inicialización y Auditoría del Meta-Proyecto)

Habilidad autónoma para preparar cualquier repositorio para flujos de trabajo con agentes. Verifica automáticamente la existencia de una estructura meta-project, evita sobrescribir datos acumulados y realiza una actualización segura al estándar más reciente o crea la estructura desde cero.

Se basa en el principio de actualización continua/oportunista: al acceder a fragmentos de metaconocimiento, el agente debe cerrar brechas y mantener una visión cohesiva del proyecto.

---

Cuándo invocar la habilidad

• El usuario solicita: "preparar repo para agentes", "inicializar meta-proyecto", "verificar agents.md", "actualizar estructura del agente", "refrescar meta-conocimiento".

---

Pasos de ejecución

Fase 0: Verificar el Entorno Existente del Meta-Proyecto

Antes de realizar cualquier escritura, verifique la presencia de componentes del meta-proyecto:

1. Verifique la existencia de AGENTS.md en la raíz del repositorio.
2. Verifique la existencia de los directorios .agents/project_knowledge/ y .agents/skills/.

Escenario A: La Estructura ya Existe (Modo de Auditoría y Actualización Segura)

Si AGENTS.md o la carpeta .agents/ ya están presentes en el repositorio:

1. Prohibición de Sobrescritura Destructiva:
   • Está estrictamente prohibido eliminar o sobrescribir observations.md — todas las observaciones acumuladas deben preservarse.
   • Está prohibido eliminar invariantes personalizadas y descripciones de usuario del AGENTS.md existente.
2. Auditoría de Cumplimiento de Estándares:
   • Verifique que AGENTS.md contenga la sección "Principios y Orientaciones Arquitectónicas (North Stars)". Si falta, agréguela sin modificar el propósito del servicio ni las invariantes.
   • Verifique que AGENTS.md contenga el protocolo de directiva con el enlace "acceder + actualización oportunista". Si está desactualizado, actualice la sección.
   • Verifique que boundaries.md utilice patrones glob, protección de directorios de datos (data/**, *.db), asigne módulos de formateo/renderizado a la zona Amarilla y contenga la invariante de Denegación por Defecto (Zona Negra).
   • Verifique la tabla de observations.md para la columna Categoría. Si usa el formato heredado de 4 columnas, actualice el encabezado de la tabla sin eliminar filas de datos.
   • Verifique la actualidad de los archivos SKILL.md en .agents/skills/ (record-observation, sync-architecture, ground-meta-project).
3. Mejora Segura:
   • Cree fragmentos faltantes (por ejemplo, si weak_spots.md está ausente).
   • Complemente el registro de habilidades en AGENTS.md con nuevas habilidades de pila especializadas para el repositorio.
4. Informe de Actualización:
   • Informe al usuario: "Meta-proyecto existente detectado. Auditado y actualizado al estándar más reciente sin pérdida de datos acumulados."

---

Escenario B: Configuración Inicial (Modo de Andamiaje Limpio)

Si no existe estructura, ejecute el algoritmo estándar de dos pasadas:

Pasada 1: Escaneo Rápido y Generación del Esqueleto (Rápido y de Alto Nivel)

1. Inspección rápida de la raíz del repositorio: Liste el directorio raíz e identifique:

   • Manifiestos: package.json, pyproject.toml, go.mod, Cargo.toml, requirements.txt, pom.xml, docker-compose.yml.
   • Directorios principales: src/, app/, tests/, migrations/, scripts/, data/.
   • Regla de Cero Directorios No Mapeados: Enumere todos los directorios fuente de nivel superior en la raíz del repositorio. Filtre estrictamente las rutas de .gitignore, metadatos de VCS y cachés estándar de compilación/empaquetado/pruebas (.git, node_modules, .venv, venv, dist, build, coverage, __pycache__, .pytest_cache, .idea, .vscode). Cada directorio fuente de nivel superior restante DEBE ser explícitamente contabilizado y mapeado a las zonas Verde, Amarilla o Roja en boundaries.md (los directorios no mapeados caen bajo la Denegación por Defecto / Zona Roja por defecto).
   • Nombre del proyecto, propósito y conceptos principales de README.md (si existe).
   • Claves y dependencias requeridas de .env.example (si existe).

2. Identifique la pila tecnológica y los principios principales:

   • Formule una cadena de pila concisa (ej: Python 3.12, FastAPI, uv, pytest, Docker).
   • Destaque 2 o 3 orientaciones base (ej: simplicidad arquitectónica, tipado estricto, inmutabilidad de datos, offline-first).

3. Cree la estructura de directorios: Cree directorios:

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

4. Despliegue las habilidades del meta-proyecto empaquetadas y los scripts de ejecución: Escriba los archivos SKILL.md a partir de las plantillas incrustadas a continuación en:

   • .agents/skills/record-observation/SKILL.md
   • .agents/skills/sync-architecture/SKILL.md
   • .agents/skills/ground-meta-project/SKILL.md Despliegue scripts de automatización de límites y compactación sin dependencias en scripts/ del repositorio:
   • scripts/check_boundaries.py (CLI de Puerta de Límites)
   • scripts/compact_memory.py (Escudo de Rotación de Contexto y Compactador de Memoria)

5. Cree borradores iniciales de fragmentos de conocimiento: Escriba archivos en .agents/project_knowledge/:

   • observations.md (tabla de 5 columnas con la primera fila de inicialización; use ejemplos de comandos multiplataforma, ej: python -m pytest).
   • boundaries.md (plantilla de zonas con patrones glob básicos: formateo en zona Amarilla, datos en zona Roja).
   • weak_spots.md (estructura de registro de riesgos base).
   • architecture.md (andamiaje arquitectónico base).
   • tasks.md (objetivo activo, lista de verificación del equipo y registro de delegación).

Pasada 2: Inmersión Profunda en el Repositorio, Principios y Habilidades de Shell

1. Lista de Verificación de Inspección Principal Obligatoria: ¡Prohibido poblar weak_spots.md y architecture.md con plantillas repetitivas sin leer el código fuente de los módulos clave! El agente debe ejecutar llamadas read_file para las siguientes áreas críticas:

   • Almacenamiento y Base de Datos: Lea el módulo de acceso a datos principal (storage.py, repositorios, modelos). Evalúe el tamaño monolítico (recuento de LOC), acoplamiento de esquemas y configuración de migraciones.
   • API Externa y Clientes de Servicio: Lea los módulos de integración (SDK de modelos de IA, clientes externos). Verifique reintentos, tiempos de espera, alternativas y singletons globales.
   • Contenedorización y Entorno de Ejecución: Lea Dockerfile, docker-compose.yml y flujos de trabajo de CI (.github/workflows/). Verifique dependencias de binarios del sistema (FFmpeg, utilidades), permisos de usuario (UID) y montajes de volúmenes de datos.
   • Interfaz de Usuario y Entrada: Lea los módulos de teclado/enrutador. Verifique restricciones de plataforma (ej: límite de 64 bytes para callback_data de Telegram, estados FSM, confirmación para acciones destructivas).

2. Entrevista de Calibración Interactiva (Protocolo de Dos Preguntas Codificado): Los escaneos automatizados identifican lo que existe en el código, pero no pueden detectar contexto histórico no escrito, invariantes de negocio o sensibilidades de producción. El agente realiza una breve entrevista interactiva estructurada (a través de la herramienta ask_question o un mensaje interactivo directo) haciendo exactamente 2 preguntas enfocadas:

   • Pregunta 1 (North Stars e Invariantes Principales): "¿Cuáles son las invariantes arquitectónicas clave, reglas de negocio y restricciones de producción (North Stars) que no deben romperse bajo ninguna modificación?"
   • Pregunta 2 (Zona Roja y Rutas Sensibles): "¿Qué directorios o módulos específicos (facturación, BD, criptografía, claves, legado) son críticos y deben estar bloqueados en la Zona Roja?"

   Procesamiento de respuestas:

   • Las respuestas del usuario a la Pregunta 1 se integran inmediatamente en la Sección 1 de AGENTS.md ("Principios y Orientaciones Arquitectónicas (North Stars)").
   • Las respuestas del usuario a la Pregunta 2 se mapean en la Zona Roja de boundaries.md antes del volcado de una sola pasada.
   • Si el usuario omite o proporciona una respuesta vacía, recurra elegantemente a las orientaciones deducidas de la Lista de Verificación de Inspección Principal.

3. Calibre los conceptos y principios del proyecto: Sintetice los hallazgos de la lista de verificación y las respuestas de la entrevista en 2 o 3 orientaciones arquitectónicas concisas (North Stars) que eviten acciones contradictorias del agente.

4. Empareje las habilidades de la pila desde el registro de shell del agente: Mapee la pila del repositorio a habilidades especializadas disponibles en el entorno del agente (~/.gemini/config/skills/ e integradas):

   • Python / uv / ruff → python-pro
   • FastAPI → fastapi-pro
   • TypeScript / JavaScript → typescript-expert
   • Next.js → nextjs-best-practices
   • Docker / Dockerfile / Compose → docker-expert
   • PostgreSQL / SQL / migraciones → postgresql-optimization, sql-pro
   • Kubernetes / Helm → kubernetes-architect
   • Bot de Telegram / aiogram → telegram-bot-builder
   • Pipelines CI/CD → github-actions-creator
   • Código limpio y revisión → clean-code, code-reviewer

5. Calibre los límites (boundaries.md): Refine los patrones glob en .agents/project_knowledge/boundaries.md para los directorios reales del proyecto:

   • Denegación por Defecto / Cobertura de Ruta al 100% (Cero Directorios No Mapeados): Garantice que cada directorio fuente de nivel superior no ignorado esté asignado explícitamente a una zona. Agregue la regla de Denegación por Defecto (Zona Negra): cualquier ruta no mapeada es estrictamente Zona Roja por defecto.
   • Diferenciación de Zona de Pruebas:
     • Crear nuevas pruebas para nueva funcionalidad — Zona Verde.
     • Conjunto de pruebas de regresión existente (tests/**, *_test.*, *.spec.*) — estrictamente Zona Amarilla con invariante que prohíbe debilitar aserciones (assert/expect).
     • Pruebas de integridad arquitectónica, contrato de API y esquema de datos (*integrity*, *contract*, *schema*, E2E) — estrictamente Zona Roja.
   • Módulos de formateo/escapado y motores de plantillas — estrictamente Zona Amarilla.
   • Archivos y directorios de base de datos (data/**, *.db, *.sqlite*) — estrictamente Zona Roja.
   • Reemplace las rutas de marcador de posición con rutas de migración reales (alembic/versions/**, prisma/migrations/**, etc.).
   • Reemplace las rutas de ruta/controlador con ubicaciones reales de subsistemas.

6. Análisis de riesgos y puntos débiles (weak_spots.md): Registre la deuda técnica concreta identificada durante la inspección principal (monolitos, singletons), dependencias externas de tiempo de ejecución (Redis, Postgres, brokers de mensajes, utilidades del sistema como FFmpeg), restricciones de plataforma y variables obligatorias de .env.example.

7. Pueble el fragmento de arquitectura (architecture.md): Describa la pila de alto nivel, subsistemas, tareas en segundo plano/programadores y flujos de datos basados en los módulos principales inspeccionados.

   • Flujos de Datos de Extremo a Extremo Condicionales: Genere el esquema "Flujos de Datos de Extremo a Extremo (Trazado de Flujo Previo al Vuelo)" siempre que se detecten componentes de múltiples capas, cliente-servidor, API o UI (mapeando [Origen: UI/CLI/Evento] ➔ [Transporte: Ruta API / Mensaje] ➔ [Dominio / Almacenamiento: Persistencia] ➔ [Ensamblaje / Empaquetador] ➔ [Consumidor: Cliente / Daemon]). Para bibliotecas CLI puras de una sola capa o stdlib sin comunicación externa o capas de persistencia, omita esta sección para evitar inflar el contexto.

8. Protocolo de Volcado de Síntesis en Memoria: El agente no escribe borradores intermedios en el disco. Todas las invariantes se sintetizan en la memoria de trabajo durante las Pasadas 1 y 2, después de lo cual los archivos se escriben en un orden estricto de abajo hacia arriba:

   • Paso A: Habilidades preinstaladas (.agents/skills/record-observation/, sync-architecture/ y ground-meta-project/) y scripts de automatización (scripts/check_boundaries.py, scripts/compact_memory.py si es una configuración de repositorio compartido).
   • Paso B: Fragmentos de conocimiento (observations.md -> boundaries.md -> weak_spots.md -> architecture.md).
   • Paso C: Pasaporte raíz (AGENTS.md) — estrictamente al final, como el agregador de referencias a fragmentos y habilidades de pila.

---

Finalización y Verificación

1. Verifique los archivos creados/actualizados usando Get-ChildItem -Recurse .agents o ls -R .agents.
2. Opción de Superposición Local Invisible: Si se inicializa en un proyecto externo/de cliente o si se solicita modo personal sin commits de Git:
   • Agregue AGENTS.md y .agents/ a .git/info/exclude en el repositorio de destino.
   • Verifique git status: los archivos del meta-proyecto no deben aparecer en los archivos no rastreados.
3. Genere un resumen conciso para el usuario:
   • Modo de ejecución (configuración inicial versus auditoría con actualización; superposición compartida versus invisible).
   • Árbol de archivos creados/actualizados.
   • Orientaciones del proyecto capturadas (North Stars).
   • Lista de habilidades de pila vinculadas.

---

Plantillas de Referencia Incrustadas

Plantilla: record-observation/SKILL.md

---
name: record-observation
description: >-
  Use esta habilidad para registrar un error no documentado, peculiaridad del entorno, caso límite de ejecución
  o solución no obvia en la tabla `.agents/project_knowledge/observations.md` del repositorio.
---

# Registrar Observación en la Base de Conocimiento del Repositorio

1. Verifique que exista `.agents/project_knowledge/observations.md`.
2. Revise las últimas 20 filas en busca de duplicados.
3. Agregue la entrada estrictamente como una sola línea de tabla Markdown:
   `| YYYY-MM-DD | [<categoría>] | <Ruta_o_componente> | <Resumen breve del problema/hecho> | <Solución o alternativa> |`
   Categorías: `[build]`, `[runtime]`, `[deps]`, `[db]`, `[api]`, `[test]`, `[env]`, `[ci]`, `[boundaries]`, `[orchestration]`, `[decommission]`, `[incident]`, `[init]`, o etiqueta de dominio explícita (ej. `[theme]`).
4. Si el recuento de filas supera 30–40, archive los registros resueltos en `.agents/project_knowledge/archive/observations-YYYY.md`.

Plantilla: sync-architecture/SKILL.md

---
name: sync-architecture
description: >-
  Use esta habilidad para analizar los módulos, dependencias y puntos de entrada del repositorio,
  y generar o actualizar `.agents/project_knowledge/architecture.md`.
---

# Sincronizar el Fragmento de Arquitectura del Proyecto

1. Lea los manifiestos de dependencias y compilación.
2. Identifique los puntos de entrada y directorios de nivel superior.
3. Identifique 3–5 subsistemas, sus roles y flujos de datos.
4. Actualice `.agents/project_knowledge/architecture.md`.
5. Muestre un breve resumen de los cambios al usuario.

Plantilla: ground-meta-project/SKILL.md

---
name: ground-meta-project
description: >-
  Habilidad de emergencia para poner a tierra y recalibrar: detiene ediciones descontroladas, fuerza un alejamiento,
  relee AGENTS.md, el pasaporte de rol activo, boundaries.md y el mapa de arquitectura, diagnostica la desviación de contexto y restablece la edad...

...

[truncado para traducción]