@tacuchi/agent-workflow-cli 14.6.0 → 14.9.0

package/skills/w/loops/plan-new-loop/SKILL.md

@@ -1,20 +1,16 @@
 ---
 name: plan-new-loop
 description: >-
-  Genera un plan de implementación rico (docs/plans/PPP-plan-<slug>.md) a partir
-  de un spec (docs/specs/NNN-spec-<slug>.md). Heir del chasis spec-refine-loop:
-  reusa íntegro su motor gap-driven convergente, su única session por run,
-  research INLINE, structured-choice con ≤3 preguntas de contenido + 1 control flow
-  (Compactar/Cerrar) siempre presente, research autónomo con regla BD read-only,
-  y artefactos como log vivo (CHECKPOINT siempre, BACKLOG solo si difiere). Sus
-  deltas: el plan absorbe inline el nivel TECHNICAL-NOTE
-  (Solution/Impacted/AS-IS/TO-BE/Validations…) + Phases/Tasks con estado vivo;
-  el research aquí mapea código/impacto (componentes FE/BE/BD, wiring AS-IS,
-  dependencias); y una gap taxonomy propia de planificación. Distingue spec
-  refinado de borrador por la presencia de Refinement decisions/Q&A traceability
-  (si faltan → soft-suggest correr spec-refine antes). Lo arranca el comando
-  /w:plan-new y es reanudable. Invocar cuando un spec deba convertirse en un plan
-  ejecutable antes de implementar.
+  Genera un plan de implementación rico (docs/plans/PPP-plan-<slug>.md) a
+  partir de un spec (docs/specs/NNN-spec-<slug>.md). Heir del chasis spec-
+  refine-loop (motor gap-driven convergente, session única, research inline,
+  structured-choice, artefactos como log vivo); sus deltas viven en el cuerpo:
+  el plan absorbe el nivel TECHNICAL-NOTE + Phases/Tasks con estado vivo,
+  research de mapeo código/impacto, gap taxonomy de planificación, y si el
+  plan incluye UI compone ui-design para autorar design SPECs por pantalla
+  (NNN-SPEC-<SLUG>.md). Si el spec no está refinado sugiere spec-refine antes.
+  Lo arranca /w:plan-new y es reanudable. Invocar cuando un spec deba
+  convertirse en un plan ejecutable antes de implementar.
 ---
 
 # plan-new-loop
@@ -34,7 +30,7 @@ PLAN
 `docs/specs/NNN-spec-*.md` (glob — localiza el spec por número; o la ruta exacta del argumento del comando). **Refinado vs borrador** se distingue por la **presencia** de `## Refinement decisions` / `## Q&A traceability` en el spec: si faltan → **soft-suggest** correr `/w:spec-refine` primero (planificar sobre un spec sólido produce mejores planes), pero el usuario puede proceder.
 
 ## Writes
-`docs/plans/PPP-plan-<slug>.md` (`generate`; **sobrescribe con confirmación** si existe). Solo escribe `docs/plans` — nunca otras carpetas `docs/` ni auto-export.
+`docs/plans/PPP-plan-<slug>.md` (`generate`; **sobrescribe con confirmación** si existe). Solo escribe `docs/plans` — nunca otras carpetas `docs/` ni auto-export. Si el plan **incluye UI**, además produce **design SPECs** (`NNN-SPEC-<SLUG>.md`) como artefactos **de su sesión** (ver *Delta 4* — no son `docs/`, no hay auto-export).
 
 > **slug**: kebab-case corto derivado del Requirement del spec — solo `[a-z0-9-]`, ≤ ~5 palabras / ≤ 40 chars. El CLI solo devuelve el número `PPP`; el loop arma el nombre completo. Para localizar planes, glob `docs/plans/PPP-plan-*.md`.
 
@@ -93,13 +89,18 @@ Reemplaza la gap taxonomy de spec por una orientada a planificación:
 | Deps faltantes | orden no claro | research / humano |
 | Criterios del spec sin cubrir | tareas no trazan a acceptance criteria | la IA deriva + humano confirma |
 | Riesgos sin atender | riesgos técnicos sin mitigar/declarar | humano |
+| UI sin design SPEC *(si aplica)* | el plan incluye UI (FE/pantallas en `Impacted`, `## UI spec` en el spec, o tareas UI) sin `NNN-SPEC-*.md` en la sesión | **capacidad `ui-design`** |
 
 ## Delta 3 — What research investigates here
 
 El research **inline** del chasis se especializa: mapear **código/impacto** — componentes FE/BE/BD afectados, wiring AS-IS, dependencias. Alimenta las secciones `Solution`, `Impacted`, `Current state (AS-IS)`. La regla BD del chasis aplica igual (queries read-only a `SCRIPTS.sql`, MCP elegido vía pregunta de contenido si >1 sin default).
 
+## Delta 4 — Design SPECs (si el plan incluye UI)
+
+El gap **UI sin design SPEC** se resuelve **componiendo** la capacidad **`ui-design`** (default built-in [`ui-spec`](../../roles/ui-spec/SKILL.md); rebindeable vía `.workflow/skills.toml`; `off` → degrada a humano / `Open questions`): autora **un design SPEC por pantalla** como artefacto de la sesión — `NNN-SPEC-<SLUG>.md` (`001-SPEC-MODAL-EXPORT.md`, `002-SPEC-ADMIN-DASHBOARD.md`; numeración local a la sesión, ver [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)). **Deriva** de la sección `## UI spec` del spec si existe (la parte por pantalla y la eleva a detalle ejecutable); si no, autora desde el `Requirement` (design-system/tema/ambigüedades vía *structured-choice*, cuenta en el batch). Las **Tasks UI del plan referencian** la ruta de su SPEC — esa referencia es la fuente de verdad — y `plan-exec-loop` los lee como referencia de diseño. Es el mismo tercer modo de resolución de gap del chasis (junto a *research* y *humano*).
+
 ## Convergence / exit
 
-Sin gaps materiales → **coherence gate** (read-only) = **`Success criteria` en verde** (*verification-first*; es el "convergence gate" del chasis para PLAN-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`. Lo que falle **vuelve como gap** — la trazabilidad criterio→tarea es una **invariante chequeada**, no una sección aparte. Si pasa → *structured-choice* (contenido: `Guardar plan` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, escribe `docs/plans/PPP-plan-<slug>.md` (con confirmación si existe) → `finalize` (persiste `CHECKPOINT`, y `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.
+Sin gaps materiales → **coherence gate** (read-only) = **`Success criteria` en verde** (*verification-first*; es el "convergence gate" del chasis para PLAN-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`; y si el plan incluye UI: cada pantalla/tarea UI **traza a su design SPEC** (`NNN-SPEC-*.md`) y los SPECs no contradicen el `## UI spec` del spec (si existe). Lo que falle **vuelve como gap** — la trazabilidad criterio→tarea es una **invariante chequeada**, no una sección aparte. Si pasa → *structured-choice* (contenido: `Guardar plan` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, escribe `docs/plans/PPP-plan-<slug>.md` (con confirmación si existe) → `finalize` (persiste `CHECKPOINT`, y `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.
 
 > **Después de generar:** el plan puede ir directo a `plan-exec`, o —si surgen cambios antes de ejecutar (nuevos requerimientos, ajustes de alcance)— pasar por [`plan-refine-loop`](../plan-refine-loop/SKILL.md) (`/w:plan-refine`, auxiliar y **no obligatorio**), que lo refina in place.

package/skills/w/loops/plan-refine-loop/SKILL.md

@@ -1,17 +1,15 @@
 ---
 name: plan-refine-loop
 description: >-
-  Refina un plan existente (docs/plans/PPP-plan-<slug>.md) editándolo IN PLACE,
-  como paso auxiliar y NO obligatorio del flujo PLAN antes de plan-exec. Heir del
-  chasis spec-refine-loop: reusa íntegro su motor gap-driven convergente, su única
-  session por run, research INLINE, structured-choice con ≤3 preguntas de contenido
-  + 1 control flow (Compactar/Cerrar) siempre, research autónomo con regla BD
-  read-only, y artefactos como log vivo (CHECKPOINT siempre, BACKLOG solo si
-  difiere). Es a plan-new lo que spec-refine es a spec-new: edita el plan-doc in
-  place (no genera uno nuevo). Reusa la gap taxonomy y el coherence gate de
-  plan-new-loop; agrega Refinement decisions/Q&A traceability al plan (traza, sin
-  contrato de gating: plan-exec corre cualquier plan). Lo arranca /w:plan-refine y
-  es reanudable + re-corrible a demanda. Invocar cuando un plan ya generado deba
+  Refina un plan existente (docs/plans/PPP-plan-<slug>.md) editándolo IN
+  PLACE, como paso auxiliar y NO obligatorio del flujo PLAN antes de plan-
+  exec. Es a plan-new lo que spec-refine es a spec-new. Heir del chasis spec-
+  refine-loop (motor gap-driven, session única, research inline, structured-
+  choice, artefactos como log vivo); reusa la gap taxonomy y el coherence gate
+  de plan-new-loop, agrega Refinement decisions/Q&A traceability al plan
+  (traza, sin gating), y si el refine toca UI compone ui-design y
+  produce/actualiza design SPECs por pantalla. Lo arranca /w:plan-refine;
+  reanudable y re-corrible a demanda. Invocar cuando un plan ya generado deba
   ajustarse antes de ejecutarlo.
 ---
 
@@ -37,7 +35,7 @@ PLAN
 `docs/plans/PPP-plan-*.md` (glob — localiza el plan por número; o la ruta exacta del argumento del comando). **Siempre el plan mismo**: este loop lo edita in place, no hay un archivo "refined" aparte.
 
 ## Writes
-Actualiza `docs/plans/PPP-plan-<slug>.md` **in place** (cuando el usuario elige `Guardar plan refinado`): completa/ajusta secciones y **agrega** `## Refinement decisions` + `## Q&A traceability`. Como sobrescribe un doc existente, **con confirmación** del usuario. Solo escribe `docs/plans` — nunca otras carpetas `docs/` ni auto-export.
+Actualiza `docs/plans/PPP-plan-<slug>.md` **in place** (cuando el usuario elige `Guardar plan refinado`): completa/ajusta secciones y **agrega** `## Refinement decisions` + `## Q&A traceability`. Como sobrescribe un doc existente, **con confirmación** del usuario. Solo escribe `docs/plans` — nunca otras carpetas `docs/` ni auto-export. Si el refine **toca UI**, además produce/actualiza **design SPECs** (`NNN-SPEC-<SLUG>.md`) como artefactos **de su propia sesión** (ver *Delta 4* — no son `docs/`, no hay auto-export).
 
 ## Inherits
 
@@ -69,7 +67,7 @@ Cada duda preguntada al humano + la respuesta elegida.
 
 ## Delta 2 — Gap taxonomy (de "plan")
 
-Reusa **íntegra** la gap taxonomy de [`plan-new-loop`](../plan-new-loop/SKILL.md) (§ *Delta 2*): Approach/Solution vago, componentes sin identificar, wiring AS-IS desconocido, fase muy grande, tarea no atómica, deps faltantes, criterios del spec sin cubrir, riesgos sin atender. **Diferencia de foco:** plan-new **construye** el plan desde cero; plan-refine **detecta qué cambió** respecto del plan ya escrito (o respecto del spec, si el spec se re-refinó) y cierra **esos** gaps — típicamente menos y más localizados. Un gap extra propio del re-refine:
+Reusa **íntegra** la gap taxonomy de [`plan-new-loop`](../plan-new-loop/SKILL.md) (§ *Delta 2*): Approach/Solution vago, componentes sin identificar, wiring AS-IS desconocido, fase muy grande, tarea no atómica, deps faltantes, criterios del spec sin cubrir, riesgos sin atender, UI sin design SPEC. **Diferencia de foco:** plan-new **construye** el plan desde cero; plan-refine **detecta qué cambió** respecto del plan ya escrito (o respecto del spec, si el spec se re-refinó) y cierra **esos** gaps — típicamente menos y más localizados. Un gap extra propio del re-refine:
 
 | Gap | Signal | Resolved by |
 |---|---|---|
@@ -79,6 +77,10 @@ Reusa **íntegra** la gap taxonomy de [`plan-new-loop`](../plan-new-loop/SKILL.m
 
 Igual que plan-new (mapea código/impacto: componentes FE/BE/BD, wiring AS-IS, deps), pero **acotado al delta**: re-verifica solo lo que el cambio toca (no re-mapea todo el plan). Regla BD del chasis igual (read-only a `SCRIPTS.sql`, MCP vía pregunta si >1 sin default).
 
+## Delta 4 — Design SPECs (si el refine toca UI)
+
+Mismo mecanismo que [`plan-new-loop`](../plan-new-loop/SKILL.md) (§ *Delta 4*: capacidad **`ui-design`** → `NNN-SPEC-<SLUG>.md` por pantalla, ver [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)), **acotado al delta**: solo las pantallas **nuevas o cambiadas** por el refine reciben design SPEC. El SPEC actualizado se escribe en **la sesión propia** del plan-refine (cada loop maneja los artefactos de SU sesión — no edita los de la sesión de plan-new) y el plan **re-apunta** la referencia de la Task UI al SPEC vigente. Pantallas no tocadas conservan su SPEC original.
+
 ## Compact / resume
 
 El resume **keya off el `CHECKPOINT`** de la refine session, no de un archivo "refined". Tres casos al ejecutar `/w:plan-refine` sobre un plan:
@@ -91,4 +93,4 @@ El resume **keya off el `CHECKPOINT`** de la refine session, no de un archivo "r
 
 ## Convergence / exit
 
-Sin gaps materiales → **coherence gate** (read-only) = **`Success criteria` en verde** (*verification-first*; el "convergence gate" del chasis para PLAN, mismo que plan-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`, y —propio del re-refine— **el plan quedó realineado** con lo que cambió. Lo que falle **vuelve como gap**. Si pasa → *structured-choice* (contenido: `Guardar plan refinado` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, edita `docs/plans/PPP-plan-<slug>.md` in place (con confirmación) + inserta `Refinement decisions`/`Q&A traceability` → `finalize` (persiste `CHECKPOINT`; `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.
+Sin gaps materiales → **coherence gate** (read-only) = **`Success criteria` en verde** (*verification-first*; el "convergence gate" del chasis para PLAN, mismo que plan-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`, si hay UI cada pantalla/tarea UI **traza a su design SPEC vigente**, y —propio del re-refine— **el plan quedó realineado** con lo que cambió. Lo que falle **vuelve como gap**. Si pasa → *structured-choice* (contenido: `Guardar plan refinado` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, edita `docs/plans/PPP-plan-<slug>.md` in place (con confirmación) + inserta `Refinement decisions`/`Q&A traceability` → `finalize` (persiste `CHECKPOINT`; `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.

package/skills/w/loops/quick-loop/SKILL.md

@@ -1,19 +1,15 @@
 ---
 name: quick-loop
 description: >-
-  El atajo liviano de agent-workflow: resuelve una tarea acotada (un fix, un
-  ajuste pequeño) directamente desde el prompt del usuario, editando código con
-  ceremonia mínima. Heir del chasis spec-refine-loop (motor gap-driven mínimo,
-  research INLINE con regla BD read-only, structured-choice con ≤3 preguntas de
-  contenido + 1 control flow Compactar/Cerrar siempre, compact/resume con artefactos
-  como log vivo: CHECKPOINT siempre, BACKLOG solo si difiere) y de plan-exec-loop
-  (git seguro: rama esperada antes de editar + commit propuesto, nunca
-  push/--amend/--no-verify; la IA nunca ejecuta DML, migraciones a SCRIPTS.sql;
-  sin auto-export). Sus deltas: sin fases ni plan-doc (el prompt ES la tarea),
-  una sola session ligera (<slug>-quick), un solo commit; y escalación con
-  handoff si la tarea crece (propone subir a SPEC/PLAN dejando el código a
-  medias como contexto). NO toca docs/. Lo arranca /w:quick y es reanudable.
-  Invocar para cambios pequeños y directos que no ameritan spec ni plan formal.
+  El atajo liviano de agent-workflow: resuelve una tarea acotada (fix, ajuste
+  chico) directamente desde el prompt, editando código con ceremonia mínima.
+  Heir del chasis spec-refine-loop y de plan-exec-loop (git seguro, BD solo-
+  scripts, gate de revisión de cierre proporcional, sin auto-export); sus
+  deltas viven en el cuerpo: sin fases ni plan-doc (el prompt ES la tarea),
+  session ligera única (<slug>-quick), un solo commit, y escalación con
+  handoff a SPEC/PLAN si la tarea crece. NO toca docs/. Lo arranca /w:quick y
+  es reanudable. Invocar para cambios pequeños y directos que no ameritan spec
+  ni plan formal.
 ---
 
 # quick-loop
@@ -44,7 +40,7 @@ QUICK
 ## Inherits
 
 - del **chasis** [`spec-refine-loop`](../spec-refine-loop/SKILL.md): **objetivo persistente** (acá el más directo: el prompt *es* el objetivo) + **verification-first** (`SESSION.Success criteria` proporcional), gap-driven (mínimo), *structured-choice* ≤3 preguntas de contenido + 1 control `flow` (`Compactar`/`Cerrar`) (capacidad del arnés — ver [`../../harness/SKILL.md`](../../harness/SKILL.md); en Claude Code es `AskUserQuestion`), `research` **inline** + regla BD read-only (pregunta MCP si >1 sin default → `SCRIPTS.sql` → ejecuta read-only), compact/resume, **artefactos como log vivo (ciclo artifact-first)** (`CHECKPOINT` siempre; `BACKLOG` solo si difiere).
-- de [`plan-exec-loop`](../plan-exec-loop/SKILL.md): **git** (rama segura antes de editar + commit propuesto; nunca `push`/`--amend`/`--no-verify`), **BD** (la IA nunca ejecuta DML; migraciones → `SCRIPTS.sql` de la session), **sin auto-export** (no toca otras carpetas `docs/`).
+- de [`plan-exec-loop`](../plan-exec-loop/SKILL.md): **git** (rama segura antes de editar + commit propuesto; nunca `push`/`--amend`/`--no-verify`), **BD** (la IA nunca ejecuta DML; migraciones → `SCRIPTS.sql` de la session), **sin auto-export** (no toca otras carpetas `docs/`), y el **gate de revisión de cierre** (§ *Delta 5* de plan-exec) en versión **proporcional**: antes de proponer el único commit, re-lectura del diff aplicando las convenciones ambientes instaladas → corregir o diferir justificado.
 
 ## Composes
 
@@ -56,7 +52,7 @@ QUICK
 
 - **Sin fases, sin plan-doc**: el prompt **es** la tarea (una sola unidad). No hay roadmap.
 - **Verification-first proporcional** (ceremonia mínima): aun acá se **siembra el check antes**, del tamaño de la tarea. Código: un test (repro del bug → fix) o "build/lint/tests existentes siguen verdes" (chore). **Análisis/diseño**: una **rúbrica falsable corta**, *ratificada por el usuario* antes de perseguirla. Es el `SESSION.Success criteria` del run (ver [chasis § Verification-first](../spec-refine-loop/SKILL.md)).
-- **Una sola session**. **Un solo commit** propuesto al final (solo si hubo cambios de código).
+- **Una sola session**. **Un solo commit** propuesto al final (solo si hubo cambios de código), **tras el gate de revisión de cierre proporcional** (heredado de plan-exec § *Delta 5*): re-lectura del diff + convenciones ambientes; corregir o diferir; nada llega al commit sin revisar.
 - **Escalación + handoff**: si la tarea crece (muchos archivos / ≥2 fuentes / necesita arquitectura) → propone subir a **SPEC/PLAN**. Si el usuario acepta:
   - el **código ya editado queda** en el working tree (no se revierte) **y se registra** en `CHECKPOINT` + `BACKLOG` ("cambios sin commitear en `<fuente>` — código a medias; decidir commit/descartar al retomar") — reusando **ambas** mitades del patrón "commit rechazado" de plan-exec (no revertir **y** registrar lo sin commitear). Crítico en la rama **SPEC**, que no retoma el working tree;
   - la session quick va a `finalize`, persistiendo `CHECKPOINT` + `BACKLOG` con un **puntero** al spec/plan sembrado (Followups: "escalado a `docs/specs/NNN` o `docs/plans/PPP` — retomar ahí");
@@ -91,7 +87,10 @@ quick-loop(prompt):
     si la tarea CRECE → proponer escalar a SPEC/PLAN
         si acepta → handoff (avance queda; BACKLOG→spec/plan sembrado) → goto finalize
   convergence gate: Success criteria en verde                # tests verdes si código · rúbrica satisfecha si análisis/diseño
-  si hubo cambios de código → proponer commit (aprobar antes)   # nunca push/amend/--no-verify
+  si hubo cambios de código:
+    gate de revisión de cierre (proporcional):               # re-lectura del diff + convenciones ambientes instaladas
+        hallazgos → corregir (re-validar) ó diferir justificado (BACKLOG)
+    proponer commit (aprobar antes)                          # nunca push/amend/--no-verify; solo tras el gate
   structured_choice(contenido: [Cerrar tarea, Preguntar algo más], flow: [Compactar, Cerrar])
 finalize: CHECKPOINT (DESPUÉS: Pending→Completed) + BACKLOG (solo si queda algo diferido) + cerrar session + reportar
 ```
@@ -106,14 +105,15 @@ flowchart TD
     GROW -->|sí| ESC["escalar a SPEC/PLAN<br/>avance queda · BACKLOG→spec/plan sembrado"]
     ESC --> FIN
     GROW -->|no| V["convergence gate:<br/>Success criteria en verde"]
-    V --> CM["si hubo código → proponer commit (aprobar)"]
+    V --> RV["si hubo código → gate de revisión de cierre<br/>(diff + convenciones ambientes → corregir/diferir)"]
+    RV --> CM["proponer commit (aprobar)"]
     CM --> Q["structured-choice[Cerrar · Preguntar más]<br/>flow[Compactar · Cerrar]"]
     Q --> FIN["finalize: CHECKPOINT + BACKLOG + cerrar"]
 ```
 
 ## Convergence / exit
 
-- **Success criteria en verde** (proporcional) + commit propuesto si hubo código (o aprobado saltarlo) → `Cerrar`.
+- **Success criteria en verde** (proporcional) + gate de revisión de cierre pasado y commit propuesto si hubo código (o aprobado saltarlo) → `Cerrar`.
 - `Cerrar`/`Compactar` (control `flow`) → persiste `CHECKPOINT` + `BACKLOG` (reanudable).
 - **Sin export**: nada va a `docs/`. Si algo amerita preservarse → se promueve aparte vía `export-*`, o se escala a SPEC/PLAN.
 

package/skills/w/loops/spec-refine-loop/SKILL.md

@@ -123,6 +123,8 @@ El **CLI es dueño del número**: `aw session-create` antepone un `NNN` **global
 
 El gap **UI sin especificar** (cuando el requerimiento involucra UI; ver *Gap taxonomy*) se resuelve **componiendo** la capacidad **`ui-design`** (default built-in `ui-spec`; rebindeable vía `.workflow/skills.toml`): autora el UI spec nativamente (estructura, vocabulario, formato Markdown). Es un tercer modo de resolución de gap (junto a *research* y *humano*): el loop aporta la iteración/Q&A que el viejo servicio no tenía (design-system, tema, variantes, desambiguación) **vía la misma structured-choice**, y lo integra como sección `## UI spec` del spec.
 
+> **Dos niveles de la misma capacidad:** aquí (SPEC) produce la sección `## UI spec` del spec — el *qué* de la UI, grano grueso. En PLAN, `plan-new-loop`/`plan-refine-loop` componen la **misma** capacidad para producir **design SPECs por pantalla** (`NNN-SPEC-<SLUG>.md`, artefactos de su sesión — ver [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)), derivados de esta sección si existe.
+
 Otras capacidades transversales que el chasis usa siempre: `research` (research **inline**, ver abajo), `sql` (regla BD en research). Todas se resuelven por config; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta. La **prosa del spec** sigue las convenciones de redacción **ambientes** (el host auto-aplica una skill de writing instalada si está presente), no un rol compuesto.
 
 > **Convenciones ambientes (no roles).** Los estándares de código, testing, redacción **y la creación de herramientas** (`creating-tools`) **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Familias útiles viven en plugins del marketplace (`dev-conventions`, `tool-builder`), pero el workflow **no depende** de ellos.

package/skills/w/roles/README.md

@@ -12,7 +12,7 @@ All 6 roles, their built-in defaults, their tier, and which loops/exports compos
 
 | Role | Default built-in | Tier | Composed by |
 |---|---|---|---|
-| `ui-design` | [`ui-spec`](ui-spec/SKILL.md) | must | `spec-refine-loop` (when requirement involves UI) |
+| `ui-design` | [`ui-spec`](ui-spec/SKILL.md) | must | `spec-refine-loop` (when requirement involves UI) · `plan-new-loop` / `plan-refine-loop` (per-screen design SPECs) |
 | `sql` | `sql` | must | inline research · `plan-exec-loop` · `quick-loop` · `export-scripts` |
 | `git` | `git` | must | `plan-exec-loop` · `quick-loop` |
 | `research` | [`research`](research/SKILL.md) | should | all loops (on-demand investigation) |
@@ -24,6 +24,8 @@ All 6 roles, their built-in defaults, their tier, and which loops/exports compos
 - `should` — loaded on-demand; active by default but lower priority to override.
 
 > **Convenciones ambientes (no roles).** Los estándares de código, testing, redacción **y la creación de herramientas** (`creating-tools`) **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Familias útiles viven en plugins del marketplace (`dev-conventions`, `tool-builder`), pero el workflow **no depende** de ellos.
+>
+> **La revisión de cierre tampoco es un rol** (decisión deliberada — se evaluó y descartó un rol `conventions`/`rules`/`review`): el **gate de revisión de cierre** de `plan-exec-loop`/`quick-loop` (pre-commit) es un **paso del loop**; el loop crea el **momento** y las convenciones ambientes instaladas lo llenan. Un rol que "señale las skills del marketplace" re-acoplaría lo que esta extracción desacopló.
 
 ---
 

package/skills/w/roles/ui-spec/SKILL.md

@@ -5,9 +5,12 @@ description: >-
   requirement, author a structured, framework-agnostic screen specification as
   **Markdown** (single output format). Knows the conceptual screen structure, the
   kind/region vocabulary, the authoring rules, design-system / theme / variant
-  handling, and the exact Markdown render format. Use when a loop is refining a spec
-  that involves screens, forms, dashboards, modals or any UI surface — primarily
-  `spec-refine-loop`. Recycled from the `ui-spec-generator` service.
+  handling, and the exact Markdown render format. Two landing zones, same render:
+  in SPEC (`spec-refine-loop`) it authors the `## UI spec` section of the spec doc;
+  in PLAN (`plan-new-loop`/`plan-refine-loop`) it authors per-screen **design
+  SPECs** (`NNN-SPEC-<SLUG>.md`) as session artifacts. Use when a loop is refining
+  a spec or building/refining a plan that involves screens, forms, dashboards,
+  modals or any UI surface. Recycled from the `ui-spec-generator` service.
 ---
 
 # ui-spec — UI spec authoring
@@ -22,13 +25,18 @@ Dado un requerimiento de UI, autorar una **descripción estructurada en Markdown
 
 ## Composed by
 
-La carga el **`spec-refine-loop`** (ver `../../loops/spec-refine-loop/SKILL.md`) al resolver el gap **UI sin especificar** (cuando el requerimiento involucra UI). El loop aporta lo que el servicio viejo no tenía:
+Dos niveles, misma capacidad:
+
+- **`spec-refine-loop`** (ver `../../loops/spec-refine-loop/SKILL.md`) — al resolver el gap **UI sin especificar** (cuando el requerimiento involucra UI): autora la sección `## UI spec` **del spec** (el *qué* de la UI, pantallas a grano grueso).
+- **`plan-new-loop` · `plan-refine-loop`** (ver `../../loops/plan-new-loop/SKILL.md` § *Delta 4*) — al resolver el gap **UI sin design SPEC** (cuando el **plan incluye UI**): autora **design SPECs** por pantalla (`NNN-SPEC-<SLUG>.md`) como **artefactos de la sesión de PLAN** (ver `../../artifacts/artifacts-design/SPEC.md`); derivan de `## UI spec` si existe.
+
+En ambos, el loop aporta lo que el servicio viejo no tenía:
 
 - **Pregunta al humano** (design-system, tema, ambigüedades de pantalla) vía *structured-choice* (capacidad del arnés — ver `../../harness/SKILL.md`). En **Claude Code** es `AskUserQuestion` (máx 4 preguntas/llamada → **≤3 preguntas de contenido + 1 control `flow`**); en un arnés sin elección estructurada, degrada a **markdown numerado**.
 - **Itera** gap-driven hasta converger.
 - Ofrece **variantes** y **cura** el resultado.
 
-Cualquier loop podría componerla; el caso primario es SPEC. La descripción Markdown aterriza como una sección dentro del documento spec (`docs/specs/NNN-spec-<slug>.md`) — nunca como artefacto suelto (invariante 3: el spec es un documento).
+Cualquier loop podría componerla; los casos primarios son SPEC y PLAN. En SPEC, la descripción aterriza como sección del documento spec (`docs/specs/NNN-spec-<slug>.md`) — el spec sigue siendo un documento (invariante 3). En PLAN aterriza como **design SPECs** (artefactos de sesión) — que **no** son el requirement-spec: son el detalle de diseño por pantalla, de proceso.
 
 ## Knowledge
 
@@ -114,9 +122,16 @@ Si el humano no responde, asumir el caso más simple coherente con la descripci
 - **Registros** (table)
 ```
 
-## Output — sección `## UI spec` dentro del spec (`docs/specs/NNN-spec-<slug>.md`)
+## Output — dos aterrizajes, un solo formato (Markdown)
+
+**Salida en un solo formato: Markdown.** La escribe el loop (no esta skill por sí sola). El **render es el mismo** en ambos niveles; cambia dónde aterriza, según el loop que compone:
+
+| Loop que compone | Aterriza en | Grano |
+|---|---|---|
+| `spec-refine-loop` | sección `## UI spec` **del spec** (`docs/specs/NNN-spec-<slug>.md`) — documento, in place | todas las pantallas del requerimiento, grano grueso |
+| `plan-new-loop` · `plan-refine-loop` | **design SPECs** `NNN-SPEC-<SLUG>.md` — artefactos en la **sesión de PLAN** (uno **por pantalla**, con encabezado de traza; ver `../../artifacts/artifacts-design/SPEC.md`) | una pantalla por archivo, detalle ejecutable |
 
-**Salida en un solo formato: Markdown.** La escribe el loop (no esta skill por sí sola). Encabezar la sección con las opciones de diseño elegidas (design system, tema, idioma) en una línea. Luego el render Markdown, con estas reglas exactas (recicladas del `MarkdownFormatter`):
+Encabezar la sección (o el encabezado de traza del SPEC) con las opciones de diseño elegidas (design system, tema, idioma) en una línea. Luego el render Markdown, con estas reglas exactas (recicladas del `MarkdownFormatter`):
 
 - `# {nombre}`
 - `**Tipo**: {tipo} | **Plataforma**: {plataforma}`