template-saas/orchestration/GUIA-ORQUESTACION-SUBAGENTES.md

# GUIA DE ORQUESTACION DE SUBAGENTES

**Proyecto:** template-saas
**Version:** 1.0.0
**Fecha:** 2026-01-10
**Autor:** Arquitecto de Soluciones / Tech Lead

---

## TABLA DE CONTENIDOS

1. [Introduccion](#1-introduccion)
2. [Perfiles de Agentes](#2-perfiles-de-agentes)
3. [Protocolo de Asignacion](#3-protocolo-de-asignacion)
4. [Templates de Tareas](#4-templates-de-tareas)
5. [Flujo de Ejecucion](#5-flujo-de-ejecucion)
6. [Validacion y Aceptacion](#6-validacion-y-aceptacion)
7. [Actualizacion de Inventarios](#7-actualizacion-de-inventarios)
8. [Ejemplos Practicos](#8-ejemplos-practicos)

---

## 1. INTRODUCCION

### 1.1 Proposito

Esta guia define el proceso para orquestar multiples subagentes de desarrollo en el proyecto template-saas, maximizando la eficiencia y manteniendo la coherencia del codigo.

### 1.2 Principios

1. **Contexto Completo**: Cada agente recibe toda la informacion necesaria
2. **Independencia**: Tareas paralelas no tienen dependencias entre si
3. **Validacion Continua**: Cada entrega es validada antes de continuar
4. **Trazabilidad**: Todo queda documentado en inventarios y trazas

### 1.3 Documentos de Referencia

| Documento | Proposito |
|-----------|-----------|
| `ANALISIS-MAESTRO-TEMPLATE-SAAS.md` | Estado actual y requerimientos |
| `planes/PLAN-SPRINT-{N}-*.md` | Plan detallado de cada sprint |
| `PROJECT-STATUS.md` | Estado general del proyecto |
| `PROXIMA-ACCION.md` | Siguiente tarea a ejecutar |
| `inventarios/*.yml` | Estado de cada capa |

---

## 2. PERFILES DE AGENTES

### 2.1 Database-Agent

**Responsabilidades:**
- Creacion y modificacion de DDL
- Implementacion de RLS policies
- Creacion de funciones y triggers
- Seeds de datos

**Contexto Requerido:**
```yaml
archivos_obligatorios:
  - orchestration/inventarios/DATABASE_INVENTORY.yml
  - apps/database/ddl/schemas/{schema}/
  - docs/00-vision-general/ARQUITECTURA-MULTI-TENANT.md
```

**Comandos Frecuentes:**
```bash
cd apps/database/scripts && ./drop-and-recreate-database.sh
psql -d template_saas_platform -f nuevo_archivo.sql
```

**Entregables Tipicos:**
- `apps/database/ddl/schemas/{schema}/tables/*.sql`
- `apps/database/ddl/schemas/{schema}/functions/*.sql`
- `apps/database/ddl/schemas/{schema}/rls-policies/*.sql`
- `apps/database/seeds/prod/*.sql`

---

### 2.2 Backend-Agent

**Responsabilidades:**
- Modulos NestJS (controller, service, module)
- DTOs y validaciones
- Tests unitarios
- Integraciones con servicios externos

**Contexto Requerido:**
```yaml
archivos_obligatorios:
  - orchestration/inventarios/BACKEND_INVENTORY.yml
  - apps/backend/src/modules/{modulo}/
  - apps/backend/src/shared/
```

**Comandos Frecuentes:**
```bash
cd apps/backend && npm run test
cd apps/backend && npm run test:cov
cd apps/backend && npm run lint
cd apps/backend && npm run build
```

**Entregables Tipicos:**
- `apps/backend/src/modules/{modulo}/{modulo}.controller.ts`
- `apps/backend/src/modules/{modulo}/{modulo}.service.ts`
- `apps/backend/src/modules/{modulo}/{modulo}.module.ts`
- `apps/backend/src/modules/{modulo}/dto/*.dto.ts`
- `apps/backend/src/modules/{modulo}/entities/*.entity.ts`
- `apps/backend/src/modules/{modulo}/__tests__/*.spec.ts`

---

### 2.3 Frontend-Agent

**Responsabilidades:**
- Componentes React
- Paginas y rutas
- Hooks personalizados
- Stores Zustand
- Tests de componentes

**Contexto Requerido:**
```yaml
archivos_obligatorios:
  - orchestration/inventarios/FRONTEND_INVENTORY.yml
  - apps/frontend/src/pages/
  - apps/frontend/src/shared/
  - apps/frontend/src/hooks/
```

**Comandos Frecuentes:**
```bash
cd apps/frontend && npm run dev
cd apps/frontend && npm run test
cd apps/frontend && npm run build
cd apps/frontend && npm run lint
```

**Entregables Tipicos:**
- `apps/frontend/src/pages/{pagina}Page.tsx`
- `apps/frontend/src/components/{componente}/{Componente}.tsx`
- `apps/frontend/src/hooks/use{Hook}.ts`
- `apps/frontend/src/stores/{store}.store.ts`
- `apps/frontend/src/__tests__/*.spec.tsx`

---

### 2.4 QA-Agent

**Responsabilidades:**
- Tests end-to-end (Playwright)
- Validacion de flujos completos
- Reporte de bugs
- Verificacion de criterios de aceptacion

**Contexto Requerido:**
```yaml
archivos_obligatorios:
  - apps/backend/package.json
  - apps/frontend/package.json
  - criterios_aceptacion del plan
```

**Comandos Frecuentes:**
```bash
cd apps/backend && npm run test:e2e
npx playwright test
npx playwright test --ui
```

**Entregables Tipicos:**
- `e2e/{flujo}.spec.ts`
- `e2e/fixtures/{fixture}.ts`
- Reportes de validacion

---

### 2.5 Docs-Agent

**Responsabilidades:**
- Documentacion tecnica
- ADRs (Architecture Decision Records)
- Guias de desarrollo
- Actualizacion de READMEs

**Contexto Requerido:**
```yaml
archivos_obligatorios:
  - docs/_MAP.md
  - docs/00-vision-general/
  - codigo implementado a documentar
```

**Entregables Tipicos:**
- `docs/01-modulos/SAAS-{NNN}-{modulo}.md`
- `docs/architecture/adr/ADR-{NNN}-{decision}.md`
- `docs/95-guias-desarrollo/{guia}.md`

---

### 2.6 DevOps-Agent

**Responsabilidades:**
- CI/CD pipelines
- Docker configurations
- Environment setup
- Deployment scripts

**Contexto Requerido:**
```yaml
archivos_obligatorios:
  - .github/workflows/
  - docker-compose.yml
  - Dockerfile
  - orchestration/inventarios/DEVENV-*.yml
```

**Entregables Tipicos:**
- `.github/workflows/{workflow}.yml`
- `Dockerfile`
- `docker-compose.yml`
- Scripts de deployment

---

## 3. PROTOCOLO DE ASIGNACION

### 3.1 Flujo de Asignacion

```
┌─────────────────────────────────────────────────────────────┐
│                     ORQUESTADOR                              │
├─────────────────────────────────────────────────────────────┤
│  1. Consultar ANALISIS-MAESTRO                              │
│  2. Seleccionar siguiente Sprint del backlog                │
│  3. Identificar tareas del Sprint                           │
│  4. Determinar dependencias entre tareas                    │
│  5. Agrupar tareas paralelas                                │
│  6. Asignar perfil de agente a cada tarea                   │
│  7. Preparar contexto para cada agente                      │
│  8. Ejecutar asignaciones                                   │
└─────────────────────────────────────────────────────────────┘
```

### 3.2 Determinacion de Paralelismo

**Tareas Paralelas (pueden ejecutarse simultaneamente):**
- No comparten archivos de escritura
- No hay dependencia de datos entre ellas
- Pertenecen a modulos diferentes

**Tareas Secuenciales (deben esperar):**
- Una tarea necesita el output de otra
- Modifican los mismos archivos
- Hay dependencia logica

### 3.3 Preparacion de Contexto

Para cada tarea, preparar:

```yaml
contexto_tarea:
  # Identificacion
  id: "TST-001"
  nombre: "Tests Auth Module Adicionales"
  sprint: "Sprint 1"
  sp: 2

  # Agente asignado
  agente: "Backend-Agent"

  # Archivos que DEBE leer antes de empezar
  archivos_leer:
    - "apps/backend/src/modules/auth/services/auth.service.ts"
    - "apps/backend/src/modules/auth/__tests__/auth.service.spec.ts"
    - "orchestration/inventarios/BACKEND_INVENTORY.yml"

  # Dependencias (tareas que deben completarse antes)
  dependencias: []

  # Archivos que debe crear/modificar
  entregables:
    - "apps/backend/src/modules/auth/__tests__/token.service.spec.ts"
    - "apps/backend/src/modules/auth/__tests__/oauth.service.spec.ts"

  # Criterios para considerar la tarea completada
  criterios_aceptacion:
    - "Todos los tests pasan"
    - "Cobertura modulo auth >= 85%"
    - "No hay tests flaky"

  # Comandos de validacion
  comandos_validacion:
    - "cd apps/backend && npm run test -- --testPathPattern=auth"
    - "cd apps/backend && npm run test:cov"
```

---

## 4. TEMPLATES DE TAREAS

### 4.1 Template: Tarea de Backend

```markdown
# TAREA: {ID}

## Informacion General
- **Agente:** Backend-Agent
- **Sprint:** {N}
- **SP:** {N}
- **Dependencias:** {lista o "Ninguna"}

## Contexto
Lee los siguientes archivos antes de comenzar:
- `{archivo1}`
- `{archivo2}`

Consulta el inventario:
- `orchestration/inventarios/BACKEND_INVENTORY.yml`

## Objetivo
{Descripcion clara del objetivo}

## Entregables
Crear/modificar los siguientes archivos:
1. `{ruta/archivo1.ts}`
2. `{ruta/archivo2.ts}`

## Especificacion Detallada

### {Archivo1}
{Descripcion de lo que debe contener}

### {Archivo2}
{Descripcion de lo que debe contener}

## Criterios de Aceptacion
- [ ] {Criterio 1}
- [ ] {Criterio 2}
- [ ] {Criterio 3}

## Validacion
Ejecutar estos comandos para validar:
```bash
{comando1}
{comando2}
```

## Post-Ejecucion
Actualizar:
- [ ] `orchestration/inventarios/BACKEND_INVENTORY.yml`
- [ ] `orchestration/trazas/TRAZA-TAREAS-BACKEND.md`
```

### 4.2 Template: Tarea de Frontend

```markdown
# TAREA: {ID}

## Informacion General
- **Agente:** Frontend-Agent
- **Sprint:** {N}
- **SP:** {N}
- **Dependencias:** {lista o "Ninguna"}

## Contexto
Lee los siguientes archivos antes de comenzar:
- `{archivo1}`
- `{archivo2}`

Revisa componentes existentes en:
- `apps/frontend/src/shared/components/`

## Objetivo
{Descripcion clara del objetivo}

## Entregables
1. `apps/frontend/src/pages/{Pagina}Page.tsx`
2. `apps/frontend/src/hooks/use{Hook}.ts`

## Especificacion de UI

### Layout
{Descripcion del layout}

### Componentes
- **{Componente1}:** {descripcion}
- **{Componente2}:** {descripcion}

### Estados
- Loading
- Error
- Empty
- Success

## Criterios de Aceptacion
- [ ] {Criterio 1}
- [ ] {Criterio 2}

## Validacion
```bash
cd apps/frontend && npm run build
cd apps/frontend && npm run lint
```
```

### 4.3 Template: Tarea de Database

```markdown
# TAREA: {ID}

## Informacion General
- **Agente:** Database-Agent
- **Sprint:** {N}
- **SP:** {N}
- **Dependencias:** {lista o "Ninguna"}

## Contexto
Revisar schema existente:
- `apps/database/ddl/schemas/{schema}/`

Consultar arquitectura:
- `docs/00-vision-general/ARQUITECTURA-MULTI-TENANT.md`

## Objetivo
{Descripcion clara del objetivo}

## Entregables
1. `apps/database/ddl/schemas/{schema}/tables/{tabla}.sql`
2. `apps/database/ddl/schemas/{schema}/rls-policies/{policy}.sql`

## Especificacion DDL

### Tabla: {nombre}
```sql
CREATE TABLE {schema}.{nombre} (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants.tenants(id),
    -- columnas
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);
```

### RLS Policy
```sql
ALTER TABLE {schema}.{nombre} ENABLE ROW LEVEL SECURITY;

CREATE POLICY "{nombre}_tenant_isolation" ON {schema}.{nombre}
    USING (tenant_id = current_setting('app.current_tenant_id')::UUID);
```

## Criterios de Aceptacion
- [ ] Script ejecuta sin errores
- [ ] RLS policy activa
- [ ] Indices creados

## Validacion
```bash
cd apps/database/scripts && ./drop-and-recreate-database.sh
psql -d template_saas_platform -c "\d {schema}.{nombre}"
```
```

---

## 5. FLUJO DE EJECUCION

### 5.1 Diagrama de Flujo

```
┌──────────────────────────────────────────────────────────────────┐
│                    INICIO DE SPRINT                               │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌────────────────┐                                              │
│  │  1. PLANIFICAR │                                              │
│  │  - Leer plan   │                                              │
│  │  - Identificar │                                              │
│  │    tareas      │                                              │
│  └───────┬────────┘                                              │
│          │                                                        │
│          ▼                                                        │
│  ┌────────────────────────────────────────────────────────┐      │
│  │  2. ASIGNAR TAREAS PARALELAS                           │      │
│  │                                                         │      │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │      │
│  │  │ Tarea 1 │  │ Tarea 2 │  │ Tarea 3 │  │ Tarea 4 │   │      │
│  │  │ Agent A │  │ Agent B │  │ Agent A │  │ Agent B │   │      │
│  │  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘   │      │
│  │       │            │            │            │         │      │
│  │       └────────────┴────────────┴────────────┘         │      │
│  │                         │                               │      │
│  └─────────────────────────┼───────────────────────────────┘      │
│                            │                                      │
│                            ▼                                      │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │  3. VALIDAR ENTREGABLES                                  │     │
│  │  - Ejecutar tests                                        │     │
│  │  - Verificar criterios                                   │     │
│  │  - Review de codigo                                      │     │
│  └────────────────────────┬────────────────────────────────┘     │
│                           │                                       │
│            ┌──────────────┴──────────────┐                       │
│            │                             │                        │
│            ▼                             ▼                        │
│     ┌────────────┐               ┌────────────┐                  │
│     │   PASA     │               │  NO PASA   │                  │
│     └──────┬─────┘               └──────┬─────┘                  │
│            │                            │                         │
│            ▼                            ▼                         │
│  ┌──────────────────┐         ┌──────────────────┐               │
│  │ 4. ACTUALIZAR    │         │ 4b. CORREGIR     │               │
│  │    INVENTARIOS   │         │     (loop)       │               │
│  └────────┬─────────┘         └──────────────────┘               │
│           │                                                       │
│           ▼                                                       │
│  ┌──────────────────┐                                            │
│  │ 5. SIGUIENTE     │                                            │
│  │    SPRINT        │                                            │
│  └──────────────────┘                                            │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘
```

### 5.2 Secuencia de Comandos

```bash
# 1. Antes de asignar tareas
cd /home/isem/workspace-v1/projects/template-saas

# 2. Verificar estado actual
cat orchestration/PROJECT-STATUS.md
cat orchestration/PROXIMA-ACCION.md

# 3. Leer plan del sprint
cat orchestration/planes/PLAN-SPRINT-{N}-*.md

# 4. Ejecutar tareas (por cada agente)
# ... asignar tareas segun templates ...

# 5. Validar resultados
cd apps/backend && npm run test
cd apps/frontend && npm run build

# 6. Actualizar inventarios
# ... actualizar archivos YML ...

# 7. Actualizar status
# ... actualizar PROJECT-STATUS.md ...
```

---

## 6. VALIDACION Y ACEPTACION

### 6.1 Checklist de Validacion por Capa

#### Backend
- [ ] `npm run lint` pasa sin errores
- [ ] `npm run build` compila exitosamente
- [ ] `npm run test` todos los tests pasan
- [ ] Coverage >= objetivo (usualmente 80%)
- [ ] No hay warnings de TypeScript

#### Frontend
- [ ] `npm run lint` pasa sin errores
- [ ] `npm run build` compila exitosamente
- [ ] `npm run test` todos los tests pasan
- [ ] No hay errores de consola en navegador

#### Database
- [ ] Script DDL ejecuta sin errores
- [ ] `drop-and-recreate-database.sh` exitoso
- [ ] RLS policies creadas y activas
- [ ] Seeds ejecutan correctamente

### 6.2 Criterios de Aceptacion Globales

1. **Funcionalidad**: El codigo hace lo que se espera
2. **Tests**: Coverage cumple objetivo
3. **Calidad**: Sin errores de lint ni warnings
4. **Documentacion**: Inventarios actualizados
5. **Integracion**: No rompe funcionalidad existente

---

## 7. ACTUALIZACION DE INVENTARIOS

### 7.1 Inventarios a Actualizar

Despues de cada tarea completada:

| Inventario | Cuando Actualizar |
|------------|-------------------|
| `DATABASE_INVENTORY.yml` | Nueva tabla/funcion/policy |
| `BACKEND_INVENTORY.yml` | Nuevo modulo/servicio/test |
| `FRONTEND_INVENTORY.yml` | Nueva pagina/componente/hook |
| `MASTER_INVENTORY.yml` | Cambio de estado de modulo |
| `PROJECT-STATUS.md` | Fin de sprint |
| `PROXIMA-ACCION.md` | Cada tarea completada |

### 7.2 Formato de Actualizacion

```yaml
# Ejemplo: Actualizar BACKEND_INVENTORY.yml

# Antes
modulos:
  - nombre: "auth"
    estado: "completado"
    tests: 45

# Despues
modulos:
  - nombre: "auth"
    estado: "completado"
    tests: 65  # +20 tests nuevos
```

### 7.3 Actualizacion de Trazas

```markdown
# orchestration/trazas/TRAZA-TAREAS-BACKEND.md

## Sprint 1

### TST-001: Tests Auth Module Adicionales
- **Fecha:** 2026-01-10
- **Agente:** Backend-Agent
- **Estado:** COMPLETADO
- **Entregables:**
  - apps/backend/src/modules/auth/__tests__/token.service.spec.ts
  - apps/backend/src/modules/auth/__tests__/oauth.service.spec.ts
- **Metricas:**
  - Tests nuevos: 20
  - Coverage auth: 70% -> 85%
```

---

## 8. EJEMPLOS PRACTICOS

### 8.1 Ejemplo: Asignacion de Sprint Completo

```markdown
# Sprint 1: Test Coverage

## Tareas Paralelas (Grupo 1)

### Agente Backend-Agent #1
Ejecutar TST-001 (Tests Auth)
- Leer: auth.service.ts, auth.service.spec.ts
- Crear: token.service.spec.ts, oauth.service.spec.ts, mfa.service.spec.ts
- Validar: npm run test -- --testPathPattern=auth

### Agente Backend-Agent #2
Ejecutar TST-002 (Tests Billing)
- Leer: billing.service.ts, subscription.service.ts
- Crear: stripe-webhooks.spec.ts, invoice.service.spec.ts
- Validar: npm run test -- --testPathPattern=billing

## Tareas Paralelas (Grupo 2)

### Agente Backend-Agent #1
Ejecutar TST-003 (Tests Notifications)
- Leer: notification-queue.service.ts, notifications.gateway.ts
- Crear: notification-queue.service.spec.ts, notifications.gateway.spec.ts
- Validar: npm run test -- --testPathPattern=notifications

### Agente Backend-Agent #2
Ejecutar TST-004 (Tests Storage)
- Leer: storage.service.ts, s3.service.ts
- Crear: s3.service.spec.ts, storage.controller.spec.ts
- Validar: npm run test -- --testPathPattern=storage

## Validacion Final

### QA-Agent
- Ejecutar: npm run test (todos los tests)
- Verificar: Coverage >= 80%
- Actualizar: PROJECT-STATUS.md
```

### 8.2 Ejemplo: Mensaje de Asignacion a Agente

```
TAREA: TST-001 - Tests Auth Module Adicionales

Agente: Backend-Agent
Sprint: 1
SP: 2

CONTEXTO:
Lee estos archivos antes de comenzar:
1. apps/backend/src/modules/auth/services/auth.service.ts
2. apps/backend/src/modules/auth/services/token.service.ts
3. apps/backend/src/modules/auth/services/oauth.service.ts
4. apps/backend/src/modules/auth/__tests__/auth.service.spec.ts (referencia)

OBJETIVO:
Crear tests unitarios adicionales para el modulo de autenticacion,
cubriendo token.service, oauth.service y mfa.service.

ENTREGABLES:
1. apps/backend/src/modules/auth/__tests__/token.service.spec.ts
2. apps/backend/src/modules/auth/__tests__/oauth.service.spec.ts
3. apps/backend/src/modules/auth/__tests__/mfa.service.spec.ts

CASOS DE TEST REQUERIDOS:
[Ver lista detallada en PLAN-SPRINT-1-TESTS.md seccion TST-001]

CRITERIOS DE ACEPTACION:
- Todos los tests pasan
- Cobertura modulo auth >= 85%
- No hay tests flaky
- Mocks correctamente implementados

VALIDACION:
cd apps/backend && npm run test -- --testPathPattern=auth
cd apps/backend && npm run test:cov

POST-EJECUCION:
Reportar:
- Numero de tests creados
- Coverage alcanzado
- Cualquier issue encontrado
```

---

## CONTROL DE VERSIONES

| Version | Fecha | Cambios |
|---------|-------|---------|
| 1.0.0 | 2026-01-10 | Version inicial |

---

**Creado:** 2026-01-10
**Sistema:** NEXUS v4.0 | SIMCO