@tacuchi/agent-workflow-cli 11.0.1 → 12.2.0

package/skills/w/loops/quick-loop/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: quick-loop
+description: >-
+  El atajo liviano de agent-workflow: resuelve una tarea acotada (un fix, un
+  ajuste pequeño) directamente desde el prompt del usuario, editando código con
+  ceremonia mínima. Heir del chasis spec-refine-loop (motor gap-driven mínimo,
+  research on-demand con regla BD read-only, AskUserQuestion con ≤3 tabs de
+  contenido + 1 tab flow Compactar/Cerrar siempre, compact/resume con Cerrar que
+  persiste CHECKPOINT + BACKLOG) y de plan-exec-loop (git seguro: rama esperada
+  antes de editar + commit propuesto, nunca push/--amend/--no-verify; la IA
+  nunca ejecuta DML, migraciones a SCRIPTS.sql; sin auto-export). Sus deltas: sin
+  fases ni plan-doc (el prompt ES la tarea), una sola session ligera
+  (<slug>-quick), un solo commit; y escalación con handoff si la tarea crece
+  (propone subir a SPEC/PLAN dejando el código a medias como contexto). NO toca
+  docs/. Lo arranca /w:quick y es reanudable. Invocar para cambios pequeños y
+  directos que no ameritan spec ni plan formal.
+---
+
+# quick-loop
+
+> **Heir** del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md) + las políticas de ejecución de [`plan-exec-loop`](../plan-exec-loop/SKILL.md). Aquí **solo** los deltas de QUICK.
+
+## Flow
+QUICK
+
+## Layer
+2 — la IA lo corre entero (loop mínimo).
+
+## Started by
+`/w:quick` — **reanudable** (mismo mecanismo de resume del chasis).
+
+## Reads
+— (el prompt del usuario; no hay documento de entrada).
+
+## Writes
+- Edita código en las fuentes (cambio mínimo).
+- Artefactos de la session en `.workflow/sessions/`.
+- **NO toca `docs/`** (sin doc, sin auto-export).
+
+## Internal session
+
+- **SIEMPRE** crea una session ligera `<slug>-quick` (Type = `quick`, ≈ `exec`): `SESSION` · `DECISION` · `SCRIPTS.sql` · `CHECKPOINT` (+ `BACKLOG` al cerrar). Una sola session (no exec-por-fase).
+
+## Inherits
+
+- del **chasis** [`spec-refine-loop`](../spec-refine-loop/SKILL.md): gap-driven (mínimo), `AskUserQuestion` ≤3 + `flow` (`Compactar`/`Cerrar`), `research` on-demand + regla BD read-only (pregunta MCP si >1 sin default → `SCRIPTS.sql` → ejecuta read-only), compact/resume, `Cerrar` persiste `CHECKPOINT`+`BACKLOG`.
+- de [`plan-exec-loop`](../plan-exec-loop/SKILL.md): **git** (rama segura antes de editar + commit propuesto; nunca `push`/`--amend`/`--no-verify`), **BD** (la IA nunca ejecuta DML; migraciones → `SCRIPTS.sql` de la session), **sin auto-export** (no toca otras carpetas `docs/`).
+
+## Composes
+
+`git` · `coding-standards` · `testing` (validación puntual) · `sql` (regla BD) · `writing` · `research`. Resueltas por `.workflow/skills.toml`.
+
+## Delta QUICK — minimal ceremony
+
+- **Sin fases, sin plan-doc**: el prompt **es** la tarea (una sola unidad). No hay roadmap.
+- **Una sola session** (no exec-por-fase). **Un solo commit** propuesto al final.
+- **Escalación + handoff**: si la tarea crece (muchos archivos / ≥2 fuentes / necesita arquitectura) → propone subir a **SPEC/PLAN**. Si el usuario acepta:
+  - el **código ya editado queda** en el working tree (no se revierte) **y se registra** en `CHECKPOINT` + `BACKLOG` ("cambios sin commitear en `<fuente>` — código a medias; decidir commit/descartar al retomar") — reusando **ambas** mitades del patrón "commit rechazado" de plan-exec (no revertir **y** registrar lo sin commitear). Crítico en la rama **SPEC**, que no retoma el working tree;
+  - la session quick va a `finalize`, persistiendo `CHECKPOINT` + `BACKLOG` con un **puntero** al spec/plan sembrado (Followups: "escalado a `docs/specs/NNN` o `docs/plans/PPP` — retomar ahí");
+  - los artefactos (`DECISION`, `SCRIPTS.sql`) **quedan en la session quick** como contexto referenciable por la nueva session (no se migran);
+  - **asimetría**: escalar a **PLAN** puede **absorber** el avance (plan-exec retoma el working tree existente); escalar a **SPEC** **reinicia** el ciclo de diseño y trata el código a medias como **contexto/referencia**, no como trabajo ya ingerido.
+
+## Sequence
+
+```
+quick-loop(prompt):
+  s = create_or_resume(<slug>-quick)        # siempre session ligera
+  trabajar la tarea (loop mínimo):
+    verificar rama esperada por fuente (branch-check); si no → pausar + resolver
+    editar código (cambio mínimo)
+    si consulta BD read-only → SCRIPTS.sql + ejecutar read-only
+    si cambio BD (DDL/DML) → SCRIPTS.sql (artefacto session, NO ejecutar)
+    si decisión no obvia → DECISION
+    si duda/gap → research session ó AskUserQuestion        # chasis
+    si la tarea CRECE → proponer escalar a SPEC/PLAN
+        si acepta → handoff (código queda; BACKLOG→spec/plan sembrado) → goto finalize
+  validación puntual (test si aplica)
+  proponer commit (aprobar antes)                            # nunca push/amend/--no-verify
+  AskUserQuestion(contenido: [Cerrar tarea, Preguntar algo más], flow: [Compactar, Cerrar])
+finalize: CHECKPOINT + BACKLOG (si queda algo) + cerrar session + reportar
+```
+
+```mermaid
+flowchart TD
+    S["create_or_resume session <slug>-quick"] --> G["branch-check por fuente"]
+    G -->|ok| DO["editar código · BD→SCRIPTS.sql · DECISION<br/>(duda→research/AskUserQuestion)"]
+    G -->|rama ≠| PA["pausar + resolver"]
+    PA --> G
+    DO --> GROW{"¿la tarea creció?"}
+    GROW -->|sí| ESC["escalar a SPEC/PLAN<br/>código queda · BACKLOG→spec/plan sembrado"]
+    ESC --> FIN
+    GROW -->|no| V["validación puntual"]
+    V --> CM["proponer commit (aprobar)"]
+    CM --> Q["AskUserQuestion[Cerrar · Preguntar más]<br/>flow[Compactar · Cerrar]"]
+    Q --> FIN["finalize: CHECKPOINT + BACKLOG + cerrar"]
+```
+
+## Convergence / exit
+
+- Tarea hecha + commit (o aprobado saltarlo) → `Cerrar`.
+- `Cerrar`/`Compactar` (tab flow) → persiste `CHECKPOINT` + `BACKLOG` (reanudable).
+- **Sin export**: nada va a `docs/`. Si algo amerita preservarse → se promueve aparte vía `export-*`, o se escala a SPEC/PLAN.

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

@@ -0,0 +1,222 @@
+---
+name: spec-refine-loop
+description: >-
+  El CHASIS de los loops de agent-workflow. Refina un spec borrador
+  (docs/specs/NNN-spec.md) hasta un spec refinado sin ambigüedad
+  (docs/specs/NNN-spec-refined.md) mediante un motor gap-driven convergente:
+  detecta huecos/ambigüedades, los resuelve preguntando al humano (lo que
+  depende de su intención) o investigando de forma autónoma vía sessions de
+  research (lo que se responde leyendo el repo/datos), integra y repite hasta
+  converger. Compone la capacidad ui-design (built-in ui-spec) cuando el
+  requerimiento involucra UI. Lo arranca el comando /w:spec-refine y es
+  reanudable (4 casos de resume). Usa AskUserQuestion con ≤3 tabs de contenido
+  + 1 tab flow (Compactar/Cerrar) siempre presente; Cerrar persiste CHECKPOINT
+  + BACKLOG. Es el patrón de referencia que heredan plan-new-loop,
+  plan-exec-loop y quick-loop. Invocar cuando haya que refinar/desambiguar una
+  especificación antes de planificar.
+---
+
+# spec-refine-loop
+
+> **El CHASIS.** Primer loop diseñado en detalle; patrón de referencia que heredan los demás loops (`plan-new-loop`, `plan-exec-loop`, `quick-loop`). Si editas el motor, edítalo aquí.
+
+## Flow
+SPEC
+
+## Layer
+2 — la IA lo corre entero (gap-driven). El usuario no conduce el ciclo; solo responde tabs de contenido y dirige el ciclo de vida por el tab `flow`.
+
+## Started by
+`/w:spec-refine` — **reanudable**. Detecta el estado previo y arranca según corresponda (ver *Compact / resume*, 4 casos).
+
+## Reads
+- `docs/specs/NNN-spec.md` (borrador), **o**
+- `docs/specs/NNN-spec-refined.md` si **ya existe** un refinado previo → se re-refina incremental sobre el refined (NO sobre el borrador stale).
+
+## Writes
+`docs/specs/NNN-spec-refined.md` (cuando el usuario elige `Guardar especificación refinada`). Si el archivo **ya existe**, **sobrescribe con confirmación** del usuario.
+
+> **Invariante de boundary:** este loop escribe **solo** en `docs/specs`. Nunca gradúa/exporta otros artefactos a `docs/` — eso es trabajo de `export-*`, aparte.
+
+## Internal sessions (managed)
+
+El loop crea y maneja sus sessions en `.workflow/sessions/`. El usuario nunca las crea.
+
+| Session | When | Artifacts | Role |
+|---|---|---|---|
+| **refine session** `<spec>-spec-refine/` | al arrancar el loop (o se reanuda) | `SESSION.md` · `CHECKPOINT.md` (· `BACKLOG.md` al cerrar) | Dueña del run. Guarda el avance al `Compactar` y al `Cerrar`; habilita el resume. Type = `refine`. |
+| **research session** `<run>-research-*/` | on-demand, por cada gap factual | `SESSION.md` · `ANALYSIS-FILE.md` → `CONCLUSIONS.md` (+ `SCRIPTS.sql` si consulta BD) | Investiga, concluye, **cierra y reporta**. Puede cerrar **inconclusa**. Type = `research`; on-demand, **no reanudable** (run-and-close, sin `CHECKPOINT`/`BACKLOG` propios). |
+
+> El spec **nunca** entra en una session; vive en `docs/specs/`.
+>
+> `<run>` = id de la session dueña del loop padre, que prefija sus sessions hijas: `<spec>-spec-refine`, `<plan>-plan-new`, `<plan>-plan-exec`, `<slug>-quick`. Así el patrón de naming es exacto en cualquier flujo que herede este chasis.
+
+**CLI** (asunción de naming; los subcomandos se implementan en paralelo — no bloquear):
+- `aw session-create --type refine --name <spec>-spec-refine` / `aw session-resume --code <…>` (detecta `CHECKPOINT`).
+- `aw session-create --type research --name <run>-research-<gap>` para cada gap factual.
+- `aw checkpoint-write` / `aw checkpoint-read` para el resume.
+- `aw session-close` al cerrar (con razón); `aw session-artifacts` para inspeccionar.
+
+## Composes
+
+Cuando el requerimiento involucra **UI**, compone la capacidad **`ui-design`** (default built-in `ui-spec`; rebindeable vía `.workflow/skills.toml`): autora el UI spec nativamente (esquema `Screen`, vocabulario, formato). El loop aporta la iteración/Q&A que el viejo servicio no tenía (design-system, tema, variantes, desambiguación) y lo integra como sección `## UI spec` del spec.
+
+Otras capacidades transversales que el chasis usa siempre: `research` (research on-demand), `sql` (regla BD en research), `writing` (redacción del refined). Todas se resuelven por config; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta.
+
+## Deliverable schema (`NNN-spec-refined.md`)
+
+Más rico que el borrador: mismas secciones **completadas** + dos nuevas (`Refinement decisions`, `Q&A traceability`).
+
+```markdown
+# Spec NNN (refined) — <slug>
+
+> Derivado de `NNN-spec.md` · refinado por spec-refine-loop
+
+## Requirement            (afinado, sin ambigüedad)
+## Context                (completo)
+## Scope                  (In / Out claros)
+## Acceptance criteria    (testables, - [ ])
+## Assumptions            (declarados)
+
+## UI spec                (opt. — si involucra UI; vía capacidad ui-design / skill ui-spec)
+Screen (JSON) + render Markdown.
+
+## Refinement decisions   ← NEW
+Qué se definió al refinar y por qué. Incluye lo resuelto vía research
+(con referencia a la research session / CONCLUSIONS).
+
+## Q&A traceability       ← NEW
+Cada duda preguntada al humano + la respuesta elegida.
+
+## Open questions         (idealmente "None"; lo que quede se difiere)
+```
+
+## Gap taxonomy (= weak sections of the schema)
+
+`detect_gaps(work)` busca estas señales; cada una tiene un resolutor:
+
+| Gap | Signal | Resolved by |
+|---|---|---|
+| Requirement vago | el qué/por qué ambiguo | **humano** |
+| Context incompleto | sistemas/componentes sin identificar | **research** |
+| Scope borroso | falta `Out`, o In/Out se solapan | **humano** |
+| Criterios no testables | acceptance no verificable | **humano** (derivar + confirmar) |
+| Open questions abiertas | dudas explícitas | según naturaleza |
+| Supuestos ocultos | el spec asume cosas no dichas | **research** valida / **humano** confirma |
+| Contradicción interna | secciones que se contradicen | **humano** |
+
+## Ask-vs-research rule (el discriminador)
+
+Para cada gap, una sola pregunta decide el resolutor:
+
+> *"¿Puedo responder esto leyendo el repo/datos?"* → **research** (autónomo).
+> *"¿Depende de lo que el usuario quiere?"* → **preguntar al humano** (AskUserQuestion).
+
+## Research: autonomy, scope & failure
+
+- **Autónomo**: la IA crea la research session, investiga y reporta **sin pedir permiso**. El humano se entera al integrarse (en `Refinement decisions`) y mantiene control vía el tab `flow`.
+- **Alcance**: workspace + repos asociados (fuentes) + MCPs de BD.
+- **Regla BD** (única excepción a la autonomía):
+  1. **Elección de MCP**: si el gap requiere BD y hay **>1 MCP candidato sin default configurado**, la IA pregunta cuál usar. Esa pregunta va por el **mismo `AskUserQuestion`** como un **tab de contenido** (cuenta dentro del límite ≤3 + `flow`), **antes** de ejecutar queries. Si hay un único MCP o un default, no pregunta.
+  2. Escribe **primero** las queries en `SCRIPTS.sql` de la research session.
+  3. Las ejecuta **read-only** vía MCP (respeta `sql-mutation-guard`: nunca DML/DDL).
+- **Research inconclusa** (BD no disponible, evidencia insuficiente, gap factual irresoluble):
+  - La research session cierra con estado **`inconcluso`** y reporta el motivo (vía su `Success criteria` no cumplido).
+  - El loop **degrada** el gap: lo pasa a **pregunta-al-humano** (próximo batch → `Q&A traceability`) o, si tampoco aplica, lo **difiere** a `## Open questions` del refined.
+  - El gap se marca **"ya intentado vía research"** (`attempts[gap]++`, límite `MAX`) para que `detect_gaps` **no lo re-dispare en bucle** → garantiza convergencia.
+
+## AskUserQuestion (design & batching)
+
+- Límite del host: **máx 4 preguntas/llamada**. Como el tab `flow` va **siempre** → **≤3 tabs de contenido + 1 tab `flow`**.
+- **tab `flow`** (ciclo de vida, siempre presente): `Compactar` | `Cerrar`. Responder solo los tabs de contenido (sin tocar `flow`) = seguir iterando.
+- **Tabs de contenido** posibles:
+  - dudas-de-humano (gaps no factuales);
+  - elección de MCP (regla BD) — antes de ejecutar queries;
+  - en **convergencia**, acción: `Guardar especificación refinada` | `Preguntar algo más`.
+- **Batching**: agrupar hasta 3 gaps de humano en una sola llamada. Si hay más de 3 pendientes, priorizar (los que desbloquean otros gaps primero) y diferir el resto a la próxima vuelta.
+
+## Sequence
+
+```
+spec-refine-loop(spec):
+  input = exists(NNN-spec-refined.md) ? NNN-spec-refined.md : NNN-spec.md   # (#2 resume)
+  refine_session = create_or_resume(<spec>-spec-refine)    # detecta CHECKPOINT
+  work = read(input)  (+ aplicar avance del checkpoint si reanuda)
+  attempts = {}                                            # anti-relanzamiento por gap
+  repeat:
+    gaps = detect_gaps(work)  menos los gaps "agotados"
+    if gaps == ∅: break
+    batch = top ≤3 gaps ; pending_human = []
+    para cada gap en batch:
+      si factual(gap) y attempts[gap] < MAX:
+        si requiere BD y >1 MCP sin default → encolar "elección MCP" en pending_human
+        rs  = create_research_session(gap)
+        res = rs.run_and_close()             # ANALYSIS-FILE → CONCLUSIONS (+SCRIPTS.sql)
+        si res.concluyente: work = integrate(work, res)    # → Refinement decisions
+        si no: attempts[gap]++ ; si attempts[gap] >= MAX → pending_human.push(gap)
+      si no:
+        pending_human.push(gap)
+    si pending_human no vacío:
+      ans = AskUserQuestion(contenido: pending_human (≤3), flow: [Compactar, Cerrar])
+      switch(flow):
+        Compactar → write CHECKPOINT (refine_session) ; /compact ; continue
+        Cerrar    → goto finalize
+      work = integrate(work, ans)            # → Q&A traceability / Open questions
+  # convergió:
+  ans = AskUserQuestion(contenido: [Guardar refinada, Preguntar algo más],
+                        flow: [Compactar, Cerrar])
+  Guardar          → write_with_confirm(NNN-spec-refined.md) ; goto finalize   # (#2)
+  Preguntar algo más → continue
+  flow Compactar/Cerrar → manejar igual
+finalize:
+  write CHECKPOINT (refine_session)                        # (#5) persiste siempre
+  write/update BACKLOG (motivo de cierre + Open questions diferidas)   # (#5)
+  cerrar research sessions abiertas ; cerrar refine_session ; reportar
+```
+
+```mermaid
+flowchart TD
+    S["input = refined si existe, si no borrador<br/>create_or_resume refine session"] --> D{"¿gaps<br/>(no agotados)?"}
+    D -->|no| C["AskUserQuestion<br/>contenido[Guardar refinada · Preguntar más]<br/>flow[Compactar · Cerrar]"]
+    D -->|sí| B["tomar ≤3 gaps"]
+    B --> F{"¿factual y<br/>attempts<MAX?"}
+    F -->|sí| RS["research session<br/>ANALYSIS-FILE → CONCLUSIONS (+SCRIPTS.sql)"]
+    RS --> CC{"¿concluyente?"}
+    CC -->|sí| I1["integrar → Refinement decisions"]
+    CC -->|no| DEG["attempts++ ; degradar a humano / Open questions"]
+    F -->|no| Q["AskUserQuestion<br/>contenido[dudas + elección MCP ≤3]<br/>flow[Compactar · Cerrar]"]
+    Q --> I2["integrar → Q&A traceability"]
+    I1 --> D
+    DEG --> D
+    I2 --> D
+    C -->|Guardar| W["write_with_confirm<br/>NNN-spec-refined.md"]
+    C -->|Preguntar más| D
+    W --> FIN["finalize: CHECKPOINT + BACKLOG<br/>+ cerrar sessions + reportar"]
+```
+
+## Compact / resume
+
+Cuatro casos al ejecutar `/w:spec-refine` sobre un spec:
+
+1. **En curso** (existe `CHECKPOINT.md` en la refine session) → reanuda desde el avance (gaps resueltos, Q&A, `attempts`, research sessions abiertas).
+2. **Sin avance** (no hay CHECKPOINT ni refined) → arranca desde cero leyendo `NNN-spec.md`.
+3. **Ya completado** (existe `NNN-spec-refined.md`, sin CHECKPOINT) → re-refinamiento incremental: input = el **refined** (no el borrador); al `Guardar`, sobrescribe con confirmación.
+4. **`Compactar`** (tab flow) → escribe `CHECKPOINT.md` en la refine session (spec en progreso, gaps restantes, Q&A, `attempts`, research sessions abiertas) → dispara `/compact` del host → reanuda leyendo el checkpoint.
+
+## Convergence / exit
+
+- **Sin gaps materiales** → ofrece `Guardar especificación refinada`.
+- `Guardar` → `write_with_confirm(NNN-spec-refined.md)` y `finalize`.
+- `Cerrar` (tab flow, en cualquier momento) → `finalize`. **`finalize` persiste siempre**: escribe `CHECKPOINT.md` (reanudable) **y** `BACKLOG.md` (motivo de cierre + `Open questions` diferidas), cierra sessions y reporta. Así sobrevive el avance aunque no se haya `Compactar` antes.
+
+## Integration (dónde aterriza cada resolución)
+
+- Resuelto vía **research** → `## Refinement decisions` del refined (+ ref a la research session / `CONCLUSIONS`).
+- Resuelto vía **humano** → `## Q&A traceability` del refined.
+- **Research inconclusa o sin resolver** → `## Open questions` del refined (diferido) + `BACKLOG.md` de la refine session al cerrar.
+
+## Heredan este chasis
+
+- `plan-new-loop` — mismo motor; deltas: plan rico + gap taxonomy de plan.
+- `plan-exec-loop` — mismo motor; deltas: ejecución real (código/BD/git), session por fase, sin auto-export.
+- `quick-loop` — mismo motor (mínimo); hereda además git/BD/no-export de `plan-exec-loop`.

package/skills/w/roles/README.md

@@ -0,0 +1,154 @@
+# roles/ — Capability role catalog
+
+> Built-in default implementations of the **capability roles** that loops and exports compose.
+> A role is a slot in the system; a skill is one concrete implementation of that slot.
+> Changing implementation = changing one line in `skills.toml`.
+
+---
+
+## Capability catalog
+
+All 10 roles, their built-in defaults, their tier, and which loops/exports compose them:
+
+| Role | Default built-in | Tier | Composed by |
+|---|---|---|---|
+| `ui-design` | [`ui-spec`](../ui-spec/SKILL.md) | must | `spec-refine-loop` (when requirement involves UI) |
+| `sql` | `sql` | must | research sessions · `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 | all loops · `export-manuals` · `export-reports` |
+| `research` | [`research`](research/SKILL.md) | should | all loops (on-demand investigation) |
+| `testing` | [`testing`](testing/SKILL.md) | should | `plan-exec-loop` · `quick-loop` |
+| `tools` | [`tools`](tools/SKILL.md) | should | `plan-exec-loop` |
+| `diagrams` | [`diagrams`](diagrams/SKILL.md) | should | `export-diagrams` |
+| `overview` | `workflow` | should | any loop (orientation about the workflow itself) |
+
+**Tiers:**
+- `must` — core to almost every session; built-in always active unless explicitly `off`.
+- `should` — loaded on-demand; active by default but lower priority to override.
+
+---
+
+## Binding cascade
+
+The CLI resolves which skill fulfills a role at compose-time using a 3-level cascade:
+
+```
+built-in default
+    ↓  (overridden by, if present)
+~/.workflow/skills.toml        (global — applies to all workspaces on this machine)
+    ↓  (overridden by, if present)
+.workflow/skills.toml          (workspace — applies only to this workspace)
+```
+
+**Resolution rules:**
+
+1. **Role with a binding** (workspace, or global if not workspace) → use that skill name.
+   - If the name exists under `roles/<name>/` → it is a built-in skill.
+   - If not → it is a third-party skill installed by name on the host (e.g. via skills.sh).
+2. **Role with no binding at any level** → use the built-in default (table above). No config needed for the common case.
+3. **`off`** → capability disabled. The loop continues without it; if the task required it, the loop reports why it cannot proceed or asks the human.
+
+---
+
+## skills.toml format
+
+```toml
+[skills]
+# Built-in defaults (no entry needed — listed here for reference only)
+# ui-design        = "ui-spec"
+# sql              = "sql"
+# git              = "git"
+# coding-standards = "coding-standards"
+# writing          = "writing"
+# research         = "research"
+# testing          = "testing"
+# tools            = "tools"
+# diagrams         = "diagrams"
+# overview         = "workflow"
+
+# Override examples:
+testing          = "off"                # disable testing capability
+ui-design        = "acme/figma-spec"    # third-party skill installed via skills.sh
+diagrams         = "mermaid-only"       # custom built installed locally
+```
+
+### Override: point to a third-party skill
+
+```toml
+[skills]
+ui-design = "acme/figma-spec"
+```
+
+`acme/figma-spec` must be installed on the host (e.g. via `skills.sh install acme/figma-spec`). The CLI resolves the skill by name; if not found, it falls back to the built-in default and warns.
+
+### Override: disable a capability
+
+```toml
+[skills]
+testing = "off"
+```
+
+The loop that composes `testing` will skip it. If the task required testing and the role is `off`, the loop should inform the human and ask how to proceed.
+
+### Override: use a different built-in
+
+```toml
+[skills]
+diagrams = "diagrams-lite"   # if a "diagrams-lite" built-in were registered
+```
+
+Only meaningful if multiple built-ins for the same role are registered. Currently each role has exactly one built-in default.
+
+---
+
+## Inspecting resolved bindings
+
+```bash
+aw skills
+```
+
+Lists the resolved binding for every role in the current workspace, showing which level of the cascade provided it (built-in / global / workspace) and whether it is `off`.
+
+Example output:
+
+```
+Role              Resolved skill      Source
+----------------- ------------------- -----------
+ui-design         ui-spec             built-in
+sql               sql                 built-in
+git               git                 built-in
+coding-standards  coding-standards    built-in
+writing           writing             built-in
+research          research            built-in
+testing           off                 workspace   (.workflow/skills.toml)
+tools             tools               built-in
+diagrams          mermaid-only        global      (~/.workflow/skills.toml)
+overview          workflow            built-in
+```
+
+---
+
+## Adding a new role
+
+1. Define the role in this README (name, default built-in, tier, composed by).
+2. Author the built-in skill under `roles/<name>/SKILL.md` following the schema.
+3. Register it in the CLI resolver so `aw skills` lists it.
+4. Document the binding key in the `skills.toml` reference above.
+
+## Authoring a built-in skill
+
+Each `SKILL.md` follows this schema:
+
+| Section | Content |
+|---|---|
+| Frontmatter `name:` | kebab-case; MUST equal the binding name (`research`, `testing`, etc.) |
+| Frontmatter `description:` | rich description: what + when; drives automatic selection |
+| `## Role` | which capability role this implements (its skills.toml slot) |
+| `## Purpose` | what it does |
+| `## Composed by` | which loops/exports use it and when |
+| `## Knowledge` | reusable know-how: vocabulary, rules, schema, examples |
+| `## Output` | what it produces and where (if any) |
+| `## Source` | recycled from (if applicable) |
+
+See [`research/SKILL.md`](research/SKILL.md) as a reference implementation.

package/skills/w/roles/coding-standards/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: coding-standards
+description: >-
+  Coding standards capability — built-in default for the `coding-standards` role.
+  Stack-agnostic principles (SOLID, fail-fast, descriptive names, small methods,
+  reuse over duplication) plus per-stack conventions (Java/Spring, Angular/TypeScript,
+  Node), security (no secrets in code or logs, parametrized SQL, DB read-only via MCP),
+  HTTP error handling (never silence errors), logging levels, and FE-BE integration
+  rules (unified sparse DTO, PATCH for edit, no hidden fallbacks). Use when a loop
+  implements, reviews or refactors code.
+---
+
+# coding-standards — Coding standards capability
+
+## Role
+
+`coding-standards` — built-in default. Rebindable in `.workflow/skills.toml` (third-party skill or `off`).
+
+## Purpose
+
+Aportar los estándares de código que la IA aplica al **implementar, revisar o refactorizar**. Read-only por diseño: carga reglas, no edita ni ejecuta nada por sí misma — el loop consumidor materializa el código.
+
+## Composed by
+
+- **`plan-exec-loop`** — al implementar/refactorizar las tasks del plan.
+- **`quick-loop`** — al implementar el atajo liviano.
+
+## Knowledge
+
+### Principios generales
+
+- **SOLID** — Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion.
+- **Fail fast** — validar y retornar al inicio del método (early returns, evitar nesting).
+- **Nombres descriptivos** — el código habla por sí mismo; comentarios solo para el "por qué".
+- **Métodos pequeños** — una sola responsabilidad por función.
+- **Composición sobre herencia**.
+- **Reutilización antes que duplicación (DRY)** — antes de crear componente/función/clase, revisar si ya existe en `shared/` (frontend) o `common/`/`util/` (backend). Si un patrón aparece 2-3 veces, proponer extracción.
+
+### Estándares por stack
+
+- **Java / Spring Boot**: Constructor Injection (sin Field Injection), `@Transactional(readOnly=true)` para lecturas, Java records para DTOs Request/Response, Jakarta Validation para inputs.
+- **Angular / TypeScript**: constructor injection, `async` pipe en templates, evitar `any`, FormBuilder reactivo sobre `ngModel` directo, arquitectura `@data`/`@presentation`, normalización de tipos.
+- **Node / otros**: mismos principios generales; aplicar las convenciones idiomáticas del proyecto detectado.
+
+### Integración FE-BE (cuando el cambio cruza frontend y backend)
+
+- **R1 — Sparse DTO unificado**: mismo DTO `<Feature>SaveRequest` para create + edit, todos los campos nullable. `null` = "no tocar".
+- **R2 — PATCH para edit**: `@PatchMapping` en BE, `http.patch()` en FE. POST solo para create. PUT solo si replace total justificado.
+- **R3 — FE envía solo cambios**: payload diff entre `formValue` y entidad original.
+- **R4 — Sin fallbacks que oculten errores**: prohibido `catchError(() => of([]))` en FE; prohibido try/catch con fallback al método legacy en BE durante migraciones. Usar feature flags explícitas para rollout gradual.
+- **R5 — Validación BE con Bean Validation + groups**: `@NotNull(groups = OnCreate.class)` para distinguir reglas POST vs PATCH cuando comparten DTO.
+- **R6 — DB stub-first**: funciones/SP nuevas arrancan devolviendo mock (`RETURN '[]'::jsonb`); implementación real en una fase posterior.
+
+### Seguridad
+
+- **Nunca** exponer secrets, API keys ni credenciales en código.
+- **Nunca** logear datos sensibles (contraseñas, tokens, datos personales).
+- **Siempre** parametrizar queries SQL (nunca concatenar strings).
+- **BD vía MCP es READONLY**. Modificaciones a BD solo como scripts SQL versionados (ver rol `sql`); las aplica el **usuario**, nunca la IA — ni por MCP, ni `Bash`, ni `psql`, ni driver. (Invariante 4.)
+
+### Manejo de errores HTTP
+
+- **Nunca** silenciar errores HTTP con `catchError(() => of([]))` ni equivalentes. Los errores del backend se propagan al usuario (toast/mensaje) para detectar regresiones en guardado/sincronización/creación. Para reintentos usar operadores explícitos (`retry`, `retryWhen`), no silenciar.
+
+### Logging
+
+- `ERROR` — fallos que requieren atención inmediata.
+- `WARN` — situaciones inesperadas pero manejadas.
+- `INFO` — eventos de negocio relevantes (inicio/fin de procesos).
+- `DEBUG` — detalle técnico para diagnóstico.
+
+### Convenciones de BD (nomenclatura)
+
+Esquemas `esq_`, tablas `tb_`, sequences `seq_`, funciones `fn_`/procedimientos `sp_`, patrón maestra-detalle, auditoría en `esq_audit`. Para autoría de scripts SQL (estilo, header, categorías, rollback) usar el rol **`sql`**.
+
+## Output
+
+Ninguno propio. La skill aporta reglas; el código lo escribe el loop. Cuando el cambio toca BD, delega la autoría de scripts al rol `sql`. Nunca exporta a `docs/` (invariante 1).
+
+## Source
+
+Reciclada de `standards/coding-standards/` (SKILL.md + references Java/Spring, Angular/TypeScript, fe-be-integration, database-conventions, frontend-structure, project-structure). Los principios UX de mantenimientos CRUD (formularios, listados, modales) viven en el rol `ui-spec`/`ui-design`; la autoría de scripts SQL en el rol `sql`. Se descarta la dependencia de `profile.json` y de comandos CLI de la doctrina vieja.