# 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

```yaml
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

```yaml
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:**
```yaml
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

```yaml
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

```markdown
| 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

```markdown
## 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

```yaml
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

```yaml
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

```markdown
## 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

```yaml
# 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

```markdown
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

```yaml
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

```markdown
## 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

```yaml
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*