workspace-v1/orchestration

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

# 🆕 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

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

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

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

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