vlv-code/manage-meta-project

Orquestación del Equipo de Agentes del Repositorio (Orquestación del Equipo del Meta-Proyecto)

Habilidad autónoma para componer, auditar y optimizar un equipo de agentes especializado adaptado al proyecto. La habilidad analiza la estructura del repositorio, identifica las especializaciones requeridas (Gestor de GitHub, DevOps, QA, UI/UX, Seguridad, Analista de Producto, Legal, Juez de Consenso, etc.), materializa perfiles aislados en .agents/team/ y establece protocolos de coordinación estrictos (supervisión humana, traspasos mediados por el usuario, notas inmutables, arbitraje basado en evidencia).

---

Cuándo invocar la habilidad

• El usuario solicita: "ensamblar equipo de agentes", "dotar el proyecto con roles", "configurar roles de agentes", "auditar actividad del equipo", "revisar roles del equipo", "actualizar composición del equipo de agentes".
• Se introducen nuevas capas tecnológicas importantes en el proyecto (Docker, CI/CD, interfaz móvil, base de datos, integraciones de pago externas) que requieren una gobernanza de dominio dedicada.

---

Pasos de ejecución

Fase 1: Escaneo Rápido del Repositorio (Inspección de Marcadores)

Antes de definir roles, el agente debe inspeccionar los marcadores clave del proyecto:

1. Infraestructura de Alojamiento y CI: Presencia de directorio .github/, flujos de trabajo, plantillas de pull request, plantillas de issue.
2. Licencias y Gobernanza de Código Abierto: Presencia de LICENSE, copyrights, CONTRIBUTING.md, manifiestos de dependencias.
3. Contenerización y Orquestación: Dockerfile, docker-compose*.yml, k8s/, helm/.
4. Infraestructura de Pruebas: Directorio tests/, pytest.ini, vitest.config.*, fixtures de prueba.
5. Seguridad y Datos Sensibles: Directorios auth/, security/, manejo de tokens, gestión de sesiones, lógica de cifrado.
6. Interfaz de Usuario y Diseño: Módulos frontend, HTML/CSS, diseños de teclado de bots, assets, tokens de diseño.
7. Pasaporte Actual del Proyecto: Lectura de AGENTS.md y fragmentos de .agents/project_knowledge/ (si ya está inicializado).
8. Stacks Secundarios / Políglotas: Subdirectorios que contienen archivos fuente de lenguajes compilados o alternativos (ej., .cpp, .c, .h, .rs, .go, .swift en client/, native/, core/, desktop/).

---

Fase 2: Dimensionamiento Adaptativo a la Escala y Matriz de Competencias Abierta

Antes de proponer roles, el agente debe evaluar la escala del repositorio y sintetizar un equipo mínimamente suficiente.

1. Dimensionamiento del Repositorio y Síntesis de Roles

El agente estima el volumen del código base (LOC, profundidad de carpetas, diversidad tecnológica):

• Repositorio Micro / Pequeño (<10k líneas, desarrollador en solitario, 1–2 stacks principales): Sintetizar 2–3 roles combinados agrupando bloques de competencias de la matriz en perfiles unificados.

  • Trío Compacto Canónico:
    1. agent-dev-lead: Combina análisis de entrada, descomposición de tareas e implementación general de código (agent-intake-dispatcher + agent-general-worker).
    2. agent-quality-guardian: Combina integridad del pasaporte/conocimiento, suites de pruebas unitarias y auditoría de código muerto (agent-meta-guardian + agent-qa-engineer + agent-deep-auditor).
    3. agent-github-steward: Higiene de Git, commits convencionales, paridad Código-README y CI/CD.

• Repositorio Mediano (10k–50k líneas, equipo pequeño, varios servicios): Desplegar 3–5 roles dedicados adaptados a componentes clave.

• Repositorio Grande / Empresarial (>50k líneas, monorepos, microservicios): Desplegar 6+ roles granulares con estricto aislamiento de responsabilidades.

• Regla de Aislamiento de Stack Políglota (Sin Paquetes Tóxicos): Prohibir estrictamente agrupar stacks secundarios compilados o especializados (C/C++, Rust, Go, GUI nativa) en agent-general-worker sin habilidades dedicadas. Cuando se detecte un stack políglota, sintetizar un rol dedicado (ej., agent-native-desktop con compiladores nativos y toolchains) o mapear explícitamente los directorios nativos a Zona Roja con un disparador de Handoff obligatorio.

• Regla de Despachador Obligatorio (Sin Caos Multi-Rol): Al desplegar 3 o más roles especializados, es estrictamente obligatorio desplegar un despachador de entrada (agent-intake-dispatcher o un despachador integrado en agent-dev-lead). Prohibir dejar al usuario con un conjunto de múltiples roles aislados sin un único punto de entrada.

2. Catálogo de Competencias Abiertas (Matriz de Roles)

[!IMPORTANT] La siguiente tabla es un Catálogo de Competencias Abiertas, no una enumeración cerrada e inmutable. Los agentes tienen plena autonomía para sintetizar roles combinados o inventar roles personalizados específicos del dominio (ej., agent-solana-smart-contracts, agent-3d-designer, agent-data-pipeline) que coincidan con la arquitectura real del repositorio.

Categoría	Bloque de Competencia / Rol	Marcadores del Repositorio	Habilidades Especializadas	Límites de Responsabilidad
Rol Base	agent-general-worker(Trabajador General / Generalista)	Cualquier proyecto (rol base fundamental)	clean-codecode-reviewersystematic-debugging + habilidades del stack	Verde: implementación de funcionalidades, scripts, pruebas, corrección de errores.Amarillo: modificar contratos de API y dependencias.Rojo: acciones destructivas y módulos de dominio especializados sin Handoff.
Orquestación	agent-intake-dispatcher(Despachador de Entrada)	Cualquier proyecto con 2+ roles	prompt-engineeringbrainstorming	Verde: descomposición de solicitudes, preparación de prompts, ejecución rápida.Rojo: modificación directa del código fuente del proyecto.
Orquestación	agent-meta-guardian(Guardián del Meta-Proyecto)	Presencia de estructura meta-project	clean-codecode-reviewer	Verde: auditoría del pasaporte, telemetría de roles, mantenimiento de la base de conocimiento.Amarillo: archivar roles inactivos.Rojo: eliminar la base de conocimiento sin confirmación del usuario.
Orquestación	agent-consensus-judge(Árbitro y Juez de Consenso)	Proyectos con decisiones en disputa	architecture-decision-recordsapi-design-principles	Verde: comparar argumentos, verificación empírica de pruebas.Amarillo: redactar ADRs.Rojo: tomar decisiones sin evidencia empírica.
Orquestación	agent-deep-auditor(Auditor Profundo de Todo el Repositorio)	Código base maduro (>500 líneas)	systematic-debuggingcode-reviewer	Verde: generar informes de auditoría, detección de código muerto, verificar integridad de enlaces/anclas.Amarillo: registrar hallazgos en observaciones.Rojo: refactorizaciones destructivas, eliminación autónoma de archivos.
Producto y Negocio	agent-product-roaster(Analista de Producto y Crítico)	Servicios de producto, startups	search_webbrainstorming	Verde: análisis competitivo, prueba de hipótesis bajo estrés.Rojo: cambiar la lógica de negocio sin especificaciones.
Producto y Negocio	agent-creative-director(Director Creativo)	Componentes UI, web, temas, iconos	image-generatorcss-tokens	Verde: generar paletas de colores, iconos, banners.Amarillo: editar estilos globales.Rojo: reemplazar la identidad de marca sin confirmación.
Producto y Negocio	agent-ui-ux-engineer(Ingeniero UI/UX)	Frontend, bots, interfaces	semantic-htmlcss-coderui-ux-invariants	Verde: diseño de componentes, estados FSM.Amarillo: cambios en la navegación de pantallas.Rojo: eliminar confirmaciones para acciones destructivas.
Producto y Negocio	agent-legal-compliance(Auditor Legal y de Cumplimiento)	LICENSE, repositorios públicos	Auditoría SPDX/SBOM	Verde: auditoría de licencias de dependencias.Amarillo: actualizar NOTICE y copyrights de encabezados.Rojo: cambiar la licencia del repositorio.
Ingeniería	agent-github-steward(Gurú de GitHub y Capitán de Lanzamientos)	.github/, remotos git	github-managementgithub-actions-creatorclean-codecode-reviewer	Verde: higiene de Git, commits convencionales, gestión de ramas, triaje de issues, borradores de lanzamientos.Amarillo: verificación de paridad Código-README (asegurar que las instrucciones/CLI del README coinciden con el código real), ajuste de CI/CD.Rojo: force-push, fusionar en main sin revisión, modificar secretos.
Ingeniería	agent-devops-infra(Arquitecto de Infraestructura)	Dockerfile, docker-compose*	docker-expertkubernetes-architectbash-linux	Verde: contenedores de desarrollo, linting de configuración.Amarillo: optimización de builds multi-etapa.Rojo: secretos de producción, .env*, k8s de producción.
Ingeniería	agent-qa-engineer(Ingeniero de Fiabilidad y QA)	tests/, frameworks de pruebas	test-driven-developmentverification-before-completion	Verde: escribir pruebas unitarias/de integración, verificar ejecuciones de pruebas.Amarillo: configurar ejecutores de pruebas y aserciones de contratos.Rojo: deshabilitar pruebas en CI.
Ingeniería	agent-tech-writer(Redactor Técnico)	docs/, OpenAPI, Swagger	mermaid-diagram-specialistopenapigoogle-style-guide	Verde: documentar funciones, README, diagramas.Amarillo: editar especificaciones de API.Rojo: publicar documentación no revisada.

---

Fase 3: Auditoría del Equipo Existente (Poda de Roles y Recolección de Basura)

Si el directorio .agents/team/ ya existe:

1. Escanear todas las carpetas: .agents/team/*/profile.md.
2. Inspeccionar la tabla Registro de Llamadas de Rol (Telemetría) en cada perfil.
3. Identificar roles inactivos u obsoletos:
   • El rol fue inicializado, pero el registro contiene solo la entrada inicial y no se han producido invocaciones reales durante >30 días.
   • El stack tecnológico subyacente del rol fue completamente eliminado del proyecto (ej., Docker fue dado de baja, pero agent-devops-infra permaneció).
4. Compilar una lista de candidatos para archivar en .agents/team/archive/<role_id>/.
5. Prohibición de eliminación autónoma: ¡Archivar roles requiere la aprobación explícita del usuario!

---

Fase 4: Diálogo y Alineación con el Usuario

Generar una propuesta de asesoramiento concisa para el usuario:

1. Marcadores detectados: Listar los componentes del proyecto identificados.
2. Roles recomendados para habilitar: Trabajador base (agent-general-worker) + 2–4 roles de dominio más críticos que coincidan con los marcadores detectados, con breves justificaciones.
3. Candidatos a archivar: (si existen roles inactivos).
4. Solicitud de aprobación: "¿Aprobar el aprovisionamiento de los siguientes roles: [...]?"

---

Fase 5: Materialización de Perfiles y Registro en el Pasaporte

Después de la confirmación del usuario, realizar la escritura de producción:

1. Crear directorios para cada rol aprobado: .agents/team/<role_id>/.
2. Scaffold de .agents/team/<role_id>/profile.md usando la plantilla de referencia templates/team/profile.md (o la plantilla incrustada a continuación):
   • Rellenar ID del rol, alcance, disparadores de invocación, habilidades activas y permisos de límite.
   • Inicializar la tabla de telemetría con la fecha actual.
3. Crear un archivo de notas privado: .agents/team/<role_id>/notes.md usando la plantilla de referencia templates/team/notes.md (o la plantilla incrustada a continuación).
4. Generar el prompt de sistema inicial listo para usar .agents/team/<role_id>/system_prompt.md usando templates/team/system_prompt.md (o la plantilla incrustada a continuación):
   • Rellenar nombre del rol, propósito, stack de habilidades y permisos de límite canónicos (Verde / Amarillo / Rojo).
5. Registrar roles en la raíz AGENTS.md bajo la sección:

   ## 6. Equipo de Agentes del Proyecto (.agents/team/)
   - [{{TÍTULO_DEL_ROL}}](.agents/team/{{ID_DEL_ROL}}/profile.md) — {{ALCANCE_DEL_ROL}} (invocado por: {{DISPARADORES_DEL_ROL}})
   

6. Generar y mostrar una tabla compacta de Inicio Rápido al usuario sin saturar el chat con texto largo de prompt:

   | Rol | Propósito | Ruta del Prompt de Sistema | Palabras Clave de Disparo |
   | :--- | :--- | :--- | :--- |
   | `agent-qa-engineer` | Pruebas y verificación | `.agents/team/agent-qa-engineer/system_prompt.md` | "ejecutar pruebas", "verificar validación" |
   

---

Fase 6: Reglas de Compromiso del Equipo

Cada agente del equipo debe adherirse a los principios básicos de coordinación:

1. Pasividad Impulsada por el Usuario: Los agentes nunca realizan acciones en segundo plano sin instrucciones explícitas del usuario.
2. Traspasos Mediados por el Usuario: Los agentes no transfieren el control directamente entre sí evitando al usuario. Si una tarea requiere otro dominio, el agente devuelve un paquete de traspaso estructurado al usuario:

   ### Paquete de Traspaso de Tarea: [agente-A -> agente-B]
   - Objetivo original: <lo que se solicitó>
   - Trabajo completado: <lista de archivos tocados>
   - Límite de traspaso: <por qué se detuvo el agente actual>
   - Prompt recomendado para agente-B: <texto del prompt listo para usar>
   

3. Límite de Cadena de Traspasos: Máximo de 2 traspasos consecutivos (saltos = 2). En el 3er paso, el control debe volver al humano.
4. Santidad de las Anotaciones de Archivos Compartidos: Prohibido editar las notas de otros en tasks.md, observations.md y architecture.md. Solo se puede actualizar el propio estado/tareas. En caso de conflicto, presentar una descripción clara del compromiso al usuario.
5. Propiedad Exclusiva de notes.md: Solo el propietario del rol puede modificar .agents/team/<rol>/notes.md.
6. Arbitraje Basado en Evidencia: agent-consensus-judge emite veredictos estrictamente basados en resultados de pruebas, mediciones de benchmark y especificaciones oficiales.
7. Delegación de Subagentes en Paralelo (dispatching-parallel-agents): Al manejar cargas de trabajo repetitivas, paralelas o de lotes en múltiples directorios (ej., migraciones de múltiples archivos, generación de múltiples suites de pruebas, linting/auditorías masivas), los agentes primarios DEBEN invocar la habilidad dispatching-parallel-agents. El agente padre particiona la carga de trabajo entre subagentes transitorios por directorios o tareas no superpuestas, transmitiendo las invariantes del proyecto de AGENTS.md y los límites de los roles. El padre coordina la finalización, ejecuta pruebas de integridad y devuelve un informe consolidado al usuario sin cargar al humano con traspasos de subagentes intermedios.
8. Interruptor de Circuito (Detener Trabajo en la 2da Iteración): Si una corrección de error requiere una 2da edición consecutiva en el mismo módulo o produce una regresión secundaria en código adyacente, cesar de escribir código. Alejar la vista, rastrear el ciclo de vida completo de los datos desde el origen hasta el consumidor, identificar la causa raíz arquitectónica y presentar un análisis sistémico antes de proponer cualquier nuevo diff.
9. Auditoría de Estado Objetivo: Antes de modificar módulos no triviales en zonas Amarillas o Rojas, determinar el estado objetivo único mediante verificación empírica (leer el estado actual del sistema, consultar salida de compilación, ejecutar pruebas existentes). No se debe asumir el estado actual basándose únicamente en la inspección del código fuente.

---

Variables de entorno

No se requieren variables de entorno para esta habilidad.

---

Archivos relevantes

• Archivos de rol: .agents/team/<role_id>/
• Pasaporte del proyecto: AGENTS.md, .agents/project_knowledge/
• Plantillas de referencia (rutas de ejemplo): templates/team/profile.md, templates/team/notes.md, templates/team/system_prompt.md