workspace/core/orchestration/directivas/DIRECTIVA-SUBAGENTES-ORQUESTACION.md

DIRECTIVA: Orquestacion de Subagentes

Version: 1.0 Fecha: 2025-12-12 Origen: Leccion aprendida Sprint 0 P0 Bloques 5-6

---

PROPOSITO

Guia para la orquestacion efectiva de subagentes en tareas paralelas, considerando limitaciones de contexto y configuracion apropiada.

---

PRINCIPIOS

1. Limites de Contexto

Los subagentes tienen un limite de contexto que debe respetarse:

consideraciones:
  - Cada subagente recibe contexto inicial + prompt + referencias
  - Evitar enviar demasiados archivos de referencia
  - Preferir referencias a paths en lugar de contenido inline
  - Dividir tareas grandes en subtareas mas pequenas

2. Configuracion de Prompts

Los prompts para subagentes deben ser:

estructura_prompt:
  - Objetivo claro y especifico (1-2 oraciones)
  - Contexto minimo necesario (solo lo esencial)
  - Referencias a archivos (paths, no contenido)
  - Criterios de completitud
  - Formato de output esperado

ejemplo_bueno: |
  Objetivo: Crear tests para AuthService en gamilit.
  Contexto: NestJS backend con Jest.
  Referencia: ~/workspace/projects/gamilit/apps/backend/src/modules/auth/
  Output: Archivos .spec.ts con minimo 20 test cases.  

ejemplo_malo: |
  [Incluir aqui todo el contenido del archivo auth.service.ts]
  [Incluir aqui todo el contenido del archivo base.service.ts]
  [... mas archivos inline...]
  Crea tests para todo esto.  

3. Granularidad de Tareas

recomendaciones:
  - 1 subagente = 1 tarea especifica
  - Maximo 4-6 subagentes en paralelo
  - Cada tarea debe poder completarse en contexto limitado

division_recomendada:
  - Por proyecto (gamilit, trading, erp-suite)
  - Por modulo (auth, progress, gamification)
  - Por tipo de artefacto (tests, servicios, controllers)

evitar:
  - Un subagente para "todos los tests de todos los proyectos"
  - Prompts con mas de 2000 tokens de contexto inline

4. Monitoreo de Errores

errores_comunes:
  context_overflow:
    causa: Demasiado contexto en prompt
    solucion: Reducir referencias, usar paths

  incomplete_output:
    causa: Tarea muy amplia
    solucion: Dividir en subtareas

  dependency_failure:
    causa: Subagente depende de resultado de otro
    solucion: Ejecutar secuencialmente, no en paralelo

---

PATRON DE USO

// Ejemplo de orquestacion apropiada
const tareas = [
  {
    nombre: "P0-008: Tests gamilit",
    prompt: `
      Objetivo: Crear infraestructura de tests para gamilit backend.
      Path: ~/workspace/projects/gamilit/apps/backend/
      Archivos a crear:
        - __tests__/setup.ts
        - __mocks__/repositories.mock.ts
        - modules/auth/services/__tests__/auth.service.spec.ts
      Output: Lista de archivos creados con rutas completas.
    `,
    modelo: "sonnet", // Usar modelo apropiado
    contexto_estimado: "bajo" // 500-1000 tokens
  },
  // ... mas tareas similares
];

// Ejecutar en paralelo solo si son independientes
await Promise.all(tareas.map(t => ejecutarSubagente(t)));

---

INTEGRACION CON PERFILES

Esta directiva debe incluirse en todos los perfiles tecnicos:

• Architecture-Analyst
• Full-Stack Developer
• Backend Specialist
• QA Engineer

Referencia en perfil:

directivas:
  - @SUBAGENTES_ORQUESTACION: directivas/DIRECTIVA-SUBAGENTES-ORQUESTACION.md

---

METRICAS DE EXITO

Metrica	Objetivo
Errores de contexto	< 5% de ejecuciones
Tareas completadas	> 95%
Tiempo promedio subagente	< 5 minutos

---

Autor: NEXUS-ARCHITECT Leccion aprendida de: Sprint 0 P0 Bloques 5-6