@tacuchi/agent-workflow-cli 11.0.0 → 12.0.0

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

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

@@ -0,0 +1,180 @@
+---
+name: testing
+description: >
+  Estrategia y ejecución de pruebas: selecciona niveles (unit / integration / e2e),
+  resuelve comandos por stack detectado, guía la convención de nombres y estructura de tests.
+  Pregunta al humano antes de ejecutar; nunca lanza el test runner sin confirmación explícita.
+  Compuesta por plan-exec-loop y quick-loop durante la fase de validación de cambios.
+---
+
+# testing — Test strategy and execution capability
+
+## Role
+
+`testing` — implementación built-in por defecto. Rebindeable a otra skill (de tercero o `off`) en `.workflow/skills.toml`.
+
+## Purpose
+
+Dar a los loops la capacidad de razonar sobre tests: qué nivel aplicar, con qué comando, con qué convención. **No ejecuta tests de forma autónoma** — primero pregunta al humano si quiere que el loop los corra, o si los correrá manualmente, o si no hacen falta en esta sesión.
+
+## Composed by
+
+| Loop | Cuándo la compone |
+|---|---|
+| `plan-exec-loop` | durante validation de cada task ejecutada |
+| `quick-loop` | cuando el cambio quick requiere verificación |
+
+## Knowledge
+
+### Execution rule
+
+Por defecto, **no ejecutar pruebas automáticamente**. Antes de correr cualquier test runner:
+
+```
+AskUserQuestion:
+  "¿Correr los tests?"
+  [a] Sí, el loop los ejecuta
+  [b] Los corro yo manualmente
+  [c] No hace falta en esta sesión
+```
+
+Solo saltear la pregunta si el workspace declara `Validation mode: auto` en `.workflow/config.toml`.
+
+### Test levels
+
+Tres niveles universales (adaptados al stack detectado):
+
+| Nivel | Alcance | Cuándo usarlo |
+|---|---|---|
+| **a) Unit** | Lógica aislada (servicios, utils, mappers) | Fix puntual, lógica sin dependencias externas |
+| **b) Integration** | Unit + capa de API/controladores | Endpoint nuevo o modificado |
+| **c) Full** | Integration + contexto completo + e2e | Feature completa, flujo crítico, integración entre capas |
+
+### Stack resolution
+
+El stack se detecta por archivos de manifest presentes en el workspace. Precedencia: si el bloque `WORKSPACE → Stack` declara override de build/wrapper, usarlo.
+
+#### Spring Boot (Maven)
+
+| Nivel | Framework | Comando |
+|---|---|---|
+| a) Unit | JUnit 5 + Mockito | `./mvnw test -Dtest=ClaseTest` |
+| b) Integration | + MockMvc | `./mvnw test` |
+| c) Full | + @SpringBootTest | `./mvnw verify` |
+
+> Windows: `mvnw.cmd` en lugar de `./mvnw`.
+
+#### Spring Boot (Gradle)
+
+| Nivel | Comando |
+|---|---|
+| a) Unit | `./gradlew test --tests ClaseTest` |
+| b) Integration | `./gradlew test` |
+| c) Full | `./gradlew integrationTest` (o `check`) |
+
+#### Angular
+
+| Nivel | Framework | Comando |
+|---|---|---|
+| a) Unit | Jasmine + Karma (o Jest) | `ng test --watch=false` |
+| b) Integration | + TestBed + ComponentFixture | `ng test --watch=false` |
+| c) Full | + Cypress/Playwright si configurado | `npm run e2e` |
+
+#### Node / TypeScript genérico
+
+| Nivel | Comando |
+|---|---|
+| a) Unit | `npm test` (script `test` en `package.json`) |
+| b) Integration | `npm test` con suites de integración |
+| c) Full | `npm run test:e2e` o según config |
+
+#### Resolución automática
+
+1. `mvnw` / `mvnw.cmd` → Maven wrapper.
+2. `gradlew` → Gradle wrapper.
+3. `angular.json` → `ng test`.
+4. `package.json` con script `test` → `npm test`.
+5. Si hay override en `WORKSPACE → Stack` → usarlo.
+
+### Naming conventions
+
+**Java:** clase `[Objetivo]Test.java`, método `[metodo]_[escenario]_[resultado]`. Estructura Arrange-Act-Assert.
+
+```java
+@Test
+void enviar_conEmailValido_retornaExito() {
+    // Arrange
+    var request = new NotificacionRequest("user@example.com", "Asunto", "template", Map.of());
+    when(emailProvider.send(any())).thenReturn(true);
+    // Act
+    var resultado = service.enviar(request);
+    // Assert
+    assertThat(resultado).isTrue();
+}
+```
+
+**Angular / TypeScript:** archivo `[nombre].spec.ts`, bloques `describe` / `it`. Usar `TestBed` para componentes.
+
+```typescript
+describe('AuthService', () => {
+  it('should return token on login', () => {
+    // ...
+  });
+});
+```
+
+### Level selection prompt (to show the human)
+
+Adaptar al stack resuelto. Ejemplo para Spring Boot:
+
+```
+¿Qué nivel de pruebas aplicamos?
+  a) Unitarios       — JUnit 5 + Mockito (rápido, aislado)
+  b) Integración     — + MockMvc controllers
+  c) Completo        — + @SpringBootTest (contexto Spring completo)
+```
+
+El humano puede cambiar de nivel en cualquier momento o decidir no ejecutar desde el loop.
+
+### Execution and logging
+
+1. Confirmar que el humano quiere ejecución desde el loop (ver "Execution rule").
+2. Ejecutar el comando resuelto según stack y nivel.
+3. Registrar resultado en `TEST_LOG.md` **solo si** el humano pidió registro formal o la ejecución fue desde el loop.
+4. Si el humano ya validó manualmente, no repetir; anotar una línea breve si aporta trazabilidad.
+5. Si hay fallos y el humano quiere continuar: corregir y re-ejecutar.
+
+### TestBuilder pattern (Java)
+
+Para construir fixtures reutilizables sin acoplar los tests al constructor de producción:
+
+```java
+public class NotificacionTestBuilder {
+    private String destinatario = "test@example.com";
+    private String estado = "PENDIENTE";
+
+    public static NotificacionTestBuilder builder() { return new NotificacionTestBuilder(); }
+
+    public NotificacionTestBuilder destinatario(String val) { this.destinatario = val; return this; }
+    public NotificacionTestBuilder estado(String val) { this.estado = val; return this; }
+
+    public Notificacion build() {
+        var e = new Notificacion();
+        e.setDestinatario(destinatario);
+        e.setEstado(estado);
+        return e;
+    }
+}
+```
+
+## Output
+
+No produce artefactos de forma autónoma. Cuando el humano confirma ejecución:
+- Corre el comando resuelto y reporta el resultado inline.
+- Escribe `TEST_LOG.md` en la sesión activa solo si fue pedido explícitamente.
+
+No gradua a `docs/` (invariant #1).
+
+## Source
+
+Reciclado de `agent-workflow/standards/testing-strategy/` del bundle viejo (v0.1.0). Se conserva: los tres niveles (a/b/c), la regla de confirmación antes de ejecutar, la resolución de stack por manifest, los naming conventions, la tabla de comandos por framework. Se descarta: la referencia al bloque `AW-PROJECT → Stack` (reemplazado por `WORKSPACE → Stack`), el `TEST_LOG.md` obligatorio, el sandbox-readonly-rules legacy, referencias a `plan mode` del sistema anterior.

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

@@ -0,0 +1,148 @@
+---
+name: tools
+description: >
+  Capacidad de autoría de herramientas y utilidades que el plan crea: scripts, CLIs, helpers,
+  configuraciones reutilizables. Produce el código de la herramienta y su documentación en
+  docs/tools/. Compuesta por plan-exec-loop cuando una task crea una utilidad nueva (no un
+  cambio de producto). No aplica a código de producto — solo a tooling auxiliar.
+---
+
+# tools — Tool authoring capability
+
+## Role
+
+`tools` — implementación built-in por defecto. Rebindeable a otra skill (de tercero o `off`) en `.workflow/skills.toml`.
+
+## Purpose
+
+Dar al `plan-exec-loop` la capacidad de crear herramientas y utilidades auxiliares con una estructura consistente: el código de la tool + su documentación en `docs/tools/`. Cubre scripts de automatización, CLIs auxiliares, helpers de CI/CD, configuraciones reutilizables, y cualquier artefacto de tooling que el plan genere como producto de una task.
+
+**Distinciones clave:**
+
+| Tipo | Rol | ¿Quién lo maneja? |
+|---|---|---|
+| Código de producto (services, controllers, components) | cambio en el repo fuente | `plan-exec-loop` + `coding-standards` |
+| Tool / utilidad auxiliar creada por el plan | herramienta de soporte | esta skill (`tools`) |
+| Script SQL de migración | dato persistente | `sql` + `export-scripts` |
+
+## Composed by
+
+| Loop | Cuándo la compone |
+|---|---|
+| `plan-exec-loop` | cuando una task del plan crea una herramienta nueva (helper, script CLI, configuración reutilizable) |
+
+## Knowledge
+
+### Tool vs. product code
+
+Una **tool** es cualquier artefacto que el plan crea para soportar el trabajo, no para el usuario final del producto:
+
+- Scripts de seed/fixtures para desarrollo local.
+- CLIs auxiliares (`validate-schema.js`, `sync-env.sh`).
+- Helpers de CI/CD (scripts de deploy, linters de configuración).
+- Configuraciones reutilizables (templates de entorno, fixtures de test).
+- Generadores o scaffolders para tareas repetitivas.
+
+Si el artefacto es lógica de negocio del producto → no es una tool, es código de producto.
+
+### Tool anatomy
+
+Cada tool tiene dos partes:
+
+1. **El código** — en el repo fuente apropiado (en su carpeta natural: `scripts/`, `tools/`, `bin/`, etc.).
+2. **La doc** — en `docs/tools/NNN-<slug>.md` del workspace (invariant #2: PLAN escribe `docs/tools`).
+
+### docs/tools/NNN-<slug>.md schema
+
+```markdown
+# <Nombre de la tool>
+
+> **Tipo**: <script | cli | helper | config-template | generator>
+> **Repo**: <alias de la fuente donde vive el código>
+> **Path**: <path relativo al repo>
+> **Creada en**: <sesion-slug>
+
+## Purpose
+
+[1-2 oraciones: qué hace y cuándo usarla.]
+
+## Usage
+
+```<lenguaje o bash>
+<ejemplo de invocación>
+```
+
+## Parameters
+
+| Param | Tipo | Requerido | Default | Descripcion |
+|---|---|---|---|---|
+| `--foo` | string | sí | — | ... |
+
+## Output
+
+[Qué produce: archivos, stdout, efectos secundarios.]
+
+## Dependencies
+
+- <prerequisito 1: binario, env var, servicio>
+- <prerequisito 2>
+
+## Examples
+
+```bash
+# Caso de uso principal
+./scripts/validate-schema.sh --env staging
+
+# Caso edge
+./scripts/validate-schema.sh --env staging --dry-run
+```
+
+## Notes
+
+[Advertencias, limitaciones, cuándo NO usar.]
+```
+
+### Numbering
+
+`docs/tools/` usa numeración secuencial `NNN` (001, 002, ...). Consultar el número siguiente con el filesystem antes de escribir; no asumir el siguiente en base a lo que el loop ya sabe.
+
+### Git-safe authoring (invariant #5)
+
+- Verificar la rama esperada antes de escribir código.
+- Proponer el commit; nunca hacer `push`/`--amend`/`--no-verify` autónomamente.
+- Si la tool modifica scripts ya existentes: leer el archivo completo primero.
+
+### DB scripts rule (invariant #4)
+
+Si la tool genera o manipula SQL:
+- Nunca generar DML/DDL que se ejecute inline — el SQL va a `SCRIPTS.sql` y se entrega vía `export-scripts`.
+- Una tool puede generar un archivo `.sql`; no puede ejecutarlo contra la BD.
+
+### Code quality baseline
+
+Al autorar el código de la tool, aplicar lo que la capacidad `coding-standards` del workspace establezca. Si `coding-standards` está `off` o no está configurada, usar los estándares del lenguaje detectado:
+- **Shell**: shellcheck-compatible, variables entre comillas, `set -euo pipefail`.
+- **Node/TS**: tipado explícito, sin `any` salvo justificación, error handling explícito.
+- **Python**: type hints, docstring en funciones públicas, manejo de excepciones específico.
+- **Java**: Javadoc mínimo en clases públicas, excepciones tipadas.
+
+### Self-contained tools
+
+Preferir tools que declaren explícitamente sus dependencias (en doc + en el propio script). Una tool que falla silenciosamente porque le falta un binario es peor que una que no existe.
+
+```bash
+# Pattern: check dependencies al inicio
+command -v jq >/dev/null 2>&1 || { echo "jq requerido: brew install jq"; exit 1; }
+```
+
+## Output
+
+Por cada tool creada:
+- **Código**: en el repo fuente, en la carpeta que corresponda (`scripts/`, `tools/`, `bin/`).
+- **Doc**: en `docs/tools/NNN-<slug>.md` del workspace.
+
+Writes `docs/tools/` (invariant #2: PLAN es el dueño de esta carpeta). No gradua a ninguna otra carpeta de `docs/`.
+
+## Source
+
+Autoria original (no hay skill equivalente en el bundle viejo). Basado en la descripción del rol en `workflow-skills/README.md` y en el invariant #2 del diseño (`docs/tools/` es del flujo PLAN). Las convenciones de estructura de doc (`## Purpose`, `## Usage`, `## Parameters`, `## Output`, `## Examples`) siguen el patrón de calidad del bundle.