@tacuchi/agent-workflow-cli 11.0.1 → 12.2.0

package/skills/w/roles/diagrams/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: diagrams
+description: >
+  Autoría de diagramas de arquitectura y sistema: C4 (Context, Container, Component),
+  PlantUML y Structurizr DSL. Compuesta por export-diagrams para producir el contenido
+  de docs/diagrams/. Selecciona el motor de render según el flag --diagrams del export
+  (Structurizr default, Mermaid y PlantUML opt-in). Incluye link mermaid.ink por cada
+  bloque Mermaid para preview sin renderer local.
+---
+
+# diagrams — Diagram authoring capability
+
+## Role
+
+`diagrams` — implementación built-in por defecto. Rebindeable a otra skill (de tercero o `off`) en `.workflow/skills.toml`.
+
+## Purpose
+
+Autorar diagramas de arquitectura con notación C4 (Levels 1-3) usando el motor que el export configure. Produce source renderizable (DSL, PUML, Mermaid) — **no renderiza visualmente**; el render lo hace el lector con sus herramientas. Cubre el estándar C4 formal (Structurizr DSL), el opt-in embebido (Mermaid nativo) y el opt-in exportable (PlantUML).
+
+## Composed by
+
+| Export | Cuándo la compone |
+|---|---|
+| `export-diagrams` | para generar el contenido de `docs/diagrams/NNN-*/` |
+
+Cualquier loop puede componerla también si necesita producir un diagrama inline durante ejecución (raro; el caso primario es `export-diagrams`).
+
+## Knowledge
+
+### Engine matrix
+
+| `--diagrams` flag | Motor | Archivos producidos | Cuándo elegirlo |
+|---|---|---|---|
+| `structurizr` (default) | Structurizr DSL | `workspace.dsl` + Mermaid auxiliar embebido en `.md` | Dossier técnico formal; soporte de tooling externo (structurizr.com, structurizr-lite) |
+| `mermaid` | Mermaid C4 nativo | solo `.md` con bloques Mermaid | Preferir render embebido sin DSL separado; GitHub/GitLab lo renderizan inline |
+| `plantuml` | PlantUML C4-stdlib | `arquitectura.puml` + nota en `.md` | Equipos con pipeline PlantUML instalado |
+
+**Regla canónica**: `export-diagrams` usa Structurizr DSL por defecto (C4 formal, separa modelo de vistas). Mermaid es opt-in cuando se prefiere render embebido.
+
+### C4 model — levels
+
+#### Level 1: Context (C4Context)
+
+El sistema como caja única + actores + sistemas vecinos. Perspectiva de negocio.
+
+```mermaid
+C4Context
+  title Diagrama de Contexto: <PRODUCTO>
+  Person(dev, "Developer", "Miembro del equipo")
+  System(sistema, "<PRODUCTO>", "<descripcion corta>")
+  System_Ext(extA, "<Sistema A>", "<rol>")
+  Rel(dev, sistema, "Usa")
+  Rel(sistema, extA, "<integracion>")
+```
+
+#### Level 2: Container (C4Container)
+
+Aplicaciones, servicios, data stores que componen el sistema. Una fuente declarada en `WORKSPACE` = un contenedor.
+
+```mermaid
+C4Container
+  title Diagrama de Contenedores: <PRODUCTO>
+  Person(dev, "Developer")
+  System_Boundary(sistema, "<PRODUCTO>") {
+    Container(svcA, "<Servicio A>", "<tech>", "<responsabilidad>")
+    Container(svcB, "<Servicio B>", "<tech>", "<responsabilidad>")
+    ContainerDb(db, "Base de datos", "<motor>", "<uso>")
+  }
+  System_Ext(extA, "<Sistema A>")
+  Rel(dev, svcA, "Usa")
+  Rel(svcA, db, "Lee/escribe")
+  Rel(svcA, extA, "<protocolo>")
+```
+
+#### Level 3: Component (C4Component)
+
+Módulos internos relevantes de un contenedor. Solo para contenedores con complejidad interna suficiente. Un diagrama por contenedor; el resto se omite.
+
+```mermaid
+C4Component
+  title Componentes: <Contenedor>
+  Container_Boundary(cont, "<Contenedor>") {
+    Component(compA, "<Componente A>", "<tech>", "<responsabilidad>")
+    Component(compB, "<Componente B>", "<tech>", "<responsabilidad>")
+  }
+  Rel(compA, compB, "<interaccion>")
+```
+
+Si ningún contenedor justifica C4 Component → omitir la sección con nota inline `_(Sin contenedores con complejidad interna suficiente para C4 Component.)_`.
+
+### Structurizr DSL template
+
+```dsl
+workspace "<PRODUCTO>" "<descripcion>" {
+
+  model {
+    // Personas
+    dev = person "Developer" "Miembro del equipo"
+
+    // Sistema bajo análisis
+    sistema = softwareSystem "<PRODUCTO>" "<descripcion>" {
+      svcA = container "<Servicio A>" "<tech>" "<responsabilidad>"
+      svcB = container "<Servicio B>" "<tech>" "<responsabilidad>"
+      db   = container "Base de datos" "<motor>" "<uso>" "Database"
+    }
+
+    // Sistemas externos
+    extA = softwareSystem "<Sistema A>" "<rol>" "External"
+
+    // Relaciones
+    dev   -> sistema "Usa"
+    svcA  -> db      "Lee/escribe"
+    svcA  -> extA    "<protocolo>"
+  }
+
+  views {
+    systemContext sistema "Context" {
+      include *
+      autoLayout
+    }
+
+    container sistema "Container" {
+      include *
+      autoLayout
+    }
+
+    // Una vista por contenedor con C4 Component relevante:
+    component svcA "SvcA-Components" {
+      include *
+      autoLayout
+    }
+
+    theme default
+  }
+}
+```
+
+Render online gratuito: [structurizr.com/dsl](https://structurizr.com/dsl) o structurizr-lite (Docker).
+
+### PlantUML C4-stdlib template
+
+```plantuml
+@startuml arquitectura
+
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
+
+title <PRODUCTO> — Diagrama de Contexto C4
+
+Person(dev, "Developer", "Miembro del equipo")
+System(sistema, "<PRODUCTO>", "<descripcion>")
+System_Ext(extA, "<Sistema A>", "<rol>")
+
+Rel(dev, sistema, "Usa")
+Rel(sistema, extA, "<protocolo>")
+
+SHOW_LEGEND()
+@enduml
+```
+
+Render: [plantuml.com](https://plantuml.com) o `plantuml.jar` local.
+
+### Mermaid auxiliar (bajo Structurizr default)
+
+Cuando `--diagrams structurizr`, el archivo `.md` incluye también un bloque Mermaid derivado del DSL como **fallback offline** (lectores sin acceso a structurizr.com/dsl pueden leerlo directamente):
+
+```
+```mermaid
+C4Context
+  title ...
+```
+
+> Ver diagrama renderizado: <https://mermaid.ink/img/BASE64>
+```
+
+El `BASE64` es el código Mermaid plano codificado en base64 URL-safe (RFC 4648 §5; alfabeto `A-Z a-z 0-9 - _`). **Cada bloque Mermaid lleva su propio link** inmediatamente después del fence de cierre.
+
+### Sequence diagrams (opt-in)
+
+Para flujos críticos de integración (no C4 estructural), un `sequenceDiagram` Mermaid complementa el C4 Container:
+
+```mermaid
+sequenceDiagram
+  participant Dev
+  participant SvcA
+  participant DB
+  Dev->>SvcA: POST /resource
+  SvcA->>DB: INSERT
+  DB-->>SvcA: OK
+  SvcA-->>Dev: 201 Created
+```
+
+Solo si aporta claridad real — no agregar sequence diagrams por defecto.
+
+### Entity-Relationship (modelo de datos)
+
+Cuando `export-diagrams` incluye `--scope datos` y hay MCP configurado:
+
+```mermaid
+erDiagram
+  TABLA_A ||--o{ TABLA_B : "tiene"
+  TABLA_A {
+    int id PK
+    string nombre
+  }
+  TABLA_B {
+    int id PK
+    int a_id FK
+    string detalle
+  }
+```
+
+MCP read-only: `\d <tabla>` + `SELECT count(*)` para magnitud (aplicar cost guard: ver skill `research` o `sql`).
+
+### Output file structure
+
+```
+docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/
+├── README.md            # indice + how-to-read + motores usados
+├── arquitectura.md      # documento principal con C4 + Mermaid auxiliar
+├── workspace.dsl        # solo con --diagrams structurizr (default)
+└── arquitectura.puml    # solo con --diagrams plantuml
+```
+
+### Render rules
+
+1. Sin cota de palabras — completitud > concisión para documentación técnica.
+2. Diagrama principal (al menos C4Context + C4Container) es obligatorio; sin ellos el output no es válido.
+3. C4Component solo si el contenedor lo justifica.
+4. Sequence y erDiagram son opcionales; solo si aportan claridad real.
+5. Cada bloque `mermaid` lleva el link `mermaid.ink` como blockquote inline.
+6. Placeholders `{{PLACEHOLDER}}` siempre reemplazados — nunca dejar marcadores sin rellenar.
+
+## Output
+
+Produce en `docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/`:
+- `README.md`
+- `arquitectura.md` (siempre)
+- `workspace.dsl` (si `--diagrams structurizr`)
+- `arquitectura.puml` (si `--diagrams plantuml`)
+
+Escribe solo `docs/diagrams/` (invariant #1 y #2: solo `export-*` gradua a `docs/`; esta skill la compone `export-diagrams`).
+
+## Source
+
+Reciclado de `agent-workflow/exports/export-arq/` del bundle viejo (v1.3.0). Se conserva: el modelo C4 Levels 1-3, los tres motores (Structurizr default, Mermaid opt-in, PlantUML opt-in), las plantillas DSL y PUML, la regla de link `mermaid.ink` por bloque Mermaid, la estructura de output, el cost guard para MCP. Se descarta: la lógica de lectura de AW-PROJECT legacy, los comandos CLI `agent-workflow next-number`/`history-data`/etc. (son detalles de implementación del CLI, no de la skill), y el scope `--diagrams` como input flag (lo recibe el export que compone esta skill).

package/skills/w/roles/git/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: git
+description: >-
+  Git-safe capability — built-in default for the `git` role. Verifies the expected
+  work branch per source before editing, proposes commits (one per source) and only
+  commits when the user approves, and NEVER runs push, --amend, --no-verify, force,
+  merge/rebase/cherry-pick, tags, or destructive resets without explicit user request.
+  Read-only git (status/log/diff/branch) is always allowed. Use when a loop is about
+  to edit code or when the user asks to commit / save / push changes.
+---
+
+# git — git-safe capability
+
+## Role
+
+`git` — built-in default. Rebindable in `.workflow/skills.toml` (third-party skill or `off`). This skill encodes invariant 5: **git seguro**.
+
+## Purpose
+
+Operar git de forma **segura y controlada**: verificar la rama esperada antes de editar, **proponer** commits por fuente, y nunca ejecutar operaciones destructivas o de publicación sin pedido explícito del usuario.
+
+## Composed by
+
+- **`plan-exec-loop`** — verifica rama antes de cada edit; propone commits al cerrar/checkpoint.
+- **`quick-loop`** — igual, en el atajo liviano.
+
+(Cualquier flujo que edite código o que el usuario quiera commitear lo usa.)
+
+## Knowledge
+
+### Operaciones prohibidas sin solicitud explícita del usuario
+
+Lista cerrada. La IA **nunca** las ejecuta por iniciativa propia:
+
+- `git commit` (incluye `--amend`)
+- `git push` (incluye `--force` / `-f`)
+- `git merge` · `git rebase` · `git cherry-pick`
+- `git tag` (crear o editar)
+- `git reset --hard` · `git restore .` · `git checkout -- .` · `git clean -fd` · `git stash` (cuando hay trabajo sin commit)
+
+Y **siempre** prohibido, aún cuando el usuario pida commit: `--no-verify` (respetar los hooks pre-commit), `--force`, trailers `Co-Authored-By`, firmas de modelo.
+
+### Operaciones read-only (siempre permitidas, sin preguntar)
+
+`status` · `log` · `diff` · `branch --show-current` · `rev-parse` · `show`. `git checkout` (cambio de rama) **no** es read-only: requiere `AskUserQuestion` aunque no sea destructivo (ver verificación de rama).
+
+### Verificación de rama (antes de editar)
+
+La rama esperada **nunca se asume desde la rama actual** — el usuario pudo cambiarla a mano. Verificar contra la rama de trabajo declarada por fuente antes de cualquier `Write/Edit`.
+
+Campos por fuente: `alias`, `path`, `main_branch` (base, default `certificacion`), `expected_work_branch`, `current_branch`, `match` (`current == expected`), `dirty` (cambios sin commit).
+
+Casos:
+
+- **`match=true`** → OK, editar.
+- **`match=false, dirty=false`** (Caso A — rama distinta, repo limpio) → `AskUserQuestion`: hacer `git checkout <expected>` / mantener current y actualizar la expectativa de la sesión / cancelar.
+- **`match=false, dirty=true`** (Caso B — rama distinta + cambios sin commit) → **pausar y esperar resolución manual**. No proponer checkout (podría perder trabajo). Pedir al usuario commit/stash/discard y avisar cuando continuar.
+- **Cross-fuente (hub)**: si las fuentes tocadas apuntan a ramas distintas sin declararlo, **hard gate** — bloquear avance con `AskUserQuestion` (alinear todas / declarar divergencia explícita / cancelar).
+- **HEAD detached** → tratar como Caso A.
+- **Fuente fuera de git** (`is_repo=false`) → informar, no bloquear.
+
+### Commits — propose-then-execute, una fuente a la vez
+
+Ante cualquier pedido o disparo de commit (cierre de loop, "commitea esto", "guardá los cambios"):
+
+1. Resolver las fuentes y su estado dirty/rama.
+2. Si hay 1+ fuentes `dirty=true`, invocar **una sola** `AskUserQuestion` con un tab por fuente dirty (máx 4 simultáneas; si N>4, en tandas):
+   - Header del tab: el `alias` de la fuente.
+   - Opciones: "Aprobar sugerido (Recomendado)" con el mensaje canónico / "Saltar esta fuente". `Other` = mensaje custom.
+3. Ejecutar `git -C <path> commit -m "<msg>"` solo en las fuentes aprobadas, **una a una**. Respetar hooks (sin `--no-verify`).
+4. Si una fuente tiene `match=false` (rama distinta a la esperada): **omitirla y abortar su commit**; avisar para alinear la rama primero.
+5. Si todas están `dirty=false` → skip silencioso, informar en chat que no hay nada que commitear.
+
+**Bypass** (Regla 5): si el usuario aporta el mensaje literal exacto (`-m "..."`, comillas), commitear directo sin `AskUserQuestion`, pero seguir validando rama, hooks y formato. Si el literal viola el formato, avisar antes de ejecutar.
+
+### Formato canónico del mensaje
+
+- **Una sola línea**, corta (≤72 chars sugerido), descriptiva (qué cambia, no cómo).
+- Incluir el código de sesión activa (`session<NNN>` como tag o en el prefijo) cuando aplique.
+- Prefijo Conventional Commits **opcional** (`feat:` `fix:` `docs:` `chore:` `refactor:` `test:`).
+- **Prohibido**: multi-línea/body, trailers `Co-Authored-By`, firmas de modelo, emojis (salvo pedido explícito), `--no-verify`.
+
+Válidos:
+```
+session007: agrega politica de commits controlados
+feat(session012): nuevo export-scripts
+fix(session018): corrige drift en hooks.json
+```
+
+Fuera de sesión activa: relajar a "1 línea + sin co-author"; el tag `session<NNN>` se omite. El propose-then-execute sigue activo.
+
+## Output
+
+Ninguno en `docs/`. Produce commits **solo** cuando el usuario aprueba, en los repos fuente. La verificación de rama puede actualizar la expectativa de rama de la sesión si el usuario lo elige.
+
+## Source
+
+Reciclada de la doctrina vieja: `doctrine/session/references/commits-policy.md` (Reglas 1-5: propose-then-execute, formato canónico, bypass) + `doctrine/session/references/branch-verification.md` (Casos A/B/C, cross-fuente hard gate). Se descarta la dependencia de comandos CLI específicos (`agent-workflow sources`): la verificación se hace con git read-only directo más la rama de trabajo declarada por la sesión.

package/skills/w/roles/research/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: research
+description: >
+  Capacidad de investigación on-demand que los loops componen cuando necesitan evidencia para avanzar.
+  Crea una sesión de investigación, lee el workspace + repos asociados + MCPs en modo read-only,
+  produce ANALYSIS-FILE → CONCLUSIONS. Cierra INCONCLUSIVE si la pregunta no puede responderse
+  con las fuentes disponibles. Discrimina cuándo investigar ("¿puedo responder leyendo repo/datos?")
+  vs cuándo preguntar al humano ("¿depende de lo que el usuario quiere?").
+---
+
+# research — On-demand investigation capability
+
+## Role
+
+`research` — implementación built-in por defecto. Rebindeable a otra skill (de tercero o `off`) en `.workflow/skills.toml`.
+
+## Purpose
+
+Resolver preguntas factuales sobre el sistema antes de actuar: leer el repo, rastrear datos vía MCP read-only, producir hallazgos sintetizados. **No crea artefactos de producción** — produce evidencia y conclusiones para que el loop que la compuso pueda avanzar con información de calidad.
+
+El discriminador clave:
+
+| La pregunta... | Acción |
+|---|---|
+| puede responderse leyendo repo / datos (hechos objetivos del sistema) | **investigar** |
+| depende de preferencias, prioridades o decisiones del usuario | **preguntar al humano** vía `AskUserQuestion` |
+| está parcialmente en el repo y parcialmente en intención del usuario | investigar primero, luego preguntar solo por la parte incierta |
+
+## Composed by
+
+Todos los loops la cargan on-demand:
+
+| Loop | Cuándo la compone |
+|---|---|
+| `spec-refine-loop` | para entender el sistema existente antes de refinar un spec |
+| `plan-new-loop` | para descubrir dependencias, integrations, convenciones del repo |
+| `plan-exec-loop` | para investigar comportamiento real de un componente antes de modificarlo |
+| `quick-loop` | para responder preguntas de orientación sobre el código o datos |
+
+## Knowledge
+
+### Investigation lifecycle
+
+```
+[pregunta del loop] → [crear sesión research] → [recolectar evidencia] → [sintetizar] → [CONCLUSIONS]
+                                                          ↕
+                                               [nueva hipótesis o gap] → [más evidencia o INCONCLUSIVE]
+```
+
+1. **Crear sesión research** en `.workflow/sessions/<slug>/` con `SESSION.md` (pregunta original + scope).
+2. **Recolectar evidencia** — read-only: `Read`, `Grep`, `Glob`, MCP SELECT, `git log`.
+3. **Escribir `ANALYSIS-FILE.md`** con hallazgos crudos.
+4. **Sintetizar** en `CONCLUSIONS.md` con conclusiones evidenciadas.
+5. **Cerrar** la sesión: estado `closed` si converge; `inconclusive` si no hay suficiente material.
+
+### Ask-vs-research discriminator (examples)
+
+```
+"¿qué convención de nombres usa este repo?"     → investigar (Grep + Read)
+"¿qué endpoint necesita el spec?"               → investigar (leer spec + código)
+"¿prefieres enfoque A o B?"                     → preguntar al humano
+"¿cuál es el estado de la tabla X?"             → investigar (MCP read-only)
+"¿qué tan urgente es esto para ti?"             → preguntar al humano
+"¿el servicio Y ya tiene auth implementado?"    → investigar (leer código)
+```
+
+### ANALYSIS-FILE.md schema
+
+```markdown
+# Analysis — <slug>
+
+## Question
+
+[La pregunta exacta que el loop planteó.]
+
+## Sources consulted
+
+- Codigo: <repo/path:lineas>
+- BD (<mcp-name>): queries en queries/
+- Git: <SHAs relevantes>
+- Refs externas: <links si aplica>
+
+## Finding 1: <titulo>
+
+- **Que se observo**: ...
+- **Donde**: <path o link>
+- **Cuando**: <fecha si aplica>
+
+## Finding N: ...
+
+## Tentative hypotheses
+
+- [hipotesis sin compromiso, para revisar en synthesis]
+
+## Gaps
+
+- [lo que no pudo leerse o no esta disponible]
+```
+
+### CONCLUSIONS.md schema
+
+```markdown
+# Conclusions — <slug>
+
+## Summary
+
+[1-2 oraciones: que se investigo y que se concluyó.]
+
+## Conclusions
+
+- **C1**: <conclusion + link a ANALYSIS-FILE#section>
+- **C2**: ...
+
+## Recommendations
+
+- **R1**: <accion concreta para el loop que hizo la pregunta>
+
+## Open (gaps)
+
+- <pregunta sin responder si aplica>
+```
+
+### DB rule (invariant #4)
+
+- **Solo SELECT** — nunca DML/DDL.
+- **Escribir la query primero** en `.workflow/sessions/<slug>/queries/NNN-<slug>.sql` con header:
+  ```sql
+  -- Query: <proposito>
+  -- MCP: <nombre>
+  -- Fecha: YYYY-MM-DD
+  -- Sesion: <slug>
+  -- Costo estimado: <filas|N/A>
+  ```
+- **Si hay >1 MCP candidato sin default declarado**: preguntar al humano cuál usar antes de ejecutar.
+- **Cost guard antes de ejecutar**:
+  - `COUNT(*) ≤ 1.000` o lookup por PK → ejecutar directo.
+  - `1.000–10.000` filas o seq scan tabla pequeña → avisar estimado al usuario.
+  - `> 10.000` filas o seq scan tabla grande → confirmación explícita del usuario.
+  - UPDATE/INSERT/DELETE → rechazar.
+
+### Code reading rules
+
+- Usar `Grep` y `Read` extensivamente. **Nunca** `Edit/Write` durante investigación.
+- Citar con path + líneas: `src/services/Foo.java:142`.
+- Si el código está disperso: `Glob` + `Grep` para acotar.
+
+### Git read-only (git-safe, invariant #5)
+
+Solo: `git log`, `git show`, `git diff`, `git blame`, `git branch --show-current`.
+Nunca durante investigación: `commit`, `push`, `merge`, `rebase`, `reset`, `checkout`.
+
+### Inconclusive closure
+
+Si tras investigar los gaps persisten y no pueden cerrarse con las fuentes disponibles:
+- Documentar los gaps en `CONCLUSIONS.md#Open`.
+- Marcar sesión como `inconclusive`.
+- Reportar al loop: qué se pudo y qué no — el loop decide si pregunta al humano.
+
+### Research session artifacts
+
+```
+.workflow/sessions/<slug>/
+├── SESSION.md          # pregunta original + scope + estado (open|closed|inconclusive)
+├── ANALYSIS-FILE.md    # hallazgos crudos (equivale a EVIDENCE.md del modelo viejo)
+├── CONCLUSIONS.md      # sintesis + recomendaciones para el loop
+└── queries/            # SQL read-only (si se usó MCP)
+    └── 001-<slug>.sql
+```
+
+## Output
+
+Produce en `.workflow/sessions/<slug>/`:
+- `ANALYSIS-FILE.md` — hallazgos crudos sin sintetizar.
+- `CONCLUSIONS.md` — conclusiones con evidencia + recomendaciones para el loop.
+- `queries/*.sql` — solo si se usó MCP.
+
+No gradua a `docs/` (invariant #1). El loop que compone esta capacidad consume las conclusiones y actua en consecuencia.
+
+## Source
+
+Reciclado de `analyze-investigate`, `analyze-synthesize` y `analyze-conclude` del bundle viejo. Se conserva: el modelo de investigacion divergente → sintesis → conclusiones; las reglas read-only; el cost guard de queries; la discriminacion de gaps. Se descarta: la terminología de `flow=analyze`, `EVIDENCE.md`/`FINDINGS.md` como nombres canónicos (ahora `ANALYSIS-FILE.md`/`CONCLUSIONS.md`), el lifecycle de sesiones legacy, y la modulacion por modalidad (technical/incident/data) — la skill de research es de propósito general.

package/skills/w/roles/sql/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: sql
+description: >-
+  SQL / database capability — built-in default for the `sql` role. Authoring DB
+  changes as versioned scripts (never executing them): writes statements to the
+  session `SCRIPTS.sql` with `@category` + `@stmt` markers, applies project SQL
+  style (canonical header, BEGIN/COMMIT, idempotency, explicit schema, CTEs over
+  DO/LOOP), classifies into the 4 categories, and knows how rollbacks are derived
+  on export. DB access is read-only via MCP — DML/DDL is NEVER executed (invariant 4).
+  Use when a loop writes migrations / queries, when research reads schema, or when
+  export-scripts consolidates the bundle.
+---
+
+# sql — SQL / database capability
+
+## Role
+
+`sql` — built-in default. Rebindable in `.workflow/skills.toml` (third-party skill or `off`). When `off`, the loop continues without DB authoring help and says so if the task needed it.
+
+## Purpose
+
+Autorar cambios de base de datos como **scripts SQL versionados**, nunca ejecutándolos. Cubre dos modos:
+
+- **Read-only** (consulta): leer schema/datos via MCP para entender el dominio (research, planning).
+- **Write-to-script** (cambio): toda mutación de BD se escribe a `SCRIPTS.sql` de la sesión; la **aplica el usuario**, no la IA.
+
+## Composed by
+
+- **research** — leer schema via MCP read-only para entender el dominio.
+- **`plan-exec-loop`** — cada cambio SQL se appendea a `SCRIPTS.sql` durante la ejecución.
+- **`quick-loop`** — igual, para el atajo liviano.
+- **`export-scripts`** — consolida los `SCRIPTS.sql` de N sesiones en el bundle `docs/scripts/NNN-export-scripts-YYYY-MM-DD/` y deriva el rollback.
+
+## Knowledge
+
+### Regla cero — nunca ejecutar SQL (invariante 4)
+
+La IA **nunca ejecuta DML/DDL** contra ninguna BD, por ningún canal (MCP, `psql`, `Bash`, driver de app). Las migraciones quedan en `SCRIPTS.sql` y las **aplica el usuario**. Si aparece la tentación de "verificar aplicando", rehusar y pedir al usuario que ejecute.
+
+- **Lecturas read-only via MCP**: `SELECT`, inspección de schema, conteos — OK. Sin `INSERT/UPDATE/DELETE/CREATE/ALTER/DROP/TRUNCATE`.
+- Los MCP de BD (cert/prod) son **READONLY** por contrato.
+- Excepción única, que NO relaja la regla: si el usuario pide explícitamente "ejecutalo vos contra cert", aún así confirmar por bloque y no asumir autorización ampliada.
+
+### Staging — archivo único `SCRIPTS.sql` por sesión
+
+```
+.workflow/sessions/<folder>/
+└── SCRIPTS.sql      (consolidado de TODAS las sentencias de la sesión)
+```
+
+Cada sentencia se **appendea** con un par de markers en comentarios:
+
+```sql
+-- @category: 01-ddl-tablas
+-- @stmt: 01-crear-tabla-usuarios
+CREATE TABLE IF NOT EXISTS esq_credito.tb_usuarios (
+  ...
+);
+```
+
+- `@category` clasifica (4 valores canónicos, abajo).
+- `@stmt` da el slug determinístico `NN-verbo-objetivo`; `export-scripts` deriva el filename al separar.
+- Orden dentro del archivo = orden cronológico de append. El orden de ejecución final por categoría (01→02→03→04) lo resuelve `export-scripts`, no este paso.
+- `BEGIN;` global al inicio del archivo, `COMMIT;` al final. Cada sentencia individual **no** trae su propio BEGIN/COMMIT.
+- **Sin** `.rollback.sql` per archivo durante exec — el rollback se genera al exportar.
+
+### Las 4 categorías (`@category`)
+
+| Marker | Patrones de detección |
+|---|---|
+| `01-ddl-tablas` | `CREATE/DROP/ALTER TABLE`, `CREATE INDEX`, `CREATE SEQUENCE` |
+| `02-ddl-funciones` | `CREATE [OR REPLACE] FUNCTION/PROCEDURE`, `DROP FUNCTION/PROCEDURE` |
+| `03-migracion` | `UPDATE`, `INSERT ... SELECT`, `DELETE` sobre datos existentes, transformaciones de columnas |
+| `04-inserts` | `INSERT INTO ... VALUES`, seeds de catálogos, datos de configuración inicial |
+
+**Orden de ejecución obligatorio**: 01 → 02 → 03 → 04. El `SCRIPTS.sql` puede mezclar categorías cronológicamente; `export-scripts` ordena el bundle final.
+
+### Estilo SQL (cumple `database-conventions`)
+
+- **Header canónico de 4 líneas**, entre dos líneas de iguales:
+  ```sql
+  -- ============================================================================
+  -- Script:  NNN-tipo-objetivo.sql
+  -- Sesion:  sNNN
+  -- Objeto:  <qué hace, 1-2 líneas>
+  -- Alcance: <filtros y boundaries del cambio, 1 línea>
+  -- ============================================================================
+  ```
+  Solo 4 campos. Autor/Fecha/notas largas NO van en el header (si hacen falta, bloque libre debajo). Si el motor no es Postgres, indicarlo en `Objeto:`.
+- **Idempotencia**: `CREATE TABLE IF NOT EXISTS`, `DROP ... IF EXISTS`, `CREATE OR REPLACE`, `ON CONFLICT`.
+- **Schema explícito** siempre (`esq_credito.tb_x`, nunca `public.`).
+- **CTEs sobre DO/LOOP**: una transformación = `WITH ... AS` encadenadas + un `INSERT/UPDATE/DELETE` final. Evitar `DO $$ ... LOOP ... END $$` cuando el resultado se logra declarativamente (más fácil de auditar y revertir). Excepción: descubrimiento dinámico de objetos (FKs/columnas/constraints) — documentar el motivo en `Objeto:`.
+- **Queries parametrizadas** siempre (nunca concatenar strings) — en cualquier SQL que termine en código de app.
+- Nunca crear `fn_*`/`sp_*` para reusar lógica exclusiva de un script; usar CTE o inline.
+- **Separadores entre secciones** (solo si hay 2+ secciones):
+  ```sql
+  -- ----------------------------------------------------------------------------
+  -- N. Descripción corta de qué hace este bloque.
+  -- ----------------------------------------------------------------------------
+  ```
+  Cajas dobles (`====`) solo para el header.
+
+### Proceso de mantenimiento del `SCRIPTS.sql`
+
+1. **Detectar la categoría** del cambio (tabla de markers).
+2. **Verificar idempotencia** del statement.
+3. **Append** con par de markers (`@category` + `@stmt`).
+4. **Style check** — header canónico, CTEs sobre DO/LOOP, schema explícito.
+5. **No** renumerar ni mover (solo hay un `SCRIPTS.sql`).
+6. **No** generar `.rollback.sql` durante exec.
+
+### Rollback (lo genera `export-scripts`, no este paso)
+
+`export-scripts` lee los forwards ya consolidados y genera **un único** `00-ROLLBACK.sql` al root del bundle, en orden inverso. Conocer las estrategias para escribir forwards reversibles:
+
+| Forward | Rollback |
+|---|---|
+| `CREATE TABLE IF NOT EXISTS tb_x` | `DROP TABLE IF EXISTS tb_x;` |
+| `ALTER TABLE tb_x ADD COLUMN col` | `ALTER TABLE tb_x DROP COLUMN IF EXISTS col;` |
+| `CREATE INDEX idx_...` | `DROP INDEX IF EXISTS idx_...;` |
+| `CREATE SEQUENCE seq_...` | `DROP SEQUENCE IF EXISTS seq_...;` |
+| `CREATE OR REPLACE FUNCTION fn_x(...)` | `DROP FUNCTION IF EXISTS fn_x(<firma>);` |
+| `UPDATE/DELETE` con backup en `esq_audit.tb_bkp_*` | `UPDATE … FROM esq_audit.tb_bkp_…` |
+| `INSERT INTO tb_x VALUES (...)` | `DELETE FROM tb_x WHERE <clave natural / rango>;` (nunca DELETE sin WHERE) |
+
+**Irreversibles → bloque "Fase 5" manual** (fuera de la transacción, una línea por caso): `TRUNCATE`, `DROP COLUMN`/`DROP TABLE` sin backup, `ALTER COLUMN TYPE` con pérdida, `DROP ... CASCADE`, `DELETE/UPDATE` sin respaldo en `esq_audit`. Para que un cambio destructivo sea reversible, escribir el backup en el mismo forward (`esq_audit.tb_bkp_<tabla>_sNNN`).
+
+## Output
+
+- Durante loops: sentencias appendeadas a `.workflow/sessions/<folder>/SCRIPTS.sql` (artefacto de sesión, no `docs/`).
+- Vía `export-scripts`: bundle `docs/scripts/NNN-export-scripts-YYYY-MM-DD/` — `00-ROLLBACK.sql` + `01-<CATEGORIA>.sql` … (numeración continua, sin gaps por categoría vacía) + `README.md`. Orden canónico de categorías: `DDL-TABLES → DDL-FUNCTIONS → DML → INSERTS`.
+
+Nunca escribe a `docs/` desde un loop (invariante 1: solo `export-*` exporta). Nunca ejecuta nada contra una BD (invariante 4).
+
+## Source
+
+Reciclada de `standards/sql-script-organizer/` (staging `SCRIPTS.sql`, markers, 4 categorías, estilo) + `standards/sql-rollback-generator/` (derivación de rollback, irreversibles, Fase 5) + reglas de estilo de `standards/coding-standards/references/database-conventions.md`. Se moderniza al modelo nuevo: el bundle lo arma `export-scripts`, no la skill; el "release/graduate" viejo se reemplaza por `export-scripts`.