---
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.
