refacil-sdd-ai 4.2.4 → 4.4.0

package/skills/prereqs/METHODOLOGY-CONTRACT.md

@@ -1,115 +1,122 @@
-# Contrato Metodologico SDD-AI (Refacil)
-
-Este archivo centraliza reglas transversales para evitar duplicacion e inconsistencias entre skills.
-
-## 1) Estados del flujo (Definition of Ready / Done)
-
-- **READY_FOR_PROPOSE**: problema entendido (objetivo, alcance, restricciones) y contexto minimo del repo.
-- **READY_FOR_APPLY**: artefactos SDD completos (`proposal.md`, `design.md`, `tasks.md`, especificacion en `specs.md` y/o `specs/**/*.md`) y aprobacion explicita del usuario.
-- **READY_FOR_VERIFY**: implementacion terminada, sin cambios fuera de alcance.
-- **READY_FOR_REVIEW**: para cambios regulares (propose), verify ejecutado e issues criticos resueltos o aceptados por el usuario. Para bug fixes, la implementacion y tests de regresion estan completos (los bugs no pasan por verify).
-- **READY_FOR_ARCHIVE**: review aprobado (`.review-passed` existe), tasks completas o excepciones aprobadas, cambio funcionalmente cerrado.
-- **READY_FOR_MERGE**: review aprobado (`.review-passed` existe) e integracion lista: PR creado para la rama destino. `/refacil:up-code` verifica automaticamente el review antes del push — si falta, lo ejecuta.
-- Si existen multiples cambios activos sin review, se debe seleccionar explicitamente el cambio objetivo antes de ejecutar review/push.
-
-## 2) Politica AGENTS.md
-
-- Si una skill requiere perfil `openspec`: `AGENTS.md` es obligatorio (si falta, detener y redirigir a `/refacil:setup`).
-- Si una skill requiere perfil `agents`: si falta `AGENTS.md`, continuar con baseline generico y reportar limitacion al usuario.
-
-## 3) Resolucion de comando de tests (multi-stack)
-
-No hardcodear `npm test` salvo que sea realmente el comando del proyecto.
-
-Orden de deteccion:
-1. Si `AGENTS.md` define comando oficial de tests, usar ese.
-2. Si existe script de package manager (ej. `npm test`, `pnpm test`, `yarn test`, `bun test`), usar el correspondiente.
-3. Si es Python: `pytest`.
-4. Si es Go: `go test ./...`.
-5. Si es Rust: `cargo test`.
-6. Si es Java/Gradle: `./gradlew test` o `gradle test`.
-7. Si es Java/Maven: `mvn test`.
-
-Coverage (si aplica): detectar comando del proyecto (`test:cov`, `coverage`, `pytest --cov`, etc.). Si no existe, reportar N/A con justificacion.
-
-## 4) Politica de ramas protegidas y creacion de rama
-
-Ramas protegidas (nunca desarrollar directamente en ellas): `master`, `main`, `develop`, `dev`, `testing`, `qa`.
-
-Regla critica:
-- **NUNCA** hacer cambios directos en ramas protegidas.
-- Toda integracion a ramas protegidas se hace mediante PR, sin excepciones (incluye `testing`).
-
-### Creacion de ramas de trabajo
-
-- Regla general: toda rama nueva de trabajo (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.) debe crearse desde `develop` o `dev` actualizado.
-- Excepcion para repos nuevos: si aun no existe `develop` ni `dev`, se permite crear temporalmente desde `main` o `master`.
-- Si se usa la excepcion, recomendar crear `develop`/`dev` y adoptar ese flujo como estandar del repo.
-- **NUNCA** crear ramas de trabajo desde `testing`, `qa` ni desde otras ramas de feature/bug.
-
-### Integracion
-
-- Toda integracion a cualquier rama protegida requiere **PR**.
-- No hay excepciones: `testing`, `develop`, `main`, `master`, `qa`, `release/*` — todas requieren PR.
-- Recomendar al usuario crear PR a `testing` para que los cambios esten disponibles en el entorno de pruebas.
-
-### Protocolo cuando la rama actual es protegida
-
-Si la rama actual es protegida y se necesita escribir codigo:
-
-1. Informar y pedir identificador de tarea (Jira u otro).
-2. Verificar working directory limpio (`git status --porcelain`).
-3. Si hay cambios sin commitear, pedir aprobacion para `git stash push -m "stash-automatico-refacil"`.
-4. Detectar rama base para crear rama de trabajo:
-   - Preferir `develop`, luego `dev`.
-   - Solo si no existen (repo nuevo), usar `main` o `master` como excepcion temporal.
-   - Cambiar y actualizar (`git pull origin <base>`). Si ninguna existe, detener.
-5. Crear rama de trabajo:
-   - Feature: `feature/<ID>`
-   - Bugfix: `fix/<ID>`
-   - Sin ID: nombre descriptivo corto y recomendar crear ticket.
-6. Restaurar `stash` si se uso.
-7. Si el usuario no aprueba el proceso, detener.
-
-## 5) Politica de salida (UX)
-
-Modo por defecto: **conciso**.
-
-- **Conciso**: veredicto + blockers + maximo 5 hallazgos priorizados + siguiente paso.
-- **Detallado**: reporte completo por seccion.
-
-Si el usuario no pide detalle, usa modo conciso.
-
-### Continuidad natural del flujo (confirmacion)
-
-- Cuando exista **un unico siguiente paso posible** dentro del flujo, no limitarse a "ejecuta `/refacil:...`".
-- En ese caso, cerrar con una pregunta de continuidad en lenguaje natural usando la **formula unica**:
-  - *"El siguiente paso es [descripcion breve]. Quieres que continue con `/refacil:<skill>`?"*
-- Cuando haya **multiples siguientes pasos validos** (ramificacion real), listar opciones numeradas y pedir seleccion explicita.
-- Si el paso actual es **terminal** (fin de flujo, p.ej. PR creado), cerrar sin preguntar por siguiente skill.
-
-**Regla operativa (obligatoria)**: si el usuario confirma afirmativamente ("si", "ok", "dale", "continua", "yes", etc.) a la pregunta de continuidad, **invocar directamente la siguiente skill via el Skill tool** en el mismo turno. No pedir al usuario que escriba `/refacil:X` ni que repita el contexto — la sesion debe continuar sin friccion.
-
-## 6) Scope de review y push
-
-- `up-code` y `check-review` solo deben auto-ejecutar review cuando hay un unico cambio pendiente.
-- Si hay multiples cambios pendientes de review, bloquear y pedir seleccion explicita de `nombre-cambio`.
-- `review` no debe correr en modo masivo por defecto cuando hay multiples cambios activos sin alcance explicito.
-
-## 7) Persistencia de evidencia de review
-
-- `archive` requiere `.review-passed` como precondicion bloqueante (comprobar existencia segun **§8**).
-- Al archivar cambios regulares (via OpenSpec), la metadata de `.review-passed` debe persistirse en `openspec/specs/`.
-- El formato recomendado es `review.yaml` dentro de cada carpeta de spec afectada.
-- Si no se puede mapear de forma confiable a specs concretos, registrar la evidencia en `openspec/specs/review-metadata.yaml`.
-
-## 8) Archivos ocultos bajo `openspec/changes/<cambio>/`
-
-- **`.review-passed`** y cualquier archivo cuyo nombre empiece por **`.`** son **ocultos** en muchos entornos: en shell, **`ls` sin `-a` / `-la` no los lista** — no concluyas que no existen por eso (evita falsos negativos en prereqs, review, verify, `up-code` y archive).
-- **Preferido**: herramienta **`Glob`** (patron bajo `openspec/changes/<nombre>/`), **`Read`** sobre la ruta exacta `openspec/changes/<nombre>/.review-passed`, o Bash **`test -f`** / **`[ -f ... ]`** sobre esa ruta.
-- Si el usuario dice que el archivo existe y tu comprobacion lo nego, **re-verifica** con uno de los metodos anteriores antes de insistir.
-
-## 9) Identificador de carpeta bajo `openspec/changes/<cambio>/`
-
-- El **nombre de la carpeta** del cambio activo es el identificador que usa el CLI de OpenSpec (`openspec status --change`, flujos de archive, etc.).
-- **Debe empezar con una letra ASCII** `[a-zA-Z]`. Si el primer caracter es un digito u otro simbolo, el CLI rechaza el nombre (p. ej. `Invalid change name: Change name must start with a letter`).
+# SDD-AI Methodology Contract
+
+This file centralizes cross-cutting rules to avoid duplication and inconsistencies between skills.
+
+## §1 — Flow states (Definition of Ready / Done)
+
+- **READY_FOR_PROPOSE**: problem understood (objective, scope, constraints) and minimum repo context.
+- **READY_FOR_APPLY**: complete SDD artifacts (`proposal.md`, `design.md`, `tasks.md`, specification in `specs.md` and/or `specs/**/*.md`) and explicit user approval.
+- **READY_FOR_VERIFY**: implementation finished, no changes outside scope.
+- **READY_FOR_REVIEW**: for regular changes (propose), verify executed and critical issues resolved or accepted by the user. For bug fixes, the implementation and regression tests are complete (bugs do not go through verify).
+- **READY_FOR_ARCHIVE**: review approved (`.review-passed` exists), tasks complete or exceptions approved, change functionally closed.
+- **READY_FOR_MERGE**: review approved (`.review-passed` exists) and integration ready: PR created for the target branch. `/refacil:up-code` automatically verifies the review before push — if missing, it runs it.
+- If multiple active changes exist without review, the target change must be explicitly selected before running review/push.
+
+## §2 — AGENTS.md policy
+
+- If a skill requires the `sdd` profile: `AGENTS.md` is mandatory (if missing, stop and redirect to `/refacil:setup`).
+- If a skill requires the `agents` profile: if `AGENTS.md` is missing, continue with a generic baseline and report the limitation to the user.
+
+## §3 — Test command resolution (multi-stack)
+
+Do not hardcode `npm test` unless it is genuinely the project's command.
+
+Detection order:
+1. If `AGENTS.md` defines the official test command, use that.
+2. If a package manager script exists (e.g. `npm test`, `pnpm test`, `yarn test`, `bun test`), use the corresponding one.
+3. If Python: `pytest`.
+4. If Go: `go test ./...`.
+5. If Rust: `cargo test`.
+6. If Java/Gradle: `./gradlew test` or `gradle test`.
+7. If Java/Maven: `mvn test`.
+
+Coverage (if applicable): detect the project command (`test:cov`, `coverage`, `pytest --cov`, etc.). If it does not exist, report N/A with justification.
+
+## §4 — Protected branch policy and branch creation
+
+Protected branches (never develop directly on them): `master`, `main`, `develop`, `dev`, `testing`, `qa`.
+
+Critical rule:
+- **NEVER** make direct changes on protected branches.
+- All integration to protected branches is done via PR, without exceptions (including `testing`).
+
+### Working branch creation
+
+- General rule: every new working branch (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.) must be created from an updated `develop` or `dev`.
+- Exception for new repos: if neither `develop` nor `dev` exists yet, creating temporarily from `main` or `master` is allowed.
+- If the exception is used, recommend creating `develop`/`dev` and adopting that flow as the repo standard.
+- **NEVER** create working branches from `testing`, `qa`, or from other feature/bug branches.
+
+### Integration
+
+- All integration to any protected branch requires a **PR**.
+- No exceptions: `testing`, `develop`, `main`, `master`, `qa`, `release/*` — all require PR.
+- Recommend the user create a PR to `testing` so the changes are available in the test environment.
+
+### Protocol when the current branch is protected
+
+If the current branch is protected and code needs to be written:
+
+1. Inform and ask for a task identifier (Jira or other).
+2. Verify clean working directory (`git status --porcelain`).
+3. If there are uncommitted changes, ask for approval to `git stash push -m "auto-stash-refacil"`.
+4. Detect the base branch to create a working branch from:
+   - Prefer `develop`, then `dev`.
+   - Only if neither exists (new repo), use `main` or `master` as a temporary exception.
+   - Switch and update (`git pull origin <base>`). If none exist, stop.
+5. Create the working branch:
+   - Feature: `feature/<ID>`
+   - Bugfix: `fix/<ID>`
+   - Without ID: short descriptive name and recommend creating a ticket.
+6. Restore `stash` if used.
+7. If the user does not approve the process, stop.
+
+## §5 — Output policy (UX)
+
+Default mode: **concise**.
+
+- **Concise**: verdict + blockers + maximum 5 prioritized findings + next step.
+- **Detailed**: full section-by-section report.
+
+If the user does not request detail, use concise mode.
+
+### Natural flow continuity (confirmation)
+
+- When there is **one single possible next step** within the flow, do not limit yourself to "run `/refacil:...`".
+- In that case, close with a continuity question in natural language using the **single formula**:
+  - *"The next step is [brief description]. Do you want me to continue with `/refacil:<skill>`?"*
+- When there are **multiple valid next steps** (real branching), list numbered options and ask for explicit selection.
+- If the current step is **terminal** (end of flow, e.g. PR created), close without asking for the next skill.
+
+**Operative rule (mandatory)**: if the user confirms affirmatively ("yes", "ok", "go", "continue", "sure", etc.) to the continuity question, **directly invoke the next skill via the Skill tool** in the same turn. Do not ask the user to type `/refacil:X` or repeat the context — the session must continue without friction.
+
+## §6 — Review and push scope
+
+- `up-code` and `check-review` should only auto-run review when there is a single pending change.
+- If there are multiple changes pending review, block and ask for explicit selection of `change-name`.
+- `review` must not run in bulk mode by default when there are multiple active changes without explicit scope.
+
+## §7 — Review evidence persistence
+
+- `archive` requires `.review-passed` as a blocking precondition (verify existence according to **§8**).
+- When archiving regular changes (proposal-driven flow), the `.review-passed` metadata must be persisted in `refacil-sdd/specs/`.
+- The recommended format is `review.yaml` inside each affected spec folder.
+- If it cannot be reliably mapped to specific specs, record the evidence in `refacil-sdd/specs/review-metadata.yaml`.
+
+## §8 — Hidden files under `refacil-sdd/changes/<change>/`
+
+- **`.review-passed`** and any file whose name starts with **`.`** are **hidden** in many environments: in shell, **`ls` without `-a` / `-la` does not list them** — do not conclude they do not exist because of this (avoid false negatives in prereqs, review, verify, `up-code`, and archive).
+- **Preferred**: **`Glob`** tool (pattern under `refacil-sdd/changes/<name>/`), **`Read`** on the exact path `refacil-sdd/changes/<name>/.review-passed`, or Bash **`test -f`** / **`[ -f ... ]`** on that path.
+- If the user says the file exists and your check denied it, **re-verify** with one of the above methods before insisting.
+
+## §9 — Folder identifier under `refacil-sdd/changes/<change>/`
+
+- The **folder name** of the active change is the identifier used by the refacil-sdd CLI (`refacil-sdd status --change`, archive flows, etc.).
+- **Must start with an ASCII letter** `[a-zA-Z]`. If the first character is a digit or other symbol, the CLI rejects the name (e.g. `Invalid change name: Change name must start with a letter`).
+
+## §10 — Language policy
+
+- **Agent and skill internal instructions**: always in **English** (reduces token cost, improves LLM performance).
+- **Responses to the user**: in the **user's language**. If the user writes in Spanish, respond in Spanish. If in English, respond in English. Default: Spanish.
+- **SDD artifacts** (proposal.md, specs, design.md, tasks.md): in the **user's language** (or the language the team agreed on for the project).
+- Technical terms, code identifiers, and proper nouns stay in their canonical language regardless.

package/skills/prereqs/SKILL.md

@@ -1,37 +1,30 @@
----
-name: refacil:prereqs
-description: Referencia interna — prerequisitos SDD-AI compartidos por el resto de skills refacil (no invocar manualmente)
-user-invocable: false
----
-
-# Prerequisitos SDD-AI
-
-Metodologia identica en Claude Code (`.claude/skills/refacil-*`) y Cursor (`.cursor/skills/refacil-*`). Usa la ruta del IDE abierto.
-
-Reglas transversales (estados, ramas, tests, salida): `METHODOLOGY-CONTRACT.md` en esta misma carpeta.
-
-## Perfil `openspec`
-
-Una skill pide este perfil cuando usa OpenSpec y necesita `AGENTS.md`. Estas validaciones son obligatorias en cada ejecucion de skill que declare este perfil.
-
-1. Verifica comando OpenSpec: `openspec --version 2>&1`. Si falla: *"OpenSpec no esta instalado o no esta en PATH. Ejecuta `/refacil:setup`"* y **detente**.
-2. Verifica `openspec/` en la raiz del repo. Si falta: *"OpenSpec no esta inicializado en este repo. Ejecuta `/refacil:setup`"* y **detente**.
-3. Lee `AGENTS.md` de la raiz. Si falta: *"No se encontro AGENTS.md. Ejecuta `/refacil:setup`"* y **detente**.
-4. Si un comando de OpenSpec falla despues, consulta `.claude/skills/refacil-setup/troubleshooting.md`.
-5. Si `AGENTS.md` incluye bloque `compact-guidance`, aplica esas reglas de eficiencia de tokens en toda la ejecucion.
-
-Caso especial: en `refacil:explore`, `AGENTS.md` es contexto activo durante toda la exploracion.
-
-## Perfil `agents`
-
-Solo requiere `AGENTS.md`. Si existe, leelo y aplica `compact-guidance` si esta presente. Si falta: continua con baseline generico y avisa al usuario: *"No se encontro AGENTS.md; ejecuta `/refacil:setup` para reglas del proyecto."*
-
-## OPENSPEC-DELTAS.md
-
-Convenciones Refacil al delegar a skills `openspec-*`: ver `OPENSPEC-DELTAS.md` (misma carpeta), leer junto a la skill OpenSpec que se invoque.
-
-## BUS-CROSS-REPO.md
-
-Protocolo compartido para consultar a otros repositorios via `refacil-bus` y para **acuerdos en sala** (propose + cierre al solicitante). Aplica en `explore`, `propose`, `verify` y `bug` cuando la skill detecta dependencia cross-repo o coordinacion multi-repo. Ver `BUS-CROSS-REPO.md` (misma carpeta).
-
-Si faltan estos archivos, ejecuta `refacil-sdd-ai update` (o `init`).
+---
+name: refacil:prereqs
+description: Internal reference — SDD-AI prerequisites shared by all other refacil skills (do not invoke manually)
+user-invocable: false
+---
+
+# SDD-AI Prerequisites
+
+Identical methodology in Claude Code (`.claude/skills/refacil-*`) and Cursor (`.cursor/skills/refacil-*`). Use the path of the open IDE.
+
+Cross-cutting rules (states, branches, tests, output): `METHODOLOGY-CONTRACT.md` in this same folder.
+
+## `sdd` profile
+
+A skill requests this profile when it needs `AGENTS.md` to operate with the SDD-AI flow. These validations are mandatory on each execution of a skill that declares this profile.
+
+1. Read `AGENTS.md` from the root. If missing: *"AGENTS.md not found. Run `/refacil:setup`"* and **stop**.
+2. If `AGENTS.md` includes a `compact-guidance` block, apply those token efficiency rules throughout the execution.
+
+Special case: in `refacil:explore`, `AGENTS.md` is active context throughout the entire exploration.
+
+## `agents` profile
+
+Only requires `AGENTS.md`. If it exists, read it and apply `compact-guidance` if present. If missing: continue with generic baseline and inform the user: *"AGENTS.md not found; run `/refacil:setup` for project rules."*
+
+## BUS-CROSS-REPO.md
+
+Shared protocol for consulting other repositories via `refacil-bus` and for **room agreements** (propose + notification to the requester). Applies in `explore`, `propose`, `verify`, and `bug` when the skill detects a cross-repo dependency or multi-repo coordination. See `BUS-CROSS-REPO.md` (same folder).
+
+If these files are missing, run `refacil-sdd-ai init` to reinstall skills and prereqs.

package/skills/propose/SKILL.md

@@ -1,102 +1,103 @@
----
-name: refacil:propose
-description: Crear una propuesta de cambio completa — delega la exploracion del codebase y la generacion de artefactos al sub-agente refacil-proposer, y maneja la revision humana obligatoria de los artefactos
-user-invocable: true
----
-
-# refacil:propose — Entrypoint de Propuesta de Cambio
-
-Este skill es un **wrapper** que prepara el scope, delega la generacion de artefactos SDD al sub-agente `refacil-proposer`, y maneja la revision humana obligatoria (Human-in-the-Loop). El sub-agente corre en contexto aislado explorando el codebase y generando los artefactos; este wrapper los presenta al usuario para aprobacion.
-
-**Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
-
-## Flujo
-
-### Paso 1: Entender el cambio
-
-Si el usuario NO proporciono suficiente contexto en `$ARGUMENTS`, preguntale:
-- **Que tipo de cambio es?** (feature nuevo, mejora, refactor)
-- **Cual es el problema o necesidad?** (contexto de negocio)
-- **Cual es el objetivo?** (que debe lograr en una oracion)
-
-Si `$ARGUMENTS` ya es claro, no preguntes de nuevo.
-
-### Paso 1.5: Identificador de carpeta del cambio (bloqueante)
-
-El directorio `openspec/changes/<nombre>/` **no puede** usar un `<nombre>` cuyo **primer caracter no sea una letra ASCII** `[a-zA-Z]` — ver **`refacil-prereqs/METHODOLOGY-CONTRACT.md` §9**. Nombres como `2026-04-17-exponer-algo` hacen fallar `openspec status --change` y otros comandos.
-
-**Antes de delegar al sub-agente:**
-
-1. Acuerda o deriva el **slug final** del cambio (kebab-case: `feat-...`, `exponer-...`, `imp-...`, etc.). Fecha o ticket no van al **inicio** del nombre.
-2. Si el usuario propone un nombre invalido, **corrigelo** (p. ej. prefijo `feat-` o `change-`) o pide el slug correcto; **no** delegar hasta tener un nombre valido.
-3. Comunica al usuario el slug final acordado antes de generar.
-
-### Paso 2: Delegar al sub-agente refacil-proposer
-
-Invoca al sub-agente `refacil-proposer` pasandole:
-- `changeName`: el slug valido acordado en el Paso 1.5.
-- `description`: descripcion completa del cambio (del Paso 1 o de `$ARGUMENTS`).
-
-El sub-agente:
-- Lee `openspec-propose/SKILL.md` + `OPENSPEC-DELTAS.md` para seguir las instrucciones de OpenSpec propose con los deltas Refacil.
-- Explora el codebase (lee `AGENTS.md`, detecta archivos y convenciones relevantes) antes de generar.
-- Genera los artefactos bajo `openspec/changes/<changeName>/`: `proposal.md`, especificacion (`specs.md` y/o `specs/**/*.md`), `design.md`, `tasks.md`.
-- Si el cambio involucra contratos cross-repo, lo nota en `design.md`.
-- Retorna UN solo mensaje con el resumen + bloque JSON fenced como ` ```refacil-propose-result `.
-
-Si el cambio surge de un **acuerdo en sala del bus** (`refacil-bus`), indicarselo al sub-agente en la descripcion para que lo tenga en cuenta al generar los artefactos. No acortar el flujo metodologico. Ver `refacil-prereqs/BUS-CROSS-REPO.md` (seccion acuerdos en sala).
-
-### Paso 3: Revision del desarrollador (Human-in-the-Loop — OBLIGATORIO)
-
-Parsea el bloque `refacil-propose-result` del sub-agente para obtener las rutas reales de los artefactos. Presenta al usuario un resumen claro para su revision:
-
-1. **Proposal**: objetivo, alcance y justificacion del cambio.
-2. **Specs**: criterios de aceptacion y rechazo — listar **rutas reales** recibidas en el bloque JSON.
-3. **Design**: archivos a crear/modificar y patrones a usar.
-4. **Tasks**: lista de tareas — verificar que el desglose sea correcto y completo.
-
-Pregunta explicitamente:
-
-```
-=== Revision requerida ===
-Los artefactos estan listos para tu revision:
- - openspec/changes/[nombre]/proposal.md
- - [rutas reales de specs]
- - openspec/changes/[nombre]/design.md
- - openspec/changes/[nombre]/tasks.md
-
-Por favor revisa los artefactos y confirma:
- 1. Los criterios de aceptacion son correctos?
- 2. El design se alinea con la arquitectura del proyecto?
- 3. Las tasks cubren todo el alcance?
-
-Responde "OK" para continuar, o indica que ajustes necesitas.
-```
-
-**NO continuar al Paso 4 hasta que el usuario apruebe explicitamente.**
-
-Si el usuario pide ajustes acotados (cambiar un criterio, corregir una ruta, ajustar una task), aplicalos directamente en los archivos correspondientes y vuelve a presentar el resumen. Si los ajustes son amplios (cambiar el objetivo o el scope completo), re-invoca al sub-agente con la descripcion actualizada.
-
-### Paso 4: Siguiente paso
-
-```
-Propuesta aprobada en: openspec/changes/[nombre]/
-El siguiente paso es implementar las tasks.
-Quieres que continue con /refacil:apply?
-```
-
-## Reglas
-
-- **Nombre de carpeta del cambio**: cumplir siempre **§9** del contrato metodologico (primer caracter letra ASCII; nunca iniciar con digito). Validar ANTES de delegar.
-- **NUNCA escribir, modificar o generar codigo fuente** — solo artefactos SDD.
-- Aunque el usuario pase una descripcion completa en `$ARGUMENTS`, la salida es EXCLUSIVAMENTE artefactos de planificacion.
-- Si el usuario pide que tambien implemente, responder: "La implementacion se hace con `/refacil:apply` despues de aprobar los artefactos."
-- **Siempre delega la generacion al sub-agente**. No repliques aqui la logica de exploracion del codebase ni la generacion de artefactos.
-- **No muestres el bloque JSON al usuario**. Es solo metadata para obtener las rutas reales de los artefactos.
-- **Revision humana es obligatoria** — NO saltar el Paso 3.
-- **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:apply"`. No describirlo en texto ni esperar que el usuario escriba `/refacil:apply`. (Ver `METHODOLOGY-CONTRACT.md §5`.)
-
-## Ver tambien
-
-- Sub-agente: `.claude/agents/refacil-proposer.md` (fuente: `refacil-sdd-ai/agents/proposer.md`)
-- Bus cross-repo: `refacil-prereqs/BUS-CROSS-REPO.md`
+---
+name: refacil:propose
+description: Create a complete change proposal — delegates codebase exploration and artifact generation to the refacil-proposer sub-agent, and handles mandatory human review of the artifacts
+user-invocable: true
+---
+
+# refacil:propose — Change Proposal Entrypoint
+
+This skill is a **wrapper** that prepares the scope, delegates SDD artifact generation to the `refacil-proposer` sub-agent, and handles the mandatory human review (Human-in-the-Loop). The sub-agent runs in an isolated context exploring the codebase and generating the artifacts; this wrapper presents them to the user for approval.
+
+**Prerequisites**: `sdd` profile from `refacil-prereqs/SKILL.md` + rules from `METHODOLOGY-CONTRACT.md`.
+
+## Flow
+
+### Step 0.5: Duplicate exploration guard (CA-11)
+
+Before gathering context or delegating, check the current session conversation for a prior complete exploration report with overlapping scope (same modules, files, or described topic):
+
+- **If a prior complete exploration exists for the same or highly overlapping topic**: summarize the already-known context in 2-3 sentences and ask:
+  ```
+  I already explored [topic] earlier in this session. The key findings were: [summary].
+  Do you want me to run a targeted follow-up, or proceed with the full exploration for this proposal?
+  ```
+  Wait for the user's answer. If they confirm "proceed", continue to Step 1 — do not re-invoke a full exploration automatically.
+- **If there is no prior exploration** for this topic: continue to Step 1 without interruption.
+
+### Step 1: Understand the change
+
+If the user did NOT provide sufficient context in `$ARGUMENTS`, ask:
+- **What type of change is it?** (new feature, improvement, refactor)
+- **What is the problem or need?** (business context)
+- **What is the objective?** (what it must achieve in one sentence)
+
+If `$ARGUMENTS` is already clear, do not ask again.
+
+### Step 1.5: Change folder identifier (blocking)
+
+The `refacil-sdd/changes/<name>/` directory **cannot** use a `<name>` whose **first character is not an ASCII letter** `[a-zA-Z]` — see **`refacil-prereqs/METHODOLOGY-CONTRACT.md` §9**. Names like `2026-04-17-expose-something` cause `refacil-sdd-ai sdd status <name>` and other SDD commands to fail.
+
+**Before delegating to the sub-agent:**
+
+1. Agree on or derive the **final slug** of the change (kebab-case: `feat-...`, `expose-...`, `imp-...`, etc.). Dates or tickets do not go at the **start** of the name.
+2. If the user proposes an invalid name, **correct it** (e.g. `feat-` or `change-` prefix) or ask for the correct slug; **do not** delegate until you have a valid name.
+3. Communicate the final agreed slug to the user before generating.
+
+### Step 2: Delegate to the refacil-proposer sub-agent
+
+Invoke the `refacil-proposer` sub-agent passing it:
+- `changeName`: the valid slug agreed in Step 1.5.
+- `description`: complete description of the change (from Step 1 or from `$ARGUMENTS`).
+
+The sub-agent:
+- Explores the codebase (reads `AGENTS.md`, detects relevant files and conventions) before generating.
+- Generates the artifacts under `refacil-sdd/changes/<changeName>/`: `proposal.md`, specification (`specs.md` and/or `specs/**/*.md`), `design.md`, `tasks.md`.
+- If the change involves cross-repo contracts, notes it in `design.md`.
+- Returns ONE single message with the summary + JSON block fenced as ` ```refacil-propose-result `.
+
+If the change arises from a **bus room agreement** (`refacil-bus`), indicate it to the sub-agent in the description so it takes it into account when generating the artifacts. Do not shorten the methodology flow. See `refacil-prereqs/BUS-CROSS-REPO.md` (room agreements section).
+
+### Step 3: Developer review (Human-in-the-Loop — MANDATORY)
+
+Parse the `refacil-propose-result` block from the sub-agent to get the real artifact paths. Present a clear summary to the user for their review:
+
+1. **Proposal**: objective, scope, and justification of the change.
+2. **Specs**: acceptance and rejection criteria — list **real paths** received in the JSON block.
+3. **Design**: files to create/modify and patterns to use.
+4. **Tasks**: task list — verify the breakdown is correct and complete.
+
+Ask explicitly:
+
+```
+=== Review required ===
+The artifacts are ready for your review:
+ - refacil-sdd/changes/[name]/proposal.md
+ - [real spec paths]
+ - refacil-sdd/changes/[name]/design.md
+ - refacil-sdd/changes/[name]/tasks.md
+
+Please review the artifacts and confirm:
+ 1. Are the acceptance criteria correct?
+ 2. Does the design align with the project architecture?
+ 3. Do the tasks cover the full scope?
+
+Reply "OK" to continue, or indicate what adjustments you need.
+```
+
+**DO NOT continue to Step 4 until the user explicitly approves.**
+
+If the user requests limited adjustments (change a criterion, fix a path, adjust a task), apply them directly to the corresponding files and present the summary again. If the adjustments are broad (changing the objective or the full scope), re-invoke the sub-agent with the updated description.
+
+### Step 4: Next step
+
+```
+Proposal approved at: refacil-sdd/changes/[name]/
+The next step is to implement the tasks.
+Do you want me to continue with /refacil:apply?
+```
+
+## Rules
+
+- **Change folder name**: always comply with **§9** of the methodology contract (first character ASCII letter; never start with a digit). Validate BEFORE delegating.
+- **Always delegate generation to the sub-agent**. Do not replicate the codebase exploration or artifact generation logic here.
+- **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:apply"`. Do not describe it in text or wait for the user to type `/refacil:apply`. (See `METHODOLOGY-CONTRACT.md §5`.)