refacil-sdd-ai 3.1.0 → 4.0.0

package/README.md

@@ -43,7 +43,7 @@ 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.
+En Claude Code el hook `check-update` hace esto automaticamente al iniciar sesion. Si la nueva version incluye migraciones de estructura (ej. nuevo patron de documentacion), el hook informa al LLM y propone ejecutar `/refacil:update` — la skill detecta que aplica y omite lo que ya esta al dia.
 
 ### Desinstalar
 
@@ -126,6 +126,7 @@ Todas se invocan como `/refacil:<nombre>` en Claude Code o Cursor.
 | `/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 |
+| `/refacil:update` | Detectar y aplicar migraciones pendientes de la metodologia al repo actual |
 
 ### Sub-agentes automaticos (v3.0.0+)
 
@@ -375,12 +376,15 @@ Bus local (WebSocket sobre `127.0.0.1`) para que los agentes de distintos repos
 .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
+CLAUDE.md                    # Indice minimo → apunta a AGENTS.md
+.cursorrules                 # Idem en formato Cursor
 .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
+AGENTS.md                    # Indice del proyecto → generado por /refacil:setup
+                             # Apunta a .agents/ + incluye bloques auto-gestionados
+                             # (compact-guidance y bus presentation)
+.agents/                     # Detalle del proyecto por area (generado por /refacil:setup)
+                             # summary.md, architecture.md, stack.md, testing.md, commands.md...
 openspec/                    # Generado por /refacil:setup via OpenSpec
 ```
 

package/bin/cli.js

@@ -77,6 +77,10 @@ function checkUpdate() {
       `[refacil-sdd-ai] Skills de este repo sincronizadas (${fromLabel} -> v${syncResult.to}). ` +
       'Reinicia la sesion de Claude Code o Cursor para detectar los cambios.',
     );
+    console.log(
+      '[refacil-sdd-ai] La metodologia fue actualizada. ' +
+      'Pregunta al usuario si desea aplicar las migraciones pendientes y, si confirma, ejecuta /refacil:update.',
+    );
   } else if (syncResult && syncResult.failed) {
     console.log(
       `[refacil-sdd-ai] Skills de este repo estan desactualizadas respecto al paquete global (v${syncResult.to}) ` +
@@ -249,6 +253,9 @@ function update() {
 
   writeRepoVersion(projectRoot, getPackageVersion(packageRoot));
 
+  createClaudeMd(packageRoot, projectRoot);
+  createCursorRules(packageRoot, projectRoot);
+
   if (installHooks('.claude', projectRoot)) {
     console.log('  Hook check-update agregado a .claude/settings.json');
   }

package/lib/installer.js

@@ -22,6 +22,7 @@ const SKILLS = [
   'reply',
   'inbox',
   'attend',
+  'update',
 ];
 
 const AGENTS = [
@@ -32,8 +33,6 @@ const AGENTS = [
 
 const REPO_VERSION_FILES = ['.claude/.sdd-version', '.cursor/.sdd-version'];
 
-const SDD_SECTION_MARKER = '## Metodologia SDD-AI (Refacil)';
-
 function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
   const entries = fs.readdirSync(src, { withFileTypes: true });
@@ -134,42 +133,18 @@ function installAgents(packageRoot, projectRoot) {
   return installed;
 }
 
-function extractSddSection(templateContent) {
-  const idx = templateContent.indexOf(SDD_SECTION_MARKER);
-  if (idx === -1) return templateContent;
-  return templateContent.substring(idx);
-}
-
-function readMethodologyGuide(packageRoot) {
-  return fs.readFileSync(
-    path.join(packageRoot, 'templates', 'methodology-guide.md'),
-    'utf8',
-  );
-}
-
-function writeGuideFile(packageRoot, destPath, header, label) {
-  const guide = readMethodologyGuide(packageRoot);
-  const content = `# ${header}\n\n${guide}`;
-
-  if (fs.existsSync(destPath)) {
-    const existing = fs.readFileSync(destPath, 'utf8');
-    if (existing.includes(SDD_SECTION_MARKER)) {
-      console.log(`  ${label} ya tiene la seccion SDD-AI. Sin cambios.`);
-      return false;
-    }
-    const sddSection = extractSddSection(guide);
-    fs.writeFileSync(destPath, existing.trimEnd() + '\n\n' + sddSection + '\n');
-    console.log(`  ${label} existente — seccion SDD-AI agregada al final.`);
-    return true;
-  }
-
+function writeGuideFile(destPath, header, label) {
+  const content =
+    `# ${header}\n\n` +
+    'Contexto completo del proyecto: ver `AGENTS.md`.\n' +
+    'Si no existe, ejecuta `/refacil:setup`.\n';
   fs.writeFileSync(destPath, content);
+  console.log(`  ${label} generado.`);
   return true;
 }
 
 function createClaudeMd(packageRoot, projectRoot) {
   return writeGuideFile(
-    packageRoot,
     path.join(projectRoot, 'CLAUDE.md'),
     'CLAUDE.md',
     'CLAUDE.md',
@@ -178,7 +153,6 @@ function createClaudeMd(packageRoot, projectRoot) {
 
 function createCursorRules(packageRoot, projectRoot) {
   return writeGuideFile(
-    packageRoot,
     path.join(projectRoot, '.cursorrules'),
     'Cursor Rules',
     '.cursorrules',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "3.1.0",
+  "version": "4.0.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"
@@ -12,7 +12,8 @@
     "agents/",
     "templates/",
     "config/",
-    "README.md"
+    "README.md",
+    "refacil-bus-diagrams.md"
   ],
   "keywords": [
     "ai",

package/refacil-bus-diagrams.md

@@ -0,0 +1,314 @@
+# refacil-bus — Diagramas y explicación
+
+Documento para presentar la feature al equipo. Usa Mermaid (se renderiza automático en GitHub, GitLab, Notion, Confluence, Teams, VS Code preview). Para exportar a imagen: https://mermaid.live
+
+---
+
+## 1. El problema que resolvemos
+
+Un único dev trabaja con varios repos abiertos al mismo tiempo — **una ventana de Claude Code o Cursor por repo** (microservicios + frontend + utilidades). Cada ventana tiene SU propio agente del LLM que solo conoce ese repo. Cuando el dev está trabajando en un repo y necesita contexto de otro, hoy tiene que:
+
+- pausar lo que está haciendo
+- **saltar a la ventana del otro repo**
+- leer código él mismo, o preguntarle al LLM de esa otra ventana
+- copiar la respuesta manualmente
+- volver a la ventana original y pegar/explicar al primer agente
+
+El resultado: **el dev queda de mensajero entre sus propios agentes**. Contexto se pierde, se transcribe mal, y los bugs cruzados aparecen en QA.
+
+> **Clave del caso de uso**: las "sesiones" en el bus NO son devs distintos — son los **agentes de LLM** de cada repo que el mismo dev tiene abiertos. El bus es para que esos agentes se hablen entre sí sin que el dev sea el intermediario.
+
+### Antes de refacil-bus
+
+```mermaid
+flowchart LR
+    D[Dev en ventana<br/>de payments-api] --> A[Pide al agente:<br/>crea endpoint<br/>POST /refund]
+    A --> B{¿El agente sabe cómo<br/>lo consume el front?}
+    B -->|No| C[Dev salta a la<br/>ventana del frontend]
+    C --> E[Lee código del front<br/>o pregunta al agente<br/>de esa ventana]
+    E --> F[Copia la respuesta<br/>mentalmente o literal]
+    F --> G[Vuelve a la ventana<br/>de payments-api]
+    G --> H[Pega/explica al<br/>agente de payments]
+    H --> I[Agente implementa<br/>con info transcrita]
+    B -->|Arriesga| J[Agente implementa<br/>según suposición]
+    J --> K[Bug en QA —<br/>campo mal nombrado]
+
+    classDef dev fill:#e3f2fd,stroke:#1976d2,color:#333
+    classDef manual fill:#ffe5b3,stroke:#e17055,color:#333
+    classDef pain fill:#ffe5e5,stroke:#d63031,color:#333
+    class D dev
+    class C,E,F,G,H manual
+    class B,J,K pain
+```
+
+El dev **termina siendo el bus humano** entre sus propios agentes.
+
+### Después de refacil-bus — Escenario A: el otro agente está en `/refacil:attend`
+
+El caso ideal. El dev dejó el agente del otro repo en modo escucha antes de empezar a trabajar en el primero.
+
+```mermaid
+flowchart LR
+    D[Dev en ventana<br/>de payments-api] --> A[Pide al agente:<br/>crea /refund,<br/>pregúntale al bus<br/>si necesitás algo]
+    A --> B[Agente payments ejecuta<br/>/refacil:ask @frontend<br/>&quot;...&quot; --wait 180]
+    B --> C[Agente frontend<br/>en /refacil:attend<br/>recibe la pregunta]
+    C --> E[Agente frontend lee<br/>SUS propios archivos<br/>y responde con<br/>/refacil:reply]
+    E --> F[Agente payments recibe<br/>la respuesta automática<br/>y sigue implementando]
+    F --> G[Endpoint correcto<br/>al primer intento]
+
+    classDef dev fill:#e3f2fd,stroke:#1976d2,color:#333
+    classDef auto fill:#d4edda,stroke:#28a745,color:#333
+    class D dev
+    class A,B,C,E,F,G auto
+```
+
+**El dev nunca cambió de ventana**. Los dos agentes se hablaron entre sí; cada uno consultó su código real. El dev se enteró solo cuando el primer agente le dijo "listo, endpoint implementado con estos campos".
+
+### Después de refacil-bus — Escenario B: el otro agente NO está en attend
+
+Aún hay ganancia, pero el dev sí tendrá que ir a la otra ventana al menos una vez — aunque con menos esfuerzo que antes.
+
+```mermaid
+flowchart LR
+    D[Dev en ventana<br/>de payments-api] --> A[Pide al agente:<br/>pregúntale al front...]
+    A --> B[Agente payments ejecuta<br/>/refacil:ask @frontend &quot;...&quot;]
+    B --> C[Mensaje queda en inbox.jsonl<br/>de la sala]
+    C --> E[Dev, cuando pueda,<br/>va a la ventana frontend]
+    E --> F[Dice al agente frontend:<br/>&quot;ejecutá /refacil:inbox<br/>y respondé lo que haya&quot;]
+    F --> G[Agente frontend lee SUS<br/>archivos y responde con<br/>/refacil:reply]
+    G --> H[Dev vuelve a payments;<br/>agente payments hace<br/>/refacil:inbox y continúa]
+
+    classDef dev fill:#e3f2fd,stroke:#1976d2,color:#333
+    classDef semi fill:#fff3cd,stroke:#ffc107,color:#333
+    class D,E dev
+    class A,B,C,F,G,H semi
+```
+
+**Ganancia aún sin attend**: el dev sigue saltando, **pero NO hace de transcriptor**. El agente de cada repo responde desde su código real; el dev solo "despacha" el trabajo entre agentes. Mucho menos fricción que copiar respuestas a mano.
+
+> **Conclusión práctica**: la magia del "cero saltos de ventana" aparece cuando el dev, antes de meterse en una tarea profunda, pone los agentes de los otros repos que podría necesitar consultar en `/refacil:attend`. Sin eso, el bus sigue siendo útil — evita la transcripción manual — pero el dev sí visita las otras ventanas para "activar" al agente.
+
+---
+
+## 2. Arquitectura — qué corre dónde
+
+El broker es un proceso local mínimo que solo enruta texto plano entre sesiones. **No transfiere archivos, contexto ni tokens entre repos**. Todas las ventanas son del mismo dev — el broker conecta a sus agentes entre sí.
+
+```mermaid
+flowchart TB
+    subgraph DEV[Máquina del Dev]
+        subgraph V1[Ventana IDE 1]
+            IDE1[Claude Code / Cursor<br/>en repo payments-api<br/>agente: payments-api]
+        end
+
+        subgraph V2[Ventana IDE 2]
+            IDE2[Claude Code / Cursor<br/>en repo frontend<br/>agente: frontend]
+        end
+
+        subgraph V3[Ventana IDE 3 · opcional]
+            IDE3[Claude Code / Cursor<br/>en repo reports<br/>agente: reports]
+        end
+
+        subgraph T4[Terminal · opcional]
+            WATCH[refacil-sdd-ai bus view<br/>o bus watch<br/>0 tokens]
+        end
+
+        subgraph BROKER[Broker local · 127.0.0.1:7821]
+            WS[HTTP + WebSocket<br/>40 MB RAM · 0% CPU idle]
+            DISK[~/.refacil-sdd-ai/bus/&lt;sala&gt;/<br/>inbox.jsonl<br/>rotación 7 días]
+        end
+    end
+
+    IDE1 <-->|ws| WS
+    IDE2 <-->|ws| WS
+    IDE3 <-->|ws| WS
+    WATCH -.->|http + ws read-only| WS
+    WS <--> DISK
+
+    classDef local fill:#e3f2fd,stroke:#1976d2,color:#333
+    classDef ide fill:#f3e5f5,stroke:#7b1fa2,color:#333
+    class WS,DISK local
+    class IDE1,IDE2,IDE3,WATCH ide
+```
+
+### Propiedades importantes
+
+- **100% local**: nada sale de `127.0.0.1`. Sin internet, sin cuentas, sin servidor compartido.
+- **Zero config**: el broker se auto-arranca la primera vez que cualquier skill del bus lo necesita.
+- **Zero costo perceptible**: 40 MB RAM, 0% CPU cuando no hay tráfico.
+- **Persistente**: sobrevive reinicio del broker; mensajes quedan 7 días en disco.
+- **Portable**: las mismas skills funcionan idéntico en Claude Code y Cursor (no usa hooks específicos de un IDE).
+
+---
+
+## 3. Flujo automático agente ↔ agente (happy path)
+
+Caso de uso estrella: el dev está trabajando en un repo y sus otros agentes (en otras ventanas) responden solos cuando reciben preguntas vía el bus.
+
+> **Pre-requisito**: antes de arrancar la tarea, el dev fue a la ventana del otro repo y dijo *"atiende el bus"*. Eso pone al agente de esa ventana en `/refacil:attend`. Sin eso, el flujo cae al Escenario B (sección 3.2).
+
+### 3.1 Con attend activo — cero saltos de ventana
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant D as Dev<br/>(único)
+    participant AP as Agente<br/>payments
+    participant BR as Broker
+    participant AF as Agente<br/>frontend
+
+    Note over D,AF: Setup previo (1 vez):<br/>Dev fue a la ventana frontend y dijo "atiende el bus"
+    D->>AF: "atiende el bus<br/>mientras trabajo en otro repo"
+    AF->>BR: /refacil:attend (bloqueado)
+    Note over AF: Escuchando preguntas
+
+    Note over D,AP: Dev vuelve a la ventana payments y arranca la tarea
+    D->>AP: "crea /refund,<br/>si necesitás algo del front<br/>preguntale al bus"
+    AP->>BR: /refacil:ask @frontend<br/>"..." --wait 180
+    Note over AP: Bloqueado<br/>esperando respuesta
+
+    BR->>AF: Pregunta recibida<br/>(correlationId X)
+    AF->>AF: Read/Grep src/api/pay.ts
+    AF->>BR: /refacil:reply<br/>"cartId, amountRefunded,<br/>timestamp (camelCase)"
+    BR->>AP: Respuesta con<br/>correlationId X
+
+    AP->>D: Endpoint implementado<br/>con los campos correctos
+    AF->>BR: /refacil:attend<br/>(vuelve a escuchar)
+    Note over AF: Listo para la<br/>siguiente pregunta
+```
+
+**Leyendo el diagrama**: el Dev solo participa en los pasos 1, 4 y 12. Entre medio (pasos 5 al 11) los dos agentes se hablaron entre sí — el dev no cambió de ventana, no copió nada, no transcribió respuestas.
+
+### 3.2 Sin attend — el dev despacha manualmente pero NO transcribe
+
+Si el dev no dejó attend activo, la pregunta queda en inbox y él mismo tiene que ir a la otra ventana a "despachar" el trabajo al otro agente.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant D as Dev<br/>(único)
+    participant AP as Agente<br/>payments
+    participant BR as Broker
+    participant AF as Agente<br/>frontend
+
+    D->>AP: "pregúntale al front<br/>qué formato espera"
+    AP->>BR: /refacil:ask @frontend "..."
+    Note over AP: Pregunta enviada,<br/>sin bloqueo
+
+    Note over D: Dev salta a la<br/>ventana frontend
+
+    D->>AF: "ejecutá /refacil:inbox<br/>y respondé lo que haya"
+    AF->>BR: /refacil:inbox
+    BR->>AF: Hay 1 ask dirigido a vos
+    AF->>AF: Read/Grep src/api/pay.ts
+    AF->>BR: /refacil:reply "..."
+
+    Note over D: Dev vuelve a la<br/>ventana payments
+
+    D->>AP: "ejecutá /refacil:inbox<br/>y seguí con la tarea"
+    AP->>BR: /refacil:inbox
+    BR->>AP: Respuesta del frontend
+    AP->>D: Endpoint implementado
+```
+
+**Diferencia clave vs 3.1**: el Dev visita la ventana frontend una vez (pasos 3-4). **Pero no lee código, no copia, no transcribe** — solo dice "ejecutá inbox y respondé". El agente del repo hace el trabajo real. Aún así el attend previo es el patrón ideal.
+
+---
+
+## 4. Guía rápida: ¿qué skill uso?
+
+Para que el equipo sepa qué invocar en cada caso:
+
+```mermaid
+flowchart TD
+    START[Necesito algo<br/>del bus] --> Q1{¿Primera vez<br/>en la sala hoy?}
+    Q1 -->|Sí| JOIN[/refacil:join sala<br/>escribe el bloque en<br/>AGENTS.md si falta/]
+    Q1 -->|No| Q2{¿Qué quiero<br/>hacer?}
+
+    JOIN --> Q2
+
+    Q2 -->|Preguntar a alguien<br/>y esperar respuesta<br/>para continuar| ASKW[/refacil:ask @X<br/>&quot;...&quot; --wait 180/]
+    Q2 -->|Preguntar sin<br/>bloquear| ASK[/refacil:ask @X<br/>&quot;...&quot;/]
+    Q2 -->|Anunciar algo<br/>a toda la sala| SAY[/refacil:say &quot;...&quot;/]
+    Q2 -->|Responder<br/>pregunta que me hicieron| REPLY[/refacil:reply &quot;...&quot;/]
+    Q2 -->|Atender el bus<br/>un rato| ATTEND[/refacil:attend/]
+    Q2 -->|Ver mensajes<br/>que llegaron offline| INBOX[/refacil:inbox/]
+
+    classDef start fill:#fff3cd,stroke:#856404,color:#333
+    classDef skill fill:#cce5ff,stroke:#004085,color:#333
+    class START start
+    class JOIN,ASKW,ASK,SAY,REPLY,ATTEND,INBOX skill
+```
+
+---
+
+## 5. Impacto esperado
+
+Beneficios cualitativos para el dev que trabaja con múltiples repos. El impacto depende de si el agente del otro repo está o no en `/refacil:attend`:
+
+| Aspecto | Antes | Con bus · otro agente SIN attend | Con bus · otro agente EN attend |
+|---|---|---|---|
+| **Consulta cruzada** | Dev salta de ventana, lee código, copia al otro agente | Dev salta 1 vez y dice "ejecutá inbox y respondé" | Agente pregunta solo; otro agente responde solo |
+| **Calidad del contexto** | Transcripción manual del dev — se pierde precisión | Agente del repo dueño responde desde código real | Agente del repo dueño responde desde código real |
+| **Saltos de ventana del dev** | Muchos: salir, leer, copiar, volver, pegar | Uno solo por consulta, corto (despachar al agente) | Cero: el dev se entera al final del resultado |
+| **Ruptura del foco** | Alta: cada consulta interrumpe el flujo principal | Media: una interrupción liviana | Casi nula: todo ocurre en background |
+| **Trazabilidad** | Nada queda registrado | `inbox.jsonl` 7 días auditable | `inbox.jsonl` 7 días auditable |
+| **Bugs por transcripción** | Frecuentes (tipeo, campos mal copiados) | Eliminados — el agente copia literal | Eliminados |
+| **Revisión post-mortem** | Hay que reconstruir de memoria | Historial del bus muestra la conversación real | Historial del bus muestra la conversación real |
+
+**Lectura de la tabla**: con el bus siempre hay ganancia respecto al estado actual. La automatización **total** (columna derecha) requiere la disciplina de dejar en `/refacil:attend` los agentes de los repos que uno sabe que va a consultar antes de meterse en una tarea larga.
+
+### Impacto cuantitativo (estimar por equipo)
+
+Estos valores se deben **medir en producción del equipo** durante las primeras 2-4 semanas:
+
+- Número de preguntas/respuestas cruzadas por día (proxy: líneas en `inbox.jsonl`)
+- Reducción de reuniones técnicas ad-hoc para alinear contratos de APIs
+- Tiempo promedio hasta resolver una consulta cruzada (antes medido vs ahora)
+
+---
+
+## 6. Cómo empezar (5 minutos)
+
+```bash
+# 1. Actualiza refacil-sdd-ai a la última versión (automático si tienes Claude Code)
+npm update -g refacil-sdd-ai
+
+# 2. En cada repo donde quieras usar el bus:
+refacil-sdd-ai update    # re-copia skills (el hook lo hace solo en Claude Code)
+
+# 3. Reinicia la sesión de Claude Code o Cursor
+
+# 4. En el chat del LLM:
+/refacil:join refacil-main
+# La primera vez el LLM escribe un bloque de presentación en tu AGENTS.md
+# y te une a la sala
+```
+
+No requiere configurar puertos, servidores ni credenciales. El broker se levanta solo.
+
+---
+
+## 7. Puntos clave para el pitch al equipo
+
+- **Las sesiones son agentes de repo, no devs**: el caso principal es un dev con varias ventanas abiertas (una por repo), donde los agentes del LLM se hablan entre sí para que el dev no haga de transcriptor.
+- **El dev sigue siendo el "PM"** de la operación — decide qué tarea arrancar, a qué agentes poner en attend, y valida el resultado final. El bus solo quita el trabajo mecánico entre ventanas.
+- **No transfiere código ni secretos** entre repos: solo texto plano que el dev controla.
+- **Costo infraestructural cero**: local, sin servicio compartido, sin cuentas nuevas, 40 MB de RAM.
+- **Funciona en Claude Code y Cursor**: sin diferencias ni configuración adicional.
+- **Persistencia con expiración automática** (7 días) — no se llena el disco.
+- **Patrón óptimo**: antes de empezar una tarea que puede requerir consultar otros repos, el dev abre rápido las otras ventanas y dice *"atiende el bus"*. A partir de ahí, todo ocurre en background mientras trabaja.
+- **Fallback natural sin attend**: aunque el dev olvide el setup, el bus sigue sirviendo como canal asíncrono: el dev salta 1 vez, despacha al agente (*"ejecutá inbox y respondé"*) y vuelve. Mucho mejor que transcribir código a mano.
+
+---
+
+## Apéndice: comandos útiles para el dev
+
+```bash
+refacil-sdd-ai bus status              # ¿está activo el broker?
+refacil-sdd-ai bus rooms               # salas activas + miembros
+refacil-sdd-ai bus watch <session>     # panel en vivo (sin tokens)
+refacil-sdd-ai bus history --n 50      # últimos 50 mensajes de la sala actual
+refacil-sdd-ai bus leave               # salir de la sala
+refacil-sdd-ai bus stop                # bajar el broker (raro necesitarlo)
+```

package/skills/guide/SKILL.md

@@ -28,7 +28,8 @@ 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
+9. Migrar documentacion al patron actual → `/refacil:update`
+10. 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`.
 
@@ -67,7 +68,8 @@ Detalle completo en el README de refacil-sdd-ai (seccion `refacil-bus`).
   - Opcion 6 (Review de calidad) → `skill: "refacil:review"`
   - Opcion 7 (Subir codigo y crear PR) → `skill: "refacil:up-code"`
   - Opcion 8 (Configurar repo) → `skill: "refacil:setup"`
-  - Opcion 9 (Bus entre agentes) → `skill: "refacil:join"` (u otra del grupo `refacil:say`/`refacil:ask`/`refacil:reply`/`refacil:attend`/`refacil:inbox` segun la intencion expresada).
+  - Opcion 9 (Migrar documentacion) → `skill: "refacil:update"`
+  - Opcion 10 (Bus entre agentes) → `skill: "refacil:join"` (u otra del grupo `refacil:say`/`refacil:ask`/`refacil:reply`/`refacil:attend`/`refacil:inbox` segun la intencion expresada).
   - Si la intencion no mapea exactamente a una opcion, NO invocar — listar opciones numeradas y pedir seleccion explicita.
 
   No describirlo en texto ni esperar que el usuario escriba el comando. (Ver `METHODOLOGY-CONTRACT.md §5`.)

package/skills/setup/SKILL.md

@@ -40,35 +40,54 @@ openspec init --tools claude,cursor
 
 Si no existe, crear con `language: spanish` (y comentario de terminos tecnicos en ingles). Si existe, asegurar `language: spanish`.
 
-### Paso 6: Generar `AGENTS.md`
+### Paso 6: Generar `.agents/` y `AGENTS.md`
 
-Analiza el repo y genera `AGENTS.md` (espanol, terminos tecnicos en ingles). Si ya existe `AGENTS.md`, pregunta si regenerar.
+Analiza el repo y genera la estructura de documentacion. Si ya existen, pregunta si regenerar.
 
 **6.1 Analisis** — Lee si existen: `package.json`, `tsconfig*.json`, `nest-cli.json`, `angular.json`, `README.md`, eslint, jest, `ls` raiz, Docker, `.env.example`.
 
-**6.2 Estructura obligatoria del archivo**
+**6.2 Arquitectura obligatoria: carpeta `.agents/` + indice `AGENTS.md`**
 
-1. **Resumen para IA (primero, obligatorio)** — Lo que un asistente necesita en **como mucho ~120 lineas** (una pantalla):
-   - Titulo + descripcion breve (2-4 lineas)
-   - Tabla mini: lenguaje, framework, tests, package manager
-   - Scripts esenciales (build, test, lint) con una linea de proposito cada uno
-   - **Reglas criticas condensadas**: Siempre / Nunca / Preguntar (hasta ~5 bullets por bloque si aplica)
-   - Tabla **comandos refacil:*** (nombre + una frase; no copiar el README entero)
-   - Linea fija: *Detalle ampliado debajo. Si hay anexos en `docs/agents-*.md`, leerlos solo cuando trabajes en esa area.*
+Siempre genera esta estructura — nunca un archivo monolitico:
 
-2. **Detalle del proyecto** — Arquitectura, stack ampliado, alias, BD, testing extendido, comandos de desarrollo completos, reglas ampliadas.
+Crea la carpeta `.agents/` con un archivo `.md` por area tematica. Archivos tipicos (adaptar al proyecto real):
+- `.agents/summary.md` — descripcion breve, tabla (lenguaje, framework, tests, package manager), scripts esenciales con una frase, reglas criticas condensadas (Siempre / Nunca / Preguntar, max 5 bullets cada bloque).
+- `.agents/architecture.md` — modulos, servicios, flujos principales, patrones clave.
+- `.agents/stack.md` — dependencias, variables de entorno, bases de datos, integraciones.
+- `.agents/testing.md` — estrategia, comandos, convenciones, fixtures.
+- `.agents/commands.md` — comandos de desarrollo, alias, scripts de CI/CD.
 
-3. **Anexos (opcional)** — Si el detalle seria muy largo (>~250 lineas en una sola seccion), crear `docs/agents-architecture.md`, `docs/agents-testing.md`, etc., y en `AGENTS.md` dejar solo enlaces + cuando leer cada uno.
+Un monorepo puede agregar `.agents/services.md`; una libreria puede combinar testing en stack. Adaptar segun el proyecto.
 
-**6.3 Fallback** — Si el analisis falla, `AGENTS.md` minimo con: resumen corto + tabla refacil + TODOs + linea que invite a re-ejecutar setup; misma idea de resumen primero.
+`AGENTS.md` es el **indice puro** — no contiene detalle de proyecto, solo:
+1. Una linea de descripcion del proyecto.
+2. Por cada archivo en `.agents/`: nombre del area + enlace relativo + cuando leer ese archivo (una frase).
+3. Bloque `compact-guidance` (auto-gestionado por `refacil-sdd-ai`, no editar).
 
-**6.4** — Muestra el resultado; si el usuario aprueba, escribe en la raiz.
+**6.3 Fallback** — Si el analisis falla: crear `.agents/summary.md` con resumen minimo + tabla refacil + TODOs, y `AGENTS.md` como indice apuntando a ese unico archivo.
 
-**6.5 Eficiencia de tokens (hook + bloque auto-gestionado)**:
-- Explica al usuario que `refacil-sdd-ai` mantiene en `AGENTS.md` un bloque `compact-guidance` para reducir consumo de contexto.
-- Ese bloque se sincroniza automaticamente por el hook `check-update` en cada `SessionStart` (y tambien en `init`/`update`).
-- Si `AGENTS.md` aun no existe, la sincronizacion se omite sin error.
-- Indica que no debe editar manualmente el contenido entre marcadores `compact-guidance` porque se sobrescribe.
+**6.4** — Muestra el resultado al usuario; si aprueba, escribe los archivos.
+
+**6.5 Bloque compact-guidance**:
+- `refacil-sdd-ai` inyecta en `AGENTS.md` un bloque entre marcadores `compact-guidance` con reglas de salida compacta.
+- Se sincroniza automaticamente en cada `SessionStart`. No editar el contenido entre marcadores.
+
+### Paso 6b: Sobreescribir `CLAUDE.md` y `.cursorrules`
+
+Siempre **sobreescribe** ambos archivos aunque ya existan — son indices delgados hacia `AGENTS.md`, no deben contener detalle de proyecto.
+
+**`CLAUDE.md`** — indice minimo, sin contenido de proyecto:
+
+```
+# CLAUDE.md
+
+Contexto completo del proyecto: ver `AGENTS.md` (indice) y `.agents/` (detalle por area).
+Si `AGENTS.md` no existe, ejecuta `/refacil:setup`.
+```
+
+**`.cursorrules`** — contenido identico con header `# Cursor Rules`.
+
+Todo el detalle de proyecto, stack, reglas y comandos `refacil:*` vive en `.agents/` y se indexa desde `AGENTS.md`. No duplicar nada en CLAUDE.md ni en .cursorrules.
 
 ### Paso 7: Archivos de exclusion de contexto
 
@@ -92,7 +111,7 @@ Si el usuario quiere personalizar exclusiones adicionales, puede editarlos direc
 
 ```
 === refacil:setup completado ===
- Node.js / OpenSpec / perfil / openspec/ / config / AGENTS.md / .claudeignore / .cursorignore / skills OK
+ Node.js / OpenSpec / perfil / openspec/ / config / AGENTS.md / CLAUDE.md / .cursorrules / .claudeignore / .cursorignore / skills OK
 
  Reiniciar sesion Claude Code o Cursor si es la primera instalacion de skills.
  El siguiente paso es revisar el flujo disponible.

package/skills/update/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: refacil:update
+description: Detectar y aplicar migraciones pendientes de la metodologia SDD-AI al proyecto actual
+user-invocable: true
+---
+
+# refacil:update — Migraciones de la Metodologia
+
+Detecta el estado actual del repo y aplica solo lo que este pendiente. No repite pasos de instalacion (OpenSpec, hooks, skills).
+
+## Paso 1: Detectar migraciones pendientes
+
+Evalua cada condicion y marca si aplica:
+
+| # | Condicion detectada | Migracion |
+|---|---|---|
+| 1 | `AGENTS.md` existe y no existe carpeta `.agents/` | Reestructurar en `.agents/` + reescribir como indice |
+| 2 | `CLAUDE.md` tiene mas de 5 lineas o no apunta a `AGENTS.md` | Reemplazar por indice minimo |
+| 3 | `.cursorrules` tiene mas de 5 lineas o no apunta a `AGENTS.md` | Reemplazar por indice minimo |
+
+Si ninguna condicion aplica: informar al usuario que todo esta al dia y salir sin cambios.
+
+## Paso 2: Confirmar con el usuario
+
+Mostrar la lista de migraciones detectadas y pedir confirmacion antes de aplicar cualquier cambio.
+
+## Paso 3: Aplicar migraciones confirmadas
+
+Ejecutar solo las migraciones marcadas en el Paso 1.
+
+### Migracion 1 — AGENTS.md → `.agents/` + indice
+
+1. Lee el contenido completo de `AGENTS.md`.
+2. Identifica y separa los **bloques gestionados** — NO deben moverse a `.agents/`:
+   - Bloque `compact-guidance`: entre `<!-- refacil-sdd-ai:compact-guidance:start -->` y `<!-- refacil-sdd-ai:compact-guidance:end -->`
+   - Bloque de presentacion del bus: entre `<!-- refacil-bus:presentation:start -->` y `<!-- refacil-bus:presentation:end -->`
+3. Crea la carpeta `.agents/`.
+4. Distribuye el contenido de proyecto (todo excepto los bloques gestionados) en archivos por area. Reglas:
+   - **`.agents/summary.md` es siempre obligatorio** — descripcion del proyecto, tabla mini de stack, scripts esenciales, reglas criticas condensadas. Si el AGENTS.md original no tiene resumen claro, sintetizalo a partir del contenido disponible.
+   - Los demas archivos se crean **solo si hay contenido relevante que redistribuir**. No crear archivos vacios:
+     - `.agents/architecture.md` — modulos, servicios, flujos principales, patrones clave.
+     - `.agents/stack.md` — dependencias, variables de entorno, bases de datos, integraciones.
+     - `.agents/testing.md` — estrategia de tests, comandos, convenciones, fixtures.
+     - `.agents/commands.md` — comandos de desarrollo, alias, scripts de CI/CD.
+   - Adaptar al tipo de proyecto: un monorepo puede necesitar `.agents/services.md`; una libreria simple puede combinar testing y stack en un solo archivo. Usar el mismo criterio que `/refacil:setup`.
+5. Reescribe `AGENTS.md` como indice puro preservando los bloques gestionados al final:
+   - Primera linea: descripcion breve del proyecto.
+   - Por cada archivo en `.agents/`: nombre del area + enlace relativo + cuando leerlo (una frase).
+   - Bloques gestionados que ya existian (compact-guidance, bus presentation) al final, intactos.
+   - Si no existian, el bloque compact-guidance se re-inyectara automaticamente en el proximo SessionStart.
+
+### Migracion 2 y 3 — CLAUDE.md / .cursorrules → indice minimo
+
+Sobreescribir con exactamente este contenido:
+
+**CLAUDE.md:**
+```
+# CLAUDE.md
+
+Contexto completo del proyecto: ver `AGENTS.md`.
+Si no existe, ejecuta `/refacil:setup`.
+```
+
+**`.cursorrules`:**
+```
+# Cursor Rules
+
+Contexto completo del proyecto: ver `AGENTS.md`.
+Si no existe, ejecuta `/refacil:setup`.
+```
+
+## Paso 4: Resumen
+
+Informar que archivos se crearon o modificaron. Mencionar que el bloque `compact-guidance` se sincronizara automaticamente en el proximo SessionStart.
+
+## Reglas
+
+- Solo aplica lo que este pendiente — no toca archivos que ya cumplen el patron.
+- No inventa contenido: distribuye lo que ya existe en AGENTS.md sin agregar ni eliminar informacion.
+- No ejecuta pasos de OpenSpec, hooks ni instalacion de skills.
+- Extensible: futuras versiones de la metodologia agregaran filas a la tabla del Paso 1 sin cambiar la estructura de la skill.

package/templates/methodology-guide.md

@@ -1,45 +1,52 @@
-Instrucciones completas del proyecto: ver `AGENTS.md`. Si falta, ejecuta `/refacil:setup`.
-
-## Metodologia SDD-AI (Refacil)
-
-Skills identicas en `.claude/skills/refacil-*/` (Claude Code) y `.cursor/skills/refacil-*/` (Cursor). Instaladas por `refacil-sdd-ai init`.
-
-| Comando | Descripcion |
-|---------|-------------|
-| `/refacil:setup` | Instalar OpenSpec y generar AGENTS.md |
-| `/refacil:guide` | Guia interactiva — que comando usar |
-| `/refacil:explore` | Explorar el codebase sin cambios |
-| `/refacil:propose` | Crear propuesta de cambio |
-| `/refacil:apply` | Implementar tasks del cambio |
-| `/refacil:test` | Generar tests unitarios |
-| `/refacil:verify` | Validar implementacion vs specs |
-| `/refacil:review` | Review con checklist de calidad |
-| `/refacil:archive` | Archivar cambio completado |
-| `/refacil:up-code` | Subir codigo y crear PR |
-| `/refacil:bug` | Flujo guiado de bugfix |
-
-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`.
-- El bloque define reglas de salida compacta (lectura por rango, busqueda acotada, tests/logs resumidos).
-- Si `AGENTS.md` aun no existe, la sincronizacion se omite sin error.
-- No editar manualmente el contenido entre marcadores `compact-guidance`; se sobreescribe automaticamente.
+Instrucciones completas del proyecto: ver `AGENTS.md`. Si falta, ejecuta `/refacil:setup`.
+
+## Metodologia SDD-AI (Refacil)
+
+Skills identicas en `.claude/skills/refacil-*/` (Claude Code) y `.cursor/skills/refacil-*/` (Cursor). Instaladas por `refacil-sdd-ai init`.
+
+| Comando | Descripcion |
+|---------|-------------|
+| `/refacil:setup` | Instalar OpenSpec y generar AGENTS.md |
+| `/refacil:guide` | Guia interactiva — que comando usar |
+| `/refacil:explore` | Explorar el codebase sin cambios |
+| `/refacil:propose` | Crear propuesta de cambio |
+| `/refacil:apply` | Implementar tasks del cambio |
+| `/refacil:test` | Generar tests unitarios |
+| `/refacil:verify` | Validar implementacion vs specs |
+| `/refacil:review` | Review con checklist de calidad |
+| `/refacil:archive` | Archivar cambio completado |
+| `/refacil:up-code` | Subir codigo y crear PR |
+| `/refacil:bug` | Flujo guiado de bugfix |
+| `/refacil:update` | Migrar documentacion al patron actual (.agents/) |
+
+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.
+
+## Estructura de documentacion del proyecto
+
+El detalle del proyecto vive en `.agents/` — un archivo `.md` por area (summary, architecture, stack, testing, commands...).
+`AGENTS.md` es el indice: una linea por archivo indicando que contiene y cuando leerlo.
+`CLAUDE.md` y `.cursorrules` son indices minimos que solo apuntan a `AGENTS.md` — no contienen detalle de proyecto.
+
+## Eficiencia de tokens (automatica)
+
+- El hook `check-update` en `SessionStart` sincroniza el bloque `compact-guidance` en `AGENTS.md`.
+- El bloque define reglas de salida compacta (lectura por rango, busqueda acotada, tests/logs resumidos).
+- Si `AGENTS.md` aun no existe, la sincronizacion se omite sin error.
+- No editar manualmente el contenido entre marcadores `compact-guidance`; se sobreescribe automaticamente.