@liriraid/agentflow-ai 1.0.20 → 1.0.22

package/templates/es/README.md

@@ -1,44 +1,236 @@
-# Orquestador Multiagente
+# Orquestador Multiagente (agentflow-ai)
 
 > by **LiriRaid**
 
-Orquestador reusable para trabajar con múltiples agentes de código desde terminal, con un TUI propio, cola operativa, skills locales, memoria persistente con Engram y artefactos OpenSpec para cambios grandes.
+**Sistema de Orquestación Multiagente para Desarrollo con IA**
 
-La idea central no es dejar que una sola IA haga todo, sino:
+Un workspace reutilizable que coordina **múltiples agentes de IA** (Claude, Codex, OpenCode, etc.) para trabajar **en paralelo** en proyectos reales, manteniendo el repositorio del proyecto **completamente limpio** de archivos del orquestador.
 
-- usar a **Claude** como orquestador principal
-  - usar **OpenCode** principalmente para exploración, lectura y contexto, pero también para implementar cuando convenga
-  - usar **Codex** para ejecución estructurada e implementación de apoyo
-- reflejar todo en una **TUI** que muestra estado, cola, agentes, logs y actividad real
+```text
+workspace-proyecto/
+  mi-proyecto/          # Proyecto real (permanece limpio)
+  orchestrator-mi-proyecto/  # Workspace del orquestador (generado)
+```
+
+## 🎯 ¿Qué hace?
+
+- **Coordina múltiples agentes de IA** (Claude, Codex, OpenCode, Gemini, Cursor, Abacus) para trabajar simultáneamente en tu proyecto.
+- **Monitoreo en tiempo real** con una TUI moderna que muestra el estado en vivo de agentes, cola y progreso.
+- **Delegación automática de tareas** según la especialización del agente (análisis, implementación, revisión de código).
+- **Memoria persistente** con Engram para mantener el contexto entre sesiones.
+- **Soporte para SDD (Spec-Driven Development)** con OpenSpec para cambios grandes y multifase.
+- **Sistema de fallback automático** que reasigna tareas cuando un agente falla o alcanza límites de cuota.
+- **Soporte multi-idioma** (español e inglés) para todas las plantillas y documentación.
+
+## ✨ Características Clave
+
+### 1. **Modelo de Workspace Sibling**
+- El orquestador crea un **workspace separado** al lado de tu proyecto real.
+- Tu repositorio del proyecto **permanece completamente limpio** (sin `QUEUE.md`, `logs/`, etc.).
+- Los agentes trabajan en los archivos reales del proyecto mediante rutas absolutas configuradas en `orchestrator.config.json`.
+
+### 2. **Coordinación Multiagente**
+| Agente | Rol | Prioridad | Notas |
+|--------|-----|----------|-------|
+| **Claude-Orquestador** | Coordinador de sesión | - | Nunca implementa código directamente; delega a workers |
+| **Codex** | Implementación primaria | 1ra opción | Tareas estructuradas, tests, docs |
+| **OpenCode** | Análisis + Implementación | 2da opción | Usa el modelo que tengas configurado |
+| **Claude-Worker** (Backend/Frontend) | Fallback | 3ra opción | Toma el relevo si Codex/OpenCode fallan |
+| **Gemini** | Revisión/auditoría | Opcional | Deshabilitado por defecto |
+| **Cursor/Abacus** | Tareas mecánicas | Opcional | Deshabilitado por defecto |
+
+### 3. **Operación en Tiempo Real**
+- **fs.watch en QUEUE.md**: Detecta cambios en **~1-2 segundos** (Linux/macOS: monitoreo directo de archivo; Windows: fallback a monitoreo de directorio).
+- **Actualizaciones en vivo de la TUI**: El dashboard se refresca automáticamente cuando se agragan, inician o completan tareas.
+- **Notificaciones instantáneas**: Claude-Orquestador recibe alertas en `INBOX.md` y `NOTIFY.md` cuando las tareas finalizan.
+
+### 4. **Delegación Inteligente de Tareas**
+- **Tareas de análisis** → Siempre asignadas a **OpenCode**.
+- **Tareas de implementación** → Asignadas a **Codex** (1ra) → **OpenCode** (2da) → **Claude-Worker** (3ra).
+- **Cadena de fallback**: `Codex → OpenCode → Claude-Worker` (automático).
+
+### 5. **Memoria Persistente y SDD**
+- **Engram**: Almacena decisiones, bugs y hallazgos entre sesiones.
+- **OpenSpec**: Soporta `proposal.md`, `spec.md`, `design.md`, `tasks.md`, y `verify-report.md` para cambios grandes.
+- **Handoffs**: Resúmenes de sesión para continuidad.
+
+## 🚀 Instalación
+
+### CLI Global (Recomendado)
+```bash
+pnpm add -g @liriraid/agentflow-ai
+```
+
+### Desarrollo Local
+```bash
+git clone https://github.com/LiriRaid/agentflow-ai.git
+cd agentflow-ai
+pnpm install
+```
+
+## 🛠️ Inicio Rápido
+
+### 1. Crear un Workspace del Orquestador
+```bash
+# Interactivo (pregunta el idioma)
+agentflow init-workspace C:/code/mi-proyecto
+
+# Directo (Inglés)
+agentflow init-workspace C:/code/mi-proyecto --lang en
+
+# Directo (Español)
+agentflow init-workspace C:/code/mi-proyecto --lang es
+```
+Esto crea un workspace hermano (ej: `orchestrator-mi-proyecto/`) con todos los archivos de configuración.
+
+### 2. Configurar Repositorios
+Edita `orchestrator.config.json` en el workspace generado:
+```json
+{
+  "repos": {
+    "backend": "C:/code/mi-backend",
+    "frontend": "C:/code/mi-frontend"
+  }
+}
+```
+
+### 3. Iniciar la TUI
+```bash
+cd orchestrator-mi-proyecto
+agentflow ink --paused
+```
+**Controles:**
+- `S`: Iniciar/Reanudar
+- `P`: Pausar
+- `R`: Recargar cola
+- `Q`: Salir (detiene todos los agentes)
+
+### 4. Abrir Claude Code
+Abre una segunda terminal en el **workspace del orquestador** (no en el proyecto real):
+```bash
+cd orchestrator-mi-proyecto
+claude
+```
+Luego ejecuta:
+```
+Lee ORCHESTRATOR.md y arranca.
+```
+
+### 5. Solicitar Trabajo
+Ejemplos:
+- `"Explora este proyecto"` → OpenCode analiza y reporta.
+- `"Agrega autenticación JWT"` → OpenCode analiza, luego Codex/OpenCode implementan.
+- `"Refactoriza la capa de API"` → OpenCode explora, luego los workers implementan en paralelo.
+
+## 📁 Estructura del Workspace
+
+El workspace generado incluye:
+
+```text
+orchestrator-mi-proyecto/
+├── ORCHESTRATOR.md      # Reglas principales para la sesión del orquestador
+├── CLAUDE.md            # Reglas de enrutamiento para Claude
+├── QUEUE.md             # Cola de tareas activa (TASK-NNN | título | agente | ...)
+├── ENGRAM.md            # Convenciones de memoria persistente
+├── orchestrator.config.json  # Repos, agentes, modelos y perfiles
+├── agents/              # Instrucciones específicas por agente
+│   ├── BACKEND.md
+│   ├── FRONTEND.md
+│   ├── CODEX.md
+│   └── OPENCODE.md
+├── .claude/             # Skills y configuración local de Claude
+│   └── skills/          # Skills del orquestador (init, explore, etc.)
+├── .codex/              # Configuración de Codex
+├── .opencode/           # Configuración de OpenCode
+├── openspec/            # Artefactos SDD
+│   ├── changes/
+│   └── templates/
+├── docs/                # Documentación
+├── logs/                # Logs de ejecución
+├── handoffs/            # Handoffs de sesión
+└── progress/            # Reportes de progreso de agentes
+```
+
+## 🎛️ Configuración
+
+### Configuración de Agentes (`orchestrator.config.json`)
+```json
+{
+  "projectName": "Mi Proyecto",
+  "workspaceLanguage": "es",
+  "maxConcurrent": 5,
+  "pollIntervalSeconds": 5,  // Polling de fallback (realtime usa fs.watch)
+  "taskTimeoutMinutes": 30,
+  "repos": {
+    "backend": "C:/code/mi-backend",
+    "frontend": "C:/code/mi-frontend"
+  },
+  "agentProfiles": {
+    "claude": { "enabled": true, "localConfigDir": ".claude" },
+    "codex": { "enabled": true, "localConfigDir": ".codex" },
+    "opencode": { "enabled": true, "localConfigDir": ".opencode" }
+  },
+  "agents": {
+    "Backend": { "cli": "claude", "defaultRepo": "backend" },
+    "Frontend": { "cli": "claude", "defaultRepo": "frontend" },
+    "Codex": { "cli": "codex", "defaultRepo": "backend" },
+    "OpenCode": { "cli": "opencode", "defaultRepo": "frontend" }
+  }
+}
+```
+
+### Selección de Modelo
+Cada agente usa el modelo que tengas configurado en su propio CLI. Podés agregar opcionalmente `"model": "nombre-del-modelo"` en la entrada de cualquier agente para sobrescribir — para Claude acepta valores como `sonnet` u `opus`.
+
+## 🔄 Ejemplo de Flujo de Trabajo
+
+1. **Solicitud del Usuario**: `"Agrega autenticación JWT al backend."`
+2. **Claude-Orquestador**:
+   - Crea `TASK-001` (OpenCode): `"Analizar sistema de autenticación actual"`
+   - Espera el reporte de OpenCode en `progress/PROGRESS-OpenCode.md`
+3. **OpenCode**:
+   - Analiza el codebase.
+   - Escribe los hallazgos en `progress/PROGRESS-OpenCode.md` y `INBOX.md`.
+4. **Claude-Orquestador**:
+   - Lee el reporte de OpenCode.
+   - Crea `TASK-002` (Codex): `"Implementar autenticación JWT"` (depende de TASK-001).
+5. **Codex**:
+   - Implementa la funcionalidad.
+   - Reporta la finalización en `progress/PROGRESS-Codex.md`.
+6. **TUI**:
+   - Muestra actualizaciones en tiempo real (estado de tareas, actividad de agentes, costos).
+
+## 📊 Agentes Soportados y Modelos
 
-## Qué es hoy
+| Agente | CLI | Modelo | ¿Implementa? | Notas |
+|--------|-----|--------|--------------|-------|
+| Backend | `claude` | auto | ✅ Sí | Claude-Worker para tareas de backend |
+| Frontend | `claude` | auto | ✅ Sí | Claude-Worker para tareas de frontend |
+| Codex | `codex` | auto | ✅ Sí | Implementación primaria |
+| OpenCode | `opencode` | auto | ✅ Sí | Implementación secundaria |
+| Gemini | `gemini` | auto | ❌ No | Solo auditorías/revisiones |
+| Cursor | `cursor` | auto | ❌ No | Solo ediciones masivas |
+| Abacus | `abacusai` | auto | ❌ No | Solo tareas pequeñas y enfocadas |
 
-Este repo ya no es solo un runner con `QUEUE.md`.
+## 🛡️ Seguridad y Mejores Prácticas
 
-Hoy incluye:
+- **Sin commits automáticos**: Los agentes nunca ejecutan `git commit` o `git push`.
+- **Sin modo YOLO por defecto**: El modo seguro está activado a menos que se use `--yolo`.
+- **Claude como revisor**: Claude-Orquestador valida todo el trabajo antes de la aprobación del usuario.
+- **Repositorios limpios**: Los archivos del proyecto permanecen intactos; los archivos del orquestador viven en el workspace hermano.
+- **Fallback seguro**: Las tareas se reasignan automáticamente si un agente falla.
 
-- **motor de orquestación** en `orchestrator.js`
-- **TUI Ink** conectada al motor real
-- **skills locales** en `.claude/skills/`
-- **routing local** con `CLAUDE.md`
-- **memoria persistente** con `ENGRAM.md`
-- **OpenSpec** para cambios grandes
-- **configuración por agente** con `agentProfiles`
-- **base de installer / ecosystem configurator**
-- **documentación local de componentes y arquitectura**
+## 📚 Documentación
 
-## Valor del sistema
+- **Reglas Principales**: Ver `ORCHESTRATOR.md` en el workspace generado.
+- **Enrutamiento de Agentes**: Ver `CLAUDE.md`.
+- **Arquitectura**: Ver `docs/architecture.md`.
+- **OpenSpec**: Ver `openspec/FLOW.md`.
 
-Lo que agrega valor en este flujo:
+## 🤝 Reconocimientos
 
-- TUI multiagente visible en tiempo real
-- cola operativa (`QUEUE.md`) integrada al runtime
-- delegación real para ahorro de tokens
-- separación clara entre:
-  - exploración
-  - planificación
-  - ejecución
-  - verificación
+Inspirado en [Orquestador-AI](https://github.com/ariellontero/Orquestador-AI) de Ariel Lontero (MIT). 
+Construido desde cero con una arquitectura moderna: **TUI Ink + React, paquete npm, fs.watch en tiempo real, plantillas multi-idioma y coordinación multiagente**.
 
 ## Documentación local
 
@@ -97,7 +289,7 @@ pero **ese no es el flujo recomendado** para este proyecto.
 Instala el CLI una sola vez:
 
 ```bash
-npm i -g @liriraid/agentflow-ai
+pnpm add -g @liriraid/agentflow-ai
 ```
 
 Luego, para cada proyecto real, crea un workspace sibling del orquestador:
@@ -137,7 +329,7 @@ Si vas a modificar el orquestador mismo:
 ```bash
 git clone https://github.com/LiriRaid/agentflow.git
 cd agentflow
-npm install
+pnpm install
 ```
 
 Este repo local es la **fuente reusable** que tú modificas para agregar herramientas, cambiar el flujo o extender el sistema.
@@ -170,7 +362,7 @@ También crea carpetas runtime:
 ### 1. Instalar el CLI globalmente
 
 ```bash
-npm i -g @liriraid/agentflow-ai
+pnpm add -g @liriraid/agentflow-ai
 ```
 
 ### 2. Crear el workspace del orquestador
@@ -498,14 +690,12 @@ Eso asegura:
       "cli": "claude",
       "profile": "claude",
       "defaultRepo": "backend",
-      "model": "sonnet",
       "instructionsFile": "agents/BACKEND.md"
     },
     "Codex": {
       "cli": "codex",
       "profile": "codex",
       "defaultRepo": "backend",
-      "model": "gpt-5.5",
       "instructionsFile": "agents/CODEX.md"
     },
     "OpenCode": {

package/templates/es/agents/OPENCODE.md

@@ -1,42 +1,62 @@
-# Agente OpenCode
-
-## Rol
-
-OpenCode es un agente de **análisis y exploración exclusivamente**. Lee código, genera reportes estructurados y entrega hallazgos a `INBOX.md` para que el Orquestador decida los siguientes pasos. No implementa cambios de código.
-
-## Alcance
-
-- Auditorías del codebase
-- Exploración de flujos y arquitectura
-- Lectura de contexto antes de implementación
-- Smoke tests de lectura (sin modificar nada)
-- Reportes estructurados en Markdown
-- Identificación de residuos, dependencias faltantes, inconsistencias
-
-## Fuera de alcance
-
-- Modificar archivos del proyecto
-- Implementar features o refactors
-- Escribir tests nuevos
-- Crear o borrar archivos
-
-## Reglas
-
-1. Nunca hagas `git commit` ni `git push`
-2. Nunca modifiques archivos del proyecto real
-3. Entrega siempre los hallazgos en tablas Markdown cuando listes varios ítems
-4. Escribe el reporte de finalización en `progress/PROGRESS-OpenCode.md`
-5. Si la TASK pide implementación, reporta en TASK_REPORT: `status: blocked`, `issues: "OpenCode es solo análisis — reasignar a Codex o Claude-Worker"`
-
-## Reporte de finalización (OBLIGATORIO)
-
-```
-TASK_REPORT
-status: completed | failed | blocked
-files_modified: none
-files_created: none
-files_deleted: none
-summary: 1-3 sentences describing findings
-issues: problems or "none"
-TASK_REPORT_END
-```
+# Agente OpenCode
+
+## Rol
+
+OpenCode es un agente **multipropósito** capaz de realizar **análisis, exploración e implementación de código**.
+Sus capacidades dependen del modelo que tengas configurado en tu instalación de OpenCode.
+
+## Alcance
+
+### Análisis (Siempre disponible)
+- Auditorías del codebase
+- Exploración de flujos y arquitectura
+- Lectura de contexto antes de implementación
+- Smoke tests de lectura
+- Reportes estructurados en Markdown
+- Identificación de residuos, dependencias faltantes, inconsistencias
+
+### Implementación
+- Implementar nuevas features
+- Modificar archivos del proyecto
+- Escribir tests nuevos
+- Refactorizar código
+- Corregir bugs
+
+## Reglas Generales
+
+1. Nunca hagas `git commit` ni `git push`
+2. Si la tarea es de **análisis**: entrega hallazgos en tablas Markdown y escribe el reporte en `progress/PROGRESS-OpenCode.md`
+3. Si la tarea es de **implementación**: modifica los archivos necesarios y documenta los cambios
+4. Entrega siempre un TASK_REPORT al finalizar
+
+## Prioridad de Asignación
+
+- **Primera opción para implementación**: Codex (cuando esté disponible)
+- **Segunda opción para implementación**: OpenCode
+- **Tercera opción**: Claude-Worker (Backend/Frontend)
+
+## Reporte de finalización (OBLIGATORIO)
+
+### Para tareas de análisis:
+```
+TASK_REPORT
+status: completed | failed | blocked
+files_modified: none
+files_created: none
+files_deleted: none
+summary: 1-3 oraciones describiendo los hallazgos
+issues: problemas encontrados o "none"
+TASK_REPORT_END
+```
+
+### Para tareas de implementación:
+```
+TASK_REPORT
+status: completed | failed | blocked
+files_modified: ["src/file1.js", "src/file2.ts"]
+files_created: ["src/new-file.js"]
+files_deleted: ["src/old-file.js"]
+summary: 1-3 oraciones describiendo los cambios realizados
+issues: problemas encontrados o "none"
+TASK_REPORT_END
+```

package/templates/es/docs/usage.md

@@ -5,7 +5,7 @@
 ### 1. Instalar el CLI globalmente
 
 ```bash
-npm i -g @liriraid/agentflow-ai
+pnpm add -g @liriraid/agentflow-ai
 ```
 
 ### 2. Crear un workspace hermano para un proyecto

package/templates/es/orchestrator.config.json

@@ -50,49 +50,42 @@
       "cli": "claude",
       "profile": "claude",
       "defaultRepo": "backend",
-      "model": "sonnet",
       "instructionsFile": "agents/BACKEND.md"
     },
     "Frontend": {
       "cli": "claude",
       "profile": "claude",
       "defaultRepo": "frontend",
-      "model": "sonnet",
       "instructionsFile": "agents/FRONTEND.md"
     },
     "Codex": {
       "cli": "codex",
       "profile": "codex",
       "defaultRepo": "frontend",
-      "model": "gpt-5.5",
       "instructionsFile": "agents/CODEX.md"
     },
-"Gemini": {
+    "Gemini": {
       "cli": "gemini",
       "profile": "gemini",
       "defaultRepo": "frontend",
-      "model": "auto",
       "instructionsFile": "agents/GEMINI.md"
-    },
+    },
     "OpenCode": {
       "cli": "opencode",
       "profile": "opencode",
       "defaultRepo": "frontend",
-      "model": "auto",
       "instructionsFile": "agents/OPENCODE.md"
     },
     "Cursor": {
       "cli": "cursor",
       "profile": "cursor",
       "defaultRepo": "backend",
-      "model": "auto",
       "instructionsFile": "agents/CURSOR.md"
     },
     "Abacus": {
       "cli": "abacusai",
       "profile": "abacusai",
       "defaultRepo": "backend",
-      "model": "auto",
       "instructionsFile": "agents/ABACUS.md"
     }
   }