refacil-sdd-ai 2.6.0 → 2.8.0

package/README.md

@@ -56,7 +56,7 @@ refacil-sdd-ai update        # Actualizar skills y hooks a la ultima version
 refacil-sdd-ai check-update  # Verifica si hay una version mas reciente en npm (usado por hook)
 refacil-sdd-ai check-review  # Verifica que el review se haya completado (usado por hook)
 refacil-sdd-ai compact-bash  # Hook de rewrite de comandos Bash bare (usado por hook, no invocar manual)
-refacil-sdd-ai compact stats     # Tabla de rewrites + tokens estimados + USD ahorrado
+refacil-sdd-ai compact stats     # Estadisticas completas (hook + ya-compacto) + tokens estimados + USD
 refacil-sdd-ai compact disable   # Desactiva el hook compact-bash sin desinstalarlo
 refacil-sdd-ai compact enable    # Reactiva el hook compact-bash
 refacil-sdd-ai compact clear-log # Limpia ~/.refacil-sdd-ai/compact.log
@@ -431,13 +431,13 @@ Fase 2A — linters, type checkers, build, sistema:
 **Subcomandos de control**:
 
 ```bash
-refacil-sdd-ai compact stats       # tabla de rewrites + tokens estimados + USD
+refacil-sdd-ai compact stats       # estadisticas completas (hook + ya-compacto) + tokens estimados + USD
 refacil-sdd-ai compact disable     # desactiva el hook sin desinstalar
 refacil-sdd-ai compact enable      # reactiva el hook
 refacil-sdd-ai compact clear-log   # limpia ~/.refacil-sdd-ai/compact.log
 ```
 
-**Telemetria**: cada rewrite genera una linea JSON en `~/.refacil-sdd-ai/compact.log` con timestamp, ruleId y estimacion de tokens ahorrados. El log se usa para el comando `compact stats` que agrega por regla y calcula costo estimado (a razon de $3/MTok input de Sonnet, conservador). La telemetria es local; nada se envia a la nube.
+**Telemetria**: cada evento genera una linea JSON en `~/.refacil-sdd-ai/compact.log` con timestamp, ruleId y estimacion de tokens. Hay dos tipos de evento: `hook_rewrite` (el hook reescribe) y `already_compact` (el comando ya llega compacto, asumido por skill/agente). `compact stats` muestra ambos por defecto y calcula costo estimado (a razon de $3/MTok input de Sonnet, conservador). La telemetria es local; nada se envia a la nube.
 
 **Flujo del hook**:
 
@@ -561,8 +561,168 @@ npm uninstall -g refacil-sdd-ai
 - [Claude Code](https://claude.ai/code) — CLI de Anthropic
 - [Cursor](https://cursor.sh) — IDE con IA
 
+## refacil-bus
+
+Chat room local entre agentes. Permite que distintas sesiones de Claude Code o Cursor corriendo en repos diferentes se coordinen por texto plano — **sin compartir archivos, contexto ni tokens entre repos**. Cada agente responde desde el conocimiento de su propio repositorio.
+
+El broker corre solo en `127.0.0.1`, se arranca bajo demanda la primera vez que una skill lo necesita, y no envía datos fuera de la máquina local.
+
+### Instalación y primer arranque
+
+No requiere pasos extra: `refacil-sdd-ai init` ya copia las skills del bus junto con el resto. La primera vez que alguien ejecuta `/refacil:join <sala>`, el CLI auto-arranca el broker en `127.0.0.1:7821` (fallback 7822 / 7823 si están ocupados).
+
+### Ejemplos de uso
+
+**Ejemplo A — Conversación LLM ↔ LLM automática**
+
+```
+# Terminal 1 — repo payments-api (Claude Code)
+/refacil:join refacil-main
+# -> broadcast: "payments-api se unió. Stack: NestJS. Para consultarme: /refacil:ask @payments-api ..."
+
+# Terminal 2 — repo frontend-refacil (Cursor)
+/refacil:join refacil-main
+# -> broadcast: "frontend-refacil se unió. Stack: React/Vite. Para consultarme: /refacil:ask @frontend-refacil ..."
+
+# Dev del frontend delega su sesion a atender el bus:
+"atiende el bus"
+# LLM ejecuta: /refacil:attend  (queda escuchando sin tope)
+
+# Dev de payments trabaja en una feature:
+"crea el endpoint POST /refund y cuando necesites saber
+ como lo va a consumir el front, preguntale"
+
+# LLM de payments decide preguntar:
+/refacil:ask @frontend-refacil "endpoint POST /refund devuelve
+  { cartId, reference, status }. Que necesitas en el response?" --wait 180
+
+# LLM del frontend (en attend) recibe, lee sus archivos, responde:
+/refacil:reply "necesito tambien amountRefunded y timestamp.
+  Formato camelCase."
+
+# LLM de payments recibe la respuesta automaticamente y continua
+# implementando el endpoint con los campos correctos. Sin que ningun
+# dev haya intervenido en el intercambio.
+```
+
+**Ejemplo B — Modo pasivo con dev como bridge ligero**
+
+```
+# LLM A: /refacil:ask @frontend "..."  (sin --wait)
+# -> "pregunta enviada. Usa /refacil:inbox cuando quieras ver respuestas"
+
+# Dev B ve la pregunta en su panel watch (segunda terminal):
+refacil-sdd-ai bus watch frontend
+
+# Le dice a su LLM: "responde en el bus: <respuesta>"
+# LLM B: /refacil:reply "..."
+
+# Dev A ve la respuesta en SU watch y dice: "/refacil:inbox y continua"
+# LLM A lee la respuesta y sigue el flujo original
+```
+
+**Ejemplo C — Observador puro (sin tokens)**
+
+```
+# Segunda terminal en cualquier repo:
+refacil-sdd-ai bus watch payments-api
+# Muestra todos los mensajes en vivo con menciones resaltadas (🔔).
+# No consume tokens del LLM.
+```
+
+**Ejemplo D — Backlog asincronico**
+
+```
+# Dev A pregunta algo al bus, Dev B esta ocupado en otra tarea.
+# La pregunta queda persistida en inbox.jsonl de la sala.
+
+# Mas tarde, Dev B dice a su LLM: "atiende el bus"
+# -> /refacil:attend procesa las preguntas pendientes en orden FIFO.
+
+# Dev A si tenia --wait y expiro: usa /refacil:inbox para recuperar la respuesta.
+```
+
+### Patrones de uso recomendados
+
+- **Sesion dedicada**: abrir una segunda ventana de Claude Code en el repo que atiende, invocar `/refacil:attend` ahi y dejar la primera libre para trabajo normal.
+- **Atencion en rafagas**: invocar `/refacil:attend` solo cuando el watch panel muestre preguntas pendientes.
+- **Observador pasivo**: `refacil-sdd-ai bus watch <session>` para supervisar sin consumir tokens del LLM.
+- **Delegacion explicita al inicio del turno**: decirle al LLM *"si necesitas contexto del front/back/X, preguntale al bus"* para que use `/refacil:ask` cuando lo necesite.
+
+### Problematica que resuelve
+
+En un equipo con multiples microservicios y frontend, cada repo corre su propia sesion de Claude Code o Cursor. Antes de `refacil-bus`:
+
+- El dev saltaba entre ventanas para consultar codigo de otro repo.
+- El contexto del repo B se explicaba manualmente al agente del repo A — propenso a error y olvido.
+- No habia forma de que el agente de un repo hiciera una pregunta puntual al agente de otro sin romper el flujo de trabajo del dev.
+- Decisiones cruzadas (contrato de APIs, formato de eventos, nombres de campos) requerian reuniones o mensajes fuera de banda.
+
+Con `refacil-bus`:
+
+- Cada agente mantiene su contexto aislado en su propio repo y responde desde su conocimiento.
+- La comunicacion entre agentes es texto plano, sin transferir archivos ni tokens.
+- Una pregunta como *"¿como consumes el response de /pay?"* se responde automaticamente desde el repo que sabe la respuesta, si la sesion destino esta en modo `attend`.
+- El dev mantiene trazabilidad de toda la conversacion cruzada en `inbox.jsonl` (rotado a 7 dias) y en el watch panel.
+- La comunicacion es totalmente local — nada sale de la maquina del dev.
+
+### Comandos de referencia
+
+**Skills (invocables por el LLM)**:
+
+| Skill | Uso |
+|---|---|
+| `/refacil:join <sala>` | Unirse o crear sala. Genera presentacion automatica (lee `AGENTS.md`). |
+| `/refacil:say "..."` | Broadcast a la sala. |
+| `/refacil:ask @nombre "..." [--wait N]` | Pregunta dirigida. `--wait N` bloquea hasta respuesta o N segundos. |
+| `/refacil:reply "..."` | Responde la ultima pregunta dirigida (autocompleta `correlationId` FIFO). |
+| `/refacil:attend` | Modo escucha activa. Recibe preguntas y las entrega al LLM para que las responda. |
+| `/refacil:inbox` | Mensajes nuevos desde la ultima lectura. |
+
+**CLI (para el dev)**:
+
+```bash
+refacil-sdd-ai bus start               # Arranca el broker (opcional; las skills lo hacen solas)
+refacil-sdd-ai bus stop                # Detiene el broker
+refacil-sdd-ai bus status              # Puerto, pid, uptime
+refacil-sdd-ai bus rooms               # Salas activas + miembros
+refacil-sdd-ai bus watch <session>     # Panel en vivo (sin tokens)
+refacil-sdd-ai bus leave               # Salir de la sala (limpieza manual)
+refacil-sdd-ai bus history [--n N]     # Ultimos N mensajes
+```
+
+### Presentacion automatica al hacer join
+
+Al unirse a una sala, cada sesion envia un mensaje de presentacion. Para que sea util, la skill `/refacil:join` instruye al LLM a generar un bloque en `AGENTS.md` la primera vez, entre los marcadores:
+
+```
+<!-- refacil-bus:presentation:start -->
+Stack: <framework + lenguaje>
+Dominio: <que hace este repo en 1-2 lineas>
+Preguntame sobre: <lista corta de areas donde este repo es fuente de verdad>
+<!-- refacil-bus:presentation:end -->
+```
+
+El CLI prioriza ese bloque literal. Si no existe, hace fallback a `package.json` (name + description) + primer parrafo de `AGENTS.md`. El bloque queda versionado en el repo y cualquier dev puede ajustarlo.
+
+### Limitaciones conocidas
+
+- Mientras `/refacil:attend` esta activo, la sesion del IDE queda ocupada (el dev no puede usarla sin abortar con ESC). Mitigacion: abrir una **segunda ventana de Claude Code** en el mismo repo dedicada a atender.
+- El LLM no recibe pushes externos — la automatizacion completa requiere que el receptor este en `attend`, o que el dev le pida `/refacil:inbox` despues.
+- Sin autenticacion: cualquier proceso local puede conectar al broker (por diseño, es solo loopback y a demanda del dev).
+- Persistencia 7 dias en `~/.refacil-sdd-ai/bus/<sala>/inbox.jsonl` (rotacion lazy al escribir).
+
 ## Cambios recientes
 
+**v2.8.0** — `refacil-bus`: chat room local entre agentes:
+- Broker WebSocket local (`127.0.0.1:7821`, fallback 7822/7823) con auto-spawn
+- Persistencia por sala en `~/.refacil-sdd-ai/bus/<sala>/inbox.jsonl` con rotacion 7 dias
+- 6 skills nuevas: `join`, `say`, `ask`, `reply`, `attend`, `inbox`
+- Comandos CLI: `bus start/stop/status/watch/join/say/ask/reply/attend/inbox/history/rooms/leave`
+- Presentacion automatica al unirse usando bloque marcado en `AGENTS.md` con fallback a `package.json`
+- Soporte de conversacion automatica LLM ↔ LLM via `ask --wait` + `attend` en el otro lado
+- Funciona identico en Claude Code y Cursor (sin hooks, todo via skills)
+
 **v2.6.0** — Fase 2 del hook `compact-bash`:
 - 11 reglas nuevas: `eslint`, `biome check`, `tsc`, `prettier --check`, `npm audit`, `npm ls`, `cargo build/test/check`, `go test`, `mvn test`, `gradle test`, `ps aux` (total: 19 reglas)
 - Telemetria local en `~/.refacil-sdd-ai/compact.log`