@tacuchi/agent-workflow-cli 13.1.0 → 14.1.0

package/skills/w/loops/plan-exec-loop/SKILL.md

@@ -3,19 +3,17 @@ name: plan-exec-loop
 description: >-
   Ejecuta un plan de implementación (docs/plans/PPP-plan-<slug>.md) como living
   doc: lo lee y actualiza fase a fase mientras edita el código real, gestiona BD
-  y git. Heir del chasis spec-refine-loop: reusa su motor gap-driven (aplicado
-  dentro de una tarea ante decisiones/dudas no obvias), research inline con
-  regla BD read-only, structured-choice con ≤3 preguntas de contenido + 1 control flow
-  (Compactar/Cerrar) siempre, y artefactos como log vivo (CHECKPOINT siempre,
-  BACKLOG solo si difiere). Sus deltas: una sola session por run (resume vía
-  checkbox del plan-doc + CHECKPOINT); git seguro (verifica rama esperada antes
-  de editar, propone commits por fuente, nunca push/--amend/--no-verify); la IA
-  NUNCA ejecuta DML/DDL (migraciones se redactan en SCRIPTS.sql, solo read-only
-  se ejecuta); validación por fase y final (lo dependiente de migración no
-  aplicada se difiere como handoff a DBA); y SIN auto-export (escribe solo
-  docs/plans + docs/tools; el resto queda como artefacto de session para
-  export-*). Compone git, tools y sql. Lo arranca
-  /w:plan-exec y es reanudable. Invocar para implementar un plan ya generado.
+  y git. Heir del chasis spec-refine-loop: reusa su motor gap-driven, research
+  inline (regla BD read-only), structured-choice (≤3 preguntas + control flow
+  Compactar/Cerrar) y artefactos como log vivo (CHECKPOINT siempre, BACKLOG solo
+  si difiere). Deltas: una sola session por run (resume vía checkbox del plan-doc
+  + CHECKPOINT); git seguro (verifica la rama antes de editar, propone commits por
+  fuente, nunca push/--amend/--no-verify); la IA NUNCA ejecuta DML/DDL (las
+  migraciones se redactan en SCRIPTS.sql, solo read-only se ejecuta); validación
+  por fase y final (lo dependiente de migración no aplicada se difiere a DBA); y
+  SIN auto-export (escribe solo docs/plans; el resto queda como artefacto para
+  export-*). Compone git y sql. Lo arranca /w:plan-exec, es reanudable. Invocar
+  para implementar un plan ya generado.
 ---
 
 # plan-exec-loop
@@ -36,13 +34,12 @@ PLAN
 
 ## Writes
 - `docs/plans/PPP-plan-<slug>.md` (**read/update**, living doc: estado de fases/tareas, `Open questions`).
-- `docs/tools/`: herramientas/utilidades reusables que la IA **crea** durante la ejecución (salida directa, no export).
 - Artefactos de la plan-exec session en `.workflow/sessions/` (`SCRIPTS.sql`, `DECISION`, `ANALYSIS-FILE`/`CONCLUSIONS`, …).
 - **NO** escribe en otras carpetas `docs/` ni **gradúa/exporta** otros artefactos automáticamente (ver *Boundary*).
 
 ## Boundary — sin auto-export (hard rule)
 
-Este loop **nunca gradúa/promueve artefactos** a `docs/`. Las únicas carpetas `docs/` que escribe son **`docs/plans`** (el plan, living) y **`docs/tools`** (las herramientas que crea — salida directa, no un export). Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, diagramas → `docs/diagrams`, etc.) lo hacen skills **`export-*`** aparte, como paso explícito posterior. Los artefactos quedan en sus sessions hasta entonces.
+Este loop **nunca gradúa/promueve artefactos** a `docs/`. La única carpeta `docs/` que escribe es **`docs/plans`** (el plan, living). Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, diagramas → `docs/diagrams`, etc.) lo hacen skills **`export-*`** aparte, como paso explícito posterior. Los artefactos quedan en sus sessions hasta entonces. Si una tarea crea una herramienta/utilidad, la documenta la skill ambiente `creating-tools` en `docs/tools` (auto-descubierta por su `description`; el workflow es **indiferente**, no la bindea).
 
 ## Inherits
 
@@ -55,9 +52,9 @@ Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
 
 ## Composes
 
-`git` (rama segura + commits propuestos) · `tools` (herramientas reusables → `docs/tools`) · `sql` (regla BD). Todas resueltas por `.workflow/skills.toml`; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta.
+`git` (rama segura + commits propuestos) · `sql` (regla BD). Ambas resueltas por `.workflow/skills.toml`; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta.
 
-> **Convenciones ambientes (no roles).** Los estándares de código, testing y redacción **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Una familia útil vive en el plugin `dev-conventions` del marketplace, pero el workflow **no depende** de él.
+> **Convenciones ambientes (no roles).** Los estándares de código, testing, redacción **y la creación de herramientas** (`creating-tools`) **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Familias útiles viven en plugins del marketplace (`dev-conventions`, `tool-builder`), pero el workflow **no depende** de ellos.
 
 ## Internal sessions (managed)
 
@@ -120,7 +117,7 @@ plan-exec-loop(PPP-plan-<slug>.md):
         si no coincide → pausar + resolver con humano
       ejecutar Task:
         editar código en las fuentes (cambio mínimo)
-        si crea herramienta/utilidad reusable → docs/tools (salida directa)
+        si crea herramienta/utilidad → la skill ambiente creating-tools la documenta en docs/tools
         si consulta BD read-only → SCRIPTS.sql + ejecutar read-only
         si cambio BD (DDL/DML) → redactar en SCRIPTS.sql (artefacto session, NO ejecutar)
         si decisión no obvia → DECISION (etiquetado por fase/tarea, en el ÚNICO DECISION)

package/skills/w/loops/quick-loop/SKILL.md

@@ -50,7 +50,7 @@ QUICK
 
 `git` · `sql` (regla BD) · `research` (inline). Resueltas por `.workflow/skills.toml`.
 
-> **Convenciones ambientes (no roles).** Los estándares de código, testing y redacción **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Una familia útil vive en el plugin `dev-conventions` del marketplace, pero el workflow **no depende** de él.
+> **Convenciones ambientes (no roles).** Los estándares de código, testing, redacción **y la creación de herramientas** (`creating-tools`) **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Familias útiles viven en plugins del marketplace (`dev-conventions`, `tool-builder`), pero el workflow **no depende** de ellos.
 
 ## Delta QUICK — minimal ceremony
 

package/skills/w/loops/spec-refine-loop/SKILL.md

@@ -72,6 +72,15 @@ El objetivo persistente necesita una **condición de término checkable** — si
 
 > El **convergence gate** (sección *Convergence / exit*) es, operacionalmente, **"todos los `Success criteria` en verde"**. Los gates por-heir (analyze gate, coherencia del plan, validación final, validación puntual proporcional) son **instancias** de esto, con los criterios sembrados al inicio.
 
+**Integridad del gate (anti-gaming + verificación independiente).** El gate solo vale si no se hace trampa para pasarlo. El loop **no**:
+
+- modifica el check ni afloja un `Success criterion` para forzar verde;
+- debilita, borra ni saltea tests/validaciones;
+- usa asserts triviales o tautológicos que siempre pasan (el valor esperado sale de una fuente independiente, no del propio output);
+- parchea el test en lugar de arreglar la causa (preferir arreglar producción).
+
+Ante un blocker real **para y lo reporta** (→ `Open questions`/`BACKLOG`) en vez de gamear la métrica. El veredicto cuenta **solo el output del check, no la auto-declaración** del implementador: cuando el deliverable lo justifica, la verificación final la hace una pasada **independiente** (subagente o re-lectura limpia) que no asume correcta la implementación — *only command output counts*.
+
 ## Artifacts as a live log — ciclo artifact-first (chasis — heredado por todos los loops)
 
 El loop trabaja **artifact-first**: el artefacto se **siembra antes** de ejecutar y se **actualiza después**, no solo al cerrar. Cada gap/fase/tarea corre el ciclo de **3 tiempos**:
@@ -116,7 +125,7 @@ El gap **UI sin especificar** (cuando el requerimiento involucra UI; ver *Gap ta
 
 Otras capacidades transversales que el chasis usa siempre: `research` (research **inline**, ver abajo), `sql` (regla BD en research). Todas se resuelven por config; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta. La **prosa del spec** sigue las convenciones de redacción **ambientes** (el host auto-aplica una skill de writing instalada si está presente), no un rol compuesto.
 
-> **Convenciones ambientes (no roles).** Los estándares de código, testing y redacción **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Una familia útil vive en el plugin `dev-conventions` del marketplace, pero el workflow **no depende** de él.
+> **Convenciones ambientes (no roles).** Los estándares de código, testing, redacción **y la creación de herramientas** (`creating-tools`) **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Familias útiles viven en plugins del marketplace (`dev-conventions`, `tool-builder`), pero el workflow **no depende** de ellos.
 
 ## Deliverable schema (el spec, editado in place)
 
@@ -199,6 +208,7 @@ La investigación es **inline**: una actividad **dentro de la session actual del
   - elección de MCP (regla BD) — antes de ejecutar queries;
   - en **convergencia**, acción: `Guardar especificación refinada` | `Preguntar algo más`.
 - **Batching**: agrupar hasta 3 gaps de humano en una sola llamada. Si hay más de 3 pendientes, priorizar (los que desbloquean otros gaps primero) y diferir el resto a la próxima vuelta.
+- **Respuesta recomendada por pregunta**: cada pregunta de contenido lleva **siempre** la respuesta que la IA recomienda — como primera opción (marcada *recomendada*) en `AskUserQuestion`, o señalada en el markdown numerado al degradar. Nunca se pregunta "a secas": el humano ratifica o corrige una propuesta, no parte de cero. La IA recomienda en base a lo investigado (regla ask-vs-research), no por defecto vacío.
 
 ## Sequence
 

package/skills/w/roles/README.md

@@ -8,7 +8,7 @@
 
 ## Capability catalog
 
-All 7 roles, their built-in defaults, their tier, and which loops/exports compose them:
+All 6 roles, their built-in defaults, their tier, and which loops/exports compose them:
 
 | Role | Default built-in | Tier | Composed by |
 |---|---|---|---|
@@ -16,7 +16,6 @@ All 7 roles, their built-in defaults, their tier, and which loops/exports compos
 | `sql` | `sql` | must | inline research · `plan-exec-loop` · `quick-loop` · `export-scripts` |
 | `git` | `git` | must | `plan-exec-loop` · `quick-loop` |
 | `research` | [`research`](research/SKILL.md) | should | all loops (on-demand investigation) |
-| `tools` | [`tools`](tools/SKILL.md) | should | `plan-exec-loop` |
 | `diagrams` | [`diagrams`](diagrams/SKILL.md) | should | `export-diagrams` |
 | `overview` | `workflow` | should | any loop (orientation about the workflow itself) |
 
@@ -24,7 +23,7 @@ All 7 roles, their built-in defaults, their tier, and which loops/exports compos
 - `must` — core to almost every session; built-in always active unless explicitly `off`.
 - `should` — loaded on-demand; active by default but lower priority to override.
 
-> **Convenciones ambientes (no roles).** Los estándares de código, testing y redacción **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Una familia útil vive en el plugin `dev-conventions` del marketplace, pero el workflow **no depende** de él.
+> **Convenciones ambientes (no roles).** Los estándares de código, testing, redacción **y la creación de herramientas** (`creating-tools`) **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Familias útiles viven en plugins del marketplace (`dev-conventions`, `tool-builder`), pero el workflow **no depende** de ellos.
 
 ---
 
@@ -59,7 +58,6 @@ built-in default
 # sql              = "sql"
 # git              = "git"
 # research         = "research"
-# tools            = "tools"
 # diagrams         = "diagrams"
 # overview         = "workflow"
 
@@ -76,7 +74,7 @@ sql              = "off"                # disable the sql capability
 ui-design = "acme/figma-spec"
 ```
 
-`acme/figma-spec` must be installed on the host (e.g. via `skills.sh install acme/figma-spec`). The CLI resolves the skill by name; if not found, it falls back to the built-in default and warns.
+`acme/figma-spec` must be installed on the host (e.g. via `skills.sh install acme/figma-spec`). The binding is **advisory**: the resolver emits the name as-is — it does **not** verify the skill is installed and does **not** auto-fall-back to the built-in default. A typo'd name silently leaves the role bound to a skill that does not exist. Verify the resolution with `aw skills`, which warns when a bound skill is not found in the standard skill roots.
 
 ### Override: disable a capability
 
@@ -115,7 +113,6 @@ ui-design         ui-spec                 built-in
 sql               sql                     built-in
 git               git                     built-in
 research          research                built-in
-tools             tools                   built-in
 diagrams          mermaid-only            global      (~/.workflow/skills.toml)
 overview          workflow                built-in
 ```
@@ -135,7 +132,7 @@ Each `SKILL.md` follows this schema:
 
 | Section | Content |
 |---|---|
-| Frontmatter `name:` | kebab-case; MUST equal the binding name (`research`, `tools`, etc.) |
+| Frontmatter `name:` | kebab-case; MUST equal the binding name (`research`, `diagrams`, etc.) |
 | Frontmatter `description:` | rich description: what + when; drives automatic selection |
 | `## Role` | which capability role this implements (its skills.toml slot) |
 | `## Purpose` | what it does |

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

@@ -1,148 +0,0 @@
----
-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` (estilo: convenciones ambientes del host) |
-| 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, seguir las convenciones de código **ambientes** del host (auto-descubiertas por su `description`; no es un rol del workflow ni se bindea). Si no hay una skill de estándares aplicable, 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-roles/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.