# GUIA DE MIGRACION A SIMCO + CAPVED

**Versión:** 1.2.0
**Fecha:** 2025-12-08
**Propósito:** Guía paso a paso para migrar del sistema legacy al sistema SIMCO + CAPVED + Economía de Tokens

---

## RESUMEN EJECUTIVO

### Problema Original

Los agentes ignoraban directivas cuando realizaban tareas fuera de su perfil principal porque:

1. **Directivas embebidas en prompts**: Cada prompt de agente contenía 700-850+ líneas con ~40% duplicación
2. **Sin herencia cross-profile**: Un Backend-Agent haciendo tareas de DDL no tenía acceso a directivas de Database
3. **Sin sistema de navegación**: No existían aliases para referencias cruzadas entre proyectos
4. **Inconsistencia**: Cada perfil definía reglas ligeramente diferentes para las mismas operaciones

### Solución SIMCO

**Single Instruction Matrix by Context and Operation** reorganiza directivas por **tipo de operación**, permitiendo que cualquier agente siga las directivas correctas independientemente de su especialización.

---

## ANTES vs DESPUÉS

### Estructura Anterior (Legacy)

```
agents/
├── PROMPT-DATABASE-AGENT.md      # ~850 líneas, directivas embebidas
├── PROMPT-BACKEND-AGENT.md       # ~780 líneas, ~40% duplicado
├── PROMPT-FRONTEND-AGENT.md      # ~720 líneas, ~40% duplicado
└── PROMPT-TECH-LEADER.md         # ~600 líneas

directivas/
├── DIRECTIVA-*.md                # 20+ archivos, sin organización clara
└── ...
```

**Problemas:**
- Backend-Agent creando DDL → No lee directivas de Database
- Frontend-Agent documentando → Cada uno tiene reglas diferentes
- Mantenimiento: actualizar 1 regla = modificar N archivos

### Estructura Nueva (SIMCO)

```
directivas/
├── simco/                        # POR OPERACIÓN
│   ├── _INDEX.md                 # Índice maestro
│   ├── SIMCO-CREAR.md           # Crear cualquier archivo
│   ├── SIMCO-MODIFICAR.md       # Modificar existentes
│   ├── SIMCO-VALIDAR.md         # Build, lint, tests
│   ├── SIMCO-DOCUMENTAR.md      # Documentar trabajo
│   ├── SIMCO-BUSCAR.md          # Buscar archivos/info
│   ├── SIMCO-DELEGACION.md      # Delegar a subagentes
│   ├── SIMCO-DDL.md             # Operaciones PostgreSQL
│   ├── SIMCO-BACKEND.md         # Operaciones NestJS
│   └── SIMCO-FRONTEND.md        # Operaciones React
│
└── 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   # 🆕 Desglose de tareas

agents/perfiles/                  # PERFILES LIGEROS (~100 líneas)
├── PERFIL-DATABASE.md
├── PERFIL-BACKEND.md
├── PERFIL-FRONTEND.md
└── PERFIL-ORQUESTADOR.md

referencias/
└── ALIASES.yml                   # Sistema de aliases
```

**Beneficios:**
- Backend-Agent creando DDL → Lee `SIMCO-CREAR.md` + `SIMCO-DDL.md`
- Frontend-Agent documentando → Lee `SIMCO-DOCUMENTAR.md` (mismo que todos)
- Mantenimiento: actualizar 1 regla = modificar 1 archivo

---

## PASOS DE MIGRACIÓN

### Paso 1: Entender el Sistema SIMCO + CAPVED

**Lectura obligatoria:**
```
1. directivas/simco/_INDEX.md               # Qué es SIMCO, cómo funciona
2. directivas/principios/PRINCIPIO-CAPVED.md # Ciclo de vida de tareas
3. directivas/principios/*.md               # Los 5 principios fundamentales
4. directivas/simco/SIMCO-TAREA.md          # Punto de entrada para HUs
5. directivas/simco/SIMCO-QUICK-REFERENCE.md # 🆕 Referencia rápida (optimizado)
6. referencias/ALIASES.yml                  # Sistema de aliases
```

### Paso 2: Identificar Tu Perfil

| Si eres... | Lee primero |
|------------|-------------|
| Database-Agent | `agents/perfiles/PERFIL-DATABASE.md` |
| Backend-Agent | `agents/perfiles/PERFIL-BACKEND.md` |
| Frontend-Agent | `agents/perfiles/PERFIL-FRONTEND.md` |
| Tech-Leader | `agents/perfiles/PERFIL-ORQUESTADOR.md` |

### Paso 3: Seguir SIMCO según Operación

**Cuando vayas a CREAR algo:**
```
1. Leer @PRINCIPIOS (siempre)
2. Leer SIMCO-CREAR.md (operación crear)
3. Leer SIMCO-{DDL|BACKEND|FRONTEND}.md (según dominio)
4. Seguir checklist
```

**Cuando vayas a MODIFICAR algo:**
```
1. Leer @PRINCIPIOS (siempre)
2. Leer SIMCO-MODIFICAR.md (operación modificar)
3. Leer SIMCO-{dominio}.md si aplica
4. Seguir checklist
```

**Cuando vayas a VALIDAR:**
```
1. Leer SIMCO-VALIDAR.md
2. Ejecutar validaciones según capa
```

### Paso 4: Usar Aliases

Los aliases simplifican la navegación. Ejemplos:

```yaml
# En lugar de escribir rutas completas:
"core/orchestration/directivas/simco/SIMCO-CREAR.md"

# Usa aliases:
@CREAR

# Para archivos de proyecto:
@INVENTORY  → orchestration/inventarios/MASTER_INVENTORY.yml
@DDL        → {DB_DDL_PATH}/schemas/
@BACKEND    → {BACKEND_SRC}/modules/
```

---

## MAPEO: LEGACY → SIMCO

### Directivas Legacy → SIMCO Equivalente

| Directiva Legacy | Equivalente SIMCO |
|------------------|-------------------|
| DIRECTIVA-VALIDACION-DOCUMENTACION.md | PRINCIPIO-DOC-PRIMERO.md |
| DIRECTIVA-ANALISIS-IMPACTO-DEPENDENCIAS.md | PRINCIPIO-ANTI-DUPLICACION.md |
| DIRECTIVA-FLUJO-5-FASES.md | SIMCO-VALIDAR.md + SIMCO-DOCUMENTAR.md |
| DIRECTIVA-POLITICA-CARGA-LIMPIA.md | SIMCO-DDL.md |
| GUIA-ORQUESTACION.md | SIMCO-DELEGACION.md |
| PROCESO-VALIDACION.md | SIMCO-VALIDAR.md |
| ESTANDARES-NOMENCLATURA-BASE.md | SIMCO-CREAR.md (sección nomenclatura) |
| POLITICAS-MODULARIZACION.md | SIMCO-CREAR.md |
| DELIMITACION-PERFILES.md | agents/perfiles/PERFIL-*.md |

### Prompts Legacy → Perfiles SIMCO

| Prompt Legacy | Perfil SIMCO | Tamaño |
|---------------|--------------|--------|
| PROMPT-DATABASE-AGENT.md (~850L) | PERFIL-DATABASE.md | ~100L |
| PROMPT-BACKEND-AGENT.md (~780L) | PERFIL-BACKEND.md | ~100L |
| PROMPT-FRONTEND-AGENT.md (~720L) | PERFIL-FRONTEND.md | ~100L |
| PROMPT-TECH-LEADER.md (~600L) | PERFIL-ORQUESTADOR.md | ~100L |

---

## ESCENARIOS DE USO

### Escenario 1: Backend-Agent necesita crear DDL

**Antes (Legacy):**
```
Backend-Agent recibe tarea que requiere tabla nueva
→ No tiene directivas de DDL en su prompt
→ Crea DDL de forma inconsistente o incorrecta
→ Errores de alineación Entity/DDL
```

**Ahora (SIMCO):**
```
Backend-Agent recibe tarea que requiere tabla nueva
→ Lee @PRINCIPIOS (verifica docs/, anti-duplicación)
→ Lee @CREAR + @OP_DDL (directivas para crear DDL)
→ Sigue checklist de SIMCO-DDL.md
→ DDL correcto, alineado con estándares
```

### Escenario 2: Frontend-Agent documentando trabajo

**Antes (Legacy):**
```
Frontend-Agent termina componente
→ Cada prompt tiene sección de documentación diferente
→ Documentación inconsistente entre agentes
```

**Ahora (SIMCO):**
```
Frontend-Agent termina componente
→ Lee @DOCUMENTAR (SIMCO-DOCUMENTAR.md)
→ Mismo formato que cualquier otro agente
→ Documentación consistente
```

### Escenario 3: Tech-Leader delegando a subagentes

**Antes (Legacy):**
```
Tech-Leader delega a Database-Agent
→ No hay template estándar de delegación
→ Subagente recibe contexto incompleto
→ Subagente ignora directivas importantes
```

**Ahora (SIMCO):**
```
Tech-Leader delega a Database-Agent
→ Lee @DELEGAR (SIMCO-DELEGACION.md)
→ Usa template estándar con:
  - Principios a leer
  - SIMCO relevantes
  - Variables resueltas
  - Criterios de aceptación
→ Subagente tiene todo el contexto necesario
```

---

## CHECKLIST DE MIGRACIÓN PARA PROYECTOS

Al migrar un proyecto existente al sistema SIMCO:

```markdown
### Preparación
- [ ] Leer directivas/simco/_INDEX.md
- [ ] Entender sistema de aliases (referencias/ALIASES.yml)
- [ ] Identificar perfiles de agentes en uso

### Crear CONTEXTO-PROYECTO.md
- [ ] Copiar template de templates/TEMPLATE-CONTEXTO-PROYECTO.md
- [ ] Colocar en projects/{proyecto}/orchestration/00-guidelines/
- [ ] Resolver todos los {PLACEHOLDER}
- [ ] Definir SCHEMAS del proyecto
- [ ] Definir MODULES del backend
- [ ] Definir APPS del frontend
- [ ] Completar sección de ALIAS RESUELTOS

### Actualizar Inventarios
- [ ] Verificar MASTER_INVENTORY.yml existe
- [ ] Verificar DATABASE_INVENTORY.yml existe
- [ ] Verificar BACKEND_INVENTORY.yml existe
- [ ] Verificar FRONTEND_INVENTORY.yml existe

### Actualizar Trazas
- [ ] Verificar TRAZA-TAREAS-DATABASE.md existe
- [ ] Verificar TRAZA-TAREAS-BACKEND.md existe
- [ ] Verificar TRAZA-TAREAS-FRONTEND.md existe

### Validar Migración
- [ ] Ejecutar build en todas las capas
- [ ] Ejecutar lint en todas las capas
- [ ] Verificar que agentes pueden navegar con aliases
```

---

## PREGUNTAS FRECUENTES

### ¿Los prompts legacy siguen siendo válidos?

Sí, los prompts legacy (`PROMPT-*-AGENT.md`) siguen disponibles como **referencia extendida**. Contienen detalles adicionales que pueden ser útiles en casos específicos. Sin embargo, para trabajo diario, usar **perfiles ligeros + SIMCO** es más eficiente.

### ¿Qué pasa si necesito una directiva que no está en SIMCO?

1. Verificar si la directiva legacy sigue siendo necesaria
2. Si es necesaria, proponer incluirla en el SIMCO correspondiente
3. Si es muy específica, documentarla en el CONTEXTO-PROYECTO.md del proyecto

### ¿Cómo actualizo una directiva SIMCO?

Los SIMCO son centralizados. Cambiar un SIMCO afecta a TODOS los agentes. Antes de modificar:

1. Verificar que el cambio es universalmente aplicable
2. Si es específico de un proyecto, NO modificar SIMCO, usar CONTEXTO-PROYECTO.md
3. Actualizar versión en el archivo modificado
4. Documentar cambio en changelog

### ¿Puedo agregar aliases específicos de proyecto?

Sí. En el CONTEXTO-PROYECTO.md de cada proyecto se definen los aliases resueltos con valores específicos:

```yaml
# En CONTEXTO-PROYECTO.md de GAMILIT:
@DDL: "apps/database/ddl/schemas/"
@BACKEND: "apps/backend/src/modules/"
```

---

## SOPORTE Y MANTENIMIENTO

### Archivos a Actualizar por Tipo de Cambio

| Tipo de Cambio | Archivos a Modificar |
|----------------|----------------------|
| Nuevo principio universal | principios/PRINCIPIO-*.md |
| Nueva operación | simco/SIMCO-*.md |
| Cambio en perfil de agente | agents/perfiles/PERFIL-*.md |
| Nuevo proyecto | templates/TEMPLATE-CONTEXTO-PROYECTO.md (copiar) |
| Nuevo alias global | referencias/ALIASES.yml |

### Versionado

- **SIMCO principal:** Version 1.0.0
- **Cada archivo SIMCO** tiene su propia versión
- **Cambios mayores** incrementan versión mayor (1.0 → 2.0)
- **Cambios menores** incrementan versión menor (1.0 → 1.1)

---

## PRÓXIMOS PASOS RECOMENDADOS

1. **Inmediato:** Leer `simco/_INDEX.md` y los **5 principios** (incluyendo CAPVED y Tokens)
2. **Para HUs/Tareas:** Leer `simco/SIMCO-TAREA.md` (punto de entrada CAPVED)
3. **Para consulta rápida:** Usar `simco/SIMCO-QUICK-REFERENCE.md` (optimizado para tokens)
4. **Para agentes:** Leer tu perfil en `agents/perfiles/`
5. **Para proyectos:** Crear `CONTEXTO-PROYECTO.md` basado en template
6. **Continuo:** Usar aliases para navegación consistente

---

**Creado:** 2025-12-08
**Autor:** Sistema NEXUS
**Versión:** 1.2.0
**Sistema:** SIMCO + CAPVED + Economía de Tokens
**Cambios v1.2.0:** Integración del principio ECONOMIA-TOKENS (5º principio), SIMCO-QUICK-REFERENCE.md.
**Cambios v1.1.0:** Integración del principio CAPVED (4º principio), SIMCO-TAREA.md como punto de entrada.
