# 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:

```yaml
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:

```yaml
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

```yaml
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

```yaml
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

```typescript
// 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:
```yaml
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