@tacuchi/agent-workflow-cli 15.1.0 → 16.0.0

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

@@ -1,178 +1,174 @@
 ---
 name: spec-refine-loop
 description: >-
-  Refina un spec borrador (docs/specs/NNN-spec-<slug>.md) editándolo IN PLACE
-  hasta dejarlo sin ambigüedad. Heir del chasis común de los loops
-  (loops/CHASSIS.md — motor gap-driven convergente: session única con research
-  inline, structured-choice ≤3 preguntas + control flow, artefactos como log
-  vivo, compact/resume, convergence gate); aquí viven solo sus deltas SPEC:
-  gap taxonomy de spec, analyze gate, sección ## UI spec vía la capacidad
-  ui-design cuando el requerimiento involucra UI, y agrega Refinement
-  decisions + Q&A traceability al spec — la marca de refinado que plan-new
-  detecta. Lo arranca /w:spec-refine (o la escalación en vivo desde
-  quick-loop); reanudable vía CHECKPOINT y re-corrible a demanda. Invocar cuando haya que refinar/desambiguar una especificación
-  antes de planificar.
+  Refines a draft spec (docs/specs/NNN-spec-<slug>.md) by editing it IN PLACE
+  until it is unambiguous. Heir of the chassis (loops/CHASSIS.md). Deltas:
+  spec gap taxonomy, analyze gate, ## UI spec section via the ui-design
+  capability, and adds Refinement decisions + Q&A traceability — the refined
+  mark plan-new detects. Started by /w:spec-refine (or the live escalation
+  from quick-loop); resumable via CHECKPOINT and re-runnable on demand.
+  Invoke to refine/disambiguate a specification before planning.
 ---
 
 # spec-refine-loop
 
-> **Heir** del chasis común — aquí **solo** los deltas de SPEC. El motor no se repite.
+> **Heir** of the common chassis — **only** the SPEC deltas live here. The engine is never repeated.
 
 ## Inherits
 
-Leé **[`../CHASSIS.md`](../CHASSIS.md)** (instalación normal) **o** `CHASSIS.md` junto a este archivo (instalación aplanada) — el motor completo del loop (objetivo persistente + verification-first, gap-driven, session única + research inline, structured-choice + control `flow`, compact/resume, artefactos como log vivo, numeración, convergence gate), **siempre antes** de estos deltas.
+Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **always before** these deltas. *(If `../` does not resolve: `CHASSIS.md` next to this file — global layout rule, chassis § Reference resolution.)*
 
 ## Flow
 SPEC
 
 ## Layer
-2 — la IA lo corre entero (gap-driven). El usuario no conduce el ciclo; solo responde preguntas de contenido y dirige el ciclo de vida por el control `flow`.
+2 — the AI runs it end to end (gap-driven). The user does not drive the cycle; they only answer content questions and steer the lifecycle via the `flow` control.
 
 ## Started by
-`/w:spec-refine` — **reanudable**. Detecta el estado previo (vía CHECKPOINT) y arranca según corresponda (ver *Compact / resume — claves SPEC*).
+`/w:spec-refine` — **resumable**. Detects prior state (via CHECKPOINT) and starts accordingly (see *Compact / resume — SPEC keys*).
 
-También lo arranca la **escalación en vivo desde `quick-loop`** (gate de entrada o mid-loop — ver [`../quick-loop/SKILL.md`](../quick-loop/SKILL.md) § *Delta QUICK*): quick materializa el borrador (procedimiento de `spec-new`) y **carga este loop** sobre ese spec — misma semántica que si el usuario hubiera corrido `/w:spec-refine`.
+It is also started by the **live escalation from `quick-loop`** (entry gate or mid-loop — see [`../quick-loop/SKILL.md`](../quick-loop/SKILL.md) § *QUICK delta*): quick materializes the draft (`spec-new` procedure) and **loads this loop** over that spec — same semantics as if the user had run `/w:spec-refine`.
 
 ## Reads
-- `docs/specs/NNN-spec*.md` (glob — localiza el spec por número, también captura el legacy `NNN-spec.md`), **o** la ruta exacta pasada en el argumento del comando. **Siempre el spec mismo**: este loop lo edita in place, no hay un archivo "refined" aparte.
+- `docs/specs/NNN-spec*.md` (glob — locates the spec by number; also catches the legacy `NNN-spec.md`), **or** the exact path passed as the command argument. **Always the spec itself**: this loop edits it in place; there is no separate "refined" file.
 
 ## Writes
-Actualiza `docs/specs/NNN-spec-<slug>.md` **in place** (cuando el usuario elige `Guardar especificación refinada`): completa secciones y **agrega** `## Refinement decisions` + `## Q&A traceability`, cerrando `Open questions` a medida que se resuelven. Como sobrescribe un doc existente, **con confirmación** del usuario.
+Updates `docs/specs/NNN-spec-<slug>.md` **in place** (when the user picks `Guardar especificación refinada`): completes sections and **adds** `## Refinement decisions` + `## Q&A traceability`, closing `Open questions` as they get resolved. Since it overwrites an existing doc, it asks the user's **confirmation**.
 
-> **Invariante de boundary:** este loop escribe **solo** en `docs/specs`. Nunca gradúa/exporta otros artefactos a `docs/` — eso es trabajo de `export-*`, aparte (chasis § *docs/ boundary*).
+> **Boundary invariant:** this loop writes **only** into `docs/specs`. It never graduates/exports other artifacts to `docs/` — that is separate `export-*` work (chassis § *docs/ boundary*).
 
-## Internal sessions — instancia SPEC
+## Internal sessions — SPEC instance
 
-Doctrina completa en el chasis (§ *Internal sessions* + *Numeración*). La instancia de este loop:
+Full doctrine in the chassis (§ *Internal sessions* + *Numbering*). This loop's instance:
 
 | Session | When | Artifacts | Role |
 |---|---|---|---|
-| **refine session** `NNN-<slug>-spec-refine/` | al arrancar el loop (o se reanuda) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` solo si difiere) | Dueña del run. Type = `refine`; descriptor `<slug>-spec-refine` (el `<slug>` sale del spec de entrada). |
+| **refine session** `NNN-<slug>-spec-refine/` | when the loop starts (or resumes) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` only if something is deferred) | Owns the run. Type = `refine`; descriptor `<slug>-spec-refine` (the `<slug>` comes from the input spec). |
 
-> **Origin por escalación:** si el run nace de la escalación en vivo de `quick-loop`, el `## Origin` de la session registra "escalado desde `/w:quick`" + la session quick de origen si existe (sus `DECISION`/`SCRIPTS.sql` son contexto referenciable — no se migran).
+> **Origin on escalation:** when the run is born from quick-loop's live escalation, the session's `## Origin` records "escalated from `/w:quick`" + the origin quick session if it exists (its `DECISION`/`SCRIPTS.sql` are referenceable context — never migrated).
 
-> **Compat (legacy):** workspaces viejos pueden tener `NNN-spec.md` / `NNN-spec-refined.md` y sessions `*-research-*` aparte — son históricos y se dejan tal cual. El glob `NNN-spec*.md` igual encuentra el spec base, y re-correr spec-refine lo edita in place de ahí en adelante.
+> **Compat (legacy):** old workspaces may hold `NNN-spec.md` / `NNN-spec-refined.md` and separate `*-research-*` sessions — historical, left as-is. The `NNN-spec*.md` glob still finds the base spec, and re-running spec-refine edits it in place from then on.
 
 ## Composes
 
-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.
+The **UI unspecified** gap (when the requirement involves UI; see *Gap taxonomy*) is resolved by **composing** the **`ui-design`** capability (built-in default `ui-spec`; rebindable via `.workflow/skills.toml`): it authors the UI spec natively (structure, vocabulary, Markdown format). It is a third gap-resolution mode (next to *research* and *human*): the loop contributes iteration/Q&A (design system, theme, variants, disambiguation) **via the same structured-choice**, and integrates the result as the spec's `## UI spec` section.
 
-> **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.
+> **Two levels of the same capability:** here (SPEC) it produces `## UI spec` — the UI's *what*, coarse grain; in PLAN the plan loops produce **per-screen design SPECs** derived from that section (see [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)).
 
-Otras capacidades transversales que el motor usa siempre: `research` (research **inline** — chasis § *Research*), `sql` (regla BD en research — chasis). 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.
+Other transversal capabilities the engine always uses: `research` (**inline** — chassis § *Research*), `sql` (DB rule inside research — chassis). All resolved by config; `off` → the loop continues without the capability and, if it was needed, says so or asks. The spec's **prose** follows the **ambient** writing conventions (the host auto-applies an installed writing skill if present), not a composed role.
 
-> **Convenciones ambientes (no roles):** estándares de código/testing/redacción y `creating-tools` son skills standalone que el host auto-descubre por su `description` — el workflow no las bindea ni depende de ellas. Doctrina completa: [../../roles/README.md](../../roles/README.md).
+> **Ambient conventions (not roles):** code/testing/writing standards and `creating-tools` are standalone skills the host auto-discovers by `description` — the workflow neither binds nor depends on them. Full doctrine: [../../roles/README.md](../../roles/README.md).
 
-## Deliverable schema (el spec, editado in place)
+## Deliverable schema (the spec, edited in place)
 
-El spec se completa **in place**: mismas secciones del borrador **completadas** + dos nuevas que se **agregan** (`Refinement decisions`, `Q&A traceability`). NO se crea un archivo aparte.
+The spec is completed **in place**: the draft's sections get **completed** + two new ones are **added** (`Refinement decisions`, `Q&A traceability`). NO separate file is created.
 
 ```markdown
 # Spec NNN — <slug>
 
-> Refinado in place por spec-refine-loop
+> Refined in place by spec-refine-loop
 
-## Origin                 (opt. — se conserva del borrador)
-## Requirement            (afinado, sin ambigüedad)
-## Context                (completo)
-## Scope                  (In / Out claros)
-## Acceptance criteria    (testables, - [ ]; estilo EARS / Given-When-Then recomendado)
-## Assumptions            (declarados)
+## Origin                 (opt. — preserved from the draft)
+## Requirement            (sharpened, unambiguous)
+## Context                (complete)
+## Scope                  (clear In / Out)
+## Acceptance criteria    (testable, - [ ]; EARS / Given-When-Then style recommended)
+## Assumptions            (declared)
 
-## UI spec                (opt. — si involucra UI; vía capacidad ui-design / skill ui-spec)
-Descripción estructurada en Markdown (pantallas → regiones/componentes). Ver [`ui-spec`](../../roles/ui-spec/SKILL.md).
+## UI spec                (opt. — if UI is involved; via the ui-design capability / ui-spec skill)
+Structured Markdown description (screens → regions/components). See [`ui-spec`](../../roles/ui-spec/SKILL.md).
 
-## Refinement decisions   ← NEW (se AGREGA)
-Qué se definió al refinar y por qué. Incluye lo resuelto vía research inline
-(con referencia a las CONCLUSIONS de la session).
+## Refinement decisions   ← NEW (ADDED)
+What was defined while refining and why. Includes what inline research
+resolved (with a reference to the session's CONCLUSIONS).
 
-## Q&A traceability       ← NEW (se AGREGA)
-Cada duda preguntada al humano + la respuesta elegida.
+## Q&A traceability       ← NEW (ADDED)
+Every doubt asked to the human + the chosen answer.
 
-## Open questions         (idealmente "None"; lo que quede se difiere)
+## Open questions         (ideally "None"; whatever remains is deferred)
 ```
 
-> **Marca de refinado (contrato con PLAN):** la presencia de `## Refinement decisions` + `## Q&A traceability` distingue un spec refinado de un borrador — plan-new lo detecta así, NO por el nombre del archivo; sin esas 2 secciones plan-new hace soft-suggest de spec-refine.
+> **Refined mark (contract with PLAN):** the presence of `## Refinement decisions` + `## Q&A traceability` distinguishes a refined spec from a draft — plan-new detects it this way, NOT by filename; without those 2 sections plan-new soft-suggests spec-refine.
 
-> **Acceptance criteria = criterios testables estáticos** (el "qué"): plan-exec los valida pero el avance se trackea en el PLAN (sus Tasks), no marcando estos `- [ ]` en el spec; el spec no muta por ejecución, solo por re-refine.
+> **Acceptance criteria = static testable criteria** (the "what"): plan-exec validates them, but progress is tracked in the PLAN (its Tasks), never by ticking these `- [ ]` in the spec; the spec never mutates by execution, only by a re-refine.
 
 ## Gap taxonomy (= weak sections of the schema)
 
-`detect_gaps(work)` busca estas señales; cada una tiene un resolutor:
+`detect_gaps(work)` looks for these signals; each has a resolver:
 
 | Gap | Signal | Resolved by |
 |---|---|---|
-| Requirement vago | el qué/por qué ambiguo | **humano** |
-| Context incompleto | sistemas/componentes sin identificar | **research** |
-| Scope borroso | falta `Out`, o In/Out se solapan | **humano** |
-| Criterios no testables | acceptance no verificable | **humano** (derivar + confirmar) |
-| Open questions abiertas | dudas explícitas | según naturaleza |
-| Supuestos ocultos | el spec asume cosas no dichas | **research** valida / **humano** confirma |
-| Contradicción interna | secciones que se contradicen | **humano** |
-| UI sin especificar *(si aplica)* | el requerimiento involucra UI pero falta `## UI spec` | **capacidad `ui-design`** |
+| Vague requirement | the what/why is ambiguous | **human** |
+| Incomplete context | systems/components unidentified | **research** |
+| Blurry scope | `Out` missing, or In/Out overlap | **human** |
+| Untestable criteria | acceptance not verifiable | **human** (derive + confirm) |
+| Open questions pending | explicit doubts | by nature |
+| Hidden assumptions | the spec assumes unstated things | **research** validates / **human** confirms |
+| Internal contradiction | sections contradict each other | **human** |
+| UI unspecified *(if it applies)* | the requirement involves UI but `## UI spec` is missing | **`ui-design` capability** |
 
 ## Sequence
 
 ```
 spec-refine-loop(spec):
-  input = glob(NNN-spec*.md) | argumento (ruta)         # siempre el spec mismo (in place)
-  refine_session = create_or_resume("<slug>-spec-refine") # <slug> del spec de entrada; CLI antepone NNN global; resume localiza por descriptor/origin
-  seed SESSION.Success criteria = acceptance criteria + checklist del analyze gate   # verification-first: ANTES de iterar
-  work = read(input)  (+ aplicar avance del checkpoint si reanuda)
-  attempts = {}                                         # anti-relanzamiento por gap
+  input = glob(NNN-spec*.md) | argument (path)          # always the spec itself (in place)
+  refine_session = create_or_resume("<slug>-spec-refine") # <slug> from the input spec; CLI prepends global NNN; resume locates by descriptor/origin
+  seed SESSION.Success criteria = acceptance criteria + analyze-gate checklist   # verification-first: BEFORE iterating
+  work = read(input)  (+ apply checkpoint progress if resuming)
+  attempts = {}                                          # anti re-fire per gap
   repeat:
-    gaps = detect_gaps(work)  menos los gaps "agotados"
+    gaps = detect_gaps(work)  minus the "exhausted" gaps
     if gaps == ∅: break
     batch = top ≤3 gaps ; pending_human = []
-    seed CHECKPOINT.Pending/Next = batch (refine_session) # ANTES: sembrar intención (artifact-first)
-    para cada gap en batch:
-      si gap = UI (requerimiento con UI, falta ## UI spec):
-        componer ui-design → autora ## UI spec   # design-system/tema vía structured-choice (cuenta en el batch)
+    seed CHECKPOINT.Pending/Next = batch (refine_session) # BEFORE: seed the intent (artifact-first)
+    for each gap in batch:
+      if gap = UI (requirement involves UI, ## UI spec missing):
+        compose ui-design → author ## UI spec    # design-system/theme via structured-choice (counts in the batch)
         work = integrate(work, ui)               # → ## UI spec
-      si no, si factual(gap) y attempts[gap] < MAX:
-        si requiere BD y >1 MCP sin default → encolar "elección MCP" en pending_human
-        res = research_inline(gap)           # en la session actual: ANALYSIS-FILE → CONCLUSIONS (+SCRIPTS.sql read-only)
-        si res.concluyente: work = integrate(work, res)    # → Refinement decisions
-        si no: attempts[gap]++ ; si attempts[gap] >= MAX → pending_human.push(gap)
-      si no:
+      else if factual(gap) and attempts[gap] < MAX:
+        if it needs DB and >1 MCP without default → queue "MCP choice" in pending_human
+        res = research_inline(gap)           # in the current session: ANALYSIS-FILE → CONCLUSIONS (+read-only SCRIPTS.sql)
+        if res.conclusive: work = integrate(work, res)     # → Refinement decisions
+        else: attempts[gap]++ ; if attempts[gap] >= MAX → pending_human.push(gap)
+      else:
         pending_human.push(gap)
-    update CHECKPOINT (refine_session)        # DESPUÉS: Pending→Completed, en cada límite de gap (chasis § ciclo artifact-first)
-    si pending_human no vacío:
-      ans = structured_choice(contenido: pending_human (≤3), flow: [Compactar, Cerrar])
+    update CHECKPOINT (refine_session)        # AFTER: Pending→Completed, at every gap boundary (chassis § artifact-first cycle)
+    if pending_human not empty:
+      ans = structured_choice(content: pending_human (≤3), flow: [Compactar, Cerrar])
       switch(flow):
-        Compactar → write CHECKPOINT (refine_session) ; compactar(arnés) ; continue
+        Compactar → write CHECKPOINT (refine_session) ; compact(harness) ; continue
         Cerrar    → goto finalize
       work = integrate(work, ans)            # → Q&A traceability / Open questions
-  # sin gaps materiales → analyze gate = Success criteria en verde (read-only) antes de ofrecer Guardar:
-  issues = analyze(work)   # criterios trazan al Requirement · sin contradicciones · Scope coherente · Open questions cerradas/diferidas
-  si issues: gaps += issues ; continue            # los hallazgos vuelven al loop como gaps
-  ans = structured_choice(contenido: [Guardar refinada, Preguntar algo más],
+  # no material gaps → analyze gate = Success criteria green (read-only) before offering Guardar:
+  issues = analyze(work)   # criteria trace to the Requirement · no contradictions · coherent Scope · Open questions closed/deferred
+  if issues: gaps += issues ; continue            # findings come back into the loop as gaps
+  ans = structured_choice(content: [Guardar refinada, Preguntar algo más],
                         flow: [Compactar, Cerrar])
-  Guardar          → edit_in_place_with_confirm(spec)  # completa secciones + inserta UI spec/Refinement decisions/Q&A ; goto finalize
+  Guardar            → edit_in_place_with_confirm(spec)  # completes sections + inserts UI spec/Refinement decisions/Q&A ; goto finalize
   Preguntar algo más → continue
-  flow Compactar/Cerrar → manejar igual
+  flow Compactar/Cerrar → handle the same way
 finalize:
-  write CHECKPOINT (refine_session)                     # persiste siempre
-  si hay diferidos/followup → write/update BACKLOG (motivo + Open questions diferidas)
-  cerrar refine_session ; reportar
+  write CHECKPOINT (refine_session)                     # always persisted
+  if deferred/follow-ups exist → write/update BACKLOG (reason + deferred Open questions)
+  close refine_session ; report
 ```
 
-## Compact / resume — claves SPEC
+## Compact / resume — SPEC keys
 
-Mecanismo completo (3 casos, `Compactar`, re-run on demand con `--reopen`) en el chasis (§ *Compact / resume*). Claves SPEC:
+Full mechanism (3 cases, `Compactar`, re-run on demand with `--reopen`) in the chassis (§ *Compact / resume*). SPEC keys:
 
-- La **marca de trabajo previo** es la presencia de `## Refinement decisions` + `## Q&A traceability` en el spec (la *marca de refinado*, ver *Deliverable schema*).
-- El re-refine on demand es **operación de primera clase** mientras el flujo siga en SPEC (nuevos requerimientos, cambios de scope, tras re-leer el spec): lee siempre el **spec mismo**, re-refinamiento incremental; al `Guardar`, edita in place con confirmación.
+- The **prior-work mark** is the presence of `## Refinement decisions` + `## Q&A traceability` in the spec (the *refined mark*, see *Deliverable schema*).
+- Re-refining on demand is a **first-class operation** while the flow stays in SPEC (new requirements, scope changes, after re-reading the spec): it always reads the **spec itself**, incremental re-refinement; on `Guardar`, edits in place with confirmation.
 
 ## Convergence / exit
 
-- **Sin gaps materiales** → **analyze gate** (read-only) = **`Success criteria` en verde** (*verification-first*; la instancia SPEC del convergence gate del chasis): cada acceptance criterion traza al `Requirement`, sin contradicciones internas, `Scope` In/Out coherente, `Open questions` cerradas o explícitamente diferidas. Lo que falle **vuelve como gap**; si pasa → ofrece `Guardar especificación refinada`.
-- `Guardar` → `edit_in_place_with_confirm(spec)` y `finalize`.
-- `Cerrar` → `finalize` del chasis (persiste siempre `CHECKPOINT`; `BACKLOG` **solo si** hay diferidos — acá: motivo de cierre + `Open questions` diferidas).
+- **No material gaps** → **analyze gate** (read-only) = **`Success criteria` green** (*verification-first*; the SPEC instance of the chassis convergence gate): every acceptance criterion traces to the `Requirement`, no internal contradictions, coherent `Scope` In/Out, `Open questions` closed or explicitly deferred. Whatever fails **comes back as a gap**; if it passes → offer `Guardar especificación refinada`.
+- `Guardar` → `edit_in_place_with_confirm(spec)` and `finalize`.
+- `Cerrar` → the chassis `finalize` (always persists `CHECKPOINT`; `BACKLOG` **only if** something is deferred — here: close reason + deferred `Open questions`).
 
-## Integration (dónde aterriza cada resolución)
+## Integration (where each resolution lands)
 
-- Resuelto vía **research inline** → `## Refinement decisions` del spec (+ ref a las `CONCLUSIONS` de la session).
-- Resuelto vía **humano** → `## Q&A traceability` del spec.
-- Resuelto vía **capacidad `ui-design`** (gap UI) → sección `## UI spec` del spec.
-- **Research inconclusa o sin resolver** → `## Open questions` del spec (diferido) + `BACKLOG.md` de la refine session (solo si queda algo diferido).
+- Resolved via **inline research** → the spec's `## Refinement decisions` (+ ref to the session's `CONCLUSIONS`).
+- Resolved via **human** → the spec's `## Q&A traceability`.
+- Resolved via the **`ui-design` capability** (UI gap) → the spec's `## UI spec` section.
+- **Inconclusive or unresolved research** → the spec's `## Open questions` (deferred) + the refine session's `BACKLOG.md` (only if something is deferred).

package/skills/w/roles/README.md

@@ -23,9 +23,9 @@ All 6 roles, their built-in defaults, their tier, and which loops/exports compos
 - `must` — core to almost every session; built-in always active unless explicitly `off`.
 - `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`, escribe `docs/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.
+> **Ambient conventions (not roles).** Code, testing and writing standards **and tool authoring** (`creating-tools`, which writes `docs/tools`) are **not workflow roles** and are never bound: they are **standalone skills the host auto-discovers by `description`** and applies when relevant. The workflow is **indifferent** (it neither reads nor looks for them). Useful families live in marketplace plugins (`dev-conventions`, `tool-builder`), but the workflow does **not depend** on them.
 >
-> **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ó.
+> **The closing review is not a role either** (deliberate decision — a `conventions`/`rules`/`review` role was evaluated and discarded): the pre-commit **closing review gate** of `plan-exec-loop`/`quick-loop` is a **loop step**; the loop creates the **moment** and the installed ambient conventions fill it. A role that "points at the marketplace skills" would re-couple what this extraction decoupled.
 
 ---
 

package/skills/w/roles/diagrams/SKILL.md

@@ -1,49 +1,51 @@
 ---
 name: diagrams
 description: >
-  Autoría de diagramas de arquitectura y sistema con notación C4 (Context, Container,
-  Component): Mermaid C4 nativo (default) o Structurizr DSL. Compuesta por export-diagrams
-  para producir el contenido de docs/diagrams/. Selecciona el motor según el flag `--engine`
-  del export (Mermaid default; `c4`/Structurizr DSL opt-in). Incluye link mermaid.ink por
-  cada bloque Mermaid para preview sin renderer local.
+  Architecture and system diagram authoring with C4 notation (Context, Container,
+  Component): native Mermaid C4 (default) or Structurizr DSL. Composed by export-diagrams
+  to produce the content of docs/diagrams/. Selects the engine from the export's
+  `--engine` flag (Mermaid default; `c4`/Structurizr DSL opt-in). Includes a mermaid.ink
+  link per Mermaid block for preview without a local renderer.
 ---
 
 # diagrams — Diagram authoring capability
 
 ## Role
 
-`diagrams` — implementación built-in por defecto. Rebindeable a otra skill (de tercero o `off`) en `.workflow/skills.toml`.
+`diagrams` — built-in default implementation. Rebindable to another skill (third-party or `off`) in `.workflow/skills.toml`.
 
 ## Purpose
 
-Autorar diagramas de arquitectura con notación C4 (Levels 1-3) usando el motor que el export configure vía `--engine`. Produce source renderizable (Mermaid / DSL) — **no renderiza visualmente**; el render lo hace el lector con sus herramientas. Cubre el motor por defecto (Mermaid C4 nativo, embebido) y el opt-in `c4` (Structurizr DSL, C4 formal).
+Author architecture diagrams with C4 notation (Levels 1-3) using the engine the export configures via `--engine`. It produces renderable source (Mermaid / DSL) — **it does not render visually**; the reader renders with their tools. Covers the default engine (native embedded Mermaid C4) and the opt-in `c4` (Structurizr DSL, formal C4).
 
 ## Composed by
 
-| Export | Cuándo la compone |
+| Export | When it composes it |
 |---|---|
-| `export-diagrams` | para generar el contenido de `docs/diagrams/NNN-*/` |
+| `export-diagrams` | to generate the content of `docs/diagrams/NNN-*/` |
 
-Cualquier loop puede componerla también si necesita producir un diagrama inline durante ejecución (raro; el caso primario es `export-diagrams`).
+Any loop may also compose it to produce an inline diagram during execution (rare; the primary case is `export-diagrams`).
 
 ## Knowledge
 
 ### Engine matrix
 
-El export elige el motor con `--engine mermaid|c4` (default `mermaid`):
+The export picks the engine with `--engine mermaid|c4` (default `mermaid`):
 
-| `--engine` | Motor | Archivos producidos | Cuándo elegirlo |
+| `--engine` | Engine | Files produced | When to pick it |
 |---|---|---|---|
-| `mermaid` (default) | Mermaid C4 nativo | solo `.md` con bloques Mermaid | Render embebido sin DSL separado; GitHub/GitLab lo renderizan inline |
-| `c4` | Structurizr DSL | `workspace.dsl` + Mermaid auxiliar embebido en `.md` | Dossier técnico formal; tooling externo (structurizr.com, structurizr-lite) |
+| `mermaid` (default) | Native Mermaid C4 | only `.md` with Mermaid blocks | Embedded render, no separate DSL; GitHub/GitLab render it inline |
+| `c4` | Structurizr DSL | `workspace.dsl` + auxiliary Mermaid embedded in `.md` | Formal technical dossier; external tooling (structurizr.com, structurizr-lite) |
 
-**Regla canónica**: `export-diagrams` usa **Mermaid** por defecto (`--engine mermaid`) — render embebido sin tooling externo. `--engine c4` produce Structurizr DSL (C4 formal, separa modelo de vistas) para el dossier técnico.
+**Canonical rule**: `export-diagrams` uses **Mermaid** by default (`--engine mermaid`) — embedded render, no external tooling. `--engine c4` produces Structurizr DSL (formal C4, separates model from views) for the technical dossier.
 
 ### C4 model — levels
 
+Diagram titles/labels are user-facing content → author them in the user's language (Spanish in the templates below).
+
 #### Level 1: Context (C4Context)
 
-El sistema como caja única + actores + sistemas vecinos. Perspectiva de negocio.
+The system as a single box + actors + neighbor systems. Business perspective.
 
 ```mermaid
 C4Context
@@ -57,7 +59,7 @@ C4Context
 
 #### Level 2: Container (C4Container)
 
-Aplicaciones, servicios, data stores que componen el sistema. Una fuente declarada en `WORKSPACE` = un contenedor.
+Applications, services, data stores composing the system. One source declared in `WORKSPACE` = one container.
 
 ```mermaid
 C4Container
@@ -76,7 +78,7 @@ C4Container
 
 #### Level 3: Component (C4Component)
 
-Módulos internos relevantes de un contenedor. Solo para contenedores con complejidad interna suficiente. Un diagrama por contenedor; el resto se omite.
+Relevant internal modules of one container. Only for containers with enough internal complexity. One diagram per container; the rest are omitted.
 
 ```mermaid
 C4Component
@@ -88,7 +90,7 @@ C4Component
   Rel(compA, compB, "<interaccion>")
 ```
 
-Si ningún contenedor justifica C4 Component → omitir la sección con nota inline `_(Sin contenedores con complejidad interna suficiente para C4 Component.)_`.
+If no container justifies C4 Component → omit the section with the inline note `_(Sin contenedores con complejidad interna suficiente para C4 Component.)_`.
 
 ### Structurizr DSL template
 
@@ -126,7 +128,7 @@ workspace "<PRODUCTO>" "<descripcion>" {
       autoLayout
     }
 
-    // Una vista por contenedor con C4 Component relevante:
+    // One view per container with relevant C4 Component:
     component svcA "SvcA-Components" {
       include *
       autoLayout
@@ -137,11 +139,11 @@ workspace "<PRODUCTO>" "<descripcion>" {
 }
 ```
 
-Render online gratuito: [structurizr.com/dsl](https://structurizr.com/dsl) o structurizr-lite (Docker).
+Free online render: [structurizr.com/dsl](https://structurizr.com/dsl) or structurizr-lite (Docker).
 
-### PlantUML C4-stdlib template (motor extra, fuera del contrato actual)
+### PlantUML C4-stdlib template (extra engine, outside the current contract)
 
-> El contrato vigente de `export-diagrams` expone solo `--engine mermaid|c4` (no produce `.puml`). Esta plantilla queda como **referencia** para un export rebindeado/custom que quiera emitir PlantUML.
+> The current `export-diagrams` contract exposes only `--engine mermaid|c4` (it produces no `.puml`). This template remains as a **reference** for a rebound/custom export that wants to emit PlantUML.
 
 ```plantuml
 @startuml arquitectura
@@ -163,11 +165,11 @@ SHOW_LEGEND()
 @enduml
 ```
 
-Render: [plantuml.com](https://plantuml.com) o `plantuml.jar` local.
+Render: [plantuml.com](https://plantuml.com) or a local `plantuml.jar`.
 
-### Mermaid auxiliar (bajo `--engine c4`)
+### Auxiliary Mermaid (under `--engine c4`)
 
-Cuando `--engine c4`, el archivo `.md` incluye también un bloque Mermaid derivado del DSL como **fallback offline** (lectores sin acceso a structurizr.com/dsl pueden leerlo directamente):
+With `--engine c4`, the `.md` file also includes a Mermaid block derived from the DSL as an **offline fallback** (readers without access to structurizr.com/dsl can read it directly):
 
 ```
 ```mermaid
@@ -175,14 +177,14 @@ C4Context
   title ...
 ```
 
-> Ver diagrama renderizado: <https://mermaid.ink/img/BASE64>
+> See the rendered diagram: <https://mermaid.ink/img/BASE64>
 ```
 
-El `BASE64` es el código Mermaid plano codificado en base64 URL-safe (RFC 4648 §5; alfabeto `A-Z a-z 0-9 - _`). **Cada bloque Mermaid lleva su propio link** inmediatamente después del fence de cierre.
+`BASE64` is the plain Mermaid code encoded as URL-safe base64 (RFC 4648 §5; alphabet `A-Z a-z 0-9 - _`). **Every Mermaid block carries its own link** immediately after the closing fence.
 
 ### Sequence diagrams (opt-in)
 
-Para flujos críticos de integración (no C4 estructural), un `sequenceDiagram` Mermaid complementa el C4 Container:
+For critical integration flows (not structural C4), a Mermaid `sequenceDiagram` complements the C4 Container:
 
 ```mermaid
 sequenceDiagram
@@ -195,11 +197,11 @@ sequenceDiagram
   SvcA-->>Dev: 201 Created
 ```
 
-Solo si aporta claridad real — no agregar sequence diagrams por defecto.
+Only when it adds real clarity — never add sequence diagrams by default.
 
-### Entity-Relationship (modelo de datos)
+### Entity-Relationship (data model)
 
-Cuando `export-diagrams` incluye `--scope data` y hay MCP configurado:
+When `export-diagrams` includes `--scope data` and an MCP is configured:
 
 ```mermaid
 erDiagram
@@ -215,35 +217,36 @@ erDiagram
   }
 ```
 
-MCP read-only: `\d <tabla>` + `SELECT count(*)` para magnitud (aplicar cost guard: ver skill `research` o `sql`).
+Read-only MCP: `\d <table>` + `SELECT count(*)` for magnitude (apply the cost guard: see the `research` or `sql` skill).
 
 ### Output file structure
 
 ```
 docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/
-├── README.md            # índice + how-to-read + motores usados
-├── diagrams.md          # documento principal con C4 + Mermaid (+ links mermaid.ink)
-└── workspace.dsl        # solo con --engine c4 (Structurizr)
+├── README.md            # index + how-to-read + engines used
+├── diagrams.md          # main document with C4 + Mermaid (+ mermaid.ink links)
+└── workspace.dsl        # only with --engine c4 (Structurizr)
 ```
 
 ### Render rules
 
-1. Sin cota de palabras — completitud > concisión para documentación técnica.
-2. Diagrama principal (al menos C4Context + C4Container) es obligatorio; sin ellos el output no es válido.
-3. C4Component solo si el contenedor lo justifica.
-4. Sequence y erDiagram son opcionales; solo si aportan claridad real.
-5. Cada bloque `mermaid` lleva el link `mermaid.ink` como blockquote inline.
-6. Placeholders `{{PLACEHOLDER}}` siempre reemplazados — nunca dejar marcadores sin rellenar.
+1. No word cap — completeness > concision for technical documentation.
+2. The main diagram (at least C4Context + C4Container) is mandatory; without them the output is not valid.
+3. C4Component only when the container justifies it.
+4. Sequence and erDiagram are optional; only when they add real clarity.
+5. Every `mermaid` block carries the `mermaid.ink` link as an inline blockquote.
+6. `{{PLACEHOLDER}}` placeholders always replaced — never leave unfilled markers.
 
 ## Output
 
-Produce en `docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/`:
+Produces under `docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/`:
+
 - `README.md`
-- `diagrams.md` (siempre)
-- `workspace.dsl` (si `--engine c4`)
+- `diagrams.md` (always)
+- `workspace.dsl` (with `--engine c4`)
 
-Escribe solo `docs/diagrams/` (invariant #1 y #2: solo `export-*` gradua a `docs/`; esta skill la compone `export-diagrams`).
+Writes only `docs/diagrams/` (invariants #1 and #2: only `export-*` graduates to `docs/`; this skill is composed by `export-diagrams`).
 
 ## Source
 
-Reciclado de `agent-workflow/exports/export-arq/` del bundle viejo (v1.3.0). Se conserva: el modelo C4 Levels 1-3, las plantillas DSL/PUML, la regla de link `mermaid.ink` por bloque Mermaid, la estructura de output, el cost guard para MCP. Se moderniza al contrato vigente de `export-diagrams`: **Mermaid por defecto** (antes Structurizr), motor elegido por `--engine mermaid|c4` (lo recibe el export que compone esta skill); PlantUML queda como apéndice de referencia, fuera del contrato actual. Se descarta: la lógica de lectura de AW-PROJECT legacy y los comandos CLI `agent-workflow next-number`/`history-data`/etc. (detalles de implementación del CLI, no de la skill).
+Rationale and history: design (`docs/referencias/workflow-roles/diagrams.md`).