refacil-sdd-ai 3.0.3 → 4.0.0

package/lib/ignore-files.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const BASE_ENTRIES = [
+  '# Dependencias',
+  'node_modules/',
+  '',
+  '# Build/dist',
+  'dist/',
+  'build/',
+  '.next/',
+  'out/',
+  '',
+  '# Logs',
+  '*.log',
+  'logs/',
+  'npm-debug.log*',
+  '',
+  '# Cache y temporales',
+  '.cache/',
+  'tmp/',
+  'temp/',
+  '.parcel-cache/',
+  '.turbo/',
+  '',
+  '# Binarios y medios pesados',
+  '*.png',
+  '*.jpg',
+  '*.jpeg',
+  '*.gif',
+  '*.svg',
+  '*.pdf',
+  '*.zip',
+  '*.tar.gz',
+  '*.mp4',
+  '*.mp3',
+  '',
+  '# Secretos y credenciales',
+  '.env',
+  '.env.*',
+  '*.pem',
+  '*.key',
+  'credentials.json',
+  'secrets.json',
+  '',
+  '# Cobertura y reportes',
+  'coverage/',
+  '.nyc_output/',
+];
+
+function isSignificant(line) {
+  const trimmed = line.trim();
+  return trimmed.length > 0 && !trimmed.startsWith('#');
+}
+
+function syncIgnoreFile(filePath) {
+  const significantBase = BASE_ENTRIES.filter(isSignificant);
+
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, BASE_ENTRIES.join('\n') + '\n');
+    return { status: 'created', added: significantBase.length };
+  }
+
+  const existing = fs.readFileSync(filePath, 'utf8');
+  const existingLines = existing.split('\n').map((l) => l.trim());
+
+  const missing = BASE_ENTRIES.filter(
+    (entry) => isSignificant(entry) && !existingLines.includes(entry.trim()),
+  );
+
+  if (missing.length === 0) {
+    return { status: 'noop', added: 0 };
+  }
+
+  const separator = existing.endsWith('\n') ? '' : '\n';
+  fs.writeFileSync(filePath, existing + separator + missing.join('\n') + '\n');
+  return { status: 'updated', added: missing.length };
+}
+
+function syncIgnoreFiles(projectRoot) {
+  const claude = syncIgnoreFile(path.join(projectRoot, '.claudeignore'));
+  const cursor = syncIgnoreFile(path.join(projectRoot, '.cursorignore'));
+  return { claude, cursor };
+}
+
+module.exports = { syncIgnoreFiles, BASE_ENTRIES };

package/lib/installer.js

@@ -0,0 +1,265 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SKILLS = [
+  'setup',
+  'prereqs',
+  'guide',
+  'explore',
+  'propose',
+  'apply',
+  'test',
+  'verify',
+  'review',
+  'archive',
+  'bug',
+  'up-code',
+  'join',
+  'say',
+  'ask',
+  'reply',
+  'inbox',
+  'attend',
+  'update',
+];
+
+const AGENTS = [
+  'auditor',
+  'investigator',
+  'validator',
+];
+
+const REPO_VERSION_FILES = ['.claude/.sdd-version', '.cursor/.sdd-version'];
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function installSkills(packageRoot, projectRoot) {
+  let installed = 0;
+  for (const skill of SKILLS) {
+    const srcDir = path.join(packageRoot, 'skills', skill);
+    if (!fs.existsSync(srcDir)) continue;
+
+    const claudeDest = path.join(projectRoot, '.claude', 'skills', `refacil-${skill}`);
+    copyDir(srcDir, claudeDest);
+
+    const cursorDest = path.join(projectRoot, '.cursor', 'skills', `refacil-${skill}`);
+    copyDir(srcDir, cursorDest);
+
+    installed++;
+  }
+  return installed;
+}
+
+// Claude Code: tools allowlist granular, model: sonnet|opus|haiku
+// Cursor: readonly: true|false (booleano), model: inherit (default)
+function transformFrontmatterForCursor(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return content;
+
+  const [, frontmatterRaw, body] = match;
+  const lines = frontmatterRaw.split('\n');
+  const out = [];
+  let toolsLine = null;
+  let hasReadonly = false;
+
+  for (const line of lines) {
+    if (line.startsWith('tools:')) {
+      toolsLine = line;
+      continue;
+    }
+    if (line.startsWith('readonly:')) {
+      hasReadonly = true;
+      out.push(line);
+      continue;
+    }
+    if (line.startsWith('model:')) {
+      const value = line.slice('model:'.length).trim();
+      if (value === 'sonnet' || value === 'opus' || value === 'haiku') {
+        out.push('model: inherit');
+      } else {
+        out.push(line);
+      }
+      continue;
+    }
+    out.push(line);
+  }
+
+  if (toolsLine && !hasReadonly) {
+    const toolsList = toolsLine.slice('tools:'.length).trim();
+    const canWrite = /\b(Edit|Write|NotebookEdit)\b/.test(toolsList);
+    out.push(`readonly: ${canWrite ? 'false' : 'true'}`);
+  }
+
+  return `---\n${out.join('\n')}\n---\n${body}`;
+}
+
+function installAgents(packageRoot, projectRoot) {
+  let installed = 0;
+
+  const claudeDir = path.join(projectRoot, '.claude', 'agents');
+  const cursorDir = path.join(projectRoot, '.cursor', 'agents');
+  fs.mkdirSync(claudeDir, { recursive: true });
+  fs.mkdirSync(cursorDir, { recursive: true });
+
+  for (const agent of AGENTS) {
+    const srcFile = path.join(packageRoot, 'agents', `${agent}.md`);
+    if (!fs.existsSync(srcFile)) continue;
+
+    const content = fs.readFileSync(srcFile, 'utf8');
+
+    fs.writeFileSync(path.join(claudeDir, `refacil-${agent}.md`), content);
+    fs.writeFileSync(
+      path.join(cursorDir, `refacil-${agent}.md`),
+      transformFrontmatterForCursor(content),
+    );
+
+    installed++;
+  }
+
+  return installed;
+}
+
+function writeGuideFile(destPath, header, label) {
+  const content =
+    `# ${header}\n\n` +
+    'Contexto completo del proyecto: ver `AGENTS.md`.\n' +
+    'Si no existe, ejecuta `/refacil:setup`.\n';
+  fs.writeFileSync(destPath, content);
+  console.log(`  ${label} generado.`);
+  return true;
+}
+
+function createClaudeMd(packageRoot, projectRoot) {
+  return writeGuideFile(
+    path.join(projectRoot, 'CLAUDE.md'),
+    'CLAUDE.md',
+    'CLAUDE.md',
+  );
+}
+
+function createCursorRules(packageRoot, projectRoot) {
+  return writeGuideFile(
+    path.join(projectRoot, '.cursorrules'),
+    'Cursor Rules',
+    '.cursorrules',
+  );
+}
+
+function readRepoVersion(rootDir) {
+  for (const rel of REPO_VERSION_FILES) {
+    const p = path.join(rootDir, rel);
+    try {
+      const raw = fs.readFileSync(p, 'utf8').trim();
+      if (raw) return raw;
+    } catch (_) {
+      // siguiente
+    }
+  }
+  return null;
+}
+
+function writeRepoVersion(rootDir, version) {
+  for (const rel of REPO_VERSION_FILES) {
+    const p = path.join(rootDir, rel);
+    const parent = path.dirname(p);
+    if (!fs.existsSync(parent)) continue;
+    try {
+      fs.writeFileSync(p, String(version) + '\n');
+    } catch (_) {
+      // tolerante
+    }
+  }
+}
+
+function getPackageVersion(packageRoot) {
+  try {
+    return require(path.join(packageRoot, 'package.json')).version;
+  } catch (_) {
+    return null;
+  }
+}
+
+function removeSkills(projectRoot) {
+  let removed = 0;
+  for (const skill of SKILLS) {
+    const claudeDir = path.join(projectRoot, '.claude', 'skills', `refacil-${skill}`);
+    const cursorDir = path.join(projectRoot, '.cursor', 'skills', `refacil-${skill}`);
+
+    if (fs.existsSync(claudeDir)) {
+      fs.rmSync(claudeDir, { recursive: true });
+      removed++;
+    }
+    if (fs.existsSync(cursorDir)) {
+      fs.rmSync(cursorDir, { recursive: true });
+    }
+  }
+  return removed;
+}
+
+function checkClaudeCodeVersion() {
+  const { execSync } = require('child_process');
+  try {
+    const output = execSync('claude --version 2>&1', {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    const match = output.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match) return { ok: null, version: null };
+    const maj = Number(match[1]);
+    const min = Number(match[2]);
+    const patch = Number(match[3]);
+    const ok =
+      maj > 2 ||
+      (maj === 2 && min > 1) ||
+      (maj === 2 && min === 1 && patch >= 89);
+    return { ok, version: `${maj}.${min}.${patch}` };
+  } catch (_) {
+    return { ok: null, version: null };
+  }
+}
+
+function checkNodeVersion() {
+  const version = process.version;
+  const major = parseInt(version.split('.')[0].replace('v', ''));
+  const minor = parseInt(version.split('.')[1]);
+
+  if (major < 20 || (major === 20 && minor < 19)) {
+    console.log(`\n  ADVERTENCIA: Node.js ${version} detectado.`);
+    console.log('  OpenSpec requiere Node.js >= 20.19.0.');
+    console.log('  Las skills se instalaran pero /refacil:setup podria fallar al instalar OpenSpec.\n');
+    return false;
+  }
+  return true;
+}
+
+module.exports = {
+  SKILLS,
+  AGENTS,
+  copyDir,
+  installSkills,
+  transformFrontmatterForCursor,
+  installAgents,
+  createClaudeMd,
+  createCursorRules,
+  readRepoVersion,
+  writeRepoVersion,
+  getPackageVersion,
+  removeSkills,
+  checkClaudeCodeVersion,
+  checkNodeVersion,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "3.0.3",
+  "version": "4.0.0",
   "description": "SDD-AI: Specification-Driven Development with AI — metodologia de desarrollo con IA usando OpenSpec, Claude Code y Cursor",
   "bin": {
     "refacil-sdd-ai": "./bin/cli.js"
@@ -12,7 +12,8 @@
     "agents/",
     "templates/",
     "config/",
-    "README.md"
+    "README.md",
+    "refacil-bus-diagrams.md"
   ],
   "keywords": [
     "ai",
@@ -35,6 +36,9 @@
   "engines": {
     "node": ">=20.19.0"
   },
+  "scripts": {
+    "test": "node --test test/hooks.test.js test/installer.test.js test/ignore-files.test.js"
+  },
   "dependencies": {
     "ws": "^8.18.0"
   }

package/refacil-bus-diagrams.md

@@ -0,0 +1,314 @@
+# refacil-bus — Diagramas y explicación
+
+Documento para presentar la feature al equipo. Usa Mermaid (se renderiza automático en GitHub, GitLab, Notion, Confluence, Teams, VS Code preview). Para exportar a imagen: https://mermaid.live
+
+---
+
+## 1. El problema que resolvemos
+
+Un único dev trabaja con varios repos abiertos al mismo tiempo — **una ventana de Claude Code o Cursor por repo** (microservicios + frontend + utilidades). Cada ventana tiene SU propio agente del LLM que solo conoce ese repo. Cuando el dev está trabajando en un repo y necesita contexto de otro, hoy tiene que:
+
+- pausar lo que está haciendo
+- **saltar a la ventana del otro repo**
+- leer código él mismo, o preguntarle al LLM de esa otra ventana
+- copiar la respuesta manualmente
+- volver a la ventana original y pegar/explicar al primer agente
+
+El resultado: **el dev queda de mensajero entre sus propios agentes**. Contexto se pierde, se transcribe mal, y los bugs cruzados aparecen en QA.
+
+> **Clave del caso de uso**: las "sesiones" en el bus NO son devs distintos — son los **agentes de LLM** de cada repo que el mismo dev tiene abiertos. El bus es para que esos agentes se hablen entre sí sin que el dev sea el intermediario.
+
+### Antes de refacil-bus
+
+```mermaid
+flowchart LR
+    D[Dev en ventana<br/>de payments-api] --> A[Pide al agente:<br/>crea endpoint<br/>POST /refund]
+    A --> B{¿El agente sabe cómo<br/>lo consume el front?}
+    B -->|No| C[Dev salta a la<br/>ventana del frontend]
+    C --> E[Lee código del front<br/>o pregunta al agente<br/>de esa ventana]
+    E --> F[Copia la respuesta<br/>mentalmente o literal]
+    F --> G[Vuelve a la ventana<br/>de payments-api]
+    G --> H[Pega/explica al<br/>agente de payments]
+    H --> I[Agente implementa<br/>con info transcrita]
+    B -->|Arriesga| J[Agente implementa<br/>según suposición]
+    J --> K[Bug en QA —<br/>campo mal nombrado]
+
+    classDef dev fill:#e3f2fd,stroke:#1976d2,color:#333
+    classDef manual fill:#ffe5b3,stroke:#e17055,color:#333
+    classDef pain fill:#ffe5e5,stroke:#d63031,color:#333
+    class D dev
+    class C,E,F,G,H manual
+    class B,J,K pain
+```
+
+El dev **termina siendo el bus humano** entre sus propios agentes.
+
+### Después de refacil-bus — Escenario A: el otro agente está en `/refacil:attend`
+
+El caso ideal. El dev dejó el agente del otro repo en modo escucha antes de empezar a trabajar en el primero.
+
+```mermaid
+flowchart LR
+    D[Dev en ventana<br/>de payments-api] --> A[Pide al agente:<br/>crea /refund,<br/>pregúntale al bus<br/>si necesitás algo]
+    A --> B[Agente payments ejecuta<br/>/refacil:ask @frontend<br/>&quot;...&quot; --wait 180]
+    B --> C[Agente frontend<br/>en /refacil:attend<br/>recibe la pregunta]
+    C --> E[Agente frontend lee<br/>SUS propios archivos<br/>y responde con<br/>/refacil:reply]
+    E --> F[Agente payments recibe<br/>la respuesta automática<br/>y sigue implementando]
+    F --> G[Endpoint correcto<br/>al primer intento]
+
+    classDef dev fill:#e3f2fd,stroke:#1976d2,color:#333
+    classDef auto fill:#d4edda,stroke:#28a745,color:#333
+    class D dev
+    class A,B,C,E,F,G auto
+```
+
+**El dev nunca cambió de ventana**. Los dos agentes se hablaron entre sí; cada uno consultó su código real. El dev se enteró solo cuando el primer agente le dijo "listo, endpoint implementado con estos campos".
+
+### Después de refacil-bus — Escenario B: el otro agente NO está en attend
+
+Aún hay ganancia, pero el dev sí tendrá que ir a la otra ventana al menos una vez — aunque con menos esfuerzo que antes.
+
+```mermaid
+flowchart LR
+    D[Dev en ventana<br/>de payments-api] --> A[Pide al agente:<br/>pregúntale al front...]
+    A --> B[Agente payments ejecuta<br/>/refacil:ask @frontend &quot;...&quot;]
+    B --> C[Mensaje queda en inbox.jsonl<br/>de la sala]
+    C --> E[Dev, cuando pueda,<br/>va a la ventana frontend]
+    E --> F[Dice al agente frontend:<br/>&quot;ejecutá /refacil:inbox<br/>y respondé lo que haya&quot;]
+    F --> G[Agente frontend lee SUS<br/>archivos y responde con<br/>/refacil:reply]
+    G --> H[Dev vuelve a payments;<br/>agente payments hace<br/>/refacil:inbox y continúa]
+
+    classDef dev fill:#e3f2fd,stroke:#1976d2,color:#333
+    classDef semi fill:#fff3cd,stroke:#ffc107,color:#333
+    class D,E dev
+    class A,B,C,F,G,H semi
+```
+
+**Ganancia aún sin attend**: el dev sigue saltando, **pero NO hace de transcriptor**. El agente de cada repo responde desde su código real; el dev solo "despacha" el trabajo entre agentes. Mucho menos fricción que copiar respuestas a mano.
+
+> **Conclusión práctica**: la magia del "cero saltos de ventana" aparece cuando el dev, antes de meterse en una tarea profunda, pone los agentes de los otros repos que podría necesitar consultar en `/refacil:attend`. Sin eso, el bus sigue siendo útil — evita la transcripción manual — pero el dev sí visita las otras ventanas para "activar" al agente.
+
+---
+
+## 2. Arquitectura — qué corre dónde
+
+El broker es un proceso local mínimo que solo enruta texto plano entre sesiones. **No transfiere archivos, contexto ni tokens entre repos**. Todas las ventanas son del mismo dev — el broker conecta a sus agentes entre sí.
+
+```mermaid
+flowchart TB
+    subgraph DEV[Máquina del Dev]
+        subgraph V1[Ventana IDE 1]
+            IDE1[Claude Code / Cursor<br/>en repo payments-api<br/>agente: payments-api]
+        end
+
+        subgraph V2[Ventana IDE 2]
+            IDE2[Claude Code / Cursor<br/>en repo frontend<br/>agente: frontend]
+        end
+
+        subgraph V3[Ventana IDE 3 · opcional]
+            IDE3[Claude Code / Cursor<br/>en repo reports<br/>agente: reports]
+        end
+
+        subgraph T4[Terminal · opcional]
+            WATCH[refacil-sdd-ai bus view<br/>o bus watch<br/>0 tokens]
+        end
+
+        subgraph BROKER[Broker local · 127.0.0.1:7821]
+            WS[HTTP + WebSocket<br/>40 MB RAM · 0% CPU idle]
+            DISK[~/.refacil-sdd-ai/bus/&lt;sala&gt;/<br/>inbox.jsonl<br/>rotación 7 días]
+        end
+    end
+
+    IDE1 <-->|ws| WS
+    IDE2 <-->|ws| WS
+    IDE3 <-->|ws| WS
+    WATCH -.->|http + ws read-only| WS
+    WS <--> DISK
+
+    classDef local fill:#e3f2fd,stroke:#1976d2,color:#333
+    classDef ide fill:#f3e5f5,stroke:#7b1fa2,color:#333
+    class WS,DISK local
+    class IDE1,IDE2,IDE3,WATCH ide
+```
+
+### Propiedades importantes
+
+- **100% local**: nada sale de `127.0.0.1`. Sin internet, sin cuentas, sin servidor compartido.
+- **Zero config**: el broker se auto-arranca la primera vez que cualquier skill del bus lo necesita.
+- **Zero costo perceptible**: 40 MB RAM, 0% CPU cuando no hay tráfico.
+- **Persistente**: sobrevive reinicio del broker; mensajes quedan 7 días en disco.
+- **Portable**: las mismas skills funcionan idéntico en Claude Code y Cursor (no usa hooks específicos de un IDE).
+
+---
+
+## 3. Flujo automático agente ↔ agente (happy path)
+
+Caso de uso estrella: el dev está trabajando en un repo y sus otros agentes (en otras ventanas) responden solos cuando reciben preguntas vía el bus.
+
+> **Pre-requisito**: antes de arrancar la tarea, el dev fue a la ventana del otro repo y dijo *"atiende el bus"*. Eso pone al agente de esa ventana en `/refacil:attend`. Sin eso, el flujo cae al Escenario B (sección 3.2).
+
+### 3.1 Con attend activo — cero saltos de ventana
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant D as Dev<br/>(único)
+    participant AP as Agente<br/>payments
+    participant BR as Broker
+    participant AF as Agente<br/>frontend
+
+    Note over D,AF: Setup previo (1 vez):<br/>Dev fue a la ventana frontend y dijo "atiende el bus"
+    D->>AF: "atiende el bus<br/>mientras trabajo en otro repo"
+    AF->>BR: /refacil:attend (bloqueado)
+    Note over AF: Escuchando preguntas
+
+    Note over D,AP: Dev vuelve a la ventana payments y arranca la tarea
+    D->>AP: "crea /refund,<br/>si necesitás algo del front<br/>preguntale al bus"
+    AP->>BR: /refacil:ask @frontend<br/>"..." --wait 180
+    Note over AP: Bloqueado<br/>esperando respuesta
+
+    BR->>AF: Pregunta recibida<br/>(correlationId X)
+    AF->>AF: Read/Grep src/api/pay.ts
+    AF->>BR: /refacil:reply<br/>"cartId, amountRefunded,<br/>timestamp (camelCase)"
+    BR->>AP: Respuesta con<br/>correlationId X
+
+    AP->>D: Endpoint implementado<br/>con los campos correctos
+    AF->>BR: /refacil:attend<br/>(vuelve a escuchar)
+    Note over AF: Listo para la<br/>siguiente pregunta
+```
+
+**Leyendo el diagrama**: el Dev solo participa en los pasos 1, 4 y 12. Entre medio (pasos 5 al 11) los dos agentes se hablaron entre sí — el dev no cambió de ventana, no copió nada, no transcribió respuestas.
+
+### 3.2 Sin attend — el dev despacha manualmente pero NO transcribe
+
+Si el dev no dejó attend activo, la pregunta queda en inbox y él mismo tiene que ir a la otra ventana a "despachar" el trabajo al otro agente.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant D as Dev<br/>(único)
+    participant AP as Agente<br/>payments
+    participant BR as Broker
+    participant AF as Agente<br/>frontend
+
+    D->>AP: "pregúntale al front<br/>qué formato espera"
+    AP->>BR: /refacil:ask @frontend "..."
+    Note over AP: Pregunta enviada,<br/>sin bloqueo
+
+    Note over D: Dev salta a la<br/>ventana frontend
+
+    D->>AF: "ejecutá /refacil:inbox<br/>y respondé lo que haya"
+    AF->>BR: /refacil:inbox
+    BR->>AF: Hay 1 ask dirigido a vos
+    AF->>AF: Read/Grep src/api/pay.ts
+    AF->>BR: /refacil:reply "..."
+
+    Note over D: Dev vuelve a la<br/>ventana payments
+
+    D->>AP: "ejecutá /refacil:inbox<br/>y seguí con la tarea"
+    AP->>BR: /refacil:inbox
+    BR->>AP: Respuesta del frontend
+    AP->>D: Endpoint implementado
+```
+
+**Diferencia clave vs 3.1**: el Dev visita la ventana frontend una vez (pasos 3-4). **Pero no lee código, no copia, no transcribe** — solo dice "ejecutá inbox y respondé". El agente del repo hace el trabajo real. Aún así el attend previo es el patrón ideal.
+
+---
+
+## 4. Guía rápida: ¿qué skill uso?
+
+Para que el equipo sepa qué invocar en cada caso:
+
+```mermaid
+flowchart TD
+    START[Necesito algo<br/>del bus] --> Q1{¿Primera vez<br/>en la sala hoy?}
+    Q1 -->|Sí| JOIN[/refacil:join sala<br/>escribe el bloque en<br/>AGENTS.md si falta/]
+    Q1 -->|No| Q2{¿Qué quiero<br/>hacer?}
+
+    JOIN --> Q2
+
+    Q2 -->|Preguntar a alguien<br/>y esperar respuesta<br/>para continuar| ASKW[/refacil:ask @X<br/>&quot;...&quot; --wait 180/]
+    Q2 -->|Preguntar sin<br/>bloquear| ASK[/refacil:ask @X<br/>&quot;...&quot;/]
+    Q2 -->|Anunciar algo<br/>a toda la sala| SAY[/refacil:say &quot;...&quot;/]
+    Q2 -->|Responder<br/>pregunta que me hicieron| REPLY[/refacil:reply &quot;...&quot;/]
+    Q2 -->|Atender el bus<br/>un rato| ATTEND[/refacil:attend/]
+    Q2 -->|Ver mensajes<br/>que llegaron offline| INBOX[/refacil:inbox/]
+
+    classDef start fill:#fff3cd,stroke:#856404,color:#333
+    classDef skill fill:#cce5ff,stroke:#004085,color:#333
+    class START start
+    class JOIN,ASKW,ASK,SAY,REPLY,ATTEND,INBOX skill
+```
+
+---
+
+## 5. Impacto esperado
+
+Beneficios cualitativos para el dev que trabaja con múltiples repos. El impacto depende de si el agente del otro repo está o no en `/refacil:attend`:
+
+| Aspecto | Antes | Con bus · otro agente SIN attend | Con bus · otro agente EN attend |
+|---|---|---|---|
+| **Consulta cruzada** | Dev salta de ventana, lee código, copia al otro agente | Dev salta 1 vez y dice "ejecutá inbox y respondé" | Agente pregunta solo; otro agente responde solo |
+| **Calidad del contexto** | Transcripción manual del dev — se pierde precisión | Agente del repo dueño responde desde código real | Agente del repo dueño responde desde código real |
+| **Saltos de ventana del dev** | Muchos: salir, leer, copiar, volver, pegar | Uno solo por consulta, corto (despachar al agente) | Cero: el dev se entera al final del resultado |
+| **Ruptura del foco** | Alta: cada consulta interrumpe el flujo principal | Media: una interrupción liviana | Casi nula: todo ocurre en background |
+| **Trazabilidad** | Nada queda registrado | `inbox.jsonl` 7 días auditable | `inbox.jsonl` 7 días auditable |
+| **Bugs por transcripción** | Frecuentes (tipeo, campos mal copiados) | Eliminados — el agente copia literal | Eliminados |
+| **Revisión post-mortem** | Hay que reconstruir de memoria | Historial del bus muestra la conversación real | Historial del bus muestra la conversación real |
+
+**Lectura de la tabla**: con el bus siempre hay ganancia respecto al estado actual. La automatización **total** (columna derecha) requiere la disciplina de dejar en `/refacil:attend` los agentes de los repos que uno sabe que va a consultar antes de meterse en una tarea larga.
+
+### Impacto cuantitativo (estimar por equipo)
+
+Estos valores se deben **medir en producción del equipo** durante las primeras 2-4 semanas:
+
+- Número de preguntas/respuestas cruzadas por día (proxy: líneas en `inbox.jsonl`)
+- Reducción de reuniones técnicas ad-hoc para alinear contratos de APIs
+- Tiempo promedio hasta resolver una consulta cruzada (antes medido vs ahora)
+
+---
+
+## 6. Cómo empezar (5 minutos)
+
+```bash
+# 1. Actualiza refacil-sdd-ai a la última versión (automático si tienes Claude Code)
+npm update -g refacil-sdd-ai
+
+# 2. En cada repo donde quieras usar el bus:
+refacil-sdd-ai update    # re-copia skills (el hook lo hace solo en Claude Code)
+
+# 3. Reinicia la sesión de Claude Code o Cursor
+
+# 4. En el chat del LLM:
+/refacil:join refacil-main
+# La primera vez el LLM escribe un bloque de presentación en tu AGENTS.md
+# y te une a la sala
+```
+
+No requiere configurar puertos, servidores ni credenciales. El broker se levanta solo.
+
+---
+
+## 7. Puntos clave para el pitch al equipo
+
+- **Las sesiones son agentes de repo, no devs**: el caso principal es un dev con varias ventanas abiertas (una por repo), donde los agentes del LLM se hablan entre sí para que el dev no haga de transcriptor.
+- **El dev sigue siendo el "PM"** de la operación — decide qué tarea arrancar, a qué agentes poner en attend, y valida el resultado final. El bus solo quita el trabajo mecánico entre ventanas.
+- **No transfiere código ni secretos** entre repos: solo texto plano que el dev controla.
+- **Costo infraestructural cero**: local, sin servicio compartido, sin cuentas nuevas, 40 MB de RAM.
+- **Funciona en Claude Code y Cursor**: sin diferencias ni configuración adicional.
+- **Persistencia con expiración automática** (7 días) — no se llena el disco.
+- **Patrón óptimo**: antes de empezar una tarea que puede requerir consultar otros repos, el dev abre rápido las otras ventanas y dice *"atiende el bus"*. A partir de ahí, todo ocurre en background mientras trabaja.
+- **Fallback natural sin attend**: aunque el dev olvide el setup, el bus sigue sirviendo como canal asíncrono: el dev salta 1 vez, despacha al agente (*"ejecutá inbox y respondé"*) y vuelve. Mucho mejor que transcribir código a mano.
+
+---
+
+## Apéndice: comandos útiles para el dev
+
+```bash
+refacil-sdd-ai bus status              # ¿está activo el broker?
+refacil-sdd-ai bus rooms               # salas activas + miembros
+refacil-sdd-ai bus watch <session>     # panel en vivo (sin tokens)
+refacil-sdd-ai bus history --n 50      # últimos 50 mensajes de la sala actual
+refacil-sdd-ai bus leave               # salir de la sala
+refacil-sdd-ai bus stop                # bajar el broker (raro necesitarlo)
+```