# Analisis del Sistema de Orquestacion de Agentes

**Fecha:** 2025-12-05
**Objetivo:** Identificar componentes generalizables vs especificos para implementar sistema de orquestacion a nivel workspace

---

## 1. RESUMEN EJECUTIVO

El sistema de orquestacion de Gamilit es un sistema maduro y probado que incluye:
- **19 directivas** detalladas
- **14 prompts** para diferentes tipos de agentes
- **4 templates** para contexto y validacion
- **Sistema de trazabilidad** completo con inventarios, estados y reportes
- **Flujo de 5 fases** obligatorio para toda tarea

### Hallazgos Principales

| Categoria | Archivos | Generalizable | Especifico |
|-----------|----------|---------------|------------|
| Directivas | 19 | 15 (79%) | 4 (21%) |
| Prompts | 14 | 8 (57%) | 6 (43%) |
| Templates | 4 | 4 (100%) | 0 |
| Estados/Inventarios | 8 | Estructura | Contenido |

---

## 2. CLASIFICACION DETALLADA

### 2.1 DIRECTIVAS - Generalizables a Workspace

Estas directivas aplican a CUALQUIER proyecto:

| Directiva | Descripcion | Razon de Generalizacion |
|-----------|-------------|------------------------|
| `DIRECTIVA-FLUJO-5-FASES.md` | Flujo obligatorio de trabajo | Metodologia universal |
| `DIRECTIVA-VALIDACION-SUBAGENTES.md` | Proceso de validacion de subagentes | Calidad universal |
| `DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md` | Que y cuando documentar | Estandar de documentacion |
| `DIRECTIVA-CALIDAD-CODIGO.md` | Estandares de calidad | Aplicable a todo codigo |
| `DIRECTIVA-CONTROL-VERSIONES.md` | Git, branches, commits | Universal |
| `DIRECTIVA-GESTION-BACKUPS-GITIGNORE.md` | Manejo de backups y exclusiones | Universal |
| `POLITICAS-USO-AGENTES.md` | Cuando usar agentes/subagentes | Metodologia de orquestacion |
| `PROTOCOLO-ESCALAMIENTO-PO.md` | Cuando escalar a Product Owner | Proceso de escalamiento |
| `SISTEMA-RETROALIMENTACION-MEJORA-CONTINUA.md` | Mejora continua del sistema | Proceso de mejora |
| `ESTANDARES-NOMENCLATURA.md` | Convenciones de nombres | Generalizable con variables |
| `GUIA-NOMENCLATURA-COMPLETA.md` | Guia detallada de nombres | Complemento a estandares |
| `CHECKLIST-CODE-REVIEW-API.md` | Checklist para revision de codigo | Universal |
| `CHECKLIST-REFACTORIZACION.md` | Proceso de refactoring | Universal |
| `AUTOMATIZACION-VALIDACION-RUTAS.md` | Validacion automatica | Universal |
| `PITFALLS-API-ROUTES.md` | Errores comunes en APIs | Universal |

### 2.2 DIRECTIVAS - Especificas del Proyecto

Estas directivas contienen informacion especifica de Gamilit:

| Directiva | Contenido Especifico | Como Generalizar |
|-----------|---------------------|------------------|
| `DIRECTIVA-DISENO-BASE-DATOS.md` | Schemas de Gamilit, PostGIS, funciones | Crear plantilla con variables |
| `DIRECTIVA-POLITICA-CARGA-LIMPIA.md` | Scripts especificos, paths | Generalizar principios |
| `ESTANDARES-API-ROUTES.md` | Rutas de Gamilit | Crear como template |
| `ESTANDARES-TESTING-API.md` | Tests especificos | Generalizar estructura |

### 2.3 PROMPTS - Generalizables a Workspace

Estos prompts pueden usarse en cualquier proyecto:

| Prompt | Descripcion | Adaptacion Necesaria |
|--------|-------------|---------------------|
| `PROMPT-SUBAGENTES.md` | Guia completa para subagentes | Solo cambiar paths de proyecto |
| `PROMPT-BUG-FIXER.md` | Diagnostico y correccion de bugs | Universal |
| `PROMPT-CODE-REVIEWER.md` | Revision de codigo | Universal |
| `PROMPT-FEATURE-DEVELOPER.md` | Desarrollo de features E2E | Universal |
| `PROMPT-POLICY-AUDITOR.md` | Auditoria de cumplimiento | Universal |
| `PROMPT-DOCUMENTATION-VALIDATOR.md` | Validacion de documentacion | Universal |
| `PROMPT-REQUIREMENTS-ANALYST.md` | Analisis de requerimientos | Universal |
| `PROMPT-WORKSPACE-MANAGER.md` | Gestion del workspace | Universal |

### 2.4 PROMPTS - Especificos del Proyecto

Estos prompts contienen informacion especifica:

| Prompt | Contenido Especifico | Como Adaptar |
|--------|---------------------|--------------|
| `PROMPT-ARCHITECTURE-ANALYST.md` | Referencias a docs de Gamilit | Parametrizar rutas |
| `PROMPT-DATABASE-AGENT.md` | Schemas, tablas de Gamilit | Template con variables |
| `PROMPT-DATABASE-AUDITOR.md` | Validaciones especificas | Template con variables |
| `PROMPT-BACKEND-AGENT.md` | Modulos NestJS de Gamilit | Template con variables |
| `PROMPT-FRONTEND-AGENT.md` | Componentes de Gamilit | Template con variables |

### 2.5 TEMPLATES - Todos Generalizables

| Template | Uso | Adaptacion |
|----------|-----|------------|
| `TEMPLATE-CONTEXTO-SUBAGENTE.md` | Contexto para subagentes | Solo variables de proyecto |
| `TEMPLATE-ANALISIS.md` | Formato de analisis | Universal |
| `TEMPLATE-PLAN.md` | Formato de plan | Universal |
| `TEMPLATE-VALIDACION.md` | Formato de validacion | Universal |

---

## 3. ARQUITECTURA PROPUESTA

### 3.1 Estructura de Directorios

```
~/workspace/
├── core/
│   └── orchestration/
│       ├── directivas/                    # DIRECTIVAS GLOBALES
│       │   ├── DIRECTIVA-FLUJO-5-FASES.md
│       │   ├── DIRECTIVA-VALIDACION-SUBAGENTES.md
│       │   ├── DIRECTIVA-CALIDAD-CODIGO.md
│       │   ├── DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md
│       │   ├── DIRECTIVA-CONTROL-VERSIONES.md
│       │   ├── DIRECTIVA-GESTION-BACKUPS-GITIGNORE.md
│       │   ├── POLITICAS-USO-AGENTES.md
│       │   ├── PROTOCOLO-ESCALAMIENTO-PO.md
│       │   ├── SISTEMA-RETROALIMENTACION.md
│       │   └── ESTANDARES-NOMENCLATURA-BASE.md
│       │
│       ├── prompts/                       # PROMPTS GENERICOS
│       │   ├── base/                      # Prompts base (sin proyecto)
│       │   │   ├── PROMPT-SUBAGENTES-BASE.md
│       │   │   ├── PROMPT-BUG-FIXER.md
│       │   │   ├── PROMPT-CODE-REVIEWER.md
│       │   │   ├── PROMPT-FEATURE-DEVELOPER.md
│       │   │   ├── PROMPT-POLICY-AUDITOR.md
│       │   │   ├── PROMPT-DOCUMENTATION-VALIDATOR.md
│       │   │   ├── PROMPT-REQUIREMENTS-ANALYST.md
│       │   │   └── PROMPT-WORKSPACE-MANAGER.md
│       │   │
│       │   └── templates/                 # Templates para agentes especificos
│       │       ├── TEMPLATE-PROMPT-DATABASE-AGENT.md
│       │       ├── TEMPLATE-PROMPT-BACKEND-AGENT.md
│       │       ├── TEMPLATE-PROMPT-FRONTEND-AGENT.md
│       │       └── TEMPLATE-PROMPT-ARCHITECTURE-ANALYST.md
│       │
│       ├── templates/                     # TEMPLATES DE DOCUMENTACION
│       │   ├── TEMPLATE-CONTEXTO-SUBAGENTE.md
│       │   ├── TEMPLATE-ANALISIS.md
│       │   ├── TEMPLATE-PLAN.md
│       │   ├── TEMPLATE-VALIDACION.md
│       │   ├── TEMPLATE-INVENTARIO.yml
│       │   ├── TEMPLATE-TRAZA.md
│       │   └── TEMPLATE-ESTADO.json
│       │
│       ├── checklists/                    # CHECKLISTS REUTILIZABLES
│       │   ├── CHECKLIST-CODE-REVIEW-API.md
│       │   ├── CHECKLIST-REFACTORIZACION.md
│       │   ├── CHECKLIST-VALIDACION-SUBAGENTES.md
│       │   └── CHECKLIST-PRE-COMMIT.md
│       │
│       └── README.md                      # Guia del sistema de orquestacion
│
└── projects/
    └── {proyecto}/
        └── orchestration/
            ├── 00-guidelines/             # DIRECTIVAS ESPECIFICAS DEL PROYECTO
            │   ├── CONTEXTO-PROYECTO.md   # Contexto especifico
            │   └── DIRECTIVAS-PROYECTO.md # Directivas especificas
            │
            ├── directivas/                # Override de directivas globales
            │   ├── DIRECTIVA-DISENO-BASE-DATOS.md
            │   ├── DIRECTIVA-POLITICA-CARGA-LIMPIA.md
            │   └── ESTANDARES-NOMENCLATURA-{PROYECTO}.md
            │
            ├── prompts/                   # Prompts especificos del proyecto
            │   ├── PROMPT-DATABASE-AGENT.md
            │   ├── PROMPT-BACKEND-AGENT.md
            │   ├── PROMPT-FRONTEND-AGENT.md
            │   └── PROMPT-ARCHITECTURE-ANALYST.md
            │
            ├── agentes/                   # Trabajo de agentes
            │   ├── database/
            │   ├── backend/
            │   ├── frontend/
            │   └── ...
            │
            ├── estados/                   # Estados actuales
            │   ├── ESTADO-GENERAL.json
            │   ├── ESTADO-DATABASE.json
            │   ├── ESTADO-BACKEND.json
            │   ├── ESTADO-FRONTEND.json
            │   └── REGISTRO-SUBAGENTES.json
            │
            ├── inventarios/               # Inventarios del proyecto
            │   ├── MASTER_INVENTORY.yml
            │   ├── DATABASE_INVENTORY.yml
            │   ├── BACKEND_INVENTORY.yml
            │   └── FRONTEND_INVENTORY.yml
            │
            ├── trazas/                    # Trazabilidad
            │   ├── TRAZA-TAREAS-DATABASE.md
            │   ├── TRAZA-TAREAS-BACKEND.md
            │   ├── TRAZA-TAREAS-FRONTEND.md
            │   └── ...
            │
            └── reportes/                  # Reportes generados
```

### 3.2 Principio de Herencia

```
WORKSPACE (core/orchestration/)
    │
    │  Directivas globales + Prompts base + Templates
    │
    ▼
PROYECTO (projects/{proyecto}/orchestration/)
    │
    │  Hereda todo de workspace +
    │  Puede OVERRIDE directivas +
    │  DEBE definir prompts especificos +
    │  Mantiene estados/inventarios/trazas propios
```

### 3.3 Composicion de Prompts

Al invocar un subagente, el prompt se compone de:

```yaml
PROMPT_COMPLETO:
  # 1. Directivas globales del workspace
  - core/orchestration/directivas/DIRECTIVA-FLUJO-5-FASES.md
  - core/orchestration/directivas/DIRECTIVA-VALIDACION-SUBAGENTES.md
  - core/orchestration/directivas/DIRECTIVA-CALIDAD-CODIGO.md

  # 2. Directivas especificas del proyecto
  - projects/{proyecto}/orchestration/directivas/DIRECTIVA-DISENO-BASE-DATOS.md
  - projects/{proyecto}/orchestration/directivas/DIRECTIVA-POLITICA-CARGA-LIMPIA.md

  # 3. Prompt base del agente
  - core/orchestration/prompts/base/PROMPT-SUBAGENTES-BASE.md

  # 4. Prompt especifico del proyecto
  - projects/{proyecto}/orchestration/prompts/PROMPT-DATABASE-AGENT.md

  # 5. Contexto de la tarea especifica
  - Tarea ID, objetivo, especificaciones, archivos de referencia, etc.
```

---

## 4. VARIABLES Y PLACEHOLDERS

### 4.1 Variables de Proyecto

Para hacer los templates reutilizables, usar estas variables:

```yaml
VARIABLES_PROYECTO:
  # Identificacion
  PROJECT_NAME: "gamilit"                    # Nombre del proyecto
  PROJECT_TYPE: "edtech"                     # Tipo: saas, erp, analytics, edtech
  PROJECT_PATH: "~/workspace/projects/gamilit"

  # Stack tecnologico
  BACKEND_FRAMEWORK: "NestJS"
  FRONTEND_FRAMEWORK: "React"
  DATABASE_TYPE: "PostgreSQL"
  ORM: "TypeORM"

  # Rutas clave
  APPS_PATH: "apps/"
  BACKEND_PATH: "apps/backend/"
  FRONTEND_PATH: "apps/frontend/"
  DATABASE_PATH: "apps/database/"
  DOCS_PATH: "docs/"
  ORCHESTRATION_PATH: "orchestration/"

  # Schemas de base de datos
  DB_SCHEMAS:
    - auth_management
    - gamification_system
    - educational_content
    # ... especificos del proyecto

  # Modulos de backend
  BACKEND_MODULES:
    - auth
    - users
    - gamification
    # ... especificos del proyecto
```

### 4.2 Uso en Templates

```markdown
# PROMPT PARA DATABASE-AGENT - {PROJECT_NAME}

## Contexto del Proyecto
- **Proyecto:** {PROJECT_NAME}
- **Tipo:** {PROJECT_TYPE}
- **Base de datos:** {DATABASE_TYPE}

## Schemas Disponibles
{foreach DB_SCHEMAS as schema}
- {schema}
{endforeach}

## Rutas de Trabajo
- DDL: {DATABASE_PATH}ddl/
- Seeds: {DATABASE_PATH}seeds/
- Scripts: {DATABASE_PATH}scripts/
```

---

## 5. MEMORIA PERSISTENTE PARA AGENTES

### 5.1 Bloque Estandar de Memoria

Todo prompt de agente debe incluir este bloque:

```yaml
MEMORIA_PERSISTENTE:
  version: "2.0.0"
  principio_fundamental: "DOCUMENTACION PRIMERO, IMPLEMENTACION DESPUES"

  # Directivas globales (siempre aplicables)
  directivas_globales:
    flujo_5_fases: "core/orchestration/directivas/DIRECTIVA-FLUJO-5-FASES.md"
    validacion_subagentes: "core/orchestration/directivas/DIRECTIVA-VALIDACION-SUBAGENTES.md"
    calidad_codigo: "core/orchestration/directivas/DIRECTIVA-CALIDAD-CODIGO.md"
    documentacion: "core/orchestration/directivas/DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md"
    politicas_agentes: "core/orchestration/directivas/POLITICAS-USO-AGENTES.md"

  # Directivas del proyecto (especificas)
  directivas_proyecto:
    carga_limpia: "{ORCHESTRATION_PATH}directivas/DIRECTIVA-POLITICA-CARGA-LIMPIA.md"
    diseno_bd: "{ORCHESTRATION_PATH}directivas/DIRECTIVA-DISENO-BASE-DATOS.md"
    nomenclatura: "{ORCHESTRATION_PATH}directivas/ESTANDARES-NOMENCLATURA-{PROJECT_NAME}.md"

  # Prompts de agentes (proyecto)
  prompts:
    database_agent: "{ORCHESTRATION_PATH}prompts/PROMPT-DATABASE-AGENT.md"
    backend_agent: "{ORCHESTRATION_PATH}prompts/PROMPT-BACKEND-AGENT.md"
    frontend_agent: "{ORCHESTRATION_PATH}prompts/PROMPT-FRONTEND-AGENT.md"

  # Inventarios
  inventarios:
    master: "{ORCHESTRATION_PATH}inventarios/MASTER_INVENTORY.yml"
    database: "{ORCHESTRATION_PATH}inventarios/DATABASE_INVENTORY.yml"
    backend: "{ORCHESTRATION_PATH}inventarios/BACKEND_INVENTORY.yml"
    frontend: "{ORCHESTRATION_PATH}inventarios/FRONTEND_INVENTORY.yml"

  # Trazas
  trazas:
    database: "{ORCHESTRATION_PATH}trazas/TRAZA-TAREAS-DATABASE.md"
    backend: "{ORCHESTRATION_PATH}trazas/TRAZA-TAREAS-BACKEND.md"
    frontend: "{ORCHESTRATION_PATH}trazas/TRAZA-TAREAS-FRONTEND.md"

  # 5 Fases (recordatorio)
  fases_obligatorias:
    fase_1: "ANALISIS - Validar docs/, mapear objetos, dependencias 3 niveles"
    fase_2: "PLANEACION - docs/ primero, tareas, asignar agentes"
    fase_3: "VALIDACION PLAN - NO DELEGAR, comparar plan vs analisis"
    fase_4: "EJECUCION - Actualizar docs/ PRIMERO, orquestar agentes"
    fase_5: "VALIDACION EJECUCION - NO DELEGAR, build, lint, coherencia"

  # Validaciones obligatorias
  validaciones:
    backend:
      - "npm run build"
      - "npm run lint"
    frontend:
      - "npm run build"
      - "npm run lint"
    database:
      - "./create-database.sh"
      - "./validate-create-database.sh"
```

---

## 6. BENEFICIOS DE ESTA ARQUITECTURA

### 6.1 Reutilizacion

| Componente | Reutilizacion |
|------------|---------------|
| Directivas globales | 100% - Aplican a todos los proyectos |
| Prompts base | 100% - Logica comun para todos |
| Templates | 100% - Estructura estandar |
| Checklists | 100% - Validaciones universales |

### 6.2 Consistencia

- Todos los proyectos siguen el mismo flujo de 5 fases
- Todos los subagentes tienen el mismo proceso de validacion
- Nomenclatura consistente entre proyectos
- Estructura de documentacion estandar

### 6.3 Escalabilidad

- Nuevos proyectos solo necesitan crear directivas especificas
- Mejoras en core se propagan a todos los proyectos
- Facil onboarding de nuevos agentes

### 6.4 Mantenibilidad

- Un solo lugar para actualizar directivas globales
- Cambios en metodologia se aplican centralmente
- Versionado independiente de core vs proyectos

---

## 7. DIFERENCIAS CON SISTEMA ACTUAL

| Aspecto | Sistema Actual (Gamilit) | Sistema Propuesto |
|---------|-------------------------|-------------------|
| Ubicacion directivas | Solo en proyecto | Core + Proyecto |
| Prompts | Hardcodeados por proyecto | Templates + Especificos |
| Reutilizacion | Copiar/pegar | Herencia real |
| Actualizaciones | Manual por proyecto | Central desde core |
| Nuevos proyectos | Copiar estructura completa | bootstrap-project.sh |

---

## 8. PROXIMOS PASOS

Ver documento: `PLAN-IMPLEMENTACION-SISTEMA-ORQUESTACION.md`

---

**Autor:** Claude Code - Architecture Analyst
**Version:** 1.0.0
**Fecha:** 2025-12-05
