@liriraid/agentflow-ai 1.0.20 → 1.0.21

package/templates/es/.claude/settings.json

@@ -1,24 +1,24 @@
-{
-  "hooks": {
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node .claude/hooks/notify-check.js"
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node .claude/hooks/notify-check.js"
-          }
-        ]
-      }
-    ]
-  }
-}
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/notify-check.js"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/notify-check.js"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/es/.claude/skills/orchestrator-explore/SKILL.md

@@ -1,33 +1,34 @@
----
-name: orchestrator-explore
-description: >
-  Explora, analiza o investiga el proyecto antes de proponer cambios. Ideal cuando el usuario pide entender archivos, flujos o arquitectura antes de delegar implementación.
-  Trigger: "explora", "analiza", "investiga", "revisa este proyecto", "revisa estos archivos"
-license: MIT
-metadata:
-  owner: agentflow
-  version: "0.2"
----
-
-# Skill: orchestrator-explore
-
-## Propósito
-
-Guiar la fase de exploración del orquestador para reunir contexto útil antes de crear o delegar tareas.
-
-## Reglas críticas
-
-- Empieza por entender el alcance exacto del pedido del usuario.
-- Si hace falta lectura amplia, prioriza exploración y análisis antes de planear implementación.
-- Usa `OpenCode` como agente de exploración cuando necesites análisis profundo del codebase — su rol es **solo análisis**, no implementación.
-- Al delegar exploración a OpenCode, incluye en el brief exactamente qué debe reportar: flujos, dependencias, hallazgos de arquitectura, inconsistencias, etc.
-- No llenes `QUEUE.md` con implementación hasta tener suficiente contexto.
-- Resume hallazgos en términos accionables: qué existe, qué falta, qué riesgo hay y qué tareas salen de eso.
-- Si la exploración revela un cambio grande o multifase, el siguiente paso natural es abrir o actualizar un change en `openspec/`.
-- Si descubres una línea clara de trabajo, el siguiente paso natural es convertir hallazgos en TASKs concretas con `orchestrator-queue-planning`.
-- Mantén el foco dentro del alcance pedido; explorar no es rediseñar todo el sistema.
-- Cuando OpenCode entregue su reporte en INBOX.md, usa esos hallazgos para crear las TASKs de implementación (asignadas a Codex o Claude-Worker, nunca de vuelta a OpenCode).
-
-## Resultado esperado
-
-Una exploración útil que permita al orquestador decidir si ya puede crear TASKs o si necesita una investigación adicional.
+---
+name: orchestrator-explore
+description: >
+  Explora, analiza o investiga el proyecto antes de proponer cambios. Ideal cuando el usuario pide entender archivos, flujos o arquitectura antes de delegar implementación.
+  Trigger: "explora", "analiza", "investiga", "revisa este proyecto", "revisa estos archivos"
+license: MIT
+metadata:
+  owner: agentflow
+  version: "0.2"
+---
+
+# Skill: orchestrator-explore
+
+## Propósito
+
+Guiar la fase de exploración del orquestador para reunir contexto útil antes de crear o delegar tareas.
+
+## Reglas críticas
+
+- Empieza por entender el alcance exacto del pedido del usuario.
+- Si hace falta lectura amplia, prioriza exploración y análisis antes de planear implementación.
+- Usa **SOLO OpenCode** como agente de exploración cuando necesites análisis profundo del codebase — su rol es **EXCLUSIVAMENTE análisis**, **NUNCA implementación**.
+- Al delegar exploración a OpenCode, incluye en el brief exactamente qué debe reportar: flujos, dependencias, hallazgos de arquitectura, inconsistencias, etc.
+- No llenes `QUEUE.md` con implementación hasta tener suficiente contexto.
+- Resume hallazgos en términos accionables: qué existe, qué falta, qué riesgo hay y qué tareas salen de eso.
+- Si la exploración revela un cambio grande o multifase, el siguiente paso natural es abrir o actualizar un change en `openspec/`.
+- Si descubres una línea clara de trabajo, el siguiente paso natural es convertir hallazgos en TASKs concretas con `orchestrator-queue-planning`.
+- Mantén el foco dentro del alcance pedido; explorar no es rediseñar todo el sistema.
+- **REGLA ESTRICTA: Cuando OpenCode entregue su reporte en INBOX.md, usa ESOS hallazgos para crear las TASKs de implementación (asignadas a Codex o Claude-Worker). NUNCA, bajo ninguna circunstancia, vuelvas a analizar el código tú mismo (Claude-Orquestador) si OpenCode ya lo hizo. Lee el reporte en `progress/PROGRESS-OpenCode.md` o el INBOX.md y basa tus decisiones en ese análisis.**
+- Si el reporte de OpenCode es insuficiente, pide a OpenCode que profundice en un área específica con una nueva TASK de análisis, pero NO lo hagas tú directamente.
+
+## Resultado esperado
+
+Una exploración útil que permita al orquestador decidir si ya puede crear TASKs o si necesita una investigación adicional. **El resultado final DEBE ser una o más TASKs en QUEUE.md asignadas a Codex o Claude-Worker para implementación, NO más análisis por parte de Claude-Orquestador.**

package/templates/es/.claude/skills/orchestrator-queue-planning/SKILL.md

@@ -1,52 +1,52 @@
----
-name: orchestrator-queue-planning
-description: >
-  Convierte contexto y hallazgos en tareas concretas para QUEUE.md, con prioridades, agente objetivo y dependencias claras.
-  Trigger: "crea tareas", "planifica en queue", "divide el trabajo", "delegar tareas", "llenar queue"
-license: MIT
-metadata:
-  owner: agentflow
-  version: "0.2"
----
-
-# Orchestrator Queue Planning
-
-## Propósito
-
-Traducir una necesidad del usuario o hallazgos de exploración en tareas concretas para el motor del orquestador.
-
-## Reglas de asignación de agentes
-
-### OpenCode — análisis solamente
-- Úsalo para exploración, auditorías, lectura de contexto y reportes estructurados
-- **No le asignes implementación** — OpenCode no modifica archivos del proyecto
-- Si el trabajo necesita análisis previo, crea primero una TASK de OpenCode y luego una de Codex con dependencia `> after:TASK-NNN`
-
-### Codex — implementación principal
-- Úsalo para implementación, cambios de código, tests y docs técnicas cuando la spec esté clara
-- Es el agente primario de ejecución
-- Si Codex falla persistentemente, la TUI reasigna automáticamente a Claude-Worker (Frontend/Backend)
-
-### Claude-Worker (Frontend / Backend)
-- Es el fallback automático cuando Codex falla
-- También puede tomar trabajo cuando Codex y OpenCode están ambos ocupados y hay más tareas pendientes
-- Para proyectos solo frontend: usar siempre `Frontend`; para backend: `Backend`
-
-## Reglas críticas
-
-- Escribe TASKs pequeñas, concretas y ejecutables.
-- Cada tarea debe tener agente, prioridad, repo y descripción clara.
-- Usa dependencias `> after:TASK-NNN` cuando una tarea no pueda arrancar todavía.
-- No sobrecargues una sola IA con demasiadas tareas si puedes paralelizar sin riesgo.
-- Distribución según cantidad de TASKs independientes:
-  - **1 tarea de análisis**: OpenCode
-  - **1 tarea de implementación**: Codex
-  - **2 tareas paralelas**: OpenCode (análisis) + Codex (implementación si la spec ya es clara)
-  - **3+ tareas** y Codex ocupado: el excedente va a `Frontend` (repo FE) o `Backend` (repo BE)
-- Si existe un `openspec/changes/<change-name>/tasks.md`, úsalo como fuente de verdad.
-- Mantén `QUEUE.md` coherente con el objetivo actual del usuario.
-- **No asignes implementación a OpenCode** bajo ninguna circunstancia.
-
-## Resultado esperado
-
-Una cola clara y accionable que el motor pueda despachar de inmediato.
+---
+name: orchestrator-queue-planning
+description: >
+  Convierte contexto y hallazgos en tareas concretas para QUEUE.md, con prioridades, agente objetivo y dependencias claras.
+  Trigger: "crea tareas", "planifica en queue", "divide el trabajo", "delegar tareas", "llenar queue"
+license: MIT
+metadata:
+  owner: agentflow
+  version: "0.2"
+---
+
+# Orchestrator Queue Planning
+
+## Propósito
+
+Traducir una necesidad del usuario o hallazgos de exploración en tareas concretas para el motor del orquestador.
+
+## Reglas de asignación de agentes
+
+### OpenCode — análisis solamente
+- Úsalo para exploración, auditorías, lectura de contexto y reportes estructurados
+- **No le asignes implementación** — OpenCode no modifica archivos del proyecto
+- Si el trabajo necesita análisis previo, crea primero una TASK de OpenCode y luego una de Codex con dependencia `> after:TASK-NNN`
+
+### Codex — implementación principal
+- Úsalo para implementación, cambios de código, tests y docs técnicas cuando la spec esté clara
+- Es el agente primario de ejecución
+- Si Codex falla persistentemente, la TUI reasigna automáticamente a Claude-Worker (Frontend/Backend)
+
+### Claude-Worker (Frontend / Backend)
+- Es el fallback automático cuando Codex falla
+- También puede tomar trabajo cuando Codex y OpenCode están ambos ocupados y hay más tareas pendientes
+- Para proyectos solo frontend: usar siempre `Frontend`; para backend: `Backend`
+
+## Reglas críticas
+
+- Escribe TASKs pequeñas, concretas y ejecutables.
+- Cada tarea debe tener agente, prioridad, repo y descripción clara.
+- Usa dependencias `> after:TASK-NNN` cuando una tarea no pueda arrancar todavía.
+- No sobrecargues una sola IA con demasiadas tareas si puedes paralelizar sin riesgo.
+- Distribución según cantidad de TASKs independientes:
+  - **1 tarea de análisis**: OpenCode
+  - **1 tarea de implementación**: Codex
+  - **2 tareas paralelas**: OpenCode (análisis) + Codex (implementación si la spec ya es clara)
+  - **3+ tareas** y Codex ocupado: el excedente va a `Frontend` (repo FE) o `Backend` (repo BE)
+- Si existe un `openspec/changes/<change-name>/tasks.md`, úsalo como fuente de verdad.
+- Mantén `QUEUE.md` coherente con el objetivo actual del usuario.
+- **No asignes implementación a OpenCode** bajo ninguna circunstancia.
+
+## Resultado esperado
+
+Una cola clara y accionable que el motor pueda despachar de inmediato.

package/templates/es/AGENT-CONFIG.md

@@ -58,7 +58,8 @@ Cuando haya varias tareas independientes, el reparto recomendado es mantener ocu
 Para este proyecto reusable:
 
 - `claude` es el profile principal
-- `codex` y `opencode` son profiles de apoyo
+- `codex` es el profile de implementación primaria
+- `opencode` es el profile de apoyo que **puede implementar código cuando usa modelos avanzados** (ej: Mistral Medium 3.5 128B)
 - otros profiles pueden existir, aunque no estén habilitados por defecto
 
 ## Directorios locales sugeridos
@@ -79,5 +80,5 @@ Si existe configuración global del agente en el home del usuario y también una
 
 - `Claude` usa `.claude/skills/` como base principal del proyecto
 - `Codex` y `OpenCode` pueden tener configuración local propia aunque hoy no usen el mismo modelo de skills
-- `OpenCode` no es solo auditor: puede explorar, auditar e implementar cuando la TASK esté clara
+- `OpenCode` no es solo auditor: puede explorar, auditar e **implementar código cuando use modelos avanzados** como Mistral Medium 3.5 128B
 - el diseño debe permitir que mañana también tengan una capa local más rica

package/templates/es/ORCHESTRATOR.md

@@ -134,6 +134,8 @@ del .away-mode
 
 La TUI gestiona el fallback automáticamente siguiendo esta cadena:
 
+```
+Codex falla → OpenCode (con Mistral Medium 3.5 128B) → Frontend (repo FE) o Backend (repo BE)
 ```
 Codex falla  →  Frontend (repo FE) o Backend (repo BE) directamente
 ```
@@ -166,20 +168,24 @@ Revisa `orchestrator.config.json` → `agents`. Cada entrada tiene:
 |--------|-----|------------|
 | Backend | claude (sonnet) | Código server-side: controllers, models, migrations y tests |
 | Frontend | claude (sonnet) | Código UI: componentes, páginas y estilos |
-| Codex | codex | Docs, migraciones y tareas estructuradas con spec clara; puede apoyar frontend en tareas acotadas |
+| Codex | codex | **Primera opción para implementación**; docs, migraciones y tareas estructuradas con spec clara |
+| OpenCode | opencode | **Segunda opción para implementación** (con Mistral Medium 3.5 128B); exploración, auditorías y reportes estructurados |
 | Gemini | gemini | Auditorías, code review; suele sufrir con `node_modules` muy grandes |
-| OpenCode | opencode | Exploración, auditorías y reportes estructurados — solo análisis, no implementa código |
 | Cursor | cursor | Tareas mecánicas de alto volumen: find-and-replace y cleanup |
 | Abacus | abacusai | Tareas pequeñas y enfocadas, con alcance bien acotado |
 
+**Notas sobre OpenCode:**
+- Cuando OpenCode usa **Mistral Medium 3.5 128B o modelos equivalentes**, puede implementar código.
+- Si el modelo no es apto para implementación, OpenCode solo hará análisis y reportará como `blocked`.
+
 ## Cómo asignar trabajo
 
 1. **Cuando el usuario pide un cambio o nueva tarea** → **NUNCA analices directamente**
-   - **Si necesita análisis previo**: Crea una TASK en `QUEUE.md` asignada a **OpenCode** para que explore el contexto
-   - **Espera el reporte**: OpenCode escribe hallazgos en INBOX.md o progress/
-   - **Luego implementa**: Crea nueva TASK asignada a **Codex** (o Claude-Worker si Codex no está disponible)
-   - **OpenCode no implementa** — sus TASKs son siempre de análisis; la implementación va a Codex o Claude-Worker
-   - **Nunca analices el código del proyecto directamente tú mismo** - eso lo hace OpenCode
+- **Si necesita análisis previo**: Crea una TASK en `QUEUE.md` asignada **EXCLUSIVAMENTE** a **OpenCode** para que explore el contexto
+- **Espera el reporte**: OpenCode escribe hallazgos en `progress/PROGRESS-OpenCode.md` y notifica en `INBOX.md`
+- **Luego implementa**: **LEE EL REPORTE DE OPENCODE** en `progress/PROGRESS-OpenCode.md` o `INBOX.md` y crea nueva TASK asignada a **Codex** (o Claude-Worker si Codex no está disponible)
+- **OpenCode NO implementa** — sus TASKs son **SOLO de análisis**; la implementación **SIEMPRE** va a Codex o Claude-Worker
+- **NUNCA, bajo ninguna circunstancia, analices el código del proyecto directamente tú mismo (Claude-Orquestador)** — **ESO ES TRABAJO EXCLUSIVO DE OPENCODE**. Si ya existe un reporte de OpenCode, **USA ESE CONTEXTO** para crear tareas de implementación.
 
 2. Escribe TASKs en `QUEUE.md` (formato pipe; la TUI lo lee):
     ```
@@ -191,8 +197,9 @@ Revisa `orchestrator.config.json` → `agents`. Cada entrada tiene:
 4. (Opcional) Para un brief muy detallado, crea `briefs/TASK-NNN-BRIEF.md`; también se inyecta.
 5. Dependencias: agrega `> after:TASK-NNN` al final de la descripción para bloquear la tarea.
 6. **La TUI inicia automáticamente** - NO necesitas presionar R ni S. La TUI detecta nuevas tasks y las lanza.
-7. **OpenCode es solo análisis; Codex es la implementación principal.** Claude-Worker es el fallback automático de Codex y también toma trabajo cuando hay más tareas que agentes disponibles.
-7. Distribución según cantidad de TASKs independientes:
+7. **Codex es la primera opción para implementación; OpenCode (con Mistral Medium 3.5 128B) es la segunda opción.** Claude-Worker es el fallback automático de Codex/OpenCode y también toma trabajo cuando hay más tareas que agentes disponibles.
+8. **REGLA CRÍTICA SOBRE ANÁLISIS:** Si OpenCode ya analizó algo y escribió su reporte en `INBOX.md` o `progress/PROGRESS-OpenCode.md`, **TÚ (Claude-Orquestador) NO DEBES VOLVER A ANALIZAR EL MISMO CÓDIGO**. Usa el reporte existente para crear tareas de implementación. Si necesitas más detalles, pide a OpenCode que haga un análisis adicional con una nueva TASK, pero **NUNCA lo hagas tú directamente**.
+9. Distribución según cantidad de TASKs independientes:
    - **1 tarea de análisis**: OpenCode.
    - **1 tarea de implementación**: Codex. Nunca Claude-Worker en primera instancia.
    - **2 tareas paralelas**: OpenCode (análisis) + Codex (implementación si la spec está clara).
@@ -210,8 +217,12 @@ Revisa `orchestrator.config.json` → `agents`. Cada entrada tiene:
 6. Al terminar la sesión, escribe un `handoffs/HANDOFF-<fecha>.md` resumiendo qué se hizo y qué sigue.
 7. **Por defecto solo usa Claude, Codex y OpenCode**. No uses Gemini, Cursor ni Abacus salvo instrucción explícita del usuario.
 8. Si el usuario activa **Modo Ausencia**, revisa progreso cada 5 minutos y reasigna nuevas TASKs razonables dentro del alcance actual sin esperar confirmación intermedia.
-9. La TUI gestiona el fallback automáticamente: Codex falla → Claude-Worker (Frontend/Backend según repo). Solo intervén manualmente si la tarea queda marcada `failed`.
+9. La TUI gestiona el fallback automáticamente: Codex falla → OpenCode (si usa Mistral Medium 3.5 128B) → Claude-Worker (Frontend/Backend según repo). Solo intervén manualmente si la tarea queda marcada `failed`.
 10. Usa Engram para guardar decisiones, hallazgos, bugs y resúmenes de sesión; no dependas solo del contexto corto de la conversación.
+11. **VERIFICACIÓN OBLIGATORIA:** Antes de crear cualquier TASK de implementación, **LEE Y CONFIRMA QUE:**
+   - Existe un reporte de OpenCode en `INBOX.md` o `progress/PROGRESS-OpenCode.md` para el análisis solicitado.
+   - La TASK de implementación se basa **EXCLUSIVAMENTE** en el reporte de OpenCode.
+   - **NO** has analizado el código tú mismo (Claude-Orquestador).
 11. Para cambios grandes, usa `openspec/changes/<change-name>/` para proposal, spec, design, tasks y verify; no dejes todo solo en la conversación.
 12. No asumas bypass total o autoaceptación de cambios en los agentes. Claude debe seguir siendo la autoridad final para validar el resultado esperado antes de que el usuario dé la aprobación definitiva.
 

package/templates/es/README.md

@@ -1,44 +1,237 @@
-# 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 Mistral Medium 3.5 128B para código |
+| **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, si usa Mistral Medium 3.5 128B) → **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
+npm i -g @liriraid/agentflow-ai
+```
 
-## Qué es hoy
+### Desarrollo Local
+```bash
+git clone https://github.com/LiriRaid/agentflow-ai.git
+cd agentflow-ai
+npm install
+```
 
-Este repo ya no es solo un runner con `QUEUE.md`.
+## 🛠️ Inicio Rápido
 
-Hoy incluye:
+### 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.
 
-- **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**
+### 2. Configurar Repositorios
+Edita `orchestrator.config.json` en el workspace generado:
+```json
+{
+  "repos": {
+    "backend": "C:/code/mi-backend",
+    "frontend": "C:/code/mi-frontend"
+  }
+}
+```
 
-## Valor del sistema
+### 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)
 
-Lo que agrega valor en este flujo:
+### 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", "model": "sonnet" },
+    "Frontend": { "cli": "claude", "defaultRepo": "frontend", "model": "sonnet" },
+    "Codex": { "cli": "codex", "defaultRepo": "backend", "model": "gpt-5.5" },
+    "OpenCode": { "cli": "opencode", "defaultRepo": "frontend", "model": "auto" }
+  }
+}
+```
 
-- 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
+### Selección de Modelo
+- Usa `"model": "auto"` para que el agente use el modelo configurado por defecto en tu sistema (ej: Mistral Medium 3.5 128B para OpenCode).
+- Especifica un modelo explícitamente (ej: `"model": "gpt-5.5"`) para sobrescribir.
+
+## 🔄 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
+
+| Agente | CLI | Modelo por Defecto | ¿Implementa? | Notas |
+|--------|-----|---------------------|--------------|-------|
+| Backend | `claude` | sonnet | ✅ Sí | Claude-Worker para tareas de backend |
+| Frontend | `claude` | sonnet | ✅ Sí | Claude-Worker para tareas de frontend |
+| Codex | `codex` | gpt-5.5 | ✅ Sí | Implementación primaria |
+| OpenCode | `opencode` | auto | ✅ **Sí** (con Mistral Medium 3.5 128B) | 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 |
+
+## 🛡️ Seguridad y Mejores Prácticas
+
+- **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.
+
+## 📚 Documentación
+
+- **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`.
+
+## 🤝 Reconocimientos
+
+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