@tacuchi/agent-workflow-cli 14.8.0 → 14.10.0

package/skills/w/README.md

@@ -33,7 +33,7 @@ ZONE docs/ — permanent, user-facing deliverables
 | [`loops/`](loops/) | 2 | The 5 loops (chassis `spec-refine-loop` + heirs) the AI runs |
 | [`exports/`](exports/) | 1 | The `export-*` family — the only artifact→`docs/` promotion path |
 | [`roles/`](roles/) | cross-cutting | Pluggable capability skills (built-in defaults; rebindable via `.workflow/skills.toml`) |
-| [`harness/`](harness/SKILL.md) | cross-cutting | Capability→harness-mechanism binding (agnostic across Claude Code / Codex / opencode / Gemini) |
+| [`harness/`](harness/SKILL.md) | cross-cutting | Capability→harness-mechanism binding (agnostic across Claude Code / Codex / Gemini-Antigravity / OpenCode / Crush / Warp) |
 | [`artifacts/`](artifacts/) | 3 | Session artifact templates the loops manage |
 | [`hooks/`](hooks/) | — | Host hook template (branch-check, sql-mutation-guard, checkpoint, …) |
 | [`SKILL.md`](SKILL.md) | overview | The `workflow` orientation skill (whole-model guide) |

package/skills/w/SKILL.md

@@ -154,13 +154,13 @@ Catálogo de roles y su default:
 | `diagrams` | `diagrams` | should | `export-diagrams` |
 | `overview` | `workflow` | should | cualquiera (orientación) |
 
-> **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.
+> **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).
 
 El **chasis del loop** NO se bindea: **es** el loop, no es enchufable.
 
 ### Harness (agnóstico al arnés)
 
-La doctrina nombra **capacidades** abstractas, no tools concretos de un arnés. Un solo doc —`harness/SKILL.md`— liga cada capacidad al mecanismo de cada arnés (Claude Code, Codex, opencode, Gemini, genérico). Dos principios: **capacidad-no-tool** (los loops/comandos referencian la capacidad por nombre) y **progressive-enhancement** (usar el mecanismo más rico del arnés; degradar a un fallback universal cuando no exista).
+La doctrina nombra **capacidades** abstractas, no tools concretos de un arnés. Un solo doc —`harness/SKILL.md`— liga cada capacidad al mecanismo de cada arnés (Claude Code, Codex, Gemini/Antigravity, OpenCode, Crush, Warp, genérico). Dos principios: **capacidad-no-tool** (los loops/comandos referencian la capacidad por nombre) y **progressive-enhancement** (usar el mecanismo más rico del arnés; degradar a un fallback universal cuando no exista).
 
 Capacidades clave:
 

package/skills/w/exports/README.md

@@ -64,7 +64,7 @@ Exports read the corpus through the CLI — **never hard-coded paths**:
 
 - `aw sessions` — list sessions (counts + next correlative) to enumerate the corpus.
 - `aw release-data [--since sessionNNN] [--source alias]` — consolidated dump of sessions (corpus enumeration).
-- `aw session-artifacts --code <NNN>` — lazy read of a session's artifacts.
+- `aw session-artifacts --code <NNN> [--dump [kinds]]` — counts by default; `--dump` returns `{path, content, size}` per artifact (objetivo, decisiones, conclusiones, tasks, checkpoint, backlog, scripts).
 - `aw next-number docs/<category>` — deterministic numbering of the output.
 
 > The destination-folder resolution (workspace root, single- vs multi-source) is handled by the CLI internally. If a specific flag is uncertain at implementation time, it is noted inline in each SKILL.

package/skills/w/exports/export-diagrams/SKILL.md

@@ -50,7 +50,7 @@ En plan mode **describe**, no escribe: el motor resuelto, los niveles/secciones
 **CLI `agent-workflow` (alias `aw`)** — no leer paths hardcodeados:
 
 - `aw sessions` / `aw release-data [--since sessionNNN] [--source <alias>]` — enumera el corpus (insumo del delta AS-IS/TO-BE).
-- `aw session-artifacts --code <NNN>` — lee el plan-doc (`AS-IS`/`TO-BE`/`Impacted`) por sesión.
+- `aw session-artifacts --code <NNN> --dump objetivo` — ubica la sesión y su referencia al plan-doc; `AS-IS`/`TO-BE`/`Impacted` se leen del plan-doc por su path.
 - `aw next-number docs/diagrams` — numeración determinística (la resolución de la carpeta destino la maneja el CLI).
 
 **Filesystem / código**:
@@ -70,7 +70,7 @@ En plan mode **describe**, no escribe: el motor resuelto, los niveles/secciones
 | Flag | Comportamiento |
 |---|---|
 | `--sessions NNN[,NNN]` | Filtro discreto por código (precede a `--since`); afecta el delta AS-IS/TO-BE |
-| `--since sessionNNN` | Solo sesiones posteriores a NNN (inclusive) |
+| `--since sessionNNN` | Solo sesiones posteriores a NNN (exclusivo: la propia NNN no entra; usá `--sessions` para incluirla) |
 | `--source <alias>` | Limita a una fuente (workspace multi-fuente) |
 | `--engine mermaid\|c4` | Default `mermaid` (render en GitHub); `c4` = Structurizr DSL opt-in |
 | `--scope` | Qué secciones aparecen: `c4` (contexto/contenedores/componentes), `integrations`, `data` (solo si MCP), `todo` (default) |
@@ -90,7 +90,7 @@ Por cada fuente: estructura básica, componentes internos (módulos, servicios,
 
 ### Paso 3 — Leer el delta del corpus
 
-Por sesión filtrada (`aw session-artifacts --code <NNN>`): `Current state (AS-IS)` / `Target state (TO-BE)` y `Impacted` del plan-doc. Sirve para resaltar lo que cambió sobre el snapshot vigente.
+Por sesión filtrada (`aw session-artifacts --code <NNN> --dump objetivo`): seguir la referencia al plan-doc y leer `Current state (AS-IS)` / `Target state (TO-BE)` e `Impacted`. Sirve para resaltar lo que cambió sobre el snapshot vigente.
 
 ### Paso 4 — Inspeccionar MCP (opcional)
 

package/skills/w/exports/export-manuals/SKILL.md

@@ -51,7 +51,7 @@ En plan mode **describe**, no escribe: el modo resuelto, los temas detectados (c
 **CLI `agent-workflow` (alias `aw`)** — no leer paths hardcodeados:
 
 - `aw sessions` / `aw release-data [--since sessionNNN] [--source <alias>]` — enumera el corpus.
-- `aw session-artifacts --code <NNN>` — lee `DECISION`, el plan-doc y `SESSION` (su `## Objective`, lazy) por sesión.
+- `aw session-artifacts --code <NNN> --dump objetivo,decisiones` — devuelve `{path, content, size}` por artefacto (`SESSION` con su `## Objective`, `DECISION`); el plan-doc se lee por su path.
 - `aw next-number docs/manuals` — numeración determinística (solo modo `regenerate`).
 
 **Filesystem**:
@@ -70,7 +70,7 @@ En plan mode **describe**, no escribe: el modo resuelto, los temas detectados (c
 | Flag | Comportamiento |
 |---|---|
 | `--sessions NNN[,NNN]` | Filtro discreto por código (precede a `--since`) |
-| `--since sessionNNN` | Solo sesiones posteriores a NNN (inclusive) |
+| `--since sessionNNN` | Solo sesiones posteriores a NNN (exclusivo: la propia NNN no entra; usá `--sessions` para incluirla) |
 | `--source <alias>` | Limita a una fuente (workspace multi-fuente) |
 | `--mode complement\|regenerate` | Default `complement` |
 | `--topics slug1,slug2` | Limita a los temas declarados |
@@ -97,7 +97,7 @@ Listar `docs/manuals/*.md` (excluyendo `INDEX.md` y subdirectorios `NNN-export-m
 
 ### Paso 3 — Detectar temas
 
-Por cada sesión del corpus filtrado (`aw session-artifacts --code <NNN>`): leer `DECISION` + plan-doc (`Solution`/`Final behavior`/`Validations`) + el código tocado. Tema **primario**: la sección de temas en `SESSION` (su `## Objective`). **Secundario**: inferencia por keywords operativos ("configurar", "instalar", "paso a paso", "cómo …"). Filtrar por `--topics` si está presente. Listar (slug, confidence, sesiones de origen).
+Por cada sesión del corpus filtrado (`aw session-artifacts --code <NNN> --dump objetivo,decisiones`): tomar `DECISION` del dump + plan-doc (`Solution`/`Final behavior`/`Validations`) + el código tocado. Tema **primario**: la sección de temas en `SESSION` (su `## Objective`). **Secundario**: inferencia por keywords operativos ("configurar", "instalar", "paso a paso", "cómo …"). Filtrar por `--topics` si está presente. Listar (slug, confidence, sesiones de origen).
 
 ### Paso 4 — Sintetizar (prosa: convenciones ambientes)
 

package/skills/w/exports/export-reports/SKILL.md

@@ -50,7 +50,7 @@ En plan mode **describe**, no escribe: la audiencia/longitud resuelta, las sesio
 **CLI `agent-workflow` (alias `aw`)** — no leer paths hardcodeados:
 
 - `aw sessions` / `aw release-data [--since sessionNNN] [--source <alias>]` — enumera + filtra el corpus.
-- `aw session-artifacts --code <NNN>` — lee spec referido, `CONCLUSIONS`, `DECISION` y estado del plan-doc (lazy) por sesión.
+- `aw session-artifacts --code <NNN> --dump objetivo,conclusiones,decisiones` — devuelve `{path, content, size}` de `SESSION` (spec referido), `CONCLUSIONS` y `DECISION`; el estado del plan-doc se lee por su path.
 - `aw next-number docs/reports` — numeración determinística (la resolución de la carpeta destino la maneja el CLI).
 
 **Filesystem**:
@@ -68,7 +68,7 @@ En plan mode **describe**, no escribe: la audiencia/longitud resuelta, las sesio
 | Flag | Comportamiento |
 |---|---|
 | `--sessions NNN[,NNN]` | Filtro discreto por código (precede a `--since`/`--period`) |
-| `--since sessionNNN` | Solo sesiones posteriores a NNN (inclusive) |
+| `--since sessionNNN` | Solo sesiones posteriores a NNN (exclusivo: la propia NNN no entra; usá `--sessions` para incluirla) |
 | `--source <alias>` | Limita a una fuente (workspace multi-fuente) |
 | `--period` | Ventana temporal (`last-month`/`last-quarter`/rango `YYYY-MM..YYYY-MM`) |
 | `--audience gerencia\|tecnica` | Modula longitud/léxico: `gerencia` ≈ corto/ejecutivo; `tecnica` ≈ detallado |
@@ -85,7 +85,7 @@ Sin args: todo el corpus, audiencia ejecutiva por default. *(Si algún flag exac
 
 ### Paso 2 — Recolectar inputs por sesión
 
-Por sesión filtrada (`aw session-artifacts --code <NNN>`): el spec referido (qué se planteó), `CONCLUSIONS` (cierre técnico / R-items), `DECISION` (qué se decidió), estado del plan-doc (qué se entregó / qué queda). Recoger también componentes impactados (fuentes tocadas) para la tabla de síntesis.
+Por sesión filtrada (`aw session-artifacts --code <NNN> --dump objetivo,conclusiones,decisiones`): el spec referido (qué se planteó), `CONCLUSIONS` (cierre técnico / R-items), `DECISION` (qué se decidió), estado del plan-doc (qué se entregó / qué queda). Recoger también componentes impactados (fuentes tocadas) para la tabla de síntesis.
 
 ### Paso 3 — Dedup de recomendaciones (cross-session)
 

package/skills/w/exports/export-scripts/SKILL.md

@@ -51,7 +51,7 @@ En plan mode **describe**, no escribe: el `NNN` resuelto, las fuentes detectadas
 **CLI `agent-workflow` (alias `aw`)** — no leer paths hardcodeados:
 
 - `aw sessions` / `aw release-data [--since sessionNNN] [--source <alias>]` — enumera el corpus de sesiones.
-- `aw session-artifacts --code <NNN>` — lee `SCRIPTS.sql` de cada sesión (lazy). Si no existe → skip silencioso.
+- `aw session-artifacts --code <NNN> --dump scripts` — lista los `.sql` de la sesión con path y size (el contenido se lee por path). Si no hay scripts → lista vacía, skip silencioso.
 - `aw next-number docs/scripts` — numeración determinística del directorio del bundle (la resolución de la carpeta destino la maneja el CLI).
 
 **Filesystem**:
@@ -68,7 +68,7 @@ En plan mode **describe**, no escribe: el `NNN` resuelto, las fuentes detectadas
 | Flag | Comportamiento |
 |---|---|
 | `--sessions NNN[,NNN]` | Filtro discreto por código (precede a `--since`) |
-| `--since sessionNNN` | Solo sesiones posteriores a NNN (inclusive) |
+| `--since sessionNNN` | Solo sesiones posteriores a NNN (exclusivo: la propia NNN no entra; usá `--sessions` para incluirla) |
 | `--source <alias>` | Limita a una fuente (workspace multi-fuente) |
 | `--skip-standalone` | Omite la lectura de `docs/scripts/*.sql` standalone |
 | `--dry-run` | Reporte propositivo sin escribir archivos |
@@ -79,7 +79,7 @@ Sin args: todas las sesiones del corpus + todos los `.sql` standalone (excluyend
 
 ### Paso 1 — Recolección de fuentes SQL
 
-**Fuente A — sesiones**: por cada sesión del corpus (`aw sessions` / `release-data` + `session-artifacts --code <NNN>`), leer `.workflow/sessions/<folder>/SCRIPTS.sql` si existe. Tomar **solo** las sentencias tipo-B (migraciones DDL/DML entregables); ignorar el tipo-A read-only (consultas de diagnóstico). Markers esperados por sentencia: `-- @category: <01-04>` + `-- @stmt: NNN-verbo-objetivo` (formato definido por la capacidad `sql`).
+**Fuente A — sesiones**: por cada sesión del corpus (`aw sessions` / `release-data` + `session-artifacts --code <NNN> --dump scripts`), leer los `.sql` que el dump lista (path por script). Tomar **solo** las sentencias tipo-B (migraciones DDL/DML entregables); ignorar el tipo-A read-only (consultas de diagnóstico). Markers esperados por sentencia: `-- @category: <01-04>` + `-- @stmt: NNN-verbo-objetivo` (formato definido por la capacidad `sql`).
 
 **Fuente B — standalone** (salvo `--skip-standalone`): listar `docs/scripts/*.sql` top-level, **excluyendo** `docs/scripts/NNN-export-scripts-*/`. Por archivo: respetar markers `@category` si los hay; si no, inferir categoría del contenido (`CREATE/ALTER TABLE`, `CREATE INDEX` → `01`; `CREATE OR REPLACE FUNCTION`/`PROCEDURE` → `02`; `UPDATE`/`DELETE` → `03`; `INSERT INTO … VALUES` → `04`). Si el filename contiene `rollback` → skip (no entra en forward).
 

package/skills/w/loops/README.md

@@ -111,7 +111,7 @@ Los loops componen **capacidades por su rol**, no skills concretas; la skill que
 | `research` | `research` | todos los loops (research inline) |
 | `overview` | `workflow` | cualquiera (orientación) |
 
-> **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.
+> **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).
 
 `off` en config → capacidad desactivada: el loop sigue sin ella; si era necesaria, lo dice o pregunta al humano.
 

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

@@ -1,22 +1,16 @@
 ---
 name: plan-exec-loop
 description: >-
-  Ejecuta un plan de implementación (docs/plans/PPP-plan-<slug>.md) como living
-  doc: lo lee y actualiza fase a fase mientras edita el código real, gestiona BD
-  y git. Heir del chasis spec-refine-loop: reusa su motor gap-driven, research
-  inline (regla BD read-only), structured-choice (≤3 preguntas + control flow
-  Compactar/Cerrar) y artefactos como log vivo (CHECKPOINT siempre, BACKLOG solo
-  si difiere). Deltas: una sola session por run (resume vía checkbox del plan-doc
-  + CHECKPOINT); git seguro (verifica la rama antes de editar, propone commits por
-  fuente, nunca push/--amend/--no-verify); la IA NUNCA ejecuta DML/DDL (las
-  migraciones se redactan en SCRIPTS.sql, solo read-only se ejecuta); validación
-  por fase y final (lo dependiente de migración no aplicada se difiere a DBA);
-  gate de revisión de cierre por fase ANTES de proponer commits (re-lectura
-  independiente del diff aplicando las convenciones ambientes instaladas —
-  corrige o difiere; nada llega a un commit sin revisar); y
-  SIN auto-export (escribe solo docs/plans; el resto queda como artefacto para
-  export-*). Compone git y sql. Lo arranca /w:plan-exec, es reanudable. Invocar
-  para implementar un plan ya generado.
+  Ejecuta un plan de implementación (docs/plans/PPP-plan-<slug>.md) como
+  living doc: lo lee y actualiza fase a fase mientras edita el código real,
+  gestiona BD y git. Heir del chasis spec-refine-loop (motor gap-driven,
+  research inline, structured-choice, artefactos como log vivo); sus deltas
+  viven en el cuerpo: session única reanudable, git seguro (rama verificada,
+  commits propuestos por fuente, nunca push/--amend/--no-verify), BD solo-
+  scripts (la IA nunca ejecuta DML/DDL), validación por fase y final, gate de
+  revisión de cierre pre-commit, y sin auto-export (solo escribe docs/plans).
+  Compone git y sql. Lo arranca /w:plan-exec. Invocar para implementar un plan
+  ya generado.
 ---
 
 # plan-exec-loop
@@ -57,7 +51,7 @@ Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
 
 `git` (rama segura + commits propuestos) · `sql` (regla BD). Ambas resueltas por `.workflow/skills.toml`; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta.
 
-> **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.
+> **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).
 
 ## Internal sessions (managed)
 
@@ -77,7 +71,7 @@ Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
 
 ## Delta 2 — Git policy: **rama segura + commits propuestos**
 
-- **Antes de editar** archivos de una fuente: verifica rama actual = rama esperada de esa fuente (estilo `branch-check`). Si no coincide → **pausa y resuelve con el humano**; nunca `stash`/`reset --hard`/`checkout -- .`/`clean` sin confirmación por fuente.
+- **Antes de editar** archivos de una fuente: verifica rama actual = rama esperada de esa fuente (`aw check-branch --source <alias>`; ver rol `git`). Si no coincide → **pausa y resuelve con el humano**; nunca `stash`/`reset --hard`/`checkout -- .`/`clean` sin confirmación por fuente.
 - **Al cerrar una fase** (o al `Cerrar`): **tras pasar el gate de revisión de cierre** (Delta 5), **propone commits por fuente** (propose-then-execute, aprobar antes); nunca `push`/`--amend`/`--no-verify`. Nada llega a un commit propuesto sin revisar.
 - **Commit rechazado**: los cambios **quedan en el working tree** (no se revierten). Se permite reproponer / editar mensaje. Se registra en `CHECKPOINT` + `BACKLOG` que la fase quedó **sin commitear** (reanudable).
 - **Precondición entre fases**: `branch-check` valida *identidad* de rama, **no** *limpieza* del working tree. Antes de iniciar la siguiente fase, el working tree de cada fuente debe estar **limpio** (committeado) o explícitamente **reconocido** como "cambios sin commitear de la fase N" — para no co-mezclar dos fases en un mismo commit.

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

@@ -1,22 +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); una gap taxonomy propia de planificación; y si el plan incluye
-  UI compone la capacidad ui-design para autorar design SPECs por pantalla
-  (NNN-SPEC-<SLUG>.md) como artefactos de su sesió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

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

@@ -1,19 +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). Si el refine toca UI,
-  compone la capacidad ui-design y produce/actualiza design SPECs por pantalla
-  (NNN-SPEC-<SLUG>.md) en su propia sesión. 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.
 ---
 

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

@@ -1,21 +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; gate de revisión de cierre proporcional: re-lee el diff con
-  las convenciones ambientes instaladas y corrige antes de proponer el commit).
-  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
@@ -52,7 +46,7 @@ QUICK
 
 `git` · `sql` (regla BD) · `research` (inline). Resueltas por `.workflow/skills.toml`.
 
-> **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.
+> **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).
 
 ## Delta QUICK — minimal ceremony
 
@@ -84,7 +78,7 @@ quick-loop(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 (branch-check); si no → pausar + resolver
+    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)

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

@@ -127,7 +127,7 @@ El gap **UI sin especificar** (cuando el requerimiento involucra UI; ver *Gap ta
 
 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.
+> **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).
 
 ## Deliverable schema (el spec, editado in place)
 

package/skills/w/roles/README.md

@@ -23,7 +23,7 @@ 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`) **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.
+> **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.
 >
 > **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/git/SKILL.md

@@ -52,7 +52,7 @@ Y **siempre** prohibido, aún cuando el usuario pida commit: `--no-verify` (resp
 
 La rama esperada **nunca se asume desde la rama actual** — el usuario pudo cambiarla a mano. Verificar contra la rama de trabajo declarada por fuente antes de cualquier `Write/Edit`.
 
-Campos por fuente: `alias`, `path`, `main_branch` (base, default `certificacion`), `expected_work_branch`, `current_branch`, `match` (`current == expected`), `dirty` (cambios sin commit).
+**Mecanismo primario**: `aw check-branch --source <alias>` (o `--file <path-del-edit-inminente>`; `--strict` devuelve exit 2 en mismatch — útil como gate). Devuelve ya computados los campos por fuente: `alias`, `path`, `main_branch` (base, default `certificacion`), `expected_work_branch`, `current_branch`, `match` (`current == expected`), `dirty` (cambios sin commit). **Fallback** (repo suelto sin workspace/CLI): computarlos con git read-only directo (`git branch --show-current` + `git status --porcelain`) más la rama declarada por la sesión.
 
 Casos:
 
@@ -67,7 +67,7 @@ Casos:
 
 Ante cualquier pedido o disparo de commit (cierre de loop, "commitea esto", "guardá los cambios"):
 
-1. Resolver las fuentes y su estado dirty/rama.
+1. Resolver las fuentes y su estado dirty/rama con `aw sources` (inventario con git status enriquecido; fallback: git directo por fuente).
 2. Si hay 1+ fuentes `dirty=true`, invocar **una sola** *structured-choice* con una pregunta de contenido por fuente dirty (máx 4 simultáneas → **≤3 preguntas de contenido + 1 control `flow`**; si N>3, en tandas):
    - Header de la pregunta: el `alias` de la fuente.
    - Opciones: "Aprobar sugerido (Recomendado)" con el mensaje canónico / "Saltar esta fuente". `Other` = mensaje custom.
@@ -116,4 +116,4 @@ Ninguno en `docs/`. Produce commits **solo** cuando el usuario aprueba, en los r
 
 ## Source
 
-Reciclada de la doctrina vieja: `doctrine/session/references/commits-policy.md` (Reglas 1-5: propose-then-execute, formato canónico, bypass) + `doctrine/session/references/branch-verification.md` (Casos A/B/C, cross-fuente hard gate). Se descarta la dependencia de comandos CLI específicos (`agent-workflow sources`): la verificación se hace con git read-only directo más la rama de trabajo declarada por la sesión.
+Reciclada de la doctrina vieja: `doctrine/session/references/commits-policy.md` (Reglas 1-5: propose-then-execute, formato canónico, bypass) + `doctrine/session/references/branch-verification.md` (Casos A/B/C, cross-fuente hard gate). La verificación delega lo mecánico al CLI (`aw check-branch`, `aw sources`) — computarlo a mano en cada task pagaba tokens por trabajo que el runtime ya expone; el git read-only directo queda como fallback para repos sin workspace.