@liriraid/agentflow-ai 1.0.12 → 1.0.13

package/orchestrator.js

@@ -798,6 +798,45 @@ function reloadQueue() {
   });
 }
 
+// ============================================================================
+// INBOX NOTIFICATIONS — written when a task completes so the Orchestrator
+// session can detect it on next interaction without Modo Ausencia active.
+// ============================================================================
+function writeInboxNotification(task, agentName, elapsed) {
+  const inboxFile = path.join(WORKSPACE, "INBOX.md");
+  const progressFile = `progress/PROGRESS-${agentName}.md`;
+  const entry = [
+    ``,
+    `## [${timestamp()}] ${task.id} completada — ${agentName}`,
+    ``,
+    `- **Tarea:** ${task.title}`,
+    `- **Duración:** ${formatDuration(elapsed)}`,
+    `- **Reporte:** ${progressFile}`,
+    `- **Acción:** Lee \`${progressFile}\` y crea las siguientes TASKs si corresponde.`,
+    ``,
+  ].join("\n");
+  try {
+    fs.appendFileSync(inboxFile, entry, "utf-8");
+  } catch {}
+}
+
+function writeInboxFailureNotification(task, failedAgent, newAgent, reason) {
+  const inboxFile = path.join(WORKSPACE, "INBOX.md");
+  const entry = [
+    ``,
+    `## [${timestamp()}] ${task.id} falló — ${failedAgent} → reasignada a ${newAgent}`,
+    ``,
+    `- **Tarea:** ${task.title}`,
+    `- **Motivo:** ${reason}`,
+    `- **Nuevo agente:** ${newAgent}`,
+    `- **Acción:** La TUI reasignó automáticamente. Verifica en QUEUE.md o espera la siguiente notificación de completada.`,
+    ``,
+  ].join("\n");
+  try {
+    fs.appendFileSync(inboxFile, entry, "utf-8");
+  } catch {}
+}
+
 // ============================================================================
 // BRIEF GENERATOR
 // ============================================================================
@@ -1217,6 +1256,7 @@ function completeTask(task, agentName) {
   ag.startTime = null;
   ag.lastLine = `Última: ${task.id} completada`;
   updateQueueFile(task);
+  writeInboxNotification(task, agentName, elapsed);
   scheduleNext();
   renderDashboard();
 }
@@ -1302,19 +1342,20 @@ function failTask(task, agentName, code) {
   ag.process = null;
   ag.startTime = null;
 
-  const shouldFallbackToClaude =
+  const shouldFallback =
     ["Codex", "OpenCode"].includes(agentName) &&
     (failureFlags.exhaustedQuota ||
       failureFlags.providerUnavailable ||
       retries >= maxRetries);
 
-  if (shouldFallbackToClaude) {
+  if (shouldFallback) {
     const reason = failureFlags.exhaustedQuota
       ? "cuota o límite agotado"
       : failureFlags.providerUnavailable
         ? "proveedor o sesión no disponibles"
         : "fallo persistente";
-    if (tryFallbackToClaude(task, agentName, reason)) {
+    if (tryFallbackToAlternative(task, agentName, reason)) {
+      writeInboxFailureNotification(task, agentName, task.agent, reason);
       setTimeout(() => {
         scheduleNext();
         renderDashboard();
@@ -1474,39 +1515,55 @@ function detectSupportAgentFailure(agentName) {
 }
 
 function getClaudeFallbackAgent(task) {
+  // If both repos point to the same resolved path (frontend-only project), always prefer Frontend
+  if (
+    REPOS.backend &&
+    REPOS.frontend &&
+    path.resolve(REPOS.backend) === path.resolve(REPOS.frontend)
+  ) {
+    if (AGENTS["Frontend"]?.cli === "claude") return "Frontend";
+  }
   const preferred = task.repo === "frontend" ? "Frontend" : "Backend";
   if (AGENTS[preferred]?.cli === "claude") return preferred;
-  return (
-    Object.keys(AGENTS).find((name) => AGENTS[name]?.cli === "claude") || null
-  );
+  return Object.keys(AGENTS).find((name) => AGENTS[name]?.cli === "claude") || null;
 }
 
-function tryFallbackToClaude(task, failedAgentName, reason) {
+function getAlternativeSupportAgent(failedAgentName) {
+  if (failedAgentName === "Codex") return "OpenCode";
+  if (failedAgentName === "OpenCode") return "Codex";
+  return null;
+}
+
+function tryFallbackToAlternative(task, failedAgentName, reason) {
   if (!["Codex", "OpenCode"].includes(failedAgentName)) return false;
-  const fallbackAgent = getClaudeFallbackAgent(task);
-  if (!fallbackAgent || fallbackAgent === failedAgentName) return false;
 
-  const queueUpdated = updateQueueTaskAgent(task.id, fallbackAgent);
-  task.agent = fallbackAgent;
+  // Step 1: try sibling support agent (Codex → OpenCode, OpenCode → Codex)
+  const siblingAgent = getAlternativeSupportAgent(failedAgentName);
+  const siblingAvailable =
+    siblingAgent &&
+    AGENTS[siblingAgent] &&
+    state.agents[siblingAgent]?.status === "idle" &&
+    !rateLimitedAgents.has(siblingAgent);
+
+  // Step 2: if sibling is also unavailable, fall back to Claude worker (prefer Frontend)
+  const targetAgent = siblingAvailable ? siblingAgent : getClaudeFallbackAgent(task);
+  if (!targetAgent || targetAgent === failedAgentName) return false;
+
+  const queueUpdated = updateQueueTaskAgent(task.id, targetAgent);
+  task.agent = targetAgent;
   task.status = "pending";
   task._retryAfter = Date.now() + 3000;
   failedTasks.set(task.id, 0);
   state.queue.push(task);
 
-  log(
-    "FALLBACK",
-    `${task.id} fue reasignada de ${failedAgentName} a ${fallbackAgent} (${reason})`,
-  );
+  log("FALLBACK", `${task.id} reasignada de ${failedAgentName} a ${targetAgent} (${reason})`);
   appendToAgent(
     failedAgentName,
-    `{yellow-fg}=== REASIGNADA A ${escBl(fallbackAgent)} (${escBl(reason)}) ==={/yellow-fg}`,
+    `{yellow-fg}=== REASIGNADA A ${escBl(targetAgent)} (${escBl(reason)}) ==={/yellow-fg}`,
     true,
   );
   if (!queueUpdated) {
-    log(
-      "WARN",
-      `${task.id} fue reasignada a ${fallbackAgent}, pero QUEUE.md no pudo actualizarse automáticamente`,
-    );
+    log("WARN", `${task.id} reasignada a ${targetAgent}, pero QUEUE.md no pudo actualizarse`);
   }
   return true;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liriraid/agentflow-ai",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "Multi-agent workspace orchestrator with TUI. Coordinates AI coding agents over your real frontend and backend projects.",
   "author": "LiriRaid",
   "homepage": "https://github.com/LiriRaid/agentflow-ai#readme",

package/templates/en/ORCHESTRATOR.md

@@ -36,14 +36,14 @@ When the user requests work after startup:
 
 1. Do not implement the work in the interactive Claude session.
 2. Convert the request into one or more TASKs in `QUEUE.md`.
-3. Prefer assigning the first executable work to `Codex` or `OpenCode`.
-4. Assign a Claude-Worker only when:
-   - Codex and/or OpenCode already have useful work in flight,
-   - a task is blocked by Codex/OpenCode quota, rate limit, token limits, or repeated failure,
-   - the task is highly sensitive and needs Claude as the worker,
-   - the user explicitly asks Claude to take the worker task.
+3. Always assign first to `OpenCode` (exploration) and `Codex` (implementation).
+4. Assign a Claude-Worker (`Frontend` or `Backend`) **only** when:
+   - **Multiple independent tasks exist** AND Codex + OpenCode are both already occupied, OR
+   - A task has **permanently failed** in Codex AND OpenCode — then Claude-Worker takes it as last resort.
 
-For frontend work, prefer `Codex` for narrow, well-scoped tasks and `OpenCode` for exploration/audits. Use `Frontend`/Claude-Worker for broader UI implementation, fallback, or when the other allowed agents are already occupied.
+The TUI handles automatic fallback: Codex fails → tries OpenCode → tries Claude-Worker. You only need to manually assign Claude-Workers for load balancing (case a) or when the TUI marks a task as permanently `failed` (case b).
+
+The `repo` field determines the working directory: `frontend` for UI/client work, `backend` for API/server work. Codex and OpenCode can work in either repo depending on the task.
 
 ## This Workspace Is NOT the Real Project
 
@@ -66,11 +66,14 @@ When the user says something like `Read ORCHESTRATOR.md and start`, do this:
 2. Read `orchestrator.config.json` — identify the real project paths in `repos` (frontend, backend). Those are the paths where the worker agents operate.
 3. Read `<projectName>-plan.md`, `PLAN.md`, or `plan.md` if present.
 4. Read the newest `handoffs/HANDOFF-*.md` if the folder exists.
-5. Read `QUEUE.md` to understand pending, active, and completed work.
-6. Read all `progress/PROGRESS-*.md` files if present.
-7. Read `ENGRAM.md` and follow the memory rules.
-8. Use `openspec/` for large or multi-phase changes.
-9. Tell the user the orchestrator is ready and ask what to prioritize.
+5. **Read `INBOX.md` if it exists** — it contains automatic TUI notifications of completed tasks that require your attention (creating next TASKs, reading agent reports, etc.).
+6. Read `QUEUE.md` to understand pending, active, and completed work.
+7. Read all `progress/PROGRESS-*.md` files if present.
+8. Read `ENGRAM.md` and follow the memory rules.
+9. Use `openspec/` for large or multi-phase changes.
+10. Tell the user the orchestrator is ready and ask what to prioritize.
+
+**INBOX rule:** At the start of EACH response, if `INBOX.md` has new entries since your last read, check it first. This is how you know when an agent finished and what to create next — without Away Mode active.
 
 Startup is context loading only. Do not create project code changes during startup.
 
@@ -102,14 +105,19 @@ Away Mode limits:
 
 ## Fallback Policy
 
-If Codex or OpenCode fail persistently because of quota, rate limits, token limits, expired sessions, repeated provider errors, or CLI downtime:
+The TUI handles fallback automatically following this chain:
+
+```
+Codex fails  →  tries OpenCode (if idle and not rate-limited)
+                    ↓ (if OpenCode also fails or is blocked)
+             →  Frontend (frontend repo) or Backend (backend repo) as last resort
+```
 
-1. Detect that the issue is no longer transient.
-2. Add a clear note in `QUEUE.md`, `TASKS.md`, or a handoff.
-3. Reassign the TASK to a Claude-Worker (`Backend` or `Frontend`, based on the repo).
-4. Include the available context so the Claude-Worker can continue instead of restarting from zero.
+As Orchestrator you do **not** need to manually reassign on failure — the TUI does it. Your role is:
 
-The priority is continuity. Do not leave tasks looping forever.
+1. Check `INBOX.md` or `QUEUE.md` to confirm the fallback ran correctly.
+2. If the TUI could not resolve it (task marked `failed`), then manually assign to `Frontend` or `Backend` based on the repo.
+3. Leave a note in `QUEUE.md` or `TASKS.md` if the reason is relevant for the session.
 
 ## Agents
 

package/templates/en/orchestrator.config.json

@@ -63,21 +63,21 @@
     "Codex": {
       "cli": "codex",
       "profile": "codex",
-      "defaultRepo": "backend",
+      "defaultRepo": "frontend",
       "model": "gpt-5.5",
       "instructionsFile": "agents/CODEX.md"
     },
     "Gemini": {
       "cli": "gemini",
       "profile": "gemini",
-      "defaultRepo": "backend",
+      "defaultRepo": "frontend",
       "model": "gemini-3-pro-preview",
       "instructionsFile": "agents/GEMINI.md"
     },
     "OpenCode": {
       "cli": "opencode",
       "profile": "opencode",
-      "defaultRepo": "backend",
+      "defaultRepo": "frontend",
       "model": "opencode/glm-5-free",
       "instructionsFile": "agents/OPENCODE.md"
     },

package/templates/es/ORCHESTRATOR.md

@@ -16,7 +16,16 @@ Hay dos roles distintos que no deben confundirse:
 1. **Claude-Orquestador**: la sesión interactiva que lee este archivo, divide el trabajo, edita `QUEUE.md`, revisa resultados y decide siguientes pasos. Este rol no modifica código del proyecto directamente.
 2. **Claude-Worker**: agentes lanzados por la TUI con CLI `claude`, por ejemplo `Backend` y `Frontend`. Estos agentes sí pueden implementar código cuando una TASK se les asigna explícitamente.
 
-Claude no debe quedarse solo esperando respuestas de otros agentes. Cuando haya tareas independientes suficientes, el orquestador debe incluir al menos una TASK para un Claude-Worker en la primera tanda, además de tareas para Codex y OpenCode cuando aplique.
+**Prioridad de asignación de trabajo:**
+
+```
+OpenCode / Codex  →  primera opción siempre (exploración e implementación)
+Claude-Worker     →  último recurso, solo en estos dos casos:
+  a) Múltiples TASKs independientes Y Codex + OpenCode ambos ocupados → Claude-Worker toma 1
+  b) Codex falló persistentemente Y OpenCode también falló → Claude-Worker toma la tarea
+```
+
+El Orquestador NO asigna a Claude-Worker en la primera tanda si solo hay 1 tarea o si Codex/OpenCode están disponibles. La TUI gestiona el fallback automático al fallar un agente.
 
 ## El workspace NO es el proyecto real
 
@@ -37,11 +46,14 @@ Cuando necesites entender el proyecto para planificar tareas, **lee archivos des
 2. Lee `orchestrator.config.json` — identifica las rutas reales en `repos` (frontend, backend). Esas son las rutas del proyecto real donde trabajan los agentes.
 3. Lee `<projectName>-plan.md` (o `PLAN.md` / `plan.md`) si existe; ese es el plan general.
 4. Lee el handoff más reciente en `handoffs/HANDOFF-*.md` si existe la carpeta.
-5. Lee `QUEUE.md` para ver trabajo activo y pendiente.
-6. Lee todos los archivos `progress/PROGRESS-*.md` que existan para entender el estado actual de cada agente.
-7. Lee `ENGRAM.md` para respetar la convención de memoria persistente del proyecto.
-8. Si existe `openspec/`, úsalo como capa de artefactos para cambios grandes o de varias fases.
-9. Pregunta al usuario qué quiere priorizar; no planifiques toda la sesión automáticamente.
+5. **Lee `INBOX.md` si existe** — contiene notificaciones automáticas del TUI de tasks completadas que requieren tu atención (crear siguientes TASKs, leer reportes de agentes, etc.).
+6. Lee `QUEUE.md` para ver trabajo activo y pendiente.
+7. Lee todos los archivos `progress/PROGRESS-*.md` que existan para entender el estado actual de cada agente.
+8. Lee `ENGRAM.md` para respetar la convención de memoria persistente del proyecto.
+9. Si existe `openspec/`, úsalo como capa de artefactos para cambios grandes o de varias fases.
+10. Pregunta al usuario qué quiere priorizar; no planifiques toda la sesión automáticamente.
+
+**Regla de INBOX:** Al inicio de CADA respuesta, si `INBOX.md` tiene entradas nuevas desde tu última lectura, léelo primero antes de responder al usuario. Así sabrás qué agentes terminaron y qué falta crear.
 
 ## Restricción operativa por defecto
 
@@ -93,25 +105,19 @@ entonces debes entrar en **Modo Ausencia** durante esa sesión.
 
 ### Fallback por cuota o indisponibilidad
 
-Si una IA permitida en este proyecto, especialmente **Codex** u **OpenCode**, falla de forma persistente por motivos como:
+La TUI gestiona el fallback automáticamente siguiendo esta cadena:
 
-- rate limit prolongado
-- cuota agotada
-- falta de tokens o de plan disponible
-- sesión expirada
-- error repetido del proveedor
-- indisponibilidad temporal del CLI
-
-entonces no debes dejar la tarea en bucle indefinidamente.
-
-Debes hacer esto:
+```
+Codex falla  →  intenta OpenCode (si está libre y sin rate limit)
+                    ↓ (si OpenCode también falla o está bloqueado)
+             →  Frontend (repo FE) o Backend (repo BE) como último recurso
+```
 
-1. Detectar que el problema ya no es transitorio.
-2. Dejar nota clara del motivo en `QUEUE.md`, `TASKS.md` o handoff si hace falta.
-3. Reasignar la TASK a un **Claude-Worker** (`Backend` o `Frontend`, según el repo) como fallback.
-4. Hacer que Claude-Worker continúe la ejecución con el contexto ya disponible, en vez de abandonar la tarea.
+Como Orquestador, **no necesitas reasignar manualmente** cuando hay un fallo — la TUI lo hace sola. Tu rol en este caso es:
 
-La prioridad es mantener continuidad del trabajo aunque una IA de apoyo se quede sin cuota o deje de responder.
+1. Verificar en `INBOX.md` o `QUEUE.md` que el fallback se ejecutó correctamente.
+2. Si la TUI no pudo resolver el fallback (tarea marcada `failed`), entonces sí debes intervenir: asigna explícitamente a `Frontend` o `Backend` según el repo.
+3. Deja nota en `QUEUE.md` o `TASKS.md` del motivo si es relevante para la sesión.
 
 ### Fin de Modo Ausencia
 
@@ -153,13 +159,13 @@ Revisa `orchestrator.config.json` → `agents`. Cada entrada tiene:
 3. (Opcional) Para un brief muy detallado, crea `briefs/TASK-NNN-BRIEF.md`; también se inyecta.
 4. Dependencias: agrega `> after:TASK-NNN` al final de la descripción para bloquear la tarea.
 5. Dile al usuario que presione **R** en la TUI para recargar la cola, o **S** si está pausada.
-6. **Intenta mantener a cada agente permitido con al menos 1 tarea en vuelo**; si uno está idle, busca algo útil para asignarle.
-7. Si existen 3 o más TASKs independientes, reparte la primera tanda entre:
-   - un Claude-Worker (`Backend` o `Frontend`, según el repo)
-   - `Codex` para implementación estructurada, docs, migraciones o cambios con spec clara
-   - `OpenCode` para exploración, auditoría o implementación acotada cuando la tarea ya esté clara
-8. Si hay más TASKs que agentes permitidos disponibles, deja el resto en cola con dependencias claras o prioridad menor; no uses Gemini, Cursor ni Abacus salvo permiso explícito.
-9. Para frontend, prefiere `Frontend`/Claude como dueño principal. Usa `Codex` en `repo=frontend` solo para apoyo acotado: tests, documentación, fixes puntuales, refactors mecánicos o cambios con archivos bien delimitados.
+6. **Prioriza Codex y OpenCode** para toda implementación y exploración. Claude-Workers solo cuando hay saturación o fallo total de agentes de soporte.
+7. Distribución según cantidad de TASKs independientes:
+   - **1 tarea**: OpenCode (exploración) o Codex (implementación). Nunca Claude-Worker en primera instancia.
+   - **2 tareas**: OpenCode + Codex, una cada uno.
+   - **3+ tareas** y Codex+OpenCode ambos ocupados: el excedente puede ir a `Frontend` (repo FE) o `Backend` (repo BE) según corresponda.
+8. Si hay más TASKs que agentes disponibles, deja el resto en cola con dependencias claras o prioridad menor; no uses Gemini, Cursor ni Abacus salvo permiso explícito.
+9. El campo `repo` determina en qué directorio trabaja el agente. Usa siempre el valor correcto: `frontend` para trabajo de UI/cliente, `backend` para trabajo de API/servidor. Codex y OpenCode pueden trabajar en ambos repos según lo que indique la task.
 
 ## Reglas
 
@@ -171,7 +177,7 @@ 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. Si Codex u OpenCode fallan de forma persistente por cuota, rate limit o indisponibilidad, deja de insistir y pasa la tarea a un Claude-Worker como fallback.
+9. La TUI gestiona el fallback automáticamente: Codex falla → OpenCode → 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. 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.
@@ -202,6 +208,7 @@ Actualiza esta sección al inicio y al final de cada sesión:
 ## Archivos de referencia
 
 - **Plan del proyecto:** `<projectName>-plan.md`
+- **Notificaciones de tasks completadas:** `INBOX.md` — el TUI escribe aquí al terminar cada task; léelo al inicio de cada respuesta
 - **Protocolo de agentes:** `AGENT-PROTOCOL.md` (reglas compartidas opcionales)
 - **Instrucciones por agente:** `agents/*.md`
 - **Memoria persistente:** `ENGRAM.md`

package/templates/es/orchestrator.config.json

@@ -63,21 +63,21 @@
     "Codex": {
       "cli": "codex",
       "profile": "codex",
-      "defaultRepo": "backend",
+      "defaultRepo": "frontend",
       "model": "gpt-5.5",
       "instructionsFile": "agents/CODEX.md"
     },
     "Gemini": {
       "cli": "gemini",
       "profile": "gemini",
-      "defaultRepo": "backend",
+      "defaultRepo": "frontend",
       "model": "gemini-3-pro-preview",
       "instructionsFile": "agents/GEMINI.md"
     },
     "OpenCode": {
       "cli": "opencode",
       "profile": "opencode",
-      "defaultRepo": "backend",
+      "defaultRepo": "frontend",
       "model": "opencode/glm-5-free",
       "instructionsFile": "agents/OPENCODE.md"
     },