@tacuchi/agent-workflow-cli 12.4.0 → 12.6.0

package/skills/w/commands/fix-git.md

@@ -0,0 +1,33 @@
+---
+description: Resuelve conflictos de un merge en curso para una fuente dada o detectada. Identifica origen (theirs) y destino (ours), analiza la intención de ambos lados y resuelve; pregunta (structured-choice) ante ambigüedad o incoherencia. Git-safe — propone el commit de merge, nunca push/--amend/--no-verify. Transversal (no es flow), sin loop ni session, no toca docs/. Funciona en cualquier repo git, sin workspace inicializado.
+argument-hint: "[<source path | alias>]"
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Edit",
+  ]
+---
+
+# fix-git — resolvedor de conflictos de merge (transversal)
+
+Single-pass, **sin loop ni session**, **no escribe en `docs/`**. Comando **transversal** (no pertenece a SPEC / PLAN / QUICK). **Agnóstico al workspace**: opera sobre cualquier repo git — el `<source>` dado (path o alias), o el cwd — sin requerir `.workflow/`.
+
+## Ejecutar
+
+1. **Detectar + identificar** — corré `aw merge-state [<source>]` (read-only; `--source <alias>` o `--all` si hay workspace; un path directo si no). Del JSON, por repo: `is_merging`, `current_branch` (**destino / ours**), `merge_origin` (**origen / theirs**), `conflicted_files`.
+   - Si **no hay merge en curso** (`is_merging:false`) y el usuario indicó un **target** (p.ej. "merge `<branch>`"): es pedido explícito → `git -C <path> merge <branch>` y seguí. Sin target → informá que no hay merge que resolver y terminá.
+2. **Resolver** — **leé y seguí** la sección ***Resolución de conflictos de merge*** del rol `git` (`../roles/git/SKILL.md`): analizá la intención de cada conflicto (3 versiones `git show :1:/:2:/:3:<file>`, `git log --merge`), resolvé (ours / theirs / combinar / reescribir) y `git add` lo resuelto. Ante **ambigüedad o incoherencia**, preguntá vía *structured-choice* (no inventes la resolución).
+3. **Cerrar** — **proponé** el commit de merge (propose-then-execute, formato canónico, git-safe). Escape: `git merge --abort` tras confirmación del usuario.
+
+> No intentes `Skill: git` — el rol se **lee y se sigue** (es la capacidad que este comando compone). El comando **es** la entrada; la doctrina de conflictos vive en el rol `git`.
+
+## Plan mode
+
+Corré `aw merge-state` (read-only), reportá **origen ↔ destino** y los conflictos por archivo, y describí la **estrategia de resolución** que aplicarías — **sin** editar archivos ni commitear.
+
+## Resources
+
+- Capability: `../roles/git/SKILL.md` (sección *Resolución de conflictos de merge*)
+- CLI: `aw merge-state` (inspector read-only del estado de merge)
+- Design reference: `docs/referencias/workflow-commands/fix-git.md`

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

@@ -1,6 +1,6 @@
 ---
 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>
+argument-hint: <docs/plans/PPP-plan-<slug>.md>
 allowed-tools:
   [
     "Bash",
@@ -12,7 +12,7 @@ allowed-tools:
 
 # 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).
+Arranca o retoma `plan-exec-loop` (Layer 2), que ejecuta el trabajo real fase por fase. El plan (`docs/plans/PPP-plan-<slug>.md`) es un documento vivo que el loop mantiene actualizado (estado de fases y tareas).
 
 ## Ejecutar el loop
 
@@ -25,8 +25,8 @@ Arranca o retoma `plan-exec-loop` (Layer 2), que ejecuta el trabajo real fase po
 
 ## 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).
+- Lee y actualiza `docs/plans/PPP-plan-<slug>.md` (living doc: estado de fases/tareas).
+- Edita código en las fuentes del workspace (una sola sesión de ejecución para el run; la ejecución sigue siendo fase por fase, solo que no hay 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/`.

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

@@ -1,6 +1,6 @@
 ---
-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>
+description: Inicia o retoma el loop de planificación (plan-new-loop) a partir de un spec. Convierte el "qué" (spec) en el "cómo" (plan). Input ideal: docs/specs/NNN-spec-<slug>.md ya refinado.
+argument-hint: <docs/specs/NNN-spec-<slug>.md | prompt>
 allowed-tools:
   [
     "Bash",
@@ -12,16 +12,18 @@ allowed-tools:
 
 # 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).
+Puente SPEC → PLAN. 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`:
+El skill evalúa `$ARGUMENTS` (los specs viven in place — `docs/specs/NNN-spec-<slug>.md`; localizar vía glob `docs/specs/NNN-spec-*.md` o la ruta exacta):
 
-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.
+1. **Spec refinado** (`docs/specs/NNN-spec-<slug>.md` que **ya tiene** `## Refinement decisions` / `## Q&A traceability`) → ideal. Procede directamente a `plan-new-loop`.
+2. **Spec borrador** (mismo archivo, pero **sin** esas dos secciones) → **soft-suggest** correr `/w:spec-refine` primero; planificar sobre un spec sólido produce mejores planes (el usuario puede proceder igual).
 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.
 
+> **Refinado vs borrador** se distingue por la **presencia** de `## Refinement decisions` / `## Q&A traceability` en el spec, no por el nombre del archivo (ya no hay `-refined`).
+
 ## Ejecutar el loop
 
 `plan-new-loop` **no** es una skill invocable por nombre — es el manual de operación de este comando (un doc hermano del bundle). **Cargalo y ejecutalo de punta a punta**:
@@ -33,7 +35,7 @@ El skill evalúa `$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.
+El plan se nombra `docs/plans/PPP-plan-<slug>.md`. El CLI solo devuelve el número `PPP`; el loop arma el nombre completo (slug = kebab-case corto del Requirement: `[a-z0-9-]`, ≤ ~5 palabras / ≤ 40 chars). **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
 

package/skills/w/commands/quick.md

@@ -12,7 +12,7 @@ allowed-tools:
 
 # 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).
+Para tareas acotadas y directas que no justifican pasar por SPEC ni PLAN. Siempre crea una sesión ligera (trazabilidad + resume). Delega a `quick-loop` (Layer 2).
 
 ## Ejecutar el loop
 

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

@@ -1,5 +1,5 @@
 ---
-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.
+description: Genera un borrador de especificación (docs/specs/NNN-spec-<slug>.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:
   [
@@ -11,23 +11,24 @@ allowed-tools:
 
 # 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.
+Genera `docs/specs/NNN-spec-<slug>.md` en una sola pasada a partir del prompt en `$ARGUMENTS`. No arranca loop.
 
 > ## ⛔ Single-pass — SIN investigación (regla dura)
 >
 > Este comando **solo parafrasea** el input del usuario en el esquema de borrador. Es **una única pasada secuencial**: leer `$ARGUMENTS` → llenar las secciones → escribir el archivo. Nada más. Debe tardar **segundos, no minutos**.
 >
-> **PROHIBIDO**, sin excepción: lanzar workflows, subagentes (`Task`/`Agent`), sesiones de research, búsquedas web, o investigación profunda de código. No uses las tools `Workflow`, `Task` ni `Agent` aquí.
+> **PROHIBIDO**, sin excepción: lanzar sub-agentes/workflows (`Task`/`Agent`/`Workflow`), sesiones de research, búsquedas web, o investigación profunda de código — **incluso si el arnés está en un modo de máximo esfuerzo/profundidad** (ej. ultracode/max-effort en Claude Code).
 >
-> Esto **anula** cualquier modo o instrucción de sesión que diga "corre un workflow para toda tarea sustancial" (ultracode, max-effort, etc.). Esos modos **no aplican** a `spec-new`: el comando los pisa. Si una sección queda incierta, **no la investigues** — declarala en `## Open questions` o `## Assumptions` y seguí.
+> Esto **anula** cualquier modo o instrucción de sesión que diga "corre un workflow para toda tarea sustancial". Esos modos **no aplican** a `spec-new`: el comando los pisa. Si una sección queda incierta, **no la investigues** — declarala en `## Open questions` o `## Assumptions` y seguí.
 >
 > La investigación a profundidad (cerrar gaps, mapear código, consultar BD, research autónomo) es trabajo de **`spec-refine`**, no de aquí.
 
-1. Ejecutar `aw next-number docs/specs` para obtener `NNN` (única tool de shell necesaria).
-2. Crear `docs/specs/NNN-spec.md` parafraseando `$ARGUMENTS` en el esquema de borrador (ver abajo). Lectura del repo: opcional y mínima (p. ej. un archivo que el usuario citó) — nunca un barrido ni research.
-3. Mostrar el archivo generado y el próximo paso sugerido (`/w:spec-refine docs/specs/NNN-spec.md`).
+1. Ejecutar `aw next-number docs/specs` para obtener `NNN` (única tool de shell necesaria). El CLI solo devuelve el número; el slug lo arma este comando.
+2. Derivar el `<slug>`: kebab-case corto del Requirement — solo `[a-z0-9-]`, ≤ ~5 palabras / ≤ 40 chars.
+3. Crear `docs/specs/NNN-spec-<slug>.md` parafraseando `$ARGUMENTS` en el esquema de borrador (ver abajo). Lectura del repo: opcional y mínima (p. ej. un archivo que el usuario citó) — nunca un barrido ni research.
+4. Mostrar el archivo generado y el próximo paso sugerido (`/w:spec-refine docs/specs/NNN-spec-<slug>.md`).
 
-## Esquema del borrador (`NNN-spec.md`)
+## Esquema del borrador (`NNN-spec-<slug>.md`)
 
 ```markdown
 # Spec NNN — <slug>
@@ -46,22 +47,25 @@ Sistemas / componentes / fuentes involucradas. Restricciones conocidas.
 - Out: qué NO entra
 
 ## Acceptance criteria
-- [ ] criterio verificable 1
+- [ ] criterio verificable 1 (estilo EARS / Given-When-Then recomendado)
 - [ ] criterio verificable 2
 
-## Open questions
-Dudas pendientes. ← el spec-refine-loop las va cerrando.
-
 ## Assumptions       (opt.)
 Supuestos asumidos.
+
+## Open questions
+Dudas pendientes. ← el spec-refine-loop las va cerrando.
 ```
 
+> **`Open questions` va último** — el spec refinado **inserta antes de `Open questions`** `## UI spec` (si hay UI) + `## Refinement decisions` + `## Q&A traceability` (esquema refinado en el [`spec-refine-loop`](../loops/spec-refine-loop/SKILL.md)). Mismo esqueleto: el borrador y el refinado comparten orden.
+
 **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`.
+- **Acceptance criteria = criterios testables estáticos** (el "qué"): `plan-exec` los valida pero el avance se trackea en el PLAN (sus Tasks), no marcando estos `- [ ]` en el spec; el spec no muta por ejecución, solo por re-refine.
+- Si hay **UI** involucrada, mencionarlo en `Requirement`/`Context`; el `## UI spec` se autora en `spec-refine` (vía capacidad `ui-design`). "UI sin especificar" es un gap de primera clase del refinamiento.
+- Los **gaps** que detecta el loop = secciones débiles del esquema (Requirement vago, Scope sin `Out`, criterios no testables, Open questions abiertas, supuestos no declarados, contradicciones) **+ UI sin especificar** si el requerimiento involucra UI.
+- Alternativa equivalente: el usuario crea el borrador a mano. Ambos caminos producen el mismo `docs/specs/NNN-spec-<slug>.md`.
 
 ## Plan mode
 

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

@@ -1,6 +1,6 @@
 ---
-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>
+description: Inicia o retoma el loop de refinamiento de una especificación (spec-refine-loop). Input: docs/specs/NNN-spec-<slug>.md (borrador). Actualiza docs/specs/NNN-spec-<slug>.md in place.
+argument-hint: <docs/specs/NNN-spec-<slug>.md>
 allowed-tools:
   [
     "Bash",
@@ -25,12 +25,14 @@ Este comando no refina el spec él mismo: delega al loop `spec-refine-loop` (Lay
 
 ## Resolución de estado (resumable)
 
-El skill detecta el estado previo antes de arrancar:
+El skill detecta el estado previo antes de arrancar, **keyando off el `CHECKPOINT`** (no la existencia de un archivo "refined"):
 
 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.
+3. **Sin avance** (sin CHECKPOINT y el spec **no** tiene `## Refinement decisions`/`## Q&A traceability`) → arranca desde cero leyendo el spec (`NNN-spec*.md`).
+4. **Ya refinado** (sin CHECKPOINT abierto pero el spec **ya tiene** `## Refinement decisions`/`## Q&A traceability`) → re-refinamiento incremental leyendo el **spec mismo**; al `Guardar`, edita in place con confirmación.
+
+> **Compat (legacy):** el glob `NNN-spec*.md` también captura specs viejos `NNN-spec.md` / `NNN-spec-refined.md`. Re-correr spec-refine los edita in place de ahí en adelante.
 
 ## Plan mode
 

package/skills/w/commands/status.md

@@ -0,0 +1,50 @@
+---
+description: Dashboard read-only del workspace — qué se hizo / qué falta / qué se descartó, con fechas en español (hace 2 días, ayer en la mañana). Se apoya en `aw status`. Comando transversal (no es un flow); no escribe nada.
+argument-hint: (sin argumentos)
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+  ]
+---
+
+# status — estado del workspace (read-only)
+
+Muestra, simple y directo, el estado del workspace agrupado en **Hecho / Falta / Descartó**. Single-pass, read-only: no abre loop, no crea sesiones, no escribe en `docs/` ni en `.workflow/`. Comando **transversal** (no pertenece a ningún flow).
+
+## Ejecutar
+
+1. Corré `aw status` (devuelve JSON; se apoya en `status-service`).
+2. Renderizá un resumen legible a partir del JSON — **no** muestres el JSON crudo. Usá el campo `relative` tal cual (ya viene humanizado en español). Encabezá con `workspace.name`.
+3. Agrupá en tres bloques:
+   - **▸ HECHO** — specs con `refined: true`; plans con su progreso (`tasks_done`/`tasks_total`, `progress_pct`); sesiones `closed`.
+   - **▸ FALTA** — sesiones `active`; plans con tareas pendientes (`tasks_total − tasks_done`); specs con `open_questions > 0`.
+   - **▸ DESCARTÓ** — cada item de `discarded[]` (`kind: deferred` = diferido en BACKLOG; `kind: excluded` = excluido en CHECKPOINT), con su `text`.
+4. Cada línea termina con su fecha relativa tras ` · ` (ej. `· ayer en la mañana`). Si una sección queda vacía, mostrá `— (nada)`. No inventes datos que no estén en el JSON.
+5. Si `workspace.initialized` es `false` y todo está vacío → decí "No es un workspace de agent-workflow (no hay `.workflow/`)" y sugerí `/w:workspace-init`.
+
+Formato sugerido (texto plano):
+
+```
+Workspace: <name>
+
+▸ HECHO
+  • plan <slug> — <done>/<total> tareas (<pct>%) · <relative>
+  • spec <slug> — refinado · <relative>
+  • <folder> (<type>) — cerrada · <relative>
+
+▸ FALTA
+  • <folder> (<type>) — activa · <relative>
+  • plan <slug> — <pendientes> tareas pendientes
+  • spec <slug> — <n> preguntas abiertas
+
+▸ DESCARTÓ
+  • <text> (<kind>) · <relative>
+```
+
+## Plan mode
+Igual que en ejecución: corré `aw status` (read-only) y mostrá el resumen. No hay cambios que aplicar.
+
+## Resources
+- CLI: `aw status` (servicio `status-service`; fechas vía `humanize-es`)
+- Design reference: `docs/referencias/workflow-commands/status.md`

package/skills/w/exports/README.md

@@ -29,14 +29,14 @@
 | [`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.
+> **Composition over ownership:** an export does **not** own its authoring logic — it **composes a capability role** from [`../roles/`](../roles/) (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`).
+4. **No loop, no internal sessions** — options come from **args** (no *structured-choice* de ciclo de vida — capacidad del arnés; ver [`../harness/SKILL.md`](../harness/SKILL.md)).
 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).
 

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

@@ -60,7 +60,7 @@ En plan mode **describe**, no escribe: el motor resuelto, los niveles/secciones
 
 **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`):
+**Args** (sin *structured-choice* de ciclo de vida — capacidad del arnés; ver [`../../harness/SKILL.md`](../../harness/SKILL.md)):
 
 ```
 /w:export-diagrams [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]

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

@@ -60,7 +60,7 @@ En plan mode **describe**, no escribe: el modo resuelto, los temas detectados (c
 - `docs/manuals/INDEX.md` — re-generable (sobrescribible) en modo `complement`.
 - Código de las fuentes declaradas — lectura para describir el comportamiento.
 
-**Args** (sin lifecycle `AskUserQuestion`):
+**Args** (sin *structured-choice* de ciclo de vida — capacidad del arnés; ver [`../../harness/SKILL.md`](../../harness/SKILL.md)):
 
 ```
 /w:export-manuals [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]
@@ -123,5 +123,5 @@ Si `--dry-run`: imprimir el reporte; no escribir. Si no: `complement` → `Write
 
 - Design: `docs/referencias/workflow-exports/export-manuals.md` · familia: [`../README.md`](../README.md).
 - Capacidad compuesta: `writing` (built-in default; ver `docs/referencias/workflow-skills/`).
-- Artefactos fuente: `DECISION` + plan-doc (ver `docs/referencias/workflow-artifacts/artifacts-dev/` y `docs/specs`/`docs/plans`).
+- Artefactos fuente: `DECISION` + plan-doc (ver `docs/referencias/workflow-artifacts/artifacts-exec/` y `docs/specs`/`docs/plans`).
 - Siblings: [`../export-scripts/SKILL.md`](../export-scripts/SKILL.md) · [`../export-diagrams/SKILL.md`](../export-diagrams/SKILL.md) · [`../export-reports/SKILL.md`](../export-reports/SKILL.md).

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

@@ -57,7 +57,7 @@ En plan mode **describe**, no escribe: la audiencia/longitud resuelta, las sesio
 
 - `docs/specs`, `docs/plans`, `docs/reports/*` — contexto + no colisionar.
 
-**Args** (sin lifecycle `AskUserQuestion`):
+**Args** (sin *structured-choice* de ciclo de vida — capacidad del arnés; ver [`../../harness/SKILL.md`](../../harness/SKILL.md)):
 
 ```
 /w:export-reports [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]

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

@@ -58,7 +58,7 @@ En plan mode **describe**, no escribe: el `NNN` resuelto, las fuentes detectadas
 
 - `docs/scripts/*.sql` standalone (solo top-level), **excluyendo** cualquier `docs/scripts/NNN-export-scripts-*/` (outputs previos de este export).
 
-**Args** (sin lifecycle `AskUserQuestion`):
+**Args** (sin *structured-choice* de ciclo de vida — capacidad del arnés; ver [`../../harness/SKILL.md`](../../harness/SKILL.md)):
 
 ```
 /w:export-scripts [--sessions NNN[,NNN]] [--since sessionNNN] [--source <alias>]

package/skills/w/harness/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: harness
+description: >-
+  Harness-agnostic capability layer for agent-workflow. Read-and-follow doc (no es
+  invocable por nombre): define el contrato que mantiene a la herramienta agnóstica al
+  arnés (Claude Code, Codex, opencode, Gemini CLI, genérico) sin renunciar a las
+  capacidades ricas de cada uno. Cataloga las capacidades de las que depende el
+  workflow, las liga al mecanismo concreto de cada arnés (binding matrix), y fija los
+  dos principios (capacidad-no-tool · progressive-enhancement). Referenciado desde
+  SKILL.md (overview) y los loops cuando nombran structured-choice / compaction.
+---
+
+# harness — capa de capacidades agnóstica al arnés (cross-cutting)
+
+Doc de **lectura y seguimiento** (no se invoca por nombre). Aquí vive el contrato que mantiene a agent-workflow **agnóstico al arnés** (Claude Code, Codex, opencode, Gemini CLI, …) sin renunciar a las capacidades ricas de cada uno. Referenciado desde `../SKILL.md` (overview) y desde los loops cuando nombran una capacidad (`structured-choice`, `compaction`, …).
+
+## El problema
+
+La doctrina (comandos + loops + artefactos) describe **qué** hace la IA, no **con qué tool** de un arnés concreto. El vocabulario natural arrastra mecanismos específicos de Claude Code —`AskUserQuestion`, `/compact`, `$ARGUMENTS`, `Task`/`Agent`— como si fueran universales. Este documento los abstrae: la doctrina referencia **capacidades**; aquí se mapea cada capacidad al **mecanismo concreto** de cada arnés.
+
+## Dos principios
+
+1. **Capacidad, no tool.** Los loops/comandos nombran una **capacidad** abstracta (ej. *structured-choice*, *compaction*). Una sola tabla —esta— la liga al mecanismo de cada arnés. Cambiar de arnés = cambiar de columna, no de doctrina.
+2. **Progressive enhancement.** Usá el mecanismo **más rico** que ofrezca el arnés; **degradá** a un fallback universal cuando no exista. Así se cumple a la vez "agnóstica al arnés" **y** "aprovechar las capacidades de cada uno".
+
+> **Simetría con la cascada de skills (`.workflow/skills.toml`):** esa categoría liga **roles → skills** por config; esta liga **capacidades → mecanismos del arnés** por detección. Mismo patrón (binding + default), distinto eje: una es *qué saber compone el loop*, la otra es *con qué primitivas del host se ejecuta*.
+
+## Capability catalog
+
+Las capacidades de las que depende el harness, con su fallback universal (lo que se usa si el arnés no ofrece algo mejor):
+
+| Capability | Qué necesita el workflow | Fallback universal (mínimo común) |
+|---|---|---|
+| **command-invocation** | el usuario dispara un flujo por nombre (`spec-new`, `plan-exec`, …) | el usuario escribe "corré el procedimiento `<cmd>`" y la IA lee su doc |
+| **procedure-loading** | cargar la doctrina de un loop/comando | la IA **lee el `.md`** del loop y lo sigue (read-and-follow) |
+| **structured-choice** | preguntar al humano ≤3 preguntas de contenido **+ siempre** un control `flow` (`Compactar`/`Cerrar`) por un canal lateral | pregunta en **markdown numerado** en el chat; el control `flow` se ofrece como una opción más |
+| **compaction** | encoger el contexto sin perder el hilo | escribir `CHECKPOINT` y pedir al usuario reiniciar el contexto y reanudar (resume keya off `CHECKPOINT`) |
+| **subagent-dispatch** | *(opcional)* paralelizar breadth de research | research **inline secuencial** en la misma session (es el default igual) |
+| **persistent-context** | bloque `WORKSPACE` + convenciones siempre presentes | archivo de contexto del repo (**`AGENTS.md`** estándar; `CLAUDE.md` en Claude Code) |
+| **external-data** | lecturas read-only de BD u otras fuentes para research/validación | **MCP** (ampliamente soportado); si no hay, el gap se degrada a pregunta-al-humano |
+| **dry-run / preview** | previsualizar lo que haría un comando sin escribir | el comando **describe** el cambio en vez de aplicarlo (ej. `spec-new` lista el borrador sin crear el archivo) |
+
+> **Las capacidades `must` para el ciclo de un loop son solo dos**: `structured-choice` y `compaction`. Ambas degradan a un fallback puramente textual → **cualquier** arnés con chat + sistema de archivos corre el modelo completo. El resto (subagents, MCP, slash commands, skills nativas) es *enhancement*.
+
+## Harness binding matrix
+
+Mecanismo concreto por arnés (jun-2026; `~` parcial · `?` sin confirmar).
+
+| Capability | Claude Code | Codex CLI | opencode | Gemini CLI | Genérico |
+|---|---|---|---|---|---|
+| command-invocation | `.claude/commands/` (slash) | skills (prompts custom **deprecados**) | `.opencode/commands/` | `.gemini/commands/*.toml` | texto |
+| procedure-loading | skills `SKILL.md` | skills `SKILL.md` | skills `SKILL.md` | skills (extensiones) | read-and-follow `.md` |
+| structured-choice | `AskUserQuestion` (**solo main-agent**) | — | — | — | markdown numerado |
+| compaction | `/compact` | `?` | `?` | `?` | CHECKPOINT + resume |
+| subagent-dispatch | `Task` (paralelo) | agents (depth=1) | Explore/Scout | agents | inline |
+| persistent-context | `CLAUDE.md` (**no** lee AGENTS.md → symlink) | `AGENTS.md` | `AGENTS.md` | `AGENTS.md`/`GEMINI.md` | `AGENTS.md` |
+| external-data | MCP | MCP | MCP | MCP | — |
+| dry-run / plan | plan mode (enforced) | `/plan` (prompt, **no** enforced) | Plan agent | plan mode | describir sin escribir |
+
+> **Notas (investigación de campo jun-2026):** las **skills `SKILL.md`** son la unidad portable **universal** (las cinco las soportan; Codex deprecó los prompts custom) → la doctrina se empaqueta como skill. La **elección estructurada** (`AskUserQuestion`) es **solo de Claude Code y solo del main-agent** → en el resto, `structured-choice` degrada a markdown numerado. El **plan mode** está *enforced* solo en Claude Code/opencode (prompt-level en Codex) → **no se confía para safety**; el git-safe (invariante #5) es propio. **MCP** es universal. El **piso garantizado** (última columna) corre el modelo completo.
+
+## Leverage installed skills
+
+"Aprovechar las skills que el arnés tenga instaladas" se resuelve por el **mismo binding** de `.workflow/skills.toml`: un rol puede apuntar a una skill **instalada en el host** (de tercero, vía skills.sh) en vez del built-in. Regla:
+
+- Si el host tiene una skill **mejor** para un rol (ej. un generador de diagramas superior para `diagrams`, un linter de estándares para `coding-standards`), se la **bindea** en `.workflow/skills.toml` y el loop la compone sin cambios.
+- El built-in default es el **piso**, no el techo: garantiza que el rol funcione en cualquier host; el binding lo **enriquece** donde el host puede más.
+
+## Convención para el resto del corpus
+
+- Los loops/comandos referencian la **capacidad** por nombre (ej. "*structured-choice* (ver `harness/SKILL.md`)"), **no** el tool concreto.
+- El nombre histórico `AskUserQuestion` se conserva **solo** como el binding Claude-Code de `structured-choice` (esta tabla), no como vocabulario de la doctrina.
+- El control de ciclo de vida `flow` (`Compactar`/`Cerrar`) es parte de la capacidad `structured-choice`, no de un tool: en arneses sin elección estructurada se ofrece como una opción textual más.
+
+## Distribution (install-time)
+
+Patrón probado (Spec Kit, 30+ agentes): **una fuente canónica** + generar/symlinkear a los dirs por-arnés en la instalación (`.claude/`, `.codex/`, `.gemini/`, …). agent-workflow ya lo hace vía `aw self install-skill`. Convención recomendada: **`AGENTS.md` canónico + `CLAUDE.md` symlink** (Claude Code no lee `AGENTS.md` nativo; el resto sí).
+
+## Command packaging (harness-specific)
+
+El **contrato** de cada comando (Flow, Trigger, Input, Mode, …) es agnóstico. El **archivo** que el arnés ejecuta envuelve ese contrato en su formato nativo: Claude Code = slash-command con frontmatter (`description`, `argument-hint`, `allowed-tools`) + cuerpo que invoca la skill o el `aw` CLI; Codex = skill (los prompts custom en `~/.codex/prompts/` están deprecados); otros, su equivalente. El contrato no cambia; el envoltorio sí (otra columna). El comportamiento en *dry-run / plan mode* (previsualizar sin escribir) se documenta en el cuerpo del comando cuando aplica.
+
+## Status
+
+Modelo de capacidades + matriz de binding **definidos** y **validados** con investigación de campo (jun-2026). El piso universal (`AGENTS.md` + texto + archivos + skills) corre el modelo completo hoy.

package/skills/w/loops/README.md

@@ -13,28 +13,28 @@ Un loop es una **skill** que le enseña a la IA *cómo iterar* hasta producir un
 Propiedades comunes a **los 4 loops**:
 
 1. **Gap-driven convergente** — cada ciclo: `detect_gaps` → resolver (humano o research) → integrar → repetir hasta que no queden gaps materiales. Los gaps "agotados" (límite `MAX` de intentos) no se re-disparan → garantiza convergencia.
-2. **Puede crear sessions internas** — si refinar/planificar/ejecutar requiere trabajo profundo (ej. investigar el código), el loop crea una session en `.workflow/sessions/` que maneja **sus** artefactos, la cierra y reporta de vuelta. **El usuario nunca crea esas sessions.**
-3. **AskUserQuestion con dos tipos de tab** (límite host: 4 preguntas/llamada):
-   - **tab(s) de contenido** (≤3) — la(s) pregunta(s) real(es) del momento (resolver una duda, elegir MCP, o en convergencia: `Guardar` / `Preguntar algo más`).
-   - **tab `flow`** (1, SIEMPRE presente) — control de ciclo de vida por un canal lateral. Así el contenido lo maneja la IA y el ciclo de vida lo dirige el humano.
+2. **Una sola session por run + research inline** — el loop crea **una** session en `.workflow/sessions/` (la dueña del run) y maneja **sus** artefactos. La **investigación es inline**: una actividad dentro de esa misma session que escribe `ANALYSIS-FILE`/`CONCLUSIONS` (+ `SCRIPTS.sql` read-only si consulta BD) en su propia carpeta — ya no es una session aparte. **El usuario nunca crea sessions.** Los artefactos son el **registro vivo** del run — **ciclo artifact-first**: sembrar `CHECKPOINT.Pending/Next` (la intención) antes de ejecutar, llevar a `Completed`/DECISION después; CHECKPOINT actualizado en cada límite de gap/fase, BACKLOG solo si difiere. El spec/plan es la base guía.
+3. **Structured-choice con dos planos** (capacidad del arnés — ver [`../harness/SKILL.md`](../harness/SKILL.md); en **Claude Code** es `AskUserQuestion`, máx 4 preguntas/llamada → **≤3 + 1 control `flow`**; sin elección estructurada degrada a markdown numerado):
+   - **pregunta(s) de contenido** (≤3) — la(s) pregunta(s) real(es) del momento (resolver una duda, elegir MCP, o en convergencia: `Guardar` / `Preguntar algo más`).
+   - **control `flow`** (1, SIEMPRE presente) — control de ciclo de vida por un canal lateral. Así el contenido lo maneja la IA y el ciclo de vida lo dirige el humano.
 4. **Escribe solo en su propia carpeta `docs/`** — y **nunca** gradúa/exporta otros artefactos a `docs/`. Esa promoción la hacen las skills `export-*`, aparte y explícita.
 
-## flow tab — options
+## flow control — options
 
-El tab `flow` es **fijo**: `Compactar` / `Cerrar`, presente en los 4 loops. Responder el tab de contenido **sin tocar `flow`** = seguir iterando ("continuar" es el comportamiento por defecto del loop, no una opción del canal de control).
+El control `flow` es **fijo**: `Compactar` / `Cerrar`, presente en los 4 loops. Responder la pregunta de contenido **sin tocar `flow`** = seguir iterando ("continuar" es el comportamiento por defecto del loop, no una opción del canal de control).
 
 | Option | What it does |
 |---|---|
-| `Compactar` | Escribe `CHECKPOINT` (session dueña del run) + dispara `/compact` del host y reanuda sin perder el hilo. |
-| `Cerrar` | `finalize`: persiste lo pendiente (`CHECKPOINT` + `BACKLOG`), cierra sessions internas y termina el loop. |
+| `Compactar` | Escribe `CHECKPOINT` (session dueña del run) + dispara la **compactación** del arnés (en Claude Code: `/compact`; ver [`../harness/SKILL.md`](../harness/SKILL.md)) y reanuda sin perder el hilo. |
+| `Cerrar` | `finalize`: persiste lo pendiente (`CHECKPOINT` siempre; `BACKLOG` solo si hay algo diferido), cierra la session y termina el loop. |
 
 ## Loops and their flow
 
 | Loop (`name:`) | Flow | Started by | Reads | Writes |
 |---|---|---|---|---|
-| [`spec-refine-loop`](spec-refine-loop/SKILL.md) | SPEC | `/w:spec-refine` | `docs/specs/NNN-spec.md` (o `…-spec-refined.md` si ya existe) | `docs/specs/NNN-spec-refined.md` |
-| [`plan-new-loop`](plan-new-loop/SKILL.md) | PLANIFICATION | `/w:plan-new` | `docs/specs/NNN-spec-refined.md` | `docs/plans/PPP-plan.md` |
-| [`plan-exec-loop`](plan-exec-loop/SKILL.md) | PLANIFICATION | `/w:plan-exec` | `docs/plans/PPP-plan.md` | `docs/plans/PPP-plan.md` (update) + `docs/tools`; resto vía `export-*` |
+| [`spec-refine-loop`](spec-refine-loop/SKILL.md) | SPEC | `/w:spec-refine` | `docs/specs/NNN-spec*.md` (el spec mismo) | `docs/specs/NNN-spec-<slug>.md` (in place) |
+| [`plan-new-loop`](plan-new-loop/SKILL.md) | PLAN | `/w:plan-new` | `docs/specs/NNN-spec-*.md` | `docs/plans/PPP-plan-<slug>.md` |
+| [`plan-exec-loop`](plan-exec-loop/SKILL.md) | PLAN | `/w:plan-exec` | `docs/plans/PPP-plan-*.md` | `docs/plans/PPP-plan-<slug>.md` (update) + `docs/tools`; resto vía `export-*` |
 | [`quick-loop`](quick-loop/SKILL.md) | QUICK | `/w:quick` | — (prompt) | edita código + session ligera; **no** `docs/` |
 
 > `/w:spec-new` no tiene loop (es single-pass). Por eso hay **5 comandos / 4 loops**.
@@ -46,14 +46,14 @@ Los loops **nunca** graduan/exportan artefactos a `docs/` automáticamente. Cada
 | Flow | Carpetas `docs/` que escribe |
 |---|---|
 | SPEC | `docs/specs` |
-| PLANIFICATION | `docs/plans` (living) + `docs/tools` (herramientas creadas — salida directa) |
+| PLAN | `docs/plans` (living) + `docs/tools` (herramientas creadas — salida directa) |
 | QUICK | ninguna |
 
 Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, diagramas → `docs/diagrams`, informes → `docs/reports`) queda como **artefacto de session** hasta que un `export-*` lo promueva, como paso aparte y explícito.
 
-## Loops × flow tab
+## Loops × flow control
 
-| Loop | tab(s) de contenido típicos | tab `flow` |
+| Loop | pregunta(s) de contenido típicas | control `flow` |
 |---|---|---|
 | `spec-refine-loop` | dudas-de-humano · elección de MCP · convergencia (`Guardar especificación refinada` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
 | `plan-new-loop` | dudas · elección de MCP · convergencia (`Guardar plan` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
@@ -64,7 +64,7 @@ Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, dia
 
 | Field | Description |
 |---|---|
-| `## Flow` | A qué flujo pertenece (SPEC · PLANIFICATION · QUICK) |
+| `## Flow` | A qué flujo pertenece (SPEC · PLAN · QUICK) |
 | `## Layer` | Siempre 2 (la IA lo corre entero) |
 | `## Started by` | Comando `/w:…` que lo arranca (reanudable) |
 | `## Reads` | Documento(s) de entrada |
@@ -73,19 +73,20 @@ Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, dia
 | `## Sequence` | Pseudocódigo + mermaid del loop |
 | `## Convergence / exit` | Cuándo para |
 
-El **chasis** (`spec-refine-loop`) además detalla `## Composes` (capacidades que compone), `## Deliverable schema`, `## Gap taxonomy`, `## Ask-vs-research rule`, `## Research: autonomy, scope & failure`, `## AskUserQuestion`, `## Compact / resume`, `## Integration`.
+El **chasis** (`spec-refine-loop`) además detalla `## Composes` (capacidades que compone), `## Deliverable schema`, `## Gap taxonomy`, `## Ask-vs-research rule`, `## Research: autonomy, scope & failure`, `## Structured-choice`, `## Compact / resume`, `## Integration`.
 
 Los **heirs** (`plan-new-loop`, `plan-exec-loop`, `quick-loop`) usan `## Inherits` (lo que reusan del chasis, sin repetirlo) + `## Delta N` (sus diferencias).
 
 ## Chassis / heirs
 
 ```
-spec-refine-loop  ── CHASIS (patrón de referencia: motor gap-driven, sessions,
-        │            AskUserQuestion + tab flow, research autónomo + regla BD,
-        │            compact/resume, Cerrar persiste CHECKPOINT+BACKLOG)
+spec-refine-loop  ── CHASIS (patrón de referencia: motor gap-driven, sesión única,
+        │            structured-choice + control flow, research autónomo INLINE + regla BD,
+        │            compact/resume, artefactos como log vivo: CHECKPOINT siempre,
+        │            BACKLOG solo si difiere)
         ├── plan-new-loop   (heir)  → deltas: plan rico, gap taxonomy de plan
         ├── plan-exec-loop  (heir)  → deltas: ejecución real (código/BD/git),
-        │                              session por fase, sin auto-export
+        │                              una sola session por run, sin auto-export
         └── quick-loop      (heir)  → deltas: ceremonia mínima, 1 session,
                                        hereda git/BD/no-export de plan-exec
 ```
@@ -103,7 +104,7 @@ Los loops componen **capacidades por su rol**, no skills concretas; la skill que
 | `git` | `git` | `plan-exec-loop` · `quick-loop` |
 | `coding-standards` | `coding-standards` | `plan-exec-loop` · `quick-loop` |
 | `writing` | `writing` | todos los loops |
-| `research` | `research` | todos los loops (research on-demand) |
+| `research` | `research` | todos los loops (research inline) |
 | `testing` | `testing` | `plan-exec-loop` · `quick-loop` |
 | `tools` | `tools` | `plan-exec-loop` |
 | `overview` | `workflow` | cualquiera (orientación) |