refacil-sdd-ai 4.2.3 → 4.3.0

package/README.md

@@ -1,196 +1,218 @@
 # refacil-sdd-ai
 
-Metodologia **SDD-AI** (Specification-Driven Development with AI) empaquetada como CLI.
+**SDD-AI** (Specification-Driven Development with AI) packaged as a 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.
+Installs **skills** and **sub-agents** for **Claude Code** and **Cursor** that guide the developer through a structured AI-assisted development workflow, using **`refacil-sdd/`** as the specification store, plus a **local bus** so agents across different repos can communicate with each other.
 
 ---
 
-## Requisitos
+## Requirements
 
-- **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**
+- **Node.js >= 20.0.0**
+- **Claude Code >= 2.1.89** (required by the `compact-bash` hook for silent rewrite via `updatedInput`) or **Cursor**
 
-`refacil-sdd-ai init` verifica la version de Claude Code y advierte si es inferior. Con version < 2.1.89 el resto de la metodologia funciona, pero `compact-bash` no tendra efecto.
+`refacil-sdd-ai init` checks the Claude Code version and warns if it is below 2.1.89. With an older version the rest of the methodology works, but `compact-bash` will have no effect.
 
 ---
 
-## Instalacion
+## Installation
 
-Recomendado: instalar globalmente una sola vez, y correr `init` por repo.
+Recommended: install globally once, then run `init` per repo.
 
 ```bash
-# 1. Global (una vez)
+# 1. Global (once)
 npm install -g refacil-sdd-ai
 
-# 2. En la raiz del repo
+# 2. In the repo root
 refacil-sdd-ai init
-#    Copia skills a .claude/ y .cursor/, crea CLAUDE.md + .cursorrules, configura hooks
-#    Crea/actualiza .claudeignore y .cursorignore con exclusiones base
+#    Copies skills to .claude/ and .cursor/, creates CLAUDE.md + .cursorrules, configures hooks
+#    Creates/updates .claudeignore and .cursorignore with base exclusions
 
-# 3. Reiniciar sesion de Claude Code o Cursor
-#    (las skills nuevas no se detectan hasta reiniciar)
+# 3. Restart your Claude Code or Cursor session
+#    (new skills are not detected until you restart)
 
-# 4. En el IDE
+# 4. In the IDE
 /refacil:setup
-#    Instala OpenSpec, inicializa openspec/ y genera AGENTS.md
+#    Generates AGENTS.md and the .agents/ directory for the project
 ```
 
-### Actualizar
+### Update
 
 ```bash
 npm update -g refacil-sdd-ai
-refacil-sdd-ai update          # en cada repo donde se use
+refacil-sdd-ai update          # in each repo where it is used
 ```
 
-En Claude Code / Cursor el hook `check-update` (cada sesion) sincroniza skills y `compact-guidance`; solo si la **deteccion automatica** (`lib/methodology-migration-pending.js`) encuentra migracion de metodologia pendiente se escribe el flag y `notify-update` puede pedir `/refacil:update`. Si no hay migracion, no se molesta al usuario. La skill `/refacil:update` usa `refacil-sdd-ai migration-pending` como mismo criterio.
+In Claude Code / Cursor the `check-update` hook (every session) syncs skills and `compact-guidance`. Only if the automatic detection (`lib/methodology-migration-pending.js`) finds a pending methodology migration does it write the flag and allow `notify-update` to prompt `/refacil:update`. If there is no migration, the user is not interrupted. The `/refacil:update` skill uses `refacil-sdd-ai migration-pending` as the same criterion.
 
-### Desinstalar
+### Uninstall
 
 ```bash
-refacil-sdd-ai clean           # en el repo (elimina skills + hooks SDD-AI)
+refacil-sdd-ai clean           # in the repo (removes skills + SDD-AI hooks)
 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.
+### Legacy `openspec/` directory
+
+Older repos may still have **`openspec/changes/`**. The package **migrates automatically** to **`refacil-sdd/`** the first time you run any **`refacil-sdd-ai sdd …`** subcommand or when **`check-update`** runs at session start. After you confirm the tree under **`refacil-sdd/`**, you can remove the leftover **`openspec/`** folder.
+
+Some teams still install the **OpenSpec CLI** for **`opsx:*`** commands; those can coexist with SDD-AI. The **supported** path for changes, review markers, and archiving is **`refacil-sdd/`** plus **`refacil-sdd-ai sdd`** and **`/refacil:*`** skills.
 
 ---
 
-## Comandos del CLI
+## CLI Commands
+
+### Package management
+
+| Command | Description |
+|---|---|
+| `refacil-sdd-ai init` | Install skills and hooks in the current repo |
+| `refacil-sdd-ai update` | Re-copy skills and hooks to the latest version |
+| `refacil-sdd-ai migration-pending [--json]` | Same detection as hooks/`notify-update`; exit 1 if migration is pending; on exit 0 also deletes obsolete `.refacil-pending-update` (same as at the start of `check-update`) |
+| `refacil-sdd-ai clean` | Remove SDD-AI skills and hooks from the repo |
+| `refacil-sdd-ai help` | Show help |
 
-### Gestion del paquete
+### Internal hooks (invoked automatically — not for manual use)
 
-| Comando | Descripcion |
+| Command | Description |
 |---|---|
-| `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 migration-pending [--json]` | Misma deteccion que hooks/`notify-update`; exit 1 si hay migracion pendiente; con exit 0 tambien borra `.refacil-pending-update` obsoleto (igual que al inicio de `check-update`) |
-| `refacil-sdd-ai clean` | Elimina skills y hooks SDD-AI del repo |
-| `refacil-sdd-ai help` | Ver ayuda |
+| `refacil-sdd-ai check-update` | (`SessionStart`) Clears obsolete update flag if no migration; npm optional; syncs skills and `compact-guidance` in AGENTS.md |
+| `refacil-sdd-ai notify-update` | (`UserPromptSubmit` / `beforeSubmitPrompt`) Only acts if a methodology migration is pending (same logic as `/refacil:update`); otherwise does not interrupt |
+| `refacil-sdd-ai check-review` | (`PreToolUse`) Blocks `git push` if `.review-passed` is missing in any active change |
+| `refacil-sdd-ai compact-bash` | (`PreToolUse`) Silently rewrites bare Bash commands via `updatedInput` |
+
+### SDD artifacts (`sdd`)
 
-### Hooks internos (invocados automaticamente, no manual)
+Native CLI for **`refacil-sdd/`** (no separate OpenSpec skill layer). Used by skills and hooks; you can also run it from scripts.
 
-| Comando | Descripcion |
+| Command | Description |
 |---|---|
-| `refacil-sdd-ai check-update` | (`SessionStart`) Limpia flag de update obsoleto si no hay migracion; npm opcional; sincroniza skills y `compact-guidance` en AGENTS.md |
-| `refacil-sdd-ai notify-update` | (`UserPromptSubmit` / `beforeSubmitPrompt`) Solo actua si hay migracion de metodologia pendiente (misma logica que `/refacil:update`); si no, no interrumpe |
-| `refacil-sdd-ai check-review` | (`PreToolUse`) Bloquea `git push` si falta `.review-passed` en algun cambio activo |
-| `refacil-sdd-ai compact-bash` | (`PreToolUse`) Reescribe comandos Bash bare via `updatedInput` |
+| `refacil-sdd-ai sdd new-change <name>` | Scaffold `proposal.md`, `design.md`, `tasks.md`, and specs under `refacil-sdd/changes/<name>/` |
+| `refacil-sdd-ai sdd list [--json]` | List active changes and review status |
+| `refacil-sdd-ai sdd status <name> [--json]` | Artifact and task status for one change |
+| `refacil-sdd-ai sdd mark-reviewed <name>` | Write `.review-passed` (requires `--verdict`, `--summary`, counts) |
+| `refacil-sdd-ai sdd tasks-update <name>` | Mark a task done (`--task N --done`) |
+| `refacil-sdd-ai sdd archive <name>` | Move a regular change to `refacil-sdd/changes/archive/` |
+| `refacil-sdd-ai sdd validate-name <name>` | Validate change folder name (must start with a letter) |
 
-### Control del rewrite de comandos (`compact-bash`)
+Run **`refacil-sdd-ai help`** for the full list including `bus` and `compact` subcommands.
 
-| Comando | Descripcion |
+### Command rewrite control (`compact-bash`)
+
+| Command | Description |
 |---|---|
-| `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` |
+| `refacil-sdd-ai compact stats` | Statistics (hook + already-compact) + estimated tokens and USD |
+| `refacil-sdd-ai compact enable` | Re-enable rewriting |
+| `refacil-sdd-ai compact disable` | Disable rewriting without uninstalling |
+| `refacil-sdd-ai compact clear-log` | Clear `~/.refacil-sdd-ai/compact.log` |
 
-### Bus de agentes (`bus`)
+### Agent bus (`bus`)
 
-| Comando | Descripcion |
+| Command | Description |
 |---|---|
-| `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 <sesión> --text "..." [--wait N]` | Pregunta dirigida; `--to all` (también `*` o `everyone`) envía un ask a cada miembro de la sala excepto tú |
-| `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.
+| `refacil-sdd-ai bus start` | Start the local broker (auto-spawn detached) |
+| `refacil-sdd-ai bus stop` | Stop the broker |
+| `refacil-sdd-ai bus status` | Show port, pid, uptime |
+| `refacil-sdd-ai bus rooms` | Active rooms + members |
+| `refacil-sdd-ai bus view` | Open the web UI in the browser |
+| `refacil-sdd-ai bus watch <session> [--room <room>]` | Live terminal panel (0 tokens) |
+| `refacil-sdd-ai bus history [--n N] [--session <s>]` | Last N messages |
+| `refacil-sdd-ai bus join --room <room> [--session <s>] [--intro "..."]` | Join a room (skills do this automatically) |
+| `refacil-sdd-ai bus leave [--session <s>]` | Leave the room |
+| `refacil-sdd-ai bus say --text "..." [--session <s>]` | Broadcast (skills do this automatically) |
+| `refacil-sdd-ai bus ask --to <session> --text "..." [--wait N]` | Directed question; `--to all` (also `*` or `everyone`) sends to every room member except you |
+| `refacil-sdd-ai bus reply --text "..." [--correlation <id>]` | Reply (skills do this automatically) |
+| `refacil-sdd-ai bus attend [--timeout N]` | Listen for directed questions (skills do this automatically) |
+| `refacil-sdd-ai bus inbox [--session <s>]` | View new messages |
+
+> The `join/leave/say/ask/reply/attend/inbox` subcommands also exist as **IDE skills** (`/refacil:join`, etc.). In most cases use the skills; the CLI commands are for scripting or debugging.
 >
-> **Coordinacion entre repos** (solicitudes por `ask`, acuerdos en sala, `/refacil:propose`, cierre al solicitante): tras `init` queda en `.claude/skills/refacil-prereqs/` y `.cursor/skills/refacil-prereqs/` el archivo **`BUS-CROSS-REPO.md`** (no duplicar aqui el contrato completo).
+> **Cross-repo coordination** (ask requests, room agreements, `/refacil:propose`, closing to the requester): after `init`, the file **`BUS-CROSS-REPO.md`** is available in `.claude/skills/refacil-prereqs/` and `.cursor/skills/refacil-prereqs/`.
 
 ---
 
-## Skills disponibles en el IDE
+## Available IDE Skills
 
-Todas se invocan como `/refacil:<nombre>` en Claude Code o Cursor.
+All invoked as `/refacil:<name>` in Claude Code or Cursor.
 
-### Ciclo SDD
+### SDD cycle
 
-| Skill | Uso |
+| Skill | Usage |
 |---|---|
-| `/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 |
-| `/refacil:update` | Detectar y aplicar migraciones pendientes de la metodologia al repo actual |
-
-### 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 | Puede escribir |
+| `/refacil:setup` | Generate AGENTS.md and the `.agents/` project index |
+| `/refacil:guide` | Interactive guide on which command to use |
+| `/refacil:explore` | Explore the codebase without modifying anything |
+| `/refacil:propose` | Create a change proposal: proposal + specs + design + tasks |
+| `/refacil:apply` | Implement the change tasks |
+| `/refacil:test` | Generate unit tests from the artifacts |
+| `/refacil:verify` | Validate implementation vs specs (with optional autofix) |
+| `/refacil:review` | Quality checklist, emits `.review-passed` if approved |
+| `/refacil:archive` | Archive the completed change + sync specs (requests Jira links) |
+| `/refacil:up-code` | Commit + push + PR (runs review if missing) |
+| `/refacil:bug` | Full bugfix flow with regression tests |
+| `/refacil:update` | Detect and apply pending methodology migrations to the current repo |
+
+### Automatic sub-agents (v3.0.0+)
+
+Some skills delegate their heavy work to **sub-agents** that run in isolated context (they do not saturate the main session with mass reads). They are invoked automatically by the corresponding skill — do not call them directly.
+
+| Skill | Sub-agent | Role | Can write |
 |---|---|---|---|
-| `/refacil:explore` | `refacil-investigator` | Lee codebase, enriquece con AGENTS.md, consulta bus cross-repo | No |
-| `/refacil:verify` | `refacil-validator` | Corre tests + compara contra spec, retorna issues priorizados | No |
-| `/refacil:review` | `refacil-auditor` | Evalua cambios contra el checklist de calidad | No |
-| `/refacil:test` | `refacil-tester` | Detecta stack, genera tests cubriendo CA/CR, corre y corrige | Si (archivos de test) |
-| `/refacil:apply` | `refacil-implementer` | Lee artefactos OpenSpec e implementa todas las tasks del cambio | Si (codigo fuente) |
-| `/refacil:bug` | `refacil-debugger` | Modo `investigation`: analiza causa raiz sin modificar nada. Modo `fix`: implementa el fix, genera tests de regresion y crea `summary.md` | Solo en modo fix |
-| `/refacil:propose` | `refacil-proposer` | Explora el codebase y genera proposal, specs, design y tasks | Si (artefactos SDD) |
+| `/refacil:explore` | `refacil-investigator` | Reads codebase, enriches with AGENTS.md, queries cross-repo bus | No |
+| `/refacil:verify` | `refacil-validator` | Runs tests + compares against spec, returns prioritized issues | No |
+| `/refacil:review` | `refacil-auditor` | Evaluates changes against the quality checklist | No |
+| `/refacil:test` | `refacil-tester` | Detects stack, generates tests covering CA/CR, runs and fixes | Yes (test files) |
+| `/refacil:apply` | `refacil-implementer` | Reads SDD artifacts and implements all change tasks | Yes (source code) |
+| `/refacil:bug` | `refacil-debugger` | `investigation` mode: analyzes root cause without modifying anything. `fix` mode: implements the fix, generates regression tests, creates `summary.md` | Only in fix mode |
+| `/refacil:propose` | `refacil-proposer` | Explores the codebase and generates proposal, specs, design, and tasks | Yes (SDD artifacts) |
+
+**Common properties**: specialized system prompt, direct-invocation guardrail, output contract with a fenced JSON block per skill. Read-only sub-agents (`investigator`, `validator`, `auditor`) do not have `Edit`/`Write`. Write sub-agents (`tester`, `implementer`, `debugger`, `proposer`) do.
 
-**Propiedades comunes**: system prompt especializado, guardrail de invocacion directa, contrato de salida con bloque JSON fenced por skill. Los sub-agentes de solo lectura (`investigator`, `validator`, `auditor`) no tienen `Edit`/`Write`. Los de escritura (`tester`, `implementer`, `debugger`, `proposer`) si los tienen.
+**Model**: `refacil-proposer` runs with `model: opusplan` (uses Opus during plan mode for highest-stakes planning, then switches to Sonnet for execution). Other sub-agents use `model: sonnet` by default.
 
-**Dual-platform**: `.claude/agents/refacil-*.md` usa `tools:` (allowlist granular). `.cursor/agents/refacil-*.md` se genera automaticamente: `readonly: true` para agentes sin `Edit`/`Write`, `readonly: false` para los que si los tienen; siempre `model: inherit`. El installer transforma el frontmatter automaticamente.
+**Dual-platform**: `.claude/agents/refacil-*.md` uses `tools:` (granular allowlist). `.cursor/agents/refacil-*.md` is auto-generated: `readonly: true` for agents without `Edit`/`Write`, `readonly: false` for those that have them; always `model: inherit`. The installer transforms the frontmatter automatically.
 
-**Flujo de `refacil:bug` con dos pasadas**: el wrapper invoca primero al sub-agente en modo `investigation` (sin escribir nada) → el usuario confirma la hipotesis y aprueba el fix → el wrapper valida la rama de trabajo → invoca al sub-agente en modo `fix` para implementar.
+**Two-pass `refacil:bug` flow**: the wrapper first invokes the sub-agent in `investigation` mode (writes nothing) → the user confirms the hypothesis and approves the fix → the wrapper validates the working branch → invokes the sub-agent in `fix` mode to implement.
 
-### Bus de agentes
+### Agent bus
 
-| Skill | Uso |
+| Skill | Usage |
 |---|---|
-| `/refacil:join <sala>` | Unirse o crear sala |
+| `/refacil:join <room>` | Join or create a room |
 | `/refacil:say "..."` | Broadcast |
-| `/refacil:ask @nombre "..." [--wait N]` | Pregunta dirigida; `@all` pregunta a todos en la sala (bloquea con `--wait` hasta la **primera** respuesta) |
-| `/refacil:reply "..."` | Responder ultima pregunta (autocompleta `correlationId`) |
-| `/refacil:attend` | Modo escucha activa |
-| `/refacil:inbox` | Mensajes nuevos desde la ultima lectura |
+| `/refacil:ask @name "..." [--wait N]` | Directed question; `@all` asks everyone in the room (blocks with `--wait` until the **first** response) |
+| `/refacil:reply "..."` | Reply to the last question (auto-fills `correlationId`) |
+| `/refacil:attend` | Active listen mode |
+| `/refacil:inbox` | New messages since last read |
 
 ---
 
-## Flujo recomendado
+## Recommended Flow
 
-Regla rapida para elegir el comando de entrada:
+Quick rule for choosing the entry command:
 
-- Entender el sistema sin tocar codigo -> `/refacil:explore`
-- Feature nuevo o cambio de comportamiento -> `/refacil:propose`
-- Bug funcional o error en produccion -> `/refacil:bug`
+- Understand the system without touching code → `/refacil:explore`
+- New feature or behavior change → `/refacil:propose`
+- Functional bug or production error → `/refacil:bug`
 
-A partir de ahi, el ciclo completo es:
+From there, the full cycle is:
 
 ```
 ┌───────────────────────────┐
-│  Necesidad de cambio      │
+│  Change needed            │
 └──────────────┬────────────┘
                ▼
       ┌─────────────────┐
-      │ ¿Tipo de tarea? │
+      │ Type of task?   │
       └──┬───────┬──────┘
          │       │
    FEATURE│       │BUG
          ▼       ▼
   /refacil:    /refacil:
   propose      bug
-  (proposal +  (fix + tests
-   specs +     de regresion
-   design +    + summary.md)
+  (proposal +  (fix + regression
+   specs +     tests +
+   design +    summary.md)
    tasks)        │
          │       │
          ▼       │
@@ -204,105 +226,105 @@ A partir de ahi, el ciclo completo es:
          ▼       │
   /refacil:     │
   verify        │
-  (max 2 rondas │
+  (max 2 rounds │
    autofix)     │
          │       │
          └───┬───┘
              ▼
      /refacil:review
-     (genera .review-passed)
+     (generates .review-passed)
              ▼
     /refacil:archive
-    (feature: OpenSpec
-     bug: fix-*/spec.md +
-          review.yaml)
+    (feature: moves to archive/ + syncs specs
+     bug: fix-*/spec.md + review.yaml)
              ▼
     /refacil:up-code
-    (verifica review +
+    (checks review +
      commit + push + PR)
              ▼
-         PR creado
+         PR created
 ```
 
-**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.
+**Two-layer review gate**:
+- `/refacil:up-code` detects a missing `.review-passed` and **automatically runs `/refacil:review`** before pushing.
+- The `check-review` hook also intercepts manual `git push` commands and **blocks** the operation if it is missing. The hook does not invoke skills — it only blocks and instructs.
 
 **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.
+- For features/improvements: the CLI moves artifacts to `archive/` and extracts `.review-passed` fields to `review.yaml` inside each affected spec.
+- For bugs: manual archiving, creates `refacil-sdd/specs/fix-*/spec.md` in standard format + `review.yaml`.
+- A single branch can accumulate multiple bugs, each in its own independent `fix-*/` folder.
+- `/refacil:archive` always requests one or more **Jira links** associated with the change before proceeding. Links are stored in `review.yaml` under the `jiraTasks` field (YAML list). This field is mandatory — archiving does not proceed until the user provides at least one link.
 
 ---
 
-## Hooks automaticos
+## Automatic Hooks
 
-Se instalan en `.claude/settings.json` **y** `.cursor/settings.json` durante `init` / `update`. Aplican tanto a **Claude Code** como a **Cursor**.
+Installed in `.claude/settings.json` **and** `.cursor/settings.json` during `init` / `update`. Apply to both **Claude Code** and **Cursor**.
 
-| Hook | Evento | Que hace |
+| Hook | Event | What it does |
 |---|---|---|
-| `check-update` | `SessionStart` | Al inicio borra `.refacil-pending-update` si ya no hay migracion (flags obsoletos). Luego: npm, sync skills, **compact-guidance**. Si hubo sync de skills y **si** hay migracion pendiente, escribe el flag para `notify-update`. |
-| `notify-update` | `UserPromptSubmit` (Claude Code) / `beforeSubmitPrompt` (Cursor) | Si existe flag y **hay migracion de metodologia pendiente** (misma tabla que `/refacil:update`), inyecta la instruccion o pausa el primer mensaje; si solo hubo sync de skills sin migracion, el flag no se crea o se descarta sin preguntar. |
-| `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. |
+| `check-update` | `SessionStart` | On startup deletes `.refacil-pending-update` if no migration is pending (stale flags). Then: npm check, sync skills, **compact-guidance**. If skills were synced **and** a migration is pending, writes the flag for `notify-update`. |
+| `notify-update` | `UserPromptSubmit` (Claude Code) / `beforeSubmitPrompt` (Cursor) | If the flag exists **and** a methodology migration is pending (same table as `/refacil:update`), injects the instruction or pauses the first message; if the sync happened without a migration, the flag is not created or is discarded silently. |
+| `compact-bash` | `PreToolUse` (Bash) | Silently rewrites bare Bash commands via `updatedInput`. No extra turns, the IDE does not see the change. Requires Claude Code >= 2.1.89. |
+| `check-review` | `PreToolUse` (Bash) | Intercepts `git push` and blocks if `.review-passed` is missing in any active change. |
 
-Los cuatro hooks se instalan en `.claude/settings.json` (Claude Code) y `.cursor/settings.json` (Cursor) con la misma logica parametrica.
+All four hooks are installed in `.claude/settings.json` (Claude Code) and `.cursor/settings.json` (Cursor) with the same parametric logic.
 
-> **Por que dos hooks para el update?** `SessionStart` hace el sync silencioso al abrir la sesion sin interaccion del usuario. `notify-update` en `UserPromptSubmit` / `beforeSubmitPrompt` inyecta la instruccion justo antes de que el agente procese el siguiente mensaje del usuario, garantizando que no se ignore.
+> **Why two hooks for updates?** `SessionStart` does the silent sync when opening the session without user interaction. `notify-update` on `UserPromptSubmit` / `beforeSubmitPrompt` injects the instruction just before the agent processes the next user message, ensuring it is not ignored.
 
-### Gate de review en el push
+### Review gate on push
 
 ```
          ┌──────────────────────────────┐
-         │ Dev ejecuta /refacil:up-code │
-         │      o git push manual       │
+         │ Dev runs /refacil:up-code    │
+         │   or manual git push         │
          └──────────────┬───────────────┘
                         │
      ┌──────────────────┴──────────────────┐
-     │ Via /refacil:up-code                │ git push directo
+     │ Via /refacil:up-code                │ Direct git push
      ▼                                     ▼
 ┌─────────────────────┐          ┌───────────────────────┐
-│ up-code detecta     │          │ Hook check-review     │
-│ falta .review-passed│          │ (PreToolUse en Bash)  │
-│ INVOCA /refacil:    │          │ Verifica .review-     │
-│ review              │          │ passed en changes/*   │
+│ up-code detects     │          │ Hook check-review     │
+│ missing             │          │ (PreToolUse on Bash)  │
+│ .review-passed →    │          │ Checks .review-passed │
+│ INVOKES /refacil:   │          │ in changes/*          │
+│ review              │          │                       │
 └─────────┬───────────┘          └──────────┬────────────┘
           │                                 │
           ▼                                 ▼
    ┌──────────────┐                ┌─────────────────┐
-   │ ¿Review OK?  │                │ ¿Falta alguno?  │
+   │ Review OK?   │                │ Any missing?    │
    └──┬────────┬──┘                └──┬───────────┬──┘
-    SI│      NO│                    SI│         NO│
-      ▼        ▼                      ▼           ▼
-   push OK  informa +              block +     allow
-            no pushea              instruccion push
+    YES│      NO│                   YES│         NO│
+      ▼        ▼                       ▼           ▼
+   push OK  report +               block +     allow
+            no push                instruct    push
 ```
 
-### Hook `compact-bash` — rewrite silencioso de comandos
+### `compact-bash` hook — silent command rewrite
 
-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.
+A second token-reduction layer, **with no conversational cost**. Claude emits a Bash command; before executing it, the hook inspects it, and if it matches a rule rewrites it via `updatedInput`. Claude does not see the change.
 
-**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.
+**Intent detector**: if the command already has explicit flags (`git log -p`, `jest --watch`, `docker logs --tail 50`), the hook **does not intervene** — your intent takes precedence.
 
-**Escape**: prefija `COMPACT=0` al comando (`COMPACT=0 git log`).
+**Escape**: prefix `COMPACT=0` to the command (`COMPACT=0 git log`).
 
-**Reglas activas — git, tests, docker logs**:
+**Active rules — git, tests, docker logs**:
 
-| Bare | Reescrito a | Ahorro |
+| Bare | Rewritten to | Savings |
 |---|---|---|
 | `git log` | `git log --oneline -20` | ~85% |
 | `git status` | `git status -s` | ~70% |
-| `git diff` (sin args) | `git diff --stat` | ~80% |
+| `git diff` (no 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**:
+**Active rules — linters, type checkers, build, system**:
 
-| Bare | Reescrito a | Ahorro |
+| Bare | Rewritten to | Savings |
 |---|---|---|
 | `eslint` | `eslint . --format compact --quiet` | ~70% |
 | `eslint <path>` | `eslint <path> --format compact` | ~60% |
@@ -312,106 +334,109 @@ Segunda capa de reduccion de tokens, **sin costo conversacional**. Claude emite
 | `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% |
+| `go test …` (no 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).
+**Telemetry**: each rewrite appends a JSON line to `~/.refacil-sdd-ai/compact.log` (local, nothing leaves the machine). `compact stats` calculates token savings and estimated USD (at $3/MTok input for Sonnet, conservative).
 
-### Bloque `compact-guidance` en AGENTS.md
+### `compact-guidance` block in 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.).
+The SDD-AI methodology generates a lot of context (artifacts, specs, prompts). To compensate, the package maintains a block in `AGENTS.md` that instructs the AI to request compact output (Read with offset/limit, `git log --oneline`, tests with failures only, 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
+- Delimited by `<!-- refacil-sdd-ai:compact-guidance:start -->` and `...:end -->`
+- Source of truth: `templates/compact-guidance.md`
+- Synced on: `init`, `update`, and the `check-update` hook (every SessionStart)
+- If `AGENTS.md` does not exist, it is not created behind the user's back
 
-> **No editar manualmente** entre los marcadores. Se sobrescribe en la proxima sesion.
+> **Do not manually edit** between the markers. Content is overwritten on the next session.
 
 ---
 
-## Reglas metodologicas transversales
+## Cross-methodology rules
 
-Definidas en `skills/prereqs/METHODOLOGY-CONTRACT.md`:
+Defined in `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.
+- **Flow states**: `READY_FOR_APPLY` / `VERIFY` / `REVIEW` / `ARCHIVE` / `MERGE` — each transition validates prerequisites.
+- **Branch policy**: every new branch (`feature/*`, `fix/*`, etc.) is created from an up-to-date `develop`/`dev`. Integration to protected branches (`testing`, `develop`, `dev`, `main`, `master`, `qa`) always via PR. **Never** direct commits to `master`/`main`. Single exception: repos without `develop`/`dev`, where `main` or `master` may be used temporarily as a base.
+- **Multi-stack tests**: detects the real test command (does not hardcode `npm test`).
+- **`AGENTS.md` by profile** (`sdd` vs `agents`): the methodology respects both.
+- **Output mode**: concise by default, detailed on demand.
+- **Language policy**: internal agent and skill instructions are in **English**. Responses to the user are in the **user's language** (default: Spanish). SDD artifacts are in the **team's agreed language**.
 
 ---
 
-## refacil-bus — chat room entre agentes
+## refacil-bus — agent chat room
 
-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.
+Local bus (WebSocket over `127.0.0.1`) so agents across different repos can communicate via plain text. **Does not share files, context, or tokens between repos** — each agent responds from its own code.
 
-**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.
+**Primary use case**: a dev with several IDE windows open (one per repo). Before the bus, the dev acted as a transcriber between their own agents. With the bus, agents talk to each other directly.
 
-**Propiedades**:
+**Properties**:
 
-- 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.
+- 100% local: nothing leaves `127.0.0.1`. No accounts, no shared service.
+- Zero config: the broker auto-spawns the first time a skill needs it (`127.0.0.1:7821`, fallback 7822/7823).
+- ~40 MB RAM, 0% CPU idle. Persistence: `~/.refacil-sdd-ai/bus/<room>/inbox.jsonl` (7-day rotation).
+- Same skills in Claude Code and Cursor.
 
-**Arranque rapido**:
+**Quick start**:
 
 ```bash
-# En cada repo, una vez
+# In each repo, once
 /refacil:join refacil-main
-# La primera vez el LLM escribe un bloque de presentacion en AGENTS.md
+# On the first time the LLM writes an introduction block in 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.
+**Optimal pattern**: before starting a task that may require querying another repo, go to the other repo's window and say *"attend the bus"*. That puts it into `/refacil:attend` and the agent conversation happens in the background without the dev switching windows.
 
-**Convenciones SDD-AI en el bus**: quien esta en la sala entro con `/refacil:join` (metodologia ya activa en el repo). Las **solicitudes de cambio** a otra sesion van con **alcance claro** en el `ask` (sin pegar la guia en cada mensaje); el repo destino canaliza con **`/refacil:propose`** y quien implementa **cierra por bus** con quien pidio el trabajo. Detalle y casos limite: `refacil-prereqs/BUS-CROSS-REPO.md` en las skills instaladas.
+**SDD-AI conventions in the bus**: anyone in the room joined with `/refacil:join` (methodology already active in the repo). **Change requests** to another session go with **clear scope** in the `ask` (no pasting the guide in every message); the destination repo channels with **`/refacil:propose`** and whoever implements **closes via bus** to who requested the work. Details and edge cases: `refacil-prereqs/BUS-CROSS-REPO.md` in the installed skills.
 
-**Observador puro** (0 tokens): `refacil-sdd-ai bus watch <session>` o `refacil-sdd-ai bus view` para la UI web.
+**Pure observer** (0 tokens): `refacil-sdd-ai bus watch <session>` or `refacil-sdd-ai bus view` for the web UI.
 
-> **Diagramas, escenarios y pitch**: ver `refacil-bus-diagrams.md` (incluido en el paquete) — incluye arquitectura, flujo con attend, flujo sin attend, tabla comparativa de impacto y guia de decision visual (Mermaid).
+> **Diagrams, scenarios and pitch**: see `refacil-bus-diagrams.md` (included in the package) — includes architecture, flow with attend, flow without attend, comparative impact table, and visual decision guide (Mermaid).
 
-### Limitaciones conocidas
+### Known limitations
 
-- 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).
+- While `/refacil:attend` is active, the IDE session is occupied (abort with ESC). Mitigation: a second window of the same repo dedicated to listening.
+- The LLM does not receive external pushes: full automation requires the receiver to be in `attend`, or for the dev to ask `/refacil:inbox` afterwards.
+- No authentication: any local process can connect to the broker (by design, loopback only and on-demand by the dev).
 
 ---
 
-## Que se instala en tu repo
+## What Gets Installed in Your Repo
 
 ```
-.claude/skills/refacil-*/    # Skills Claude Code (incluye refacil-prereqs: OPENSPEC-DELTAS.md, BUS-CROSS-REPO.md, …)
-.claude/agents/refacil-*.md  # Sub-agentes readonly: auditor, investigator, validator
-                             # Sub-agentes con escritura: tester, implementer, debugger, proposer
+.claude/skills/refacil-*/    # Claude Code skills (includes refacil-prereqs: METHODOLOGY-CONTRACT.md, BUS-CROSS-REPO.md, …)
+.claude/agents/refacil-*.md  # Read-only sub-agents: auditor, investigator, validator
+                             # Write sub-agents: tester, implementer, debugger, proposer
 .claude/settings.json        # Hooks: check-update + check-review + compact-bash
-.cursor/skills/refacil-*/    # Skills Cursor (equivalente)
-.cursor/agents/refacil-*.md  # Sub-agentes Cursor (readonly:true/false + model:inherit auto-generados)
-.cursor/settings.json        # Hooks: check-update + check-review + compact-bash (mirror de .claude/)
-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                    # 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
+.cursor/skills/refacil-*/    # Cursor skills (equivalent)
+.cursor/agents/refacil-*.md  # Cursor sub-agents (readonly:true/false + model:inherit auto-generated)
+.cursor/settings.json        # Hooks: check-update + check-review + compact-bash (mirror of .claude/)
+CLAUDE.md                    # Minimal index → points to AGENTS.md
+.cursorrules                 # Same in Cursor format
+.claudeignore                # Base exclusions (node_modules, dist, .env, *.key, etc.)
+.cursorignore                # Same content as .claudeignore
+AGENTS.md                    # Project index → generated by /refacil:setup
+                             # Points to .agents/ + includes auto-managed blocks
+                             # (compact-guidance and bus presentation)
+.agents/                     # Project detail by area (generated by /refacil:setup)
+                             # summary.md, architecture.md, stack.md, testing.md, commands.md…
+refacil-sdd/                 # SDD artifacts store
+  changes/                   # Active changes: proposal.md, specs, design.md, tasks.md
+  changes/archive/           # Archived changes (moved here by /refacil:archive)
+  specs/                     # Persistent specifications synced from archived changes
 ```
 
 ---
 
-## Tecnologias
+## Technologies
 
-- [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
+- [AGENTS.md](https://agents.md/) — universal AI instructions standard
+- [Claude Code](https://claude.ai/code) — Anthropic CLI
+- [Cursor](https://cursor.sh) — AI IDE
 
-## Licencia
+## License
 
 MIT