@tacuchi/agent-workflow-cli 11.0.0 → 12.0.0

package/skills/w/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: workflow
+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
+  `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/
+  skill to reach for.
+---
+
+# workflow — agent-workflow overview
+
+## Role
+
+`overview` — built-in default. The orientation skill for the whole bundle. Rebindable in `.workflow/skills.toml`, but rarely is.
+
+## Purpose
+
+Explicar el **modelo completo** de agent-workflow para que un agente sepa: qué invoca el usuario, qué corre la IA, dónde aterriza cada entregable, y qué reglas no se rompen. Es el mapa; el detalle fino vive en cada loop/command/export/role.
+
+## Composed by
+
+Cualquiera que necesite orientación — un loop al arrancar, un agente nuevo en el workspace, o el usuario preguntando "¿cómo funciona esto?".
+
+## Knowledge
+
+### Workspace (sin modos)
+
+Un solo concepto: **workspace**. No hay project/hub. La carpeta donde arranca el agente se vuelve workspace con `/w:workspace-init` (scaffolding `.workflow/` + `docs/` + bloque `WORKSPACE` en CLAUDE.md + `.workflow/skills.toml`). Tiene 1+ fuentes (repos); "standalone" = una sola fuente.
+
+### The 3-layer architecture + `docs/` zone
+
+```
+USUARIO invoca
+  LAYER 1 · COMMANDS (lo único que el usuario invoca)
+    FLOWS:   spec-new · spec-refine · plan-new · 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
+        │ crea / lee / escribe
+        ▼
+  LAYER 3 · SESSIONS + ARTIFACTS (.workflow/sessions/ — efímero, interno)
+        │ los export-* leen artefactos
+        ▼
+  ZONA docs/ — documentos permanentes, cara al usuario
+    specs · plans · tools (flujos) · scripts · manuals · diagrams · reports (export-*)
+```
+
+- **Layer 1** — alto nivel. Single-pass o arranca un loop. Sin lógica de iteración.
+- **Layer 2** — la IA itera entera hasta converger. Sin invocación humana directa.
+- **Layer 3** — efímero, interno, process-only. Nadie lo invoca a mano.
+
+### The 3 flows
+
+| 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` · `docs/tools` | `plan-new-loop` · `plan-exec-loop` |
+| **QUICK** (atajo liviano) | `quick` | — | `quick-loop` |
+
+Cadena típica: prompt → `spec-new` genera `docs/specs/NNN-spec.md` → `spec-refine` corre el loop → `NNN-spec-refined.md` → `plan-new` → `docs/plans/PPP-plan.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-*`.
+
+### The commands (`/w:` namespace)
+
+- `/w:workspace-init` — inicializa el workspace.
+- `/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-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/`.
+
+### The loops (Layer 2)
+
+Un loop es una skill que enseña a la IA **cómo iterar** hasta un entregable. Propiedades comunes (el chasis, en `spec-refine-loop`, lo heredan los demás):
+
+1. **Gap-driven convergente** — cada ciclo: detecta huecos → resuelve (pregunta al humano o investiga) → integra → repite hasta converger.
+2. **Puede crear sessions internas** — si el trabajo es profundo (ej. investigar el código), el loop crea una session (`research`, etc.), maneja sus artefactos en `.workflow/sessions/`, la cierra y reporta. El usuario nunca crea esas sessions.
+3. **AskUserQuestion con dos tipos de tab**:
+   - **tab(s) de contenido** — la pregunta real del momento.
+   - **tab `flow`** — control de ciclo de vida, **siempre presente**: `Compactar` / `Cerrar`. Responder el tab de contenido sin tocar `flow` = seguir iterando.
+4. **Escribe solo en su carpeta `docs/`** — y nunca exporta el resto (eso es de `export-*`).
+
+`flow → Compactar` = checkpoint + `/compact` del host y reanuda. `flow → Cerrar` = persiste `CHECKPOINT` + `BACKLOG`, cierra sessions internas, termina.
+
+`spec-new` no tiene loop (single-pass): **5 comandos / 4 loops**.
+
+### The `export-*` family (única vía artefacto → `docs/`)
+
+| Export | Lee | Produce |
+|---|---|---|
+| `export-scripts` | `SCRIPTS.sql` (migraciones) de N sesiones | `docs/scripts/` (forwards numerados + `00-ROLLBACK.sql`) |
+| `export-manuals` | sesiones + decisiones + plan + código | `docs/manuals/` |
+| `export-diagrams` | código de las fuentes + plan (AS-IS/TO-BE) | `docs/diagrams/` (C4 / mermaid) |
+| `export-reports` | corpus de sesiones + plan + `docs/` | `docs/reports/` (informe ejecutivo/funcional) |
+
+Comunes: Capa 1, explícitos (los invoca el usuario, nunca un loop) · single-pass, read-only sobre sesiones · cross-session (consolidan N sesiones + `docs/`) · sin loop ni sessions internas (opciones por args).
+
+### Capability skills + `.workflow/skills.toml`
+
+Un loop **no** compone una skill concreta; compone una **capacidad por su rol** (ej. `ui-design`). Qué skill cumple el rol lo decide la config, no el loop. Cambiar de implementación = una línea del config.
+
+```toml
+[skills]
+ui-design        = "ui-spec"          # built-in default
+sql              = "sql"
+git              = "git"
+coding-standards = "coding-standards"
+writing          = "writing"
+testing          = "off"              # capacidad desactivada
+# ui-design      = "acme/figma-spec"  # ← skill de tercero (vía skills.sh)
+```
+
+**Cascada de resolución**: built-in default → `~/.workflow/skills.toml` (global, PC) → `.workflow/skills.toml` (workspace). El workspace pisa al global; el global al default. Rol sin binding → built-in default. `off` → desactivada (el loop sigue sin ella; si era necesaria, lo dice o pregunta).
+
+Catálogo de roles y su default:
+
+| Role | Default | Tier | Composed by |
+|---|---|---|---|
+| `ui-design` | `ui-spec` | must | `spec-refine-loop` (UI) |
+| `sql` | `sql` | must | research · `plan-exec-loop` · `quick-loop` · `export-scripts` |
+| `git` | `git` | must | `plan-exec-loop` · `quick-loop` |
+| `coding-standards` | `coding-standards` | must | `plan-exec-loop` · `quick-loop` |
+| `writing` | `writing` | must | todos los loops · `export-manuals`/`export-reports` |
+| `research` | `research` | should | todos los loops (on-demand) |
+| `testing` | `testing` | should | `plan-exec-loop` · `quick-loop` |
+| `tools` | `tools` | should | `plan-exec-loop` |
+| `diagrams` | `diagrams` | should | `export-diagrams` |
+| `overview` | `workflow` | should | cualquiera (orientación) |
+
+El **chasis del loop** NO se bindea: **es** el loop, no es enchufable.
+
+### The 6 hard invariants
+
+1. **Sin auto-export** — los loops nunca graduan/exportan a `docs/`. Solo `export-*` lo hace, explícito.
+2. **Cada flujo toca solo sus carpetas `docs/`** — SPEC→`specs` · PLAN→`plans`+`tools` · QUICK→ninguna · resto→`export-*`.
+3. **El spec y el plan son documentos** (`docs/`), no artefactos de sesión.
+4. **BD solo-scripts** — la IA nunca ejecuta DML/DDL; las migraciones quedan en `SCRIPTS.sql` y las aplica el usuario. Solo lecturas read-only vía MCP.
+5. **Git seguro** — rama esperada verificada antes de editar; commits propuestos por fuente; nunca `push`/`--amend`/`--no-verify`.
+6. **Chasis de loops** — gap-driven convergente · `AskUserQuestion` con ≤3 tabs de contenido + 1 tab `flow` (`Compactar`/`Cerrar`) siempre · compact/resume · `Cerrar` persiste `CHECKPOINT`+`BACKLOG`.
+
+## Output
+
+Ninguno. Es orientación pura: no escribe documentos ni artefactos.
+
+## Source
+
+Autorada del modelo de diseño (`docs/referencias/`): README de arquitectura (3 capas + 6 invariantes), `workflow-commands/`, `workflow-loops/`, `workflow-exports/`, `workflow-skills/`. Reemplaza la orientación del bundle viejo (`session` + flows dev/design/analyze, CLI v11), que se descarta.

package/skills/w/artifacts/README.md

@@ -0,0 +1,60 @@
+# workflow-artifacts — Artifact catalog (Layer 3)
+
+> Reference for the **new agent-workflow model**. This folder contains the **artifact templates**: process files managed by **sessions** inside `.workflow/sessions/`.
+> Siblings: [`../commands/`](../commands/) (Layer 1) · [`../loops/`](../loops/) (Layer 2) · [`../roles/`](../roles/) (pluggable skills).
+
+---
+
+## Artifact vs `docs/` document
+
+Central distinction of the model:
+
+| | **Artifact** (this catalog) | **`docs/` document** |
+|---|---|---|
+| Nature | Process, ephemeral | Deliverable, permanent |
+| Location | `.workflow/sessions/NNN-…/` | `docs/<category>/` |
+| Who manages it | a **loop**, through a **session** | produced by a loop/command at "save" time |
+| User-facing | No (internal) | Yes |
+| Examples | `CHECKPOINT`, `ANALYSIS-FILE`, `CONCLUSIONS`, `SCRIPTS.sql`, `TASKS`, `DECISION` | `specs`, `plans`, `manuals`, `scripts`, `tools`, `diagrams`, `reports` |
+
+> An artifact may be **promoted** to a `docs/` document (e.g. `SCRIPTS.sql` → `docs/scripts/`) — but **only via dedicated `export-*` skills**, **never** automatically by the loops. The spec and the plan **are not** artifacts: they are documents.
+
+---
+
+## Sessions & their artifacts
+
+Sessions are created by the loops as needed. Each session type manages a set of artifacts:
+
+| Session type | Created by | Artifacts | Notes |
+|---|---|---|---|
+| **research** | all loops, on-demand | `SESSION` · `ANALYSIS-FILE` · `CONCLUSIONS` · `SCRIPTS.sql` (if DB) | On-demand, **not resumable** (run-and-close). No own `CHECKPOINT`/`BACKLOG` — those live in the owning `refine/control` session. |
+| **refine / control** | `spec-refine-loop` · `plan-new-loop` · `plan-exec-loop` | `SESSION` · `CHECKPOINT` · `BACKLOG` (on close) | Owns the loop run. Tracks open research sessions. |
+| **exec** (one per phase) | `plan-exec-loop` | `SESSION` · `DECISION` · `SCRIPTS.sql` · `CHECKPOINT` | No `TECHNICAL-NOTE` or own `TASKS` — detail lives in the plan-doc (living). `TASKS` is optional for internal breakdown. |
+| **quick** (one, lightweight) | `quick-loop` | `SESSION` · `DECISION` · `SCRIPTS.sql` · `CHECKPOINT` · `BACKLOG` (on close) | Single session, single commit. |
+
+> **PLAN note (rich plan):** the plan-doc (`docs/plans/PPP-plan.md`) absorbs inline the `TECHNICAL-NOTE` level (Solution/Impacted/AS-IS/TO-BE/Validations…) **and** the `Phases`/`Tasks`. Therefore exec sessions do **not** carry a `TECHNICAL-NOTE` or own `TASKS` artifact: the technical detail and progress live in the plan-doc (living). `TASKS` remains as an optional artifact for sessions that need their own internal breakdown.
+
+---
+
+## Common artifacts (any session)
+
+`SESSION` (descriptor) · `CHECKPOINT` (resume) · `SCRIPTS.sql` (read-only queries **executable** + DDL/DML migrations **deliverable**, not executed) · `TASKS` · `BACKLOG`.
+
+---
+
+## Index (folders)
+
+| Folder | Role | Contains |
+|---|---|---|
+| [`artifacts-core/`](artifacts-core/) | common to any session | `SESSION` · `TASKS` · `CHECKPOINT` · `BACKLOG` · `SCRIPTS.sql` |
+| [`artifacts-research/`](artifacts-research/) | `research` session | `ANALYSIS-FILE` · `CONCLUSIONS` |
+| [`artifacts-dev/`](artifacts-dev/) | `exec` session | `DECISION` · `TECHNICAL-NOTE` |
+
+---
+
+## Invariants (hard rules — do not break)
+
+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 — they never live inside a session.
+4. **DB write-only scripts**: the AI **never executes DML/DDL**; migrations stay in `SCRIPTS.sql` (type B) and are delivered via `export-scripts`. Only read-only queries (type A) are executed via MCP.

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

@@ -0,0 +1,12 @@
+# BACKLOG.md — deferred items and follow-ups (common)
+
+> What it is: items deferred or surfaced during the session that do not block closure but should not be lost. Written by the loop when `Cerrar` is triggered. Owned by `refine/control` and `quick` sessions.
+
+## Deferred (text):
+List of phases/tasks (ref: plan-doc `docs/plans/PPP-plan.md`; or `TASKS.md` if the session created its own breakdown) deferred with reason.
+
+## Followups (text):
+List of activities / suggestions / dependencies for future follow-up.
+
+## Notes (list):
+Miscellaneous notes.

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

@@ -0,0 +1,22 @@
+# CHECKPOINT.md — session resume state (common)
+
+> What it is: the resume state of a session. Written by the loop when the user triggers `Compactar` or `Cerrar`. Allows the loop to resume exactly where it left off.
+> Owned by: `refine/control` sessions (and `exec` / `quick` sessions that carry a checkpoint).
+
+## Activity (text):
+Summary of the activity done so far.
+
+## Critical context (text):
+Critical context / key decisions / references to other artifacts or documents needed to continue.
+
+## Completed (list):
+List of completed phases (ref: plan-doc `docs/plans/PPP-plan.md`; or `TASKS.md` if the session created its own breakdown).
+
+## Excluded (list):
+List of excluded phases/tasks (ref: plan-doc `docs/plans/PPP-plan.md`; or `TASKS.md`) with reason.
+
+## Pending (list):
+List of pending phases (ref: plan-doc `docs/plans/PPP-plan.md`; or `TASKS.md`) still to do.
+
+## Next (text):
+Next phase/task (ref: plan-doc `docs/plans/PPP-plan.md`; or `TASKS.md`) to continue from on resume.

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`