@tacuchi/agent-workflow-cli 11.0.1 → 12.2.0

package/skills/w/artifacts/artifacts-core/SCRIPTS.sql

@@ -0,0 +1,39 @@
+-- SCRIPTS.sql — session artifact (common)
+--
+-- What it is: the SQL produced by a session. TWO types, distinguished by whether they are EXECUTED:
+--   A) READ-ONLY queries (diagnosis/validation): the AI writes them here and then
+--      executes them read-only via MCP.
+--   B) DDL/DML migrations (schema/data changes): the AI DRAFTS them as a
+--      deliverable but NEVER executes them; they are exported to docs/scripts/ (forward +
+--      rollback) for a human/DBA to apply.
+--
+-- Golden rule: the AI only EXECUTES type A (read-only). The sql-mutation-guard BLOCKS
+-- execution of DML/DDL — that is why type B is DELIVERED, not run.
+--
+-- Rules:
+--   1) One entry per script, numbered, with purpose, DB/MCP target and type (A or B).
+--   2) Only type A is executed (read-only, via the declared MCP).
+--   3) Lives in the session (.workflow/sessions/NNN-.../SCRIPTS.sql).
+--   4) Type B is exported to docs/scripts/ as a deliverable (not executed by the AI).
+
+-- ============================================================
+-- [Q1] <purpose of the query>   |   Type: A (read-only)
+-- DB/MCP: <which>   |   Origin: <gap / task that motivates it>
+-- ------------------------------------------------------------
+SELECT ...;
+
+-- ============================================================
+-- [Q2] <purpose>   |   Type: A (read-only)
+-- DB/MCP: <which>   |   Origin: <...>
+-- ------------------------------------------------------------
+SELECT ...;
+
+-- ============================================================
+-- [M1] <migration>   |   Type: B  —  DO NOT EXECUTE (deliverable; applied by a DBA;
+--                        exported to docs/scripts/ via export-*)
+-- DB/MCP: <which>   |   Origin: <plan task>
+-- ------------------------------------------------------------
+-- forward:
+ALTER TABLE ... ;
+-- rollback:
+-- ALTER TABLE ... ;

package/skills/w/artifacts/artifacts-core/SESSION.md

@@ -0,0 +1,27 @@
+# SESSION.md — internal session descriptor (common)
+
+> What it is: the brief descriptor of an **internal session** (Layer 3). Created by a **loop**, not by the user.
+> The `Type` is set by the owning loop. Authoritative type catalog: `../README.md` (table "Sessions & their artifacts").
+
+## Objective (text):
+What this session resolves: the gap, the question, or the concrete block of work.
+
+## Origin (list):
+Who created it and from where:
+- Parent loop (e.g. `spec-refine-loop`)
+- Source document (e.g. `docs/specs/003-spec.md`)
+- Trigger (e.g. gap "Context incomplete")
+
+## Type (text):
+Session type, **set by the parent loop** (not the user). Authoritative catalog: `../README.md`.
+- `research` — investigate/conclude (read-only); on-demand, **not resumable** (run-and-close)
+- `exec` — execute work, one per phase (PLAN)
+- `quick` — lightweight execution (≈ `exec`: single session, single commit) (QUICK)
+- `refine` / `control` — owns a loop run (SESSION + CHECKPOINT; + BACKLOG on close)
+
+## Components (list):
+Projects / systems / sources / databases involved.
+
+## Success criteria (list):
+Checklist `[ ]` that, when met, **closes the session and triggers the report** back to the loop.
+If NOT met (e.g. research without evidence, DB unavailable): the session **closes anyway with state `inconcluso`** and reports the reason; the parent loop degrades the gap (asks the human or defers to `Open questions`).

package/skills/w/artifacts/artifacts-core/TASKS.md

@@ -0,0 +1,18 @@
+# TASKS.md — internal task breakdown (optional, common)
+
+> What it is: an internal phases/tasks breakdown for sessions that need their own desglose. **Optional artifact** — in PLANIFICATION, phases and tasks live in the **plan-doc** (`docs/plans/PPP-plan.md`, living). Use this only when a session needs a breakdown that is not covered by the plan-doc.
+
+## Phases (list):
+List of grouping phases. Phases should have a complexity between XS and S.
+
+Example:
+- F1: Investigate billing flow
+- F2: Design new button for new payment method
+
+## Tasks (list):
+List of tasks ordered by phase. Tasks should have a maximum complexity of XS.
+
+Example:
+- T1 (F1): Analyze sources ms-motor, ms-solicitud
+- T2 (F1): Review tables in schema esq_motor
+- T1 (F2): Add new div container in payment methods screen

package/skills/w/artifacts/artifacts-dev/DECISION.md

@@ -0,0 +1,11 @@
+# DECISION.md — non-obvious decisions log (exec / quick sessions)
+
+> What it is: a log of non-obvious decisions made during an `exec` or `quick` session. Kept per-session so the loop and the human can trace why things were done a certain way.
+
+## Origin (list):
+Reference work unit (per the owning loop):
+- in `exec` → the Task from the plan-doc (`docs/plans/PPP-plan.md`, e.g. "T2 (F1)")
+- in `quick` → the prompt / work unit (no task numbering)
+
+## Decision (list):
+List of non-obvious decisions. For each: the decision taken, the reason, and the alternatives considered.

package/skills/w/artifacts/artifacts-dev/TECHNICAL-NOTE.md

@@ -0,0 +1,81 @@
+# TECHNICAL-NOTE.md — technical design note (schema reference)
+
+> **Model note:** in PLANIFICATION these sections live **inline in the plan-doc** (`docs/plans/PPP-plan.md`, rich plan), not as an exec-session artifact. This file is kept as a reference of the technical schema that the plan absorbs. Use it standalone only when the plan-doc approach does not apply (e.g. a `quick` session that needs scoped technical context).
+
+## Solution (text|list):
+Technical/functional explanation of how the solution will be implemented.
+
+## Impacted (list):
+List of impacted components:
+- Frontend
+- Backend
+- Database (schemas/tables/functions)
+- APIs (controllers/endpoints)
+- Integrations with external systems
+
+## Dependencies (list):
+List of dependencies: sessions / documents / projects / sources / databases, etc.
+
+## Current State (text):
+Simple representation of the wiring or cabling (interfaces and methods) — AS-IS behavior.
+
+Example:
+```
+ContratoEfectivoData.demo()
+        │
+        ▼
+ContratoTemplateRenderer
+   (iface)
+        │ @Service impl
+        ▼
+ThymeleafContratoTemplateRenderer ──── reads ──> templates/contratos/efectivo.html
+        │ (returns String HTML)
+        ▼
+PreviewController.efectivoHtml()  ──> respond TEXT_HTML
+              │
+              └─> efectivoPdf() ─> PdfRenderer (iface @Qualifier("chromePdfRenderer"))
+                                            │ @Service impl
+                                            ▼
+                                       CdpPdfRenderer  ──> Chrome headless via CDP
+                                                              │
+                                                              ▼
+                                                       respond APPLICATION_PDF
+```
+
+## Target State (text):
+Simple representation of the wiring or cabling (interfaces and methods) — TO-BE behavior.
+
+## Final Behavior (text|list):
+How the entire flow should behave at the end (must be aligned with the requirements and acceptance/success criteria in SESSION.md).
+
+Example:
+The user must be able to recover their password via OTP to their mobile number and the mobile number must be saved in the user's data:
+1. [User] Accesses the login screen
+2. [User] Clicks [Forgot Password]
+3. [System] Shows a window to enter mobile number
+4. [User] Enters mobile number
+5. [System] Sends OTP via SMS
+6. [System] Confirms OTP
+7. [System] Saves the mobile number and associates it with the [User]
+
+## Impact / Risks (list):
+Technical impacts and risks.
+
+## Assumptions (list):
+List of assumptions.
+
+## Estimated Time (list):
+Time estimates for [Development] and [Internal Testing].
+The work week has 5 days (Monday–Friday only).
+Size scale XS/S/M/L/XL:
+- XS -> 1 day or less
+- S  -> 1 to 2 days
+- M  -> 3 to 5 days
+- L  -> 6 to 10 days
+- XL -> More than 10 days
+
+## Validations (list):
+Validations, constraints, business-specific logic.
+
+## Open Questions (text|list):
+Pending items, doubts, open questions.

package/skills/w/artifacts/artifacts-research/ANALYSIS-FILE.md

@@ -0,0 +1,48 @@
+# ANALYSIS-FILE.md — research session analysis file
+
+> What it is: the working analysis document of a `research` session. Created on-demand by any loop. Not resumable (run-and-close) — the owning `refine/control` session's CHECKPOINT tracks open research sessions.
+
+# Case (text):
+Short title.
+
+## Question (text)
+What needs to be clarified or demonstrated?
+
+Example:
+Why does client X appear with a pending balance if they already made the payment?
+
+## Context (text)
+Example:
+- Requester:
+- Area:
+- System / module:
+- Case date:
+- Known impact:
+
+## Initial Hypotheses (text|list)
+- H1:
+- H2:
+- H3:
+
+## Evidences (list|table):
+| ID | Source | Finding | Link / file / query |
+|---|---|---|---|
+| E1 | DB | | |
+| E2 | Code | | |
+| E3 | Logs | | |
+| E4 | Email | | |
+| E5 | File | | |
+
+## Findings (text|list)
+What do the evidences indicate?
+
+- Evidence E1 shows that...
+- Evidence E2 confirms that...
+- Evidence E3 rules out that...
+
+## Identified Cause (text|list)
+- Technical:
+- Functional:
+- Operational:
+- Data:
+- Undetermined:

package/skills/w/artifacts/artifacts-research/CONCLUSIONS.md

@@ -0,0 +1,20 @@
+# CONCLUSIONS.md — research session conclusions
+
+> What it is: the conclusions of a `research` session. Produced when the session closes (success or `inconcluso`). The parent loop reads this to resolve the gap that triggered the research.
+
+## Conclusion (text|list)
+Direct answer to the initial question.
+
+## Recommended Action (text|list)
+
+Example:
+- [ ] Create bugfix
+- [ ] Create requirement
+- [ ] Correct data
+- [ ] Escalate to business
+- [ ] Train user
+- [ ] Close without technical action
+- [ ] Request more information
+
+## Details (text):
+Supporting detail, evidence references, or additional context.

package/skills/w/commands/README.md

@@ -0,0 +1,116 @@
+# w — Command map (Layer 1)
+
+> 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:export-*`.
+
+---
+
+## 3-layer model + docs/ zone
+
+```
+┌─ LAYER 1 · COMMANDS (this dir) — the only thing the user invokes ──────┐
+│   workspace-init                                                        │
+│   spec-new · spec-refine · plan-new · 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        │
+│   Gap-driven · AskUserQuestion with ≤3 content tabs + 1 `flow` tab     │
+│   (Compactar / Cerrar always present) · compact/resume support.        │
+└───────────────────────────┬────────────────────────────────────────────┘
+                            │ creates / reads / writes
+                            ▼
+┌─ LAYER 3 · SESSIONS + ARTIFACTS (.workflow/sessions/) ─────────────────┐
+│   Ephemeral, internal. No one invokes this by hand. Process-only.      │
+│   (schema in ../workflow-artifacts/)                                   │
+└────────────────────────────────────────────────────────────────────────┘
+
+╔═ docs/ ZONE — PERMANENT documents, user-facing ════════════════════════╗
+║  specs · plans · tools          ← written by flows directly            ║
+║  scripts · manuals · diagrams · reports   ← written by export-* only  ║
+╚════════════════════════════════════════════════════════════════════════╝
+```
+
+## Bootstrap
+
+[`/w:workspace-init`](workspace-init.md) converts the current folder into an agent-workflow **workspace** (scaffolds `.workflow/` + `docs/` + `WORKSPACE` block + `.workflow/skills.toml`). Replaces the old `hub-init` + `project-init` — **no project/hub distinction**. A workspace has 1+ sources; "standalone" is just a single-source workspace. Run once before any flow.
+
+## Flows & commands
+
+| Flow | docs/ target | Entry command | Advance command | Loops involved |
+|---|---|---|---|---|
+| **SPEC** | `docs/specs/` | `spec-new` *(single-pass)* | `spec-refine` | `spec-refine-loop` |
+| **PLANIFICATION** | `docs/plans/` + `docs/tools/` | `plan-new` | `plan-exec` | `plan-new-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 PLANIFICATION, **both** commands start loops. Total: **5 flow commands / 4 loops**.
+
+## Pipeline
+
+```mermaid
+flowchart LR
+    prompt(["user prompt"]) --> sn["/w:spec-new"]
+    sn -->|generates| spec["docs/specs/NNN-spec.md"]
+    spec -.->|optional manual edit| spec
+    spec --> sr["/w:spec-refine"]
+    sr -->|starts| srl(["spec-refine-loop"])
+    srl -->|generates| specr["docs/specs/NNN-spec-refined.md"]
+
+    specr --> pn["/w:plan-new"]
+    pn -->|starts| pnl(["plan-new-loop"])
+    pnl -->|generates| plan["docs/plans/PPP-plan.md"]
+
+    plan --> pe["/w:plan-exec"]
+    pe -->|starts| pel(["plan-exec-loop"])
+    pel -->|read/update| plan
+    pel -->|writes tools| tools["docs/tools/"]
+    pel -->|artifacts| sess[".workflow/sessions/\nSCRIPTS.sql · DECISION"]
+    sess -.->|export-* (separate step)| outd["docs/scripts · manuals · diagrams · reports"]
+
+    promptq(["prompt"]) --> q["/w:quick"]
+    q -->|starts| ql(["quick-loop"])
+```
+
+**Pipeline reading:** SPEC defines *what* (refined spec) → PLANIFICATION defines *how* (plan) and *executes it* → QUICK is a lightweight shortcut for scoped work that does not warrant spec or plan.
+
+> **`docs/` boundary:** each flow only touches its own folders — **SPEC** → `docs/specs`; **PLAN** → `docs/plans` + `docs/tools`. The rest of `docs/` (`scripts`, `manuals`, `diagrams`, `reports`) is written **only** by `export-*` skills (a separate, never-automatic step). See [`../loops/`](../loops/) and workflow-exports reference.
+
+## Schema of each command file
+
+Each `<command>.md` in this bundle uses this frontmatter + body structure:
+
+| Field | Description |
+|---|---|
+| `description:` | One line: what + when (drives discovery in `/`-picker) |
+| `argument-hint:` | Argument signature for the user |
+| `allowed-tools:` | YAML list; always includes `Skill` when a loop/export skill is invoked |
+| Body | 1-3 orienting lines, then the invocation (Skill tool or `aw` CLI), `## Plan mode`, `## Resources` |
+
+## 6 Hard invariants (never violate)
+
+1. **No auto-export**: loops **never** graduate/export to `docs/`. Only `export-*` does, explicitly.
+2. **Each flow touches only its `docs/` folders**: SPEC→`specs`; PLAN→`plans`+`tools`; QUICK→none; rest→`export-*`.
+3. **Spec and plan are documents** (`docs/`), not artifacts.
+4. **DB scripts-only**: AI **never executes DML/DDL**; migrations live in `SCRIPTS.sql` (type B) and are delivered via `export-scripts`. Only read-only queries via MCP.
+5. **Git-safe**: verify branch before editing; **propose** commits by source; never `push`/`--amend`/`--no-verify`.
+6. **All loops**: gap-driven convergent · `AskUserQuestion` with ≤3 content tabs + 1 `flow` tab (`Compactar`/`Cerrar`) always · compact/resume · `Cerrar` persists `CHECKPOINT`+`BACKLOG`.
+
+## Index
+
+| Command | File | Mode |
+|---|---|---|
+| `workspace-init` | [`workspace-init.md`](workspace-init.md) | single-pass, interactive (bootstrap) |
+| `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-exec` | [`plan-exec.md`](plan-exec.md) | starts `plan-exec-loop` |
+| `quick` | [`quick.md`](quick.md) | starts `quick-loop` |
+| `export-scripts` | [`export-scripts.md`](export-scripts.md) | single-pass, read-only |
+| `export-manuals` | [`export-manuals.md`](export-manuals.md) | single-pass, read-only |
+| `export-diagrams` | [`export-diagrams.md`](export-diagrams.md) | single-pass, read-only |
+| `export-reports` | [`export-reports.md`](export-reports.md) | single-pass, read-only |

package/skills/w/commands/export-diagrams.md

@@ -0,0 +1,35 @@
+---
+description: Genera diagramas C4/mermaid en docs/diagrams/ a partir del código fuente y el plan-doc (AS-IS/TO-BE). Single-pass, explícito.
+argument-hint: [--tipo <c4|mermaid|ambos>] [--sesiones <ids>] [--dry-run]
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Skill",
+  ]
+---
+
+# export-diagrams — exportar diagramas
+
+Lee el código de las fuentes del workspace + el plan-doc (secciones `AS-IS`/`TO-BE`) y genera diagramas C4 / mermaid en `docs/diagrams/`. Single-pass, read-only sobre sesiones. Invoca el skill `export-diagrams`.
+
+```
+Skill: export-diagrams
+args: $ARGUMENTS
+```
+
+## Qué produce
+
+- `docs/diagrams/`: diagramas C4 y/o mermaid, numerados, cross-session.
+- **No** muta sesiones ni abre/cierra loops.
+- Solo escribe en `docs/diagrams/`.
+
+## Plan mode
+
+Describe los diagramas que generaría (tipo, componentes cubiertos) sin escribir archivos.
+
+## Resources
+
+- Export skill: `../exports/export-diagrams/SKILL.md`
+- Design reference: `docs/referencias/workflow-exports/README.md`

package/skills/w/commands/export-manuals.md

@@ -0,0 +1,35 @@
+---
+description: Genera manuales de usuario/operación en docs/manuals/ consolidando sesiones, DECISION, plan-doc y código fuente. Single-pass, explícito.
+argument-hint: [--sessions <ids>] [--audiencia <usuario|operacion>] [--dry-run]
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Skill",
+  ]
+---
+
+# export-manuals — exportar manuales
+
+Consolida sesiones + artefactos `DECISION` + plan-doc (`Final behavior`) + código fuente y genera documentación de usuario/operación en `docs/manuals/`. Single-pass, read-only sobre sesiones. Invoca el skill `export-manuals`.
+
+```
+Skill: export-manuals
+args: $ARGUMENTS
+```
+
+## Qué produce
+
+- `docs/manuals/`: manuales consolidados, cross-session, dedup.
+- **No** muta sesiones ni abre/cierra loops.
+- Solo escribe en `docs/manuals/`.
+
+## Plan mode
+
+Describe el alcance de los manuales que generaría (secciones, sesiones fuente) sin escribir archivos.
+
+## Resources
+
+- Export skill: `../exports/export-manuals/SKILL.md`
+- Design reference: `docs/referencias/workflow-exports/README.md`

package/skills/w/commands/export-reports.md

@@ -0,0 +1,35 @@
+---
+description: Genera un informe ejecutivo/funcional en docs/reports/ consolidando el corpus de sesiones (spec, CONCLUSIONS, DECISION), el plan-doc y el estado de docs/. Single-pass, explícito.
+argument-hint: [--sesiones <ids>] [--tipo <ejecutivo|funcional>] [--dry-run]
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Skill",
+  ]
+---
+
+# export-reports — exportar informes
+
+Consolida el corpus completo de sesiones (`CONCLUSIONS`, `DECISION`, spec) + plan-doc (estado) + `docs/` y genera un informe ejecutivo o funcional en `docs/reports/`. Single-pass, read-only sobre sesiones. Invoca el skill `export-reports`.
+
+```
+Skill: export-reports
+args: $ARGUMENTS
+```
+
+## Qué produce
+
+- `docs/reports/`: informe consolidado, cross-session, con dedup y estado de avance.
+- **No** muta sesiones ni abre/cierra loops.
+- Solo escribe en `docs/reports/`.
+
+## Plan mode
+
+Describe el alcance e índice del informe que generaría (secciones, sesiones fuente, estado de avance) sin escribir archivos.
+
+## Resources
+
+- Export skill: `../exports/export-reports/SKILL.md`
+- Design reference: `docs/referencias/workflow-exports/README.md`

package/skills/w/commands/export-scripts.md

@@ -0,0 +1,35 @@
+---
+description: Exporta scripts de BD (SCRIPTS.sql tipo-B) de N sesiones a docs/scripts/ como forwards numerados + rollback. Paso explícito y aparte — nunca automático.
+argument-hint: [--sessions <ids>] [--dry-run]
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Skill",
+  ]
+---
+
+# export-scripts — exportar scripts de BD
+
+Promueve los artefactos `SCRIPTS.sql` (tipo B — migraciones) de N sesiones de `.workflow/sessions/` a `docs/scripts/`. Single-pass, read-only sobre sesiones. Invoca el skill `export-scripts`.
+
+```
+Skill: export-scripts
+args: $ARGUMENTS
+```
+
+## Qué produce
+
+- `docs/scripts/`: forwards numerados de forma continua (cross-session, dedup) + `00-ROLLBACK.sql`.
+- **No** muta sesiones ni abre/cierra loops.
+- La IA **nunca ejecuta** los scripts — solo los consolida y entrega.
+
+## Plan mode
+
+Describe los scripts que consolidaría y la estructura de `docs/scripts/` que generaría, sin escribir archivos.
+
+## Resources
+
+- Export skill: `../exports/export-scripts/SKILL.md`
+- Design reference: `docs/referencias/workflow-exports/README.md`

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

@@ -0,0 +1,46 @@
+---
+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>
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "Skill",
+  ]
+---
+
+# 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).
+
+Invocar el skill:
+
+```
+Skill: plan-exec-loop
+args: $ARGUMENTS
+```
+
+## 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).
+- 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/`.
+- **No exporta** a `docs/scripts`, `docs/manuals`, `docs/diagrams`, `docs/reports` — eso lo hacen los `export-*` como paso aparte.
+- Scripts de BD (migraciones) van a `SCRIPTS.sql` tipo B; la IA **nunca ejecuta DML/DDL**, solo lecturas read-only vía MCP.
+
+## Resumable
+
+Mismo patrón que los demás loops: detecta CHECKPOINT existente y continúa desde ahí.
+
+## Plan mode
+
+El skill describe fase por fase lo que ejecutaría, qué archivos tocaría, y qué commits propondría, sin aplicar cambios.
+
+## Resources
+
+- Loop skill: `../loops/plan-exec-loop/SKILL.md`
+- Design reference: `docs/referencias/workflow-commands/plan-exec.md`

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

@@ -0,0 +1,44 @@
+---
+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>
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "Skill",
+  ]
+---
+
+# 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).
+
+## Resolución de input
+
+El skill evalúa `$ARGUMENTS`:
+
+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.
+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.
+
+Invocar el skill:
+
+```
+Skill: plan-new-loop
+args: $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.
+
+## Plan mode
+
+El skill resuelve el input según las 3 reglas de arriba y describe las acciones del loop que ejecutaría, sin arrancar la iteración.
+
+## Resources
+
+- Loop skill: `../loops/plan-new-loop/SKILL.md`
+- Design reference: `docs/referencias/workflow-commands/plan-new.md`

package/skills/w/commands/quick.md

@@ -0,0 +1,39 @@
+---
+description: Atajo liviano para trabajo acotado (fix, ajuste, chore) que no amerita spec ni plan. Inicia quick-loop. No toca docs/. Escala a SPEC/PLAN si la tarea crece.
+argument-hint: <prompt con la tarea acotada>
+allowed-tools:
+  [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "Skill",
+  ]
+---
+
+# 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).
+
+Invocar el skill:
+
+```
+Skill: quick-loop
+args: $ARGUMENTS
+```
+
+## Qué hace el loop
+
+- Edita código en las fuentes del workspace.
+- Artefactos mínimos en la sesión (DECISION lazy, commit propuesto).
+- **No toca `docs/`** ni exporta nada.
+- **Escala** a SPEC/PLAN si emerge complejidad (muchos archivos, ≥2 fuentes, necesita arquitectura, o el cambio es feature/refactor).
+
+## Plan mode
+
+El skill describe los cambios que aplicaría y los archivos que tocaría, sin ejecutarlos.
+
+## Resources
+
+- Loop skill: `../loops/quick-loop/SKILL.md`
+- Design reference: `docs/referencias/workflow-commands/quick.md`