workspace-v1/orchestration/README.md

# Sistema de Orquestación de Agentes - NEXUS

**Versión:** 3.4
**Sistema:** SIMCO + CAPVED + Economía de Tokens + Herencia Escalonada
**Actualizado:** 2025-12-26
**Ubicación:** `workspace-v1/orchestration/` (BASE PRINCIPAL)

---

## Visión General

Este directorio es la **BASE PRINCIPAL** del Sistema NEXUS de orquestación de agentes IA. Todo el contenido fundamental reside aquí y los subniveles (control-plane/, core/, projects/) solo **heredan y extienden** con directivas específicas.

### Arquitectura de Herencia Escalonada

```
workspace-v1/orchestration/        ← BASE PRINCIPAL (este directorio)
    ↓ hereda
control-plane/orchestration/       ← Extensiones CI/CD
    ↓ hereda
core/orchestration/                ← Extensiones Catálogo
    ↓ hereda
projects/{proyecto}/orchestration/ ← Extensiones por Proyecto
```

**Novedad v3.0:** Implementación del sistema **SIMCO** que organiza directivas por tipo de operación, permitiendo que cualquier agente siga las directivas correctas independientemente de su especialización.

**Novedad v3.1:** Integración del principio **CAPVED** (Contexto → Análisis → Planeación → Validación → Ejecución → Documentación) como ciclo de vida obligatorio para toda HU/tarea que modifica código o documentación.

**Novedad v3.2:** Integración del principio **ECONOMÍA DE TOKENS** para desglose de tareas y evitar overload. Nuevo `SIMCO-QUICK-REFERENCE.md` para consulta rápida optimizada.

---

## SISTEMA SIMCO (RECOMENDADO)

### Qué es SIMCO

**Single Instruction Matrix by Context and Operation** reorganiza las directivas por **tipo de operación** en lugar de por perfil de agente. Esto resuelve el problema donde los agentes ignoraban directivas cuando realizaban tareas fuera de su dominio principal.

### Acceso Rápido (Rutas Relativas a Este Directorio)

```
../core/catalog/               # CATÁLOGO DE FUNCIONALIDADES (en core/)
├── CATALOG-INDEX.yml          # Índice máquina-readable
├── auth/                      # Autenticación y autorización
├── session-management/        # Gestión de sesiones
├── rate-limiting/             # Limitación de tasa
├── notifications/             # Sistema de notificaciones
├── multi-tenancy/             # Soporte multi-tenant
├── feature-flags/             # Feature flags dinámicos
├── websocket/                 # Comunicación WebSocket
└── payments/                  # Integración de pagos

directivas/simco/              # DIRECTIVAS POR OPERACIÓN (en este directorio)
├── _INDEX.md                  # LEER PRIMERO - Índice del sistema
├── SIMCO-TAREA.md             # CICLO CAPVED - Punto de entrada para HUs
├── SIMCO-REUTILIZAR.md        # Reutilizar del catálogo
├── SIMCO-CREAR.md             # Crear cualquier archivo
├── SIMCO-MODIFICAR.md         # Modificar archivos existentes
├── SIMCO-VALIDAR.md           # Validar código (build, lint)
├── SIMCO-DOCUMENTAR.md        # Documentar trabajo realizado
├── SIMCO-BUSCAR.md            # Buscar archivos e información
├── SIMCO-DELEGACION.md        # Delegar a subagentes
├── SIMCO-DDL.md               # Operaciones PostgreSQL
├── SIMCO-BACKEND.md           # Operaciones NestJS
└── SIMCO-FRONTEND.md          # Operaciones React

directivas/principios/         # PRINCIPIOS FUNDAMENTALES (6)
├── PRINCIPIO-CAPVED.md        # Ciclo de vida de tareas (OBLIGATORIO)
├── PRINCIPIO-DOC-PRIMERO.md   # Documentación antes de implementación
├── PRINCIPIO-ANTI-DUPLICACION.md  # Verificar @CATALOG antes de crear
├── PRINCIPIO-VALIDACION-OBLIGATORIA.md  # Build/lint obligatorios
├── PRINCIPIO-ECONOMIA-TOKENS.md  # Desglose tareas para evitar overload
└── PRINCIPIO-NO-ASUMIR.md     # 🆕 No asumir, PREGUNTAR si falta info

agents/perfiles/               # PERFILES LIGEROS DE AGENTES
├── PERFIL-DATABASE.md         # Database-Agent (~100 líneas)
├── PERFIL-BACKEND.md          # Backend-Agent (~100 líneas)
├── PERFIL-FRONTEND.md         # Frontend-Agent (~100 líneas)
└── PERFIL-ORQUESTADOR.md      # Tech-Leader (~100 líneas)

referencias/
└── ALIASES.yml                # Sistema de aliases para navegación
```

### Cómo Usar SIMCO + CAPVED

**Para TODA HU/Tarea que modifica código:**

1. **Leer SIMCO-TAREA.md** (ciclo CAPVED completo)
2. **Seguir las 6 fases CAPVED**:
   - **C** - Contexto: Vincular HU a proyecto/módulo/epic
   - **A** - Análisis: Mapear impacto, dependencias, riesgos
   - **P** - Planeación: Desglosar en subtareas
   - **V** - Validación: Gate antes de ejecutar (NO DELEGAR)
   - **E** - Ejecución: Implementar usando SIMCO específicos
   - **D** - Documentación: Gate de cierre (OBLIGATORIO)

**Para operaciones específicas dentro de una tarea:**

1. **Verificar catálogo** (PRIMERO): `grep -i "{funcionalidad}" @CATALOG_INDEX`
2. **Si existe en catálogo**: Seguir `SIMCO-REUTILIZAR.md`
3. **Leer principios** (siempre): `directivas/principios/*.md` (5 fundamentales)
4. **Identificar operación**: ¿Crear? ¿Modificar? ¿Validar?
5. **Leer SIMCO correspondiente**: `directivas/simco/SIMCO-{operación}.md`
6. **Si aplica dominio**: Leer `SIMCO-{DDL|BACKEND|FRONTEND}.md`
7. **Seguir checklist** del archivo SIMCO

### Sistema de Aliases

```yaml
# 🆕 CAPVED - CICLO DE VIDA DE TAREAS
@CAPVED:     directivas/principios/PRINCIPIO-CAPVED.md
@TAREA:      directivas/simco/SIMCO-TAREA.md
@TPL_CAPVED: templates/TEMPLATE-TAREA-CAPVED.md

# CATÁLOGO DE FUNCIONALIDADES (CONSULTAR PRIMERO)
@CATALOG:       core/catalog/
@CATALOG_INDEX: core/catalog/CATALOG-INDEX.yml

# Operaciones
@REUTILIZAR: directivas/simco/SIMCO-REUTILIZAR.md
@CREAR:      directivas/simco/SIMCO-CREAR.md
@MODIFICAR:  directivas/simco/SIMCO-MODIFICAR.md
@VALIDAR:    directivas/simco/SIMCO-VALIDAR.md
@DOCUMENTAR: directivas/simco/SIMCO-DOCUMENTAR.md
@BUSCAR:     directivas/simco/SIMCO-BUSCAR.md
@DELEGAR:    directivas/simco/SIMCO-DELEGACION.md

# Especializados
@OP_DDL:     directivas/simco/SIMCO-DDL.md
@OP_BACKEND: directivas/simco/SIMCO-BACKEND.md
@OP_FRONTEND: directivas/simco/SIMCO-FRONTEND.md

# Principios (5 fundamentales)
@PRINCIPIOS: directivas/principios/
@TOKENS:     directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md
@QUICK_REF:  directivas/simco/SIMCO-QUICK-REFERENCE.md

# Proyecto (valores en CONTEXTO-PROYECTO.md)
@INVENTORY:  orchestration/inventarios/MASTER_INVENTORY.yml
@DDL:        {DB_DDL_PATH}/schemas/
@BACKEND:    {BACKEND_SRC}/modules/
@FRONTEND:   {FRONTEND_SRC}/apps/
```

---

## Arquitectura de Herencia

```
┌─────────────────────────────────────────────────────────────────────┐
│                    WORKSPACE (~/workspace/)                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌────────────────────────────────────────────────────────────────┐ │
│  │         🆕 CORE/CATALOG (Funcionalidades Reutilizables)        │ │
│  │  • Código probado y documentado                                │ │
│  │  • auth, session, rate-limiting, notifications, etc.          │ │
│  │  • CONSULTAR ANTES de implementar funcionalidad común         │ │
│  └────────────────────────────────────────────────────────────────┘ │
│                               │                                      │
│                               ▼ REUTILIZA                            │
│  ┌────────────────────────────────────────────────────────────────┐ │
│  │              CORE/ORCHESTRATION (Nivel Workspace)              │ │
│  │  • Sistema SIMCO (directivas por operación)                   │ │
│  │  • Principios fundamentales (aplican a TODOS)                 │ │
│  │  • Perfiles ligeros de agentes                                │ │
│  │  • Sistema de aliases                                          │ │
│  │  • Templates de documentación                                  │ │
│  └────────────────────────────────────────────────────────────────┘ │
│                               │                                      │
│                               ▼ HEREDA                               │
│  ┌────────────────────────────────────────────────────────────────┐ │
│  │           PROJECTS/{proyecto}/ORCHESTRATION (Nivel Proyecto)   │ │
│  │  • CONTEXTO-PROYECTO.md (aliases resueltos)                   │ │
│  │  • Directivas específicas del proyecto                        │ │
│  │  • Inventarios (DATABASE, BACKEND, FRONTEND)                  │ │
│  │  • Trazas de tareas                                           │ │
│  │  • PROXIMA-ACCION.md                                          │ │
│  └────────────────────────────────────────────────────────────────┘ │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Estructura de Directorios

```
core/orchestration/
├── README.md                         # ⭐ Este archivo
│
├── directivas/
│   ├── _MAP.md                       # Mapa de contenidos
│   │
│   ├── simco/                        # 🆕 SISTEMA SIMCO
│   │   ├── _INDEX.md                 # Índice maestro SIMCO
│   │   ├── SIMCO-CREAR.md
│   │   ├── SIMCO-MODIFICAR.md
│   │   ├── SIMCO-VALIDAR.md
│   │   ├── SIMCO-DOCUMENTAR.md
│   │   ├── SIMCO-BUSCAR.md
│   │   ├── SIMCO-DELEGACION.md
│   │   ├── SIMCO-DDL.md
│   │   ├── SIMCO-BACKEND.md
│   │   └── SIMCO-FRONTEND.md
│   │
│   ├── principios/                   # 🆕 PRINCIPIOS FUNDAMENTALES (5)
│   │   ├── PRINCIPIO-CAPVED.md
│   │   ├── PRINCIPIO-DOC-PRIMERO.md
│   │   ├── PRINCIPIO-ANTI-DUPLICACION.md
│   │   ├── PRINCIPIO-VALIDACION-OBLIGATORIA.md
│   │   └── PRINCIPIO-ECONOMIA-TOKENS.md
│   │
│   └── legacy/                       # Directivas legacy (referencia)
│
├── agents/
│   ├── perfiles/                     # 🆕 PERFILES LIGEROS SIMCO
│   │   ├── PERFIL-DATABASE.md
│   │   ├── PERFIL-BACKEND.md
│   │   ├── PERFIL-FRONTEND.md
│   │   └── PERFIL-ORQUESTADOR.md
│   │
│   └── legacy/                       # Prompts legacy (referencia extendida)
│
├── referencias/
│   └── ALIASES.yml                   # 🆕 Sistema de aliases
│
├── templates/
│   ├── TEMPLATE-CONTEXTO-PROYECTO.md # 🆕 Template para proyectos
│   ├── TEMPLATE-ANALISIS.md
│   ├── TEMPLATE-PLAN.md
│   └── TEMPLATE-VALIDACION.md
│
├── checklists/
│   ├── CHECKLIST-CODE-REVIEW-API.md
│   ├── CHECKLIST-PROPAGACION.md      # 🆕 Verificar propagación entre niveles
│   └── CHECKLIST-REFACTORIZACION.md
│
└── _historico/                       # Documentos de análisis archivados
    └── *.md
```

---

## Principios Fundamentales (6)

### 1. CAPVED (PRINCIPIO-CAPVED.md) 🆕
```
TODA tarea que modifica código o documentación DEBE pasar por:
  C - Contexto:     Vincular HU a proyecto/módulo/epic
  A - Análisis:     Mapear impacto, dependencias, riesgos
  P - Planeación:   Desglosar en subtareas por dominio
  V - Validación:   Gate antes de ejecutar (NO DELEGAR)
  E - Ejecución:    Implementar usando SIMCO específicos
  D - Documentación: Gate de cierre (HU no está Done sin esto)

Si aparece scope creep → Registrar y crear HU derivada

Objetivo: Trazabilidad completa, análisis de impacto, documentación actualizada
```

### 2. Doc Primero (PRINCIPIO-DOC-PRIMERO.md)
```
ANTES de implementar cualquier cosa:
1. Consultar docs/ del proyecto
2. Verificar especificaciones existentes
3. NO asumir - verificar

Objetivo: Implementación alineada con documentación
```

### 3. Anti-Duplicación (PRINCIPIO-ANTI-DUPLICACION.md)
```
ANTES de crear cualquier archivo:
1. Verificar @INVENTORY correspondiente
2. Buscar patrones similares existentes
3. Si existe, REUTILIZAR o EXTENDER

Objetivo: Cero objetos duplicados
```

### 4. Validación Obligatoria (PRINCIPIO-VALIDACION-OBLIGATORIA.md)
```
ANTES de marcar tarea como completada:
1. npm run build DEBE pasar
2. npm run lint DEBE pasar
3. Carga limpia DEBE funcionar (si DDL)

Objetivo: Código siempre en estado válido
```

### 5. Economía de Tokens (PRINCIPIO-ECONOMIA-TOKENS.md)
```
ANTES de ejecutar tareas complejas:
1. Verificar límites de tokens (~200K input, ~8K output)
2. Desglosar HUs grandes en subtareas manejables
3. Usar SIMCO-QUICK-REFERENCE.md para consultas rápidas

Objetivo: Evitar overload de contexto, maximizar eficiencia
```

### 6. No Asumir (PRINCIPIO-NO-ASUMIR.md) 🆕
```
SI falta información o hay ambigüedad:
1. Buscar exhaustivamente en docs (10-15 min)
2. Si no se encuentra → DETENER
3. Documentar la pregunta claramente
4. Escalar al Product Owner
5. Esperar respuesta antes de implementar

Objetivo: Cero implementaciones basadas en suposiciones
```

---

## Flujo CAPVED (6 Fases - Obligatorio)

```
┌─────────────────────────────────────────────────────────────────┐
│ FASE C: CONTEXTO        │ Vincular HU, clasificar, cargar SIMCO │
├─────────────────────────────────────────────────────────────────┤
│ FASE A: ANÁLISIS        │ Leer docs/, mapear impacto, riesgos   │
├─────────────────────────────────────────────────────────────────┤
│ FASE P: PLANEACIÓN      │ Desglosar subtareas, asignar agentes  │
├─────────────────────────────────────────────────────────────────┤
│ FASE V: VALIDACIÓN      │ ⚠️ Gate antes de ejecutar (NO DELEGAR)│
├─────────────────────────────────────────────────────────────────┤
│ FASE E: EJECUCIÓN       │ Implementar usando SIMCO específicos  │
├─────────────────────────────────────────────────────────────────┤
│ FASE D: DOCUMENTACIÓN   │ Gate de cierre, actualizar inventarios│
└─────────────────────────────────────────────────────────────────┘

NOTA: Si aparece scope creep en cualquier fase → Crear HU derivada
```

---

## Uso Rápido

### Al iniciar una sesión de trabajo

```markdown
1. Leer core/orchestration/directivas/simco/_INDEX.md
2. Leer los 5 principios en directivas/principios/ (incluyendo CAPVED y Economía de Tokens)
3. Leer tu perfil en agents/perfiles/PERFIL-{TU-TIPO}.md
4. Leer projects/{proyecto}/orchestration/00-guidelines/CONTEXTO-PROYECTO.md
5. Leer projects/{proyecto}/orchestration/PROXIMA-ACCION.md
```

### Para realizar una HU/Tarea

```markdown
1. Leer SIMCO-TAREA.md (ciclo CAPVED completo)
2. Fase C: Vincular HU a proyecto/módulo/epic
3. Fase A: Mapear impacto, dependencias, riesgos
4. Fase P: Desglosar en subtareas
5. Fase V: Validar que todo cuadra (NO DELEGAR)
6. Fase E: Implementar usando SIMCO específicos
7. Fase D: Actualizar inventarios, trazas, lecciones aprendidas
```

### Para operaciones dentro de una tarea

```markdown
1. Identificar operación → Leer SIMCO correspondiente
2. Si aplica dominio → Leer SIMCO de dominio
3. Seguir checklist del SIMCO
4. Al completar → SIMCO-VALIDAR.md + SIMCO-DOCUMENTAR.md
```

### Para delegar a subagente

```markdown
1. Leer SIMCO-DELEGACION.md
2. Usar template de delegación
3. Incluir:
   - Principios a leer
   - SIMCO relevantes
   - Variables resueltas
   - Criterios de aceptación
```

---

## Migración desde Sistema Anterior

Si vienes del sistema legacy (prompts de 700-850 líneas):

1. **Lee:** `_historico/GUIA-MIGRACION-SIMCO.md`
2. **Usa:** Perfiles ligeros + SIMCO en lugar de prompts extensos
3. **Consulta:** Prompts legacy solo para detalles adicionales específicos

### Beneficios de SIMCO vs Legacy

| Aspecto | Legacy | SIMCO |
|---------|--------|-------|
| Líneas por perfil | ~800 | ~100 |
| Duplicación | ~40% | <5% |
| Cross-profile tasks | Se ignoran directivas | Se aplican SIMCO correctos |
| Mantenimiento | Actualizar N archivos | Actualizar 1 fuente |
| Navegación | Rutas largas | Aliases claros |

---

## Documentos Clave

### Lectura Obligatoria (SIMCO + CAPVED)
1. `directivas/simco/_INDEX.md` - Índice del sistema SIMCO
2. `directivas/principios/*.md` - Los 5 principios fundamentales (incluyendo CAPVED y Economía de Tokens)
3. `directivas/simco/SIMCO-TAREA.md` - Ciclo CAPVED para toda HU/tarea
4. `agents/perfiles/PERFIL-{TU-TIPO}.md` - Tu perfil
5. `referencias/ALIASES.yml` - Sistema de aliases

### Referencia Extendida (Legacy)
- `agents/legacy/PROMPT-*-AGENT.md` - Prompts detallados por perfil
- `directivas/legacy/DIRECTIVA-*.md` - Directivas específicas

### Templates
- `templates/TEMPLATE-TAREA-CAPVED.md` - 🆕 Template completo para tracking de HUs con CAPVED
- `templates/TEMPLATE-CONTEXTO-PROYECTO.md` - Para nuevos proyectos
- `templates/TEMPLATE-ANALISIS.md` - Formato de análisis
- `templates/TEMPLATE-PLAN.md` - Formato de planificación

### Checklists
- `checklists/CHECKLIST-CODE-REVIEW-API.md` - Revisión de código para APIs
- `checklists/CHECKLIST-PROPAGACION.md` - 🆕 Verificar propagación entre niveles
- `checklists/CHECKLIST-REFACTORIZACION.md` - Guía para refactorizaciones

---

## Proyectos Implementados

### Estructura Esperada por Proyecto

```
projects/{proyecto}/orchestration/
├── 00-guidelines/
│   └── CONTEXTO-PROYECTO.md     # 🆕 Aliases resueltos
├── inventarios/
│   ├── MASTER_INVENTORY.yml
│   ├── DATABASE_INVENTORY.yml
│   ├── BACKEND_INVENTORY.yml
│   └── FRONTEND_INVENTORY.yml
├── trazas/
│   ├── TRAZA-TAREAS-DATABASE.md
│   ├── TRAZA-TAREAS-BACKEND.md
│   └── TRAZA-TAREAS-FRONTEND.md
├── directivas/                   # Directivas específicas del proyecto
└── PROXIMA-ACCION.md
```

---

## Soporte y Mantenimiento

### Archivos a Actualizar

| Cambio | Archivo(s) |
|--------|------------|
| Nueva operación universal | `simco/SIMCO-*.md` |
| Nuevo principio | `principios/PRINCIPIO-*.md` |
| Cambio en perfil | `agents/perfiles/PERFIL-*.md` |
| Nuevo alias global | `referencias/ALIASES.yml` |
| Nuevo proyecto | Copiar `templates/TEMPLATE-CONTEXTO-PROYECTO.md` |

### Versionado
- **v3.2** (2025-12-08): Integración principio ECONOMÍA DE TOKENS (5º principio) + SIMCO-QUICK-REFERENCE
- **v3.1** (2025-12-08): Integración principio CAPVED (ciclo de vida de tareas)
- **v3.0** (2025-12-08): Implementación sistema SIMCO
- **v2.0** (2025-12-05): Sistema legacy con prompts extensos
- **v1.0**: Sistema inicial

---

*Sistema NEXUS - Orquestación de Agentes IA*
*Versión: 3.3 (SIMCO + CAPVED + Economía de Tokens + NO-ASUMIR)*
*Actualizado: 2025-12-08*