@tacuchi/agent-workflow-cli 11.0.1 → 12.0.0

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

@@ -0,0 +1,127 @@
+---
+name: export-manuals
+description: "Sintetiza manuales técnicos del workspace en `docs/manuals/` consolidando N sesiones (`exec`/`quick`) + `docs/`. Lee de cada sesión el `DECISION` y el plan-doc (`Solution`, `Final behavior`, `Validations`) + el código tocado en las fuentes (cómo opera/funciona lo construido). Dos modos: `complement` (default, sobrescribe `INDEX.md` apuntando a los manuales detectados) y `regenerate` (produce dossier `NNN-export-manuals-YYYY-MM-DD/` con 1 manual por tema). Audiencia: operadores / soporte / onboarding. Read-only/reporte: no commitea ni muta sesiones. Compone la capacidad `writing`. Úsalo para 'manual operativo', 'cómo funciona lo entregado', 'paquete de onboarding técnico', 'índice de manuales'. Invocado por el usuario vía `/w:export-manuals`."
+---
+
+# export-manuals — Manuales técnicos desde sesiones + `docs/`
+
+Genera o refresca manuales de **operación / cómo-funciona / onboarding** en `docs/manuals/`, consolidando lo entregado en N sesiones + el corpus `docs/`. **Read-only / reporte** — no commitea, no muta sesiones ni el código.
+
+> Familia `export-*` (la única vía artefacto→`docs/`). Recicla el espíritu del viejo `export-tech-manuals` (modos complementar/regenerar, `INDEX.md`, dossier por tema), modernizado: `docs/manuals` en inglés, sin modos project/hub, y la prosa la aporta la capacidad `writing` (no una skill propia). Diseño: `docs/referencias/workflow-exports/export-manuals.md`.
+
+## Category
+
+`docs/manuals` — **única** carpeta `docs/` que este export escribe.
+
+## Composes
+
+Capacidad **`writing`** (built-in default `writing`), resuelta vía `.workflow/skills.toml`. Aporta la redacción accionable (frases cortas, listas sobre prosa, sin relleno) y el léxico técnico para la audiencia operador/soporte. Este export **no** posee esa lógica: la compone. Rebindeable u `off` por config.
+
+## When to use
+
+- "Manual operativo", "cómo funciona lo que entregamos", "guía paso a paso".
+- "Índice de manuales" / refrescar el `INDEX.md` tras nuevas sesiones.
+- Paquete de **onboarding técnico** para nuevos miembros del equipo.
+- Auditoría de cobertura documental.
+
+## What it does
+
+1. Lee el corpus de sesiones (`exec`/`quick`): por sesión, `DECISION` + el plan-doc (`Solution`, `Final behavior`, `Validations`).
+2. Inspecciona el código tocado en las fuentes (cómo opera/funciona lo construido) — solo lectura.
+3. Detecta temas (declarados en el OBJECTIVE/`SESSION`, o inferidos por keywords operativos).
+4. Resuelve el modo (`complement` o `regenerate`).
+5. Sintetiza el contenido aplicando la capacidad `writing`.
+6. Escribe: `complement` → sobrescribe `docs/manuals/INDEX.md`; `regenerate` → dossier `docs/manuals/NNN-export-manuals-YYYY-MM-DD/` con 1 manual por tema.
+
+## What it does NOT do
+
+- Ejecutar commits, merges, push, SQL ni envío de correos.
+- Mutar sesiones, el plan-doc, ni el código de las fuentes (solo lectura).
+- Escribir cualquier carpeta `docs/` que no sea `docs/manuals/` (invariante: una categoría).
+- Sobrescribir un dossier `regenerate` previo (siempre next-number).
+- Inventar manuales: si no hay tema detectable → en `regenerate` aborta con mensaje claro; en `complement` produce un `INDEX.md` vacío con nota inline.
+- Renderizar visualmente diagramas (la arquitectura visual es de `export-diagrams`; Mermaid embebido solo si aporta).
+
+## Read-only sandbox
+
+En plan mode **describe**, no escribe: el modo resuelto, los temas detectados (con sesiones de origen), los manuales ya presentes en `docs/manuals/`, y — según el modo — la estructura del `INDEX.md` que sobrescribiría o el count de manuales que generaría el dossier. **No** ejecuta `Write` ni `aw next-number` con efecto.
+
+## Inputs
+
+**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 el OBJECTIVE/`SESSION` (lazy) por sesión.
+- `aw next-number docs/manuals` — numeración determinística (solo modo `regenerate`).
+
+**Filesystem**:
+
+- `docs/manuals/*.md` — manuales ya presentes (para complementar).
+- `docs/manuals/INDEX.md` — re-generable (sobrescribible) en modo `complement`.
+- Código de las fuentes declaradas — lectura para describir el comportamiento.
+
+**Args** (sin lifecycle `AskUserQuestion`):
+
+```
+/w:export-manuals [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]
+                  [--mode complement|regenerate] [--topics slug1,slug2] [--dry-run]
+```
+
+| Flag | Comportamiento |
+|---|---|
+| `--sessions NNN[,NNN]` | Filtro discreto por código (precede a `--since`) |
+| `--since sessionNNN` | Solo sesiones posteriores a NNN (inclusive) |
+| `--source <alias>` | Limita a una fuente (workspace multi-fuente) |
+| `--mode complement\|regenerate` | Default `complement` |
+| `--topics slug1,slug2` | Limita a los temas declarados |
+| `--dry-run` | Reporte propositivo sin escribir archivos |
+
+Sin args: `--mode complement` sobre todo el corpus. *(Si algún flag exacto difiere en el CLI runtime, ajustar al contrato real de `aw`.)*
+
+### Resolución de `--mode`
+
+| Modo | Output | Cuándo usar |
+|---|---|---|
+| `complement` (default) | `docs/manuals/INDEX.md` (sobrescribe) | Refrescar el índice tras nuevas sesiones/manuales |
+| `regenerate` | `docs/manuals/NNN-export-manuals-YYYY-MM-DD/` (next-number) | Paquete consolidado de manuales (ej. onboarding) |
+
+## Flow
+
+### Paso 1 — Resolver contexto y corpus
+
+`aw sessions` / `release-data` aplicando `--sessions`/`--since`/`--source`. La resolución de la carpeta destino la maneja el CLI.
+
+### Paso 2 — Inspeccionar manuales presentes
+
+Listar `docs/manuals/*.md` (excluyendo `INDEX.md` y subdirectorios `NNN-export-manuals-*/`). Por manual: slug (del filename), título (primer `#`), resumen breve (primer párrafo), path.
+
+### 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**: sección de temas en el OBJECTIVE/`SESSION`. **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 (compone `writing`)
+
+**Modo `complement`** — un `INDEX.md`: cabecera + count de manuales + tabla (Tema · Slug · Manual presente/`[pendiente]` · Sesiones de origen) + "Próximos pasos" si hay temas pendientes.
+
+**Modo `regenerate`** — 1 `.md` por tema en el dossier, cada uno con: Propósito · Pre-requisitos · Pasos numerados (cómo operar) · Comportamiento final (del plan-doc) · Validación post-uso · Decisiones relevantes (`DECISION`) · Troubleshooting · Referencias. Cada manual debe permitir al operador completar la tarea **sin** invocar al equipo de desarrollo. Más un `README.md` del dossier con el índice. La redacción aplica la capacidad `writing`.
+
+### Paso 5 — Escribir o reportar
+
+Si `--dry-run`: imprimir el reporte; no escribir. Si no: `complement` → `Write` sobre `docs/manuals/INDEX.md`; `regenerate` → `aw next-number docs/manuals` + crear el dossier. **NUNCA commitear**. Resumen al usuario: modo + paths escritos + counts; si hay temas detectables sin manual, sugerir cubrirlos.
+
+## Output location
+
+- `complement`: `docs/manuals/INDEX.md` (sobrescribe).
+- `regenerate`: `docs/manuals/NNN-export-manuals-YYYY-MM-DD/` con `README.md` + 1 `.md` por tema.
+
+## Re-run
+
+- `complement`: idempotente — dos invocaciones con el mismo corpus producen el mismo `INDEX.md`.
+- `regenerate`: cada invocación toma el siguiente `NNN`; no sobrescribe dossiers previos.
+
+## Resources
+
+- Design: `docs/referencias/workflow-exports/export-manuals.md` · familia: [`../README.md`](../README.md).
+- Capacidad compuesta: `writing` (built-in default; ver `docs/referencias/workflow-skills/`).
+- Artefactos fuente: `DECISION` + plan-doc (ver `docs/referencias/workflow-artifacts/artifacts-dev/` y `docs/specs`/`docs/plans`).
+- Siblings: [`../export-scripts/SKILL.md`](../export-scripts/SKILL.md) · [`../export-diagrams/SKILL.md`](../export-diagrams/SKILL.md) · [`../export-reports/SKILL.md`](../export-reports/SKILL.md).

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

@@ -0,0 +1,115 @@
+---
+name: export-reports
+description: "Consolida N sesiones del workspace en un informe ejecutivo/funcional bajo `docs/reports/NNN-<slug>-YYYY-MM-DD.md`. Lee el corpus: el spec (`docs/specs`), `CONCLUSIONS` (research), `DECISION`, el estado del plan-doc + el resto de `docs/` para contexto. Sintetiza: qué se hizo, decisiones clave, resultados/conclusiones, pendientes/roadmap — con dedup de recomendaciones cross-session. Audiencia ajustable vía `--audience` (gerencia ≈ corto; tecnica ≈ detallado). Funde el espíritu de los viejos export-report (ejecutivo) y export-conclusions (dedup de R-items) en una sola salida a `docs/reports`. Read-only/reporte: no commitea ni muta sesiones. Compone la capacidad `writing`. Úsalo para 'informe ejecutivo', 'qué se hizo este trimestre para gerencia', 'brief con recomendaciones consolidadas'. Invocado por el usuario vía `/w:export-reports`."
+---
+
+# export-reports — Informe ejecutivo/funcional desde el corpus de sesiones + `docs/`
+
+Genera un único `.md` que consolida N sesiones del workspace en un informe **ejecutivo/funcional**: qué se hizo, decisiones clave, resultados/conclusiones y pendientes/roadmap. **Read-only / reporte** — no commitea, no muta sesiones ni el corpus.
+
+> Familia `export-*` (la única vía artefacto→`docs/`). **Funde** el espíritu de dos viejos exports en una sola salida a `docs/reports`: `export-report` (informe ejecutivo con tabla de componentes + diagrama de flujo) y `export-conclusions` (dedup de R-items cross-session). Modernizado: `docs/reports` en inglés, sin modos project/hub, y la prosa la aporta la capacidad `writing`. Diseño: `docs/referencias/workflow-exports/export-reports.md`.
+
+## Category
+
+`docs/reports` — **única** carpeta `docs/` que este export escribe.
+
+## Composes
+
+Capacidad **`writing`** (built-in default `writing`), resuelta vía `.workflow/skills.toml`. Aporta la traducción técnico→ejecutiva, la cota de longitud por audiencia y el léxico (frases cortas, listas sobre prosa, sin relleno). Este export **no** posee esa lógica: la compone. Rebindeable u `off` por config.
+
+## When to use
+
+- "Informe ejecutivo", "documento funcional", "qué se hizo este trimestre para gerencia".
+- Brief con las **recomendaciones consolidadas** (deduplicadas) de las últimas N sesiones.
+- Re-generar tras un nuevo período (mes / trimestre); antes de un comité de seguimiento.
+
+## What it does
+
+1. Lee el corpus de sesiones filtrado: el spec (`docs/specs`), `CONCLUSIONS` (research), `DECISION`, el estado del plan-doc.
+2. Lee el resto de `docs/` (specs, plans, reports previos) para contexto.
+3. Resuelve la audiencia/longitud (`--audience`).
+4. Sintetiza: Resumen ejecutivo · Qué se hizo (agrupado por capacidad de negocio, no por sesión) · Decisiones clave · Resultados/conclusiones · Pendientes/Roadmap.
+5. **Deduplica** las recomendaciones (R-items) cross-session por slug, anotando los orígenes.
+6. Escribe `docs/reports/NNN-<slug>-YYYY-MM-DD.md`.
+
+## What it does NOT do
+
+- Ejecutar commits, merges, push, SQL ni envío de correos / creación de PRs.
+- Mutar sesiones, el corpus ni el plan-doc (solo lectura).
+- Escribir cualquier carpeta `docs/` que no sea `docs/reports/` (invariante: una categoría).
+- Inventar logros, métricas o recomendaciones: las secciones condicionales (p.ej. "Oportunidades de mejora"/Roadmap) **solo** aparecen si el corpus tiene items abiertos detectables.
+- Generar diagramas técnicos avanzados (C4/erDiagram extenso) — esos viven en `export-diagrams`; aquí, como mucho, un `flowchart LR` simple de síntesis ejecutiva.
+- Sobrescribir reports previos (siempre next-number).
+
+## Read-only sandbox
+
+En plan mode **describe**, no escribe: la audiencia/longitud resuelta, las sesiones del corpus que entrarían tras los filtros, las secciones que aparecerían, los R-items que se consolidarían (y conflictos detectados), y la longitud estimada. **No** ejecuta `Write` ni `aw next-number` con efecto.
+
+## Inputs
+
+**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 next-number docs/reports` — numeración determinística (la resolución de la carpeta destino la maneja el CLI).
+
+**Filesystem**:
+
+- `docs/specs`, `docs/plans`, `docs/reports/*` — contexto + no colisionar.
+
+**Args** (sin lifecycle `AskUserQuestion`):
+
+```
+/w:export-reports [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]
+                  [--period last-quarter|last-month|YYYY-MM..YYYY-MM]
+                  [--audience gerencia|tecnica] [--slug <kebab>] [--dry-run]
+```
+
+| Flag | Comportamiento |
+|---|---|
+| `--sessions NNN[,NNN]` | Filtro discreto por código (precede a `--since`/`--period`) |
+| `--since sessionNNN` | Solo sesiones posteriores a NNN (inclusive) |
+| `--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 |
+| `--slug <kebab>` | Override del slug del filename (default: `export-reports`) |
+| `--dry-run` | Reporte propositivo sin escribir |
+
+Sin args: todo el corpus, audiencia ejecutiva por default. *(Si algún flag exacto difiere en el CLI runtime, ajustar al contrato real de `aw`.)*
+
+## Flow
+
+### Paso 1 — Resolver contexto y filtrar corpus
+
+`aw sessions` / `release-data` aplicando `--sessions`/`--since`/`--source`/`--period`. Si el conjunto resultante está vacío → **abortar** con mensaje explícito ("No hay sesiones en el rango declarado"). La resolución de la carpeta destino la maneja el CLI.
+
+### 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.
+
+### Paso 3 — Dedup de recomendaciones (cross-session)
+
+Extraer los R-items de `CONCLUSIONS`/`DECISION` (pendientes, diferidos, "próximos pasos"). Agrupar por slug; merge de duplicados anotando `origins[]`; si dos R-items del mismo slug se contradicen, marcarlos como conflicto para resolución explícita. **No** deduplicar los C-items (son específicos de cada análisis: se preservan con trazabilidad).
+
+### Paso 4 — Sintetizar (compone `writing`)
+
+Render aplicando la capacidad `writing`: Resumen ejecutivo · Qué se hizo (agrupado por capacidad de negocio, **no** por sesión) · Componentes impactados (tabla) · Decisiones clave · Resultados/conclusiones · Pendientes/Roadmap (solo si hay R-items). Traducción técnico→ejecutiva y cota de longitud por `--audience`. Opcional: un `flowchart LR` simple de síntesis (con link `mermaid.ink`); el diagrama técnico detallado es de `export-diagrams`.
+
+### Paso 5 — Escribir o reportar
+
+`aw next-number docs/reports` → `docs/reports/NNN-<slug>-YYYY-MM-DD.md`. Si `--dry-run`: imprimir; no escribir. **NUNCA commitear**. Resumen al usuario: ruta, audiencia/longitud, sesiones cubiertas (count + rango), R-items consolidados, y nota si se omitió una sección condicional.
+
+## Output location
+
+`docs/reports/NNN-<slug>-YYYY-MM-DD.md` (default slug `export-reports`).
+
+## Re-run
+
+Idempotente funcional: cada invocación toma el siguiente `NNN`; no sobrescribe reports previos. Para regenerar el último: borrar el archivo y re-invocar.
+
+## Resources
+
+- Design: `docs/referencias/workflow-exports/export-reports.md` · familia: [`../README.md`](../README.md).
+- Capacidad compuesta: `writing` (built-in default; ver `docs/referencias/workflow-skills/`).
+- Insumos: spec (`docs/specs`), `CONCLUSIONS`/`DECISION` (ver `docs/referencias/workflow-artifacts/`), plan-doc (`docs/plans`).
+- Siblings: [`../export-scripts/SKILL.md`](../export-scripts/SKILL.md) · [`../export-manuals/SKILL.md`](../export-manuals/SKILL.md) · [`../export-diagrams/SKILL.md`](../export-diagrams/SKILL.md).

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

@@ -0,0 +1,135 @@
+---
+name: export-scripts
+description: "Consolida los SQL pendientes del workspace en un único bundle `docs/scripts/NNN-export-scripts-YYYY-MM-DD/` con numeración continua tras `00-ROLLBACK.sql`. Lee migraciones tipo-B (DDL/DML) desde dos fuentes: `.workflow/sessions/<folder>/SCRIPTS.sql` de N sesiones Y `docs/scripts/*.sql` standalone (excluyendo bundles previos). Ignora el tipo-A read-only (consultas de diagnóstico, no entregables). Headers SQL mínimos + README simple (3 secciones: Archivos / Aplicar / Revertir). El rollback se deriva de los forwards. Read-only/reporte: NUNCA ejecuta SQL ni commitea — el bundle es para que un humano/DBA lo aplique. Compone la capacidad `sql`. Úsalo para 'bundle SQL del release', 'preparar paso a prod', 'consolidar SQLs pendientes'. Invocado por el usuario vía `/w:export-scripts`."
+---
+
+# export-scripts — Bundle SQL consolidado, simple y directo
+
+Consolida las migraciones SQL pendientes de N sesiones + archivos standalone en un único bundle bajo `docs/scripts/NNN-export-scripts-YYYY-MM-DD/`, con numeración continua tras `00-ROLLBACK.sql`. **Read-only / reporte** — la IA **nunca ejecuta** el SQL; el usuario/DBA aplica el bundle manualmente.
+
+> Familia `export-*` (la única vía artefacto→`docs/`). Recicla el espíritu del viejo `export-scripts` v5.0.0 (numeración continua, headers SQL minimal, README de 3 secciones, rollback derivado de forwards), modernizado al modelo nuevo (sin modos project/hub; `docs/scripts` en inglés). Diseño: `docs/referencias/workflow-exports/export-scripts.md`.
+
+## Category
+
+`docs/scripts` — **única** carpeta `docs/` que este export escribe.
+
+## Composes
+
+Capacidad **`sql`** (built-in default `sql`), resuelta vía `.workflow/skills.toml`. Aporta el vocabulario de categorías DDL/DML, el orden de aplicación y la derivación de rollback. Este export **no** posee esa lógica: la compone. Rebindeable u `off` por config.
+
+## When to use
+
+- "Bundle SQL del release", "preparar paso a prod", "consolidar SQLs pendientes".
+- Antes de promover una rama a certificación / `main`.
+- Tras varias sesiones `exec`/`quick` que dejaron `SCRIPTS.sql` con migraciones.
+
+## What it does
+
+1. Recolecta SQL del workspace desde **dos fuentes**: `SCRIPTS.sql` tipo-B de cada sesión del corpus + `docs/scripts/*.sql` standalone (excluyendo bundles previos).
+2. Clasifica las sentencias por categoría canónica (DDL-TABLES / DDL-FUNCTIONS / DML / INSERTS).
+3. Consolida cross-source por categoría con **numeración continua** tras `00-ROLLBACK.sql`.
+4. Escribe los forwards consolidados (cada sentencia con su origen, 1 línea).
+5. Deriva `00-ROLLBACK.sql` **al final**, leyendo los forwards ya escritos.
+6. Escribe un `README.md` minimal (Archivos / Aplicar / Revertir).
+
+## What it does NOT do
+
+- **Ejecutar SQL** (invariante BD scripts-only). El bundle es entregable; lo aplica un humano/DBA.
+- Commitear, mergear, push.
+- Tocar `.workflow/sessions/` ni los `docs/scripts/*.sql` standalone (solo lectura).
+- Escribir cualquier carpeta `docs/` que no sea `docs/scripts/` (invariante: una categoría).
+- Migrar bundles previos (`docs/scripts/NNN-export-scripts-*/` quedan como histórico).
+- Incluir el tipo-A read-only (consultas de diagnóstico) ni inventar SQL.
+- Generar plantillas de correo, checklists de producción, listados de commits/sesiones, ni resúmenes ejecutivos en el README.
+
+## Read-only sandbox
+
+En plan mode **describe**, no escribe: el `NNN` resuelto, las fuentes detectadas (sesiones + standalone), las categorías con contenido, los archivos que aparecerían al root del bundle y el contenido aproximado del README. **No** ejecuta `Write`, ni `aw next-number` con efecto, ni mutaciones.
+
+## Inputs
+
+**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 next-number docs/scripts` — numeración determinística del directorio del bundle (la resolución de la carpeta destino la maneja el CLI).
+
+**Filesystem**:
+
+- `docs/scripts/*.sql` standalone (solo top-level), **excluyendo** cualquier `docs/scripts/NNN-export-scripts-*/` (outputs previos de este export).
+
+**Args** (sin lifecycle `AskUserQuestion`):
+
+```
+/w:export-scripts [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]
+                  [--skip-standalone] [--dry-run]
+```
+
+| Flag | Comportamiento |
+|---|---|
+| `--sessions NNN[,NNN]` | Filtro discreto por código (precede a `--since`) |
+| `--since sessionNNN` | Solo sesiones posteriores a NNN (inclusive) |
+| `--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 |
+
+Sin args: todas las sesiones del corpus + todos los `.sql` standalone (excluyendo bundles previos). *(Si algún flag exacto difiere en el CLI runtime, ajustar al contrato real de `aw`.)*
+
+## Flow
+
+### 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 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).
+
+Si la unión A + B está vacía → **abortar**: "No hay SQL pendientes en el workspace".
+
+### Paso 2 — Numeración del bundle
+
+`aw next-number docs/scripts` → `docs/scripts/NNN-export-scripts-YYYY-MM-DD/`.
+
+### Paso 3 — Clasificación y orden interno
+
+Agrupar por categoría canónica: `01 DDL-TABLES` · `02 DDL-FUNCTIONS` · `03 DML` · `04 INSERTS`. Orden interno cronológico por origen (sesión ascendente → stmt ascendente; standalone intercalado por orden léxico del filename).
+
+### Paso 4 — Numeración continua (sin gaps)
+
+Asignar números secuenciales **solo a las categorías con contenido**, en el orden canónico. El primer forward siempre es `01-…`. Ej.: solo DML → `00-ROLLBACK.sql`, `01-DML.sql`; las 4 categorías → `00-ROLLBACK.sql`, `01-DDL-TABLES.sql`, `02-DDL-FUNCTIONS.sql`, `03-DML.sql`, `04-INSERTS.sql`.
+
+### Paso 5 — Escribir forwards
+
+Por categoría con contenido, un archivo con header de 1-2 líneas (`-- 0N-<CATEGORIA>.sql — bundle NNN-export-scripts-YYYY-MM-DD`) y, por sentencia, **un comentario de una línea** con el origen (`-- sessionXXX / stmt-id` o `-- docs/scripts/001-filename.sql`) seguido del SQL tal cual lo escribió el developer (envuelto en `BEGIN; … COMMIT;` si aplica). No replicar motivación/impacto/idempotencia ya presentes en el origen; no agregar índice de sentencias ni SELECTs de verificación inventados.
+
+### Paso 6 — Derivar `00-ROLLBACK.sql` (al final)
+
+Vía la capacidad `sql`, **leyendo los forwards ya escritos** (no el `SCRIPTS.sql` original): sentencias inversas en orden inverso (último→primero), bloque transaccional único, y un bloque "Cleanup irreversible" al final fuera de transacción solo si hay operaciones sin reversa automática.
+
+### Paso 7 — Escribir `README.md` (3 secciones)
+
+`## Archivos` (tabla: 1 fila por archivo presente) · `## Aplicar` (un `psql -f` por archivo en orden ascendente; el export no ejecuta nada) · `## Revertir` (`psql -f 00-ROLLBACK.sql` + nota si hay bloque irreversible). **Vetado**: resumen ejecutivo, tabla de sesiones, plantillas de correo, listado de commits, checklist de producción.
+
+### Paso 8 — Escribir o reportar
+
+Si `--dry-run`: imprimir el reporte; no escribir. Si no: `Write` del bundle. **NUNCA commitear**. Resumen al usuario: una línea por archivo escrito + ruta del bundle (sin replicar el README).
+
+## Output location
+
+```
+docs/scripts/NNN-export-scripts-YYYY-MM-DD/
+├── 00-ROLLBACK.sql       # reversa derivada de los forwards
+├── 01-<CATEGORIA>.sql    # primer forward (numeración continua)
+├── 02-<CATEGORIA>.sql    # …según categorías con contenido
+└── README.md             # Archivos · Aplicar · Revertir
+```
+
+## Re-run
+
+Idempotente funcional: cada invocación toma el siguiente `NNN` y **no sobrescribe** bundles previos. Para regenerar: borrar el directorio manualmente y re-invocar.
+
+## Resources
+
+- Design: `docs/referencias/workflow-exports/export-scripts.md` · familia: [`../README.md`](../README.md).
+- Capacidad compuesta: `sql` (built-in default; ver `docs/referencias/workflow-skills/`).
+- Artefacto fuente: `SCRIPTS.sql` (ver `docs/referencias/workflow-artifacts/artifacts-core/`).
+- Siblings: [`../export-manuals/SKILL.md`](../export-manuals/SKILL.md) · [`../export-diagrams/SKILL.md`](../export-diagrams/SKILL.md) · [`../export-reports/SKILL.md`](../export-reports/SKILL.md).

package/skills/w/hooks/README.md

@@ -0,0 +1,15 @@
+# hooks — host hook template
+
+`hooks.template.json` wires the host (Claude Code) to the `agent-workflow` runtime hooks. Merge it into your host's user-level hook config (e.g. `~/.claude/settings.json`); the installer does this automatically for Claude.
+
+| Event | Hook | Purpose |
+|---|---|---|
+| `SessionStart` | namespace pin | Pins the workspace namespace to `workflow` (so `.workflow/` resolves). |
+| `PreToolUse` (Edit/Write) | `hook branch-check` | Verifies the expected work branch before any file edit (git-safe invariant). |
+| `PreToolUse` (`execute_sql`) | `hook sql-mutation-guard` | Blocks DML/DDL over MCP — reads only (DB scripts-only invariant). |
+| `PreToolUse` (Bash) | `hook git-commit-advisor` | Advises on commit policy (propose-then-execute, no `push`/`--amend`/`--no-verify`). |
+| `SessionEnd` | `auto-compact-on-close` | Persists pending state on close. |
+| `PreCompact` | `checkpoint-write` | Writes `CHECKPOINT.md` before the host compacts. |
+| `PostCompact` | `resume-summary` | Recovers the active loop state after a compact. |
+
+> These hooks enforce invariants 4 (DB scripts-only) and 5 (git-safe) at the host level, independent of the loop logic. The hook commands are runtime CLI subcommands (`agent-workflow hook …`), unchanged across the bundle namespace.

package/skills/{agent-workflow → w}/hooks/hooks.template.json

@@ -63,7 +63,7 @@
           {
             "type": "command",
             "command": "agent-workflow checkpoint-write",
-            "statusMessage": "Escribiendo CHECKPOINT.md antes de compactar... (tip: `/agent-workflow:compact` sintetiza el resumen con contexto vivo)",
+            "statusMessage": "Escribiendo CHECKPOINT.md antes de compactar...",
             "timeout": 10
           }
         ]
@@ -81,7 +81,7 @@
           },
           {
             "type": "prompt",
-            "prompt": "Contexto compactado. El JSON anterior es output de `agent-workflow resume-summary`. Si hay `active_sessions`, invocá `/agent-workflow:resume` para sintetizar CHECKPOINT.md y presentar resumen. Si está vacío, terminá."
+            "prompt": "Contexto compactado. El JSON anterior es output de `agent-workflow resume-summary`. Si hay `active_sessions`, reanudá el loop activo desde su CHECKPOINT.md y presentá un resumen. Si está vacío, terminá."
           }
         ]
       }

package/skills/w/loops/README.md

@@ -0,0 +1,118 @@
+# w/loops — Loop map (Layer 2)
+
+> Los **loops** son las piezas que la **IA corre enteras** para producir entregables y orquestar el trabajo. Los arranca un comando `/w:…` (Capa 1) y, a partir de ahí, **los conduce la IA**, no el usuario.
+>
+> Hermanos: `../commands/` (Capa 1, comandos `/w:…`) · `.workflow/sessions/` (Capa 3, sessions + artefactos internos) · la familia `export-*` (única vía artefacto→`docs/`) · las **capacidades** componibles (roles bindeados en `.workflow/skills.toml`).
+
+---
+
+## What a loop is
+
+Un loop es una **skill** que le enseña a la IA *cómo iterar* hasta producir un entregable. Se invoca por su `name:` con el tool `Skill`. La IA lo ejecuta de punta a punta: detecta huecos, los resuelve (preguntando al humano o investigando), integra y repite hasta converger.
+
+Propiedades comunes a **los 4 loops**:
+
+1. **Gap-driven convergente** — cada ciclo: `detect_gaps` → resolver (humano o research) → integrar → repetir hasta que no queden gaps materiales. Los gaps "agotados" (límite `MAX` de intentos) no se re-disparan → garantiza convergencia.
+2. **Puede crear sessions internas** — si refinar/planificar/ejecutar requiere trabajo profundo (ej. investigar el código), el loop crea una session en `.workflow/sessions/` que maneja **sus** artefactos, la cierra y reporta de vuelta. **El usuario nunca crea esas sessions.**
+3. **AskUserQuestion con dos tipos de tab** (límite host: 4 preguntas/llamada):
+   - **tab(s) de contenido** (≤3) — la(s) pregunta(s) real(es) del momento (resolver una duda, elegir MCP, o en convergencia: `Guardar` / `Preguntar algo más`).
+   - **tab `flow`** (1, SIEMPRE presente) — control de ciclo de vida por un canal lateral. Así el contenido lo maneja la IA y el ciclo de vida lo dirige el humano.
+4. **Escribe solo en su propia carpeta `docs/`** — y **nunca** gradúa/exporta otros artefactos a `docs/`. Esa promoción la hacen las skills `export-*`, aparte y explícita.
+
+## flow tab — options
+
+El tab `flow` es **fijo**: `Compactar` / `Cerrar`, presente en los 4 loops. Responder el tab de contenido **sin tocar `flow`** = seguir iterando ("continuar" es el comportamiento por defecto del loop, no una opción del canal de control).
+
+| Option | What it does |
+|---|---|
+| `Compactar` | Escribe `CHECKPOINT` (session dueña del run) + dispara `/compact` del host y reanuda sin perder el hilo. |
+| `Cerrar` | `finalize`: persiste lo pendiente (`CHECKPOINT` + `BACKLOG`), cierra sessions internas y termina el loop. |
+
+## Loops and their flow
+
+| Loop (`name:`) | Flow | Started by | Reads | Writes |
+|---|---|---|---|---|
+| [`spec-refine-loop`](spec-refine-loop/SKILL.md) | SPEC | `/w:spec-refine` | `docs/specs/NNN-spec.md` (o `…-spec-refined.md` si ya existe) | `docs/specs/NNN-spec-refined.md` |
+| [`plan-new-loop`](plan-new-loop/SKILL.md) | PLANIFICATION | `/w:plan-new` | `docs/specs/NNN-spec-refined.md` | `docs/plans/PPP-plan.md` |
+| [`plan-exec-loop`](plan-exec-loop/SKILL.md) | PLANIFICATION | `/w:plan-exec` | `docs/plans/PPP-plan.md` | `docs/plans/PPP-plan.md` (update) + `docs/tools`; resto vía `export-*` |
+| [`quick-loop`](quick-loop/SKILL.md) | QUICK | `/w:quick` | — (prompt) | edita código + session ligera; **no** `docs/` |
+
+> `/w:spec-new` no tiene loop (es single-pass). Por eso hay **5 comandos / 4 loops**.
+
+### `docs/` boundary (regla dura)
+
+Los loops **nunca** graduan/exportan artefactos a `docs/` automáticamente. Cada loop escribe **solo** su(s) carpeta(s):
+
+| Flow | Carpetas `docs/` que escribe |
+|---|---|
+| SPEC | `docs/specs` |
+| PLANIFICATION | `docs/plans` (living) + `docs/tools` (herramientas creadas — salida directa) |
+| QUICK | ninguna |
+
+Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, diagramas → `docs/diagrams`, informes → `docs/reports`) queda como **artefacto de session** hasta que un `export-*` lo promueva, como paso aparte y explícito.
+
+## Loops × flow tab
+
+| Loop | tab(s) de contenido típicos | tab `flow` |
+|---|---|---|
+| `spec-refine-loop` | dudas-de-humano · elección de MCP · convergencia (`Guardar especificación refinada` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
+| `plan-new-loop` | dudas · elección de MCP · convergencia (`Guardar plan` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
+| `plan-exec-loop` | decisiones/dudas no obvias · elección de MCP · cierre (`Marcar plan done` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
+| `quick-loop` | dudas no obvias · escalar a SPEC/PLAN · cierre (`Cerrar tarea` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
+
+## Schema of each loop file
+
+| Field | Description |
+|---|---|
+| `## Flow` | A qué flujo pertenece (SPEC · PLANIFICATION · QUICK) |
+| `## Layer` | Siempre 2 (la IA lo corre entero) |
+| `## Started by` | Comando `/w:…` que lo arranca (reanudable) |
+| `## Reads` | Documento(s) de entrada |
+| `## Writes` | Documento(s) de salida (`generate` / `read-update`) |
+| `## Internal sessions` | Sessions que crea y sus artefactos |
+| `## Sequence` | Pseudocódigo + mermaid del loop |
+| `## Convergence / exit` | Cuándo para |
+
+El **chasis** (`spec-refine-loop`) además detalla `## Composes` (capacidades que compone), `## Deliverable schema`, `## Gap taxonomy`, `## Ask-vs-research rule`, `## Research: autonomy, scope & failure`, `## AskUserQuestion`, `## Compact / resume`, `## Integration`.
+
+Los **heirs** (`plan-new-loop`, `plan-exec-loop`, `quick-loop`) usan `## Inherits` (lo que reusan del chasis, sin repetirlo) + `## Delta N` (sus diferencias).
+
+## Chassis / heirs
+
+```
+spec-refine-loop  ── CHASIS (patrón de referencia: motor gap-driven, sessions,
+        │            AskUserQuestion + tab flow, research autónomo + regla BD,
+        │            compact/resume, Cerrar persiste CHECKPOINT+BACKLOG)
+        ├── plan-new-loop   (heir)  → deltas: plan rico, gap taxonomy de plan
+        ├── plan-exec-loop  (heir)  → deltas: ejecución real (código/BD/git),
+        │                              session por fase, sin auto-export
+        └── quick-loop      (heir)  → deltas: ceremonia mínima, 1 session,
+                                       hereda git/BD/no-export de plan-exec
+```
+
+El chasis **no es una capacidad bindeable**: *es* `spec-refine-loop` y los demás loops lo heredan. Lo enchufable son las **capacidades** que un loop compone (ej. `ui-design`, `sql`, `git`, `testing`), resueltas por `.workflow/skills.toml`.
+
+## Composed capabilities (roles)
+
+Los loops componen **capacidades por su rol**, no skills concretas; la skill que cumple el rol la resuelve `.workflow/skills.toml` (`built-in default → ~/.workflow/skills.toml → .workflow/skills.toml`).
+
+| Role | Default built-in | Composed by |
+|---|---|---|
+| `ui-design` | `ui-spec` | `spec-refine-loop` (cuando hay UI) |
+| `sql` | `sql` | research · `plan-exec-loop` · `quick-loop` |
+| `git` | `git` | `plan-exec-loop` · `quick-loop` |
+| `coding-standards` | `coding-standards` | `plan-exec-loop` · `quick-loop` |
+| `writing` | `writing` | todos los loops |
+| `research` | `research` | todos los loops (research on-demand) |
+| `testing` | `testing` | `plan-exec-loop` · `quick-loop` |
+| `tools` | `tools` | `plan-exec-loop` |
+| `overview` | `workflow` | cualquiera (orientación) |
+
+`off` en config → capacidad desactivada: el loop sigue sin ella; si era necesaria, lo dice o pregunta al humano.
+
+## Index
+
+- [`spec-refine-loop/SKILL.md`](spec-refine-loop/SKILL.md) — el chasis
+- [`plan-new-loop/SKILL.md`](plan-new-loop/SKILL.md)
+- [`plan-exec-loop/SKILL.md`](plan-exec-loop/SKILL.md)
+- [`quick-loop/SKILL.md`](quick-loop/SKILL.md)