@tacuchi/agent-workflow-cli 11.0.1 → 12.0.0

package/skills/w/commands/export-manuals.md

@@ -0,0 +1,35 @@
+---
+description: Genera manuales de usuario/operación en docs/manuals/ consolidando sesiones, DECISION, plan-doc y código fuente. Single-pass, explícito.
+argument-hint: [--sessions <ids>] [--audiencia <usuario|operacion>] [--dry-run]
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Skill",
+  ]
+---
+
+# export-manuals — exportar manuales
+
+Consolida sesiones + artefactos `DECISION` + plan-doc (`Final behavior`) + código fuente y genera documentación de usuario/operación en `docs/manuals/`. Single-pass, read-only sobre sesiones. Invoca el skill `export-manuals`.
+
+```
+Skill: export-manuals
+args: $ARGUMENTS
+```
+
+## Qué produce
+
+- `docs/manuals/`: manuales consolidados, cross-session, dedup.
+- **No** muta sesiones ni abre/cierra loops.
+- Solo escribe en `docs/manuals/`.
+
+## Plan mode
+
+Describe el alcance de los manuales que generaría (secciones, sesiones fuente) sin escribir archivos.
+
+## Resources
+
+- Export skill: `../exports/export-manuals/SKILL.md`
+- Design reference: `docs/referencias/workflow-exports/README.md`

package/skills/w/commands/export-reports.md

@@ -0,0 +1,35 @@
+---
+description: Genera un informe ejecutivo/funcional en docs/reports/ consolidando el corpus de sesiones (spec, CONCLUSIONS, DECISION), el plan-doc y el estado de docs/. Single-pass, explícito.
+argument-hint: [--sesiones <ids>] [--tipo <ejecutivo|funcional>] [--dry-run]
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Skill",
+  ]
+---
+
+# export-reports — exportar informes
+
+Consolida el corpus completo de sesiones (`CONCLUSIONS`, `DECISION`, spec) + plan-doc (estado) + `docs/` y genera un informe ejecutivo o funcional en `docs/reports/`. Single-pass, read-only sobre sesiones. Invoca el skill `export-reports`.
+
+```
+Skill: export-reports
+args: $ARGUMENTS
+```
+
+## Qué produce
+
+- `docs/reports/`: informe consolidado, cross-session, con dedup y estado de avance.
+- **No** muta sesiones ni abre/cierra loops.
+- Solo escribe en `docs/reports/`.
+
+## Plan mode
+
+Describe el alcance e índice del informe que generaría (secciones, sesiones fuente, estado de avance) sin escribir archivos.
+
+## Resources
+
+- Export skill: `../exports/export-reports/SKILL.md`
+- Design reference: `docs/referencias/workflow-exports/README.md`

package/skills/w/commands/export-scripts.md

@@ -0,0 +1,35 @@
+---
+description: Exporta scripts de BD (SCRIPTS.sql tipo-B) de N sesiones a docs/scripts/ como forwards numerados + rollback. Paso explícito y aparte — nunca automático.
+argument-hint: [--sessions <ids>] [--dry-run]
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Skill",
+  ]
+---
+
+# export-scripts — exportar scripts de BD
+
+Promueve los artefactos `SCRIPTS.sql` (tipo B — migraciones) de N sesiones de `.workflow/sessions/` a `docs/scripts/`. Single-pass, read-only sobre sesiones. Invoca el skill `export-scripts`.
+
+```
+Skill: export-scripts
+args: $ARGUMENTS
+```
+
+## Qué produce
+
+- `docs/scripts/`: forwards numerados de forma continua (cross-session, dedup) + `00-ROLLBACK.sql`.
+- **No** muta sesiones ni abre/cierra loops.
+- La IA **nunca ejecuta** los scripts — solo los consolida y entrega.
+
+## Plan mode
+
+Describe los scripts que consolidaría y la estructura de `docs/scripts/` que generaría, sin escribir archivos.
+
+## Resources
+
+- Export skill: `../exports/export-scripts/SKILL.md`
+- Design reference: `docs/referencias/workflow-exports/README.md`

package/skills/w/commands/plan-exec.md

@@ -0,0 +1,46 @@
+---
+description: Inicia o retoma el loop de ejecución (plan-exec-loop) sobre un plan existente. Aquí ocurre el trabajo real: edición de código, scripts SQL propuestos, herramientas creadas. Git-safe.
+argument-hint: <docs/plans/PPP-plan.md>
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "Skill",
+  ]
+---
+
+# plan-exec — trampolín al loop de ejecución
+
+Arranca o retoma `plan-exec-loop` (Layer 2), que ejecuta el trabajo real fase por fase. El plan (`docs/plans/PPP-plan.md`) es un documento vivo que el loop mantiene actualizado (estado de fases y tareas).
+
+Invocar el skill:
+
+```
+Skill: plan-exec-loop
+args: $ARGUMENTS
+```
+
+## Qué hace el loop (resumen)
+
+- Lee y actualiza `docs/plans/PPP-plan.md` (living doc: estado de fases/tareas).
+- Edita código en las fuentes del workspace (una sesión por fase).
+- Escribe herramientas/utilidades reutilizables en `docs/tools/`.
+- Propone commits por fuente (git-safe: verifica rama, propone, nunca push/--amend/--no-verify).
+- Genera artefactos de sesión (`DECISION`, `SCRIPTS.sql`) en `.workflow/sessions/`.
+- **No exporta** a `docs/scripts`, `docs/manuals`, `docs/diagrams`, `docs/reports` — eso lo hacen los `export-*` como paso aparte.
+- Scripts de BD (migraciones) van a `SCRIPTS.sql` tipo B; la IA **nunca ejecuta DML/DDL**, solo lecturas read-only vía MCP.
+
+## Resumable
+
+Mismo patrón que los demás loops: detecta CHECKPOINT existente y continúa desde ahí.
+
+## Plan mode
+
+El skill describe fase por fase lo que ejecutaría, qué archivos tocaría, y qué commits propondría, sin aplicar cambios.
+
+## Resources
+
+- Loop skill: `../loops/plan-exec-loop/SKILL.md`
+- Design reference: `docs/referencias/workflow-commands/plan-exec.md`

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

@@ -0,0 +1,44 @@
+---
+description: Inicia o retoma el loop de planificación (plan-new-loop) a partir de un spec refinado. Convierte el "qué" (spec) en el "cómo" (plan). Input ideal: docs/specs/NNN-spec-refined.md.
+argument-hint: <docs/specs/NNN-spec-refined.md | docs/specs/NNN-spec.md | prompt>
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "Skill",
+  ]
+---
+
+# plan-new — trampolín al loop de planificación
+
+Puente SPEC → PLANIFICATION. Convierte el "qué" (spec refinado) en el "cómo" (plan). Delega a `plan-new-loop` (Layer 2).
+
+## Resolución de input
+
+El skill evalúa `$ARGUMENTS`:
+
+1. **`docs/specs/NNN-spec-refined.md`** → ideal. Procede directamente a `plan-new-loop`.
+2. **`docs/specs/NNN-spec.md`** (borrador sin refinar) → propone correr `/w:spec-refine` primero; planificar sobre un spec sólido produce mejores planes.
+3. **prompt** (sin spec referenciado) → propone usar el flujo SPEC; **por default lanza `/w:spec-new`** con ese prompt para crear el borrador, y desde ahí continúa el flujo natural.
+
+Invocar el skill:
+
+```
+Skill: plan-new-loop
+args: $ARGUMENTS
+```
+
+## Notas de numeración
+
+El plan toma su propio número `PPP` en `docs/plans/`. **No hereda el `NNN` del spec**. El vínculo al spec se establece por referencia (`## Origin` / "Derivado de") en el plan, no por número.
+
+## Plan mode
+
+El skill resuelve el input según las 3 reglas de arriba y describe las acciones del loop que ejecutaría, sin arrancar la iteración.
+
+## Resources
+
+- Loop skill: `../loops/plan-new-loop/SKILL.md`
+- Design reference: `docs/referencias/workflow-commands/plan-new.md`

package/skills/w/commands/quick.md

@@ -0,0 +1,39 @@
+---
+description: Atajo liviano para trabajo acotado (fix, ajuste, chore) que no amerita spec ni plan. Inicia quick-loop. No toca docs/. Escala a SPEC/PLAN si la tarea crece.
+argument-hint: <prompt con la tarea acotada>
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "Skill",
+  ]
+---
+
+# quick — trampolín al loop liviano
+
+Para tareas acotadas y directas que no justifican pasar por SPEC ni PLANIFICATION. Siempre crea una sesión ligera (trazabilidad + resume). Delega a `quick-loop` (Layer 2).
+
+Invocar el skill:
+
+```
+Skill: quick-loop
+args: $ARGUMENTS
+```
+
+## Qué hace el loop
+
+- Edita código en las fuentes del workspace.
+- Artefactos mínimos en la sesión (DECISION lazy, commit propuesto).
+- **No toca `docs/`** ni exporta nada.
+- **Escala** a SPEC/PLAN si emerge complejidad (muchos archivos, ≥2 fuentes, necesita arquitectura, o el cambio es feature/refactor).
+
+## Plan mode
+
+El skill describe los cambios que aplicaría y los archivos que tocaría, sin ejecutarlos.
+
+## Resources
+
+- Loop skill: `../loops/quick-loop/SKILL.md`
+- Design reference: `docs/referencias/workflow-commands/quick.md`

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