# HERENCIA DE DIRECTIVAS Y PROMPTS

**Versión:** 1.0.0
**Fecha:** 2025-12-05
**Propósito:** Documentar el sistema de herencia entre directivas/prompts globales y específicos de proyecto

---

## PRINCIPIO FUNDAMENTAL

```
┌─────────────────────────────────────────────────────────────────────────┐
│                    DIRECTIVAS Y PROMPTS GLOBALES                         │
│                      core/orchestration/                                 │
│  • Aplican a TODOS los proyectos                                         │
│  • NO mencionan proyecto específico                                      │
│  • Usan PLACEHOLDERS para paths: {PROJECT}, {DB_NAME}, etc.             │
│  • Definen QUÉ hacer (principios, estándares, flujos)                   │
└─────────────────────────────────────────────────────────────────────────┘
                               │
                               ▼ HEREDAN Y EXTIENDEN
┌─────────────────────────────────────────────────────────────────────────┐
│           DIRECTIVAS Y PROMPTS ESPECÍFICOS DE PROYECTO                   │
│             projects/{proyecto}/orchestration/                           │
│  • Aplican SOLO al proyecto específico                                   │
│  • PUEDEN sobrescribir directivas globales                              │
│  • Definen paths concretos, schemas, configuraciones del proyecto       │
│  • Resuelven placeholders usando CONTEXTO-PROYECTO.md                   │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## ESTRUCTURA DE ARCHIVOS

### Nivel Global (core/)

```
~/workspace/core/orchestration/
├── directivas/                         # Directivas globales
│   ├── DIRECTIVA-FLUJO-5-FASES.md
│   ├── DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md
│   ├── DIRECTIVA-POLITICA-CARGA-LIMPIA.md
│   ├── DIRECTIVA-DISENO-BASE-DATOS.md
│   ├── DIRECTIVA-CALIDAD-CODIGO.md
│   ├── DIRECTIVA-CONTROL-VERSIONES.md
│   ├── ESTANDARES-NOMENCLATURA-BASE.md
│   └── ...
├── agents/                             # INIT-NEXUS y prompts de agentes
│   ├── INIT-NEXUS-DATABASE.md
│   ├── INIT-NEXUS-BACKEND.md
│   ├── INIT-NEXUS-FRONTEND.md
│   ├── PROMPT-DATABASE-AGENT.md        # Versión con placeholders
│   ├── PROMPT-BACKEND-AGENT.md
│   ├── PROMPT-FRONTEND-AGENT.md
│   ├── PROMPT-SUBAGENTES.md
│   └── ...
├── prompts/
│   └── base/                           # Prompts base reutilizables
│       ├── PROMPT-SUBAGENTES-BASE.md
│       └── ...
├── templates/                          # Templates globales
├── checklists/                         # Checklists globales
└── HERENCIA-DIRECTIVAS-PROMPTS.md      # Este documento
```

### Nivel de Proyecto (projects/{proyecto}/)

```
~/workspace/projects/{proyecto}/orchestration/
├── 00-guidelines/
│   └── CONTEXTO-PROYECTO.md            # Variables para resolver placeholders
├── directivas/                         # Directivas específicas (sobrescriben)
│   ├── DIRECTIVA-DISENO-BASE-DATOS.md  # Extiende global con schemas específicos
│   ├── ESTANDARES-API-ROUTES.md        # Específico del proyecto
│   └── ...
├── prompts/                            # Prompts específicos (sobrescriben)
│   ├── PROMPT-DATABASE-AGENT.md        # Versión con valores concretos
│   ├── PROMPT-BACKEND-AGENT.md
│   └── ...
├── estados/
│   └── REGISTRO-SUBAGENTES.json
├── inventarios/
│   └── MASTER_INVENTORY.yml
└── trazas/
    └── TRAZA-TAREAS-*.md
```

---

## RESOLUCIÓN DE PLACEHOLDERS

### Variables Estándar

Los prompts globales usan estos placeholders que cada proyecto resuelve:

```yaml
# Variables de Proyecto
{PROJECT}:           Identificador del proyecto (ej: gamilit)
{PROJECT_NAME}:      Nombre descriptivo (ej: GAMILIT - Sistema de Gamificación)
{PROJECT_ROOT}:      ~/workspace/projects/{PROJECT}
{APPS_ROOT}:         ~/workspace/projects/{PROJECT}/apps
{DOCS_ROOT}:         ~/workspace/projects/{PROJECT}/docs
{ORCHESTRATION}:     ~/workspace/projects/{PROJECT}/orchestration

# Variables de Base de Datos
{DB_NAME}:           Nombre de la base de datos (ej: gamilit_platform)
{DB_DDL_PATH}:       Path a archivos DDL (ej: apps/database/ddl)
{DB_SCRIPTS_PATH}:   Path a scripts de BD (ej: apps/database)
{DB_SEEDS_PATH}:     Path a seeds (ej: apps/database/seeds)
{RECREATE_CMD}:      Comando de recreación (ej: drop-and-recreate-database.sh)
{AUTH_SCHEMA}:       Schema de autenticación (ej: auth_management)

# Variables de Backend
{BACKEND_ROOT}:      Path al backend (ej: apps/backend)
{BACKEND_SRC}:       Path a código fuente (ej: apps/backend/src)
{BACKEND_TESTS}:     Path a tests (ej: apps/backend/tests)

# Variables de Frontend
{FRONTEND_ROOT}:     Path al frontend (ej: apps/frontend)
{FRONTEND_SRC}:      Path a código fuente (ej: apps/frontend/src)
{FRONTEND_TESTS}:    Path a tests (ej: apps/frontend/tests)
```

### Ejemplo: CONTEXTO-PROYECTO.md de GAMILIT

```yaml
# orchestration/00-guidelines/CONTEXTO-PROYECTO.md

PROJECT:             gamilit
PROJECT_NAME:        GAMILIT
DB_NAME:             gamilit_platform
DB_DDL_PATH:         ~/workspace/projects/gamilit/apps/database/ddl
DB_SCRIPTS_PATH:     ~/workspace/projects/gamilit/apps/database
DB_SEEDS_PATH:       ~/workspace/projects/gamilit/apps/database/seeds
RECREATE_CMD:        drop-and-recreate-database.sh
AUTH_SCHEMA:         auth_management
BACKEND_ROOT:        ~/workspace/projects/gamilit/apps/backend
FRONTEND_ROOT:       ~/workspace/projects/gamilit/apps/frontend
```

---

## ORDEN DE PRECEDENCIA

Cuando un agente trabaja en un proyecto:

### 1. Lee Directivas Globales
```
core/orchestration/directivas/DIRECTIVA-*.md
```

### 2. Lee Directivas Específicas (si existen)
```
projects/{proyecto}/orchestration/directivas/DIRECTIVA-*.md
```

### 3. Aplica Regla de Override
```
En caso de conflicto: La directiva ESPECÍFICA tiene precedencia
```

### 4. Resuelve Placeholders
```
Usando: projects/{proyecto}/orchestration/00-guidelines/CONTEXTO-PROYECTO.md
```

---

## CASOS DE USO

### Caso 1: Directiva Global sin Override

**Ejemplo:** `DIRECTIVA-FLUJO-5-FASES.md`

- Existe solo en `core/orchestration/directivas/`
- Aplica igual a todos los proyectos
- No tiene placeholders que resolver

```
Agente lee: core/orchestration/directivas/DIRECTIVA-FLUJO-5-FASES.md
Aplica: Tal cual está escrita
```

### Caso 2: Directiva Global con Override Parcial

**Ejemplo:** `DIRECTIVA-DISENO-BASE-DATOS.md`

- Existe versión global en `core/orchestration/directivas/`
- Existe versión específica en `projects/gamilit/orchestration/directivas/`
- La específica EXTIENDE la global con schemas del proyecto

```
Agente lee:
1. core/orchestration/directivas/DIRECTIVA-DISENO-BASE-DATOS.md (principios generales)
2. projects/gamilit/orchestration/directivas/DIRECTIVA-DISENO-BASE-DATOS.md (schemas específicos)

Aplica: Principios globales + Schemas de GAMILIT
```

### Caso 3: Prompt con Placeholders

**Ejemplo:** `PROMPT-DATABASE-AGENT.md`

```
Prompt global:
  "Ejecutar: cd {DB_SCRIPTS_PATH} && ./{RECREATE_CMD}"

Contexto del proyecto:
  DB_SCRIPTS_PATH: apps/database
  RECREATE_CMD: drop-and-recreate-database.sh

Resolución:
  "Ejecutar: cd apps/database && ./drop-and-recreate-database.sh"
```

### Caso 4: Directiva Solo en Proyecto

**Ejemplo:** `ESTANDARES-API-ROUTES.md`

- Solo existe en `projects/gamilit/orchestration/directivas/`
- Es específica del proyecto (API REST de GAMILIT)
- No tiene versión global

```
Agente lee: projects/gamilit/orchestration/directivas/ESTANDARES-API-ROUTES.md
Aplica: Solo en proyecto GAMILIT
```

---

## FLUJO DE LECTURA DE UN AGENTE

```mermaid
graph TD
    A[Agente inicia tarea] --> B[Leer CONTEXTO-PROYECTO.md]
    B --> C[Obtener variables del proyecto]
    C --> D[Leer directivas globales]
    D --> E{¿Existen directivas específicas?}
    E -->|Sí| F[Leer directivas específicas]
    E -->|No| G[Usar solo globales]
    F --> H[Aplicar override donde corresponda]
    H --> I[Resolver placeholders con variables]
    G --> I
    I --> J[Ejecutar tarea]
```

---

## REGISTRO DE SUBAGENTES

El archivo `REGISTRO-SUBAGENTES.json` en cada proyecto contiene:

```json
{
  "referencias": {
    "prompts_base": "core/orchestration/agents/",
    "prompts_proyecto": "orchestration/prompts/",
    "directivas_globales": "core/orchestration/directivas/",
    "directivas_proyecto": "orchestration/directivas/",
    "contexto_proyecto": "orchestration/00-guidelines/CONTEXTO-PROYECTO.md"
  }
}
```

Cada subagente usa estas referencias para saber dónde buscar:
1. Prompts base (globales)
2. Prompts específicos del proyecto
3. Directivas globales
4. Directivas específicas
5. Variables de contexto

---

## PATRÓN DE EXTENSIÓN MÍNIMA (v2.0)

**PRINCIPIO:** Los prompts específicos de proyecto NO deben duplicar el contenido global. Solo deben contener:

1. **Referencia al prompt global** que extienden
2. **Resolución de variables** para el proyecto
3. **Extensiones específicas** que difieren del global

### Estructura de Archivo de Extensión

```markdown
# PROMPT {AGENT}-AGENT - EXTENSIÓN {PROYECTO}

**Versión:** 2.0.0
**Tipo:** Extensión de prompt global

---

## HERENCIA

```yaml
EXTIENDE: core/orchestration/agents/PROMPT-{AGENT}-AGENT.md
CONTEXTO: orchestration/00-guidelines/CONTEXTO-PROYECTO.md
```

**IMPORTANTE:** Este archivo NO duplica el prompt global. Solo contiene:
1. Resolución de variables para {PROYECTO}
2. Extensiones específicas del proyecto (si las hay)

---

## RESOLUCIÓN DE VARIABLES PARA {PROYECTO}

```yaml
{PROJECT_NAME}:    {Valor}
{DB_NAME}:         {Valor}
...
```

---

## EXTENSIONES ESPECÍFICAS

[Solo lo que difiere del global]

---

## FLUJO DE INICIO

1. Leer prompt global
2. Leer este archivo para resolver variables
3. Leer contexto del proyecto
4. Listo para tarea
```

### Comparación: Antes vs Después

| Aspecto | Antes (Duplicación) | Después (Extensión Mínima) |
|---------|---------------------|----------------------------|
| Líneas de código | ~600-800 líneas | ~100-180 líneas |
| Mantenimiento | Duplicar cambios en cada proyecto | Cambio en `core/` aplica a todos |
| Consistencia | Riesgo de divergencia | Garantizada por herencia |
| Contenido | Todo el prompt completo | Solo variables + extensiones |

### Ejemplo Real: Database-Agent

**Global** (`core/orchestration/agents/PROMPT-DATABASE-AGENT.md`):
- ~868 líneas
- Contiene: flujo de 5 fases, estándares DDL, ejemplos, matrices de delegación
- Usa placeholders: `{DB_NAME}`, `{DB_DDL_PATH}`, `{RECREATE_CMD}`

**Extensión GAMILIT** (`projects/gamilit/orchestration/prompts/PROMPT-DATABASE-AGENT.md`):
- ~138 líneas
- Contiene: resolución de variables, lista de schemas, rutas específicas, sistema Maya
- NO duplica: flujo de fases, estándares, ejemplos genéricos

---

## BUENAS PRÁCTICAS

### Para Prompts Globales (core/)

1. **Usar placeholders** para todos los paths
2. **NO mencionar** proyectos específicos
3. **Documentar** las variables requeridas al inicio
4. **Incluir sección** de "Uso en Proyectos Específicos"

### Para Prompts Específicos (projects/)

1. **Usar el patrón de extensión mínima** (NO duplicar)
2. **Indicar claramente** que extiende un prompt global con `EXTIENDE:`
3. **Resolver** los placeholders a valores concretos
4. **Agregar SOLO** las secciones que difieren del global
5. **Referenciar** el contexto del proyecto

### Para Directivas Globales

1. **Ser genéricos** en ejemplos
2. **Usar** `{schema}`, `{tabla}`, `{proyecto}` en lugar de valores concretos
3. **Documentar** el principio, no la implementación específica

### Para Directivas Específicas

1. **Comenzar con** "EXTIENDE: {directiva global}"
2. **Listar** valores concretos (schemas, tablas, rutas)
3. **Incluir** ejemplos específicos del proyecto

---

## VALIDACIÓN DE HERENCIA

Script de validación recomendado:

```bash
#!/bin/bash
# validate-inheritance.sh

PROJECT=$1

echo "Validando herencia para proyecto: $PROJECT"

# 1. Verificar que existe CONTEXTO-PROYECTO.md
if [ ! -f "projects/$PROJECT/orchestration/00-guidelines/CONTEXTO-PROYECTO.md" ]; then
    echo "ERROR: Falta CONTEXTO-PROYECTO.md"
    exit 1
fi

# 2. Verificar que directivas específicas referencian globales
for file in projects/$PROJECT/orchestration/directivas/*.md; do
    if [ -f "$file" ]; then
        if ! grep -q "EXTIENDE:" "$file" && ! grep -q "ESPECÍFICO:" "$file"; then
            echo "WARNING: $file no indica si extiende o es específico"
        fi
    fi
done

# 3. Verificar que prompts específicos tienen variables resueltas
for file in projects/$PROJECT/orchestration/prompts/*.md; do
    if [ -f "$file" ]; then
        if grep -q "{PROJECT_NAME}\|{DB_NAME}\|{DB_DDL_PATH}" "$file"; then
            echo "WARNING: $file tiene placeholders sin resolver"
        fi
    fi
done

echo "Validación completada"
```

---

## REFERENCIAS

- **MAPEO-SEPARACION-DIRECTIVAS.md** - Mapeo completo de directivas
- **ANALISIS-VALIDACION-PROMPTS-ARQUITECTURA.md** - Análisis de equivalencia

---

**Versión:** 2.0.0
**Fecha:** 2025-12-05
**Última actualización:** 2025-12-05 - Agregado patrón de extensión mínima
**Mantenido por:** Tech Lead
