@tacuchi/agent-workflow-cli 15.2.0 → 16.1.0

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

@@ -1,123 +1,123 @@
 ---
 name: plan-refine-loop
 description: >-
-  Refina un plan existente (docs/plans/PPP-plan-<slug>.md) editándolo IN
-  PLACE — paso auxiliar y NO obligatorio antes de plan-exec. Heir del chasis
-  (loops/CHASSIS.md). Deltas: reusa la gap taxonomy y el coherence gate de
-  plan-new-loop, agrega Refinement decisions / Q&A traceability (traza, sin
-  gating), y produce/actualiza design SPECs vía ui-design si el refine toca
-  UI. Lo arranca /w:plan-refine; reanudable y re-corrible a demanda. Invocar
-  cuando un plan ya generado deba ajustarse antes de ejecutarlo.
+  Refines an existing plan (docs/plans/PPP-plan-<slug>.md) by editing it IN
+  PLACE — an auxiliary, NOT mandatory step before plan-exec. Heir of the
+  chassis (loops/CHASSIS.md). Deltas: reuses plan-new-loop's gap taxonomy and
+  coherence gate, adds Refinement decisions / Q&A traceability (trace, no
+  gating), and produces/updates design SPECs via ui-design when the refine
+  touches UI. Started by /w:plan-refine; resumable and re-runnable on demand.
+  Invoke when an already generated plan must be adjusted before executing it.
 ---
 
 # plan-refine-loop
 
-> **Heir** del chasis común — aquí **solo** los deltas de PLAN-refine. El motor no se repite.
+> **Heir** of the common chassis — **only** the PLAN-refine deltas live here. The engine is never repeated.
 
-> **Relación con los otros loops de PLAN:** `plan-new-loop` **genera** el plan desde el spec; `plan-refine-loop` **lo refina in place** (opcional); `plan-exec-loop` **lo ejecuta**. plan-refine es a plan-new lo que spec-refine es a spec-new.
+> **Relation to the other PLAN loops:** `plan-new-loop` **generates** the plan from the spec; `plan-refine-loop` **refines it in place** (optional); `plan-exec-loop` **executes it**. plan-refine is to plan-new what spec-refine is to spec-new.
 
 ## Flow
 PLAN
 
 ## Layer
-2 — la IA lo corre entero.
+2 — the AI runs it end to end.
 
-## Auxiliar / NO obligatorio
-`plan-exec` corre **cualquier** plan, refinado o no — **no** hay gate que exija plan-refine. Este loop existe para incorporar cambios (nuevos requerimientos, ajustes de alcance, deps/riesgos detectados al releer) **antes** de ejecutar, sin re-generar el plan desde cero.
+## Auxiliary / NOT mandatory
+`plan-exec` runs **any** plan, refined or not — there is **no** gate requiring plan-refine. This loop exists to incorporate changes (new requirements, scope adjustments, deps/risks spotted on re-read) **before** executing, without regenerating the plan from scratch.
 
 ## Started by
-`/w:plan-refine` — **reanudable** (mismo mecanismo del chasis, keyado off CHECKPOINT) y **re-corrible a demanda** (ver *Compact / resume*).
+`/w:plan-refine` — **resumable** (same chassis mechanism, keyed off CHECKPOINT) and **re-runnable on demand** (see *Compact / resume*).
 
 ## Reads
-`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.
+`docs/plans/PPP-plan-*.md` (glob — locates the plan by number; or the exact path from the command argument). **Always the plan itself**: this loop edits it in place; there is no separate "refined" file.
 
 ## 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. 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).
+Updates `docs/plans/PPP-plan-<slug>.md` **in place** (when the user picks `Guardar plan refinado`): completes/adjusts sections and **adds** `## Refinement decisions` + `## Q&A traceability`. Since it overwrites an existing doc, it asks the user's **confirmation**. It writes only `docs/plans` — never other `docs/` folders, no auto-export. If the refine **touches UI**, it also produces/updates **design SPECs** (`NNN-SPEC-<SLUG>.md`) as artifacts **of its own session** (see *Delta 4* — they are not `docs/`, no auto-export).
 
 ## Inherits
 
-Leé **[`../CHASSIS.md`](../CHASSIS.md)** — el **motor completo** del loop — **siempre antes** de estos deltas. *(Si `../` no resuelve: `CHASSIS.md` junto a este archivo — regla global de layout, chasis § Resolución de referencias.)*
+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.)*
 
-## Internal sessions — instancia PLAN-refine
+## Internal sessions — PLAN-refine 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>-plan-refine/` | al arrancar el loop (o se reanuda/reabre) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` solo si difiere) | Dueña del run. Type = `refine`; descriptor `<slug>-plan-refine` (el `<slug>` sale del plan de entrada). |
+| **refine session** `NNN-<slug>-plan-refine/` | when the loop starts (or resumes/reopens) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` only if something is deferred) | Owns the run. Type = `refine`; descriptor `<slug>-plan-refine` (the `<slug>` comes from the input plan). |
 
-## Delta 1 — Deliverable: el PLAN, editado in place
+## Delta 1 — Deliverable: the PLAN, edited in place
 
-El plan usa el **mismo esqueleto** que produce [`plan-new-loop`](../plan-new-loop/SKILL.md) (en instalaciones aplanadas: la copia hermana `w-plan-new-loop/SKILL.md`) (§ *Delta 1 — PLAN RICO*: `Summary`/`Solution`/`Impacted`/`Phases`/`Tasks`/`Validations`/`Final behavior`/… con secciones `(core)` siempre y `(opt.)` según complejidad). plan-refine **no** cambia el esquema: **completa/ajusta** las secciones existentes **in place** y **agrega** dos de traza:
+The plan uses the **same skeleton** [`plan-new-loop`](../plan-new-loop/SKILL.md) produces (§ *Delta 1 — RICH PLAN*: `Summary`/`Solution`/`Impacted`/`Phases`/`Tasks`/`Validations`/`Final behavior`/… with `(core)` sections always and `(opt.)` by complexity). plan-refine does **not** change the schema: it **completes/adjusts** the existing sections **in place** and **adds** two trace sections:
 
 ```markdown
-## Refinement decisions   ← NEW (se AGREGA)
-Qué se ajustó al refinar y por qué (nuevos requerimientos, cambios de scope,
-deps/riesgos). Incluye lo resuelto vía research inline (ref a las CONCLUSIONS
-de la session).
+## Refinement decisions   ← NEW (ADDED)
+What was adjusted while refining and why (new requirements, scope changes,
+deps/risks). Includes what inline research resolved (ref 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.
 ```
 
-> **Sin contrato de gating** (a diferencia de spec↔plan): la presencia de `## Refinement decisions`/`## Q&A traceability` en el plan es solo **traza de auditoría** — `plan-exec` **no** la exige ni la chequea (corre cualquier plan). Sirve para (a) distinguir un plan re-refinado de uno recién generado en el resume, y (b) dejar registro de qué cambió y por qué.
+> **No gating contract** (unlike spec↔plan): the presence of `## Refinement decisions`/`## Q&A traceability` in the plan is **audit trace only** — `plan-exec` neither requires nor checks it (it runs any plan). It serves to (a) distinguish a re-refined plan from a freshly generated one on resume, and (b) record what changed and why.
 
-> El plan **no muta por ejecución** (eso lo trackea plan-exec en las Tasks del plan-doc) — solo por un (re-)refine.
+> The plan **never mutates by execution** (plan-exec tracks that in the plan-doc's Tasks) — only by a (re-)refine.
 
-## Delta 2 — Gap taxonomy (de "plan")
+## Delta 2 — Gap taxonomy (of "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, 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:
+Reuses plan-new-loop's gap taxonomy **in full** ([`plan-new-loop`](../plan-new-loop/SKILL.md) § *Delta 2*): vague Approach/Solution, components unidentified, AS-IS wiring unknown, phase too large, task not atomic, missing deps, spec criteria uncovered, unaddressed risks, UI without design SPEC. **Focus difference:** plan-new **builds** the plan from scratch; plan-refine **detects what changed** against the written plan (or against the spec, if the spec was re-refined) and closes **those** gaps — typically fewer and more localized. One extra re-refine gap:
 
 | Gap | Signal | Resolved by |
 |---|---|---|
-| Deriva plan↔spec | el spec se re-refinó y el plan quedó desalineado | **research** (re-lee el spec) / **humano** |
+| Plan↔spec drift | the spec was re-refined and the plan fell out of line | **research** (re-reads the spec) / **human** |
 
 ## Delta 3 — What research investigates here
 
-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).
+Same as plan-new (maps code/impact: FE/BE/DB components, AS-IS wiring, deps), but **scoped to the delta**: it re-verifies only what the change touches (never re-maps the whole plan). Chassis DB rule unchanged (read-only into `SCRIPTS.sql`, MCP via a question when >1 without default).
 
-## Delta 4 — Design SPECs (si el refine toca UI)
+## Delta 4 — Design SPECs (when the refine touches 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.
+Same mechanism as [`plan-new-loop`](../plan-new-loop/SKILL.md) (§ *Delta 4*: the **`ui-design`** capability → per-screen `NNN-SPEC-<SLUG>.md`, see [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)), **scoped to the delta**: only the screens **new or changed** by the refine get a design SPEC. The updated SPEC is written in **plan-refine's own session** (each loop manages ITS session's artifacts — it never edits plan-new's) and the plan **re-points** the UI Task reference to the current SPEC. Untouched screens keep their original SPEC.
 
 ## 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:
+Resume **keys off the `CHECKPOINT`** of the refine session, never a "refined" file. Three cases when `/w:plan-refine` runs over a plan:
 
-1. **En curso** (existe `CHECKPOINT.md` en la refine session) → reanuda desde el avance (gaps resueltos, Q&A, `attempts`, research inline en curso).
-2. **Sin avance** (no hay CHECKPOINT y el plan **no** tiene `Refinement decisions`/`Q&A traceability`) → arranca desde cero leyendo el plan (`PPP-plan-*.md`).
-3. **Ya refinado / re-refine on demand** (sin CHECKPOINT abierto, pero el plan **ya tiene** las 2 secciones) → **operación de primera clase**, cuantas veces haga falta mientras el flujo siga en PLAN:
-   - `create_or_resume` detecta la refine session existente (típicamente **cerrada** tras converger) por descriptor + `## Origin` y la **reabre**: `aw session-resume --code <NNN> --reopen` (detección: `aw sessions --state all`).
-   - Re-refinamiento incremental leyendo el **plan mismo**; al `Guardar`, edita in place con confirmación.
+1. **In progress** (a `CHECKPOINT.md` exists in the refine session) → resume from the recorded progress (resolved gaps, Q&A, `attempts`, in-flight inline research).
+2. **No progress** (no CHECKPOINT and the plan does **not** have `Refinement decisions`/`Q&A traceability`) → start from zero reading the plan (`PPP-plan-*.md`).
+3. **Already refined / re-refine on demand** (no open CHECKPOINT, but the plan **already has** the 2 sections) → **first-class operation**, as many times as needed while the flow stays in PLAN:
+   - `create_or_resume` finds the existing refine session (typically **closed** after convergence) by descriptor + `## Origin` and **reopens** it: `aw session-resume --code <NNN> --reopen` (detection: `aw sessions --state all`).
+   - Incremental re-refinement reading the **plan itself**; on `Guardar`, edits in place with confirmation.
 
-> **Continuidad inter-turno** (chasis, fila 2): un **comando de flujo** abre "nueva línea de trabajo" (sesión nueva) — **salvo re-correr el mismo flujo sobre la misma entrada** (mismo plan), que hace `create_or_resume` (reanuda/reabre en vez de duplicar).
+> **Inter-turn continuity** (chassis, row 2): a flow command opens a "new work line" (new session) — **except re-running the same flow over the same input** (same plan), which does `create_or_resume` (resumes/reopens instead of duplicating).
 
 ## Sequence
 
 ```
 plan-refine-loop(plan):
-  input = glob(docs/plans/PPP-plan-*.md) | ruta del argumento   # siempre el plan mismo (in place)
-  session = create_or_resume("<slug>-plan-refine")              # reabre si existe (ver Compact / resume)
-  seed SESSION.Success criteria = checklist del coherence gate  # verification-first, ANTES
-  work = read(plan) (+ el spec si hay que re-alinear; + avance del checkpoint si reanuda)
-  repeat:                                                       # motor del chasis
-    gaps = detect_gaps(work)  (taxonomy de plan-new + deriva plan↔spec)  menos los agotados
+  input = glob(docs/plans/PPP-plan-*.md) | argument path       # always the plan itself (in place)
+  session = create_or_resume("<slug>-plan-refine")             # reopens if it exists (see Compact / resume)
+  seed SESSION.Success criteria = coherence-gate checklist     # verification-first, BEFORE
+  work = read(plan) (+ the spec if realignment is needed; + checkpoint progress if resuming)
+  repeat:                                                      # chassis engine
+    gaps = detect_gaps(work)  (plan-new taxonomy + plan↔spec drift)  minus the exhausted ones
     if gaps == ∅: break
-    batch ≤3 → sembrar CHECKPOINT.Pending/Next → resolver cada gap:
-      research (acotado al delta — Delta 3) · humano (structured-choice) ·
-      ui-design (Delta 4, solo pantallas nuevas/cambiadas)
-    integrar + update CHECKPOINT                                # ciclo artifact-first
-  coherence gate (read-only) = Success criteria en verde:
-    - checklist de plan-new (criterio→tarea · Final behavior · XS–S/XS · deps · Impacted↔Solution · UI→SPEC vigente)
-    - propio del re-refine: el plan quedó REALINEADO con lo que cambió
-    lo que falle → vuelve como gap
-  structured_choice(contenido: [Guardar plan refinado, Preguntar algo más], flow: [Compactar, Cerrar])
-  Guardar → edit in place (con confirmación) + inserta/actualiza Refinement decisions + Q&A traceability
-finalize: CHECKPOINT persiste (+ BACKLOG solo si difiere) + cerrar session + reportar
+    batch ≤3 → seed CHECKPOINT.Pending/Next → resolve each gap:
+      research (scoped to the delta — Delta 3) · human (structured-choice) ·
+      ui-design (Delta 4, only new/changed screens)
+    integrate + update CHECKPOINT                              # artifact-first cycle
+  coherence gate (read-only) = Success criteria green:
+    - plan-new checklist (criterion→task · Final behavior · XS–S/XS · deps · Impacted↔Solution · UI→current SPEC)
+    - re-refine's own check: the plan is REALIGNED with what changed
+    whatever fails → comes back as a gap
+  structured_choice(content: [Guardar plan refinado, Preguntar algo más], flow: [Compactar, Cerrar])
+  Guardar → edit in place (with confirmation) + insert/update Refinement decisions + Q&A traceability
+finalize: CHECKPOINT persisted (+ BACKLOG only if something is deferred) + close session + report
 ```
 
 ## Convergence / exit
 
-- **Sin gaps materiales** → **coherence gate** (checklist del *Sequence*; el mismo gate de plan-new + la realineación propia del re-refine).
-- Pasa → `Guardar plan refinado` (edita in place con confirmación) → `finalize`.
-- `Cerrar` en cualquier momento → `finalize` (persiste `CHECKPOINT`; `BACKLOG` solo si difiere; cierra la session, reporta).
+- **No material gaps** → **coherence gate** (the *Sequence* checklist; plan-new's gate + the re-refine's own realignment check).
+- Passes → `Guardar plan refinado` (edits in place with confirmation) → `finalize`.
+- `Cerrar` at any time → `finalize` (persists `CHECKPOINT`; `BACKLOG` only if something is deferred; closes the session, reports).

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

@@ -1,123 +1,123 @@
 ---
 name: quick-loop
 description: >-
-  El atajo liviano de agent-workflow: resuelve una tarea acotada (fix, ajuste
-  chico) desde el prompt, con ceremonia mínima y un solo commit. Heir del
-  chasis (loops/CHASSIS.md + CODE-POLICIES.md). Deltas: sin plan-doc (el
-  prompt ES la tarea), session ligera única <slug>-quick, gate de tamaño a la
-  entrada y escalación EN VIVO a SPEC (a PLAN queda diferida) si el objetivo
-  excede un quick o la tarea crece. NO toca docs/. Lo arranca /w:quick;
-  reanudable. Invocar para cambios pequeños y directos que no ameritan spec
-  ni plan formal.
+  The agent-workflow lightweight shortcut: solves a scoped task (fix, small
+  tweak) straight from the prompt, with minimal ceremony and a single commit.
+  Heir of the chassis (loops/CHASSIS.md + CODE-POLICIES.md). Deltas: no
+  plan-doc (the prompt IS the task), single light session <slug>-quick, an
+  entry size gate and LIVE escalation to SPEC (to PLAN it stays deferred)
+  when the objective exceeds a quick or the task grows. Never touches docs/.
+  Started by /w:quick; resumable. Invoke for small, direct changes that do
+  not warrant a formal spec or plan.
 ---
 
 # quick-loop
 
-> **Heir** del chasis común — aquí **solo** los deltas de QUICK. El motor vive en el chasis y las *Políticas de loops que editan código* (git · BD · gate proporcional) en `CODE-POLICIES.md` — no se repiten.
+> **Heir** of the common chassis — **only** the QUICK deltas live here. The engine lives in the chassis and the *code-editing loop policies* in `CODE-POLICIES.md` — never repeated.
 
 ## Flow
 QUICK
 
 ## Layer
-2 — la IA lo corre entero (loop mínimo).
+2 — the AI runs it end to end (minimal loop).
 
 ## Started by
-`/w:quick` — **reanudable** (mismo mecanismo de resume del chasis).
+`/w:quick` — **resumable** (same chassis resume mechanism).
 
 ## Reads
-— (el prompt del usuario; no hay documento de entrada).
+— (the user's prompt; there is no input document).
 
 ## Writes
-- **Deliverable según la tarea:** edita código en las fuentes (cambio mínimo) **o** produce un **análisis/diseño** acotado (deliverable no-código, vive en los artefactos de la session — no en `docs/`).
-- Artefactos de la session en `.workflow/sessions/`.
-- **NO toca `docs/`** (sin doc, sin auto-export). Un análisis/diseño que amerite preservarse se promueve aparte (`export-*`) o se escala a SPEC/PLAN (SPEC: en vivo — ver *Delta QUICK*).
+- **Deliverable per task:** edits code in the sources (minimal change) **or** produces a scoped **analysis/design** (non-code deliverable, lives in the session artifacts — never in `docs/`).
+- Session artifacts under `.workflow/sessions/`.
+- **NEVER touches `docs/`** (no doc, no auto-export). An analysis/design worth preserving is promoted separately (`export-*`) or escalated to SPEC/PLAN (SPEC: live — see *QUICK delta*).
 
 ## Internal session
 
-- **SIEMPRE** crea una session ligera con descriptor `<slug>-quick` → `NNN-<slug>-quick` (Type = `quick`, ≈ `exec`): `SESSION` · `DECISION` · `SCRIPTS.sql` · `CHECKPOINT` (+ `BACKLOG` solo si difiere). Una sola session. La investigación es **inline** dentro de ella (`ANALYSIS-FILE`/`CONCLUSIONS` + `SCRIPTS.sql` read-only en su carpeta). El caller pasa solo el descriptor; el CLI antepone el `NNN` global y secuencial (ver chasis). **Excepción:** si el **gate de tamaño** de la entrada escala a SPEC, el run quick no llega a existir — no se crea session quick; la session es la del `spec-refine-loop`.
+- **ALWAYS** creates a light session with descriptor `<slug>-quick` → `NNN-<slug>-quick` (Type = `quick`, ≈ `exec`): `SESSION` · `DECISION` · `SCRIPTS.sql` · `CHECKPOINT` (+ `BACKLOG` only if something is deferred). A single session. Research is **inline** inside it (`ANALYSIS-FILE`/`CONCLUSIONS` + read-only `SCRIPTS.sql` in its folder). The caller passes only the descriptor; the CLI prepends the global sequential `NNN` (see chassis). **Exception:** if the entry **size gate** escalates to SPEC, the quick run never comes to exist — no quick session is created; the session is the `spec-refine-loop` one.
 
 ## Inherits
 
-Leé **[`../CHASSIS.md`](../CHASSIS.md)** — el **motor completo** del loop — **y** **[`../CODE-POLICIES.md`](../CODE-POLICIES.md)** — las *Políticas de loops que editan código* — **siempre antes** de estos deltas. *(Si `../` no resuelve: mismos nombres junto a este archivo — regla global de layout, chasis § Resolución de referencias.)*
+Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **and** **[`../CODE-POLICIES.md`](../CODE-POLICIES.md)** — the *code-editing loop policies* — **always before** these deltas. *(If `../` does not resolve: same names next to this file — global layout rule, chassis § Reference resolution.)*
 
 ## Composes
 
-`git` · `sql` (regla BD) · `research` (inline). Resueltas por `.workflow/skills.toml`.
+`git` · `sql` (DB rule) · `research` (inline). Resolved via `.workflow/skills.toml`.
 
-> **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).
 
-## Delta QUICK — minimal ceremony
+## QUICK delta — minimal ceremony
 
-- **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*](../CHASSIS.md)).
-- **Git y BD inline** (políticas completas en [`../CODE-POLICIES.md`](../CODE-POLICIES.md)): antes de editar, verificar rama esperada por fuente (`aw check-branch`); commit **propuesto** (aprobar antes) — nunca `push`/`--amend`/`--no-verify`. La IA **nunca ejecuta DML/DDL**: las migraciones se redactan en el `SCRIPTS.sql` de la session (consultas read-only sí, vía MCP).
-- **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** ([`../CODE-POLICIES.md`](../CODE-POLICIES.md) § *Gate de revisión de cierre*): re-lectura del diff + convenciones ambientes; corregir o diferir; nada llega al commit sin revisar.
-- **Gate de tamaño a la ENTRADA** (antes de crear la session): al recibir el objetivo, evaluar si **excede un quick**. Dispara **solo con señales claras** (≥2 de: necesita arquitectura · ≥2 fuentes · varios entregables · feature/refactor grande · requisitos ambiguos que piden elicitación); borderline → **sigue en quick sin preguntar** (si después crece, lo cubre la escalación mid-loop). Un **resume** de una quick existente **no** re-dispara el gate. Si dispara → **structured-choice** (1 pregunta de contenido, recomendación primera + control `flow`; `Cerrar` acá = abortar, nada creado aún):
-  - **Cambiar a SPEC** (recomendada) → **no se crea la session quick**: corre la *Transición en vivo a SPEC* (bullet siguiente).
-  - **Seguir en quick** → continúa normal (`create_or_resume` + loop).
-  - **Recortar alcance** → la IA propone la **sub-tarea que SÍ cabe** en un quick; el loop sigue con ella (`SESSION.Objective` = la sub-tarea; el prompt original queda en el `## Origin` de la session) y el resto se difiere al `BACKLOG` ("recortado en el gate — puede ameritar spec aparte, `/w:spec-new`").
-  - **Anti-duplicado** (espíritu `create_or_resume`): si ya existe un spec cuyo `## Origin` referencia este mismo objetivo (o una session `*-spec-refine` equivalente), la recomendada pasa a ser **retomar ese spec** (semántica `/w:spec-refine`) — nunca materializar un segundo borrador.
-- **Transición en vivo a SPEC** (compartida por el gate y la escalación mid-loop). Al aceptar, la línea de trabajo **pasa al flujo SPEC**: el consentimiento explícito en la structured-choice **equivale a invocar el comando destino** (*excepción consentida* — regla 3 de la *Regla de continuidad*, [`../../SKILL.md`](../../SKILL.md) § *Contexto operativo*). Ya del lado SPEC:
-  1. **Materializar el borrador** por el procedimiento de [`../../commands/spec-new.md`](../../commands/spec-new.md): `aw next-number docs/specs`, slug, esquema, single-pass **SIN investigación**. `## Origin` = "escalado desde `/w:quick`" + el prompt original (+ la session quick de origen si existe).
-  2. **Cargar y ejecutar** [`../spec-refine-loop/SKILL.md`](../spec-refine-loop/SKILL.md) — aplanada: `../w-spec-refine-loop/SKILL.md` — sobre ese spec (patrón trampolín).
-  3. La session del run es la `NNN-<slug>-spec-refine` **normal** de ese loop (el CLI numera; su `## Origin` registra la escalación). **Invariante 2 intacto**: quick, mientras es quick, no escribe `docs/` — el borrador lo escribe el flujo SPEC, post-consentimiento.
-- **Escalación mid-loop + handoff**: si la tarea crece (mismas señales del gate) → propone subir a **SPEC/PLAN** (structured-choice, recomendación primera). Si el usuario acepta:
-  1. El **código ya editado queda** en el working tree (no se revierte) y se **registra** en `CHECKPOINT` + `BACKLOG`: "cambios sin commitear en `<fuente>` — decidir commit/descartar al retomar" (patrón "commit rechazado", [`../CODE-POLICIES.md`](../CODE-POLICIES.md) § *Git seguro*).
-  2. La session quick va a `finalize` con el **puntero** en `BACKLOG`: a **PLAN** → "escalado a `docs/plans/PPP` — retomar ahí" (**diferido como hoy**: siembra + puntero, sin entrar en vivo); a **SPEC** → "escalado a `docs/specs/NNN` — **continuado en vivo** (session `NNN-<slug>-spec-refine`)".
-  3. Los artefactos (`DECISION`, `SCRIPTS.sql`) **quedan en la session quick** como contexto referenciable por la nueva session (no se migran).
-  4. **SPEC entra en vivo**: tras el `finalize` corre la *Transición en vivo a SPEC* (borrador **solo si no existe** spec para este objetivo; luego el loop). **Asimetría** intacta: PLAN puede **absorber** el avance (plan-exec retoma el working tree existente); SPEC **reinicia** el ciclo de diseño y trata el código a medias como contexto/referencia, no como trabajo ya ingerido.
+- **No phases, no plan-doc**: the prompt **is** the task (a single unit). No roadmap.
+- **Proportional verification-first** (minimal ceremony): even here the check is **seeded before**, sized to the task. Code: one test (bug repro → fix) or "existing build/lint/tests stay green" (chore). **Analysis/design**: a **short falsifiable rubric**, *ratified by the user* before pursuing it. It is the run's `SESSION.Success criteria` (see [chassis § *Verification-first*](../CHASSIS.md)).
+- **Git and DB inline** (full policies in [`../CODE-POLICIES.md`](../CODE-POLICIES.md)): before editing, verify each source's expected branch (`aw check-branch`); **proposed** commit (approve first) — never `push`/`--amend`/`--no-verify`. The AI **never executes DML/DDL**: migrations are drafted into the session's `SCRIPTS.sql` (read-only queries do run, via MCP).
+- **One session. One commit** proposed at the end (only if there were code changes), **after the proportional closing review gate** ([`../CODE-POLICIES.md`](../CODE-POLICIES.md) § *Closing review gate*): diff re-read + ambient conventions; fix or defer; nothing reaches the commit unreviewed.
+- **Entry SIZE GATE** (before creating the session): on receiving the objective, evaluate whether it **exceeds a quick**. It fires **only on clear signals** (≥2 of: needs architecture · ≥2 sources · multiple deliverables · large feature/refactor · ambiguous requirements needing elicitation); borderline → **continue in quick without asking** (if it later grows, mid-loop escalation covers it). A **resume** of an existing quick does **not** re-fire the gate. If it fires → **structured-choice** (1 content question, recommendation first + `flow` control; `Cerrar` here = abort, nothing created yet):
+  - **`Cambiar a SPEC`** (recommended) → **no quick session is created**: run the *Live transition to SPEC* (next bullet).
+  - **`Seguir en quick`** → continue normally (`create_or_resume` + loop).
+  - **`Recortar alcance`** → the AI proposes the **sub-task that DOES fit** a quick; the loop continues with it (`SESSION.Objective` = the sub-task; the original prompt goes into the session's `## Origin`) and the rest is deferred to `BACKLOG` ("trimmed at the gate — may warrant its own spec, `/w:spec-new`").
+  - **Anti-duplicate** (the `create_or_resume` spirit): if a spec whose `## Origin` references this same objective already exists (or an equivalent `*-spec-refine` session), the recommended option becomes **resuming that spec** (`/w:spec-refine` semantics) — never a second draft.
+- **Live transition to SPEC** (shared by the gate and mid-loop escalation). On acceptance, the work line **moves to the SPEC flow**: the explicit consent in the structured-choice **equals invoking the destination command** (*consented exception* — rule 3 of the *Continuity rule*, [`../../SKILL.md`](../../SKILL.md) § *Operating context*). On the SPEC side:
+  1. **Materialize the draft** via the [`../../commands/spec-new.md`](../../commands/spec-new.md) procedure: `aw next-number docs/specs`, slug, schema, single-pass **NO RESEARCH**. `## Origin` = "escalated from `/w:quick`" + the original prompt (+ the origin quick session if it exists).
+  2. **Load and execute** [`../spec-refine-loop/SKILL.md`](../spec-refine-loop/SKILL.md) — flattened: `../w-spec-refine-loop/SKILL.md` — over that spec (trampoline pattern).
+  3. The run's session is that loop's **normal** `NNN-<slug>-spec-refine` (the CLI numbers it; its `## Origin` records the escalation). **Invariant 2 intact**: quick, while it is quick, never writes `docs/` — the draft is written by the SPEC flow, post-consent.
+- **Mid-loop escalation + handoff**: if the task grows (same gate signals) → propose moving up to **SPEC/PLAN** (structured-choice, recommendation first). If the user accepts:
+  1. The **already-edited code stays** in the working tree (never reverted) and is **recorded** in `CHECKPOINT` + `BACKLOG`: "uncommitted changes in `<source>` — decide commit/discard on resume" (the "rejected commit" pattern, [`../CODE-POLICIES.md`](../CODE-POLICIES.md) § *Safe git*).
+  2. The quick session goes to `finalize` with the **pointer** in `BACKLOG`: to **PLAN** → "escalated to `docs/plans/PPP` — resume there" (**deferred** as today: seed + pointer, no live entry); to **SPEC** → "escalated to `docs/specs/NNN` — **continued live** (session `NNN-<slug>-spec-refine`)".
+  3. The artifacts (`DECISION`, `SCRIPTS.sql`) **stay in the quick session** as referenceable context for the new session (never migrated).
+  4. **SPEC enters live**: after `finalize`, run the *Live transition to SPEC* (draft **only if no spec exists** for this objective; then the loop). **Asymmetry** intact: PLAN can **absorb** the progress (plan-exec picks up the existing working tree); SPEC **restarts** the design cycle and treats the half-done code as context/reference, never as ingested work.
 
-## Continuidad entre prompts (contexto operativo)
+## Continuity across prompts (operating context)
 
-`quick` es donde la **regla de continuidad** (ver [`../../SKILL.md`](../../SKILL.md) § *Contexto operativo*) se ve más claro. Dentro de un workspace:
+`quick` is where the **continuity rule** ([`../../SKILL.md`](../../SKILL.md) § *Operating context*) shows most clearly. Inside a workspace:
 
-1. `/w:quick "primer prompt"` (**comando**) → crea la session `NNN-<slug>-quick`, arranca el loop. Los scripts van a **su** `SCRIPTS.sql`.
-2. `"segundo prompt"` (**sin comando**, trabajo relacionado) → **no** crea otra session: **continúa/reabre la más reciente** (la del paso 1) y agrega los nuevos scripts a **esa misma** `SCRIPTS.sql`.
-3. `/w:quick "tercer prompt"` (**comando** otra vez) → **nueva** session, nuevo loop.
+1. `/w:quick "first prompt"` (**command**) → creates session `NNN-<slug>-quick`, starts the loop. Scripts go to **its** `SCRIPTS.sql`.
+2. `"second prompt"` (**no command**, related work) → does **not** create another session: **continues/reopens the most recent one** (from step 1) and appends the new scripts to **that same** `SCRIPTS.sql`.
+3. `/w:quick "third prompt"` (**command** again) → **new** session, new loop.
 
-> El **comando** señala "nueva línea de trabajo"; un **prompt pelado** es "sigo en la misma" → por default continúa/reabre la más reciente (la *última iniciada*). Si es claramente no-relacionado, ofrece elegir (`continuar NNN` | `trabajo nuevo`) o cae a la rama **sin flujo** (escribe en `docs/` por convención + numeración). Sin workspace → comportamiento **vanilla**.
+> The **command** signals "new work line"; a **bare prompt** means "same line" → by default continue/reopen the most recent session (the *last started*). Clearly unrelated → offer choosing (`continuar NNN` | `trabajo nuevo`) or fall to the **no-flow** branch (write into `docs/` by convention + numbering). No workspace → **vanilla** behavior.
 
 ## Sequence
 
 ```
 quick-loop(prompt):
-  # GATE DE TAMAÑO — ANTES de crear session; solo línea de trabajo nueva (un resume no lo re-dispara)
-  si el objetivo excede un quick (≥2 señales claras — ver Delta):
-    si ya hay spec / session spec-refine de este objetivo → recomendar RETOMAR (/w:spec-refine)  # anti-duplicado
-    structured_choice(contenido: [Cambiar a SPEC (recomendada), Seguir en quick, Recortar alcance],
-                      flow: [Compactar, Cerrar])           # Cerrar acá = abortar (nada creado aún)
-    Cambiar a SPEC   → transición en vivo (ver Delta): borrador (procedimiento spec-new) +
-                       cargar y ejecutar ../spec-refine-loop/SKILL.md → FIN (sin session quick)
-    Recortar alcance → objetivo = la sub-tarea propuesta; el resto → BACKLOG al crear la session
-    Seguir en quick  → continuar
-  s = create_or_resume("<slug>-quick")      # CLI antepone NNN global; siempre session ligera
-  seed SESSION.Objective = el prompt
-  seed SESSION.Success criteria = check del deliverable     # verification-first, ANTES: test(s) si código · rúbrica corta RATIFICADA si análisis/diseño
-  seed CHECKPOINT.Pending/Next = la tarea (s)               # ANTES: sembrar intención (artifact-first)
-  trabajar la tarea (loop mínimo):
-    si edita código → verificar rama esperada por fuente (`aw check-branch`); si no → pausar + resolver
-    producir el deliverable: editar código (cambio mínimo) Ó autorar el análisis/diseño
-    si consulta BD read-only → SCRIPTS.sql + ejecutar read-only
-    si cambio BD (DDL/DML) → SCRIPTS.sql (artefacto session, NO ejecutar)
-    si decisión no obvia → DECISION
-    si duda/gap → research inline ó structured-choice         # chasis
-    si la tarea CRECE → proponer escalar a SPEC/PLAN          # structured-choice, recomendación primera
-        acepta PLAN → handoff (avance queda; BACKLOG→plan sembrado — retomar ahí) → goto finalize
-        acepta SPEC → handoff (avance queda; BACKLOG→"continuado en vivo") → finalize →
-                      transición en vivo (ver Delta): borrador si falta + spec-refine-loop
-  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:
-    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
+  # SIZE GATE — BEFORE creating a session; new work lines only (a resume does not re-fire it)
+  if the objective exceeds a quick (≥2 clear signals — see delta):
+    if a spec / spec-refine session for this objective already exists → recommend RESUMING it (/w:spec-refine)  # anti-duplicate
+    structured_choice(content: [Cambiar a SPEC (recommended), Seguir en quick, Recortar alcance],
+                      flow: [Compactar, Cerrar])           # Cerrar here = abort (nothing created yet)
+    Cambiar a SPEC   → live transition (see delta): draft (spec-new procedure) +
+                       load and execute ../spec-refine-loop/SKILL.md → END (no quick session)
+    Recortar alcance → objective = the proposed sub-task; the rest → BACKLOG when the session is created
+    Seguir en quick  → continue
+  s = create_or_resume("<slug>-quick")      # CLI prepends global NNN; always a light session
+  seed SESSION.Objective = the prompt
+  seed SESSION.Success criteria = the deliverable's check   # verification-first, BEFORE: test(s) if code · short RATIFIED rubric if analysis/design
+  seed CHECKPOINT.Pending/Next = the task (s)               # BEFORE: seed the intent (artifact-first)
+  work the task (minimal loop):
+    if it edits code → verify each source's expected branch (`aw check-branch`); mismatch → pause + resolve
+    produce the deliverable: edit code (minimal change) OR author the analysis/design
+    if read-only DB query → SCRIPTS.sql + execute read-only
+    if DB change (DDL/DML) → SCRIPTS.sql (session artifact, DO NOT execute)
+    if non-obvious decision → DECISION
+    if doubt/gap → inline research OR structured-choice      # chassis
+    if the task GROWS → propose escalating to SPEC/PLAN      # structured-choice, recommendation first
+        accepts PLAN → handoff (progress stays; BACKLOG→seeded plan — resume there, deferred) → goto finalize
+        accepts SPEC → handoff (progress stays; BACKLOG→"continued live") → finalize →
+                       live transition (see delta): draft if missing + spec-refine-loop
+  convergence gate: Success criteria green                   # tests green if code · rubric satisfied if analysis/design
+  if there were code changes:
+    closing review gate (proportional):                      # diff re-read + installed ambient conventions
+        findings → fix (re-validate) OR defer justified (BACKLOG)
+    propose commit (approve first)                           # never push/amend/--no-verify; only after the gate
+  structured_choice(content: [Cerrar tarea, Preguntar algo más], flow: [Compactar, Cerrar])
+finalize: CHECKPOINT (AFTER: Pending→Completed) + BACKLOG (only if something is deferred) + close session + report
 ```
 
 ## Convergence / exit
 
-- **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 **en vivo** — la línea continúa en spec-refine ya como flujo SPEC; a PLAN **diferido**, sembrado + puntero).
+- **Success criteria green** (proportional) + closing review gate passed and commit proposed if there was code (or skipping it approved) → `Cerrar`.
+- `Cerrar`/`Compactar` (`flow` control) → persists `CHECKPOINT` + `BACKLOG` (resumable).
+- **No export**: nothing goes to `docs/`. Anything worth preserving → promoted separately via `export-*`, or escalated (to SPEC **live** — the line continues in spec-refine already as SPEC flow; to PLAN **deferred**, seed + pointer).
 
-> El *convergence gate* de QUICK es **verification-first proporcional**: un `Success criteria` **corto** sembrado al inicio (no la *ausencia* de checklist, sino su versión mínima) — para código, "el cambio hace lo que pedía el prompt + tests/build verdes"; para análisis/diseño, una rúbrica corta ratificada. Mínima ceremonia por diseño, pero **siempre con el check declarado antes**.
+> QUICK's *convergence gate* is **proportional verification-first**: a **short** `Success criteria` seeded at start (not the *absence* of a checklist — its minimal version) — for code, "the change does what the prompt asked + tests/build green"; for analysis/design, a short ratified rubric. Minimal ceremony by design, but **always with the check declared first**.