# GUÍA DE INVOCACIÓN DE SUBAGENTES

**Versión:** 1.0.0
**Fecha:** 2025-12-05
**Propósito:** Documentar el mecanismo de invocación automática de subagentes usando Task tool

---

## PRINCIPIO FUNDAMENTAL

```
┌─────────────────────────────────────────────────────────────────┐
│  AGENTE PRINCIPAL                                               │
│  (ej: Database-Agent trabajando en GAMILIT)                     │
│                                                                 │
│  Tiene contexto:                                                │
│  - Prompt global leído                                          │
│  - Extensión de proyecto leída                                  │
│  - Variables resueltas                                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼ USA TASK TOOL
┌─────────────────────────────────────────────────────────────────┐
│  SUBAGENTE                                                      │
│  (ej: NEXUS-BACKEND)                                            │
│                                                                 │
│  Recibe en el prompt del Task:                                  │
│  1. Instrucción de leer prompts (global + extensión)            │
│  2. Variables del proyecto ya resueltas                         │
│  3. Tarea específica a ejecutar                                 │
│  4. Criterios de aceptación                                     │
└─────────────────────────────────────────────────────────────────┘
```

---

## MECANISMO DE INVOCACIÓN

### Uso del Task Tool

Para invocar un subagente, el agente principal usa el **Task tool** con `subagent_type: "general-purpose"`:

```markdown
Task tool parameters:
  description: "Ejecutar tarea de Backend-Agent"
  subagent_type: "general-purpose"
  prompt: |
    # CONTEXTO DE SUBAGENTE

    ## 1. IDENTIDAD
    Eres un subagente **Backend-Agent** trabajando en el proyecto **GAMILIT**.

    ## 2. PROMPTS A LEER (EN ORDEN)
    Lee estos archivos para obtener tus instrucciones completas:
    1. `core/orchestration/agents/PROMPT-BACKEND-AGENT.md` (prompt global)
    2. `projects/gamilit/orchestration/prompts/PROMPT-BACKEND-AGENT.md` (extensión proyecto)
    3. `core/orchestration/agents/PROMPT-SUBAGENTES.md` (protocolo de subagentes)

    ## 3. VARIABLES DEL PROYECTO (YA RESUELTAS)
    ```yaml
    PROJECT_NAME:    GAMILIT
    BACKEND_ROOT:    apps/backend
    BACKEND_SRC:     apps/backend/src
    DB_NAME:         gamilit_platform
    AUTH_SCHEMA:     auth_management
    ```

    ## 4. TAREA ESPECÍFICA
    [Descripción detallada de la tarea]

    ## 5. CONTEXTO DE LA DELEGACIÓN
    - Agente principal: Database-Agent
    - Tarea principal: DB-042 - Crear módulo de Gamificación
    - Razón de delegación: Se creó tabla, ahora se necesita Entity

    ## 6. ARCHIVOS DE REFERENCIA
    - DDL creado: apps/database/ddl/schemas/gamification_system/tables/01-badges.sql
    - Inventario: orchestration/inventarios/MASTER_INVENTORY.yml

    ## 7. CRITERIOS DE ACEPTACIÓN
    - [ ] Entity creada y alineada con DDL
    - [ ] Service con operaciones CRUD
    - [ ] Controller con endpoints REST
    - [ ] npm run build pasa sin errores
    - [ ] Inventario actualizado

    ## 8. FORMATO DE REPORTE
    Al finalizar, reporta:
    - Archivos creados/modificados
    - Validaciones ejecutadas
    - Problemas encontrados (si hay)
    - Estado: COMPLETADO | ERROR | BLOQUEADO
```

---

## TEMPLATES DE INVOCACIÓN POR TIPO DE SUBAGENTE

### Template: Database-Agent → Backend-Agent

```markdown
Task tool:
  description: "Backend-Agent: Crear Entity para {tabla}"
  subagent_type: "general-purpose"
  prompt: |
    # SUBAGENTE: Backend-Agent

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

    ## PROMPTS A LEER
    1. `core/orchestration/agents/PROMPT-BACKEND-AGENT.md`
    2. `projects/{project}/orchestration/prompts/PROMPT-BACKEND-AGENT.md`
    3. `core/orchestration/agents/PROMPT-SUBAGENTES.md`

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

    ## TAREA
    Crear Entity, Service y Controller para la tabla `{schema}.{tabla}`.

    ## REFERENCIA DDL
    Archivo: `{DB_DDL_PATH}/schemas/{schema}/tables/{archivo}.sql`

    La Entity DEBE estar 100% alineada con el DDL (columnas, tipos, constraints).

    ## CRITERIOS DE ACEPTACIÓN
    - [ ] {Tabla}Entity.ts creado en {BACKEND_SRC}/modules/{modulo}/entities/
    - [ ] {Tabla}Service.ts con CRUD completo
    - [ ] {Tabla}Controller.ts con endpoints REST + Swagger
    - [ ] npm run build pasa
    - [ ] MASTER_INVENTORY.yml actualizado

    ## REPORTE ESPERADO
    Reporta: archivos creados, validaciones, estado final.
```

### Template: Backend-Agent → Frontend-Agent

```markdown
Task tool:
  description: "Frontend-Agent: Crear componentes para {modulo}"
  subagent_type: "general-purpose"
  prompt: |
    # SUBAGENTE: Frontend-Agent

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

    ## PROMPTS A LEER
    1. `core/orchestration/agents/PROMPT-FRONTEND-AGENT.md`
    2. `projects/{project}/orchestration/prompts/PROMPT-FRONTEND-AGENT.md`
    3. `core/orchestration/agents/PROMPT-SUBAGENTES.md`

    ## VARIABLES RESUELTAS
    ```yaml
    FRONTEND_ROOT:   {valor}
    FRONTEND_SRC:    {valor}
    API_URL:         {valor}
    ```

    ## TAREA
    Crear componentes para consumir API de {modulo}.

    ## ENDPOINTS DISPONIBLES
    ```
    GET    /api/{modulo}      → Lista todos
    GET    /api/{modulo}/:id  → Obtiene uno
    POST   /api/{modulo}      → Crea nuevo
    PATCH  /api/{modulo}/:id  → Actualiza
    DELETE /api/{modulo}/:id  → Elimina
    ```

    ## TIPOS ESPERADOS (del backend)
    ```typescript
    interface {Entity} {
      id: string;
      // ... campos del DTO
    }
    ```

    ## CRITERIOS DE ACEPTACIÓN
    - [ ] Type creado en shared/types/
    - [ ] API service creado en shared/services/api/
    - [ ] Componentes/páginas creados
    - [ ] npm run build pasa
    - [ ] MASTER_INVENTORY.yml actualizado

    ## REPORTE ESPERADO
    Reporta: archivos creados, validaciones, estado final.
```

### Template: Cualquier Agente → Database-Agent

```markdown
Task tool:
  description: "Database-Agent: Crear tabla {tabla}"
  subagent_type: "general-purpose"
  prompt: |
    # SUBAGENTE: Database-Agent

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

    ## PROMPTS A LEER
    1. `core/orchestration/agents/PROMPT-DATABASE-AGENT.md`
    2. `projects/{project}/orchestration/prompts/PROMPT-DATABASE-AGENT.md`
    3. `core/orchestration/agents/PROMPT-SUBAGENTES.md`

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

    ## TAREA
    Crear tabla `{schema}.{tabla}` con las siguientes especificaciones:

    ### Columnas
    - id (UUID, PK)
    - {lista de columnas con tipos}
    - created_at, updated_at (TIMESTAMP)

    ### Índices
    - {lista de índices requeridos}

    ### Constraints
    - {FKs, CHECKs necesarios}

    ## CRITERIOS DE ACEPTACIÓN
    - [ ] DDL creado en {DB_DDL_PATH}/schemas/{schema}/tables/
    - [ ] Recreación completa exitosa (./{RECREATE_CMD})
    - [ ] MASTER_INVENTORY.yml actualizado
    - [ ] DATABASE_INVENTORY.yml actualizado

    ## REPORTE ESPERADO
    Reporta: archivo DDL creado, resultado de recreación, estado final.
```

---

## FLUJO COMPLETO DE DELEGACIÓN

```
┌────────────────────────────────────────────────────────────────────────┐
│ 1. AGENTE PRINCIPAL DETECTA NECESIDAD DE DELEGACIÓN                    │
│                                                                        │
│    Database-Agent: "Necesito que Backend cree la Entity"               │
└────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│ 2. AGENTE PRINCIPAL PREPARA CONTEXTO                                   │
│                                                                        │
│    - Identifica prompts que debe leer el subagente                     │
│    - Resuelve variables del proyecto                                   │
│    - Define tarea específica                                           │
│    - Establece criterios de aceptación                                 │
└────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│ 3. AGENTE PRINCIPAL USA TASK TOOL                                      │
│                                                                        │
│    Task(                                                               │
│      description: "Backend-Agent: Crear BadgeEntity",                  │
│      subagent_type: "general-purpose",                                 │
│      prompt: "# SUBAGENTE: Backend-Agent\n..."                         │
│    )                                                                   │
└────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│ 4. SUBAGENTE EJECUTA                                                   │
│                                                                        │
│    - Lee prompts indicados                                             │
│    - Usa variables resueltas                                           │
│    - Sigue protocolo de PROMPT-SUBAGENTES.md                           │
│    - Ejecuta tarea                                                     │
│    - Valida resultado                                                  │
│    - Genera reporte                                                    │
└────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│ 5. SUBAGENTE RETORNA REPORTE                                           │
│                                                                        │
│    {                                                                   │
│      "estado": "COMPLETADO",                                           │
│      "archivos_creados": [...],                                        │
│      "validaciones": {...},                                            │
│      "siguiente_paso": "..."                                           │
│    }                                                                   │
└────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│ 6. AGENTE PRINCIPAL PROCESA RESULTADO                                  │
│                                                                        │
│    - Valida que se cumplieron criterios                                │
│    - Actualiza traza con resultado                                     │
│    - Continúa con siguiente paso o delega otra tarea                   │
└────────────────────────────────────────────────────────────────────────┘
```

---

## REGLAS DE INVOCACIÓN

### SIEMPRE incluir en el prompt del Task:

1. **Identidad del subagente** - Qué tipo de agente es
2. **Proyecto** - Nombre y working directory
3. **Prompts a leer** - Lista ordenada (global → extensión → subagentes)
4. **Variables resueltas** - Ya con valores concretos
5. **Tarea específica** - Clara y detallada
6. **Archivos de referencia** - DDLs, DTOs, etc.
7. **Criterios de aceptación** - Checklist verificable
8. **Formato de reporte** - Qué información retornar

### NUNCA hacer:

1. **NO** invocar sin especificar prompts a leer
2. **NO** dejar variables sin resolver (con placeholders)
3. **NO** dar tareas vagas o ambiguas
4. **NO** omitir criterios de aceptación
5. **NO** olvidar pedir reporte de resultado

---

## EJEMPLO COMPLETO

### Escenario: Database-Agent necesita que Backend cree Entity

```markdown
# En el contexto de Database-Agent trabajando en GAMILIT

He creado la tabla `gamification_system.badges`. Ahora necesito
que Backend-Agent cree la Entity correspondiente.

## Invocación:

Task tool:
  description: "Backend-Agent: Crear BadgeEntity para GAMILIT"
  subagent_type: "general-purpose"
  prompt: |
    # SUBAGENTE: Backend-Agent

    ## PROYECTO
    **Nombre:** GAMILIT
    **Working directory:** ~/workspace/projects/gamilit

    ## PROMPTS A LEER (EN ORDEN)
    1. `core/orchestration/agents/PROMPT-BACKEND-AGENT.md`
    2. `projects/gamilit/orchestration/prompts/PROMPT-BACKEND-AGENT.md`
    3. `core/orchestration/agents/PROMPT-SUBAGENTES.md`

    ## VARIABLES DEL PROYECTO
    ```yaml
    PROJECT_NAME:    GAMILIT
    BACKEND_ROOT:    apps/backend
    BACKEND_SRC:     apps/backend/src
    BACKEND_TESTS:   apps/backend/tests
    DB_NAME:         gamilit_platform
    AUTH_SCHEMA:     auth_management
    ```

    ## TAREA
    Crear Entity, Service y Controller para la tabla `gamification_system.badges`.

    ## REFERENCIA DDL
    ```sql
    -- Archivo: apps/database/ddl/schemas/gamification_system/tables/01-badges.sql
    CREATE TABLE gamification_system.badges (
        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
        name VARCHAR(100) NOT NULL,
        description TEXT,
        icon_url VARCHAR(500),
        xp_required INTEGER NOT NULL DEFAULT 0,
        badge_type VARCHAR(50) NOT NULL,
        is_active BOOLEAN NOT NULL DEFAULT true,
        created_at TIMESTAMP NOT NULL DEFAULT NOW(),
        updated_at TIMESTAMP NOT NULL DEFAULT NOW()
    );
    ```

    ## CRITERIOS DE ACEPTACIÓN
    - [ ] BadgeEntity.ts creado en apps/backend/src/modules/gamification/entities/
    - [ ] Entity alineada 100% con DDL (mismos campos, tipos compatibles)
    - [ ] BadgeService.ts con operaciones CRUD
    - [ ] BadgeController.ts con endpoints REST y Swagger decorators
    - [ ] CreateBadgeDto.ts y UpdateBadgeDto.ts
    - [ ] `npm run build` pasa sin errores
    - [ ] `npm run lint` pasa sin errores
    - [ ] MASTER_INVENTORY.yml actualizado

    ## REPORTE ESPERADO
    Al finalizar, reporta:
    1. Lista de archivos creados con rutas completas
    2. Resultado de `npm run build`
    3. Resultado de `npm run lint`
    4. Problemas encontrados (si hay)
    5. Estado final: COMPLETADO | ERROR | BLOQUEADO
```

---

## REGISTRO DE SUBAGENTES

El archivo `projects/{proyecto}/orchestration/estados/REGISTRO-SUBAGENTES.json`
debe actualizarse cuando se invocan subagentes:

```json
{
  "version": "2.0",
  "proyecto": "gamilit",
  "limite_maximo": 15,
  "activos": [
    {
      "id": "SUB-001",
      "tipo": "Backend-Agent",
      "tarea": "Crear BadgeEntity",
      "invocado_por": "Database-Agent",
      "estado": "en_progreso",
      "inicio": "2025-12-05T14:30:00Z"
    }
  ],
  "completados": [],
  "fallidos": []
}
```

---

## REFERENCIAS

- `core/orchestration/agents/PROMPT-SUBAGENTES.md` - Protocolo completo de subagentes
- `core/orchestration/HERENCIA-DIRECTIVAS-PROMPTS.md` - Sistema de herencia
- `projects/{proyecto}/orchestration/estados/REGISTRO-SUBAGENTES.json` - Estado de subagentes

---

**Versión:** 1.0.0
**Fecha:** 2025-12-05
**Mantenido por:** Tech Lead
