@tacuchi/agent-workflow-cli 11.0.1 → 12.2.0

package/skills/w/commands/spec-new.md

@@ -0,0 +1,63 @@
+---
+description: Genera un borrador de especificación (docs/specs/NNN-spec.md) a partir de un prompt, en una sola pasada. Paso 1 del flujo SPEC; no arranca loop.
+argument-hint: <prompt con el requerimiento o idea>
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+  ]
+---
+
+# spec-new — borrador de especificación (single-pass)
+
+Genera `docs/specs/NNN-spec.md` en una sola pasada a partir del prompt en `$ARGUMENTS`. No arranca loop.
+
+1. Ejecutar `aw next-number docs/specs` para obtener `NNN`.
+2. Crear `docs/specs/NNN-spec.md` con el esquema de borrador (ver abajo).
+3. Mostrar el archivo generado y el próximo paso sugerido (`/w:spec-refine docs/specs/NNN-spec.md`).
+
+## Esquema del borrador (`NNN-spec.md`)
+
+```markdown
+# Spec NNN — <slug>
+
+## Origin            (opt.)
+Prompt original / doc previo / referencia que originó el spec.
+
+## Requirement
+El qué se necesita + por qué (breve). En lenguaje del usuario.
+
+## Context           (opt.)
+Sistemas / componentes / fuentes involucradas. Restricciones conocidas.
+
+## Scope
+- In:  qué entra
+- Out: qué NO entra
+
+## Acceptance criteria
+- [ ] criterio verificable 1
+- [ ] criterio verificable 2
+
+## Open questions
+Dudas pendientes. ← el spec-refine-loop las va cerrando.
+
+## Assumptions       (opt.)
+Supuestos asumidos.
+```
+
+**Notas de llenado:**
+- Sin campo `Type` — `plan-new` infiere el cómo.
+- `Scope` siempre lleva `Out` (qué queda fuera).
+- Los criterios de aceptación deben ser verificables (testeables).
+- Si hay UI involucrada, mencionarlo en `Requirement`/`Context`; el spec UI se autora en `spec-refine` (via capacidad `ui-design`).
+- Alternativa equivalente: el usuario crea el borrador a mano. Ambos caminos producen el mismo `docs/specs/NNN-spec.md`.
+
+## Plan mode
+
+Resuelve `NNN` leyendo `docs/specs/`, describe el borrador que generaría sin escribir el archivo.
+
+## Resources
+
+- Design reference: `docs/referencias/workflow-commands/spec-new.md`
+- Loop que refina este borrador: `../loops/spec-refine-loop/SKILL.md`

package/skills/w/commands/spec-refine.md

@@ -0,0 +1,41 @@
+---
+description: Inicia o retoma el loop de refinamiento de una especificación (spec-refine-loop). Input: docs/specs/NNN-spec.md (borrador). Output: docs/specs/NNN-spec-refined.md.
+argument-hint: <docs/specs/NNN-spec.md>
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "Skill",
+  ]
+---
+
+# spec-refine — trampolín al loop de refinamiento
+
+Este comando no refina el spec él mismo: delega al loop `spec-refine-loop` (Layer 2), que es quien itera, cierra gaps y produce el spec refinado.
+
+Invocar el skill:
+
+```
+Skill: spec-refine-loop
+args: $ARGUMENTS
+```
+
+## Resolución de estado (resumable)
+
+El skill detecta el estado previo antes de arrancar:
+
+1. Busca la sesión de refinamiento del spec en `.workflow/sessions/` y su `CHECKPOINT.md`.
+2. **En curso** (existe CHECKPOINT) → continúa desde el avance previo (gaps resueltos, Q&A).
+3. **Sin avance** (sin CHECKPOINT ni refined) → arranca desde cero leyendo `NNN-spec.md`.
+4. **Ya completado** (existe `NNN-spec-refined.md`, sin CHECKPOINT abierto) → re-refinamiento incremental: lee el **refined** como input (NO el borrador stale); al `Guardar`, sobrescribe con confirmación.
+
+## Plan mode
+
+El skill resuelve el estado y describe las acciones que ejecutaría el loop (gaps que cerraría, preguntas que haría), sin arrancar la iteración.
+
+## Resources
+
+- Loop skill: `../loops/spec-refine-loop/SKILL.md`
+- Design reference: `docs/referencias/workflow-commands/spec-refine.md`

package/skills/w/commands/workspace-init.md

@@ -0,0 +1,39 @@
+---
+description: Convierte la carpeta actual en un workspace de agent-workflow (scaffolding .workflow/ + docs/ + WORKSPACE block + skills.toml). Reemplaza hub-init + project-init — sin distinción project/hub. Correr una vez antes de cualquier flujo; idempotente.
+argument-hint: --source alias:path[:rama] [--proyecto <nombre>] [--main-branch <rama>] [--dry-run]
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+  ]
+---
+
+# workspace-init — bootstrap del workspace
+
+Corre `aw workspace-init` para convertir la carpeta actual en un workspace de agent-workflow. Un workspace tiene **1+ fuentes** (repos); "standalone" = una sola fuente. No hay modos project/hub — el modelo es unificado.
+
+```bash
+aw workspace-init --source alias:path[:rama] [--proyecto <nombre>] [--main-branch <rama>] [--dry-run]
+```
+
+## Pasos interactivos
+
+1. **Detectar/confirmar fuentes** — el CLI detecta la/s ruta/s de repo; el usuario confirma aliases, paths y ramas. Se acepta `--source` múltiple.
+2. **Elegir skills por defecto** — se presenta el catálogo de capacidades (roles) disponibles. Para cada rol: `built-in default`, override a skill de tercero (`skills.sh`), o `off`. Resultado escrito en `.workflow/skills.toml`. La cascada de config es: `built-in → ~/.workflow/skills.toml (global) → .workflow/skills.toml (workspace)`.
+3. **Escribir scaffolding** — crea `.workflow/sessions/`, `docs/` con su taxonomía completa (`specs/`, `plans/`, `tools/`, `scripts/`, `manuals/`, `diagrams/`, `reports/`), el bloque `WORKSPACE` en `CLAUDE.md`/`AGENTS.md` (fuentes + metadatos), y `.workflow/skills.toml`.
+4. **Multi-fuente** — si hay ≥2 fuentes, configura visibilidad multi-root (settings.local.json + config, gitignored) y reconcilia fuentes.
+
+Al terminar, el usuario puede correr `/w:spec-new`, `/w:plan-new` o `/w:quick` directamente.
+
+**Idempotente**: re-ejecutar reconcilia (no duplica entradas ni sobrescribe configuración manual).
+
+## Plan mode
+
+Resuelve las fuentes y describe el scaffolding que crearía, sin escribir archivos. Muestra qué crearía en `.workflow/` y `docs/`, y qué escribiría en `CLAUDE.md`.
+
+## Resources
+
+- Design reference: `docs/referencias/workflow-commands/workspace-init.md` (design spec)
+- Skills config: `docs/referencias/workflow-skills/` (capacidades disponibles y cascada)

package/skills/w/exports/README.md

@@ -0,0 +1,88 @@
+# exports — `export-*` family (Layer 1)
+
+> This is the **bundle README** for the `export-*` family: the **only** path that promotes session artifacts to permanent `docs/` documents. Each export is invoked by the **user** (never by a loop) as a separate, explicit step.
+> Related layers: [`../commands/`](../commands/) (Layer 1 flows) · [`../loops/`](../loops/) (Layer 2, AI-driven) · artifacts live in `.workflow/sessions/` (Layer 3). Design reference: `docs/referencias/workflow-exports/`.
+>
+> **Namespace:** invoked via the Skill tool by `name:` — `export-scripts`, `export-manuals`, `export-diagrams`, `export-reports`. The thin `/w:export-*` slash commands that route here are authored separately under [`../commands/`](../commands/).
+
+---
+
+## Principle (boundary) — hard rule
+
+**Loops NEVER graduate/export to `docs/` automatically.** A loop produces **artifacts** under `.workflow/sessions/` and writes only the `docs/` folder owned by its own flow (SPEC→`specs`; PLAN→`plans`+`tools`). Promoting the **rest** of the artifacts into documents is done **only** by these `export-*` skills, as a **separate and explicit** step that the **user** invokes — the execution loops never trigger it.
+
+```
+.workflow/sessions/<NNN-…>/           docs/  (permanent, user-facing)
+  SCRIPTS.sql  ──── export-scripts ──►  scripts/
+  DECISION · plan-doc ── export-manuals ──►  manuals/
+  source code · plan-doc ── export-diagrams ──►  diagrams/
+  spec · CONCLUSIONS · DECISION ── export-reports ──►  reports/
+        (read-only, single-pass, cross-session, user-invoked)
+```
+
+## One export per derived `docs/` category (4)
+
+| Export | Composes | Reads (artifacts / sessions + corpus) | Writes (its ONLY category) |
+|---|---|---|---|
+| [`export-scripts`](export-scripts/SKILL.md) | `sql` | type-B `SCRIPTS.sql` (DDL/DML migrations) across N sessions + standalone `docs/scripts/*.sql` | `docs/scripts/NNN-export-scripts-<date>/` (numbered forwards + `00-ROLLBACK.sql`) |
+| [`export-manuals`](export-manuals/SKILL.md) | `writing` | sessions + `DECISION` + plan-doc (`Solution`, `Final behavior`, `Validations`) + touched code | `docs/manuals/` |
+| [`export-diagrams`](export-diagrams/SKILL.md) | `diagrams` | source code of the sources + plan-doc (`AS-IS` / `TO-BE`, `Impacted`) | `docs/diagrams/` (C4 / mermaid) |
+| [`export-reports`](export-reports/SKILL.md) | `writing` | corpus of sessions (spec, `CONCLUSIONS`, `DECISION`) + plan-doc state + `docs/` | `docs/reports/` (executive / functional report) |
+
+> **Composition over ownership:** an export does **not** own its authoring logic — it **composes a capability role** from [`../../`workflow-skills](../../) (resolved through `.workflow/skills.toml`): `export-scripts` composes `sql`; `export-manuals` and `export-reports` compose `writing`; `export-diagrams` composes `diagrams`. Swapping the implementation is a one-line config change; it never touches the export.
+
+## Common properties
+
+1. **Layer 1, explicit** — the **user** invokes them (`/w:export-<cat>`). **Never** automatic (no loop fires them).
+2. **Single-pass, read-only over sessions** — they read artifacts/sessions and `docs/`, **synthesize**, and write **only** their own `docs/<category>/` folder. They do **not** mutate sessions and do **not** open/close loops.
+3. **Cross-session** — they consolidate **N** sessions + the `docs/` corpus (dedup, roadmap, continuous numbering).
+4. **No loop, no internal sessions** — options come from **args** (no lifecycle `AskUserQuestion`).
+5. **Git-safe** — they **never** commit, merge, push, `--amend`, or `--no-verify`. The output is a written document the user reviews and commits when ready.
+6. **DB scripts-only** — `export-scripts` ships migration SCRIPTS as a bundle; it **never executes** DDL/DML (a human/DBA applies them).
+
+## Section schema of each `export-*/SKILL.md`
+
+Mirrors `docs/referencias/workflow-exports/` and the old export SKILLs. Frontmatter: `name:` (kebab — exactly `export-scripts` / `export-manuals` / `export-diagrams` / `export-reports`) + rich `description:` (what + when, drives selection). Body:
+
+| Section | Purpose |
+|---|---|
+| `## Category` | Destination `docs/` folder (its ONLY category) |
+| `## Composes` | The capability role it loads (resolved via `skills.toml`) |
+| `## When to use` | Discovery triggers + scenarios |
+| `## What it does` | Step list (the synthesis) |
+| `## What it does NOT do` | Hard exclusions (no commit, no execute, single category) |
+| `## Read-only sandbox` | Plan-mode behavior (describe, don't write) |
+| `## Inputs` | `aw` reads + filesystem reads + args |
+| `## Flow` | Step-by-step (resolve context → collect → synthesize → number → write → report) |
+| `## Output location` | The exact path/shape it writes |
+| `## Re-run` | Idempotence (next NNN; never overwrites) |
+| `## Resources` | Design references + sibling exports |
+
+## Runtime CLI (`agent-workflow`, alias `aw`)
+
+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 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.
+
+## 6 Hard invariants (never violate)
+
+1. **No auto-export**: only `export-*` promotes to `docs/`, always explicit/user-invoked.
+2. **Each export writes ONLY its one `docs/` category** (scripts / manuals / diagrams / reports).
+3. **Spec and plan are documents** (written by SPEC/PLAN flows directly) — they are **not** exported.
+4. **DB scripts-only**: `export-scripts` ships SCRIPTS.sql migrations, **never executes** them.
+5. **Git-safe**: exports are read-only/report — **never** commit/push.
+6. **Cross-session synthesis**: exports consolidate N sessions, not a single one.
+
+## Index
+
+| Export | File | Category | Composes |
+|---|---|---|---|
+| `export-scripts` | [`export-scripts/SKILL.md`](export-scripts/SKILL.md) | `docs/scripts` | `sql` |
+| `export-manuals` | [`export-manuals/SKILL.md`](export-manuals/SKILL.md) | `docs/manuals` | `writing` |
+| `export-diagrams` | [`export-diagrams/SKILL.md`](export-diagrams/SKILL.md) | `docs/diagrams` | `diagrams` |
+| `export-reports` | [`export-reports/SKILL.md`](export-reports/SKILL.md) | `docs/reports` | `writing` |

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

@@ -0,0 +1,125 @@
+---
+name: export-diagrams
+description: "Genera diagramas de arquitectura y flujos del workspace en `docs/diagrams/` consolidando el código de las fuentes + el plan-doc (`Current state (AS-IS)` / `Target state (TO-BE)`, `Impacted`) de N sesiones. Produce contexto, contenedores, componentes, integraciones y modelo de datos (si MCP read-only disponible). Default `mermaid` (renderiza en GitHub, link `mermaid.ink` para preview); `c4`/structurizr opt-in vía `--engine`. Output en `docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/` (o `.md`). Read-only/reporte: emite solo el source del diagrama (el render visual lo hace el lector); no commitea ni muta nada; MCP solo lecturas. Compone la capacidad `diagrams`. Úsalo para 'diagrama del sistema', 'C4 del workspace', 'mapa de arquitectura/flujos'. Invocado por el usuario vía `/w:export-diagrams`."
+---
+
+# export-diagrams — Diagramas de arquitectura y flujos desde código + plan-doc
+
+Genera un dossier de diagramas (**arquitectura y flujos**) del workspace, agregando la estructura de las fuentes y el delta de las sesiones. **Read-only / reporte** — emite solo el **source** del diagrama (Mermaid / DSL); el render visual lo hace el lector. No commitea, no muta nada; MCP solo lecturas.
+
+> Familia `export-*` (la única vía artefacto→`docs/`). Recicla el espíritu del viejo `export-arq` (C4, niveles contexto/contenedores/componentes, integraciones, modelo de datos), reubicado a `docs/diagrams` y modernizado: default `mermaid` (en vez de structurizr), sin modos project/hub, y la generación la aporta la capacidad `diagrams` (no una skill propia). Diseño: `docs/referencias/workflow-exports/export-diagrams.md`.
+
+## Category
+
+`docs/diagrams` — **única** carpeta `docs/` que este export escribe.
+
+## Composes
+
+Capacidad **`diagrams`** (built-in default `diagrams`), resuelta vía `.workflow/skills.toml`. Aporta el motor de render (Mermaid C4 nativo / Structurizr DSL), los niveles C1–C4 y la convención del link de preview. Este export **no** posee esa lógica: la compone. Rebindeable u `off` por config.
+
+## When to use
+
+- "Diagrama del sistema", "C4 del workspace", "mapa de arquitectura".
+- "Diagrama de flujo" entre componentes / integraciones tocadas.
+- Onboarding técnico; antes de cambios estructurales (validar arquitectura vigente); auditoría técnica.
+
+## What it does
+
+1. Inspecciona el código de las fuentes del workspace (estructura, wiring, integraciones, tecnologías).
+2. Lee de las sesiones el plan-doc: `Current state (AS-IS)` / `Target state (TO-BE)` y `Impacted` (qué cambió y dónde).
+3. (Opcional) Si MCP read-only está disponible y se pide modelo de datos: consulta esquemas BD (solo lectura).
+4. Resuelve el motor (`--engine`) y consolida la arquitectura/flujos tocados por las N sesiones.
+5. Renderiza los diagramas (compone `diagrams`): contexto, contenedores, componentes, integraciones, modelo de datos (si aplica).
+6. Escribe el dossier en `docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/` con un `README.md` (índice + cómo leer).
+
+## What it does NOT do
+
+- Ejecutar commits, merges, push, ni SQL.
+- Mutar sesiones, el plan-doc ni el código (solo lectura). MCP **solo** lecturas read-only (nunca DML/DDL).
+- Escribir cualquier carpeta `docs/` que no sea `docs/diagrams/` (invariante: una categoría).
+- **Renderizar visualmente** el diagrama: emite solo el source (Mermaid / DSL); el render lo hace el lector con sus herramientas (o el link `mermaid.ink`).
+- Validar que las integraciones funcionen (eso es del doctor) ni inventar componentes ausentes.
+- Sobrescribir dossiers previos (siempre next-number).
+
+## Read-only sandbox
+
+En plan mode **describe**, no escribe: el motor resuelto, los niveles/secciones que aparecerían (resueltos por args), las fuentes a inspeccionar + integraciones detectadas, y — si se pide modelo de datos — las queries MCP propuestas con su costo estimado. **No** ejecuta `Write`, ni mutaciones MCP, 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 (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 next-number docs/diagrams` — numeración determinística (la resolución de la carpeta destino la maneja el CLI).
+
+**Filesystem / código**:
+
+- Código de las fuentes declaradas (estructura, wiring, manifests de tecnología).
+- `docs/diagrams/` existentes (para complementar / no colisionar).
+
+**MCP read-only** (opcional, solo si se pide modelo de datos y está configurado): `\d <tabla>`, `SELECT count(*)`, relaciones FK para el `erDiagram`. Con cost guard.
+
+**Args** (sin lifecycle `AskUserQuestion`):
+
+```
+/w:export-diagrams [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]
+                   [--engine mermaid|c4] [--scope c4|integrations|data|todo] [--dry-run]
+```
+
+| 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) |
+| `--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) |
+| `--dry-run` | Reporte propositivo sin escribir archivos |
+
+Sin args: `--engine mermaid --scope todo`. El **snapshot** del sistema es siempre el último estado conocido; `--since`/`--sessions` modulan el énfasis del delta (qué se tocó), no el snapshot base. *(Si algún flag exacto difiere en el CLI runtime, ajustar al contrato real de `aw`.)*
+
+## 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 las fuentes
+
+Por cada fuente: estructura básica, componentes internos (módulos, servicios, comandos, hooks, MCP configurado), tecnologías por manifest (`package.json`, `pom.xml`, …), integraciones externas.
+
+### 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.
+
+### Paso 4 — Inspeccionar MCP (opcional)
+
+Si `--scope` incluye `data` y hay MCP read-only: `\d <tabla>`, `count(*)`, relaciones FK (con cost guard). Si no disponible → omitir la sección "Modelo de datos" con nota inline.
+
+### Paso 5 — Renderizar (compone `diagrams`)
+
+Según `--engine`: `mermaid` → bloques Mermaid C4 nativos (`C4Context`/`C4Container`/`C4Component`) y `flowchart` para flujos; `c4` → `workspace.dsl` Structurizr aparte + Mermaid auxiliar embebido para lectura offline. Por cada bloque ```` ```mermaid ````, agregar inmediatamente después del fence de cierre un blockquote con el link de preview: `> Ver diagrama renderizado: <https://mermaid.ink/img/BASE64>` (base64 URL-safe del código plano). No aplica a `workspace.dsl`.
+
+### Paso 6 — Escribir o reportar
+
+Si `--dry-run`: imprimir el reporte; no escribir. Si no: `aw next-number docs/diagrams` + escribir el dossier. **NUNCA commitear**. Resumen al usuario: motor, secciones presentes/omitidas (p.ej. Datos omitido si no MCP) y ruta.
+
+## Output location
+
+```
+docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/
+├── README.md          # índice + cómo leer + counts
+├── diagrams.md        # documento principal con Mermaid embebido (+ links mermaid.ink)
+└── workspace.dsl      # solo con --engine c4 (Structurizr)
+```
+
+## Re-run
+
+Idempotente funcional: cada invocación toma el siguiente `NNN`; no sobrescribe dossiers previos. Para regenerar: borrar el directorio y re-invocar.
+
+## Resources
+
+- Design: `docs/referencias/workflow-exports/export-diagrams.md` · familia: [`../README.md`](../README.md).
+- Capacidad compuesta: `diagrams` (built-in default; ver `docs/referencias/workflow-skills/`).
+- Insumo: plan-doc `AS-IS`/`TO-BE`/`Impacted` (ver `docs/plans`).
+- Siblings: [`../export-scripts/SKILL.md`](../export-scripts/SKILL.md) · [`../export-manuals/SKILL.md`](../export-manuals/SKILL.md) · [`../export-reports/SKILL.md`](../export-reports/SKILL.md).

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).