@liriraid/agentflow-ai 1.0.19 → 1.0.21

package/README.md

@@ -1,79 +1,232 @@
-# agentflow
+# agentflow-ai
 
-Reusable multi-agent orchestration workspace for coding projects.
+**Multi-Agent Orchestration System for AI-Powered Development**
 
-This package installs a CLI that creates a separate orchestrator workspace next to your real project. The generated workspace can be created in **English** or **Spanish**.
+A reusable workspace orchestrator that coordinates multiple AI coding agents (Claude, Codex, OpenCode, etc.) to work **in parallel** on real projects, while keeping the project repository **completely clean** of orchestrator files.
 
 ```text
-my-product-workspace/
-  my-product/                 # real project, stays clean
-  orchestrator-my-product/    # generated orchestrator workspace
+project-workspace/
+  my-project/          # Real project (stays clean)
+  orchestrator-my-project/  # Orchestrator workspace (generated)
 ```
 
-## Install
-
+## 🎯 What It Does
+
+- **Coordinates multiple AI agents** (Claude, Codex, OpenCode, Gemini, Cursor, Abacus) to work simultaneously on your project.
+- **Real-time monitoring** with a modern TUI (Terminal User Interface) that shows live agent status, queue, and progress.
+- **Automatic task delegation** based on agent specialization (analysis, implementation, code review).
+- **Persistent memory** using Engram to maintain context across sessions.
+- **Spec-Driven Development (SDD)** support with OpenSpec for large, multi-phase changes.
+- **Fallback system** that automatically reassigns tasks when an agent fails or reaches rate limits.
+- **Multi-language support** (English and Spanish) for all templates and documentation.
+
+## ✨ Key Features
+
+### 1. **Sibling Workspace Model**
+- The orchestrator creates a **separate workspace** next to your real project.
+- Your project repository **stays completely clean** (no `QUEUE.md`, `logs/`, or orchestrator files).
+- Agents work on the real project files via absolute paths configured in `orchestrator.config.json`.
+
+### 2. **Multi-Agent Coordination**
+| Agent | Role | Priority | Notes |
+|-------|------|----------|-------|
+| **Claude-Orchestrator** | Session coordinator | - | Never implements code directly; delegates to workers |
+| **Codex** | Primary implementation | 1st choice | Structured tasks, tests, docs |
+| **OpenCode** | Analysis + Implementation | 2nd choice | Uses Mistral Medium 3.5 128B for coding |
+| **Claude-Worker** (Backend/Frontend) | Fallback implementation | 3rd choice | Takes over when Codex/OpenCode fail |
+| **Gemini** | Code review/audits | Optional | Disabled by default |
+| **Cursor/Abacus** | Mechanical tasks | Optional | Disabled by default |
+
+### 3. **Real-Time Operation**
+- **fs.watch on QUEUE.md**: Detects changes in **~1-2 seconds** (Linux/macOS: direct file watch; Windows: directory watch fallback).
+- **Live TUI updates**: The dashboard refreshes automatically when tasks are added, started, or completed.
+- **Instant notifications**: Claude-Orchestrator receives alerts in `INBOX.md` and `NOTIFY.md` when tasks finish.
+
+### 4. **Smart Task Delegation**
+- **Analysis tasks** → Always assigned to **OpenCode**.
+- **Implementation tasks** → Assigned to **Codex** (1st) → **OpenCode** (2nd, if using Mistral Medium 3.5 128B) → **Claude-Worker** (3rd).
+- **Fallback chain**: `Codex → OpenCode → Claude-Worker` (automatic).
+
+### 5. **Persistent Memory & SDD**
+- **Engram**: Stores decisions, bugs, and findings across sessions.
+- **OpenSpec**: Supports `proposal.md`, `spec.md`, `design.md`, `tasks.md`, and `verify-report.md` for large changes.
+- **Handoffs**: Session summaries for continuity.
+
+## 🚀 Installation
+
+### Global CLI (Recommended)
 ```bash
-npm i -g @liriraid/agentflow
+npm i -g @liriraid/agentflow-ai
 ```
 
-## Create a Workspace
-
-Interactive language selection:
-
+### Local Development
 ```bash
-agentflow init-workspace C:/code/my-project
+git clone https://github.com/LiriRaid/agentflow-ai.git
+cd agentflow-ai
+npm install
 ```
 
-Direct language selection:
+## 🛠️ Quick Start
 
+### 1. Create an Orchestrator Workspace
 ```bash
+# Interactive (asks for language)
+agentflow init-workspace C:/code/my-project
+
+# Direct (English)
 agentflow init-workspace C:/code/my-project --lang en
+
+# Direct (Spanish)
 agentflow init-workspace C:/code/mi-proyecto --lang es
 ```
+This creates a sibling workspace (e.g., `orchestrator-my-project/`) with all configuration files.
+
+### 2. Configure Repositories
+Edit `orchestrator.config.json` in the generated workspace:
+```json
+{
+  "repos": {
+    "backend": "C:/code/my-backend",
+    "frontend": "C:/code/my-frontend"
+  }
+}
+```
 
-The selected language controls the generated workspace files:
-
-- `ORCHESTRATOR.md`
-- `CLAUDE.md`
-- `QUEUE.md`
-- `PROJECT.md`
-- `README.md`
-- `agents/`
-- `docs/`
-- `openspec/`
-- `.claude/`
-- `.codex/`
-- `.opencode/`
-- `.atl/`
-- `orchestrator.config.json`
-
-## Runtime
-
-The package runtime remains language-aware through `workspaceLanguage` in the generated `orchestrator.config.json`.
-
-Start the TUI from the generated orchestrator workspace:
-
+### 3. Start the TUI
 ```bash
-cd C:/code/orchestrator-my-project
+cd orchestrator-my-project
 agentflow ink --paused
 ```
+**Controls:**
+- `S`: Start/Resume
+- `P`: Pause
+- `R`: Reload queue
+- `Q`: Quit (stops all agents)
+
+### 4. Launch Claude Code
+Open a second terminal in the **orchestrator workspace** (not the real project):
+```bash
+cd orchestrator-my-project
+claude
+```
+Then run:
+```
+Read ORCHESTRATOR.md and start.
+```
 
-Then open Claude Code in the same workspace and start with the prompt from that workspace's `ORCHESTRATOR.md`.
-
-## What Gets Packaged
+### 5. Request Work
+Examples:
+- `"Explore this project"` → OpenCode analyzes and reports.
+- `"Add JWT authentication"` → OpenCode analyzes, then Codex/OpenCode implement.
+- `"Refactor the API layer"` → OpenCode explores, then workers implement in parallel.
 
-The npm package ships:
+## 📁 Workspace Structure
 
-- `bin/`
-- `src/`
-- `scripts/`
-- `templates/en/`
-- `templates/es/`
-- `orchestrator.js`
-- `LICENSE`
+The generated workspace includes:
 
-The workspace docs and prompts live inside `templates/en` and `templates/es`; they are copied into the generated workspace based on the selected language.
+```text
+orchestrator-my-project/
+├── ORCHESTRATOR.md      # Core rules for the orchestrator session
+├── CLAUDE.md            # Routing rules for Claude
+├── QUEUE.md             # Active task queue (TASK-NNN | title | agent | ...)
+├── ENGRAM.md            # Persistent memory conventions
+├── orchestrator.config.json  # Repos, agents, models, and profiles
+├── agents/              # Agent-specific instructions
+│   ├── BACKEND.md
+│   ├── FRONTEND.md
+│   ├── CODEX.md
+│   └── OPENCODE.md
+├── .claude/             # Local Claude skills and config
+│   └── skills/          # Orchestrator skills (init, explore, etc.)
+├── .codex/              # Codex config
+├── .opencode/           # OpenCode config
+├── openspec/            # SDD artifacts
+│   ├── changes/
+│   └── templates/
+├── docs/                # Documentation
+├── logs/                # Execution logs
+├── handoffs/            # Session handoffs
+└── progress/            # Agent progress reports
+```
 
-## Acknowledgements
+## 🎛️ Configuration
+
+### Agent Configuration (`orchestrator.config.json`)
+```json
+{
+  "projectName": "My Project",
+  "workspaceLanguage": "es",
+  "maxConcurrent": 5,
+  "pollIntervalSeconds": 5,  // Fallback polling (realtime uses fs.watch)
+  "taskTimeoutMinutes": 30,
+  "repos": {
+    "backend": "C:/code/my-backend",
+    "frontend": "C:/code/my-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" }
+  }
+}
+```
 
-Inspired by [Orquestador-AI](https://github.com/ariellontero/Orquestador-AI) by Ariel Lontero (originally MIT). Built from scratch with a different architecture (Ink TUI, npm package, multi-language template system).
+### Model Selection
+- Use `"model": "auto"` to let the agent use your default configured model (e.g., Mistral Medium 3.5 128B for OpenCode).
+- Specify a model explicitly (e.g., `"model": "gpt-5.5"`) to override.
+
+## 🔄 Workflow Example
+
+1. **User Request**: `"Add user authentication to the backend."`
+2. **Claude-Orchestrator**:
+   - Creates `TASK-001` (OpenCode): `"Analyze current auth system"`
+   - Waits for OpenCode's report in `progress/PROGRESS-OpenCode.md`
+3. **OpenCode**:
+   - Analyzes the codebase.
+   - Writes findings to `progress/PROGRESS-OpenCode.md` and `INBOX.md`.
+4. **Claude-Orchestrator**:
+   - Reads OpenCode's report.
+   - Creates `TASK-002` (Codex): `"Implement JWT auth"` (depends on TASK-001).
+5. **Codex**:
+   - Implements the feature.
+   - Reports completion in `progress/PROGRESS-Codex.md`.
+6. **TUI**:
+   - Shows real-time updates (task status, agent activity, costs).
+
+## 📊 Supported Agents & Models
+
+| Agent | CLI | Default Model | Implementation? | Notes |
+|-------|-----|----------------|----------------|-------|
+| Backend | `claude` | sonnet | ✅ Yes | Claude-Worker for backend tasks |
+| Frontend | `claude` | sonnet | ✅ Yes | Claude-Worker for frontend tasks |
+| Codex | `codex` | gpt-5.5 | ✅ Yes | Primary implementation |
+| OpenCode | `opencode` | auto | ✅ **Yes** (with Mistral Medium 3.5 128B) | Secondary implementation |
+| Gemini | `gemini` | auto | ❌ No | Audits/reviews only |
+| Cursor | `cursor` | auto | ❌ No | Bulk edits only |
+| Abacus | `abacusai` | auto | ❌ No | Small focused tasks |
+
+## 🛡️ Safety & Best Practices
+
+- **No auto-commits**: Agents never run `git commit` or `git push`.
+- **No YOLO by default**: Safe permissions mode is enabled unless `--yolo` is used.
+- **Claude as reviewer**: Claude-Orchestrator validates all work before user approval.
+- **Clean repos**: Project files stay untouched; orchestrator files live in the sibling workspace.
+- **Fallback safety**: Tasks are automatically reassigned if an agent fails.
+
+## 📚 Documentation
+
+- **Core Rules**: See `ORCHESTRATOR.md` in the generated workspace.
+- **Agent Routing**: See `CLAUDE.md`.
+- **Architecture**: See `docs/architecture.md`.
+- **OpenSpec**: See `openspec/FLOW.md`.
+
+## 🤝 Acknowledgements
+
+Inspired by [Orquestador-AI](https://github.com/ariellontero/Orquestador-AI) by Ariel Lontero (MIT). 
+Built from scratch with a modern architecture: **Ink TUI + React, npm package, real-time fs.watch, multi-language templates, and multi-agent coordination**.

package/orchestrator.js

@@ -122,6 +122,7 @@ const config = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"));
 
 const QUEUE_FILE = path.join(WORKSPACE, "QUEUE.md");
 const INBOX_FILE = path.join(WORKSPACE, "INBOX.md");
+const NOTIFY_FILE = path.join(WORKSPACE, "NOTIFY.md");
 const AWAY_MODE_FILE = path.join(WORKSPACE, ".away-mode");
 const LOG_DIR = path.join(WORKSPACE, "logs");
 
@@ -266,6 +267,11 @@ const TEXT = {
     inboxReasonLabel: "- **Motivo:**",
     inboxNewAgentLabel: "- **Nuevo agente:**",
     inboxFailAction: "- **Acción:** La TUI reasignó automáticamente. Verifica en QUEUE.md o espera la siguiente notificación de completada.",
+    // NOTIFY.md — notificación concisa a la sesión interactiva de Claude
+    notifyComplete: (ts, id, agent, dur) => `🔔 [${ts}] ${id} completada por ${agent} (${dur}).\nRevisa INBOX.md y crea la siguiente tarea de implementación en QUEUE.md si aún no existe.`,
+    notifyFailed: (ts, id, from, to, reason) => `⚠️ [${ts}] ${id} falló en ${from} → reasignada a ${to}.\nMotivo: ${reason}\nRevisa INBOX.md para el contexto.`,
+    notifyPermanentFail: (ts, id, agent) => `🚨 [${ts}] ${id} falló permanentemente en ${agent} (sin más reintentos).\nDecide si eliminar, reasignar o escalar la tarea en QUEUE.md.`,
+    notifyRateLimit: (ts, id, agent, resetStr, retries, max) => `⏳ [${ts}] ${id} — ${agent} alcanzó el límite de tokens (reintento ${retries}/${max}, ${resetStr}).\nSi quieres reasignar ahora: asigna a Claude-Worker (Frontend). Si esperas, reintentará automáticamente.`,
   },
   en: {
     configExists:
@@ -370,6 +376,11 @@ const TEXT = {
     inboxReasonLabel: "- **Reason:**",
     inboxNewAgentLabel: "- **New agent:**",
     inboxFailAction: "- **Action:** TUI reassigned automatically. Check QUEUE.md or wait for the next completion notification.",
+    // NOTIFY.md — concise notification to the interactive Claude session
+    notifyComplete: (ts, id, agent, dur) => `🔔 [${ts}] ${id} completed by ${agent} (${dur}).\nCheck INBOX.md and create the next implementation task in QUEUE.md if it does not exist yet.`,
+    notifyFailed: (ts, id, from, to, reason) => `⚠️ [${ts}] ${id} failed on ${from} → reassigned to ${to}.\nReason: ${reason}\nCheck INBOX.md for context.`,
+    notifyPermanentFail: (ts, id, agent) => `🚨 [${ts}] ${id} permanently failed on ${agent} (no more retries).\nDecide whether to remove, reassign, or escalate the task in QUEUE.md.`,
+    notifyRateLimit: (ts, id, agent, resetStr, retries, max) => `⏳ [${ts}] ${id} — ${agent} hit token/rate limit (retry ${retries}/${max}, ${resetStr}).\nTo reassign now: assign to Claude-Worker (Frontend). Otherwise it will retry automatically.`,
   },
 };
 const L = TEXT[WORKSPACE_LANGUAGE];
@@ -999,6 +1010,36 @@ function parseCompletedFromFile() {
 }
 
 const loggedUnknownAgents = new Set();
+let queueWatcher = null;
+
+function setupQueueWatcher() {
+  if (!fs.existsSync(QUEUE_FILE)) return;
+  
+  if (queueWatcher) {
+    try { queueWatcher.close(); } catch {}
+    queueWatcher = null;
+  }
+  
+  try {
+    queueWatcher = fs.watch(QUEUE_FILE, { persistent: false }, (eventType, filename) => {
+      if (eventType === 'change' && filename === path.basename(QUEUE_FILE)) {
+        log('DEBUG', `QUEUE.md changed, reloading queue immediately`);
+        reloadQueue();
+        scheduleNext();
+        renderDashboard();
+      }
+    });
+    queueWatcher.on('error', (err) => {
+      log('WARN', `fs.watch failed for QUEUE.md: ${err.message}, falling back to polling`);
+      queueWatcher = null;
+    });
+    log('INFO', 'Realtime QUEUE.md watcher enabled');
+  } catch (err) {
+    log('WARN', `Failed to setup QUEUE.md watcher: ${err.message}, using polling`);
+    queueWatcher = null;
+  }
+}
+
 function reloadQueue() {
   state.queue = parseQueue();
   const activeIds = new Set([
@@ -1064,6 +1105,15 @@ function writeInboxFailureNotification(task, failedAgent, newAgent, reason) {
   } catch {}
 }
 
+// Escribe una notificación concisa en NOTIFY.md para la sesión interactiva de Claude.
+// Los hooks de .claude/settings.json leen y limpian este archivo automáticamente.
+function writeNotifyFile(message) {
+  try {
+    const sep = fs.existsSync(NOTIFY_FILE) ? '\n---\n' : '';
+    fs.appendFileSync(NOTIFY_FILE, sep + message + '\n', 'utf-8');
+  } catch {}
+}
+
 // GAP 2 — Move a task line from ## Pending to ## In Progress when it starts
 function moveTaskToInProgress(task) {
   if (!fs.existsSync(QUEUE_FILE)) return;
@@ -1523,6 +1573,7 @@ function completeTask(task, agentName) {
   ag.lastLine = L.lastCompleted(task.id);
   updateQueueFile(task);
   writeInboxNotification(task, agentName, elapsed);
+  writeNotifyFile(L.notifyComplete(timestamp(), task.id, agentName, formatDuration(elapsed)));
   scheduleNext();
   renderDashboard();
 }
@@ -1591,6 +1642,7 @@ function failTask(task, agentName, code) {
       `{yellow-fg}${escBl(L.agentRateLimit(resetStr))}{/yellow-fg}`,
       true,
     );
+    writeNotifyFile(L.notifyRateLimit(timestamp(), task.id, agentName, resetStr, retries, maxRetries));
   } else {
     log("FAIL", L.logFail(agentName, task.id, code, retries, maxRetries));
     appendToAgent(
@@ -1622,6 +1674,7 @@ function failTask(task, agentName, code) {
           : L.reasonPersistent;
     if (tryFallbackToAlternative(task, agentName, reason)) {
       writeInboxFailureNotification(task, agentName, task.agent, reason);
+      writeNotifyFile(L.notifyFailed(timestamp(), task.id, agentName, task.agent, reason));
       setTimeout(() => {
         scheduleNext();
         safeRenderDashboard();
@@ -1634,6 +1687,7 @@ function failTask(task, agentName, code) {
     task.status = "failed";
     ag.lastLine = L.lastFailed(task.id);
     log("ERROR", L.logPermanentFail(task.id, retries));
+    writeNotifyFile(L.notifyPermanentFail(timestamp(), task.id, agentName));
   } else {
     task.status = "pending";
     let retryDelay = rl.isRateLimit
@@ -1817,7 +1871,6 @@ function getClaudeFallbackAgent(task) {
 }
 
 function getAlternativeSupportAgent(failedAgentName) {
-  if (failedAgentName === "Codex") return "OpenCode";
   if (failedAgentName === "OpenCode") return "Codex";
   return null;
 }
@@ -1825,7 +1878,7 @@ function getAlternativeSupportAgent(failedAgentName) {
 function tryFallbackToAlternative(task, failedAgentName, reason) {
   if (!["Codex", "OpenCode"].includes(failedAgentName)) return false;
 
-  // Step 1: try sibling support agent (Codex → OpenCode, OpenCode → Codex)
+  // Step 1: try sibling support agent (OpenCode → Codex only; Codex falls through directly)
   const siblingAgent = getAlternativeSupportAgent(failedAgentName);
   const siblingAvailable =
     siblingAgent &&
@@ -1931,16 +1984,59 @@ setInterval(() => {
   if (command) applyControlCommand(command);
 }, 1000);
 
-// Real-time queue detection via fs.watch — fires immediately when QUEUE.md changes
-// (e.g. Claude writes a new task). No more 30s delay.
+// Real-time queue detection — watches QUEUE.md directly with fallback to WORKSPACE directory
+// fs.watch on the file itself works reliably on Linux/macOS; fallback to WORKSPACE for Windows
 let _queueWatchDebounce = null;
+let _queueWatcher = null;
+
 function startQueueWatcher() {
-  if (!fs.existsSync(QUEUE_FILE)) return;
+  if (_queueWatcher) {
+    try { _queueWatcher.close(); } catch {}
+    _queueWatcher = null;
+  }
+  
+  try {
+    // Try to watch the file directly first (best for Linux/macOS)
+    _queueWatcher = fs.watch(QUEUE_FILE, { persistent: false }, (eventType, filename) => {
+      if (_queueWatchDebounce) clearTimeout(_queueWatchDebounce);
+      _queueWatchDebounce = setTimeout(() => {
+        if (!fs.existsSync(QUEUE_FILE)) return;
+        const prevCount = state.queue.length;
+        reloadQueue();
+        if (!state.paused) scheduleNext();
+        renderDashboard();
+        if (state.queue.length > prevCount)
+          log("INFO", WORKSPACE_LANGUAGE === "es"
+            ? `Nueva tarea detectada en QUEUE.md (realtime)`
+            : `New task detected in QUEUE.md (realtime)`);
+      }, 10); // Faster debounce for direct file watch
+    });
+    _queueWatcher.on('error', () => {
+      // Fallback to WORKSPACE directory watch if direct file watch fails (Windows)
+      log('WARN', WORKSPACE_LANGUAGE === "es"
+        ? `No se pudo verificar QUEUE.md directamente, usando watcher de directorio`
+        : `Could not watch QUEUE.md directly, falling back to directory watcher`);
+      setupFallbackQueueWatcher();
+    });
+  } catch (err) {
+    log('WARN', `Queue watcher error: ${err.message}, using fallback`);
+    setupFallbackQueueWatcher();
+  }
+}
+
+function setupFallbackQueueWatcher() {
+  if (_queueWatcher) {
+    try { _queueWatcher.close(); } catch {}
+    _queueWatcher = null;
+  }
+  
   try {
-    const watcher = fs.watch(QUEUE_FILE, {persistent: false}, (eventType) => {
-      if (eventType !== 'change') return;
+    const watchName = path.basename(QUEUE_FILE);
+    _queueWatcher = fs.watch(WORKSPACE, { persistent: false }, (eventType, filename) => {
+      if (filename !== watchName) return;
       if (_queueWatchDebounce) clearTimeout(_queueWatchDebounce);
       _queueWatchDebounce = setTimeout(() => {
+        if (!fs.existsSync(QUEUE_FILE)) return;
         const prevCount = state.queue.length;
         reloadQueue();
         if (!state.paused) scheduleNext();
@@ -1951,10 +2047,12 @@ function startQueueWatcher() {
             : `New task detected in QUEUE.md`);
       }, 50);
     });
-    watcher.on('error', () => {});
+    _queueWatcher.on('error', () => {});
   } catch {}
 }
+
 startQueueWatcher();
+setupQueueWatcher();
 
 // Slow fallback (5 min) — only runs if there is actually pending work or busy agents
 // fs.watch handles real-time; this is just a safety net
@@ -2042,8 +2140,9 @@ function startInboxWatcher() {
     try { fs.writeFileSync(INBOX_FILE, '', 'utf-8'); } catch {}
   }
   try {
-    const watcher = fs.watch(INBOX_FILE, {persistent: false}, (eventType) => {
-      if (eventType !== 'change') return;
+    const watchName = path.basename(INBOX_FILE);
+    const watcher = fs.watch(WORKSPACE, {persistent: false}, (eventType, filename) => {
+      if (filename !== watchName) return;
       if (_inboxDebounce) clearTimeout(_inboxDebounce);
       _inboxDebounce = setTimeout(dispatchInboxClaude, 100);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liriraid/agentflow-ai",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "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/src/ink/index.mjs

@@ -393,11 +393,16 @@ function shutdown() {
 }
 
 // Reactivo: dispara un refresh inmediato cuando el engine escribe el STATE_FILE.
-// Esto elimina el lag de polling para cambios de cola y estado de agentes.
+// Vigila el directorio logs/ (no el archivo directamente) porque en Windows
+// fs.watch sobre un archivo es poco confiable — el patrón estable es vigilar
+// el directorio padre y filtrar por nombre de archivo.
 function ensureStateWatcher() {
-	if (stateWatcher || !fs.existsSync(STATE_FILE)) return;
+	const logsDir = path.dirname(STATE_FILE);
+	const stateFileName = path.basename(STATE_FILE);
+	if (stateWatcher || !fs.existsSync(logsDir)) return;
 	try {
-		stateWatcher = fs.watch(STATE_FILE, {persistent: false}, () => {
+		stateWatcher = fs.watch(logsDir, {persistent: false}, (eventType, filename) => {
+			if (filename !== stateFileName) return;
 			if (stateWatchDebounce) clearTimeout(stateWatchDebounce);
 			stateWatchDebounce = setTimeout(() => {
 				if (quitRequested) return;

package/templates/en/.claude/hooks/notify-check.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+'use strict';
+// Reads NOTIFY.md from the workspace and writes its content to stdout so the
+// Claude Code hook injects it into the interactive session.
+// The file is deleted after reading to avoid repeating the notification.
+const fs = require('fs');
+const path = require('path');
+
+const notifyFile = path.join(process.cwd(), 'NOTIFY.md');
+if (!fs.existsSync(notifyFile)) process.exit(0);
+
+const content = fs.readFileSync(notifyFile, 'utf8').trim();
+if (!content) {
+  try { fs.unlinkSync(notifyFile); } catch {}
+  process.exit(0);
+}
+
+try { fs.unlinkSync(notifyFile); } catch {}
+
+process.stdout.write('\n' + content + '\n');

package/templates/en/.claude/settings.json

@@ -0,0 +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"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -5,7 +5,7 @@ description: >
 license: MIT
 metadata:
   owner: agentflow
-  version: "1.0"
+  version: "1.1"
 ---
 
 # Skill: orchestrator-explore
@@ -18,12 +18,15 @@ Gather useful context before creating TASKs or OpenSpec artifacts.
 
 - Understand the user's exact scope first.
 - Prefer exploration before implementation when context is unclear.
-- Use OpenCode as the first support worker for broad reading, audits, and structured findings when appropriate.
+- Use **ONLY OpenCode** as the exploration agent when deep codebase analysis is needed — its role is **EXCLUSIVELY analysis**, **NEVER implementation**.
+- When delegating exploration to OpenCode, include in the brief exactly what it must report: flows, dependencies, architecture findings, inconsistencies, etc.
 - Do not fill `QUEUE.md` with implementation tasks until enough context exists.
 - Summarize findings in actionable terms: what exists, what is missing, what risks exist, and what tasks follow.
 - If the change is large or multi-phase, move toward OpenSpec.
-- If work is clear, convert findings into concrete TASKs.
+- If work is clear, convert findings into concrete TASKs using `orchestrator-queue-planning`.
+- **STRICT RULE: When OpenCode delivers its report in INBOX.md, use THOSE findings to create implementation TASKs (assigned to Codex or Claude-Worker). Under NO circumstances should Claude-Orchestrator re-analyze the code itself if OpenCode has already done so. Read the report in `progress/PROGRESS-OpenCode.md` or INBOX.md and base your decisions on that analysis.**
+- If OpenCode's report is insufficient, ask OpenCode to deepen analysis on a specific area with a new analysis TASK, but **DO NOT do it yourself**.
 
 ## Expected Result
 
-The orchestrator can decide whether to plan TASKs or continue investigation.
+The orchestrator can decide whether to plan TASKs or continue investigation. **The final result MUST be one or more TASKs in QUEUE.md assigned to Codex or Claude-Worker for implementation, NOT more analysis by Claude-Orchestrator.**

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

@@ -5,7 +5,7 @@ description: >
 license: MIT
 metadata:
   owner: agentflow
-  version: "1.0"
+  version: "1.1"
 ---
 
 # Skill: orchestrator-queue-planning
@@ -14,17 +14,36 @@ metadata:
 
 Turn the user's request into executable queue work for the TUI.
 
+## Agent Assignment Rules
+
+### OpenCode — analysis only
+- Use for exploration, audits, context reading, and structured reports.
+- **Do not assign implementation** — OpenCode does not modify project files.
+- If work needs prior analysis, create an OpenCode TASK first, then a Codex TASK with `> after:TASK-NNN`.
+
+### Codex — primary implementation
+- Use for implementation, code changes, tests, and docs when the spec is clear.
+- It is the primary execution agent.
+- If Codex fails persistently, the TUI automatically reassigns to Claude-Worker (Frontend/Backend).
+
+### Claude-Worker (Frontend / Backend)
+- Automatic fallback when Codex fails.
+- Also takes overflow work when both Codex and OpenCode are busy and more tasks are pending.
+- Frontend-only projects: always use `Frontend`; backend work: use `Backend`.
+
 ## Critical Rules
 
 - Create small, concrete, executable TASKs.
 - Every TASK must include agent, priority, repo, and a clear description.
 - Use `> after:TASK-NNN` for dependencies.
 - Do not implement the task directly as Claude-Orchestrator.
-- Prefer assigning first executable work to `Codex` or `OpenCode` when they are suitable.
-- Use Claude-Worker only for fallback, extra capacity, sensitive work, broad implementation, or when explicitly requested.
-- Codex can work in `repo=frontend`, but only for narrow, clear, verifiable tasks.
-- Broad frontend work should go to `Frontend`/Claude-Worker.
+- Distribution by task count:
+  - **1 analysis task**: OpenCode
+  - **1 implementation task**: Codex
+  - **2 parallel tasks**: OpenCode (analysis) + Codex (implementation when spec is clear)
+  - **3+ tasks** with Codex busy: overflow goes to `Frontend` (FE repo) or `Backend` (BE repo)
 - Keep `QUEUE.md` aligned with the user's current objective.
+- **Never assign implementation to OpenCode.**
 
 ## Expected Result