# SISTEMA SIMCO - ÍNDICE MAESTRO

**Single Instruction Matrix by Context and Operation**

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

---

## 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
    │   │   ├── _INDEX.md               ← ESTÁS AQUÍ
    │   │   ├── SIMCO-TAREA.md          # 🆕 CICLO CAPVED - Punto de entrada para HUs
    │   │   ├── SIMCO-INICIALIZACION.md # Bootstrap de agentes (CCA)
    │   │   ├── SIMCO-REUTILIZAR.md     # Reutilizar del catálogo
    │   │   ├── SIMCO-CONTRIBUIR-CATALOGO.md # 🆕 Contribuir al 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 (con CCA)
    │   │   ├── SIMCO-DDL.md            # Operaciones de base de datos
    │   │   ├── SIMCO-BACKEND.md        # Operaciones de backend NestJS
    │   │   ├── SIMCO-FRONTEND.md       # Operaciones de frontend React
    │   │   ├── SIMCO-NIVELES.md        # 🆕 Identificación de nivel jerárquico
    │   │   ├── SIMCO-PROPAGACION.md    # 🆕 Propagación de documentación
    │   │   └── SIMCO-QUICK-REFERENCE.md # 🆕 Referencia rápida (optimizado para tokens)
    │   │
    │   └── principios/                  # PRINCIPIOS FUNDAMENTALES (5)
    │       ├── 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
    │
    ├── agents/
    │   └── perfiles/                    # PERFILES LIGEROS + CCA
    │       ├── PERFIL-DATABASE.md      # PostgreSQL DDL - Incluye protocolo CCA
    │       ├── PERFIL-BACKEND.md       # NestJS/TypeORM - Incluye protocolo CCA
    │       ├── PERFIL-BACKEND-EXPRESS.md # Express.js/Prisma - Incluye protocolo CCA
    │       ├── PERFIL-FRONTEND.md      # React Web - Incluye protocolo CCA
    │       ├── PERFIL-MOBILE-AGENT.md  # React Native - Incluye protocolo CCA
    │       ├── PERFIL-ML-SPECIALIST.md # Python/ML/AI - Incluye protocolo CCA
    │       └── PERFIL-ORQUESTADOR.md   # Coordinación - Incluye protocolo CCA
    │
    ├── templates/
    │   ├── TEMPLATE-DELEGACION-SUBAGENTE.md  # Template con contexto heredado
    │   ├── 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
    │
    ├── 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
    │
    ├── _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 |
| **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 |

### 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
# 🆕 CAPVED - CICLO DE VIDA DE TAREAS
@CAPVED:     core/orchestration/directivas/principios/PRINCIPIO-CAPVED.md
@TAREA:      core/orchestration/directivas/simco/SIMCO-TAREA.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
@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

# Especializados por Dominio
@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 Jerárquicos
@NIVELES:     core/orchestration/directivas/simco/SIMCO-NIVELES.md
@PROPAGACION: core/orchestration/directivas/simco/SIMCO-PROPAGACION.md

# Templates de Contexto por Nivel
@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 (5 fundamentales)
@PRINCIPIOS: core/orchestration/directivas/principios/
@TOKENS:     core/orchestration/directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md

# Referencia rápida (optimizado para tokens)
@QUICK_REF:  core/orchestration/directivas/simco/SIMCO-QUICK-REFERENCE.md

# Inventarios (proyecto)
@INVENTORY:  orchestration/inventarios/MASTER_INVENTORY.yml

# Aliases completos
@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
