# SISTEMA SIMCO - ÍNDICE MAESTRO

**Single Instruction Matrix by Context and Operation**

**Versión:** 2.3.0
**Fecha:** 2025-12-12
**Extensión:** CCA + CAPVED + Niveles Jerárquicos + Economía de Tokens + Git + Escalamiento

---

## QUÉ ES SIMCO

SIMCO es un sistema de directivas organizadas por **tipo de operación**, no por perfil de agente. Esto permite que cualquier agente, independientemente de su especialización, pueda seguir las directivas correctas cuando realiza una operación fuera de su dominio principal.

---

## ESTRUCTURA

```
core/
├── catalog/                         # 🆕 CATÁLOGO DE FUNCIONALIDADES REUTILIZABLES
│   ├── CATALOG-INDEX.yml           # Índice máquina-readable (buscar aquí PRIMERO)
│   ├── 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
│
└── orchestration/
    ├── directivas/
    │   ├── simco/                       # DIRECTIVAS POR OPERACIÓN (20 archivos)
    │   │   ├── _INDEX.md               ← ESTÁS AQUÍ
    │   │   │
    │   │   │   # === CICLO DE VIDA ===
    │   │   ├── SIMCO-TAREA.md          # CICLO CAPVED - Punto de entrada para HUs
    │   │   ├── SIMCO-INICIALIZACION.md # Bootstrap de agentes (CCA)
    │   │   │
    │   │   │   # === OPERACIONES UNIVERSALES ===
    │   │   ├── 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 (con CCA)
    │   │   │
    │   │   │   # === CATÁLOGO ===
    │   │   ├── SIMCO-REUTILIZAR.md     # Reutilizar del catálogo
    │   │   ├── SIMCO-CONTRIBUIR-CATALOGO.md # Contribuir al catálogo
    │   │   │
    │   │   │   # === POR DOMINIO TÉCNICO ===
    │   │   ├── SIMCO-DDL.md            # Operaciones de base de datos
    │   │   ├── SIMCO-BACKEND.md        # Operaciones de backend NestJS
    │   │   ├── SIMCO-FRONTEND.md       # Operaciones de frontend React
    │   │   ├── SIMCO-MOBILE.md         # Operaciones React Native
    │   │   ├── SIMCO-ML.md             # Machine Learning y AI
    │   │   │
    │   │   │   # === NIVELES Y PROPAGACIÓN ===
    │   │   ├── SIMCO-NIVELES.md        # Identificación de nivel jerárquico
    │   │   ├── SIMCO-PROPAGACION.md    # Propagación de documentación
    │   │   │
    │   │   │   # === TOMA DE DECISIONES ===
    │   │   ├── SIMCO-ALINEACION.md     # Alineación entre capas
    │   │   ├── SIMCO-DECISION-MATRIZ.md # Matriz de decisión para agentes
    │   │   │
    │   │   │   # === GIT Y GOBERNANZA ===
    │   │   ├── SIMCO-GIT.md              # 🆕 Control de versiones y commits
    │   │   ├── SIMCO-ESCALAMIENTO.md     # 🆕 Escalamiento a Product Owner
    │   │   │
    │   │   │   # === REFERENCIA ===
    │   │   └── SIMCO-QUICK-REFERENCE.md # Referencia rápida (optimizado para tokens)
    │   │
    │   └── principios/                  # PRINCIPIOS FUNDAMENTALES (6)
    │       ├── PRINCIPIO-CAPVED.md      # Ciclo de vida de tareas
    │       ├── PRINCIPIO-DOC-PRIMERO.md
    │       ├── PRINCIPIO-ANTI-DUPLICACION.md
    │       ├── PRINCIPIO-VALIDACION-OBLIGATORIA.md
    │       ├── PRINCIPIO-ECONOMIA-TOKENS.md  # Límites y desglose de tareas
    │       └── PRINCIPIO-NO-ASUMIR.md   # 🆕 No asumir, preguntar
    │
    ├── agents/
    │   └── perfiles/                    # PERFILES DE AGENTES (23 archivos)
    │       │
    │       │   # === PERFILES TÉCNICOS ===
    │       ├── PERFIL-DATABASE.md          # PostgreSQL DDL
    │       ├── PERFIL-BACKEND.md           # NestJS/TypeORM
    │       ├── PERFIL-BACKEND-EXPRESS.md   # Express.js/Prisma
    │       ├── PERFIL-FRONTEND.md          # React Web
    │       ├── PERFIL-MOBILE-AGENT.md      # React Native
    │       ├── PERFIL-ML-SPECIALIST.md     # Python/ML/AI
    │       ├── PERFIL-LLM-AGENT.md         # 🆕 Integración LLM/AI
    │       ├── PERFIL-TRADING-STRATEGIST.md # 🆕 Estrategias de trading
    │       │
    │       │   # === PERFILES DE COORDINACIÓN ===
    │       ├── PERFIL-ORQUESTADOR.md       # Coordinación general
    │       ├── PERFIL-TECH-LEADER.md       # Liderazgo técnico
    │       ├── PERFIL-ARCHITECTURE-ANALYST.md # Análisis de arquitectura
    │       ├── PERFIL-REQUIREMENTS-ANALYST.md # Análisis de requerimientos
    │       │
    │       │   # === PERFILES DE CALIDAD ===
    │       ├── PERFIL-CODE-REVIEWER.md     # Revisión de código
    │       ├── PERFIL-BUG-FIXER.md         # Corrección de bugs
    │       ├── PERFIL-TESTING.md           # QA y testing
    │       ├── PERFIL-DOCUMENTATION-VALIDATOR.md # Validación de documentación
    │       ├── PERFIL-WORKSPACE-MANAGER.md # Gestión de workspace
    │       │
    │       │   # === PERFILES DE AUDITORÍA ===
    │       ├── PERFIL-SECURITY-AUDITOR.md  # Auditoría de seguridad
    │       ├── PERFIL-DATABASE-AUDITOR.md  # 🆕 Auditoría de BD
    │       ├── PERFIL-POLICY-AUDITOR.md    # 🆕 Auditoría de cumplimiento
    │       ├── PERFIL-INTEGRATION-VALIDATOR.md # 🆕 Validación de integración
    │       │
    │       │   # === PERFILES DE INFRAESTRUCTURA ===
    │       ├── PERFIL-DEVOPS.md            # DevOps y CI/CD
    │       └── PERFIL-DEVENV.md            # Ambiente de desarrollo
    │
    ├── templates/                          # TEMPLATES (17 archivos)
    │   │
    │   │   # === CONTEXTO POR NIVEL ===
    │   ├── CONTEXTO-NIVEL-STANDALONE.md      # Template para proyectos standalone
    │   ├── CONTEXTO-NIVEL-SUITE.md           # Template para suites multi-vertical
    │   ├── CONTEXTO-NIVEL-SUITE-CORE.md      # Template para core de suite
    │   ├── CONTEXTO-NIVEL-VERTICAL.md        # Template para verticales
    │   │
    │   │   # === TEMPLATES DE AGENTES ===
    │   ├── TEMPLATE-DELEGACION-SUBAGENTE.md  # Delegación a subagentes
    │   ├── TEMPLATE-CONTEXTO-SUBAGENTE.md    # Contexto para subagentes
    │   ├── TEMPLATE-CONTEXTO-PROYECTO.md     # Contexto de proyecto
    │   ├── TEMPLATES-SUBAGENTES.md           # Guía de subagentes
    │   │
    │   │   # === TEMPLATES DE TAREAS ===
    │   ├── TEMPLATE-TAREA-CAPVED.md          # Tarea con ciclo CAPVED
    │   ├── TEMPLATE-TAREA-TECNICA.md         # Tarea técnica simple
    │   ├── TEMPLATE-HISTORIA-USUARIO.md      # Historia de usuario
    │   ├── TEMPLATE-EPICA.md                 # Épica
    │   ├── TEMPLATE-PLAN.md                  # Plan de implementación
    │   │
    │   │   # === TEMPLATES DE VALIDACIÓN ===
    │   ├── TEMPLATE-ANALISIS.md              # Análisis de impacto
    │   ├── TEMPLATE-VALIDACION.md            # Validación de entregables
    │   ├── CHECKLIST-ESTRUCTURA-PROYECTO.md  # Estructura de proyecto
    │   └── _MAP.md                           # Mapa de templates
    │
    ├── patrones/                        # PATRONES DE CÓDIGO
    │   ├── MAPEO-TIPOS-DDL-TYPESCRIPT.md # Mapeo PostgreSQL ↔ TypeScript
    │   ├── PATRON-VALIDACION.md          # Validación con class-validator/Zod
    │   ├── PATRON-EXCEPTION-HANDLING.md  # Manejo de errores y excepciones
    │   ├── PATRON-TESTING.md             # Patrones de testing
    │   ├── PATRON-LOGGING.md             # Logging estructurado
    │   ├── PATRON-CONFIGURACION.md       # Variables de entorno y config
    │   ├── PATRON-SEGURIDAD.md           # Seguridad y OWASP
    │   ├── PATRON-PERFORMANCE.md         # Optimización y caching
    │   ├── PATRON-TRANSACCIONES.md       # Transacciones de BD
    │   ├── ANTIPATRONES.md               # Lo que NUNCA hacer
    │   └── NOMENCLATURA-UNIFICADA.md     # Convenciones de nombres
    │
    ├── impactos/                        # IMPACTO DE CAMBIOS
    │   ├── IMPACTO-CAMBIOS-DDL.md       # Cascada de cambios en BD
    │   ├── IMPACTO-CAMBIOS-BACKEND.md   # Sincronización Backend↔Frontend
    │   ├── IMPACTO-CAMBIOS-ENTITY.md    # Cambios en Entities TypeORM
    │   ├── IMPACTO-CAMBIOS-API.md       # Cambios en endpoints REST
    │   └── MATRIZ-DEPENDENCIAS.md       # Matriz completa de dependencias
    │
    ├── procesos/                        # PROCESOS DE TRABAJO
    │   └── ORDEN-IMPLEMENTACION.md      # DDL-First, orden de capas
    │
    ├── checklists/                      # CHECKLISTS DE VERIFICACIÓN
    │   ├── CHECKLIST-CODE-REVIEW-API.md    # Revisión de código API
    │   ├── CHECKLIST-REFACTORIZACION.md    # Checklist de refactoring
    │   └── CHECKLIST-PROPAGACION.md        # Propagación de cambios
    │
    ├── _historico/
    │   └── MAPA-CONTEXTO-AGENTE.md     # Trazabilidad (histórico)
    │
    └── referencias/
        └── ALIASES.yml                  # SISTEMA DE ALIAS
```

---

## GUÍA RÁPIDA

### Inicialización de Agente (CCA)

```yaml
# Prompt mínimo de inicialización:
"Serás {PERFIL}-Agent trabajando en el proyecto {PROYECTO}
para realizar: {TAREA}

Antes de actuar, ejecuta el protocolo CCA (Carga de Contexto Automática)."

# El agente debe:
1. Leer SIMCO-INICIALIZACION.md
2. Cargar contexto en cascada (Core → Proyecto → Operación → Tarea)
3. Confirmar "READY_TO_EXECUTE" antes de implementar

# Ver: MAPA-CONTEXTO-AGENTE.md para trazabilidad completa
```

### Para TODO Agente - Siempre Leer:

| Principio | Archivo | Resumen |
|-----------|---------|---------|
| **CAPVED** | `PRINCIPIO-CAPVED.md` | 🆕 Toda tarea pasa por Contexto→Análisis→Plan→Validación→Ejecución→Doc |
| Doc Primero | `PRINCIPIO-DOC-PRIMERO.md` | Consultar docs/ antes de implementar |
| Anti-Dup | `PRINCIPIO-ANTI-DUPLICACION.md` | Verificar que no existe antes de crear |
| Validación | `PRINCIPIO-VALIDACION-OBLIGATORIA.md` | Build y lint DEBEN pasar |
| **Tokens** | `PRINCIPIO-ECONOMIA-TOKENS.md` | 🆕 Desglosar tareas para evitar overload |

### Por Tipo de Operación:

| Operación | Archivo SIMCO | Cuándo Usar |
|-----------|---------------|-------------|
| **Tarea/HU** | `SIMCO-TAREA.md` | **PUNTO DE ENTRADA** - Toda HU/tarea que modifica código |
| **Inicialización** | `SIMCO-INICIALIZACION.md` | Bootstrap de agentes (protocolo CCA) |
| **Reutilizar** | `SIMCO-REUTILIZAR.md` | ANTES de implementar funcionalidad común |
| **Contribuir** | `SIMCO-CONTRIBUIR-CATALOGO.md` | DESPUÉS de implementar funcionalidad reutilizable |
| **Crear** | `SIMCO-CREAR.md` | Al crear cualquier archivo nuevo |
| **Modificar** | `SIMCO-MODIFICAR.md` | Al modificar archivos existentes |
| **Validar** | `SIMCO-VALIDAR.md` | Antes de marcar tarea completa |
| **Documentar** | `SIMCO-DOCUMENTAR.md` | Al finalizar cualquier tarea |
| **Buscar** | `SIMCO-BUSCAR.md` | Para encontrar archivos/info |
| **Delegar** | `SIMCO-DELEGACION.md` | Al asignar trabajo a subagentes |
| **Alineación** | `SIMCO-ALINEACION.md` | Validar alineación entre capas (DDL↔Entity↔DTO) |
| **Decisión** | `SIMCO-DECISION-MATRIZ.md` | Clarificar qué directiva ejecutar |

### Por Dominio Técnico:

| Dominio | Archivo SIMCO | Cuándo Usar |
|---------|---------------|-------------|
| **Database** | `SIMCO-DDL.md` | Operaciones con PostgreSQL/DDL |
| **Backend NestJS** | `SIMCO-BACKEND.md` | Operaciones con NestJS/TypeORM |
| **Backend Express** | `SIMCO-BACKEND.md` | Operaciones con Express.js (Prisma/Drizzle) |
| **Frontend** | `SIMCO-FRONTEND.md` | Operaciones con React/TypeScript |
| **Mobile** | `SIMCO-MOBILE.md` | Operaciones con React Native |
| **ML/AI** | `SIMCO-ML.md` | Machine Learning, LLM integration, FastAPI |

### Por Nivel Jerárquico:

| Operación | Archivo SIMCO | Cuándo Usar |
|-----------|---------------|-------------|
| **Identificar Nivel** | `SIMCO-NIVELES.md` | PASO 0 de toda tarea - identificar dónde estoy |
| **Propagar** | `SIMCO-PROPAGACION.md` | Al completar tarea - actualizar niveles superiores |

---

## CÓMO USAR SIMCO

### Paso 0: ¿Es una HU/Tarea que genera commit?

**SÍ** → Usar `SIMCO-TAREA.md` (ciclo CAPVED completo)
**NO** (solo exploración/consulta) → Usar `SIMCO-BUSCAR.md`

### Paso 1: Identificar Operación

¿Qué voy a hacer?
- ¿Ejecutar HU/tarea completa? → `SIMCO-TAREA.md` (CAPVED)
- ¿Crear algo nuevo? → `SIMCO-CREAR.md`
- ¿Modificar existente? → `SIMCO-MODIFICAR.md`
- ¿Validar código? → `SIMCO-VALIDAR.md`
- ¿Documentar trabajo? → `SIMCO-DOCUMENTAR.md`

### Paso 2: Identificar Dominio (si aplica)

¿En qué capa?
- ¿Base de datos? → `SIMCO-DDL.md`
- ¿Backend? → `SIMCO-BACKEND.md`
- ¿Frontend? → `SIMCO-FRONTEND.md`

### Paso 3: Leer Principios (5 Fundamentales)

Siempre tener en mente:
1. **CAPVED**: Toda tarea pasa por el ciclo completo
2. **Doc Primero**: Documentación antes de código
3. **Anti-Dup**: Verificar que no existe antes de crear
4. **Validación**: Build/lint DEBEN pasar
5. **Tokens**: Desglosar tareas grandes para evitar overload

### Paso 4: Seguir Checklist

Cada SIMCO tiene un checklist. Seguirlo paso a paso.

---

## ALIAS MÁS USADOS

```yaml
# CICLO DE VIDA Y BOOTSTRAP
@CAPVED:        core/orchestration/directivas/principios/PRINCIPIO-CAPVED.md
@TAREA:         core/orchestration/directivas/simco/SIMCO-TAREA.md
@INICIALIZACION: core/orchestration/directivas/simco/SIMCO-INICIALIZACION.md
@TPL_CAPVED:    core/orchestration/templates/TEMPLATE-TAREA-CAPVED.md

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

# OPERACIONES UNIVERSALES
@REUTILIZAR: core/orchestration/directivas/simco/SIMCO-REUTILIZAR.md
@CREAR:      core/orchestration/directivas/simco/SIMCO-CREAR.md
@MODIFICAR:  core/orchestration/directivas/simco/SIMCO-MODIFICAR.md
@VALIDAR:    core/orchestration/directivas/simco/SIMCO-VALIDAR.md
@DOCUMENTAR: core/orchestration/directivas/simco/SIMCO-DOCUMENTAR.md
@BUSCAR:     core/orchestration/directivas/simco/SIMCO-BUSCAR.md
@DELEGAR:    core/orchestration/directivas/simco/SIMCO-DELEGACION.md

# POR DOMINIO TÉCNICO
@OP_DDL:      core/orchestration/directivas/simco/SIMCO-DDL.md
@OP_BACKEND:  core/orchestration/directivas/simco/SIMCO-BACKEND.md
@OP_FRONTEND: core/orchestration/directivas/simco/SIMCO-FRONTEND.md
@OP_MOBILE:   core/orchestration/directivas/simco/SIMCO-MOBILE.md
@OP_ML:       core/orchestration/directivas/simco/SIMCO-ML.md

# NIVELES Y PROPAGACIÓN
@NIVELES:     core/orchestration/directivas/simco/SIMCO-NIVELES.md
@PROPAGACION: core/orchestration/directivas/simco/SIMCO-PROPAGACION.md

# TOMA DE DECISIONES
@ALINEACION:      core/orchestration/directivas/simco/SIMCO-ALINEACION.md
@DECISION_MATRIZ: core/orchestration/directivas/simco/SIMCO-DECISION-MATRIZ.md

# TEMPLATES DE CONTEXTO
@CTX_STANDALONE: core/orchestration/templates/CONTEXTO-NIVEL-STANDALONE.md
@CTX_SUITE:      core/orchestration/templates/CONTEXTO-NIVEL-SUITE.md
@CTX_SUITE_CORE: core/orchestration/templates/CONTEXTO-NIVEL-SUITE-CORE.md
@CTX_VERTICAL:   core/orchestration/templates/CONTEXTO-NIVEL-VERTICAL.md

# PRINCIPIOS
@PRINCIPIOS: core/orchestration/directivas/principios/
@TOKENS:     core/orchestration/directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md

# PATRONES Y REFERENCIAS
@PATRONES:   core/orchestration/patrones/
@IMPACTOS:   core/orchestration/impactos/
@QUICK_REF:  core/orchestration/directivas/simco/SIMCO-QUICK-REFERENCE.md

# PROYECTO
@INVENTORY:  orchestration/inventarios/MASTER_INVENTORY.yml
@ALIASES:    core/orchestration/referencias/ALIASES.yml
```

---

## FLUJO TÍPICO CON SIMCO + CAPVED

```
TAREA: Crear nueva tabla + entity + endpoints

══════════════════════════════════════════════════════════════
FASE C - CONTEXTO
══════════════════════════════════════════════════════════════
├── Vincular HU a proyecto/módulo/epic
├── Clasificar tipo (feature/fix/refactor)
├── Registrar origen (plan/descubrimiento)
├── Cargar SIMCO-TAREA.md
└── Verificar @CATALOG_INDEX (¿existe similar?)

══════════════════════════════════════════════════════════════
FASE A - ANÁLISIS
══════════════════════════════════════════════════════════════
├── Leer PRINCIPIOS (5 fundamentales)
├── Consultar docs/ del proyecto
├── Mapear objetos impactados (BD, BE, FE)
├── Identificar dependencias con otras HUs
└── Detectar riesgos

══════════════════════════════════════════════════════════════
FASE P - PLANEACIÓN
══════════════════════════════════════════════════════════════
├── Desglosar en subtareas:
│   ├── ST-001: Actualizar docs/
│   ├── ST-002: Database-Agent → DDL
│   ├── ST-003: Backend-Agent → Entity
│   ├── ST-004: Backend-Agent → Service/Controller
│   ├── ST-005: Frontend-Agent → Components
│   └── ST-006: Validación final
├── Definir criterios de aceptación
└── Asignar agentes

══════════════════════════════════════════════════════════════
FASE V - VALIDACIÓN (⚠️ NO DELEGAR)
══════════════════════════════════════════════════════════════
├── ¿Todo lo de A tiene subtarea en P?
├── ¿Dependencias resueltas?
├── ¿Hay scope creep? → Crear HU derivada
└── GATE: Solo pasa si todo cuadra

══════════════════════════════════════════════════════════════
FASE E - EJECUCIÓN
══════════════════════════════════════════════════════════════
├── Actualizar docs/ PRIMERO
├── Database-Agent: @CREAR + @OP_DDL
├── Backend-Agent: @CREAR + @OP_BACKEND
├── Frontend-Agent: @CREAR + @OP_FRONTEND
├── Validar build/lint por capa
└── Registrar progreso

══════════════════════════════════════════════════════════════
FASE D - DOCUMENTACIÓN
══════════════════════════════════════════════════════════════
├── Actualizar inventarios
├── Actualizar trazas
├── Crear ADR (si aplica)
├── Vincular HUs derivadas
├── Registrar lecciones aprendidas
└── GATE: HU no está Done sin esto
```

---

## COMPARATIVA: ANTES vs DESPUÉS

| Aspecto | Sistema Anterior | Sistema SIMCO |
|---------|------------------|---------------|
| Directivas | Por perfil (~800 líneas c/u) | Por operación (~200 líneas c/u) |
| Duplicación | Alta (~40%) | Mínima (<5%) |
| Cross-profile | Se ignoran directivas | Se aplican SIMCO correctos |
| Mantenimiento | Actualizar N archivos | Actualizar 1 fuente |
| Navegación | Difícil | Aliases claros |

---

## MIGRACIÓN DESDE SISTEMA ANTERIOR

Los prompts extensos anteriores (`PROMPT-*-AGENT.md`) siguen disponibles como referencia extendida. Los nuevos perfiles ligeros (`PERFIL-*.md`) + SIMCO reemplazan la necesidad de leerlos completos.

**Recomendación:**
1. Usar perfiles ligeros + SIMCO para trabajo diario
2. Consultar prompts extensos solo si necesitas detalle adicional

---

## MANTENIMIENTO

| Archivo | Actualizar Cuando |
|---------|-------------------|
| SIMCO-*.md | Cambian procesos universales |
| PRINCIPIO-*.md | Cambian principios fundamentales (raro) |
| PERFIL-*.md | Cambian responsabilidades de agentes |
| ALIASES.yml | Se agregan proyectos o rutas |

---

**Versión:** 2.2.0 | **Sistema:** SIMCO + CAPVED + Niveles + Tokens | **Mantenido por:** Tech Lead
