workspace-v1/orchestration/directivas/simco/SIMCO-DELEGACION.md

SIMCO: DELEGACIÓN A SUBAGENTES

Versión: 1.2.0 Fecha: 2025-12-08 Aplica a: Agentes orquestadores que necesiten delegar tareas Prioridad: OBLIGATORIA para delegación Template: Ver templates/TEMPLATE-DELEGACION-SUBAGENTE.md para formato completo

---

RESUMEN EJECUTIVO

Delegar bien = contexto HEREDADO completo + criterios claros + validación al recibir. Un subagente sin contexto heredado = alucinaciones garantizadas. Un subagente con contexto heredado = ejecución precisa. ⚠️ Prompt muy grande = error de tokens. Desglosar primero.

---

PRINCIPIOS DE DELEGACIÓN

╔══════════════════════════════════════════════════════════════════════╗
║  1. CONTEXTO COMPLETO                                                 ║
║     El subagente NO tiene acceso a tu conversación anterior          ║
║     DEBES proporcionar TODO lo necesario en el prompt                ║
║                                                                       ║
║  2. ESPECIFICIDAD                                                     ║
║     Tareas vagas = resultados vagos                                  ║
║     Tareas específicas = resultados específicos                      ║
║                                                                       ║
║  3. CRITERIOS VERIFICABLES                                           ║
║     Si no puedes verificar, no puedes validar                        ║
║     Criterios de aceptación DEBEN ser checklist                      ║
║                                                                       ║
║  4. VALIDACIÓN OBLIGATORIA                                           ║
║     SIEMPRE valida el trabajo del subagente                          ║
║     NO asumas que está bien                                           ║
╚══════════════════════════════════════════════════════════════════════╝

---

CUÁNDO DELEGAR

SÍ Delegar

Situación	Delegar a
Crear tabla/schema DDL	Database-Agent
Crear entity/service/controller	Backend-Agent
Crear componente/página	Frontend-Agent
Tarea especializada fuera de tu dominio	Agente especializado
Tareas paralelizables independientes	Múltiples subagentes

NO Delegar

Situación	Razón
Validación final de tu trabajo	Tú eres responsable
Decisiones arquitectónicas	Requiere contexto completo
Tareas que requieren tu contexto de conversación	Subagente no lo tiene
Correcciones menores en tu código	Más rápido hacerlo tú
Tareas que dependen de resultado de otra	Hacerlas secuencialmente

---

ESTRUCTURA DE DELEGACIÓN

Template de Prompt para Subagente

# SUBAGENTE: {Tipo-Agente}

## PROYECTO
**Nombre:** {PROJECT_NAME}
**Working directory:** ~/workspace/projects/{proyecto}

## VERIFICAR CATÁLOGO PRIMERO (🆕 OBLIGATORIO)
**ANTES de implementar, verificar si existe en @CATALOG:**
- Consultar: `grep -i "{funcionalidad}" @CATALOG_INDEX`
- Si existe: Seguir `@REUTILIZAR` (SIMCO-REUTILIZAR.md)
- Funcionalidades catalogadas: auth, session, rate-limiting, notifications,
  multi-tenancy, feature-flags, websocket, payments

## PROMPTS A LEER (EN ORDEN)
1. `@CATALOG_INDEX` (verificar funcionalidades existentes)
2. `@SIMCO/SIMCO-CREAR.md` (o SIMCO relevante)
3. `@PERFILES/PERFIL-{TIPO}.md`
3. `@PROMPTS/PROMPT-{TIPO}-AGENT.md` (si necesita más detalle)

## VARIABLES DEL PROYECTO (RESUELTAS)
```yaml
PROJECT_NAME:    {valor concreto}
DB_NAME:         {valor concreto}
DB_DDL_PATH:     {valor concreto}
BACKEND_ROOT:    {valor concreto}
BACKEND_SRC:     {valor concreto}
FRONTEND_ROOT:   {valor concreto}
FRONTEND_SRC:    {valor concreto}
# ... todas las variables necesarias

TAREA

{Descripción clara y específica de qué debe hacer}

Objetivo

{Qué se debe lograr}

Especificaciones

{Detalles técnicos: columnas, tipos, estructura, etc.}

Ubicación de Archivos

• Crear en: {ruta exacta}
• Referencia: {archivo de referencia a consultar}

Restricciones

• ❌ NO hacer: {lista de prohibiciones}
• ✅ SÍ hacer: {lista de obligaciones}

ARCHIVOS DE REFERENCIA

• {ruta_1} - {propósito}
• {ruta_2} - {propósito}

CRITERIOS DE ACEPTACIÓN

• {criterio verificable 1}
• {criterio verificable 2}
• {criterio verificable 3}
• Build pasa sin errores
• Inventario actualizado
• Sin duplicados creados

VALIDACIONES REQUERIDAS

# Comandos que DEBE ejecutar antes de reportar
{comando 1}
{comando 2}

REPORTE ESPERADO

Al completar, el subagente debe reportar:

1. Archivos creados/modificados
2. Resultado de validaciones
3. Problemas encontrados (si hay)
4. Confirmación de criterios de aceptación

CONTEXTO ADICIONAL

{Información relevante que el subagente necesita saber}

---

## DELEGACIÓN POR TIPO

### A Database-Agent

```markdown
# SUBAGENTE: Database-Agent

## PROYECTO
**Nombre:** {PROJECT_NAME}
**Working directory:** ~/workspace/projects/{proyecto}

## PROMPTS A LEER
1. `@SIMCO/SIMCO-CREAR.md`
2. `@SIMCO/SIMCO-DDL.md`
3. `@PERFILES/PERFIL-DATABASE.md`

## VARIABLES RESUELTAS
```yaml
PROJECT_NAME:    {valor}
DB_NAME:         {valor}
DB_DDL_PATH:     {valor}
DB_SCRIPTS_PATH: {valor}
DB_SEEDS_PATH:   {valor}
RECREATE_CMD:    {valor}

TAREA

Crear tabla {schema}.{nombre_tabla} con las siguientes especificaciones:

Columnas

Columna	Tipo	Nullable	Default	Descripción
id	UUID	NO	gen_random_uuid()	PK
{col1}	{tipo}	{nullable}	{default}	{desc}

Índices

• idx_{tabla}_{col1} en ({col1})
• idx_{tabla}_{col2} en ({col2})

Constraints

• FK: {columna} → {tabla_ref}({columna_ref})
• CHECK: {condición}

Ubicación

{DB_DDL_PATH}/schemas/{schema}/tables/{NN}-{tabla}.sql

CRITERIOS DE ACEPTACIÓN

• Archivo DDL creado en ubicación correcta
• Todas las columnas según especificación
• Todos los índices creados
• Constraints correctos
• COMMENT ON incluidos
• Carga limpia exitosa: ./{RECREATE_CMD}
• @INVENTORY actualizado
• @TRAZA_DB actualizada

### A Backend-Agent

```markdown
# SUBAGENTE: Backend-Agent

## PROYECTO
**Nombre:** {PROJECT_NAME}
**Working directory:** ~/workspace/projects/{proyecto}

## VERIFICAR CATÁLOGO PRIMERO (🆕)
Si la tarea involucra: auth, session, rate-limiting, notifications,
multi-tenancy, feature-flags, websocket, payments
→ Consultar @CATALOG_INDEX y usar @REUTILIZAR si existe

## PROMPTS A LEER
1. `@CATALOG_INDEX` (verificar si existe funcionalidad)
2. `@SIMCO/SIMCO-CREAR.md`
3. `@SIMCO/SIMCO-BACKEND.md`
4. `@PERFILES/PERFIL-BACKEND.md`

## VARIABLES RESUELTAS
```yaml
PROJECT_NAME:    {valor}
BACKEND_ROOT:    {valor}
BACKEND_SRC:     {valor}
DB_NAME:         {valor}
AUTH_SCHEMA:     {valor}

TAREA

Crear Entity, Service y Controller para {nombre}:

Entity

• Mapear a: {schema}.{tabla}
• Archivo: {BACKEND_SRC}/modules/{modulo}/entities/{nombre}.entity.ts

DTOs

• CreateDto: {BACKEND_SRC}/modules/{modulo}/dto/create-{nombre}.dto.ts
• UpdateDto: {BACKEND_SRC}/modules/{modulo}/dto/update-{nombre}.dto.ts

Service

• CRUD básico
• Archivo: {BACKEND_SRC}/modules/{modulo}/services/{nombre}.service.ts

Controller

• Endpoints REST con Swagger
• Archivo: {BACKEND_SRC}/modules/{modulo}/controllers/{nombre}.controller.ts

CRITERIOS DE ACEPTACIÓN

• Entity alineada 100% con DDL
• DTOs con validaciones class-validator
• Service con lógica CRUD
• Controller con Swagger decorators
• JSDoc en todo código público
• npm run build pasa
• npm run lint pasa
• @INVENTORY actualizado
• @TRAZA_BE actualizada

### A Frontend-Agent

```markdown
# SUBAGENTE: Frontend-Agent

## PROYECTO
**Nombre:** {PROJECT_NAME}
**Working directory:** ~/workspace/projects/{proyecto}

## PROMPTS A LEER
1. `@SIMCO/SIMCO-CREAR.md`
2. `@SIMCO/SIMCO-FRONTEND.md`
3. `@PERFILES/PERFIL-FRONTEND.md`

## VARIABLES RESUELTAS
```yaml
PROJECT_NAME:    {valor}
FRONTEND_ROOT:   {valor}
FRONTEND_SRC:    {valor}
API_BASE_URL:    {valor}

TAREA

Crear componente/página para {nombre}:

Componente

• Nombre: {NombreComponente}
• Archivo: {FRONTEND_SRC}/apps/{app}/components/{Nombre}.tsx

Hook (si necesario)

• Nombre: use{Nombre}
• Archivo: {FRONTEND_SRC}/apps/{app}/hooks/use{Nombre}.ts

Tipos

• Archivo: {FRONTEND_SRC}/shared/types/{nombre}.types.ts

API Integration

• Endpoint: {endpoint}
• Método: {GET|POST|PUT|DELETE}

CRITERIOS DE ACEPTACIÓN

• Componente con props documentadas
• Hook con manejo de estados (loading, error)
• Types alineados con DTOs del backend
• TSDoc en funciones públicas
• npm run build pasa
• npm run lint pasa
• @INVENTORY actualizado
• @TRAZA_FE actualizada

---

## PARALELIZACIÓN

### Cuándo Paralelizar

```markdown
✅ PARALELIZABLE:
- Tareas en diferentes capas sin dependencia (tabla A + tabla B)
- Componentes independientes
- Tests independientes

❌ NO PARALELIZABLE:
- Entity depende de tabla → primero tabla
- Componente depende de hook → primero hook
- Service depende de entity → primero entity

Límites

Máximo subagentes paralelos: 5
Razón: Más allá es difícil coordinar y validar

---

⚠️ LÍMITES DE TOKENS (CRÍTICO)

Límites de Prompt de Delegación

PROMPT_DELEGACION:
  maximo_absoluto: 3,000 tokens (~12,000 caracteres)
  recomendado: 1,500 tokens (~6,000 caracteres)
  minimo_efectivo: 500 tokens (~2,000 caracteres)

TAREA_INDIVIDUAL:
  output_maximo: 2,000 tokens
  archivos_por_tarea: 1-2 máximo
  si_mas_archivos: "DESGLOSAR en subtareas"

Señales de Tarea Demasiado Grande

ALERTA_ROJA:
  - Tarea pide crear "módulo completo"
  - Tarea menciona >3 archivos a crear
  - Prompt de delegación >200 líneas
  - Se incluye código de referencia >50 líneas inline

ACCION:
  - DETENER delegación
  - Desglosar en subtareas
  - 1 subtarea = 1-2 archivos máximo

Template Optimizado (~800 tokens)

# PROMPT OPTIMIZADO PARA TOKENS

## SUBAGENTE: {Tipo}
Nivel: {nivel} | Proyecto: {proyecto}

## TAREA ÚNICA
{1-2 oraciones máximo}

## ESPECIFICACIÓN
{Máximo 10 líneas de detalles técnicos}

## REFERENCIA
- Copiar patrón de: `{ruta}` (líneas X-Y)

## CRITERIOS (máximo 5)
- [ ] {criterio 1}
- [ ] {criterio 2}
- [ ] {criterio 3}

## VALIDACIÓN
{1-2 comandos bash}

## ENTREGABLE
1. {archivo único a crear}

Desglose Obligatorio

# MAL - Tarea muy grande
"Crear módulo de usuarios con entity, service, controller, DTOs y tests"

# BIEN - Desglosado
ST-001: Crear UserEntity (1 archivo)
ST-002: Crear CreateUserDto y UpdateUserDto (2 archivos pequeños)
ST-003: Crear UserService con CRUD (1 archivo)
ST-004: Crear UserController (1 archivo)
ST-005: Ejecutar build + lint (validación)

Si Ocurre Error de Tokens

SINTOMAS:
  - Respuesta truncada
  - Error de context overflow
  - Subagente "olvida" parte de la tarea

SOLUCION:
  1. Dividir tarea en 2-3 subtareas más pequeñas
  2. Reducir contexto heredado (solo lo esencial)
  3. Usar referencias a archivos en lugar de incluir código
  4. Ejecutar subtareas secuencialmente

Referencia Completa

Ver: @PRINCIPIOS/PRINCIPIO-ECONOMIA-TOKENS.md

Template de Paralelización

# DELEGACIÓN PARALELA

## Subagente 1: Database-Agent
{contexto completo para crear tabla A}

## Subagente 2: Database-Agent
{contexto completo para crear tabla B}

## Subagente 3: Backend-Agent
{contexto completo para crear módulo X (independiente)}

## Sincronización
Esperar que todos completen antes de continuar con tareas dependientes.

---

RECEPCIÓN Y VALIDACIÓN

Al Recibir Resultado del Subagente

## Validación de Entrega - {SUBAGENTE-ID}

### Criterios de Aceptación
- [ ] {criterio 1}: ✅ Cumple | ❌ No cumple
- [ ] {criterio 2}: ✅ Cumple | ❌ No cumple
- [ ] {criterio 3}: ✅ Cumple | ❌ No cumple

### Verificación Técnica
- [ ] Archivos existen en ubicación correcta
- [ ] Build pasa
- [ ] Lint pasa
- [ ] Sin duplicados

### Coherencia
- [ ] Alineado con docs/
- [ ] Consistente con otras capas
- [ ] Convenciones seguidas

### Resultado
✅ ACEPTADO - Continuar
❌ RECHAZADO - Requiere corrección:
   - {problema 1}
   - {problema 2}

Si Hay Problemas

## Corrección Requerida - {SUBAGENTE-ID}

### Problemas Detectados
1. {problema 1}
2. {problema 2}

### Correcciones Necesarias
1. {corrección 1}
2. {corrección 2}

### Nueva Delegación o Corrección Propia
{Decidir si re-delegar o corregir directamente}

---

ERRORES COMUNES EN DELEGACIÓN

Error	Causa	Solución
Resultado incorrecto	Contexto incompleto	Proporcionar TODO el contexto
Ubicación incorrecta	No especificó ruta	Dar ruta EXACTA
Convenciones ignoradas	No incluyó referencias	Incluir prompts SIMCO
Variables sin resolver	Usó placeholders	Resolver TODAS las variables
Sin validación	Confió en el subagente	SIEMPRE validar resultado
Duplicados	No mencionó anti-duplicación	Incluir verificación @INVENTORY

---

CONTEXTO HEREDADO (CCA)

El Subagente DEBE Ejecutar CCA

Cada subagente debe ejecutar el protocolo de Carga de Contexto Automática antes de actuar:

instruccion_en_delegacion: |
  ANTES de actuar, ejecuta el protocolo CCA:
  1. Lee core/orchestration/directivas/simco/SIMCO-INICIALIZACION.md
  2. Sigue los pasos de carga de contexto
  3. Confirma "READY_TO_EXECUTE" antes de implementar  

Contexto que DEBES Heredar al Subagente

contexto_heredado_obligatorio:
  # Variables resueltas del proyecto
  variables:
    DB_NAME: "{valor concreto}"
    DB_DDL_PATH: "{valor concreto}"
    BACKEND_ROOT: "{valor concreto}"
    # ... todas las necesarias

  # Alias resueltos
  aliases:
    "@DDL": "{ruta completa}"
    "@BACKEND": "{ruta completa}"
    "@INVENTORY": "{ruta completa}"

  # Estado actual relevante
  estado:
    tablas_existentes: ["{lista}"]
    entities_existentes: ["{lista}"]
    endpoints_existentes: ["{lista}"]

  # Documentación de referencia
  docs:
    - path: "{ruta}"
      proposito: "{qué contiene}"

  # Código de referencia
  patrones:
    - path: "{ruta código similar}"
      usar_para: "{qué copiar}"

Template Completo de Delegación

Ver: templates/TEMPLATE-DELEGACION-SUBAGENTE.md

Este template incluye 8 bloques:

1. Identidad y Contexto
2. Contexto Heredado (variables, aliases, estado)
3. Directivas a Seguir
4. Tarea Específica
5. Dependencias
6. Criterios de Aceptación
7. Entregables
8. Restricciones

---

REFERENCIAS

• Template de delegación: templates/TEMPLATE-DELEGACION-SUBAGENTE.md
• Mapa de contexto: MAPA-CONTEXTO-AGENTE.md
• Inicialización CCA: directivas/simco/SIMCO-INICIALIZACION.md
• Perfiles de agentes: agents/perfiles/
• Directivas SIMCO: directivas/simco/
• Aliases: referencias/ALIASES.yml

---

Versión: 1.2.0 | Sistema: SIMCO + CCA + Tokens | Mantenido por: Tech Lead