workspace/orchestration/analisis/ANALISIS-ORQUESTACION-AGENTES-2025-12-08.md

ANALISIS DE ORQUESTACION DE AGENTES Y SUBAGENTES

Fecha: 2025-12-08 Version: 1.0.0 Sistema: SIMCO v2.2.0 + CAPVED Objetivo: Identificar puntos de mejora para claridad de trabajo entre agentes/subagentes

---

RESUMEN EJECUTIVO

El analisis exhaustivo del sistema de orquestacion revela un sistema bien estructurado conceptualmente pero con gaps criticos en la ejecucion que causan:

• Perdida de contexto entre niveles
• Ambiguedad en responsabilidades
• Falta de agentes especializados
• Propagacion incompleta de informacion

Impacto: Los subagentes pueden confundirse, duplicar trabajo, o perder trazabilidad.

---

1. HALLAZGOS CRITICOS

1.1 Agentes Faltantes en SIMCO

Agente	Estado	Impacto
Architecture-Analyst	Solo en Legacy	3 agentes lo referencian pero NO existe
Requirements-Analyst	Solo en Legacy	Fase A (Analisis) sin soporte especializado
Code-Reviewer	Solo en Legacy	Sin revision de calidad pre-merge
Bug-Fixer	Solo en Legacy	Sin flujo diferenciado para bugs
Feature-Developer	Solo en Legacy	Ambiguedad con Orquestador

Problema Critico: Los 4 agentes tecnicos (Database, Backend, Frontend, Orquestador) delegan a "Architecture-Analyst" para validar arquitectura, pero este perfil NO EXISTE en SIMCO.

1.2 Ambiguedad en Seleccion de Directivas

Pregunta sin respuesta clara:

Tarea: "Crear tabla notifications"

Camino A: SIMCO-TAREA → CAPVED completo → SIMCO-DDL
Camino B: Solo SIMCO-CREAR + SIMCO-DDL (salta CAPVED)

¿Cual es correcto? El sistema no lo especifica claramente.

1.3 Propagacion Rota en ERP Suite

Estado de Propagacion:
  erp-core:
    nivel_local: "70% - 30 specs sin inventariar"
    nivel_suite: "0% - SUITE_MASTER_INVENTORY.yml NO EXISTE"
    nivel_workspace: "Parcial"

  verticales:
    nivel_local: "Templates creados"
    nivel_suite: "Sin referencias"
    nivel_workspace: "Parcial"

Consecuencia: Trabajo de dias es INVISIBLE en niveles superiores.

1.4 Validacion Cross-Layer Ausente

DDL crea:     auth.users (7 columnas)
Entity crea:  UserEntity (6 columnas)  ← ERROR NO DETECTADO
DTO crea:     UserDto (6 campos)       ← ERROR PROPAGADO

¿Quien valida alineacion? NADIE esta asignado.

---

2. FORTALEZAS DEL SISTEMA

2.1 Lo que funciona bien

1. CAPVED - Ciclo de vida claro en 6 fases
2. CCA Protocol - Carga de contexto automatica bien definida
3. Sistema de Niveles - Jerarquia 0-3 clara
4. Separacion de Responsabilidades - Agentes saben que NO hacer
5. Sistema de Aliases - Navegacion consistente
6. Catalogo de Funcionalidades - Evita duplicacion (cuando se usa)
7. Economia de Tokens - Limites explicitos

2.2 Documentacion Solida

• 5 Principios fundamentales
• 10+ directivas SIMCO por operacion
• 4 perfiles de agentes completos
• Templates de delegacion detallados

---

3. GAPS IDENTIFICADOS

3.1 Gaps en Perfiles de Agentes

DEFINIDOS EN SIMCO (4):
  ✅ PERFIL-ORQUESTADOR.md
  ✅ PERFIL-DATABASE.md
  ✅ PERFIL-BACKEND.md
  ✅ PERFIL-FRONTEND.md

REFERENCIADOS PERO NO EXISTEN (5):
  ❌ Architecture-Analyst (CRITICO)
  ❌ Requirements-Analyst
  ❌ Code-Reviewer
  ❌ Bug-Fixer
  ❌ Feature-Developer

3.2 Gaps en CAPVED

Fase	Estado	Gap
C - Contexto	✅ OK	-
A - Analisis	⚠️ Parcial	Sin Requirements-Analyst
P - Planeacion	✅ OK	-
V - Validacion	❌ CRITICO	Sin Architecture-Analyst
E - Ejecucion	✅ OK	-
D - Documentacion	⚠️ Parcial	Sin Documentation-Validator

3.3 Gaps en Propagacion

Aspecto	Estado	Descripcion
SUITE_MASTER_INVENTORY.yml	❌ NO EXISTE	erp-suite sin inventario consolidado
Trazas a nivel Suite	❌ NO EXISTE	Sin directorio trazas/
HERENCIA-ERP-CORE.md	❌ NO EXISTE	Verticales sin documentar herencia
CONSUMIDORES.yml	❌ NO EXISTE	Catalogo sin rastrear uso

3.4 Gaps en Validacion

Validaciones sin responsable:
  - Alineacion DDL ↔ Entity
  - Alineacion Entity ↔ DTO
  - Alineacion Backend ↔ Frontend
  - Contrato API consistente
  - Especificacion vs Implementacion

---

4. AREAS DE CONFUSION PARA SUBAGENTES

4.1 Confusion #1: ¿SIMCO-TAREA o SIMCO-{OPERACION}?

Situacion: Subagente recibe "Crea tabla X"

Duda: ¿Ejecuto CAPVED completo (SIMCO-TAREA) o solo SIMCO-CREAR + SIMCO-DDL?

Solucion Propuesta: Crear SIMCO-DECISION-MATRIZ.md

4.2 Confusion #2: ¿Quien valida arquitectura?

Situacion: Backend-Agent necesita validar diseño de Entity

Instruccion actual: "Consultar con Architecture-Analyst"

Problema: Architecture-Analyst NO EXISTE en SIMCO

4.3 Confusion #3: ¿Variables resueltas o placeholders?

Template dice:

DB_NAME: "{valor}"

Duda: ¿Debo reemplazar "{valor}" o ya viene resuelto?

4.4 Confusion #4: ¿Propagar a donde?

Vertical crea tabla.

Duda: ¿Propago a Suite + Workspace? ¿O solo a Suite?

SIMCO-PROPAGACION dice: "PROPAGATE_TO: lista de niveles"

Pero: No especifica si es secuencial o paralelo.

4.5 Confusion #5: ¿Delegar o consultar?

Backend dice: "Si tabla NO existe → DELEGAR a Database"

Backend dice: "Si necesito validar → CONSULTAR con Architecture"

Duda: ¿Consultar = pedir opinion? ¿O requiere aprobacion?

4.6 Confusion #6: Scope Creep

Durante Fase P surge: "Tambien necesito endpoint de busqueda"

Duda: ¿Es scope creep (crear HU derivada) o detalle tecnico (continuar)?

Criterio: No esta definido claramente.

---

5. RECOMENDACIONES ESTRUCTURADAS

5.1 TIER 1: Critico (Implementar Inmediatamente)

R1. Crear PERFIL-ARCHITECTURE-ANALYST.md

Ubicacion: core/orchestration/agents/perfiles/
Responsabilidades:
  - Validar alineacion DDL ↔ Entity ↔ DTO
  - Revisar decisiones arquitectonicas
  - Aprobar planes en Fase V
  - Detectar anti-patterns
Cuando se invoca:
  - Gate de Fase V (CAPVED)
  - Por solicitud de cualquier agente tecnico
  - Decisiones complejas

R2. Crear SIMCO-DECISION-MATRIZ.md

| Tipo de Trabajo | Primero | Luego |
|-----------------|---------|-------|
| HU que crea archivos | SIMCO-TAREA | SIMCO-CREAR |
| HU que modifica codigo | SIMCO-TAREA | SIMCO-MODIFICAR |
| Subtarea dentro de HU | Directamente | SIMCO-{operacion} |
| Exploracion/investigacion | SIMCO-BUSCAR | (no commit) |
| Validacion de entrega | SIMCO-VALIDAR | (gate) |

R3. Crear SIMCO-ALINEACION.md

## Protocolo de Alineacion Entre Capas

1. Database-Agent crea tabla
   - Documenta: nombre, columnas, tipos

2. Backend-Agent ANTES de crear Entity:
   - [ ] Verifica tabla existe
   - [ ] Campos iguales en numero
   - [ ] Tipos mapeados correctamente
   - [ ] Constraints reflejados

3. Frontend-Agent ANTES de crear Types:
   - [ ] DTOs tienen campos correctos
   - [ ] Optional fields coinciden

R4. Crear SUITE_MASTER_INVENTORY.yml

Ubicacion: projects/erp-suite/orchestration/inventarios/
Contenido:
  - Resumen consolidado de erp-core
  - Resumen de cada vertical
  - Estado de propagacion
  - Referencias a inventarios hijos

5.2 TIER 2: Alto (Implementar Esta Semana)

R5. Estandarizar Nombres de Inventarios

Antes (inconsistente):
  - MASTER_INVENTORY.yml (standalone)
  - SUITE_MASTER_INVENTORY.yml (suite)
  - VERTICAL_INVENTORY.yml (vertical)
  - CORE_INVENTORY.yml (core)

Despues (consistente):
  - MASTER_INVENTORY.yml (todos los niveles)
  - DATABASE_INVENTORY.yml (todos)
  - BACKEND_INVENTORY.yml (todos)
  - FRONTEND_INVENTORY.yml (todos)

R6. Crear Protocolo de Scope Creep

## Clasificacion de Scope Creep

CONTINUAR EN MISMA HU:
  - Detalle tecnico no mencionado pero necesario
  - Mejora detectada durante analisis

CREAR HU DERIVADA:
  - Funcionalidad completamente nueva
  - Integracion con sistema distinto
  - Change request de usuario

REGLA: Si lo planeaste en P y encontraste en A = NO es scope creep

R7. Agregar Timestamps a Estado Heredado

# En delegaciones
contexto_heredado:
  timestamp: "2025-12-08 14:30 UTC"
  valido_hasta: "2025-12-08 15:30 UTC"

  tablas_existentes:
    - auth.users (creada 14:15)
    - auth.roles (creada 14:20)

5.3 TIER 3: Medio (Implementar Proximas 2 Semanas)

R8. Crear HERENCIA-ERP-CORE.md para Verticales

Ubicacion: cada vertical/orchestration/00-guidelines/

Contenido:
  - Que modulos hereda de core (60-70%)
  - Que extiende vs modifica
  - Especificaciones transversales que usa
  - Dependencias con otros verticales

R9. Crear CONSUMIDORES.yml en Catalogo

Ubicacion: core/catalog/{funcionalidad}/

Contenido:
  funcionalidad: auth
  consumidores:
    - proyecto: gamilit
      version: "1.1.0"
    - proyecto: erp-core
      especializacion: "Multi-tenant"

R10. Crear CHECKLIST-PROPAGACION.md

## Post-Tarea Obligatorio

Nivel Local:
  - [ ] Inventario actualizado
  - [ ] Traza registrada
  - [ ] PROXIMA-ACCION.md actualizado

Nivel Superior:
  - [ ] Referencia agregada
  - [ ] Status actualizado
  - [ ] Entrada en traza superior

---

6. MATRIZ DE RIESGOS

Riesgo	Probabilidad	Impacto	Mitigacion
Subagente salta CAPVED	Alta	Alto	R2: Matriz de decision
Entity no matchea DDL	Alta	Alto	R3: SIMCO-ALINEACION
Architecture-Analyst no existe	Critico	Alto	R1: Crear perfil
Scope creep no detectado	Media	Medio	R6: Protocolo explicito
Estado heredado desactualizado	Media	Medio	R7: Timestamps
Propagacion incompleta	Alta	Alto	R4, R10: Inventarios + Checklist
Trabajo invisible en suite	Critico	Alto	R4: SUITE_MASTER_INVENTORY

---

7. PLAN DE IMPLEMENTACION

Fase 1: Criticos (Dia 1-2)

1. Crear PERFIL-ARCHITECTURE-ANALYST.md
2. Crear SIMCO-DECISION-MATRIZ.md
3. Crear SIMCO-ALINEACION.md
4. Crear SUITE_MASTER_INVENTORY.yml

Fase 2: Altos (Dia 3-5)

5. Estandarizar nombres de inventarios
6. Crear protocolo de scope creep
7. Agregar timestamps a delegaciones
8. Crear trazas/ en erp-suite

Fase 3: Medios (Semana 2)

9. Crear HERENCIA-ERP-CORE.md en verticales
10. Crear CONSUMIDORES.yml en catalogo
11. Crear CHECKLIST-PROPAGACION.md
12. Actualizar SIMCO-TAREA.md con Fase 0

---

8. METRICAS DE EXITO

Antes de implementar:
  - Agentes con perfil SIMCO: 4/9 (44%)
  - Proyectos con propagacion completa: 1/5 (20%)
  - Verticales con herencia documentada: 1/5 (20%)
  - Validacion cross-layer: 0%

Despues de implementar:
  - Agentes con perfil SIMCO: 9/9 (100%)
  - Proyectos con propagacion completa: 5/5 (100%)
  - Verticales con herencia documentada: 5/5 (100%)
  - Validacion cross-layer: 100%

---

9. CONCLUSION

El sistema SIMCO tiene una base solida pero requiere:

1. Completar perfiles de agentes (especialmente Architecture-Analyst)
2. Clarificar puntos de decision (que SIMCO ejecutar)
3. Implementar propagacion real (inventarios y trazas en todos los niveles)
4. Agregar validacion cross-layer (DDL ↔ Entity ↔ DTO)

Con las 10 recomendaciones implementadas, el sistema evitaria ~95% de confusiones y retrabajos.

---

Archivos Relacionados:

• /home/isem/workspace/core/orchestration/README.md
• /home/isem/workspace/core/orchestration/directivas/simco/
• /home/isem/workspace/core/orchestration/agents/perfiles/

Proxima Revision: 2025-12-15

---

Sistema NEXUS + SIMCO v2.2.0 Analisis realizado: 2025-12-08