@tacuchi/agent-workflow-cli 6.1.0 → 7.0.0

package/skills/agent-workflow/specialties/analyze-investigate/references/cost-guard.md

@@ -0,0 +1,85 @@
+# Cost guard — protocolo para queries MCP
+
+Antes de ejecutar `mcp__plugin_developer-workflow_qtc-{cert,prod}__execute_sql` con cualquier query no-trivial, aplicar este guard. Las queries contra `<mcp-cert>` / `<mcp-prod>` tienen costo real (latencia, I/O, hold de conexión).
+
+## Paso 1 — estimar tamaño antes de ejecutar la query principal
+
+Para queries que NO son `SELECT 1`, `LIMIT 1`, ni `WHERE pk = literal`:
+
+```sql
+-- Estimación 1: cuántas filas esperar
+SELECT COUNT(*) FROM <tabla principal> WHERE <filtros>;
+
+-- Estimación 2: peek a estructura (1 fila)
+SELECT * FROM <tabla principal> WHERE <filtros> LIMIT 1;
+```
+
+Si soporta `EXPLAIN`:
+
+```sql
+EXPLAIN (FORMAT TEXT) <query principal>;
+```
+
+Leer el plan: índices usados, tipo de scan (seq scan vs index scan), filas estimadas (`rows=`).
+
+## Paso 2 — clasificar costo
+
+| Categoría | Criterios | Acción |
+|---|---|---|
+| **Barata** | COUNT(*) ≤ 1.000 filas; PK lookup; EXPLAIN dice index scan | Ejecutar directamente. Documentar tamaño real en query header. |
+| **Moderada** | COUNT(*) entre 1.000 y 10.000; seq scan sobre tabla pequeña (<100k); JOIN con todos índices | Avisar al usuario el tamaño + duración estimada. Ejecutar si no objeta. |
+| **Costosa** | COUNT(*) > 10.000; JOIN sin índice; seq scan sobre >100k; ventana > 90 días sobre tabla activa | **Confirmación EXPLÍCITA** antes de ejecutar. Sugerir LIMIT, filtros, sample. |
+| **Bloqueada** | UPDATE/INSERT/DELETE detectado; lock fuerte (FOR UPDATE) | Refusarse. MCP enforcan; el AI tampoco intenta. |
+
+## Paso 3 — formato de aviso al usuario
+
+### Moderada (antes de ejecutar)
+
+```
+La query estimada toca ~5.200 filas (EXPLAIN: index scan sobre idx_solicitud_fecha,
+ventana 30 días). Tiempo esperado <2s. Ejecuto?
+```
+
+### Costosa
+
+**Dispara `AskUserQuestion`** con spec de C2 (`agent-workflow:prompts-catalog#C2`). Header `cost`, 2 opciones canónicas (Proceder / Cancelar) + preview ASCII obligatorio con el SQL y el plan EXPLAIN resumido. NO narrar la pregunta en texto plano (anti-patrón histórico: bloque "(a)/(b)/(c)/(d) — Decidí" como input libre).
+
+Plantilla del preview:
+
+```
+⚠ Query potencialmente costosa
+  COUNT(*) estimado: ~85.000 filas
+  EXPLAIN: seq scan sobre solicitud (sin índice para WHERE estado='X')
+  Sin LIMIT — Servidor: <mcp-prod>
+
+SQL:
+  SELECT * FROM solicitud WHERE estado = 'X' ORDER BY fecha DESC;
+```
+
+Si el usuario activa el Other auto-inyectado puede pedir variantes (LIMIT, sample por mod(id,N), filtros adicionales) en texto libre — el AI reformula la query y vuelve a aplicar el guard sobre la versión revisada antes de ejecutar.
+
+NO ejecutar la versión costosa sin confirmación explícita, aunque el usuario haya autorizado queries genéricas en la sesión.
+
+## Paso 4 — registrar el costo real
+
+Tras ejecutar, agregar al header del archivo SQL:
+
+```sql
+-- Costo real: <filas devueltas> filas en <duración>; servidor=<cert|prod>
+```
+
+Esto cierra el loop: la próxima sesión que toque la misma tabla tiene referencia.
+
+## Excepciones permitidas (sin guard explícito)
+
+- `SELECT 1` y healthchecks.
+- `SELECT * FROM <tabla> WHERE <pk> = <valor>` (PK lookup determinístico).
+- Queries contra `information_schema` / `pg_catalog` (metadata, casi gratis).
+- Re-ejecución de una query que ya tenía guard documentado en una sesión previa.
+
+## Anti-patrones
+
+- **`SELECT * FROM tabla` sin WHERE**: nunca, salvo confirmación con `(a)` arriba.
+- **JOIN cartesiano accidental**: revisar siempre que cada JOIN tenga ON con clave indexada.
+- **Loop de queries pequeñas**: si vas a correr 50 queries similares, 1 query con `IN (...)` o `JOIN` es preferible. Documentar la decisión.
+- **Saltarse el guard porque "es solo cert"**: cert también tiene costo y se comparte con otros equipos.

package/skills/agent-workflow/specialties/analyze-synthesize/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: analyze-synthesize
+description: Estructura información en un plan accionable. Skill CLAVE invocada por agent-workflow:session durante la fase planning para descomponer el OBJECTIVE en TASKS.md (cuando auto-plan dice `lite` o `full`). También se invoca durante execution para sintetizar FINDINGS.md a partir de evidencia recolectada por analyze-investigate. Output siempre estructurado con criterios + dependencias + ordenamiento.
+version: 1.1.0
+---
+
+# analyze-synthesize — qtc v1.1+
+
+Specialty skill **analyze**: estructura información de manera accionable. Doble rol:
+
+1. **En `planning`** (uso primario): descompone OBJECTIVE en TASKS.md cuando `agent-workflow auto-plan-decide` retorna `lite` o `full`. La invoca `agent-workflow:session` directamente.
+2. **En `execution`** (analyze-only): sintetiza FINDINGS.md a partir de EVIDENCE.md después de `analyze-investigate`.
+
+Es la **skill más importante** del flow=analyze porque participa en planning de TODOS los flows (no solo analyze).
+
+## Cuándo se invoca
+
+- **Composición desde `agent-workflow:session` en planning** cuando `auto-plan-decide` retorna `lite` o `full`.
+- **Composición en sesión analyze en execution** después de `analyze-investigate` cuando hay evidencia que organizar.
+- NL del usuario: "estructurá el plan", "organizá los hallazgos", "armá las tareas".
+- Devuelta por `specialty-choose --phase planning`.
+
+## Acción: estructurar plan (uso primario, planning)
+
+Output: `.workflow/sessions/<folder>/TASKS.md` con descomposición ordenada.
+
+### Estructura canónica de TASKS.md
+
+```markdown
+# Tasks — sessionNNN-<flow>-<slug>
+
+## Plan summary
+
+[1-2 oraciones: qué se va a hacer, en qué orden, criterio de hecho.]
+
+## Tasks
+
+- [ ] **T1**: <título imperativo> — <criterio: cómo sé que está hecha>
+  - Depende de: ninguna
+  - Estima: <S|M|L>
+- [ ] **T2**: <título> — <criterio>
+  - Depende de: T1
+  - Estima: <S|M|L>
+- [ ] **T3**: ... — <criterio>
+  - Depende de: T1
+  - Estima: <S|M|L>
+
+## Risks / external dependencies
+
+- <riesgo 1: qué podría romper la ejecución, mitigación>
+```
+
+### Reglas de estructuración
+
+- **3-7 tareas para `full`**, 1-3 para `lite`. Si exceden 7, agrupar.
+- **Cada tarea con criterio de hecho explícito** (no solo título).
+- **Dependencias declaradas** — el AI puede paralelizar tareas independientes.
+- **Estima S|M|L** orientativa: S = <30min, M = 30min-2h, L = 2-8h. Si una L se acerca a 8h, considerá descomponer.
+- **No prescribir solución técnica acá** — la decisión de "cómo" se toma durante execution con la specialty correspondiente (implement, design-deliver, etc.).
+
+## Acción: sintetizar hallazgos (analyze execution)
+
+Output: `.workflow/sessions/<folder>/FINDINGS.md` (legacy: `HALLAZGOS.md`).
+
+```markdown
+# Findings — sessionNNN-analyze-<slug>
+
+## Patterns identified
+
+- **Patrón A**: <qué+por qué+evidencia (link a EVIDENCE.md sección)>
+
+## False positives discarded
+
+- **<hipótesis descartada>**: por qué no aplica, evidencia.
+
+## Model decision
+
+[Cuál modelo / hipótesis explica mejor los datos. 1-2 párrafos.]
+
+## What is NOT known (gaps)
+
+- <pregunta abierta que requeriría más investigación>
+```
+
+### Reglas de síntesis
+
+- **Toda afirmación con evidencia**: link al `EVIDENCE.md#section` o al artefacto (query, screenshot, log).
+- **Honest gaps**: lo que no se pudo probar o quedó incierto, declararlo. No inventar.
+- **Convergencia**: el output debe ser una historia coherente, no un dump.
+- **Próximo paso**: FINDINGS termina apuntando a `analyze-conclude` (produce CONCLUSIONS.md modulado por `## Modality`).
+
+## Reglas
+
+- **Sin imaginación creativa**: este skill es estructurador, no inventor. Trabaja con lo que el OBJECTIVE o EVIDENCE ya dice.
+- **Single source of truth**: el TASKS.md es la fuente de qué se va a hacer; el FINDINGS.md es la fuente de qué se sabe. Otros artefactos (DECISIONS, CONCLUSIONS) referencian, no duplican.
+- **Idempotente**: re-invocar sobre TASKS.md existente refina, no recrea.
+- **No commits autónomos**: ver `agent-workflow:commits-policy`. Synthesize escribe TASKS/FINDINGS pero nunca commitea.
+
+## Composición con otras skills
+
+| Skill | Cuándo |
+|---|---|
+| `analyze-investigate` | en analyze sessions, EVIDENCE antes de sintetizar |
+| `analyze-conclude` | siguiente paso en analyze sessions; produce CONCLUSIONS.md modulado por `## Modality` (technical/incident/data) |
+| `agent-workflow:session` | invoca este skill en planning de cualquier flow |
+
+## Sandbox read-only
+
+Reglas universales en el canon (`sandbox-readonly-rules.md`). En plan mode esta skill describe en el plan file el output según el rol:
+
+- **Rol planning** (invocado por `agent-workflow:session` durante phase planning):
+  - **Path destino**: `.workflow/sessions/<folder>/TASKS.md`.
+  - **Items propuestos** (≥3 si auto-plan = `full`, 1-3 si `lite`): cada uno con título, criterio de aceptación, dependencias (orden), estimación de esfuerzo.
+  - Sugerencias de skills a invocar para cada item (sin invocarlas).
+
+- **Rol execution** (sesiones analyze, sintetizar evidencia):
+  - **Path destino**: `.workflow/sessions/<folder>/FINDINGS.md`.
+  - **Estructura**: hallazgo principal, sub-hallazgos numerados, conexiones entre ellos, gaps (qué falta investigar).
+  - Origen de cada hallazgo: link al item de EVIDENCE.md (sin re-pegar el contenido).
+
+NO ejecuta: `Write` sobre TASKS.md ni FINDINGS.md.
+
+## Recursos
+
+- shared-contract §14 — fase planning del lifecycle universal.
+- shared-contract §15 — naming convention specialty skills.
+- shared-contract §19 — auto-plan trigger heurística (cuándo invocar este skill).

package/skills/agent-workflow/specialties/design-brief/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: design-brief
+description: Capta el brief inicial de una sesión de diseño y declara el `## Type` (project|system). Invocado desde la fase planning del lifecycle universal qtc-core cuando el OBJECTIVE menciona UI/UX/diseño/pantalla/mockup/wireframe. Produce OBJECTIVE.md con secciones Type, Brief, Context y Acceptance criteria. No produce código ni mocks aún — sólo capturar QUÉ y POR QUÉ.
+version: 1.1.0
+---
+
+# design-brief — qtc v1.0+
+
+Specialty skill **design**: capta el brief y el tipo de sesión durante la fase `planning` del lifecycle universal.
+
+## Cuándo se invoca
+
+- Composición desde `agent-workflow:session` en `planning` cuando el OBJECTIVE menciona UI/UX/diseño/pantalla/mockup/wireframe/layout/forma.
+- Devuelta por `agent-workflow specialty-choose --phase planning` si el OBJECTIVE incluye keywords de design.
+- NL del usuario: "abrí una sesión de diseño", "vamos a diseñar X", "necesito un mock de Y".
+
+## Pre-requisitos
+
+1. Bloque AW-PROJECT presente. Si no → proponer `/agent-workflow:project-init`.
+2. Sesión nueva (o existente sin OBJECTIVE completo).
+
+## Acción
+
+### 1. Pedir al usuario
+
+| Campo | Tipo | Ejemplos |
+|---|---|---|
+| **Type** | `project` \| `system` (legacy ES: `proyecto`/`sistema`) | `project` = pantalla/mantenimiento concreto. `system` = tokens/componentes compartidos. |
+| **Nombre** | slug-kebab ≤4 palabras | `mock-lista-negra`, `tokens-spacing`, `wizard-nuevo-cliente` |
+| **Brief corto** | 1-3 oraciones | quién (rol/usuario), qué problema, constraints clave |
+| **Acceptance criteria** | lista | cómo sabemos que la sesión cumple su objetivo |
+
+Si el OBJECTIVE no declara `## Type`, **dispara `AskUserQuestion`** con spec de S1 (`agent-workflow:prompts-catalog#S1`). Header `design-type`, 2 opciones (Project / System). Si el usuario activa el Other auto, pedir clarificación libre y NO inferir el type desde el texto — la sesión queda sin type hasta que el usuario lo declare.
+
+NO narrar la pregunta en texto plano (ej. "¿Esto es proyecto o sistema?" en chat es un anti-patrón).
+
+### 2. Crear sesión
+
+```
+agent-workflow session-create \
+    --name <slug> \
+    --objetivo "<brief>" \
+    --type <project|system>
+```
+
+Crea `.workflow/sessions/sessionNNN-design-<slug>/OBJECTIVE.md` con `## Type` + `## Brief` pre-cargados. Las flags legacy `--tipo proyecto|sistema` siguen aceptadas y se normalizan a EN.
+
+### 3. Iterar el brief si hace falta
+
+Si el brief es vago o ambiguo:
+- 1-2 preguntas de clarificación (no más).
+- Editar OBJECTIVE.md (legacy: OBJETIVO.md) con la versión refinada.
+- Confirmar con el usuario antes de avanzar.
+
+### 4. Hand-off a planning del lifecycle universal
+
+Reportar al `agent-workflow:session` que el brief está cerrado y el plan structurado puede empezar (si auto-plan dice `full` o `lite`). Para `type=system`, plan suele ser `lite` (tareas predecibles); para `type=project`, suele ser `full` (criterios + variantes).
+
+## Reglas
+
+- **Spec-only**: NO escribir código. NO escribir mocks aún (eso es design-develop).
+- **Type es obligatorio**: sin `Type` no se crea la sesión. Convención shared-contract §11.
+- **Brief corto**: si el usuario quiere extender, hacerlo en `## Context` o en `DISCOVERY.md` (más adelante).
+- **No asumir framework de UI**: el brief habla del problema, no de Angular/React/Bootstrap. Eso lo decide el flow=dev al implementar.
+
+## Composición con otras skills
+
+| Skill | Cuándo |
+|---|---|
+| `design-discover` | siguiente paso, en fase `execution` (investigación de usuarios/flows/sistema existente) |
+| `design-develop` | divergencia/convergencia de soluciones, en `execution` |
+| `design-deliver` | spec final, al cerrar `execution` antes de `validation` |
+| `frontend-design` | reglas agnósticas de UI (form/list/modal/navigation/feedback) — referenciar pero no invocar acá |
+
+## Sandbox read-only
+
+Reglas universales en el canon (`sandbox-readonly-rules.md`). En plan mode esta skill describe en el plan file:
+
+- Campos a pedir al usuario para capturar el brief: nombre/slug, Type (`project`|`system`; legacy ES aceptado), Brief, Context, Acceptance criteria, Inspiración.
+- Que el OBJECTIVE.md se crearía a partir del template `objetivo-design.md` (interno del CLI) con esos campos.
+- Que `agent-workflow session-create` se invocaría — pero NO se ejecuta hasta salir de plan mode.
+
+NO ejecuta: `agent-workflow session-create`, `Write` sobre OBJECTIVE.md.
+
+## Recursos
+
+- shared-contract §11 — convención `## Type` (project|system; legacy ES `proyecto`/`sistema`).
+- shared-contract §14 — fase planning del lifecycle universal.
+- `agent-workflow:prompts-catalog#S1` — spec literal del prompt design-type (header, opciones, manejo del Other).
+- skill `frontend-design` — principios de UI agnósticos del framework.

package/skills/agent-workflow/specialties/design-deliver/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: design-deliver
+description: Spec final estable para handoff al flow=dev. Componentes, estados, validaciones, tokens aplicados, decisiones UX racionalizadas. Sin código. Produce DELIVERY.md como entregable canónico (referenciado por handoff `--from design:NNN`). Invocado al final de execution cuando design-develop convergió en una variante elegida.
+version: 2.2.0
+---
+
+# design-deliver — qtc v2.1+
+
+Specialty skill **design**: producción del spec final. Cierre creativo de `execution` antes de pasar a `validation`.
+
+## Cuándo se invoca
+
+- Composición desde `agent-workflow:session` al final de `execution` cuando design-develop convergió.
+- NL del usuario: "spec final", "armá el entregable", "vamos a deliverable", "cerrá el diseño".
+
+## Acción
+
+Producir `.workflow/sessions/<folder>/DELIVERY.md` (legacy: `ENTREGA.md`) con el spec completo + canónico para handoff al flow=dev.
+
+### Estructura canónica de DELIVERY.md
+
+```markdown
+# Delivery — sessionNNN-design-<slug>
+
+## Summary
+[2-3 oraciones del qué y para quién. Esto es el TL;DR del handoff.]
+
+## Components
+
+### <Component 1>
+- Type: form | list | modal | navigation | feedback | custom
+- States: idle | loading | error | success | disabled | …
+- Validations (if form): [lista]
+- Tokens applied: spacing.md, color.danger, font.body
+- UX rules: [shortcuts, accesibilidad, responsive]
+- Mock: docs/referencias/<nombre>.png o link Figma
+
+### <Component 2>
+- ...
+
+## Flows / interactions
+
+1. [paso 1]
+2. [paso 2]
+3. ...
+
+## UX decisions
+
+- [decisión clave + por qué + qué se descartó]
+
+## Tokens / design-system applied
+
+- (sólo si type=project): listar tokens consumidos del DS.
+- (si type=system): listar tokens NUEVOS o MODIFICADOS, con migration impact.
+
+## Validation criteria
+
+- [cómo qtc-dev sabrá que la implementación cumple el spec]
+
+## Out of scope
+
+- [qué NO se implementa en este spec, para evitar scope creep en la sesión dev]
+```
+
+## Reglas
+
+- **Sin código**: DELIVERY.md es markdown puro + referencias a mocks/Figma. El código lo escribe el flow=dev.
+- **Componentes referenciados a frontend-design**: si un componente es una variante estándar, citar `frontend-design references/<patron>.md`. Si es nuevo/custom, especificarlo entero.
+- **Estados explícitos**: cada componente declara TODOS sus estados (no asumir que el dev los infiere).
+- **Validaciones con regex/longitud/required cuando aplica**: el dev no inventa.
+- **Out of scope explícito**: cierra puertas; evita feature creep.
+- **Si type=system**: DELIVERY.md describe los CAMBIOS al design system (delta + migration), no una pantalla. La distinción `## Type: project|system` queda como metadato interno del documento; **no** afecta la carpeta de graduación (todo va a `docs/especificaciones/` — path canónico ES preservado por compat con sesiones legacy).
+- **No commits autónomos**: design-deliver **nunca** commitea DELIVERY.md ni `docs/referencias/` por iniciativa. Ver `agent-workflow:commits-policy` (Regla 3): cuando el usuario solicita un commit — closure auto, ad-hoc en cualquier fase, o sin sesión activa — el AI invoca el flujo M1 propose-then-execute con `AskUserQuestion`.
+
+## Loop hasta convergencia final
+
+Después del primer draft de DELIVERY.md:
+
+1. Mostrar al usuario.
+2. Recibir feedback.
+3. Iterar sobre el archivo (Edit, no recreación).
+4. Repetir hasta el usuario confirme: "OK, podemos handoff".
+
+## Hand-off al flow=dev (post-cierre de la sesión design)
+
+Cuando la sesión cierre, DELIVERY.md se gradúa a `docs/especificaciones/NNN-<slug>/DELIVERY.md` (kind=`especificacion`, modelo nuevo DEC-003). Sin distinción project/system en la carpeta destino — la distinción queda como `## Type` interno del documento. La carpeta destino conserva el nombre español `docs/especificaciones/` por compatibilidad con paths existentes en sesiones legacy.
+
+Destino según workspace_mode (DEC-002):
+- **hub mode** → `<hub>/docs/especificaciones/NNN-<slug>/DELIVERY.md`.
+- **project mode** → `<cwd>/docs/especificaciones/NNN-<slug>/DELIVERY.md`.
+
+```
+/agent-workflow:session --from design:<code> "<objetivo de implementación>"
+```
+
+El OBJECTIVE de la sesión dev quedará con `## Origin` linkeado al `DELIVERY.md` y tag `origen:design-NNN` en HISTORY.md (shared-contract §10).
+
+## Composición con otras skills
+
+| Skill | Cuándo |
+|---|---|
+| `design-develop` | si el feedback del usuario invalida la convergencia, retroceder |
+| `frontend-design` | para validar que cada componente referenciado existe en patterns |
+
+## Sandbox read-only
+
+Reglas universales en el canon (`sandbox-readonly-rules.md`). En plan mode esta skill describe en el plan file:
+
+- **Path destino** del DELIVERY.md: `.workflow/sessions/<folder>/DELIVERY.md`.
+- **Esqueleto propuesto**: secciones (Summary, Components, States, Tokens applied, Variants, Validation criteria, Hand-off a dev), longitud aproximada por sección.
+- **Referencias del usuario**: lista de archivos en `<workspace-root>/docs/referencias/` (mockups, especificaciones de tokens, exportes que el usuario provea), con formato y propósito. Carpeta transversal — DEC-004 v2. **El AI no escribe ahí salvo solicitud explícita**.
+- **Type declarado** en OBJECTIVE: `project` o `system` (legacy ES `proyecto`/`sistema` se normaliza). Metadato interno del documento. En cualquier caso gradúa a `docs/especificaciones/` (kind=`especificacion`). Si falta, plan dice "preguntar al usuario".
+
+NO ejecuta: `Write` sobre DELIVERY.md ni `docs/referencias/`; `agent-workflow graduate --kind especificacion`.
+
+## Recursos
+
+- skill `frontend-design` — patterns canónicos para referenciar.
+- shared-contract §10 — handoff `--from design:<code>`.
+- shared-contract §11 — convención `## Type` (afecta destino de graduación).
+- shared-contract §14 — fase execution del lifecycle universal.

package/skills/agent-workflow/specialties/design-develop/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: design-develop
+description: Convergencia en problem statement + divergencia en soluciones (variantes/mocks). Iteración con el usuario hasta tener una propuesta validada. Produce PROBLEM.md, IDEAS.md y opcionalmente mocks/wireframes en `docs/referencias/` (carpeta transversal manual del usuario, DEC-004 v2). Invocado en execution después de design-discover (o directo si el OBJECTIVE no requiere discovery).
+version: 2.2.0
+---
+
+# design-develop — qtc v2.1+
+
+Specialty skill **design**: convergencia en problema + divergencia/iteración de soluciones. Núcleo creativo del flujo design.
+
+## Cuándo se invoca
+
+- Composición desde `agent-workflow:session` en `execution` cuando hay OBJECTIVE + (DISCOVERY.md o sesión saltó discovery por trivialidad).
+- NL del usuario: "vamos a diseñar opciones", "propone variantes", "cómo lo resolvemos", "boceto rápido".
+- Recomendado por `design-discover` como siguiente paso.
+
+## Acción
+
+Producir 2-3 artefactos en paralelo:
+
+### 1. PROBLEM.md — convergencia
+
+Statement de problema en 1-3 oraciones. Foco en QUÉ se resuelve, no en CÓMO. (legacy: `PROBLEMA.md`)
+
+```markdown
+# Problem — sessionNNN-design-<slug>
+
+## Statement
+[1-3 oraciones: usuario X necesita Y porque Z].
+
+## Key constraints
+- [restricciones técnicas, de UX, de tiempo, de tokens del design system]
+
+## Success metrics
+- [cómo sabemos que la solución funciona]
+```
+
+### 2. IDEAS.md — divergencia
+
+Lista de variantes con tradeoffs. **No** elegir todavía:
+
+```markdown
+# Ideas — sessionNNN-design-<slug>
+
+## Variant A: <name>
+- Descripción 1-2 oraciones.
+- Pros: ...
+- Cons: ...
+- Mockup: docs/referencias/A-mockup.png  (si el usuario lo aporta) o link Figma/Stitch
+
+## Variant B: <name>
+- ...
+
+## Variant C: ...
+- (3 variantes es típico; más sólo si justifica)
+
+## Initial recommendation
+- [variante preferida y por qué; queda abierto a feedback del usuario]
+```
+
+### 3. `docs/referencias/` — mocks aportados por el usuario (DEC-004 v2)
+
+- Wireframes/mocks bajos en fidelidad para iteración rápida.
+- Storage:
+  - Local: `<workspace-root>/docs/referencias/A-*.png|svg|md` (el **usuario** los coloca; el AI los lee). Carpeta transversal — cualquier sesión accede a las mismas referencias sin re-subirlas.
+  - Externo (Figma/Stitch): URL en IDEAS.md, nada en `docs/referencias/`.
+- **El AI no escribe en `docs/referencias/` salvo solicitud explícita** del usuario ("guardá este wireframe en referencias"). Si necesita generar un esqueleto ASCII, lo embebe directamente en IDEAS.md.
+- Para `type=system`, las referencias pueden ser ejemplos de uso de tokens/componentes (no mockups de pantallas).
+
+## Loop de iteración
+
+```
+[propuestas] → [feedback usuario] → [refinar] → [propuestas v2] → [...]
+                                       ↓
+                                  [convergencia]
+                                       ↓
+                              [→ design-deliver]
+```
+
+Cada iteración:
+- Editar PROBLEM.md/IDEAS.md (no recrear).
+- Si el usuario aporta nuevos mockups en `docs/referencias/`, leerlos y reflejarlos en IDEAS.md. El AI no toca `docs/referencias/` salvo pedido explícito.
+- Confirmar con el usuario antes de la próxima iteración.
+
+## Reglas
+
+- **3 variantes es óptimo**: si el espacio de soluciones es claro, 1-2 alcanza. Si el problema es muy abierto, hasta 4. Más es ruido.
+- **No saltar a deliver sin convergencia explícita**: el usuario debe confirmar "OK, vamos con la variante X" antes de pasar a `design-deliver`.
+- **Mocks de baja fidelidad primero**: alta fidelidad en `design-deliver`. Acá importa el flujo, no el pixel.
+- **Spec-only**: NO escribir código de UI. Mocks como imágenes/wireframes/Figma URLs.
+- **Frontend-design es referencia, no obligación**: para `type=system`, las decisiones de tokens/componentes ALIMENTAN `frontend-design` (no al revés).
+
+## Composición con otras skills
+
+| Skill | Cuándo |
+|---|---|
+| `design-deliver` | siguiente paso una vez hay convergencia |
+| `frontend-design` | consultar patterns existentes para validar consistencia |
+| `design-discover` | si surge nueva pregunta que requiere investigación, retroceder |
+
+## Sandbox read-only
+
+Reglas universales en el canon (`sandbox-readonly-rules.md`). En plan mode esta skill describe en el plan file:
+
+- **Paths destino**: `.workflow/sessions/<folder>/PROBLEM.md`, `IDEAS.md`, opcional lectura de `<workspace-root>/docs/referencias/` (carpeta transversal manual del usuario, DEC-004 v2) con mocks/wireframes que el usuario aporte.
+- **Problem statement** propuesto: 1-2 oraciones que capturan QUÉ resolver y POR QUÉ.
+- **Variantes a explorar**: 2-4 enfoques distintos (estructura, layout, interacción) con pros/cons textuales — sin diseñar mocks aún.
+- **Iteración prevista**: cuántas rondas con el usuario, qué validar en cada una.
+
+NO ejecuta: `Write` sobre PROBLEM.md/IDEAS.md, generación de mocks en `docs/referencias/` (manual del usuario), ediciones a `docs/especificaciones/`.
+
+## Recursos
+
+- skill `frontend-design` — patterns reutilizables (form/list/modal/navigation/feedback).
+- shared-contract §14 — fase execution del lifecycle universal.

package/skills/agent-workflow/specialties/design-discover/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: design-discover
+description: Fase de investigación divergente del diseño dentro del lifecycle universal. Investiga usuarios, flows existentes, código relacionado, design system actual y referencias externas. Produce DISCOVERY.md como artefacto lazy. Invocado desde execution cuando ya hay OBJECTIVE con Type capturado por design-brief y el usuario está listo para divergir antes de converger en problema/soluciones.
+version: 1.2.0
+---
+
+# design-discover — qtc v1.1+
+
+Specialty skill **design**: investigación divergente. Primer paso de `execution` para sesiones design.
+
+## Cuándo se invoca
+
+- Composición desde `agent-workflow:session` en `execution` cuando hay OBJECTIVE con `## Type` (legacy: `## Tipo`) y todavía no existe `DISCOVERY.md`.
+- NL del usuario: "investigá el contexto", "qué hay del usuario X", "miremos cómo está hecho hoy".
+- Recomendado por `design-brief` como siguiente paso natural.
+
+## Acción
+
+Producir o iterar `.workflow/sessions/<folder>/DISCOVERY.md` con investigación divergente sobre 4 ejes:
+
+### 1. Usuarios
+
+- Quién va a usar esto, en qué contexto, con qué frecuencia.
+- Si hay personas/role-models existentes, referenciarlas.
+- Si hay usuarios reales accesibles, considerar entrevistas (lo decide el usuario).
+
+### 2. Flows / proceso actual
+
+- Cómo se hace HOY (si existe). Pasos, frustraciones, walking skeleton.
+- Capturas de pantalla / refs al código existente si aplica.
+- Para `type=project` → mirar pantallas existentes del módulo.
+- Para `type=system` → mirar componentes/tokens existentes en `docs/especificaciones/` (kind=`especificacion`, modelo nuevo) o el design system instalado.
+
+### 3. Design system existente
+
+- Qué tokens / componentes ya tenemos que aplican.
+- Patterns establecidos (`skill frontend-design references/*-patterns.md`).
+- Decisiones previas en `docs/especificaciones/NNN-*/DELIVERY.md` (kind=`especificacion`; legacy: `ENTREGA.md`).
+
+### 4. Referencias externas
+
+- Productos parecidos (con screenshots/links si el usuario los provee).
+- Buenas prácticas del dominio.
+- Restricciones de accesibilidad / responsive / multi-idioma.
+
+## Estructura típica de DISCOVERY.md
+
+```markdown
+# Discovery — sessionNNN-design-<slug>
+
+## Users
+
+- ...
+
+## Current flow
+
+- ...
+
+## Applicable design system
+
+- Tokens: ...
+- Components: ...
+- Patterns: ...
+
+## External references
+
+- ...
+
+## Key findings
+
+- [1-3 hallazgos accionables que el siguiente paso (define+develop) usa]
+```
+
+## Reglas
+
+- **Divergir ahora, converger después**: no proponer soluciones todavía — eso es `design-develop`.
+- **Citar fuentes**: cada afirmación con un link/path a evidencia (código, screenshots, docs).
+- **DISCOVERY.md es lazy**: si el OBJECTIVE es trivial (ej. cambio menor a un componente existente), saltar a `design-develop` directo.
+- **No escribir código**: spec-only siempre.
+
+## Composición con otras skills
+
+| Skill | Cuándo |
+|---|---|
+| `design-develop` | siguiente paso una vez DISCOVERY tiene hallazgos accionables |
+| `frontend-design` | consultar patterns existentes para el inventario "design system aplicable" |
+| `analyze-investigate` | si la investigación requiere análisis técnico profundo (latencia, datos), invocar acá |
+
+## Sandbox read-only
+
+Reglas universales en el canon (`sandbox-readonly-rules.md`). En plan mode esta skill describe en el plan file:
+
+- **Path destino**: `.workflow/sessions/<folder>/DISCOVERY.md`.
+- **Fuentes a consultar**: pantallas existentes (paths o screenshots), flows del repo, design system actual (`docs/especificaciones/` con kind=`especificacion` y `## Type: system` interno), referencias externas (links). Material aportado por el usuario en `<workspace-root>/docs/referencias/` también se considera (carpeta transversal — DEC-004 v2).
+- **Preguntas de investigación**: lista priorizada (qué hacen los usuarios hoy, qué duele, qué falta).
+- **Esqueleto del DISCOVERY.md**: secciones (Contexto, Stakeholders, Estado actual, Pain points, Referencias, Preguntas abiertas).
+
+NO ejecuta: `Read` sobre código fuente (sí permitido — read-only), `Write` sobre DISCOVERY.md.
+
+## Recursos
+
+- skill `frontend-design` — patterns reutilizables.
+- shared-contract §14 — fase execution del lifecycle universal.

package/skills/agent-workflow/standards/README.md

@@ -0,0 +1,12 @@
+# standards/
+
+Estándares técnicos universales (no doctrina del lifecycle, no específicos de empresa).
+
+Contenido esperado (T2 PR2):
+
+- `coding-standards.md` — estándares por stack (Java/Spring, Angular/TS, Node) + seguridad (sin secrets, SQL parametrizado, logging por nivel).
+- `sql-mutation-guard.md` — patrón del hook que aborta SQL no parametrizado / DDL fuera de scripts/.
+- `i18n-conventions.md` — convención EN-canon + ES-legacy aliases bilingües.
+- `commit-style.md` — formato de commit messages compatible con el ecosistema.
+
+Inyectables vía `profile.migrate_legacy_rules[]` cuando una empresa tiene estilos heredados.