@tacuchi/agent-workflow-cli 14.1.1 → 14.3.0

package/skills/w/loops/README.md

@@ -10,7 +10,7 @@
 
 Un loop es una **skill** que le enseña a la IA *cómo iterar* hasta producir un entregable. **No es invocable por nombre** con el tool `Skill` (no se registra como skill suelta): es el cuerpo de su comando `/w:…`, que lo **carga leyendo `<loop>/SKILL.md`** y lo ejecuta inline. La IA lo corre de punta a punta: detecta huecos, los resuelve (preguntando al humano o investigando), integra y repite hasta converger.
 
-Propiedades comunes a **los 4 loops**:
+Propiedades comunes a **los 5 loops**:
 
 1. **Objetivo persistente + verification-first** — el loop persigue su `SESSION.Objective` y solo finaliza cuando sus `SESSION.Success criteria` están **en verde** (o el humano aborta vía `flow` `Cerrar`). Esos criterios —la condición de término— se **siembran al inicio** (*verification-first*, TDD generalizado: tests ejecutables para código, rúbrica falsable para análisis/diseño), no se improvisan al final. Modelado en el `/goal` de Claude Code pero como **doctrina agnóstica** (sin depender de ningún host) y con registro durable. El "no parar hasta converger" es del loop, no del arnés. **Entre turnos**, el mismo `CHECKPOINT`+resume hace que un prompt **sin comando** **continúe/reabra la sesión más reciente** en vez de arrancar trabajo suelto — la cara *inter-turno* del objetivo persistente (ver [`../SKILL.md`](../SKILL.md) § *Contexto operativo*).
 2. **Gap-driven convergente** — el *cómo* del objetivo persistente: 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.
@@ -22,7 +22,7 @@ Propiedades comunes a **los 4 loops**:
 
 ## flow control — options
 
-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).
+El control `flow` es **fijo**: `Compactar` / `Cerrar`, presente en los 5 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 |
 |---|---|
@@ -35,10 +35,11 @@ El control `flow` es **fijo**: `Compactar` / `Cerrar`, presente en los 4 loops.
 |---|---|---|---|---|
 | [`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-refine-loop`](plan-refine-loop/SKILL.md) | PLAN | `/w:plan-refine` *(aux, opcional)* | `docs/plans/PPP-plan-*.md` (el plan mismo) | `docs/plans/PPP-plan-<slug>.md` (in place) |
 | [`plan-exec-loop`](plan-exec-loop/SKILL.md) | PLAN | `/w:plan-exec` | `docs/plans/PPP-plan-*.md` | `docs/plans/PPP-plan-<slug>.md` (update); 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**.
+> `/w:spec-new` no tiene loop (es single-pass). Por eso hay **6 comandos / 5 loops**.
 
 ### `docs/` boundary (regla dura)
 
@@ -58,6 +59,7 @@ Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, dia
 |---|---|---|
 | `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` |
+| `plan-refine-loop` | dudas · elección de MCP · convergencia (`Guardar plan refinado` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
 | `plan-exec-loop` | decisiones/dudas no obvias · elección de MCP · cierre (`Marcar plan done` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
 | `quick-loop` | dudas no obvias · escalar a SPEC/PLAN · cierre (`Cerrar tarea` / `Preguntar algo más`) | `Compactar` / `Cerrar` |
 
@@ -76,7 +78,7 @@ Todo lo demás (migraciones → `docs/scripts`, manuales → `docs/manuals`, dia
 
 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).
+Los **heirs** (`plan-new-loop`, `plan-refine-loop`, `plan-exec-loop`, `quick-loop`) usan `## Inherits` (lo que reusan del chasis, sin repetirlo) + `## Delta N` (sus diferencias).
 
 ## Chassis / heirs
 
@@ -85,11 +87,13 @@ spec-refine-loop  ── CHASIS (patrón de referencia: objetivo persistente + v
         │            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),
-        │                              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
+        ├── plan-new-loop    (heir)  → deltas: plan rico, gap taxonomy de plan
+        ├── plan-refine-loop (heir)  → deltas: refina el plan in place (aux, opcional);
+        │                               reusa gap taxonomy + coherence gate de plan-new
+        ├── plan-exec-loop   (heir)  → deltas: ejecución real (código/BD/git),
+        │                               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
 ```
 
 El chasis **no es una capacidad bindeable**: *es* `spec-refine-loop` y los demás loops lo heredan. Lo enchufable son las **capacidades** que un loop compone (ej. `ui-design`, `sql`, `git`), resueltas por `.workflow/skills.toml`.
@@ -114,5 +118,6 @@ Los loops componen **capacidades por su rol**, no skills concretas; la skill que
 
 - [`spec-refine-loop/SKILL.md`](spec-refine-loop/SKILL.md) — el chasis
 - [`plan-new-loop/SKILL.md`](plan-new-loop/SKILL.md)
+- [`plan-refine-loop/SKILL.md`](plan-refine-loop/SKILL.md) — aux, opcional (refina el plan in place)
 - [`plan-exec-loop/SKILL.md`](plan-exec-loop/SKILL.md)
 - [`quick-loop/SKILL.md`](quick-loop/SKILL.md)

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

@@ -30,7 +30,7 @@ PLAN
 `/w:plan-exec` — **reanudable** (mismo mecanismo del chasis; aquí el resume keya off el checkbox del plan-doc + CHECKPOINT, ver Delta 1).
 
 ## Reads
-`docs/plans/PPP-plan-<slug>.md` (localizar vía glob `docs/plans/PPP-plan-*.md` o la ruta exacta del argumento del comando).
+`docs/plans/PPP-plan-<slug>.md` (localizar vía glob `docs/plans/PPP-plan-*.md` o la ruta exacta del argumento del comando). Corre **cualquier** plan, haya pasado o no por [`plan-refine-loop`](../plan-refine-loop/SKILL.md) — plan-refine es auxiliar y no obligatorio; no hay gate que lo exija.
 
 ## Writes
 - `docs/plans/PPP-plan-<slug>.md` (**read/update**, living doc: estado de fases/tareas, `Open questions`).

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

@@ -101,3 +101,5 @@ El research **inline** del chasis se especializa: mapear **código/impacto** —
 ## Convergence / exit
 
 Sin gaps materiales → **coherence gate** (read-only) = **`Success criteria` en verde** (*verification-first*; es el "convergence gate" del chasis para PLAN-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`. Lo que falle **vuelve como gap** — la trazabilidad criterio→tarea es una **invariante chequeada**, no una sección aparte. Si pasa → *structured-choice* (contenido: `Guardar plan` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, escribe `docs/plans/PPP-plan-<slug>.md` (con confirmación si existe) → `finalize` (persiste `CHECKPOINT`, y `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.
+
+> **Después de generar:** el plan puede ir directo a `plan-exec`, o —si surgen cambios antes de ejecutar (nuevos requerimientos, ajustes de alcance)— pasar por [`plan-refine-loop`](../plan-refine-loop/SKILL.md) (`/w:plan-refine`, auxiliar y **no obligatorio**), que lo refina in place.

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

@@ -0,0 +1,94 @@
+---
+name: plan-refine-loop
+description: >-
+  Refina un plan existente (docs/plans/PPP-plan-<slug>.md) editándolo IN PLACE,
+  como paso auxiliar y NO obligatorio del flujo PLAN antes de plan-exec. Heir del
+  chasis spec-refine-loop: reusa íntegro su motor gap-driven convergente, su única
+  session por run, research INLINE, structured-choice con ≤3 preguntas de contenido
+  + 1 control flow (Compactar/Cerrar) siempre, research autónomo con regla BD
+  read-only, y artefactos como log vivo (CHECKPOINT siempre, BACKLOG solo si
+  difiere). Es a plan-new lo que spec-refine es a spec-new: edita el plan-doc in
+  place (no genera uno nuevo). Reusa la gap taxonomy y el coherence gate de
+  plan-new-loop; agrega Refinement decisions/Q&A traceability al plan (traza, sin
+  contrato de gating: plan-exec corre cualquier plan). Lo arranca /w:plan-refine y
+  es reanudable + re-corrible a demanda. Invocar cuando un plan ya generado deba
+  ajustarse antes de ejecutarlo.
+---
+
+# plan-refine-loop
+
+> **Heir** del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md). Aquí **solo** los deltas. El motor (gap-driven, sesión única, structured-choice + control `flow`, research inline + regla BD, compact/resume, artefactos como log vivo, objetivo persistente + verification-first) vive en el chasis — no se repite.
+
+> **Relación con los otros loops de PLAN:** `plan-new-loop` **genera** el plan desde el spec; `plan-refine-loop` **lo refina in place** (opcional); `plan-exec-loop` **lo ejecuta**. plan-refine es a plan-new lo que spec-refine es a spec-new.
+
+## Flow
+PLAN
+
+## Layer
+2 — la IA lo corre entero.
+
+## Auxiliar / NO obligatorio
+`plan-exec` corre **cualquier** plan, refinado o no — **no** hay gate que exija plan-refine. Este loop existe para incorporar cambios (nuevos requerimientos, ajustes de alcance, deps/riesgos detectados al releer) **antes** de ejecutar, sin re-generar el plan desde cero.
+
+## Started by
+`/w:plan-refine` — **reanudable** (mismo mecanismo del chasis, keyado off CHECKPOINT) y **re-corrible a demanda** (ver *Compact / resume*).
+
+## Reads
+`docs/plans/PPP-plan-*.md` (glob — localiza el plan por número; o la ruta exacta del argumento del comando). **Siempre el plan mismo**: este loop lo edita in place, no hay un archivo "refined" aparte.
+
+## Writes
+Actualiza `docs/plans/PPP-plan-<slug>.md` **in place** (cuando el usuario elige `Guardar plan refinado`): completa/ajusta secciones y **agrega** `## Refinement decisions` + `## Q&A traceability`. Como sobrescribe un doc existente, **con confirmación** del usuario. Solo escribe `docs/plans` — nunca otras carpetas `docs/` ni auto-export.
+
+## Inherits
+
+Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
+
+- **Objetivo persistente + verification-first**: persigue su `SESSION.Objective` hasta que sus `SESSION.Success criteria` están **en verde** (sembrados al inicio; acá la rúbrica = **coherencia del plan**, ver *Convergence*). Motor **gap-driven convergente** + **ciclo artifact-first** (sembrar `CHECKPOINT.Pending/Next` ANTES → `detect_gaps` → resolver → integrar → `Pending→Completed` DESPUÉS; gaps agotados con límite `MAX` no se re-disparan).
+- **Una sola session por run**: descriptor `<slug>-plan-refine` → `NNN-<slug>-plan-refine` (Type = `refine`): `SESSION` + `CHECKPOINT` (+ `BACKLOG` solo si difiere). La **investigación es inline** dentro de esta session (produce `ANALYSIS-FILE`/`CONCLUSIONS` + `SCRIPTS.sql` read-only en su propia carpeta), no una session aparte. El CLI antepone el `NNN` global; el caller pasa solo el descriptor.
+- **Structured-choice**: ≤3 preguntas de contenido + 1 control `flow` (`Compactar`/`Cerrar`) siempre (ver [`../../harness/SKILL.md`](../../harness/SKILL.md); en Claude Code es `AskUserQuestion`). Cada pregunta de contenido lleva **respuesta recomendada**.
+- **Ask-vs-research rule** + **research autónomo inline** + **regla BD** (pregunta MCP si >1 sin default → queries a `SCRIPTS.sql` → ejecuta read-only, `sql-mutation-guard`) + manejo de research **inconclusa** (degrada a humano / difiere a `Open questions` + límite `MAX`).
+- **Compact / resume** y **artefactos como log vivo (ciclo artifact-first)** (`CHECKPOINT` siempre; `BACKLOG` solo si difiere). **Integridad del gate** (anti-gaming + verificación independiente): *only command output counts*.
+
+## Delta 1 — Deliverable: el PLAN, editado in place
+
+El plan usa el **mismo esqueleto** que produce [`plan-new-loop`](../plan-new-loop/SKILL.md) (§ *Delta 1 — PLAN RICO*: `Summary`/`Solution`/`Impacted`/`Phases`/`Tasks`/`Validations`/`Final behavior`/… con secciones `(core)` siempre y `(opt.)` según complejidad). plan-refine **no** cambia el esquema: **completa/ajusta** las secciones existentes **in place** y **agrega** dos de traza:
+
+```markdown
+## Refinement decisions   ← NEW (se AGREGA)
+Qué se ajustó al refinar y por qué (nuevos requerimientos, cambios de scope,
+deps/riesgos). Incluye lo resuelto vía research inline (ref a las CONCLUSIONS
+de la session).
+
+## Q&A traceability       ← NEW (se AGREGA)
+Cada duda preguntada al humano + la respuesta elegida.
+```
+
+> **Sin contrato de gating** (a diferencia de spec↔plan): la presencia de `## Refinement decisions`/`## Q&A traceability` en el plan es solo **traza de auditoría** — `plan-exec` **no** la exige ni la chequea (corre cualquier plan). Sirve para (a) distinguir un plan re-refinado de uno recién generado en el resume, y (b) dejar registro de qué cambió y por qué.
+
+> El plan **no muta por ejecución** (eso lo trackea plan-exec en las Tasks del plan-doc) — solo por un (re-)refine.
+
+## Delta 2 — Gap taxonomy (de "plan")
+
+Reusa **íntegra** la gap taxonomy de [`plan-new-loop`](../plan-new-loop/SKILL.md) (§ *Delta 2*): Approach/Solution vago, componentes sin identificar, wiring AS-IS desconocido, fase muy grande, tarea no atómica, deps faltantes, criterios del spec sin cubrir, riesgos sin atender. **Diferencia de foco:** plan-new **construye** el plan desde cero; plan-refine **detecta qué cambió** respecto del plan ya escrito (o respecto del spec, si el spec se re-refinó) y cierra **esos** gaps — típicamente menos y más localizados. Un gap extra propio del re-refine:
+
+| Gap | Signal | Resolved by |
+|---|---|---|
+| Deriva plan↔spec | el spec se re-refinó y el plan quedó desalineado | **research** (re-lee el spec) / **humano** |
+
+## Delta 3 — What research investigates here
+
+Igual que plan-new (mapea código/impacto: componentes FE/BE/BD, wiring AS-IS, deps), pero **acotado al delta**: re-verifica solo lo que el cambio toca (no re-mapea todo el plan). Regla BD del chasis igual (read-only a `SCRIPTS.sql`, MCP vía pregunta si >1 sin default).
+
+## Compact / resume
+
+El resume **keya off el `CHECKPOINT`** de la refine session, no de un archivo "refined". Tres casos al ejecutar `/w:plan-refine` sobre un plan:
+
+1. **En curso** (existe `CHECKPOINT.md` en la refine session) → reanuda desde el avance (gaps resueltos, Q&A, `attempts`, research inline en curso).
+2. **Sin avance** (no hay CHECKPOINT y el plan **no** tiene `Refinement decisions`/`Q&A traceability`) → arranca desde cero leyendo el plan (`PPP-plan-*.md`).
+3. **Ya refinado / re-refine on demand** (no hay CHECKPOINT abierto pero el plan **ya tiene** `Refinement decisions`/`Q&A traceability`) → **operación de primera clase**: mientras el flujo siga en PLAN, re-correr `/w:plan-refine` sobre el mismo plan **cuantas veces haga falta** está soportado. `create_or_resume` detecta la refine session existente —típicamente **cerrada** tras converger— por descriptor + `## Origin` y la **reabre** (ver chasis § *Internal sessions*: detección con `aw sessions --state all` / `aw resume-summary --include-recent-closed`, reapertura con `aw session-resume --code <NNN> --reopen`); re-refinamiento incremental leyendo el **plan mismo**; al `Guardar`, edita in place con confirmación.
+
+> **Continuidad inter-turno** (chasis, fila 2): un **comando de flujo** abre "nueva línea de trabajo" (sesión nueva) — **salvo re-correr el mismo flujo sobre la misma entrada** (mismo plan), que hace `create_or_resume` (reanuda/reabre en vez de duplicar).
+
+## Convergence / exit
+
+Sin gaps materiales → **coherence gate** (read-only) = **`Success criteria` en verde** (*verification-first*; el "convergence gate" del chasis para PLAN, mismo que plan-new): cada `acceptance criterion` del spec **traza** a una fase/tarea, `Final behavior` los cubre, fases XS–S / tareas XS, `deps` sin ciclos, `Impacted` consistente con `Solution`, y —propio del re-refine— **el plan quedó realineado** con lo que cambió. Lo que falle **vuelve como gap**. Si pasa → *structured-choice* (contenido: `Guardar plan refinado` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`) → al `Guardar`, edita `docs/plans/PPP-plan-<slug>.md` in place (con confirmación) + inserta `Refinement decisions`/`Q&A traceability` → `finalize` (persiste `CHECKPOINT`; `BACKLOG` solo si difiere; cierra la session, reporta). `Cerrar` en cualquier momento → `finalize` igual.

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

@@ -307,5 +307,6 @@ El resume **keya off el `CHECKPOINT`** de la refine session, no de la existencia
 ## Heredan este chasis
 
 - `plan-new-loop` — mismo motor; deltas: plan rico + gap taxonomy de plan.
+- `plan-refine-loop` — mismo motor; deltas: refina el **plan** in place (auxiliar, no obligatorio), reusando la gap taxonomy + coherence gate de `plan-new-loop`. Es a `plan-new` lo que este chasis (`spec-refine`) es a `spec-new`.
 - `plan-exec-loop` — mismo motor; deltas: ejecución real (código/BD/git), **una sola session por run** (progreso por fase en el plan-doc), sin auto-export.
 - `quick-loop` — mismo motor (mínimo); hereda además git/BD/no-export de `plan-exec-loop`.