refacil-sdd-ai 2.9.0 → 2.10.0

package/README.md

@@ -1,743 +1,373 @@
 # refacil-sdd-ai
 
-Metodologia **SDD-AI** (Specification-Driven Development with AI) empaquetada como herramienta CLI.
+Metodologia **SDD-AI** (Specification-Driven Development with AI) empaquetada como CLI.
 
-Instala skills para **Claude Code** y **Cursor** que guian al desarrollador por un flujo estructurado de desarrollo usando **OpenSpec** como base de especificaciones.
+Instala skills para **Claude Code** y **Cursor** que guian al desarrollador por un flujo estructurado de desarrollo usando **OpenSpec** como base de especificaciones, mas un **bus local** para que los agentes de distintos repos se comuniquen entre si.
+
+---
 
 ## Requisitos
 
 - **Node.js >= 20.19.0** (requerido por OpenSpec)
-- **Claude Code >= 2.1.89** (requerido por el hook `compact-bash` para rewrite silencioso de comandos via `updatedInput`) o **Cursor**
+- **Claude Code >= 2.1.89** (requerido por el hook `compact-bash` para rewrite silencioso via `updatedInput`) o **Cursor**
+
+`refacil-sdd-ai init` verifica la version de Claude Code y advierte si es inferior. Con version < 2.1.89 el resto de la metodologia funciona, pero `compact-bash` no tendra efecto.
 
-`refacil-sdd-ai init` verifica la version de Claude Code y muestra advertencia si es inferior. Con version < 2.1.89 el resto de la metodologia funciona, pero el hook `compact-bash` no tendra efecto (Claude Code ignora `updatedInput` en versiones antiguas).
+---
 
-## Instalacion y Setup
+## Instalacion
 
-Se recomienda instalar **a nivel global** para no tener que instalar el paquete en cada repositorio donde se use la metodologia.
+Recomendado: instalar globalmente una sola vez, y correr `init` por repo.
 
 ```bash
-# 1. Instalar de forma global (una sola vez)
+# 1. Global (una vez)
 npm install -g refacil-sdd-ai
 
-# 2. En la raiz del repo donde quieras usar la metodologia:
+# 2. En la raiz del repo
 refacil-sdd-ai init
-#    Copia skills a .claude/ y .cursor/, crea CLAUDE.md y .cursorrules
+#    Copia skills a .claude/ y .cursor/, crea CLAUDE.md + .cursorrules, configura hooks
 
-# 3. IMPORTANTE: Reiniciar la sesion de Claude Code o Cursor
+# 3. Reiniciar sesion de Claude Code o Cursor
 #    (las skills nuevas no se detectan hasta reiniciar)
 
-# 4. En Claude Code o Cursor, ejecutar:
+# 4. En el IDE
 /refacil:setup
-#    Esto hace:
-#    - Verifica Node.js
-#    - Verifica OpenSpec (si no esta instalado, lo instala globalmente)
-#    - Inicializa openspec/ en el repo (openspec init --tools claude,cursor)
-#    - Crea openspec/config.yaml con idioma espanol
-#    - Genera AGENTS.md automaticamente analizando el repo
+#    Instala OpenSpec, inicializa openspec/ y genera AGENTS.md
 ```
 
-### Actualizar a una nueva version
+### Actualizar
 
 ```bash
-# Actualizar el paquete global
 npm update -g refacil-sdd-ai
-
-# En cada repo donde se use, re-copiar las skills actualizadas:
-refacil-sdd-ai update
+refacil-sdd-ai update          # en cada repo donde se use
 ```
 
-> **Nota**: `openspec init` tambien instala sus propios comandos (`opsx:*`) en `.claude/` y `.cursor/`. Esto es normal. Los `refacil:*` y `opsx:*` coexisten sin conflicto. El equipo debe usar `refacil:*` como interfaz principal.
+En Claude Code el hook `check-update` hace esto automaticamente al iniciar sesion.
 
-## Comandos del CLI
+### Desinstalar
 
 ```bash
-refacil-sdd-ai init          # Instalar skills, hooks y crear configs en el repo actual
-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     # 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
-refacil-sdd-ai clean         # Eliminar skills y remover hooks SDD-AI del repo
-refacil-sdd-ai help          # Ver ayuda
-```
-
-## Skills disponibles
-
-Una vez instalado, estos comandos estan disponibles en Claude Code y Cursor:
-
-| Comando | Descripcion |
-|---------|-------------|
-| `/refacil:setup` | Instalar OpenSpec y generar AGENTS.md para el repo |
-| `/refacil:guide` | Guia interactiva — que comando usar segun lo que necesites |
-| `/refacil:explore` | Explorar el codebase sin hacer cambios |
-| `/refacil:propose` | Crear propuesta de cambio (proposal + specs + design + tasks) |
-| `/refacil:apply` | Implementar las tasks del cambio propuesto |
-| `/refacil:test` | Generar tests unitarios desde los artefactos |
-| `/refacil:verify` | Validar implementacion vs specs (con opcion de aplicar correcciones) |
-| `/refacil:review` | Review con checklist de calidad del equipo |
-| `/refacil:archive` | Archivar cambio completado |
-| `/refacil:up-code` | Integrar codigo a rama propia del desarollo y gestionar PR |
-| `/refacil:bug` | Flujo guiado completo para investigar y corregir bugs |
-
-## Uso rapido (guia de decision)
-
-Si no tienes claro que comando usar, aplica esta regla simple:
-
-- Quiero entender el sistema sin tocar codigo -> `/refacil:explore`
-- Quiero construir algo nuevo o cambiar comportamiento -> `/refacil:propose`
-- Ya aprobe artefactos y quiero implementar -> `/refacil:apply`
-- Quiero generar o completar pruebas -> `/refacil:test`
-- Quiero validar cumplimiento contra spec -> `/refacil:verify`
-- Quiero evaluacion de calidad tecnica -> `/refacil:review`
-- Ya termine y quiero cerrar el cambio en OpenSpec -> `/refacil:archive`
-- Quiero subir cambios al repositorio -> `/refacil:up-code`
-- Tengo un error en produccion o bug funcional -> `/refacil:bug`
-
-## Flujo minimo recomendado (equipo)
-
-Para mantener trazabilidad y calidad sin pasos innecesarios:
-
-1. `/refacil:propose` (aprobacion humana obligatoria)
-2. `/refacil:apply`
-3. `/refacil:test`
-4. `/refacil:verify`
-5. `/refacil:review` (si lo omites, `/refacil:up-code` lo dispara antes del push)
-6. `/refacil:archive`
-7. `/refacil:up-code`
-
-Si es bugfix, inicia con `/refacil:bug` (ya genera tests de regresion internamente) y continua con `/refacil:review` → `/refacil:archive` → `/refacil:up-code`.
-
-> **Nota — dos capas independientes de chequeo de review**:
-> - `/refacil:up-code` detecta si falta `.review-passed` y **ejecuta `/refacil:review` automaticamente** antes del push.
-> - El hook `check-review` (en `.claude/settings.json`) intercepta tambien `git push` manuales y **bloquea** la operacion si falta `.review-passed`. El hook NO invoca skills por si mismo — solo bloquea y emite instrucciones para ejecutar `/refacil:review` manualmente.
->
-
-## Flujos de trabajo
-
-### Feature nuevo
-
-```
-/refacil:propose "descripcion del feature"
-# → Revisar y aprobar artefactos (proposal, specs, design, tasks)
-/refacil:apply
-/refacil:test
-/refacil:verify
-# → Si hay correcciones: verify pregunta si aplicarlas automaticamente
-# → Si aprueba: aplica fixes y re-verifica (maximo 2 rondas de correccion automatica)
-/refacil:review
-/refacil:archive
-/refacil:up-code
-```
-
-### Bug fix
-
-```
-/refacil:setup
-# → Precondicion si el repo aun no tiene openspec/ (solo la primera vez)
-/refacil:bug "descripcion del error"
-# → Investiga, implementa fix, genera tests de regresion
-# → Crea trazabilidad en openspec/changes/fix-[descripcion-corta]/summary.md
-# → Nombre siempre descriptivo (sin IDs de ticket)
-/refacil:review
-# → Evalua calidad del fix, crea .review-passed si aprueba
-/refacil:archive
-# → Archiva el fix SIN pasar por OpenSpec (evita error por falta de artefactos completos)
-# → Mueve carpeta a openspec/changes/archive/[fecha]-[nombre]/
-# → Crea spec individual en openspec/specs/fix-[nombre]/spec.md
-#   en formato OpenSpec estandar (Purpose/Requirements/Scenario)
-# → Crea openspec/specs/fix-[nombre]/review.yaml con metadata del review
-/refacil:up-code
+refacil-sdd-ai clean           # en el repo (elimina skills + hooks SDD-AI)
+npm uninstall -g refacil-sdd-ai
 ```
 
-> **Nota**: En una misma rama pueden corregirse multiples bugs. Cada uno genera su propia carpeta `fix-*` con su trazabilidad independiente.
->
-> **Importante**: `/refacil:archive` requiere review aprobado (`.review-passed`). Si no existe, bloquea el archivado. Para bugs, el archive no delega a OpenSpec — hace el archivado manual y documenta el bug en `openspec/specs/` como spec individual en formato OpenSpec estandar, con `review.yaml` separado.
->
-> En cambios regulares (feature/mejora) que se archivan con OpenSpec, Refacil **extrae los campos** de `.review-passed` (JSON) y los persiste como `review.yaml` dentro de cada spec afectado (o en `openspec/specs/review-metadata.yaml` si no hay mapeo preciso). El archivo `.review-passed` original no se copia: solo su contenido convertido a YAML.
+> **Nota**: `openspec init` tambien instala sus comandos `opsx:*`. Coexisten sin conflicto con los `refacil:*`. Usar siempre `refacil:*` como interfaz principal.
 
-### Explorar codigo
+---
 
-```
-/refacil:explore "que quiero entender"
-```
+## Comandos del CLI
 
-## Diagrama de flujo completo
+### Gestion del paquete
 
-Vista unica del ciclo de vida de un cambio — desde la necesidad hasta el PR integrado.
+| Comando | Descripcion |
+|---|---|
+| `refacil-sdd-ai init` | Instala skills y hooks en el repo actual |
+| `refacil-sdd-ai update` | Re-copia skills y hooks a la ultima version |
+| `refacil-sdd-ai clean` | Elimina skills y hooks SDD-AI del repo |
+| `refacil-sdd-ai help` | Ver ayuda |
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│              INICIO: Necesidad de cambio                        │
-└────────────────────────────────┬────────────────────────────────┘
-                                 │
-                                 ▼
-                    ┌────────────────────────┐
-                    │  ¿Repo configurado?    │
-                    └───┬────────────────┬───┘
-                      NO│                │SI
-                        ▼                │
-              ┌──────────────────┐       │
-              │ refacil-sdd-ai   │       │
-              │ init             │       │
-              │ /refacil:setup   │       │
-              └────────┬─────────┘       │
-                       └────────┬────────┘
-                                ▼
-                    ┌────────────────────────┐
-                    │   ¿Que tipo de tarea?  │
-                    └───┬────────┬───────┬───┘
-                        │        │       │
-              ┌─────────┘        │       └─────────┐
-              ▼                  ▼                 ▼
-     ┌────────────────┐  ┌──────────────┐  ┌──────────────┐
-     │ FEATURE NUEVO  │  │     BUG      │  │  EXPLORAR    │
-     └───────┬────────┘  └──────┬───────┘  └──────┬───────┘
-             │                  │                 │
-             ▼                  ▼                 ▼
-    ┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
-    │/refacil:propose │ │/refacil:bug  │ │/refacil:explore │
-    │                 │ │              │ │                 │
-    │ Genera:         │ │ Investiga +  │ │ Analiza codigo  │
-    │ • proposal.md   │ │ fix + test   │ │ sin modificar   │
-    │ • specs/        │ │ de regresion │ │                 │
-    │ • design.md     │ │ (interno)    │ │     (FIN)       │
-    │ • tasks.md      │ │              │ └─────────────────┘
-    └────────┬────────┘ └──────┬───────┘
-             │                 │
-             ▼                 │
-    ┌─────────────────┐        │
-    │ REVISAR         │        │
-    │ artefactos      │        │
-    │ (aprobacion     │        │
-    │  humana)        │        │
-    └────────┬────────┘        │
-             │                 │
-             ▼                 │
-    ┌─────────────────┐        │
-    │ /refacil:apply  │        │
-    │ Implementa      │        │
-    │ tasks           │        │
-    └────────┬────────┘        │
-             │                 │
-             ▼                 │
-    ┌─────────────────┐        │
-    │ /refacil:test   │        │
-    │ Tests unitarios │        │
-    │ + edge cases    │        │
-    └────────┬────────┘        │
-             │                 │
-             ▼                 │
-    ┌─────────────────┐        │
-    │ /refacil:verify │        │
-    │ ¿Cumple specs?  │        │
-    │ (max 2 rondas   │        │
-    │  autofix)       │        │
-    └────────┬────────┘        │
-             │                 │
-             └────────┬────────┘
-                      ▼
-             ┌─────────────────┐
-             │ /refacil:review │
-             │ Checklist       │──► genera .review-passed
-             │ calidad         │    (JSON con veredicto)
-             └────────┬────────┘
-                      ▼
-             ┌─────────────────┐
-             │/refacil:archive │
-             │ Mueve a archive/│
-             │ Sincroniza specs│
-             │ (bug → fix-*/   │
-             │  spec OpenSpec) │
-             └────────┬────────┘
-                      ▼
-             ┌─────────────────┐
-             │/refacil:up-code │
-             │ commit + push   │
-             │ + PR            │
-             └────────┬────────┘
-                      ▼
-             ┌─────────────────┐
-             │   PR creado     │
-             │     (FIN)       │
-             └─────────────────┘
-```
+### Hooks internos (invocados automaticamente, no manual)
 
-### Gate de review en el push
+| Comando | Descripcion |
+|---|---|
+| `refacil-sdd-ai check-update` | Verifica nueva version + sincroniza `compact-guidance` en AGENTS.md |
+| `refacil-sdd-ai check-review` | Bloquea `git push` si falta `.review-passed` en algun cambio activo |
+| `refacil-sdd-ai compact-bash` | Reescribe comandos Bash bare via `updatedInput` |
 
-Vista del mecanismo de dos capas que protege `git push`:
+### Control del rewrite de comandos (`compact-bash`)
 
-```
-                ┌──────────────────────────────┐
-                │ Dev ejecuta /refacil:up-code │
-                │       o git push manual      │
-                └────────────────┬─────────────┘
-                                 │
-          ┌──────────────────────┴──────────────────────┐
-          │ Via /refacil:up-code                        │ git push directo
-          ▼                                             ▼
-┌─────────────────────────┐                ┌───────────────────────────┐
-│ up-code detecta         │                │ Hook check-review          │
-│ .review-passed faltante │                │ (PreToolUse en Bash)       │
-│                         │                │                            │
-│ INVOCA /refacil:review  │                │ Verifica .review-passed    │
-│ automaticamente         │                │ en openspec/changes/*      │
-└────────────┬────────────┘                └────────────┬───────────────┘
-             │                                          │
-             ▼                                          ▼
-      ┌──────────────┐                         ┌─────────────────┐
-      │ Review OK?   │                         │ Falta alguno?   │
-      └──┬────────┬──┘                         └──┬───────────┬──┘
-       SI│      NO│                              SI│         NO│
-         ▼        ▼                                ▼           ▼
-   ┌─────────┐ ┌────────────┐              ┌─────────────┐ ┌────────┐
-   │ push OK │ │ informa    │              │ block +     │ │ allow  │
-   │         │ │ correccion │              │ instruccion │ │ push   │
-   │         │ │ no pushea  │              │ a ejecutar  │ │        │
-   │         │ │            │              │ /refacil:   │ │        │
-   │         │ │            │              │ review      │ │        │
-   └─────────┘ └────────────┘              └─────────────┘ └────────┘
-```
+| Comando | Descripcion |
+|---|---|
+| `refacil-sdd-ai compact stats` | Estadisticas (hook + ya-compacto) + tokens y USD estimados |
+| `refacil-sdd-ai compact enable` | Reactiva el rewrite |
+| `refacil-sdd-ai compact disable` | Desactiva el rewrite sin desinstalar |
+| `refacil-sdd-ai compact clear-log` | Limpia `~/.refacil-sdd-ai/compact.log` |
 
-## Reglas metodologicas transversales
+### Bus de agentes (`bus`)
 
-Para mantener consistencia entre todas las skills, el paquete define un contrato metodologico unico en `skills/prereqs/METHODOLOGY-CONTRACT.md`:
+| Comando | Descripcion |
+|---|---|
+| `refacil-sdd-ai bus start` | Arranca el broker local (auto-spawn detached) |
+| `refacil-sdd-ai bus stop` | Detiene el broker |
+| `refacil-sdd-ai bus status` | Muestra puerto, pid, uptime |
+| `refacil-sdd-ai bus rooms` | Salas activas + miembros |
+| `refacil-sdd-ai bus view` | Abre la UI web en el navegador |
+| `refacil-sdd-ai bus watch <session> [--room <sala>]` | Panel en vivo en terminal (0 tokens) |
+| `refacil-sdd-ai bus history [--n N] [--session <s>]` | Ultimos N mensajes |
+| `refacil-sdd-ai bus join --room <sala> [--session <s>] [--intro "..."]` | Unirse a sala (las skills lo hacen) |
+| `refacil-sdd-ai bus leave [--session <s>]` | Salir de la sala |
+| `refacil-sdd-ai bus say --text "..." [--session <s>]` | Broadcast (las skills lo hacen) |
+| `refacil-sdd-ai bus ask --to <name> --text "..." [--wait N]` | Pregunta dirigida (las skills lo hacen) |
+| `refacil-sdd-ai bus reply --text "..." [--correlation <id>]` | Responder (las skills lo hacen) |
+| `refacil-sdd-ai bus attend [--timeout N]` | Escucha preguntas dirigidas (las skills lo hacen) |
+| `refacil-sdd-ai bus inbox [--session <s>]` | Ver mensajes nuevos |
 
-- Estados del flujo (Ready for Propose/Apply/Verify/Review/Archive/Merge)
-- Politica de `AGENTS.md` por perfil (`openspec` vs `agents`)
-- Resolucion de comando de tests multi-stack (sin hardcodear `npm test`)
-- Politica unificada de ramas protegidas, creacion de ramas e integracion por pr
-- Modo de salida estandar: `conciso` por defecto, `detallado` bajo demanda
+> Los subcomandos `join/leave/say/ask/reply/attend/inbox` tambien existen como **skills** dentro del IDE (`/refacil:join`, etc.). En la mayoria de los casos conviene usar las skills; los comandos del CLI son para scripting o debugging.
 
-### Politica de ramas (resumen)
+---
 
-- Toda rama nueva de trabajo (`feature/*`, `fix/*`, `hotfix/*`, etc.) se crea desde `develop` o `dev` actualizado.
-- Excepcion para repos nuevos: si no existe `develop`/`dev`, se permite usar temporalmente `main` o `master` como rama base.
-- Toda integracion a ramas protegidas (`testing`, `develop`, `dev`, `main`, `master`, `qa`) requiere PR.
-- NUNCA se hacen ajustes directos en `master` o `main`.
+## Skills disponibles en el IDE
 
-### Checkpoints de estado (DoR/DoD)
+Todas se invocan como `/refacil:<nombre>` en Claude Code o Cursor.
 
-Antes de avanzar de etapa, valida estos estados:
+### Ciclo SDD
 
-- `READY_FOR_APPLY`: artefactos SDD completos + aprobacion explicita
-- `READY_FOR_VERIFY`: implementacion terminada y enfocada al alcance
-- `READY_FOR_REVIEW`: verify ejecutado y bloqueantes tratados
-- `READY_FOR_ARCHIVE`: cambio funcionalmente cerrado + review aprobado (`.review-passed`)
-- `READY_FOR_MERGE`: review aprobado (`.review-passed`) y PR creado hacia la rama destino protegida
+| Skill | Uso |
+|---|---|
+| `/refacil:setup` | Instalar OpenSpec + generar AGENTS.md |
+| `/refacil:guide` | Guia interactiva sobre que comando usar |
+| `/refacil:explore` | Explorar codebase sin modificar |
+| `/refacil:propose` | Crear propuesta: proposal + specs + design + tasks |
+| `/refacil:apply` | Implementar tasks del cambio |
+| `/refacil:test` | Generar tests unitarios desde los artefactos |
+| `/refacil:verify` | Validar implementacion vs specs (con autofix opcional) |
+| `/refacil:review` | Checklist de calidad, emite `.review-passed` si aprueba |
+| `/refacil:archive` | Archivar cambio completado + sincronizar specs |
+| `/refacil:up-code` | Commit + push + PR (ejecuta review si falta) |
+| `/refacil:bug` | Flujo completo de bugfix con tests de regresion |
 
-### Hooks automaticos
+### Bus de agentes
 
-El paquete instala hooks en `.claude/settings.json` durante `init` y `update`:
+| Skill | Uso |
+|---|---|
+| `/refacil:join <sala>` | Unirse o crear sala |
+| `/refacil:say "..."` | Broadcast |
+| `/refacil:ask @nombre "..." [--wait N]` | Pregunta dirigida (bloquea con `--wait`) |
+| `/refacil:reply "..."` | Responder ultima pregunta (autocompleta `correlationId`) |
+| `/refacil:attend` | Modo escucha activa |
+| `/refacil:inbox` | Mensajes nuevos desde la ultima lectura |
+
+---
+
+## Flujo recomendado
+
+Regla rapida para elegir el comando de entrada:
+
+- Entender el sistema sin tocar codigo -> `/refacil:explore`
+- Feature nuevo o cambio de comportamiento -> `/refacil:propose`
+- Bug funcional o error en produccion -> `/refacil:bug`
+
+A partir de ahi, el ciclo completo es:
+
+```
+┌───────────────────────────┐
+│  Necesidad de cambio      │
+└──────────────┬────────────┘
+               ▼
+      ┌─────────────────┐
+      │ ¿Tipo de tarea? │
+      └──┬───────┬──────┘
+         │       │
+   FEATURE│       │BUG
+         ▼       ▼
+  /refacil:    /refacil:
+  propose      bug
+  (proposal +  (fix + tests
+   specs +     de regresion
+   design +    + summary.md)
+   tasks)        │
+         │       │
+         ▼       │
+  /refacil:     │
+  apply         │
+         │       │
+         ▼       │
+  /refacil:     │
+  test          │
+         │       │
+         ▼       │
+  /refacil:     │
+  verify        │
+  (max 2 rondas │
+   autofix)     │
+         │       │
+         └───┬───┘
+             ▼
+     /refacil:review
+     (genera .review-passed)
+             ▼
+    /refacil:archive
+    (feature: OpenSpec
+     bug: fix-*/spec.md +
+          review.yaml)
+             ▼
+    /refacil:up-code
+    (verifica review +
+     commit + push + PR)
+             ▼
+         PR creado
+```
+
+**Nota — dos capas de chequeo de review**:
+- `/refacil:up-code` detecta `.review-passed` faltante y **ejecuta `/refacil:review` automaticamente** antes del push.
+- El hook `check-review` tambien intercepta `git push` manuales y **bloquea** la operacion si falta. El hook no invoca skills — solo bloquea e instruye.
+
+**Archive**:
+- Para features/mejoras: OpenSpec mueve a `archive/` y extrae los campos del `.review-passed` a `review.yaml` dentro de cada spec afectado.
+- Para bugs: archivado manual, crea `openspec/specs/fix-*/spec.md` en formato OpenSpec estandar + `review.yaml`.
+- Una misma rama puede acumular multiples bugs, cada uno en su `fix-*/` independiente.
+
+---
+
+## Hooks automaticos
+
+Se instalan en `.claude/settings.json` durante `init` / `update`. Solo aplican a Claude Code (Cursor ignora estos hooks, el resto de la metodologia funciona igual).
 
 | Hook | Evento | Que hace |
-|------|--------|----------|
-| `check-update` | `SessionStart` | Verifica si hay nueva version del paquete en npm y la instala automaticamente. Tambien **sincroniza el bloque `compact-guidance`** en `AGENTS.md` (ver [Eficiencia de tokens](#eficiencia-de-tokens-bloque-auto-gestionado-en-agentsmd)). |
-| `compact-bash` | `PreToolUse` (Bash) | Reescribe **silenciosamente** comandos Bash bare (git/tests/docker logs) a su forma compacta usando `updatedInput`. Sin turnos extra y sin que Claude vea el cambio. Requiere Claude Code >= 2.1.89. |
-| `check-review` | `PreToolUse` (Bash) | Intercepta `git push` y verifica que exista `.review-passed` en cada cambio activo de `openspec/changes/`. Si falta, **bloquea el push** y emite instrucciones para ejecutar `/refacil:review`. El hook no invoca skills por si mismo. |
-
-#### Flujo del hook de review
-
-El hook unicamente decide `allow` o `block`. La ejecucion automatica de `/refacil:review` la realiza `/refacil:up-code`, no el hook.
-
-```
-git push (manual o via /refacil:up-code)
-  │
-  ▼
-Hook check-review se dispara
-  │
-  ▼
-Busca carpetas activas en openspec/changes/ (excluye archive/)
-  │
-  ▼
-¿Todas tienen .review-passed?
-  │
-  ├─ SI ──► allow → el push procede
-  │
-  └─ NO ──► block → emite mensaje instructivo:
-             • 1 pendiente   → sugiere "/refacil:review <cambio>"
-             • N pendientes  → lista cambios y pide seleccionar uno
-
-Capa adicional cuando se usa /refacil:up-code:
-  /refacil:up-code detecta el faltante ANTES de llamar a git push,
-  invoca /refacil:review y solo entonces intenta el push.
-    • Si el review APRUEBA      → genera .review-passed → push procede
-    • Si requiere CORRECCIONES  → informa al usuario, no pushea
-```
-
-#### Evidencia de review
+|---|---|---|
+| `check-update` | `SessionStart` | Chequea nueva version en npm, la instala, y **sincroniza el bloque `compact-guidance`** en `AGENTS.md`. |
+| `compact-bash` | `PreToolUse` (Bash) | Reescribe silenciosamente comandos Bash bare via `updatedInput`. Sin turnos extra, sin que Claude vea el cambio. Requiere Claude Code >= 2.1.89. |
+| `check-review` | `PreToolUse` (Bash) | Intercepta `git push` y bloquea si falta `.review-passed` en algun cambio activo. |
 
-Cuando `/refacil:review` aprueba un cambio, crea el archivo `.review-passed` en la carpeta del cambio:
+### Gate de review en el push
 
 ```
-openspec/changes/mi-feature/
-├── proposal.md
-├── design.md
-├── tasks.md
-├── specs.md
-└── .review-passed        ← evidencia de review aprobado (JSON)
-
-openspec/changes/fix-session-timeout-redis/
-├── summary.md            ← trazabilidad del bug fix
-└── .review-passed        ← evidencia de review aprobado (JSON)
+         ┌──────────────────────────────┐
+         │ Dev ejecuta /refacil:up-code │
+         │      o git push manual       │
+         └──────────────┬───────────────┘
+                        │
+     ┌──────────────────┴──────────────────┐
+     │ Via /refacil:up-code                │ git push directo
+     ▼                                     ▼
+┌─────────────────────┐          ┌───────────────────────┐
+│ up-code detecta     │          │ Hook check-review     │
+│ falta .review-passed│          │ (PreToolUse en Bash)  │
+│ INVOCA /refacil:    │          │ Verifica .review-     │
+│ review              │          │ passed en changes/*   │
+└─────────┬───────────┘          └──────────┬────────────┘
+          │                                 │
+          ▼                                 ▼
+   ┌──────────────┐                ┌─────────────────┐
+   │ ¿Review OK?  │                │ ¿Falta alguno?  │
+   └──┬────────┬──┘                └──┬───────────┬──┘
+    SI│      NO│                    SI│         NO│
+      ▼        ▼                      ▼           ▼
+   push OK  informa +              block +     allow
+            no pushea              instruccion push
 ```
 
-El archivo `.review-passed` contiene: veredicto, fecha, resumen, cantidad de hallazgos y si hubo blockers.
+### Hook `compact-bash` — rewrite silencioso de comandos
 
-### Hook `compact-bash` — rewrite silencioso de comandos Bash
+Segunda capa de reduccion de tokens, **sin costo conversacional**. Claude emite un comando Bash; antes de ejecutarlo, el hook lo inspecciona, y si matchea una regla lo reescribe via `updatedInput`. Claude no ve el cambio.
 
-Segunda capa de reduccion de tokens, **sin costo conversacional**. Antes de que Claude Code ejecute un comando Bash, el hook `compact-bash` inspecciona el comando y, si matchea una regla, lo reescribe usando el campo `updatedInput` del hook. Claude **no ve el cambio**, no hay turno adicional, no hay bloqueo.
+**Detector de intencion**: si el comando ya tiene flags explicitos (`git log -p`, `jest --watch`, `docker logs --tail 50`), el hook **no interviene** — tu intencion manda.
 
-**Reglas activas (19 reglas)**:
+**Escape**: prefija `COMPACT=0` al comando (`COMPACT=0 git log`).
 
-Fase 1 — git, tests base, docker logs:
+**Reglas activas — git, tests, docker logs**:
 
-| Comando bare | Reescrito a | Ahorro tipico |
+| Bare | Reescrito a | Ahorro |
 |---|---|---|
 | `git log` | `git log --oneline -20` | ~85% |
 | `git status` | `git status -s` | ~70% |
 | `git diff` (sin args) | `git diff --stat` | ~80% |
 | `git show` | `git show --stat` | ~70% |
-| `docker logs <container>` | `docker logs --tail 100 <container>` | ~80%+ |
+| `docker logs <c>` | `docker logs --tail 100 <c>` | ~80% |
 | `npm test` / `yarn test` / `pnpm test` | `… 2>&1 \| tail -80` | ~90% |
 | `jest` | `jest --silent --reporters=summary` | ~85% |
 | `pytest` | `pytest -q` | ~60% |
 
-Fase 2A — linters, type checkers, build, sistema:
+**Reglas activas — linters, type checkers, build, sistema**:
 
-| Comando bare | Reescrito a | Ahorro tipico |
+| Bare | Reescrito a | Ahorro |
 |---|---|---|
 | `eslint` | `eslint . --format compact --quiet` | ~70% |
 | `eslint <path>` | `eslint <path> --format compact` | ~60% |
 | `biome check` | `biome check --reporter=summary` | ~65% |
 | `tsc` / `npx tsc …` | `… 2>&1 \| head -80` | variable |
-| `prettier --check <path>` | `prettier --check <path> --loglevel warn` | ~50% |
+| `prettier --check <p>` | `prettier --check <p> --loglevel warn` | ~50% |
 | `npm audit` | `npm audit 2>&1 \| tail -10` | ~80% |
 | `npm ls` | `npm ls --depth=0` | ~90% |
-| `cargo build` / `cargo test` / `cargo check` | `… --quiet` | ~50% |
+| `cargo build / test / check` | `… --quiet` | ~50% |
 | `go test …` (sin flags) | `… 2>&1 \| tail -80` | ~70% |
 | `mvn test` | `mvn test -q` | ~60% |
 | `./gradlew test` / `gradle test` | `… -q` | ~60% |
 | `ps aux` | `ps -eo pid,pcpu,pmem,comm \| head -30` | ~80% |
 
-**Detector de intencion**: si el comando ya tiene flags explicitos (`git log -p`, `git log --all`, `jest --watch`, `docker logs --tail 50 …`), el hook **no interviene**. Tu intencion manda.
+**Telemetria**: cada rewrite genera una linea JSON en `~/.refacil-sdd-ai/compact.log` (local, nada viaja fuera). `compact stats` calcula ahorro en tokens y USD estimado (a $3/MTok input de Sonnet, conservador).
 
-**Escape mecanismo**: prefija `COMPACT=0` al comando para desactivar el rewrite puntualmente: `COMPACT=0 git log`.
+### Bloque `compact-guidance` en AGENTS.md
 
-**Pipes y redirecciones** en test bare: si ya hay `|` o `>`, el detector no las envuelve de nuevo.
+La metodologia SDD-AI genera mucho contexto (artefactos, specs, prompts). Para compensar, el paquete mantiene un bloque en `AGENTS.md` que instruye a la IA a pedir salidas compactas (Read con offset/limit, `git log --oneline`, tests solo con failures, etc.).
 
-**Subcomandos de control**:
+- Delimitado por `<!-- refacil-sdd-ai:compact-guidance:start -->` y `...:end -->`
+- Fuente de verdad: `templates/compact-guidance.md`
+- Sincroniza en: `init`, `update`, y hook `check-update` (cada SessionStart)
+- Si `AGENTS.md` no existe, no se crea a espaldas del usuario
 
-```bash
-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
-```
+> **No editar manualmente** entre los marcadores. Se sobrescribe en la proxima sesion.
 
-**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**:
+## Reglas metodologicas transversales
 
-```
-Claude emite "git log"
-  │
-  ▼
-Hook compact-bash recibe tool_input via stdin (JSON)
-  │
-  ▼
-¿Matchea alguna regla y no tiene intent flags?
-  │
-  ├─ SI  ──► stdout JSON:
-  │          {
-  │            "hookSpecificOutput": {
-  │              "hookEventName": "PreToolUse",
-  │              "permissionDecision": "allow",
-  │              "updatedInput": { "command": "git log --oneline -20", ... },
-  │              "permissionDecisionReason": "compact-bash: git log → --oneline -20"
-  │            }
-  │          }
-  │          Claude Code ejecuta el comando reescrito. Claude no lo ve.
-  │
-  └─ NO  ──► stdout vacio → Claude Code ejecuta el comando original.
-```
+Definidas en `skills/prereqs/METHODOLOGY-CONTRACT.md`:
 
-### Eficiencia de tokens (bloque auto-gestionado en AGENTS.md)
+- **Estados del flujo**: `READY_FOR_APPLY` / `VERIFY` / `REVIEW` / `ARCHIVE` / `MERGE` — cada transicion valida prerequisitos.
+- **Politica de ramas**: toda rama nueva (`feature/*`, `fix/*`, etc.) se crea desde `develop`/`dev` actualizado. Integracion a ramas protegidas (`testing`, `develop`, `dev`, `main`, `master`, `qa`) siempre por PR. **Nunca** commits directos a `master`/`main`. Excepcion unica: repos sin `develop`/`dev`, donde se permite usar temporalmente `main` o `master` como base.
+- **Tests multi-stack**: se detecta el comando real (no hardcodea `npm test`).
+- **`AGENTS.md` por perfil** (`openspec` vs `agents`): la metodologia respeta ambos.
+- **Modo de salida**: conciso por defecto, detallado bajo demanda.
 
-La metodologia SDD-AI genera consumo elevado de contexto (artefactos, specs, prompts de skills). Para compensarlo, `refacil-sdd-ai` mantiene un bloque de guia de eficiencia de tokens dentro de `AGENTS.md` que instruye a la IA sobre como pedir salidas compactas (Read con offset/limit, `git log --oneline`, tests solo con failures, etc.).
+---
 
-**Caracteristicas**:
-- Delimitado por marcadores HTML: `<!-- refacil-sdd-ai:compact-guidance:start -->` y `<!-- refacil-sdd-ai:compact-guidance:end -->`
-- Fuente de verdad: `templates/compact-guidance.md` dentro del paquete
-- Se sincroniza automaticamente en tres momentos:
-  1. `refacil-sdd-ai init` (al instalar)
-  2. `refacil-sdd-ai update` (al actualizar manualmente)
-  3. Hook `check-update` en cada `SessionStart` (garantiza que repos ya instalados reciban las guias nuevas sin intervencion manual)
-- Si `AGENTS.md` aun no existe (el usuario no ha corrido `/refacil:setup`), la sincronizacion no hace nada — no se crea el archivo a espaldas del usuario
-- `refacil-sdd-ai clean` remueve el bloque de forma limpia
+## refacil-bus — chat room entre agentes
 
-> **IMPORTANTE**: No edites manualmente el contenido entre los marcadores. Cualquier cambio se sobrescribira en la proxima sesion. Si tienes sugerencias sobre reglas de eficiencia, proponlas al paquete (`templates/compact-guidance.md`).
+Bus local (WebSocket sobre `127.0.0.1`) para que los agentes de distintos repos se comuniquen por texto plano. **No comparte archivos, contexto ni tokens entre repos** — cada agente responde desde su propio codigo.
 
-**Flujo del refresh automatico**:
+**Caso de uso principal**: un dev con varias ventanas de IDE abiertas (una por repo). Antes del bus, el dev hacia de transcriptor entre sus propios agentes. Con el bus, los agentes se hablan solos.
 
-```
-Nueva sesion de Claude Code
-  │
-  ▼
-Hook SessionStart → ejecuta "refacil-sdd-ai check-update"
-  │
-  ├─► syncCompactGuidance()
-  │     │
-  │     ├─ AGENTS.md no existe → skip (sin ruido)
-  │     ├─ sin marcadores      → append del bloque al final
-  │     ├─ con marcadores      → reemplaza contenido entre ellos
-  │     └─ contenido identico  → no-op (no ensucia git status)
-  │
-  └─► chequeo de version npm
-        │
-        └─ si hay version nueva → npm update -g + refacil-sdd-ai update
-                                  (que vuelve a sincronizar el bloque)
-```
+**Propiedades**:
 
-## Como funciona
+- 100% local: nada sale de `127.0.0.1`. Sin cuentas, sin servicio compartido.
+- Zero config: el broker se auto-arranca la primera vez que una skill lo necesita (`127.0.0.1:7821`, fallback 7822/7823).
+- ~40 MB RAM, 0% CPU idle. Persistencia: `~/.refacil-sdd-ai/bus/<sala>/inbox.jsonl` (rotacion 7 dias).
+- Mismas skills en Claude Code y Cursor.
 
-1. **`refacil-sdd-ai init`** copia las skills a `.claude/skills/` y `.cursor/skills/`, crea `CLAUDE.md` + `.cursorrules`, y configura hooks automaticos en `.claude/settings.json`
-2. **`/refacil:setup`** (en Claude Code o Cursor) instala OpenSpec, analiza el repo y genera un `AGENTS.md` personalizado
-3. Las demas skills (`propose`, `apply`, `test`, etc.) leen `AGENTS.md` para entender las convenciones del proyecto
-4. `/refacil:up-code` verifica que el review se haya completado antes de pushear — si falta, ejecuta `/refacil:review` automaticamente
-5. En Claude Code, los hooks agregan una capa extra: auto-actualizacion de version al iniciar sesion y bloqueo de push sin review
-
-```
-refacil-sdd-ai init          →  Skills en .claude/ y .cursor/
-                                 CLAUDE.md y .cursorrules creados
-                                 Hooks configurados en .claude/settings.json
-
-/refacil:setup               →  OpenSpec instalado
-                                 AGENTS.md generado (analisis automatico del repo)
-                                 + bloque compact-guidance inyectado automaticamente
-
-/refacil:propose             →  Artefactos en openspec/changes/
-/refacil:apply               →  Codigo implementado
-/refacil:test                →  Tests generados
-/refacil:verify              →  Validacion PASS/FAIL (puede aplicar fixes con aprobacion)
-/refacil:review              →  Review con checklist + .review-passed si aprueba
-/refacil:bug                 →  Fix + trazabilidad en openspec/changes/fix-*/summary.md
-/refacil:archive             →  Cambio archivado + specs sincronizadas
-                                 (bugs: crea openspec/specs/fix-*/spec.md OpenSpec + review.yaml)
-/refacil:up-code             →  Verifica review (si falta lo ejecuta) + push a rama
-```
-
-## Que se instala en tu repo
-
-```
-.claude/skills/refacil-*/    # Claude Code (refacil-prereqs incluye OPENSPEC-DELTAS.md)
-.claude/settings.json        # Hooks automaticos (check-update + check-review)
-.cursor/skills/refacil-*/    # Cursor — copia equivalente
-.claude/skills/refacil-setup/troubleshooting.md  # guia incluida en refacil-setup si falla install/PATH
-CLAUDE.md                    # Claude Code — apunta a AGENTS.md
-.cursorrules                 # Cursor — apunta a AGENTS.md
-AGENTS.md                    # Generado por /refacil:setup (NO por el CLI)
-                             # Incluye bloque compact-guidance auto-gestionado por el hook SessionStart
-openspec/                    # Generado por /refacil:setup via OpenSpec
-```
-
-## Desinstalar
+**Arranque rapido**:
 
 ```bash
-# Eliminar skills del repo actual
-refacil-sdd-ai clean
-# (tambien remueve hooks SDD-AI de .claude/settings.json)
-
-# Desinstalar paquete global (opcional)
-npm uninstall -g refacil-sdd-ai
-```
-
-## 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)
+# En cada repo, una vez
 /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.
+# La primera vez el LLM escribe un bloque de presentacion en AGENTS.md
 ```
 
-**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.
+**Patron optimo**: antes de arrancar una tarea que puede requerir consultar otro repo, ir a la ventana del otro repo y decir *"atiende el bus"*. Eso lo pone en `/refacil:attend` y la conversacion entre agentes ocurre en background sin que el dev cambie de ventana.
 
-# Mas tarde, Dev B dice a su LLM: "atiende el bus"
-# -> /refacil:attend procesa las preguntas pendientes en orden FIFO.
+**Observador puro** (0 tokens): `refacil-sdd-ai bus watch <session>` o `refacil-sdd-ai bus view` para la UI web.
 
-# 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 en terminal (sin tokens)
-refacil-sdd-ai bus view                # Abre la UI web en el navegador (sin tokens)
-refacil-sdd-ai bus leave               # Salir de la sala (limpieza manual)
-refacil-sdd-ai bus history [--n N]     # Ultimos N mensajes
-```
-
-### Vista web en vivo — `bus view`
-
-Ademas del panel en terminal (`bus watch`), refacil-bus incluye una UI web minimalista. Se abre con:
-
-```bash
-refacil-sdd-ai bus view
-```
-
-El broker (que ya expone el puerto `127.0.0.1:7821` para WebSocket) tambien sirve HTTP desde ahi — **cero deps nuevas, cero servicios externos**. El comando:
-
-1. Auto-arranca el broker si no estaba corriendo
-2. Abre el navegador por default del OS en `http://127.0.0.1:7821/`
-3. Imprime la URL por stdout por si el navegador no abre solo
-
-**Que muestra la UI**:
+> **Diagramas, escenarios y pitch**: ver [`refacil-bus-diagrams.md`](./refacil-bus-diagrams.md) — incluye arquitectura, flujo con attend, flujo sin attend, tabla comparativa de impacto y guia de decision visual (Mermaid).
+>
+> **Referencia tecnica completa**: ver [`REFACIL-BUS.md`](./REFACIL-BUS.md).
 
-- Sidebar con lista de salas activas y sus miembros
-- Feed en vivo con todos los mensajes, coloreados por tipo (`ask` cian, `reply` verde, `say` ambar, `system` gris)
-- Indicador visual de menciones dirigidas (`→ @<session>`)
-- Emparejamiento ask/reply: cada pregunta muestra `pending` hasta que llega la respuesta con su `correlationId`, entonces cambia a `answered`
-- Filtros por tipo (ocultar system, ver solo ask/reply, etc.)
-- Totalizadores fijos abajo: mensajes recibidos, pares cerrados, preguntas pendientes
-- Selector de sala o vista "todas las salas" en la sidebar
-- Auto-scroll al ultimo mensaje; si haces scroll arriba para ver historial, no te interrumpe con los nuevos
+### Limitaciones conocidas
 
-**Util para**: presentar la feature al equipo, hacer demos didacticas, supervisar sesiones en paralelo mientras trabajas, ver en tiempo real que pasa cuando dos agentes conversan. **No consume tokens** — es un observador puro vía WebSocket read-only.
+- Mientras `/refacil:attend` esta activo, la sesion del IDE queda ocupada (abortar con ESC). Mitigacion: segunda ventana del 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, solo loopback y bajo demanda del dev).
 
-### 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:
+## Que se instala en tu repo
 
 ```
-<!-- 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 -->
+.claude/skills/refacil-*/    # Skills Claude Code (incluye refacil-prereqs con OPENSPEC-DELTAS.md)
+.claude/settings.json        # Hooks: check-update + check-review + compact-bash
+.cursor/skills/refacil-*/    # Skills Cursor (equivalente)
+CLAUDE.md                    # Apunta a AGENTS.md
+.cursorrules                 # Apunta a AGENTS.md
+AGENTS.md                    # Generado por /refacil:setup (no por el CLI)
+                             # Incluye bloque compact-guidance auto-gestionado
+openspec/                    # Generado por /refacil:setup via OpenSpec
 ```
 
-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
+- [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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "2.9.0",
+  "version": "2.10.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"

package/skills/bug/SKILL.md

@@ -39,6 +39,12 @@ Si `$ARGUMENTS` no los trae, pregunta al usuario: comportamiento actual, esperad
 
 Con la hipotesis confirmada: muestra el codigo exacto que falla, explica que condicion no se maneja, evalua impacto en otras zonas.
 
+### Paso 3.5: Validar si la causa raiz es cross-repo (opcional)
+
+Si durante la investigacion la causa raiz parece estar en la interaccion con otro repo (respuesta inesperada de una API externa, evento con formato distinto al esperado, contrato roto del lado del productor/consumidor), **no asumas como se comporta el otro lado** — aplica el protocolo de `refacil-prereqs/BUS-CROSS-REPO.md` para verificarlo con el agente del otro repo via el bus antes de proponer la correccion.
+
+Usa la respuesta para confirmar si el fix va en este repo, en el otro, o en ambos (en cuyo caso el otro tendra su propio `/refacil:bug`).
+
 ### Paso 4: Proponer correccion
 
 Presenta: cambio minimo, archivos a modificar, riesgos, alternativas (si existen). Espera aprobacion antes de implementar.
@@ -128,5 +134,6 @@ Este archivo es obligatorio para la trazabilidad del fix y permite que el hook d
 - El fix debe ser MINIMO — no aprovechar para refactorizar
 - Los tests de regresion son OBLIGATORIOS
 - Si el bug es en produccion (critico), priorizar velocidad pero sin saltarse tests ni trazabilidad
+- El Paso 3.5 (bus cross-repo) es **opcional** — solo invocarlo si la causa raiz parece cross-repo. Ver `refacil-prereqs/BUS-CROSS-REPO.md`.
 - Responder en español con terminos tecnicos en ingles
 - Usa modo de salida **conciso** por defecto y **detallado** solo si el usuario lo pide (ver `METHODOLOGY-CONTRACT.md`)

package/skills/explore/SKILL.md

@@ -24,7 +24,13 @@ Ademas de lo que OpenSpec explore reporta, agrega:
 - Patrones especificos del proyecto que encontraste en AGENTS.md relevantes a la exploracion
 - Convenciones que el usuario deberia tener en cuenta si planea hacer cambios en esa area
 
-### Paso 3: Recomendar siguiente paso
+### Paso 3: Detectar dependencias cross-repo (opcional)
+
+Si durante la exploracion detectas que este repo depende de codigo que NO vive aqui (APIs que consume de otro servicio, eventos que recibe/emite, colas compartidas, contratos con un front/back externo), **no asumas el comportamiento del otro lado** — aplica el protocolo de `refacil-prereqs/BUS-CROSS-REPO.md` para consultar al agente del otro repo via el bus.
+
+Incorpora la respuesta al reporte como contexto cross-repo.
+
+### Paso 4: Recomendar siguiente paso
 
 Al final del reporte, sugiere:
 - Si el usuario quiere hacer un cambio: "Ejecuta `/refacil:propose <descripcion>` para crear una propuesta"
@@ -33,3 +39,4 @@ Al final del reporte, sugiere:
 ## Reglas
 
 - NO modifiques ningun archivo ni generes codigo; solo lectura e investigacion (idioma: ver `OPENSPEC-DELTAS.md`).
+- El Paso 3 (bus cross-repo) es **opcional** — aplica solo si hay una dependencia cross-repo real. Ver `refacil-prereqs/BUS-CROSS-REPO.md`.

package/skills/guide/SKILL.md

@@ -25,9 +25,29 @@ Eres un guia **breve**: eliges el siguiente comando; el detalle de cada flujo es
 6. Review de calidad → `/refacil:review`
 7. Subir codigo y crear PR → `/refacil:up-code`
 8. Configurar repo → `refacil-sdd-ai init` (global + por repo) y `/refacil:setup`
+9. Coordinar con otros repos (sin copy/paste manual) → ver bloque **Bus entre agentes** abajo
 
 > **Nota**: `/refacil:up-code` verifica que el review este aprobado (`.review-passed`). Si falta y hay un solo cambio pendiente, lanza `/refacil:review` automaticamente (sin re-ejecutar si no hay cambios nuevos). Si hay multiples cambios sin review, pide seleccion explicita. Toda integracion a ramas protegidas (incluyendo `testing`) requiere PR. Nunca se hacen ajustes directos en `master` o `main`. La validacion de rama se hace en `/refacil:apply` o `/refacil:bug`, no en `up-code`.
 
+## Bus entre agentes (refacil-bus)
+
+Para cuando el dev tiene varias ventanas de Claude Code / Cursor abiertas (una por repo) y necesita que los agentes se consulten entre si sin que el dev sea el transcriptor manual:
+
+| Comando | Cuando usarlo |
+|---------|---------------|
+| `/refacil:join <sala>` | Primer paso: une esta sesion a una sala (crea el bloque de presentacion en `AGENTS.md` si falta). |
+| `/refacil:say "..."` | Anuncio a toda la sala. |
+| `/refacil:ask @<repo> "..." [--wait N]` | Pregunta dirigida a otro agente. Con `--wait N` bloquea hasta respuesta o N seg. |
+| `/refacil:reply "..."` | Responde la ultima pregunta dirigida a esta sesion. |
+| `/refacil:attend` | Deja esta sesion escuchando el bus: cuando llegue una pregunta dirigida, la respondes y vuelves a escuchar. |
+| `/refacil:inbox` | Ver mensajes nuevos desde la ultima lectura. |
+
+**Patron tipico**: antes de una tarea que puede necesitar contexto de otros repos, el dev va a las otras ventanas y dice *"atiende el bus"*. Luego en su repo de trabajo, `/refacil:ask @<otro-repo> "..." --wait 180` trae la respuesta automatica sin saltar entre ventanas.
+
+Para supervision: `refacil-sdd-ai bus view` (UI web) o `refacil-sdd-ai bus watch <session>` (terminal). No consumen tokens.
+
+Detalle completo en el README de refacil-sdd-ai (seccion `refacil-bus`).
+
 ## Tips (una linea por herramienta)
 
 - **Claude Code:** comandos `/refacil:*` en el chat.

package/skills/prereqs/BUS-CROSS-REPO.md

@@ -0,0 +1,38 @@
+# Consulta cross-repo via refacil-bus
+
+Protocolo compartido para todas las skills que pueden necesitar contexto de otro repositorio durante su ejecucion (`explore`, `propose`, `verify`, `bug`).
+
+## Cuando aplicar
+
+Cada skill define su trigger propio (ver su `SKILL.md`). En general, aplica cuando la skill detecta que **necesita informacion que no vive en este repo** y asumirla arriesga un error: contratos de API, formato de eventos, comportamiento del consumidor/productor, colas compartidas.
+
+**Regla de oro**: el bus es **opcional y no bloqueante**. No lo invoques si la pregunta se responde leyendo el codigo de este repo, o si no hay incertidumbre real cross-repo. Si el dev responde o aclara la duda directamente (verbalmente, por chat, con un link a docs, etc.), **la skill continua normalmente** — el bus solo es una de las vias posibles para resolver la incognita.
+
+## Protocolo (3 pasos)
+
+Cuando el trigger de la skill se cumpla:
+
+1. **Verificar salas activas**: ejecuta `refacil-sdd-ai bus rooms` para ver las salas y sus miembros.
+2. **Evaluar precondiciones**:
+   - **Si hay una sala activa Y el repo que necesitas consultar ya esta en ella**: puedes ejecutar `/refacil:ask @<nombre-repo> "pregunta concreta" --wait 180` directamente. **Informa al usuario antes de enviar** ("voy a preguntar a @X en la sala Y: ..."). Si el otro repo esta en `/refacil:attend` responde automatico; si no, el dev va a esa ventana y pide `/refacil:inbox`.
+   - **Si no hay sala, o el repo que necesitas no esta en ninguna**: **no crees la sala por tu cuenta**. Pide al usuario que ejecute `/refacil:join <nombre-sala>` en **esta** sesion y tambien en la sesion del otro repo (otra ventana de IDE). Ambos repos deben estar en la misma sala. Una vez confirmado, vuelve al paso 2.
+
+Si el usuario no conoce el bus o no sabe como configurarlo, remitelo a `/refacil:guide` (seccion "Bus entre agentes") antes de intentar la consulta.
+
+**Salida valida sin bus**: en cualquier punto del protocolo, si el dev responde o aclara la duda directamente, registra su respuesta como contexto y **continua con el flujo de la skill**. No insistas en usar el bus ni bloquees el avance esperando una confirmacion cross-repo que el dev ya respondio por otra via.
+
+## Como usar la respuesta
+
+Cada skill decide que hacer con la respuesta:
+
+- `explore`: incorporarla al reporte como contexto cross-repo.
+- `propose`: ajustar `specs.md` / `design.md` antes de revision humana.
+- `verify`: incorporarla al reporte combinado como SUGGESTION; si revela un bug real, escalar a WARNING/CRITICAL.
+- `bug`: usarla para confirmar si el fix va en este repo, en el otro, o en ambos (en cuyo caso el otro tendra su propio `/refacil:bug`).
+
+## Que NO hacer
+
+- No asumas el comportamiento del otro repo sin consultar.
+- No ejecutes `/refacil:join` por tu cuenta — crear o unirse a una sala es decision del dev (implica que el otro repo tambien debe unirse desde su ventana).
+- No ejecutes `/refacil:ask` sin antes verificar que la sala existe y el repo destino esta en ella. Si alguna precondicion falla, pide al dev que la resuelva.
+- No insistas si el dev prefiere resolverlo por otra via (lectura directa, docs, pregunta verbal a un compañero).

package/skills/prereqs/SKILL.md

@@ -30,4 +30,8 @@ Solo requiere `AGENTS.md`. Si existe, leelo y aplica `compact-guidance` si esta
 
 Convenciones Refacil al delegar a skills `openspec-*`: ver `OPENSPEC-DELTAS.md` (misma carpeta), leer junto a la skill OpenSpec que se invoque.
 
+## BUS-CROSS-REPO.md
+
+Protocolo compartido para consultar a otros repositorios via `refacil-bus`. Aplica en `explore`, `propose`, `verify` y `bug` cuando la skill detecta una dependencia cross-repo. Ver `BUS-CROSS-REPO.md` (misma carpeta).
+
 Si faltan estos archivos, ejecuta `refacil-sdd-ai update` (o `init`).

package/skills/propose/SKILL.md

@@ -27,6 +27,12 @@ Si $ARGUMENTS ya es claro, no preguntes de nuevo.
 2. Lee `OPENSPEC-DELTAS.md` en la carpeta `refacil-prereqs` (misma ruta dual que en prereqs).
 3. Ejecuta la skill OpenSpec siguiendo sus instrucciones y aplicando los deltas Refacil para generar los artefactos (proposal, specs, design, tasks) en una sola pasada.
 
+### Paso 2.5: Validar contratos cross-repo (opcional)
+
+Si el cambio propuesto involucra un contrato con otro sistema (un endpoint que otro repo consume, un evento que otro repo emite o recibe, un formato de datos compartido, una cola o topico cross-servicio), **no asumas como luce el otro lado** — aplica el protocolo de `refacil-prereqs/BUS-CROSS-REPO.md` para validarlo con el agente del otro repo via el bus antes de cerrar los artefactos.
+
+Usa la respuesta para ajustar `specs.md` / `design.md` antes de pasar a revision humana.
+
 ### Paso 3: Revision del desarrollador (Human-in-the-Loop)
 
 **IMPORTANTE**: Este paso es OBLIGATORIO. El desarrollador debe revisar y aprobar los artefactos antes de implementar.
@@ -72,3 +78,4 @@ Siguiente paso: ejecuta /refacil:apply para implementar las tasks.
 - Si el usuario pide que tambien implemente, responder: "La implementacion se hace con `/refacil:apply` despues de aprobar los artefactos."
 - Siempre explorar el codebase ANTES de generar artefactos (para que el design sea realista)
 - Los criterios de aceptacion deben ser especificos y testeables
+- El Paso 2.5 (bus cross-repo) es **opcional** — solo invocarlo si el cambio toca un contrato con otro sistema. Ver `refacil-prereqs/BUS-CROSS-REPO.md`.

package/skills/verify/SKILL.md

@@ -49,6 +49,12 @@ Correcciones necesarias:
 2. [issues de tests]
 ```
 
+### Paso 3.5: Validar ambigüedades cross-repo (opcional)
+
+Si durante la verificacion detectas que la spec no cubre algo relevante del lado de un consumidor o productor externo (formato que otro repo espera, evento que otro repo emite, comportamiento del consumidor bajo cierta condicion), y esa ambigüedad impide decidir si la implementacion es correcta, **no asumas** — aplica el protocolo de `refacil-prereqs/BUS-CROSS-REPO.md` para resolverlo con el agente del otro repo via el bus antes de cerrar el reporte.
+
+Incorpora la respuesta al reporte combinado como SUGGESTION; si revela un bug real, escalalo a WARNING/CRITICAL.
+
 ### Paso 4: Resultado y siguiente paso
 
 #### Si APROBADO (sin issues CRITICAL ni WARNING):
@@ -92,3 +98,4 @@ Lista los issues para que el usuario los corrija manualmente. Sugiere ejecutar `
 - Ser estricto con los criterios de la spec
 - Si algo no esta en la spec pero parece necesario, mencionarlo como SUGGESTION (observacion), no como CRITICAL/WARNING
 - Usa modo de salida **conciso** por defecto y **detallado** solo si el usuario lo pide (ver `METHODOLOGY-CONTRACT.md`)
+- El Paso 3.5 (bus cross-repo) es **opcional** — solo invocarlo si hay una ambigüedad real cross-repo que bloquea el veredicto. Ver `refacil-prereqs/BUS-CROSS-REPO.md`.

package/templates/methodology-guide.md

@@ -20,6 +20,23 @@ Skills identicas en `.claude/skills/refacil-*/` (Claude Code) y `.cursor/skills/
 
 Flujo: `setup` → `propose` → `apply` → `test` → `verify` → `review` → `archive` → `up-code`
 
+## Bus entre agentes (refacil-bus)
+
+Canal local de texto plano entre sesiones de Claude Code / Cursor corriendo en distintos repos. Evita que el dev haga de transcriptor manual entre sus propios agentes.
+
+| Comando | Descripcion |
+|---------|-------------|
+| `/refacil:join <sala>` | Crear o unirse a una sala. La primera vez genera un bloque de presentacion en `AGENTS.md`. |
+| `/refacil:say "..."` | Anuncio a toda la sala. |
+| `/refacil:ask @nombre "..." [--wait N]` | Pregunta dirigida a otra sesion. `--wait N` bloquea hasta respuesta o N seg. |
+| `/refacil:reply "..."` | Responde la ultima pregunta dirigida (autocompleta `correlationId`). |
+| `/refacil:attend` | Modo escucha activa: recibe preguntas y el LLM las responde, luego re-invoca para seguir escuchando. |
+| `/refacil:inbox` | Ver mensajes nuevos desde la ultima lectura. |
+
+Uso tipico: antes de arrancar una tarea que puede requerir contexto de otros repos, el dev pone al agente de cada otro repo en `/refacil:attend`. Despues, en su repo de trabajo, el LLM puede pedir contexto con `/refacil:ask @<repo> "..." --wait` y recibir la respuesta automaticamente sin que el dev salte entre ventanas.
+
+CLI util para el dev: `refacil-sdd-ai bus view` (abre UI web en el navegador), `bus watch <session>` (panel en terminal), `bus status`, `bus rooms`. No consumen tokens.
+
 ## Eficiencia de tokens (automatica)
 
 - El hook `check-update` en `SessionStart` sincroniza el bloque `compact-guidance` en `AGENTS.md`.