@saulwade/swl-ses 1.0.0

package/habilidades/likec4-experto/SKILL.md

@@ -0,0 +1,412 @@
+---
+name: likec4-experto
+description: >
+  Experto en LikeC4 — lenguaje "architecture-as-code" inspirado en el C4 model.
+  Cubre sintaxis del DSL (.likec4/.c4), estructura de proyectos multi-archivo,
+  views, deployment, dynamic views, predicates (*, _, **), flags del CLI
+  (validate, export), y consumo del MCP server oficial desde agentes SWL.
+  Cargar cuando el proyecto del usuario contenga archivos .likec4/.c4, un
+  .likec4rc o likec4.config.{ts,js,json}, o cuando el usuario mencione "c4
+  model", "architecture as code", "likec4" o "structurizr dsl". NO cargar para
+  diagramas Mermaid/PlantUML/D2 sueltos (existen skills separadas) ni para ADRs
+  en Markdown puro.
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para diagramas Mermaid, PlantUML o D2 sueltos sin relación con el C4 model — para Mermaid cargar `generacion-mermaid`; para diagramas de arquitectura visual enriquecidos cargar `diagrama-arquitectura`."
+  - "No cargar para ADRs en Markdown puro sin diagrama arquitectónico versionable — para ADRs de texto cargar directamente la regla `arquitectura.md`."
+  - "No cargar para Structurizr DSL puro (sintaxis diferente a LikeC4 aunque inspirada en C4) — los proyectos Structurizr tienen su propia sintaxis y CLI no compatibles con LikeC4."
+  - "No cargar si el proyecto no tiene archivos `.likec4`, `.c4` ni `likec4.config.*` — si el equipo no ha adoptado LikeC4, usar `generacion-mermaid` o `diagrama-arquitectura` según el tipo de diagrama."
+---
+# LikeC4 Experto — Architecture-as-code con DSL y MCP
+
+## Cuándo NO cargar
+
+- El proyecto usa diagramas Mermaid sueltos: cargar `generacion-mermaid`.
+- El usuario pide solo un ADR textual sin diagrama arquitectónico versionable: usar la regla `arquitectura.md` directamente.
+- El proyecto usa Structurizr DSL puro (sintaxis diferente, no compatible): no hay skill equivalente, documentar con Mermaid.
+- No hay archivos `.likec4`, `.c4` ni `likec4.config.*` en el proyecto: el equipo no ha adoptado LikeC4.
+
+## Cuándo cargar esta skill
+
+- El proyecto contiene archivos `.likec4` o `.c4`.
+- Existe `.likec4rc` o `likec4.config.{ts,js,json}` en el repo.
+- El usuario menciona `c4model.com`, architecture-as-code, LikeC4, Structurizr DSL,
+  o pide generar/validar diagramas de arquitectura versionables.
+- El agente `arquitecto-swl` o `documentador-swl` necesita emitir diagramas
+  programáticos y el proyecto ya adoptó LikeC4.
+
+---
+
+## Response Discipline
+
+Aplica a esta skill (command-first domain):
+
+- Si el prompt pide `"minimal"`, `"strict"`, `"exact"`, `"paste-ready"`,
+  `"comando exacto"`: responde con **una sola línea** (comando o snippet) como
+  primera línea, sin preámbulo.
+- Si el prompt pide snippet de view/model: responde con el snippet LikeC4
+  como primera línea en bloque de código ` ```likec4 `, sin alternativas.
+- Prose-only es falla en prompts strict.
+
+---
+
+## Anti-substitution guardrails
+
+- Familia validate: usar `likec4 validate` (nunca sustituir con `check`,
+  `lint`, `build`, `compile`).
+- Familia export: usar `likec4 export` (nunca `generate`, `render`, `output`).
+- Flags de validación: usar `--json --no-layout --file <path> <project-dir>`
+  (nunca `--output-json`, `--skip-layout`, `--target-file`).
+- Export de imágenes: usar `--outdir` o `-o` (nunca `--output-dir`, `--out`).
+- Primary key de elementos: usar FQN completo cross-file (`cloud.backend.api`,
+  nunca shortcut `backend.api` cuando se cruza archivo).
+- Identificadores: sin puntos (`payment-api` válido; `payment.api` NO es
+  identificador — los puntos son separadores de FQN).
+
+---
+
+## Dependencia externa — LikeC4 CLI y MCP
+
+LikeC4 es un paquete npm del proyecto del usuario, **no de SWL**.
+
+### Instalación (en *su* proyecto)
+
+```bash
+npm install --save-dev likec4
+# o ejecutar sin instalar:
+npx likec4 --version
+```
+
+### MCP server oficial
+
+LikeC4 expone un MCP server con 15+ tools de consulta del modelo. Se inicia:
+
+```bash
+npx likec4 mcp
+```
+
+Y se configura en Claude Code como cualquier otro MCP server. Los agentes SWL
+lo consumen vía las herramientas nativas MCP del runtime — **SWL no necesita
+adaptador propio**.
+
+Tools disponibles (resumen):
+
+| Tool MCP | Qué hace |
+|----------|----------|
+| `list-projects` | Enumera los proyectos LikeC4 del workspace |
+| `read-project-summary` | Overview de un proyecto (elementos, views, tags) |
+| `search-element` | Busca elementos por nombre/título/descripción |
+| `read-element` | Lee un elemento por FQN con fields completos |
+| `read-view` | Lee la definición de una view |
+| `read-deployment` | Lee modelo de despliegue |
+| `batch-read-elements` | Lee múltiples elementos en una sola llamada |
+| `query-graph` | Subgrafo entre dos elementos |
+| `query-incomers-graph` | Dependencias entrantes de un elemento |
+| `query-outgoers-graph` | Dependencias salientes de un elemento |
+| `find-relationships` | Busca relaciones por endpoint |
+| `find-relationship-paths` | Caminos entre dos elementos |
+| `query-by-tags` | Filtra elementos por tags |
+| `query-by-tag-pattern` | Filtra por glob de tags |
+| `query-by-metadata` | Filtra por metadata key/value |
+| `element-diff` | Diff entre dos elementos |
+| `subgraph-summary` | Resumen compacto de un subgrafo |
+| `open-view` | Abre una view en el preview |
+
+---
+
+## Sintaxis DSL esencial
+
+### Estructura top-level
+
+Un archivo `.c4`/`.likec4` admite **solo** estos bloques top-level:
+
+```likec4
+import 'shared'         // opcional, otros proyectos
+specification { ... }   // define kinds y tags
+model { ... }           // define elementos y relaciones
+deployment { ... }      // modelo de despliegue físico
+views { ... }           // define vistas
+global { ... }          // styling compartido
+```
+
+Todos pueden repetirse dentro del proyecto (multi-archivo merge). Al menos uno
+debe aparecer por archivo.
+
+### `specification`
+
+```likec4
+specification {
+  element system
+  element service
+  element database {
+    style {
+      shape: storage
+    }
+  }
+  tag critical
+  tag public-api
+}
+```
+
+### `model` — elementos y relaciones
+
+```likec4
+model {
+  customer = actor 'Customer'
+
+  saas = system 'SaaS Platform' {
+    backend = service 'Backend' {
+      paymentsApi = service 'Payments API' #public-api
+    }
+    db = database 'Main DB' #critical
+  }
+
+  customer -> saas.backend.paymentsApi 'Pays'
+  saas.backend.paymentsApi -> saas.db 'reads/writes'
+}
+```
+
+### `views`
+
+```likec4
+views {
+  view index {
+    title 'System Context'
+    include *
+  }
+
+  view backend of saas.backend {
+    include *, saas.db
+    style * { color muted }
+    style saas.backend.* { color blue }
+  }
+
+  dynamic view checkout {
+    title 'Checkout flow'
+    customer -> saas.backend.paymentsApi 'POST /pay'
+    saas.backend.paymentsApi -> saas.db 'insert payment'
+    saas.db -> saas.backend.paymentsApi 'OK'
+    saas.backend.paymentsApi -> customer '201'
+  }
+}
+```
+
+### Predicates `*`, `_`, `**`
+
+| Predicate | Significado |
+|-----------|-------------|
+| `*` | Todos los elementos del scope actual |
+| `_` | El elemento referenciado (self) |
+| `**` | Recursivo sobre hijos anidados |
+| `saas.**` | Todos los descendientes de `saas` (incluyendo nietos) |
+| `saas.*` | Hijos directos de `saas` |
+
+### Identificadores y FQN
+
+- **Identificador**: letras, dígitos, `-`, `_`. No puntos, no empieza con dígito.
+  - Válidos: `customer`, `payment-service`, `frontendApp`, `queue-1`
+  - Inválido: `payment.api` (el punto es separador de FQN)
+- **FQN**: path dot-separado único por proyecto. Ej: `saas.backend.paymentsApi`.
+- **Lexical scoping** dentro del mismo archivo (puede sombrear). **Cross-file**
+  requiere SIEMPRE FQN completo.
+
+---
+
+## CLI canonical contracts
+
+### Validate
+
+```bash
+# Validación completa del proyecto
+npx likec4 validate <project-dir>
+
+# Validación strict en CI (recomendada)
+npx likec4 validate --json --no-layout --file <ruta.c4> <project-dir>
+```
+
+Flags clave:
+- `--json`: salida JSON estructurada.
+- `--no-layout`: omite verificación de layout drift (más rápido; útil en
+  pre-commit de sintaxis pura).
+- `--file <path>`: scope de errores al archivo dado (repetible).
+- `--file <a> --file <b>`: multi-archivo.
+
+Campos críticos del JSON:
+- `filteredFiles`, `filteredErrors`: errores acotados al archivo.
+- `totalErrors`: errores de todo el proyecto.
+
+### Export
+
+```bash
+# PNG a directorio
+npx likec4 export png --outdir ./images <project-dir>
+
+# Filtrar views por glob
+npx likec4 export png --views 'overview*' --outdir ./images <project-dir>
+
+# Otros formatos
+npx likec4 export svg --outdir ./images <project-dir>
+npx likec4 export dot --outdir ./dot <project-dir>
+npx likec4 export mermaid --outdir ./md <project-dir>
+```
+
+### Preview interactivo
+
+```bash
+npx likec4 start <project-dir>
+```
+
+Levanta servidor local con hot-reload.
+
+---
+
+## Casos de uso en SWL
+
+### 1. `arquitecto-swl` genera ADR con diagrama LikeC4
+
+Cuando el usuario pide registrar una decisión arquitectónica y el proyecto ya
+tiene LikeC4:
+
+1. Escribir el ADR en `docs/adr/NNNN-<slug>.md`.
+2. Añadir una view dedicada en `views` del modelo LikeC4.
+3. Exportar PNG/SVG al directorio del ADR con `likec4 export`.
+4. Enlazar la imagen desde el ADR.
+
+### 2. `documentador-swl` consulta arquitectura vía MCP
+
+Sin abrir los archivos fuente, usar las tools MCP:
+
+```
+list-projects → read-project-summary → read-view('index')
+```
+
+Útil cuando se necesita describir la arquitectura sin cargar todo el DSL en
+contexto.
+
+### 3. `revisor-codigo-swl` detecta deriva modelo↔código
+
+Si el proyecto tiene `src/backend/payments.ts` pero el modelo LikeC4 no lo
+menciona, reportar como drift.
+
+```bash
+# Lista servicios del modelo
+npx likec4 validate --json <project-dir> | \
+  node -e "const d=require('fs').readFileSync(0,'utf8'); const m=JSON.parse(d); console.log(m.elements.map(e=>e.id).join('\n'))"
+```
+
+### 4. `depurador-swl` prioriza por relaciones críticas
+
+Antes de modificar un servicio, consultar `query-incomers-graph` para entender
+quién depende de él y ajustar el blast radius esperado.
+
+---
+
+## Patrones buenos y malos
+
+### BIEN — una sola fuente de verdad
+
+```likec4
+// projects/saas/system-model.c4
+model {
+  saas = system 'SaaS' {
+    backend = service
+  }
+}
+```
+
+El proyecto se determina por el `likec4.config.json` más cercano en el árbol.
+
+### MAL — cross-file sin FQN completo
+
+```likec4
+// archivo-a.c4
+model {
+  saas = system { backend = service }
+}
+
+// archivo-b.c4
+views {
+  view test of backend { ... }  // ERROR: cross-file sin FQN completo
+}
+```
+
+### BIEN — cross-file con FQN completo
+
+```likec4
+views {
+  view test of saas.backend { ... }
+}
+```
+
+### MAL — styling del modelo dentro del model block
+
+```likec4
+model {
+  saas = system 'SaaS' #blue   // ❌ styling no va en model
+}
+```
+
+### BIEN — styling en specification o en view
+
+```likec4
+specification {
+  element system {
+    style { color: blue }
+  }
+}
+
+// o solo para una view específica:
+views {
+  view x {
+    include *
+    style saas.* { color blue }
+  }
+}
+```
+
+---
+
+## Integración con otros componentes SWL
+
+- **`arquitecto-swl`**: invoca esta skill cuando el proyecto adopta LikeC4.
+- **`documentador-swl`**: consume MCP `read-view` para obtener descripciones de
+  arquitectura sin parsear el DSL manualmente.
+- **`revisor-codigo-swl`**: usa `element-diff` y `query-graph` para detectar
+  inconsistencias entre el código y el modelo.
+- **`habilidades/generacion-mermaid`**: si el proyecto NO adopta LikeC4, esa
+  skill es la alternativa. Las dos no coexisten en el mismo proyecto.
+- **`habilidades/dbml-experto`**: complementaria — LikeC4 describe arquitectura
+  de sistemas; DBML describe esquema de BD. Pueden coexistir en el mismo proyecto.
+
+---
+
+## Lo que esta skill NO hace
+
+- **No renderiza diagramas** — delega al CLI `likec4 export` o al preview.
+- **No parsea el DSL programáticamente** — delega al MCP server o al CLI.
+- **No reemplaza** Structurizr, C4-PlantUML, PlantUML o Mermaid — es una
+  herramienta distinta con su propio DSL.
+- **No genera código de aplicación** — describe arquitectura, no la
+  implementa.
+
+---
+
+## Referencias
+
+- Sitio oficial: https://likec4.dev/
+- Playground: https://playground.likec4.dev/
+- C4 Model: https://c4model.com/
+- Skill fuente (inspiración): `skills/likec4-dsl/SKILL.md` del repo LikeC4.
+- MCP server: ejecutar `npx likec4 mcp --help` para flags del servidor.
+
+## Gotchas / Errores comunes no obvios
+
+**`npx likec4 validate` reporta cero errores pero el proyecto tiene referencias cross-file rotas cuando se usa FQN incorrecto**: LikeC4 no valida referencias cross-file si el FQN referenciado no existe en el scope del proyecto — simplemente crea un elemento implícito sin advertencia en la versión predeterminada del CLI. Causa: la validación de referencias cross-file requiere el flag `--json` + parsing del output para detectar elementos implícitos no declarados. Fix: ejecutar `npx likec4 validate --json <project-dir>` y verificar en el JSON de output que no hay elementos con `kind: implicit` — esos indican referencias a FQNs que no existen en ningún archivo del proyecto.
+
+**Los identificadores con guiones (`payment-api`) generan FQNs ambiguos cuando el padre también tiene guiones**: `cloud.payment-api.auth-service` puede interpretarse incorrectamente por herramientas externas que asumen que los guiones separan segmentos del FQN en lugar de ser parte del identificador. Causa: el parser de LikeC4 usa el punto como separador de FQN, pero herramientas de análisis de texto externas pueden no distinguirlo. Fix: para elementos que formarán parte de FQNs complejos o serán referenciados vía MCP tool `read-element`, preferir `camelCase` (`paymentApi`, `authService`) que elimina la ambigüedad con separadores.
+
+**`likec4 export png` produce imágenes con texto cortado en componentes con nombres largos en español**: el renderer de LikeC4 calcula el bounding box del texto basándose en caracteres ASCII y subvalora el ancho de caracteres acentuados y la ñ. En una caja con `title 'Gestión de Autenticación'`, el texto puede quedar truncado o solapado con el borde. Causa: el motor de layout usa métricas de fuente aproximadas. Fix: usar nombres de elementos más cortos en el `title` (máximo 3 palabras) y poner la descripción completa en el campo `description`, que aparece como tooltip pero no en la caja del diagrama exportado.
+
+**El MCP server de LikeC4 (`npx likec4 mcp`) no detecta cambios en los archivos `.c4` después de iniciado**: si el agente modifica archivos del modelo mientras el MCP server está corriendo, las tools `read-element` y `read-view` devuelven los datos del estado inicial del modelo, no el estado actualizado. Causa: el MCP server carga el modelo una vez al iniciar y no implementa file watching por defecto. Fix: reiniciar el MCP server después de modificaciones al modelo (`Ctrl+C` + `npx likec4 mcp`), o usar `likec4 start` en modo preview con hot-reload para desarrollo iterativo y el MCP solo en consultas finales.

package/habilidades/likec4-experto/evals/evals.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "../../../schemas/skill-evals.schema.json",
+  "skill_name": "likec4-experto",
+  "artifact_type": "skill",
+  "schema_version": 1,
+  "description": "Evals para likec4-experto — CLI, DSL, MCP server, anti-substituciones.",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Comando minimal y strict para validar solo el archivo `projects/template/system-model.c4` sin layout drift.",
+      "files": [],
+      "expectations": [
+        "Usa `likec4 validate` (nunca `check`, `lint`, `build`).",
+        "Incluye `--json`.",
+        "Incluye `--no-layout`.",
+        "Incluye `--file projects/template/system-model.c4`.",
+        "Incluye el project path `projects/template` después de los flags."
+      ],
+      "grading_guidance": "Aceptar `npx likec4@latest` o variantes de pin de versión.",
+      "tags": ["primary-flow", "cli"],
+      "weight": 1.5
+    },
+    {
+      "id": 1,
+      "prompt": "Exportar solo vistas que coincidan con `overview*` como PNG al directorio `./images`.",
+      "files": [],
+      "expectations": [
+        "Usa `likec4 export png`.",
+        "Usa `--outdir ./images` (o `-o`).",
+        "Usa `--views 'overview*'` (glob).",
+        "NO usa alias inventados tipo `--output-dir` o `--out`."
+      ],
+      "tags": ["cli", "export"]
+    },
+    {
+      "id": "anti-substitution-validate",
+      "prompt": "¿Con qué comando se chequea un proyecto LikeC4? Dame el comando exacto.",
+      "files": [],
+      "expectations": [
+        "La respuesta usa `likec4 validate`.",
+        "La respuesta NO sustituye con `check`, `lint`, `build`, `compile`."
+      ],
+      "grading_guidance": "Failure inmediata si aparece `check`/`lint`/`build` como comando principal.",
+      "tags": ["anti-pattern", "regression"],
+      "weight": 2.0
+    },
+    {
+      "id": "cross-file-fqn",
+      "prompt": "En un archivo `views.c4`, ¿puedo escribir `view x of backend { ... }` si `backend` está definido en otro archivo del mismo proyecto?",
+      "files": [],
+      "expectations": [
+        "La respuesta indica que NO, que cross-file requiere FQN completo.",
+        "La respuesta da el ejemplo correcto (ej: `view x of cloud.backend`).",
+        "La respuesta menciona que el lexical scoping NO cruza archivos."
+      ],
+      "tags": ["dsl", "fqn"]
+    },
+    {
+      "id": "mcp-server",
+      "prompt": "¿Cómo inicio el MCP server oficial de LikeC4?",
+      "files": [],
+      "expectations": [
+        "La respuesta incluye `npx likec4 mcp`.",
+        "La respuesta menciona al menos 2 tools del MCP (ej: `query-graph`, `read-view`, `find-relationship-paths`)."
+      ],
+      "tags": ["mcp"]
+    }
+  ]
+}

package/habilidades/manejo-errores/.evolved.json

@@ -0,0 +1,9 @@
+{
+  "SKILL.md": {
+    "evolved": true,
+    "evolvedFrom": "5.10.4",
+    "evolvedAt": "2026-04-20",
+    "evolvedBy": "aprender",
+    "evolvedNote": "throttle adaptativo ante fallo transitorio"
+  }
+}