@tacuchi/agent-workflow-cli 14.1.1 → 14.2.0

package/dist/cli/tui/data/workflow-content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-content.d.ts","sourceRoot":"","sources":["../../../../src/cli/tui/data/workflow-content.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,gBAAgB,EAAE,eAsL9B,CAAC"}
+{"version":3,"file":"workflow-content.d.ts","sourceRoot":"","sources":["../../../../src/cli/tui/data/workflow-content.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,gBAAgB,EAAE,eAuL9B,CAAC"}

package/dist/cli/tui/data/workflow-content.js

@@ -35,9 +35,9 @@ export const WORKFLOW_CONTENT = {
             id: "plan",
             n: 3,
             title: "PLAN — the how",
-            desc: "Plan and execute. plan-new + plan-exec each drive loops → docs/plans.",
-            commands: ["plan-new", "plan-exec"],
-            slash: "/w:plan-new · /w:plan-exec",
+            desc: "Plan, (optionally) refine, and execute. plan-new + plan-refine (aux) + plan-exec each drive loops → docs/plans.",
+            commands: ["plan-new", "plan-refine", "plan-exec"],
+            slash: "/w:plan-new · /w:plan-refine · /w:plan-exec",
             hook: "PreCompact · PostCompact",
         },
         {
@@ -148,6 +148,7 @@ export const WORKFLOW_CONTENT = {
         "/w:spec-new",
         "/w:spec-refine",
         "/w:plan-new",
+        "/w:plan-refine",
         "/w:plan-exec",
         "/w:quick",
         "/w:status",

package/dist/cli/tui/data/workflow-content.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-content.js","sourceRoot":"","sources":["../../../../src/cli/tui/data/workflow-content.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workflow-content.js","sourceRoot":"","sources":["../../../../src/cli/tui/data/workflow-content.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tacuchi/agent-workflow-cli",
-  "version": "14.1.1",
+  "version": "14.2.0",
   "description": "Agnostic runtime CLI for AI development workflows — a stages + loops + artifacts harness. Bundles the universal `w` skill set under `skills/w/` (slash commands `/w:*`: spec-new/spec-refine, plan-new/plan-exec, quick, workspace-init, export-*); `self install --target <host>` copies SKILL + commands + hooks into the host. Pluggable capability skills via `.workflow/skills.toml`. Multi-empresa parametrization via `profile.json` cascade. Namespace auto-detected from any `.<ns>/sessions/` dir in CWD; default `workflow`.",
   "type": "module",
   "bin": {

package/skills/w/README.md

@@ -9,13 +9,13 @@ This bundle implements the **stages + loops + artifacts** model. The design sour
 ```
 LAYER 1 · COMMANDS  (/w:* — the only thing the user invokes)
   SPEC   spec-new (single-pass) · spec-refine        EXPORTS  export-scripts · export-manuals
-  PLAN   plan-new · plan-exec                                  export-diagrams · export-reports
+  PLAN   plan-new · plan-refine · plan-exec                    export-diagrams · export-reports
   QUICK  quick                                        SETUP   workspace-init
         │ start                                              │ (single-pass, read-only)
         ▼                                                    │
 LAYER 2 · LOOPS  (the AI runs them whole)                    │
   spec-refine-loop (chassis) · plan-new-loop ·                │
-  plan-exec-loop · quick-loop                                 │
+  plan-refine-loop · plan-exec-loop · quick-loop              │
         │ create / manage                                     │
         ▼                                                     │
 LAYER 3 · SESSIONS + ARTIFACTS  (.workflow/sessions/)  ───────┘ export-* read these
@@ -30,7 +30,7 @@ ZONE docs/ — permanent, user-facing deliverables
 | Folder | Layer | Contains |
 |---|---|---|
 | [`commands/`](commands/) | 1 | The `/w:` slash commands the user invokes |
-| [`loops/`](loops/) | 2 | The 4 loops (chassis `spec-refine-loop` + heirs) the AI runs |
+| [`loops/`](loops/) | 2 | The 5 loops (chassis `spec-refine-loop` + heirs) the AI runs |
 | [`exports/`](exports/) | 1 | The `export-*` family — the only artifact→`docs/` promotion path |
 | [`roles/`](roles/) | cross-cutting | Pluggable capability skills (built-in defaults; rebindable via `.workflow/skills.toml`) |
 | [`harness/`](harness/SKILL.md) | cross-cutting | Capability→harness-mechanism binding (agnostic across Claude Code / Codex / opencode / Gemini) |
@@ -43,12 +43,12 @@ ZONE docs/ — permanent, user-facing deliverables
 | Flow | Commands | `docs/` owned | Loops |
 |---|---|---|---|
 | **SPEC** | `spec-new` *(single-pass)* · `spec-refine` | `docs/specs` | `spec-refine-loop` |
-| **PLAN** | `plan-new` · `plan-exec` | `docs/plans` | `plan-new-loop` · `plan-exec-loop` |
+| **PLAN** | `plan-new` · `plan-refine` *(aux)* · `plan-exec` | `docs/plans` | `plan-new-loop` · `plan-refine-loop` · `plan-exec-loop` |
 | **QUICK** | `quick` | — | `quick-loop` |
 
 SPEC defines the **what** → PLAN the **how** and executes it → QUICK is the lightweight shortcut. Promotion to `docs/` (scripts/manuals/diagrams/reports) is **always** a separate step via `export-*`.
 
-> **Transversal commands** (no flow, not counted in 5/4): `/w:status` (read-only workspace dashboard) · `/w:fix-git` (resolve an in-progress merge conflict, git-safe — works on any repo). Setup: `/w:workspace-init`.
+> **Transversal commands** (no flow, not counted in 6/5): `/w:status` (read-only workspace dashboard) · `/w:fix-git` (resolve an in-progress merge conflict, git-safe — works on any repo). Setup: `/w:workspace-init`.
 
 ## Bootstrap
 

package/skills/w/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Orientation skill for the whole agent-workflow harness — built-in default for the
   `overview` role. Load this to understand the model end-to-end: the 3-layer
   architecture (commands → loops → sessions/artifacts) plus the docs/ zone, the 3
-  flows (SPEC / PLAN / QUICK), the `/w:` commands, the 4 loops and their chassis, the
+  flows (SPEC / PLAN / QUICK), the `/w:` commands, the 5 loops and their chassis, the
   `export-*` family, the composable capability skills + `.workflow/skills.toml`
   binding cascade, and the 6 hard invariants. Use whenever an agent (or human) needs
   to know how the pieces fit, where a deliverable should land, or which command/loop/
@@ -36,12 +36,12 @@ Un solo concepto: **workspace**. No hay project/hub. La carpeta donde arranca el
 ```
 USUARIO invoca
   LAYER 1 · COMMANDS (lo único que el usuario invoca)
-    FLOWS:   spec-new · spec-refine · plan-new · plan-exec · quick
+    FLOWS:   spec-new · spec-refine · plan-new · plan-refine · plan-exec · quick
     EXPORTS: export-scripts · export-manuals · export-diagrams · export-reports
         │ arranca / delega
         ▼
   LAYER 2 · LOOPS (los corre la IA, gap-driven)
-    spec-refine-loop (CHASIS) · plan-new-loop · plan-exec-loop · quick-loop
+    spec-refine-loop (CHASIS) · plan-new-loop · plan-refine-loop · plan-exec-loop · quick-loop
         │ crea / lee / escribe
         ▼
   LAYER 3 · SESSIONS + ARTIFACTS (.workflow/sessions/ — efímero, interno)
@@ -60,10 +60,10 @@ USUARIO invoca
 | Flow | Commands | docs/ propio | Loops |
 |---|---|---|---|
 | **SPEC** (el *qué*) | `spec-new` *(single-pass)* · `spec-refine` | `docs/specs` | `spec-refine-loop` |
-| **PLAN** (el *cómo* + ejecutar) | `plan-new` · `plan-exec` | `docs/plans` | `plan-new-loop` · `plan-exec-loop` |
+| **PLAN** (el *cómo* + ejecutar) | `plan-new` · `plan-refine` *(aux, opcional)* · `plan-exec` | `docs/plans` | `plan-new-loop` · `plan-refine-loop` · `plan-exec-loop` |
 | **QUICK** (atajo liviano) | `quick` | — | `quick-loop` |
 
-Cadena típica: prompt → `spec-new` genera `docs/specs/NNN-spec-<slug>.md` → `spec-refine` corre el loop y refina **ese mismo spec in place** → `plan-new` → `docs/plans/PPP-plan-<slug>.md` → `plan-exec` ejecuta y actualiza el plan (living doc) + artefactos en sesiones. La promoción del resto a `docs/` es **siempre** un paso aparte vía `export-*`.
+Cadena típica: prompt → `spec-new` genera `docs/specs/NNN-spec-<slug>.md` → `spec-refine` corre el loop y refina **ese mismo spec in place** → `plan-new` → `docs/plans/PPP-plan-<slug>.md` → *(opcional)* `plan-refine` ajusta **ese mismo plan in place** si hay cambios antes de ejecutar → `plan-exec` ejecuta y actualiza el plan (living doc) + artefactos en sesiones. La promoción del resto a `docs/` es **siempre** un paso aparte vía `export-*`.
 
 ### Contexto operativo — dónde aterriza cada cosa
 
@@ -84,13 +84,14 @@ Antes de cualquier loop, la IA resuelve su **contexto operativo** en **cada prom
 - `/w:spec-new` — genera un spec inicial (single-pass, sin loop).
 - `/w:spec-refine` — arranca `spec-refine-loop` para refinar el spec.
 - `/w:plan-new` — arranca `plan-new-loop` para derivar un plan ejecutable del spec refinado.
+- `/w:plan-refine` — arranca `plan-refine-loop` para refinar el plan in place (auxiliar, **no obligatorio**) antes de ejecutar.
 - `/w:plan-exec` — arranca `plan-exec-loop` para ejecutar y mantener el plan.
 - `/w:quick` — arranca `quick-loop` (atajo, sin `docs/`).
 - `/w:export-scripts` · `/w:export-manuals` · `/w:export-diagrams` · `/w:export-reports` — promueven artefactos a `docs/`.
 
 ### Transversal skills (no flow) — `/w:status` · `/w:fix-git`
 
-Skills **invocables independientes de flujo**: se disparan con `/w:` igual que un comando, pero **no** pertenecen a SPEC/PLAN/QUICK, **no** manejan `docs/`, y **no** entran en el conteo **5 comandos de flow / 4 loops**. (En el diseño son su propia categoría —`workflow-skills/`, aparte de los comandos de flow—; en el bundle se empaquetan bajo `commands/` para que `/w:` las invoque.)
+Skills **invocables independientes de flujo**: se disparan con `/w:` igual que un comando, pero **no** pertenecen a SPEC/PLAN/QUICK, **no** manejan `docs/`, y **no** entran en el conteo **6 comandos de flow / 5 loops**. (En el diseño son su propia categoría —`workflow-skills/`, aparte de los comandos de flow—; en el bundle se empaquetan bajo `commands/` para que `/w:` las invoque.)
 
 - `/w:status` — dashboard read-only del workspace (Hecho/Falta/Descartó, con fechas en español). No escribe nada; se apoya en `aw status`.
 - `/w:fix-git` — resuelve conflictos de un merge en curso en cualquier repo (identifica origen↔destino, analiza intención, *structured-choice* ante ambigüedad). No crea session, no toca `docs/`; git-safe; se apoya en `aw merge-state`.
@@ -109,9 +110,9 @@ Un loop es una skill que enseña a la IA **cómo iterar** hasta un entregable. P
 
 `flow → Compactar` = checkpoint + la **compactación** del arnés (en Claude Code: `/compact`; ver `harness/SKILL.md`) y reanuda. `flow → Cerrar` = persiste `CHECKPOINT` (siempre) + `BACKLOG` (solo si difiere), cierra la session, termina.
 
-Cada loop tiene un **convergence gate** read-only antes de ofrecer `Guardar`/`done`, que es operacionalmente **"todos los `SESSION.Success criteria` en verde"** (*verification-first*): chequea invariantes propios del entregable y lo que falle vuelve como gap (en `spec-refine-loop` es el *analyze gate*; en `plan-new-loop`, la coherencia del plan; en `plan-exec-loop`, la validación final; en `quick-loop`, una validación puntual proporcional). El detalle vive en cada loop.
+Cada loop tiene un **convergence gate** read-only antes de ofrecer `Guardar`/`done`, que es operacionalmente **"todos los `SESSION.Success criteria` en verde"** (*verification-first*): chequea invariantes propios del entregable y lo que falle vuelve como gap (en `spec-refine-loop` es el *analyze gate*; en `plan-new-loop` —y en `plan-refine-loop`— la coherencia del plan; en `plan-exec-loop`, la validación final; en `quick-loop`, una validación puntual proporcional). El detalle vive en cada loop.
 
-`spec-new` no tiene loop (single-pass): **5 comandos / 4 loops**.
+`spec-new` no tiene loop (single-pass): **6 comandos / 5 loops**.
 
 ### The `export-*` family (única vía artefacto → `docs/`)
 

package/skills/w/commands/README.md

@@ -3,7 +3,7 @@
 > This is the **bundle README** for the `/w:` slash-command namespace. Every command listed here is something the **user** invokes directly.
 > Related layers: [`../loops/`](../loops/) (Layer 2, AI-driven) · artifacts live in `.workflow/sessions/` (Layer 3) · permanent deliverables in `docs/`.
 >
-> **Namespace:** all commands are under `w:` (`w` = *workflow*): `/w:spec-new`, `/w:spec-refine`, `/w:plan-new`, `/w:plan-exec`, `/w:quick`, `/w:workspace-init`, `/w:status` (transversal), `/w:fix-git` (transversal), `/w:export-*`.
+> **Namespace:** all commands are under `w:` (`w` = *workflow*): `/w:spec-new`, `/w:spec-refine`, `/w:plan-new`, `/w:plan-refine`, `/w:plan-exec`, `/w:quick`, `/w:workspace-init`, `/w:status` (transversal), `/w:fix-git` (transversal), `/w:export-*`.
 
 ---
 
@@ -12,14 +12,15 @@
 ```
 ┌─ LAYER 1 · COMMANDS (this dir) — the only thing the user invokes ──────┐
 │   workspace-init                                                        │
-│   spec-new · spec-refine · plan-new · plan-exec · quick                │
+│   spec-new · spec-refine · plan-new · plan-refine · plan-exec · quick  │
 │   export-scripts · export-manuals · export-diagrams · export-reports   │
 │   High-level. Single-pass or starts a loop. No iteration logic here.   │
 └───────────────────────────┬────────────────────────────────────────────┘
                             │ starts / delegates to
                             ▼
 ┌─ LAYER 2 · LOOPS (../loops/) — AI runs these end-to-end ───────────────┐
-│   spec-refine-loop · plan-new-loop · plan-exec-loop · quick-loop        │
+│   spec-refine-loop · plan-new-loop · plan-refine-loop                  │
+│   plan-exec-loop · quick-loop                                          │
 │   Gap-driven · structured-choice: ≤3 content questions + 1 `flow`     │
 │   (Compactar / Cerrar always present) · compact/resume support.        │
 └───────────────────────────┬────────────────────────────────────────────┘
@@ -46,14 +47,14 @@
 | Flow | docs/ target | Entry command | Advance command | Loops involved |
 |---|---|---|---|---|
 | **SPEC** | `docs/specs/` | `spec-new` *(single-pass)* | `spec-refine` | `spec-refine-loop` |
-| **PLAN** | `docs/plans/` | `plan-new` | `plan-exec` | `plan-new-loop`, `plan-exec-loop` |
+| **PLAN** | `docs/plans/` | `plan-new` | `plan-refine` *(aux, opcional)* · `plan-exec` | `plan-new-loop`, `plan-refine-loop`, `plan-exec-loop` |
 | **QUICK** | — *(no doc)* | `quick` | — | `quick-loop` |
 
-> **Intentional asymmetry:** in SPEC, `spec-new` generates the draft in a **single pass** (no loop) and the loop is in `spec-refine`. In PLAN, **both** commands start loops. Total: **5 flow commands / 4 loops**.
+> **Intentional asymmetry:** in SPEC, `spec-new` generates the draft in a **single pass** (no loop) and the loop is in `spec-refine`. In PLAN, all commands start loops — `plan-new` generates, `plan-refine` (auxiliary, **optional**) refines it in place, `plan-exec` executes. Total: **6 flow commands / 5 loops**.
 
 > **Transversal (no flow):** [`/w:status`](status.md) is a read-only dashboard of the whole workspace — what's done / pending / discarded, with friendly Spanish dates. It leans on `aw status`, writes nothing, and belongs to no flow.
 >
-> **Transversal (no flow):** [`/w:fix-git`](fix-git.md) resolves an **in-progress merge conflict** for any repo — identify origin↔destination, analyze both sides' intent, resolve (structured-choice on ambiguity), propose the merge commit (git-safe). Leans on `aw merge-state`; writes no `docs/`; works without a workspace. Neither transversal is counted in **5 flow / 4 loops**.
+> **Transversal (no flow):** [`/w:fix-git`](fix-git.md) resolves an **in-progress merge conflict** for any repo — identify origin↔destination, analyze both sides' intent, resolve (structured-choice on ambiguity), propose the merge commit (git-safe). Leans on `aw merge-state`; writes no `docs/`; works without a workspace. Neither transversal is counted in **6 flow / 5 loops**.
 >
 > `/w:status` and `/w:fix-git` are **transversal skills** — in the design model they form their own category (`workflow-skills/`, distinct from flow commands); here they are packaged under `commands/` so `/w:` can invoke them (Claude Code only invokes `commands/*.md`). See [`../harness/SKILL.md`](../harness/SKILL.md) § *Command packaging*.
 
@@ -72,6 +73,10 @@ flowchart LR
     pn -->|starts| pnl(["plan-new-loop"])
     pnl -->|generates| plan["docs/plans/PPP-plan-<slug>.md"]
 
+    plan -.->|optional: changes before exec| pr["/w:plan-refine"]
+    pr -->|starts| prl(["plan-refine-loop"])
+    prl -->|refines IN PLACE| plan
+
     plan --> pe["/w:plan-exec"]
     pe -->|starts| pel(["plan-exec-loop"])
     pel -->|read/update| plan
@@ -114,6 +119,7 @@ Each `<command>.md` in this bundle uses this frontmatter + body structure:
 | `spec-new` | [`spec-new.md`](spec-new.md) | single-pass |
 | `spec-refine` | [`spec-refine.md`](spec-refine.md) | starts `spec-refine-loop` |
 | `plan-new` | [`plan-new.md`](plan-new.md) | starts `plan-new-loop` |
+| `plan-refine` | [`plan-refine.md`](plan-refine.md) | starts `plan-refine-loop` (aux, optional) |
 | `plan-exec` | [`plan-exec.md`](plan-exec.md) | starts `plan-exec-loop` |
 | `quick` | [`quick.md`](quick.md) | starts `quick-loop` |
 | `status` | [`status.md`](status.md) | single-pass, read-only (transversal) |

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

@@ -0,0 +1,53 @@
+---
+description: Inicia o retoma el loop de refinamiento de un plan (plan-refine-loop). Paso auxiliar y NO obligatorio del flujo PLAN — refina un plan existente in place antes de ejecutarlo. Input ideal: docs/plans/PPP-plan-<slug>.md ya generado por plan-new.
+argument-hint: <docs/plans/PPP-plan-<slug>.md>
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+  ]
+---
+
+# plan-refine — trampolín al loop de refinamiento del plan
+
+Paso **auxiliar y NO obligatorio** del flujo PLAN: el gemelo de `spec-refine`, pero sobre el **plan**. `plan-new` ya produce un plan a partir del spec refinado; `plan-refine` existe para cuando —**antes de ejecutar**— surgen cambios (nuevos requerimientos, ajustes de alcance, deps o riesgos que aparecen al releer el plan) que conviene incorporar sin re-generar el plan desde cero.
+
+Este comando no refina el plan él mismo: delega al loop `plan-refine-loop` (Layer 2), que itera, cierra gaps y edita el plan **in place**.
+
+> **No obligatorio.** `plan-exec` corre **cualquier** plan, refinado o no — no hay gate que exija pasar por aquí. Usalo solo cuando el plan necesite ajustes antes de ejecutar.
+
+## Resolución de input
+
+El skill evalúa `$ARGUMENTS` (los planes viven in place — `docs/plans/PPP-plan-<slug>.md`; localizar vía glob `docs/plans/PPP-plan-*.md` o la ruta exacta):
+
+1. **Plan existente** (`docs/plans/PPP-plan-<slug>.md`) → procede a `plan-refine-loop`.
+2. **Sin plan** (el arg no referencia un plan, o no hay ninguno) → **soft-suggest** correr `/w:plan-new` primero (no hay nada que refinar todavía); el usuario decide.
+
+## Ejecutar el loop
+
+`plan-refine-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**:
+
+1. **Leé** `../loops/plan-refine-loop/SKILL.md` (ruta relativa a este archivo).
+2. **Seguí** sus instrucciones tomando `$ARGUMENTS` como input: detecta estado/resume, corre el motor gap-driven, crea y maneja sessions, converge y reporta.
+
+> No intentes `Skill: plan-refine-loop` — no está registrada como skill. El comando **es** la entrada; el loop es su cuerpo.
+
+## Resolución de estado (resumable)
+
+El skill detecta el estado previo antes de arrancar, **keyando off el `CHECKPOINT`** (no un archivo "refined"):
+
+1. Busca la sesión de refinamiento del plan en `.workflow/sessions/` (descriptor `<slug>-plan-refine` + `## Origin`) y su `CHECKPOINT.md`.
+2. **En curso** (existe CHECKPOINT) → continúa desde el avance previo (gaps resueltos, Q&A).
+3. **Sin avance** (sin CHECKPOINT y el plan **no** tiene `## Refinement decisions`/`## Q&A traceability`) → arranca desde cero leyendo el plan (`PPP-plan-*.md`).
+4. **Ya refinado / re-refine a demanda** (sin CHECKPOINT abierto pero el plan **ya tiene** `## Refinement decisions`/`## Q&A traceability`) → **soportado de primera clase**: mientras el flujo siga en PLAN podés re-correr `/w:plan-refine` sobre el mismo plan **las veces que haga falta** (nuevos requerimientos, cambios de scope, re-lectura). El loop hace `create_or_resume` — localiza la refine session existente (aunque esté cerrada) y la **reabre** en vez de duplicarla — y re-refina leyendo el **plan mismo**; al `Guardar`, edita in place con confirmación.
+
+## Plan mode
+
+El skill resuelve el estado y describe las acciones que ejecutaría el loop (gaps que cerraría, preguntas que haría), sin arrancar la iteración.
+
+## Resources
+
+- Loop skill: `../loops/plan-refine-loop/SKILL.md`
+- Design reference: `docs/referencias/workflow-commands/plan-refine.md`

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