# 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