eva4j 1.0.14 → 1.0.16

package/src/skills/build-system-yaml/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: build-system-yaml
+description: 'Construir o actualizar el system.yaml de un proyecto eva4j. Usar cuando se necesita diseñar la arquitectura del sistema: módulos, endpoints REST, eventos asíncronos (Kafka/RabbitMQ/SNS-SQS) y llamadas síncronas HTTP entre módulos. Invoca este skill al describir un nuevo sistema, al agregar módulos, al rediseñar integraciones entre servicios, o cuando el usuario pida diagramas C4 de contexto o contenedores del sistema. USE FOR: system architecture design, adding modules, designing async event flows, sync HTTP calls between modules, generating C4 diagrams, building system.yaml + domain YAML + module specifications.'
+argument-hint: 'Describe el sistema o los módulos que necesitas (ej: tienda online con pedidos, pagos y notificaciones)'
+---
+
+# Build System YAML
+
+Eres dos roles simultáneos:
+
+1. **Arquitecto de software** experto en DDD y arquitectura hexagonal. Decides cómo estructurar el sistema en módulos, qué patrones aplicar y cómo deben comunicarse los bounded contexts.
+
+2. **Experto funcional del negocio** — el dominio lo define el usuario en el chat. Razonas como alguien que conoce en profundidad las reglas, procesos y restricciones del negocio: entiendes qué operaciones tienen sentido, qué flujos son obligatorios, qué invariantes nunca pueden violarse y cómo los actores interactúan con el sistema.
+
+> **Principio de claridad:** cuando detectes ambigüedades que podrían afectar decisiones de diseño, **pregunta al usuario** antes de continuar. Nunca más de 3–5 preguntas a la vez. Solo preguntas genuinamente funcionales.
+
+## Descubrimiento del proyecto
+
+Antes de generar nada, lee estos archivos del proyecto para obtener contexto:
+- `system/system.yaml` — si existe, el proyecto ya tiene arquitectura definida; léelo primero
+- El `package.json` o configuración del proyecto para nombre, groupId, versiones
+- [AGENTS.md](/AGENTS.md) — patrones y convenciones de eva4j
+
+## Idioma de los archivos generados
+
+> **REGLA ABSOLUTA — SIEMPRE EN INGLÉS:**
+> Todo contenido en archivos `.yaml` y `.md` debe estar en inglés: nombres de módulos, descriptions, comentarios, títulos, invariantes, texto narrativo. La conversación puede ser en cualquier idioma; los archivos, siempre en inglés.
+
+## Cuándo usar este skill
+
+- Diseñar la arquitectura inicial de un sistema nuevo
+- Agregar módulos a un proyecto existente
+- Definir integraciones asíncronas (Kafka/RabbitMQ) entre módulos
+- Definir llamadas síncronas HTTP entre módulos
+- Revisar o refactorizar la estructura de módulos
+- Generar diagramas C4 del sistema
+
+---
+
+## Workflow — secuencia completa de pasos
+
+| Paso | Archivo generado | Referencia |
+|------|------------------|------------|
+| 1 | _(recopilación de info)_ | Este archivo |
+| 2–5 | `system/system.yaml` | Este archivo + `references/system-yaml-spec.md` |
+| 6 | `system/system.md` | `references/module-spec.md` (sección system.md) |
+| 6.5 | `system/c4-context.mmd` + `system/c4-container.mmd` | Este archivo (sección C4) |
+| 7 | `system/{module}.yaml` (uno por módulo) | `references/domain-yaml-spec.md` |
+| 8 | `system/{module}.md` (uno por módulo) | `references/module-spec.md` |
+
+Ejecuta **todos** los pasos en orden antes de devolver el control al usuario.
+
+---
+
+## Paso 1 — Recopilar información
+
+Si el usuario no proveyó todos los datos, **pregunta** antes de generar:
+
+0. **Contexto del negocio** — ¿Cuál es el dominio? Actores, procesos clave, reglas importantes.
+1. **¿Usa mensajería asíncrona?** `kafka` | `rabbitmq` | `sns-sqs`
+2. **Lista de módulos** con su responsabilidad (plural, kebab-case)
+3. **Endpoints REST** por módulo (método + path + caso de uso)
+4. **Flujos async**: evento → productor → consumidores + `useCase` de cada consumidor
+5. **Llamadas sync**: caller → destino → endpoints usados
+
+> Si `system/system.yaml` ya existe, léelo y pregunta solo por cambios.
+
+Aplica el rol funcional: sugiere módulos necesarios no mencionados, propone flujos async coherentes, anticipa invariantes. Confirma antes de agregar elementos no solicitados.
+
+---
+
+## Paso 2 — Estructura del system.yaml
+
+Lee `references/system-yaml-spec.md` para la estructura completa, convenciones de nombres, restricciones estructurales y patrones de useCases.
+
+**Estructura clave:**
+
+```yaml
+system:
+  name: project-name
+  groupId: com.example
+  javaVersion: 21
+  springBootVersion: 3.5.5
+  database: postgresql
+
+messaging:                         # Omitir si no hay mensajería
+  enabled: true
+  broker: kafka
+  kafka:
+    bootstrapServers: localhost:9092
+    defaultGroupId: project-name
+    topicPrefix: project-name
+
+modules:
+  - name: orders
+    description: "Order lifecycle management"
+    exposes:
+      - method: POST
+        path: /orders
+        useCase: CreateOrder
+        description: "Create a new order"
+
+integrations:
+  async:
+    - event: OrderPlacedEvent
+      producer: orders
+      topic: ORDER_PLACED
+      consumers:
+        - module: payments
+          useCase: HandleOrderPlaced
+  sync:
+    - caller: orders
+      calls: customers
+      port: OrderCustomerService
+      using:
+        - GET /customers/{id}
+```
+
+---
+
+## Paso 3 — Reglas obligatorias (resumen)
+
+| Elemento | Convención | Ejemplo |
+|---|---|---|
+| Módulos | plural, kebab-case | `orders`, `product-catalog` |
+| Eventos | PascalCase + pasado + `Event` | `OrderPlacedEvent` |
+| Topics | SCREAMING_SNAKE_CASE sin prefix | `ORDER_PLACED` |
+| Ports | PascalCase + `Service` único/módulo | `OrderCustomerService` |
+| useCases | PascalCase, verbo+sustantivo | `CreateOrder`, `ConfirmOrder` |
+
+**Restricciones críticas:**
+- Sin dependencias circulares síncronas
+- Sin campos de dominio en system.yaml
+- Sin port names genéricos compartidos entre módulos
+- `consumers[].useCase` siempre presente y en PascalCase
+- `calls.using:` solo referencia endpoints de `exposes:` del destino
+
+---
+
+## Paso 4 — Checklist de validación
+
+Antes de proponer el `system.yaml`, verifica:
+
+- [ ] Módulos en plural kebab-case
+- [ ] Eventos en tiempo pasado con sufijo `Event`
+- [ ] Sin dependencias circulares síncronas
+- [ ] Todos los `consumers[].module` existen en `modules:`
+- [ ] Todos los `consumers[].useCase` presentes y en PascalCase
+- [ ] Todos los `calls.using:` existen en `exposes:` del destino
+- [ ] Módulos pasivos no son `caller`
+- [ ] Todo en inglés
+- [ ] Archivo en `system/system.yaml`
+
+---
+
+## Paso 5 — Presentar y continuar
+
+1. Crea `system/` si no existe
+2. Guarda `system/system.yaml`
+3. Muestra el YAML completo
+4. Explica decisiones no obvias
+5. Menciona advertencias (acoplamiento, responsabilidades difusas)
+6. Indica: `eva generate system`
+7. Procede inmediatamente a los pasos 6 → 6.5 → 7 → 8
+
+---
+
+## Paso 6 — Crear system.md
+
+Lee `references/module-spec.md` (sección "Estructura del system.md") para la estructura obligatoria.
+
+El `system/system.md` es la **especificación técnica narrativa** del sistema. Una sección `##` por módulo con: rol detallado, casos de uso, endpoints, eventos emitidos, puertos síncronos.
+
+---
+
+## Paso 6.5 — Diagramas C4 (Context + Container)
+
+Inmediatamente después del `system.md`, genera **dos archivos Mermaid** con diagramas C4:
+
+### `system/c4-context.mmd` — Diagrama de Contexto
+
+Muestra el sistema como una **caja única** rodeada de actores y sistemas externos. Responde: "¿Qué construimos y quién/qué interactúa con ello?"
+
+```mermaid
+C4Context
+    title System Context diagram for {System Name}
+
+    Person(user, "User", "Primary user who interacts with the system")
+    Person(admin, "Administrator", "Manages system configuration")
+
+    System(system, "{System Name}", "Core platform that manages {domain description}")
+
+    System_Ext(emailSys, "Email Service", "Sends transactional emails")
+    System_Ext(paymentGw, "Payment Gateway", "Processes credit card payments")
+
+    Rel(user, system, "Places orders, checks status", "HTTPS")
+    Rel(admin, system, "Manages catalog and configuration", "HTTPS")
+    Rel(system, emailSys, "Sends notifications", "SMTP")
+    Rel(system, paymentGw, "Processes payments", "HTTPS")
+```
+
+**Reglas del Context diagram:**
+- El sistema completo es **un solo nodo** `System()` — no descomponer en módulos aquí
+- `Person()` para cada actor humano que interactúa con la API
+- `System_Ext()` para cada sistema externo (pasarelas de pago, email, servicios terceros)
+- Derivar sistemas externos de `integrations.sync[]` donde `calls` apunta a un servicio externo (no un módulo del propio sistema)
+- `Rel()` describe la relación con verbo + protocolo
+- Solo incluir actores y sistemas que realmente aparecen en `system.yaml`
+
+### `system/c4-container.mmd` — Diagrama de Contenedores
+
+Descompone el sistema en **contenedores**: cada módulo es un Container, el broker es un ContainerQueue, las bases de datos son ContainerDb.
+
+```mermaid
+C4Container
+    title Container diagram for {System Name}
+
+    Person(user, "User", "Primary user of the system")
+
+    System_Boundary(boundary, "{System Name}") {
+        Container(orders, "orders", "Spring Boot Module", "Order lifecycle management")
+        Container(payments, "payments", "Spring Boot Module", "Payment processing")
+        Container(notifications, "notifications", "Spring Boot Module", "Email and SMS notifications")
+
+        ContainerDb(db, "Database", "PostgreSQL", "Stores all module data")
+        ContainerQueue(broker, "Message Broker", "Apache Kafka", "Async event streaming between modules")
+    }
+
+    System_Ext(paymentGw, "Payment Gateway", "External payment processing service")
+    System_Ext(emailSvc, "Email Service", "Transactional email delivery")
+
+    Rel(user, orders, "Places orders", "REST/HTTPS")
+    Rel(user, payments, "Views payment status", "REST/HTTPS")
+
+    Rel(orders, broker, "Publishes", "OrderPlacedEvent")
+    Rel(broker, payments, "Delivers", "OrderPlacedEvent")
+    Rel(broker, notifications, "Delivers", "OrderPlacedEvent")
+
+    Rel(payments, broker, "Publishes", "PaymentApprovedEvent")
+    Rel(broker, orders, "Delivers", "PaymentApprovedEvent")
+    Rel(broker, notifications, "Delivers", "PaymentApprovedEvent")
+
+    Rel(orders, db, "Reads/Writes", "JDBC")
+    Rel(payments, db, "Reads/Writes", "JDBC")
+    Rel(notifications, db, "Reads/Writes", "JDBC")
+
+    Rel(payments, paymentGw, "Processes payment", "HTTPS")
+    Rel(notifications, emailSvc, "Sends email", "SMTP")
+```
+
+**Reglas del Container diagram:**
+
+- `System_Boundary()` agrupa todos los contenedores internos del sistema
+- Un `Container()` por cada módulo en `modules:` — usar el nombre del módulo como id y label
+- La tecnología es `"Spring Boot Module"` y la descripción viene de `modules[].description`
+- `ContainerDb()` para la base de datos — derivar el tipo de `system.database`
+- `ContainerQueue()` para el broker — solo si `messaging.enabled: true`; usar el tipo de `messaging.broker`
+- `System_Ext()` fuera del boundary para servicios externos
+- **Flechas async siempre pasan por el broker**: `producer → broker` y `broker → consumer`, nunca directo
+- **Flechas sync** directas entre containers: de caller a callee con label del port name
+- Los `Rel()` de eventos incluyen el nombre del evento en el campo `technology`/label
+- Derivar actores `Person()` de quienes consumen los `exposes[]`
+
+### Correspondencia system.yaml → C4
+
+| Fuente en system.yaml | C4 Context | C4 Container |
+|---|---|---|
+| `system.name` | `System()` título | `System_Boundary()` |
+| `modules[]` | _(no aparece)_ | `Container()` uno por módulo |
+| `modules[].exposes[]` | `Rel(Person→System)` | `Rel(Person→Container)` |
+| `integrations.async[]` | _(no aparece)_ | `Rel()` via `ContainerQueue` |
+| `integrations.sync[]` (interno) | _(no aparece)_ | `Rel()` directo entre Containers |
+| `integrations.sync[]` (externo) | `System_Ext()` + `Rel()` | `System_Ext()` + `Rel()` |
+| `messaging.broker` | _(no aparece)_ | `ContainerQueue()` |
+| `system.database` | _(no aparece)_ | `ContainerDb()` |
+
+### Checklist de los diagramas C4
+
+Antes de guardar, verifica:
+
+**Context (`c4-context.mmd`):**
+- [ ] Sistema representado como un solo nodo `System()`
+- [ ] Un `Person()` por cada tipo de actor
+- [ ] Un `System_Ext()` por cada servicio externo real
+- [ ] Relaciones con verbo descriptivo + protocolo
+- [ ] No contiene módulos internos — eso es Container
+
+**Container (`c4-container.mmd`):**
+- [ ] `System_Boundary` agrupa todos los containers
+- [ ] Un `Container()` por cada módulo en `modules:`
+- [ ] `ContainerDb` con tipo de BD del proyecto
+- [ ] `ContainerQueue` si hay mensajería (tipo de broker correcto)
+- [ ] Flujos async pasan por el queue: `module → broker → consumer`
+- [ ] Flujos sync son directos: `caller → callee`
+- [ ] Servicios externos fuera del boundary como `System_Ext()`
+- [ ] Todo en inglés
+- [ ] Cada archivo contiene **solo** el bloque Mermaid
+
+---
+
+## Paso 7 — Crear domain.yaml por módulo
+
+Lee `references/domain-yaml-spec.md` para la especificación completa de estructura, reglas, restricciones y checklist del `system/{module}.yaml`.
+
+Para cada módulo en `modules:`, genera `system/{nombre-del-modulo}.yaml` con: aggregates, entities, valueObjects, enums (con transitions si aplica), events, endpoints, listeners y ports — todo inferido del `system.yaml`.
+
+---
+
+## Paso 8 — Crear especificación técnica por módulo
+
+Lee `references/module-spec.md` para la estructura obligatoria del `system/{module}.md`.
+
+Para cada módulo, genera `system/{nombre-del-modulo}.md` con: rol del módulo, invariantes, máquina de estados, diagrama de interacciones, diagrama de secuencia, casos de uso detallados, endpoints, eventos y puertos.
+
+---
+
+## Ciclo de refinamiento
+
+Después de entregar v1, si el usuario pide ajustes:
+- Aplica el **cambio mínimo** necesario
+- Revalida el checklist del Paso 4
+- Actualiza `system.md`, `c4-context.mmd`, `c4-container.mmd`, `{module}.yaml` y `{module}.md` afectados
+- Entrega solo el diff explicado