refacil-sdd-ai 2.7.0 → 2.8.1

package/README.md

@@ -554,35 +554,164 @@ refacil-sdd-ai clean
 npm uninstall -g refacil-sdd-ai
 ```
 
-## Tecnologias
+## refacil-bus
 
-- [OpenSpec](https://github.com/Fission-AI/OpenSpec) — Framework de especificaciones
-- [AGENTS.md](https://agents.md/) — Estandar universal de instrucciones para IA
-- [Claude Code](https://claude.ai/code) — CLI de Anthropic
-- [Cursor](https://cursor.sh) — IDE con IA
+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).
 
-## Cambios recientes
+### Ejemplos de uso
 
-**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`
-- Subcomandos `compact stats | disable | enable | clear-log`
-- `ps-aux` solo se activa en Unix (Linux/Mac); en Windows la regla no interviene
+**Ejemplo A — Conversación LLM ↔ LLM automática**
 
-**v2.5.0** — Fase 1 del hook `compact-bash`:
-- Hook `PreToolUse` que reescribe silenciosamente comandos Bash bare via `updatedInput` (requiere Claude Code >= 2.1.89)
-- Reglas iniciales: git log/status/diff/show, docker logs, npm/yarn/pnpm test, jest, pytest
-- Escape mecanismo `COMPACT=0 <cmd>`
+```
+# 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.
+```
 
-**v2.4.0** — Reduccion de tokens en la metodologia:
-- Boilerplate "Antes de empezar" unificado en 9 skills
-- Validacion de OpenSpec simplificada en `prereqs/SKILL.md`
-- Templates consolidados (`claude-md.md` + `cursorrules.md` → `methodology-guide.md` unico)
-- Compactacion de `review/SKILL.md`, `bug/SKILL.md`, `test/SKILL.md`
+**Ejemplo B — Modo pasivo con dev como bridge ligero**
 
-**v2.3.0** — Bloque `compact-guidance` auto-gestionado en `AGENTS.md`:
-- Hook `SessionStart` sincroniza el bloque en cada sesion
-- Fuente de verdad: `templates/compact-guidance.md`
+```
+# 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).
+
+
+## Tecnologias
+
+- [OpenSpec](https://github.com/Fission-AI/OpenSpec) — Framework de especificaciones
+- [AGENTS.md](https://agents.md/) — Estandar universal de instrucciones para IA
+- [Claude Code](https://claude.ai/code) — CLI de Anthropic
+- [Cursor](https://cursor.sh) — IDE con IA
 
 ## Licencia