refacil-sdd-ai 3.0.2 → 3.1.0

package/README.md

@@ -1,392 +1,398 @@
-# refacil-sdd-ai
-
-Metodologia **SDD-AI** (Specification-Driven Development with AI) empaquetada como CLI.
-
-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 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.
-
----
-
-## Instalacion
-
-Recomendado: instalar globalmente una sola vez, y correr `init` por repo.
-
-```bash
-# 1. Global (una vez)
-npm install -g refacil-sdd-ai
-
-# 2. En la raiz del repo
-refacil-sdd-ai init
-#    Copia skills a .claude/ y .cursor/, crea CLAUDE.md + .cursorrules, configura hooks
-
-# 3. Reiniciar sesion de Claude Code o Cursor
-#    (las skills nuevas no se detectan hasta reiniciar)
-
-# 4. En el IDE
-/refacil:setup
-#    Instala OpenSpec, inicializa openspec/ y genera AGENTS.md
-```
-
-### Actualizar
-
-```bash
-npm update -g refacil-sdd-ai
-refacil-sdd-ai update          # en cada repo donde se use
-```
-
-En Claude Code el hook `check-update` hace esto automaticamente al iniciar sesion.
-
-### Desinstalar
-
-```bash
-refacil-sdd-ai clean           # en el repo (elimina skills + hooks SDD-AI)
-npm uninstall -g refacil-sdd-ai
-```
-
-> **Nota**: `openspec init` tambien instala sus comandos `opsx:*`. Coexisten sin conflicto con los `refacil:*`. Usar siempre `refacil:*` como interfaz principal.
-
----
-
-## Comandos del CLI
-
-### Gestion del paquete
-
-| 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 |
-
-### Hooks internos (invocados automaticamente, no manual)
-
-| 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` |
-
-### Control del rewrite de comandos (`compact-bash`)
-
-| 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` |
-
-### Bus de agentes (`bus`)
-
-| 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 |
-
-> 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.
-
----
-
-## Skills disponibles en el IDE
-
-Todas se invocan como `/refacil:<nombre>` en Claude Code o Cursor.
-
-### Ciclo SDD
-
-| 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 |
-
-### Sub-agentes automaticos (v3.0.0+)
-
-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.
-
-| 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 |
-
-**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`).
-
-**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.
-
-### Bus de agentes
-
-| 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` | 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. |
-
-### Gate de review en el push
-
-```
-         ┌──────────────────────────────┐
-         │ 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
-```
-
-### Hook `compact-bash` — rewrite silencioso de comandos
-
-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.
-
-**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.
-
-**Escape**: prefija `COMPACT=0` al comando (`COMPACT=0 git log`).
-
-**Reglas activas — git, tests, docker logs**:
-
-| 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 <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% |
-
-**Reglas activas — linters, type checkers, build, sistema**:
-
-| 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 <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 / 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% |
-
-**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).
-
-### Bloque `compact-guidance` en AGENTS.md
-
-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.).
-
-- 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
-
-> **No editar manualmente** entre los marcadores. Se sobrescribe en la proxima sesion.
-
----
-
-## Reglas metodologicas transversales
-
-Definidas en `skills/prereqs/METHODOLOGY-CONTRACT.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.
-
----
-
-## refacil-bus — chat room entre agentes
-
-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.
-
-**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.
-
-**Propiedades**:
-
-- 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.
-
-**Arranque rapido**:
-
-```bash
-# En cada repo, una vez
-/refacil:join refacil-main
-# La primera vez el LLM escribe un bloque de presentacion en AGENTS.md
-```
-
-**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.
-
-**Observador puro** (0 tokens): `refacil-sdd-ai bus watch <session>` o `refacil-sdd-ai bus view` para la UI web.
-
-> **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).
-
-### Limitaciones conocidas
-
-- 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).
-
----
-
-## Que se instala en tu repo
-
-```
-.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
-```
-
----
-
-## Tecnologias
-
-- [OpenSpec](https://github.com/Fission-AI/OpenSpec) — framework de especificaciones
-- [AGENTS.md](https://agents.md/) — estandar universal de instrucciones para IA
-- [Claude Code](https://claude.ai/code) — CLI de Anthropic
-- [Cursor](https://cursor.sh) — IDE con IA
-
-## Licencia
-
-MIT
+# refacil-sdd-ai
+
+Metodologia **SDD-AI** (Specification-Driven Development with AI) empaquetada como CLI.
+
+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 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.
+
+---
+
+## Instalacion
+
+Recomendado: instalar globalmente una sola vez, y correr `init` por repo.
+
+```bash
+# 1. Global (una vez)
+npm install -g refacil-sdd-ai
+
+# 2. En la raiz del repo
+refacil-sdd-ai init
+#    Copia skills a .claude/ y .cursor/, crea CLAUDE.md + .cursorrules, configura hooks
+#    Crea/actualiza .claudeignore y .cursorignore con exclusiones base
+
+# 3. Reiniciar sesion de Claude Code o Cursor
+#    (las skills nuevas no se detectan hasta reiniciar)
+
+# 4. En el IDE
+/refacil:setup
+#    Instala OpenSpec, inicializa openspec/ y genera AGENTS.md
+```
+
+### Actualizar
+
+```bash
+npm update -g refacil-sdd-ai
+refacil-sdd-ai update          # en cada repo donde se use
+```
+
+En Claude Code el hook `check-update` hace esto automaticamente al iniciar sesion.
+
+### Desinstalar
+
+```bash
+refacil-sdd-ai clean           # en el repo (elimina skills + hooks SDD-AI)
+npm uninstall -g refacil-sdd-ai
+```
+
+> **Nota**: `openspec init` tambien instala sus comandos `opsx:*`. Coexisten sin conflicto con los `refacil:*`. Usar siempre `refacil:*` como interfaz principal.
+
+---
+
+## Comandos del CLI
+
+### Gestion del paquete
+
+| 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 |
+
+### Hooks internos (invocados automaticamente, no manual)
+
+| 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` |
+
+### Control del rewrite de comandos (`compact-bash`)
+
+| 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` |
+
+### Bus de agentes (`bus`)
+
+| 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 |
+
+> 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.
+
+---
+
+## Skills disponibles en el IDE
+
+Todas se invocan como `/refacil:<nombre>` en Claude Code o Cursor.
+
+### Ciclo SDD
+
+| 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 (solicita links de Jira) |
+| `/refacil:up-code` | Commit + push + PR (ejecuta review si falta) |
+| `/refacil:bug` | Flujo completo de bugfix con tests de regresion |
+
+### Sub-agentes automaticos (v3.0.0+)
+
+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.
+
+| 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 |
+
+**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`).
+
+**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.
+
+### Bus de agentes
+
+| 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.
+- `/refacil:archive` siempre solicita uno o varios **links de Jira** asociados al cambio antes de proceder. Los links se guardan en `review.yaml` bajo el campo `jiraTasks` (lista YAML). El campo es obligatorio — el archivado no avanza hasta que el usuario proporcione al menos un link.
+
+---
+
+## Hooks automaticos
+
+Se instalan en `.claude/settings.json` **y** `.cursor/settings.json` durante `init` / `update`. Aplican tanto a **Claude Code** como a **Cursor**.
+
+| Hook | Evento | Que hace |
+|---|---|---|
+| `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 el IDE 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. |
+
+Los tres hooks se instalan en paralelo en `.claude/settings.json` (Claude Code) y `.cursor/settings.json` (Cursor) con la misma logica parametrica.
+
+### Gate de review en el push
+
+```
+         ┌──────────────────────────────┐
+         │ 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
+```
+
+### Hook `compact-bash` — rewrite silencioso de comandos
+
+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.
+
+**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.
+
+**Escape**: prefija `COMPACT=0` al comando (`COMPACT=0 git log`).
+
+**Reglas activas — git, tests, docker logs**:
+
+| 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 <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% |
+
+**Reglas activas — linters, type checkers, build, sistema**:
+
+| 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 <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 / 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% |
+
+**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).
+
+### Bloque `compact-guidance` en AGENTS.md
+
+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.).
+
+- 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
+
+> **No editar manualmente** entre los marcadores. Se sobrescribe en la proxima sesion.
+
+---
+
+## Reglas metodologicas transversales
+
+Definidas en `skills/prereqs/METHODOLOGY-CONTRACT.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.
+
+---
+
+## refacil-bus — chat room entre agentes
+
+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.
+
+**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.
+
+**Propiedades**:
+
+- 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.
+
+**Arranque rapido**:
+
+```bash
+# En cada repo, una vez
+/refacil:join refacil-main
+# La primera vez el LLM escribe un bloque de presentacion en AGENTS.md
+```
+
+**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.
+
+**Observador puro** (0 tokens): `refacil-sdd-ai bus watch <session>` o `refacil-sdd-ai bus view` para la UI web.
+
+> **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).
+>
+
+### Limitaciones conocidas
+
+- 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).
+
+---
+
+## Que se instala en tu repo
+
+```
+.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)
+.cursor/settings.json        # Hooks: check-update + check-review + compact-bash (mirror de .claude/)
+CLAUDE.md                    # Apunta a AGENTS.md
+.cursorrules                 # Apunta a AGENTS.md
+.claudeignore                # Exclusiones base (node_modules, dist, .env, *.key, etc.)
+.cursorignore                # Idem — mismo contenido que .claudeignore
+AGENTS.md                    # Generado por /refacil:setup (no por el CLI)
+                             # Incluye bloque compact-guidance auto-gestionado
+openspec/                    # Generado por /refacil:setup via OpenSpec
+```
+
+---
+
+## Tecnologias
+
+- [OpenSpec](https://github.com/Fission-AI/OpenSpec) — framework de especificaciones
+- [AGENTS.md](https://agents.md/) — estandar universal de instrucciones para IA
+- [Claude Code](https://claude.ai/code) — CLI de Anthropic
+- [Cursor](https://cursor.sh) — IDE con IA
+
+## Licencia
+
+MIT