refacil-sdd-ai 2.9.1 → 3.0.0

package/README.md

@@ -1,743 +1,389 @@
 # 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** y **sub-agentes** 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
+refacil-sdd-ai clean           # en el repo (elimina skills + hooks SDD-AI)
+npm uninstall -g refacil-sdd-ai
 ```
 
-## Skills disponibles
+> **Nota**: `openspec init` tambien instala sus comandos `opsx:*`. Coexisten sin conflicto con los `refacil:*`. Usar siempre `refacil:*` como interfaz principal.
 
-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
-```
+## Comandos del CLI
 
-### Bug fix
+### Gestion del paquete
 
-```
-/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
-```
+| 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 |
 
-> **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.
+### Hooks internos (invocados automaticamente, no manual)
 
-### Explorar codigo
+| 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` |
 
-```
-/refacil:explore "que quiero entender"
-```
+### Control del rewrite de comandos (`compact-bash`)
 
-## Diagrama de flujo completo
+| 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` |
 
-Vista unica del ciclo de vida de un cambio — desde la necesidad hasta el PR integrado.
+### Bus de agentes (`bus`)
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│              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)       │
-             └─────────────────┘
-```
+| 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 |
 
-### Gate de review en el push
+> 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.
 
-Vista del mecanismo de dos capas que protege `git push`:
+---
 
-```
-                ┌──────────────────────────────┐
-                │ 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      │ │        │
-   └─────────┘ └────────────┘              └─────────────┘ └────────┘
-```
+## Skills disponibles en el IDE
 
-## Reglas metodologicas transversales
+Todas se invocan como `/refacil:<nombre>` en Claude Code o Cursor.
 
-Para mantener consistencia entre todas las skills, el paquete define un contrato metodologico unico en `skills/prereqs/METHODOLOGY-CONTRACT.md`:
+### Ciclo SDD
 
-- 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
+| 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 |
 
-### Politica de ramas (resumen)
+### Sub-agentes automaticos (v3.0.0+)
 
-- 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`.
+Algunos skills delegan su trabajo pesado a **sub-agentes** que corren en contexto aislado (no saturan la sesion principal con lecturas masivas). Son invocados automaticamente por el skill correspondiente — no se llaman directo.
 
-### Checkpoints de estado (DoR/DoD)
+| Skill | Sub-agente | Rol |
+|---|---|---|
+| `/refacil:explore` | `refacil-investigator` | Lee codebase, enriquece con AGENTS.md, consulta bus cross-repo |
+| `/refacil:verify` | `refacil-validator` | Corre tests + compara contra spec, retorna issues priorizados |
+| `/refacil:review` | `refacil-auditor` | Evalua cambios contra el checklist de calidad |
 
-Antes de avanzar de etapa, valida estos estados:
+**Propiedades comunes**: `readonly` (no pueden modificar archivos), system prompt especializado, guardrail de invocacion directa. El contrato con el skill wrapper es un bloque JSON fenced (`refacil-review-result`, `refacil-verify-result`).
 
-- `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
+**Dual-platform**: `.claude/agents/refacil-*.md` usa `tools:` (allowlist granular). `.cursor/agents/refacil-*.md` se genera automaticamente con `readonly: true` y `model: inherit`. El installer transforma el frontmatter.
 
-### 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
-```
-
-**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**:
-
-```
-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.
-```
+> **No editar manualmente** entre los marcadores. Se sobrescribe en la proxima sesion.
 
-### Eficiencia de tokens (bloque auto-gestionado en AGENTS.md)
+---
 
-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
+## Reglas metodologicas transversales
 
-> **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`).
+Definidas en `skills/prereqs/METHODOLOGY-CONTRACT.md`:
 
-**Flujo del refresh automatico**:
+- **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.
 
-```
-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)
-```
+---
 
-## Como funciona
+## refacil-bus — chat room entre agentes
 
-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
+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.
 
-```
-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
-```
+**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.
 
-## Que se instala en tu repo
+**Propiedades**:
 
-```
-.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
-```
+- 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.
 
-## 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.
-```
-
-**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)**
-
+# La primera vez el LLM escribe un bloque de presentacion en AGENTS.md
 ```
-# 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/agents/refacil-*.md  # Sub-agentes (auditor, investigator, validator)
+.claude/settings.json        # Hooks: check-update + check-review + compact-bash
+.cursor/skills/refacil-*/    # Skills Cursor (equivalente)
+.cursor/agents/refacil-*.md  # Sub-agentes Cursor (readonly + model:inherit auto-generados)
+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