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
2. Perfiles de Agentes
3. Protocolo de Asignacion
4. Templates de Tareas
5. Flujo de Ejecucion
6. Validacion y Aceptacion
7. Actualizacion de Inventarios
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:

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

Comandos Frecuentes:

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:

archivos_obligatorios:
  - orchestration/inventarios/BACKEND_INVENTORY.yml
  - apps/backend/src/modules/{modulo}/
  - apps/backend/src/shared/

Comandos Frecuentes:

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:

archivos_obligatorios:
  - orchestration/inventarios/FRONTEND_INVENTORY.yml
  - apps/frontend/src/pages/
  - apps/frontend/src/shared/
  - apps/frontend/src/hooks/

Comandos Frecuentes:

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:

archivos_obligatorios:
  - apps/backend/package.json
  - apps/frontend/package.json
  - criterios_aceptacion del plan

Comandos Frecuentes:

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:

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:

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:

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

# 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

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

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

# 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

# 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

# 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