refacil-sdd-ai 4.2.4 → 4.4.0

package/skills/archive/SKILL.md

@@ -1,106 +1,109 @@
 ---
 name: refacil:archive
-description: Archivar un cambio completado — mueve artefactos a archive y sincroniza specs
+description: Archive a completed change — move artifacts to archive and sync specs
 user-invocable: true
 ---
 
-# refacil:archive — Archivar Cambio Completado
+# refacil:archive — Archive Completed Change
 
-Este comando envuelve la funcionalidad de OpenSpec archive (que internamente llama a sync-specs) y agrega verificaciones previas del equipo.
+This command archives completed SDD changes (bug fixes manually, regular changes via `refacil-sdd-ai sdd archive`), syncs `refacil-sdd/specs/`, and enforces team pre-verification checks.
 
-**Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
+**Prerequisites**: `sdd` profile from `refacil-prereqs/SKILL.md` + rules from `METHODOLOGY-CONTRACT.md`.
 
-## Instrucciones
+## Instructions
 
-### Paso 1: Verificaciones previas (aporte Refacil)
+### Step 1: Pre-verification checks
 
-Antes de archivar, verifica que el cambio esta realmente completo:
+Before archiving, run `refacil-sdd-ai sdd status <changeName> --json` and parse the JSON to get the change status.
 
-1. **Tasks completadas**: Busca el `tasks.md` del cambio y verifica que todas las tasks tienen checkbox marcado (`[x]`). Si hay tasks sin completar, informa al usuario y pregunta si quiere continuar de todas formas.
+Verify the change is truly complete:
 
-2. **Tests pasan**: Resuelve y ejecuta el comando de tests segun `refacil-prereqs/METHODOLOGY-CONTRACT.md`. Si hay tests que fallan, informa y pregunta si quiere continuar.
+1. **Tasks completed**: Use the `tasksProgress` (or `tasks`) field from the JSON — verify that `tasks.pending === 0`. If there are incomplete tasks, inform the user and ask if they want to continue anyway.
 
-3. **Sin archivos pendientes**: Ejecuta `git status` y verifica si hay cambios sin commitear relacionados al feature. Si los hay, sugiere hacer commit antes de archivar.
+2. **Tests pass**: Resolve and run the test command according to `refacil-prereqs/METHODOLOGY-CONTRACT.md`. If there are failing tests, inform and ask if they want to continue.
 
-4. **Review aprobado (bloqueante)**: Verifica que existe el archivo `.review-passed` en la carpeta del cambio (`openspec/changes/[nombre-cambio]/.review-passed`) siguiendo **`METHODOLOGY-CONTRACT.md` §8** (dotfile; no concluyas por listados sin dotfiles). Si NO existe, **detener el archivado** e informar al usuario:
+3. **No pending files**: Run `git status` and verify if there are uncommitted changes related to the feature. If there are, suggest committing before archiving.
+
+4. **Review approved (blocking)**: Verify that the `.review-passed` file exists in the change folder (`refacil-sdd/changes/[change-name]/.review-passed`) following **`METHODOLOGY-CONTRACT.md` §8** (dotfile; do not conclude by listings without dotfiles). If it does NOT exist, **stop the archiving** and inform the user:
    ```
-   No se puede archivar: el cambio no tiene review aprobado.
-   Ejecuta /refacil:review primero.
+   Cannot archive: the change does not have an approved review.
+   Run /refacil:review first.
    ```
-   Esta verificacion es **obligatoria y bloqueante** — no se puede saltar.
+   This verification is **mandatory and blocking** — it cannot be skipped.
 
-Si alguna de las verificaciones 1-3 falla, informa al usuario pero permite que decida si continuar.
-Si la verificacion 4 falla, el archivado no puede continuar.
+If any of checks 1-3 fail, inform the user but allow them to decide whether to continue.
+If check 4 fails, archiving cannot continue.
 
-### Paso 1.5: Solicitar links de Jira (trazabilidad — obligatorio)
+### Step 1.5: Request Jira links (traceability — mandatory)
 
-Antes de proceder al archivado, solicita al usuario los links de Jira asociados al cambio:
+Before proceeding to archiving, ask the user for the Jira links associated with the change:
 
 ```
-Link de Jira asociado a este cambio (si son varios, sepáralos con comas):
+Jira link(s) associated with this change (if multiple, separate with commas):
 ```
 
-**Reglas:**
-- El usuario puede ingresar uno o múltiples links separados por comas en un solo mensaje.
-- Si el usuario no proporciona ningún link (responde vacío, "n", "no", "ninguno", Enter en blanco), **bloquear el archivado** y volver a solicitar:
+**Rules:**
+- The user may enter one or multiple links separated by commas in a single message.
+- If the user provides no link (answers empty, "n", "no", "none", blank Enter), **block the archiving** and ask again:
   ```
-  No se puede archivar sin al menos un link de Jira.
-  Proporciona el link de la tarea que originó este cambio para continuar.
+  Cannot archive without at least one Jira link.
+  Provide the link to the task that originated this change to continue.
   ```
-- Repetir hasta recibir al menos una URL válida.
-- Guardar los links en `jiraTasks` para usarlos al escribir `review.yaml` en los pasos siguientes.
+- Repeat until at least one valid URL is received.
+- Save the links in `jiraTasks` to use when writing `review.yaml` in the following steps.
+
+### Step 2: Determine change type
 
-### Paso 2: Determinar tipo de cambio
+Inspect the change folder in `refacil-sdd/changes/`:
 
-Inspecciona la carpeta del cambio en `openspec/changes/`:
+- **It is a bug fix** if the folder name starts with `fix-` (created by `refacil:bug`).
+- **It is a regular change** in any other case (created by `refacil:propose`).
 
-- **Es un bug fix** si el nombre de la carpeta empieza con `fix-` (creado por `refacil:bug`).
-- **Es un cambio regular** en cualquier otro caso (creado por `refacil:propose`).
+Depending on the type, follow the corresponding step:
 
-Segun el tipo, sigue el paso correspondiente:
+### Step 2A: Bug fix → Manual archiving (no `sdd archive` CLI)
 
-### Paso 2A: Bug fix → Archivado manual (sin OpenSpec)
+Bug fixes only contain `summary.md` (and optionally `.review-passed`); they are not full proposal/spec/design/task trees. Archive them with **git mv** / **mv** per the steps below — **do not** use `refacil-sdd-ai sdd archive` for these folders.
 
-Los bug fixes solo contienen `summary.md` (y opcionalmente `.review-passed`), no tienen los artefactos completos que OpenSpec espera. Por eso se archivan **sin delegar a OpenSpec**.
+0. **Delete memory.yaml if present** (CA-18): run `rm -f "refacil-sdd/changes/[fix-name]/memory.yaml"` before moving the folder.
 
-1. **Mover a archive (operacion de move, no copy)**: traslada la carpeta completa del fix desde `openspec/changes/[nombre-fix]/` a `openspec/changes/archive/[fecha-ISO]-[nombre-fix]/`. La carpeta de origen **debe quedar eliminada** al finalizar.
+1. **Move to archive (move operation, not copy)**: transfer the full fix folder from `refacil-sdd/changes/[fix-name]/` to `refacil-sdd/changes/archive/[ISO-date]-[fix-name]/`. The source folder **must be eliminated** when done.
 
-   Orden de ejecucion recomendado (determinista y cross-platform):
-   1. Asegurar que existe el directorio `openspec/changes/archive/` (crearlo si no existe).
-   2. Preferir un **move atomico** con `git mv "openspec/changes/[nombre-fix]" "openspec/changes/archive/[fecha-ISO]-[nombre-fix]"` cuando el fix ya esta bajo control de git (mueve y stagea de una).
-   3. Si `git mv` no aplica (archivos no trackeados o error), usar en su lugar:
-      - Linux/macOS: `mv "openspec/changes/[nombre-fix]" "openspec/changes/archive/[fecha-ISO]-[nombre-fix]"`
-      - Windows (bash de Claude Code): el mismo `mv` funciona sobre rutas POSIX (`/c/Users/...`). **No usar `cp -r` sin el `rm -rf` posterior** — es la causa raiz tipica del bug en que la carpeta de origen sobrevive.
-   4. **Verificacion obligatoria post-move**: ejecutar una listado/test de existencia para confirmar que:
-      - `openspec/changes/[nombre-fix]/` **ya NO existe**.
-      - `openspec/changes/archive/[fecha-ISO]-[nombre-fix]/` **SI existe** y contiene `summary.md` (+ `.review-passed` si lo habia).
-   5. Si la verificacion falla (la carpeta de origen sobrevivio), eliminarla explicitamente con `rm -rf "openspec/changes/[nombre-fix]"` y re-verificar. No continuar al paso 2 hasta que el estado sea consistente.
+   Recommended execution order (deterministic and cross-platform):
+   1. Ensure the `refacil-sdd/changes/archive/` directory exists (create if not present).
+   2. Prefer an **atomic move** with `git mv "refacil-sdd/changes/[fix-name]" "refacil-sdd/changes/archive/[ISO-date]-[fix-name]"` when the fix is already under git control (moves and stages at once).
+   3. If `git mv` does not apply (untracked files or error), use instead:
+      - Linux/macOS/Windows: `mv "refacil-sdd/changes/[fix-name]" "refacil-sdd/changes/archive/[ISO-date]-[fix-name]"`. Always use `mv` (not `cp -r`) — verify source no longer exists after the move.
+   4. **Mandatory post-move verification**: run a listing/existence test to confirm:
+      - `refacil-sdd/changes/[fix-name]/` **no longer exists**.
+      - `refacil-sdd/changes/archive/[ISO-date]-[fix-name]/` **does exist** and contains `summary.md` (+ `.review-passed` if it existed).
+   5. If the verification fails (source folder survived), explicitly delete it with `rm -rf "refacil-sdd/changes/[fix-name]"` and re-verify. Do not continue to step 2 until the state is consistent.
 
-2. **Documentar en specs**: Lee el `summary.md` y el `.review-passed` del fix (desde la ruta **archivada** en `openspec/changes/archive/[fecha-ISO]-[nombre-fix]/`, ya no desde la ruta original), y crea un spec individual para el bug en `openspec/specs/[nombre-descriptivo]/spec.md`.
+2. **Document in specs**: Read the `summary.md` and `.review-passed` from the fix (from the **archived** path at `refacil-sdd/changes/archive/[ISO-date]-[fix-name]/`, no longer from the original path), and create an individual spec for the bug at `refacil-sdd/specs/[descriptive-name]/spec.md`.
 
-   **Nombre de la carpeta en specs**: Usa una descripcion corta y clara del bug en kebab-case (ej. `fix-session-timeout-redis`, `fix-null-pointer-payment-callback`). **NO uses IDs de tickets** (REF-123, JIRA-456, etc.) — el nombre debe ser descriptivo para que `/refacil:explore` pueda encontrar y entender el fix sin contexto externo.
+   **Spec folder name**: Use a short, clear kebab-case description of the bug (e.g. `fix-session-timeout-redis`, `fix-null-pointer-payment-callback`). **Do NOT use ticket IDs** (REF-123, JIRA-456, etc.) — the name must be descriptive so `/refacil:explore` can find and understand the fix without external context.
 
-   Contenido del `spec.md` (formato OpenSpec estandar):
+   Content of `spec.md` (Refacil SDD spec layout):
    ```markdown
-   # [nombre-descriptivo] Specification
+   # [descriptive-name] Specification
 
    ## Purpose
-   Corregir [descripcion clara del bug] para restaurar el comportamiento esperado sin introducir regresiones.
+   Fix [clear bug description] to restore expected behavior without introducing regressions.
 
    ## Requirements
-   ### Requirement: [comportamiento esperado principal]
-   El sistema SHALL [comportamiento correcto despues del fix].
+   ### Requirement: [main expected behavior]
+   The system SHALL [correct behavior after the fix].
 
-   #### Scenario: Bug corregido en condicion original
-   - **WHEN** [condicion que antes fallaba]
-   - **THEN** el sistema SHALL [resultado esperado]
+   #### Scenario: Bug fixed in original condition
+   - **WHEN** [condition that previously failed]
+   - **THEN** the system SHALL [expected result]
 
-   #### Scenario: Flujo normal permanece estable
-   - **WHEN** [condicion normal]
-   - **THEN** el sistema SHALL [comportamiento normal sin regresion]
+   #### Scenario: Normal flow remains stable
+   - **WHEN** [normal condition]
+   - **THEN** the system SHALL [normal behavior without regression]
    ```
 
-3. **Persistir metadata de review separada**: crea `openspec/specs/[nombre-descriptivo]/review.yaml` con los campos de `.review-passed` más los links de Jira del Paso 1.5:
+3. **Persist review metadata separately**: create `refacil-sdd/specs/[descriptive-name]/review.yaml` with the fields from `.review-passed` plus the Jira links from Step 1.5:
    ```yaml
    verdict: APROBADO|APROBADO CON OBSERVACIONES
    date: 2026-04-10T00:00:00.000Z
@@ -109,83 +112,78 @@ Los bug fixes solo contienen `summary.md` (y opcionalmente `.review-passed`), no
    failCount: 0
    blockers: false
    jiraTasks:
-     - https://tu-empresa.atlassian.net/browse/REF-123
+     - https://your-company.atlassian.net/browse/REF-123
    ```
 
-4. Continua al **Paso 3**.
+4. Continue to **Step 3**.
 
-### Paso 2B: Cambio regular → Delegar a OpenSpec archive
+### Step 2B: Regular change → Archive with native CLI
 
-1. Lee `openspec-archive-change/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
-2. Lee `OPENSPEC-DELTAS.md` en `refacil-prereqs` (seccion **archive**).
-3. Sigue OpenSpec con argumento **$ARGUMENTS** (sync de specs segun deltas).
+The spec and review evidence are written **before** running the CLI archive command, while the artifacts are still at their original paths. The CLI only moves the folder — it never syncs specs.
 
-4. **Verificar sincronizacion**: Despues de que OpenSpec archive, verifica que `openspec/specs/` fue actualizada:
-   - Revisa si hay archivos nuevos o modificados en `openspec/specs/`
-   - Si la sincronizacion no ocurrio (OpenSpec la salto o fallo), ejecuta manualmente:
-     - Lee la especificacion del cambio archivado: `specs.md` si existe **y** todos los `.md` bajo `specs/` de esa carpeta (misma regla que `refacil:apply`)
-     - Busca el spec principal relevante en `openspec/specs/`
-     - Si existe, integra los cambios (ADDED → agregar, MODIFIED → actualizar, REMOVED → eliminar)
-     - Si NO existe, crea un spec principal nuevo con nombre descriptivo
+1. **Sync spec to `refacil-sdd/specs/` (before archiving)**:
+   - Read `refacil-sdd/changes/<changeName>/specs.md` (and all `.md` under `specs/` if that subfolder exists).
+   - Determine the spec folder name: use `<changeName>` unless a more descriptive name is clearly better.
+   - If `refacil-sdd/specs/<specName>/spec.md` already exists, integrate the changes (ADDED → add, MODIFIED → update, REMOVED → delete sections).
+   - If it does NOT exist, create `refacil-sdd/specs/<specName>/spec.md` with the content derived from `specs.md` (convert acceptance/rejection criteria into Requirements + Scenarios format).
 
-5. **Persistir evidencia de review en specs (obligatorio)**:
-   - Lee `openspec/changes/[nombre-cambio]/.review-passed` **antes** de mover/archivar (o desde la ruta archivada si ya fue movido).
-   - Toma sus campos (`verdict`, `date`, `summary`, `failCount`, `blockers`, `changeName`).
-   - Crea/actualiza `review.yaml` en cada carpeta de spec afectada (`openspec/specs/<spec-name>/review.yaml`).
-   - Formato de `review.yaml` (incluye `jiraTasks` del Paso 1.5):
+2. **Persist review evidence (before archiving)**:
+   - Read `refacil-sdd/changes/<changeName>/.review-passed` (dotfile — use `ls -la` or read by explicit path, not directory listing).
+   - Create/update `refacil-sdd/specs/<specName>/review.yaml` with its fields plus `jiraTasks` from Step 1.5:
      ```yaml
      verdict: APROBADO|APROBADO CON OBSERVACIONES
      date: 2026-04-10T00:00:00.000Z
-     changeName: nombre-del-cambio
+     changeName: change-name
      summary: "..."
      failCount: 0
      blockers: false
      jiraTasks:
-       - https://tu-empresa.atlassian.net/browse/REF-123
-       - https://tu-empresa.atlassian.net/browse/REF-124
+       - https://your-company.atlassian.net/browse/REF-123
      ```
-   - Si el cambio sincroniza multiples specs, crea/actualiza `review.yaml` en cada una con los mismos `jiraTasks`.
-   - Si el `review.yaml` ya existe, agregar/actualizar solo `jiraTasks` sin eliminar los demás campos.
-   - Si no se puede determinar con precision los specs afectados, crea/actualiza `openspec/specs/review-metadata.yaml` con un registro por cambio.
+   - If `review.yaml` already exists, update only the fields that changed without removing others.
+
+3. **Delete memory.yaml if present** (CA-18): before running the CLI archive, delete `refacil-sdd/changes/<changeName>/memory.yaml` if it exists — run `rm -f "refacil-sdd/changes/<changeName>/memory.yaml"`. This is part of the archive cleanup.
+
+4. **Run the CLI archive**: `refacil-sdd-ai sdd archive <changeName>` — this moves the change to `refacil-sdd/changes/archive/<date>-<changeName>/`.
+5. Verify the command completed successfully (exit 0) and the original folder no longer exists.
 
-6. Continua al **Paso 3**.
+6. Continue to **Step 3**.
 
-El objetivo es que `openspec/specs/` documente como funciona el sistema HOY.
+The goal is for `refacil-sdd/specs/` to document how the system works TODAY.
 
-### Paso 3: Confirmar
+### Step 3: Confirm
 
-Antes de mostrar el resumen, ejecutar una **verificacion final de limpieza** (aplica tanto a bug fixes como a cambios regulares):
+Before showing the summary, run a **final cleanup verification** (applies to both bug fixes and regular changes):
 
-- `openspec/changes/[nombre-original]/` **NO debe existir** (solo la version archivada debe sobrevivir en `openspec/changes/archive/...`).
-- Si la carpeta de origen sobrevivio por cualquier razon (fallo del move, OpenSpec dejo residuos, copia en vez de mover), eliminarla explicitamente con `rm -rf "openspec/changes/[nombre-original]"` antes de confirmar al usuario.
+- `refacil-sdd/changes/[original-name]/` **must NOT exist** (only the archived version must survive in `refacil-sdd/changes/archive/...`).
+- If the source folder survived for any reason (failed move, partial copy, interrupted move), explicitly delete it with `rm -rf "refacil-sdd/changes/[original-name]"` before confirming to the user.
 
 ```
-=== Cambio archivado ===
- Cambio: [nombre]
- Tipo: [Bug fix | Cambio regular]
- Ubicacion: openspec/changes/archive/[fecha]-[nombre]/
- Carpeta original eliminada: SI
- Specs sincronizadas: SI
+=== Change archived ===
+ Change: [name]
+ Type: [Bug fix | Regular change]
+ Location: refacil-sdd/changes/archive/[date]-[name]/
+ Original folder deleted: YES
+ Specs synced: YES
  Tests: PASS
 
- El cambio ha sido completado y archivado exitosamente.
+ The change has been completed and archived successfully.
 ```
 
-### Paso 4: Recomendar subir codigo
+### Step 4: Recommend pushing the code
 
-Despues de confirmar el archivado, recomienda al usuario subir los cambios al remoto:
+After confirming the archiving, recommend the user push the changes to the remote:
 
 ```
-El siguiente paso es subir el cambio y crear el PR.
-Quieres que continue con /refacil:up-code?
+The next step is to push the change and create the PR.
+Do you want me to continue with /refacil:up-code?
 ```
 
-## Reglas
+## Rules
 
-- Siempre verificar completitud antes de archivar
-- **Continuidad del flujo**: si el usuario confirma afirmativamente ("si", "ok", "dale", "continua", etc.) la pregunta de continuidad del Paso 4, invocar inmediatamente el **Skill tool** con `skill: "refacil:up-code"`. No describirlo en texto ni esperar que el usuario escriba `/refacil:up-code`. (Ver `METHODOLOGY-CONTRACT.md §5`.)
-- La sincronizacion de specs es OBLIGATORIA en la metodologia Refacil
-- La metadata de `.review-passed` debe persistirse separada en YAML (`review.yaml`) dentro de cada carpeta de spec
-- No eliminar artefactos, solo moverlos a archive/ para trazabilidad
-- **La carpeta original en `openspec/changes/[nombre]/` NO debe sobrevivir al archivado** — ni para bug fixes (Paso 2A) ni para cambios regulares (Paso 2B). Usar `git mv` o `mv` (no `cp -r`) y verificar explicitamente. Si queda residuo, borrarlo con `rm -rf` antes del Paso 3.
-- Usa modo de salida **conciso** por defecto y **detallado** solo si el usuario lo pide (ver `METHODOLOGY-CONTRACT.md`)
+- Always verify completeness before archiving
+- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question in Step 4, immediately invoke the **Skill tool** with `skill: "refacil:up-code"`. Do not describe it in text or wait for the user to type `/refacil:up-code`. (See `METHODOLOGY-CONTRACT.md §5`.)
+- Spec synchronization is MANDATORY in the Refacil methodology
+- The `.review-passed` metadata must be persisted separately in YAML (`review.yaml`) inside each spec folder
+- Do not delete artifacts, only move them to archive/ for traceability
+- **The original folder in `refacil-sdd/changes/[name]/` must NOT survive archiving** — neither for bug fixes (Step 2A) nor for regular changes (Step 2B). Use `git mv` or `mv` (not `cp -r`) and verify explicitly. If residue remains, delete it with `rm -rf` before Step 3.

package/skills/ask/SKILL.md

@@ -1,78 +1,78 @@
----
-name: refacil:ask
-description: Preguntar algo dirigido a otra sesión del bus. Opcionalmente bloquea esperando la respuesta (--wait N segundos) para flujo automático LLM a LLM.
-user-invocable: true
----
-
-# refacil:ask — Pregunta dirigida a otra sesión
-
-Envía una pregunta dirigida a una sesión de la sala, o a **todas las demás** sesiones de la sala con `@all` (alias: `*`, `everyone`). **$ARGUMENTS** incluye `@<destino>` y el texto.
-
-## Instrucciones
-
-### Paso 1: Identificar destino y texto
-
-Formato esperado de $ARGUMENTS:
-```
-@<nombre-sesion> "pregunta..."
-```
-
-Extrae:
-- `destino`: nombre de sesión sin el `@`
-- `texto`: la pregunta
-
-Si el destino no es claro, usa `/refacil:rooms` (vía `refacil-sdd-ai bus rooms`) para listar sesiones activas y pide aclaración al usuario.
-
-**Broadcast dirigido (`@all`)**: el broker emite un `ask` por cada miembro (excepto quien pregunta), mismo `correlationId`. Cada receptor puede `/refacil:reply` por su lado. Con `--wait`, el CLI sigue devolviendo **la primera** respuesta que llegue (no espera a todos).
-
-### Paso 1.5: Pregunta informativa vs. solicitud de cambio (en el repo destino)
-
-Quien está en la sala llegó con **`/refacil:join`** (y el repo con metodologia Refacil): **ya conoce SDD-AI**; **no** hace falta pegar en el `ask` la guía ni explicar de nuevo qué es `/refacil:propose`. Basta con que el mensaje sea **claro en alcance y criterios** para que el otro agente ejecute **su** flujo (`propose`, `apply`, etc.) sin improvisar parches.
-
-Antes de redactar el `--text`, clasifica lo que vas a pedir a `@<destino>`:
-
-| Tipo | Ejemplos | Cómo redactar el `ask` |
-|------|----------|-------------------------|
-| **Solo información** | "¿Qué payload envía Z?", "¿Dónde está el handler de X?" | Pregunta concreta. |
-| **Solicitud de cambio** en el **repo del destino** | "Agregá campo W al contrato", "Corregí el bug en el servicio que vive en tu repo", "Alineá el consumer con la spec" | Describe **qué** hay que lograr, **dónde** aplica, criterios de aceptación o enlaces a spec/conversación. El destinatario canaliza eso con **`/refacil:propose`** (y lo que siga) en **su** repo; no pidas "solo un cambio rápido" opaco cuando el impacto es código versionable, salvo orden **explícita** del usuario humano en contrario. |
-
-Si mezclas consulta + cambio, separa en dos mensajes o deja claro qué parte es solo lectura y qué parte es trabajo versionable en el otro repo.
-
-### Paso 2: Decidir si usar `--wait`
-
-Dos modos:
-
-**Modo bloqueante (recomendado cuando necesitas la respuesta para continuar)**:
-```bash
-refacil-sdd-ai bus ask --to <destino> --text "<pregunta>" --wait 180
-```
-- El CLI bloquea hasta recibir la respuesta o pasar el timeout (default sugerido: 60-180s)
-- Si el otro lado está en `/refacil:attend`, la respuesta vuelve automáticamente
-- Si llega la respuesta: el CLI la imprime y puedes continuar con esa info
-- Si hay timeout: avisa al usuario y sugiere `/refacil:inbox` más tarde
-
-**Modo fire-and-forget**:
-```bash
-refacil-sdd-ai bus ask --to <destino> --text "<pregunta>"
-```
-- No bloquea; retorna inmediatamente tras enviar
-- Úsalo cuando no sabes si el otro lado está activo o no necesitas la respuesta ahora
-
-### Paso 3: Ejecutar
-
-Usa `Bash` con el comando elegido.
-
-### Paso 4: Procesar resultado
-
-- Si `--wait` trajo respuesta: úsala como contexto para continuar tu trabajo; no reportes solo el mensaje, continúa con el flujo que el usuario te pidió.
-- Si `--wait` expiró: informa al usuario y propón `/refacil:inbox` para revisar más tarde.
-- Si fire-and-forget: confirma al usuario que se envió.
-
-## Reglas
-
-- Entrecomilla correctamente el texto de la pregunta.
-- Si el texto tiene comillas, escápalas con `\`.
-- Nunca envíes secretos, tokens ni datos sensibles — el bus persiste los mensajes 7 días en disco local.
-- Si el destino no existe en la sala, el mensaje queda en el `inbox.jsonl` y se entregará cuando se una.
-- Si **acordaste** con otra sesion que ellos cambien su repo, ellos deben usar **`/refacil:propose`** alli y **avisarte por el bus** al terminar; si te piden cambios a ti, tu haces lo mismo aqui. Convencion completa: `refacil-prereqs/BUS-CROSS-REPO.md`.
-- Los **`ask` que son solicitudes de cambio** deben ser **sustantivos en alcance** (Paso 1.5): el receptor ya usa la metodologia; no repitas la guía en el texto. No uses el bus para pedir quick fixes opacos cuando el impacto exige SDD-AI.
+---
+name: refacil:ask
+description: Ask something directed to another session on the bus. Optionally blocks waiting for the response (--wait N seconds) for automatic LLM-to-LLM flow.
+user-invocable: true
+---
+
+# refacil:ask — Directed question to another session
+
+Sends a directed question to a session in the room, or to **all other sessions** in the room with `@all` (aliases: `*`, `everyone`). **$ARGUMENTS** includes `@<destination>` and the text.
+
+## Instructions
+
+### Step 1: Identify destination and text
+
+Expected format of $ARGUMENTS:
+```
+@<session-name> "question..."
+```
+
+Extract:
+- `destination`: session name without the `@`
+- `text`: the question
+
+If the destination is not clear, use `/refacil:rooms` (via `refacil-sdd-ai bus rooms`) to list active sessions and ask the user for clarification.
+
+**Directed broadcast (`@all`)**: the broker emits an `ask` for each member (except the asker), same `correlationId`. Each receiver can `/refacil:reply` on their side. With `--wait`, the CLI returns **the first** response that arrives (does not wait for all).
+
+### Step 1.5: Informational question vs. change request (in the destination repo)
+
+Whoever is in the room arrived via **`/refacil:join`** (and the repo with Refacil methodology): **they already know SDD-AI**; **no need** to paste the guide or re-explain what `/refacil:propose` is. It is enough that the message is **clear in scope and criteria** so the other agent runs **their** flow (`propose`, `apply`, etc.) without improvising patches.
+
+Before drafting the `--text`, classify what you are going to ask `@<destination>`:
+
+| Type | Examples | How to draft the `ask` |
+|------|----------|------------------------|
+| **Information only** | "What payload does Z send?", "Where is the X handler?" | Concrete question. |
+| **Change request** in the **destination repo** | "Add field W to the contract", "Fix the bug in the service that lives in your repo", "Align the consumer with the spec" | Describe **what** must be achieved, **where** it applies, acceptance criteria or links to spec/conversation. The recipient channels that with **`/refacil:propose`** (and what follows) in **their** repo; do not ask for "just a quick change" when the impact is versionable code, unless the **human user** explicitly orders otherwise. |
+
+If you mix query + change, separate into two messages or make clear which part is read-only and which is versionable work in the other repo.
+
+### Step 2: Decide whether to use `--wait`
+
+Two modes:
+
+**Blocking mode (recommended when you need the response to continue)**:
+```bash
+refacil-sdd-ai bus ask --to <destination> --text "<question>" --wait 180
+```
+- The CLI blocks until it receives the response or the timeout passes (default suggested: 60-180s)
+- If the other side is in `/refacil:attend`, the response comes back automatically
+- If the response arrives: the CLI prints it and you can continue with that info
+- If timeout: notify the user and suggest `/refacil:inbox` later
+
+**Fire-and-forget mode**:
+```bash
+refacil-sdd-ai bus ask --to <destination> --text "<question>"
+```
+- Does not block; returns immediately after sending
+- Use it when you do not know if the other side is active or you do not need the response now
+
+### Step 3: Execute
+
+Use `Bash` with the chosen command.
+
+### Step 4: Process result
+
+- If `--wait` brought a response: use it as context to continue your work; do not just report the message, continue with the flow the user asked for.
+- If `--wait` expired: inform the user and propose `/refacil:inbox` to review later.
+- If fire-and-forget: confirm to the user that it was sent.
+
+## Rules
+
+- Correctly quote the question text.
+- If the text has quotes, escape them with `\`.
+- Never send secrets, tokens, or sensitive data — the bus persists messages 7 days on local disk.
+- If the destination does not exist in the room, the message is stored in `inbox.jsonl` and will be delivered when they join.
+- If you **agreed** with another session that they will change their repo, they must use **`/refacil:propose`** there and **notify you via bus** when done; if they request changes from you, you do the same here. Full convention: `refacil-prereqs/BUS-CROSS-REPO.md`.
+- **`ask`s that are change requests** must be **substantive in scope** (Step 1.5): the recipient already uses the methodology; do not repeat the guide in the text. Do not use the bus to request opaque quick fixes when the impact requires SDD-AI.