maestro-bundle 1.3.1 → 1.4.0

package/templates/bundle-jhipster-microservices/skills/ci-cd-pipeline/references/gitlab-ci-templates.md

@@ -0,0 +1,93 @@
+# GitLab CI Templates Reference
+
+## Pipeline Stages
+```yaml
+stages:
+  - lint
+  - test
+  - security
+  - build
+  - deploy-staging
+  - deploy-prod
+```
+
+## Java/Maven Lint Template
+```yaml
+.lint-java:
+  stage: lint
+  image: maven:3.9-eclipse-temurin-21
+  script:
+    - ./mvnw checkstyle:check -DskipTests
+    - ./mvnw pmd:check -DskipTests
+```
+
+## Java/Maven Test Template
+```yaml
+.test-java:
+  stage: test
+  image: maven:3.9-eclipse-temurin-21
+  services:
+    - postgres:16
+  variables:
+    SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/testdb
+  script:
+    - ./mvnw verify -Pprod -DskipTests=false
+  artifacts:
+    reports:
+      junit: target/surefire-reports/*.xml
+```
+
+## Angular Test Template
+```yaml
+.test-angular:
+  stage: test
+  image: node:20-slim
+  script:
+    - npm ci
+    - npm run lint
+    - npm test -- --coverage
+```
+
+## Jib Build Template
+```yaml
+.build-jib:
+  stage: build
+  script:
+    - ./mvnw -ntp verify -DskipTests jib:build
+        -Djib.to.image=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
+        -Djib.to.auth.username=$CI_REGISTRY_USER
+        -Djib.to.auth.password=$CI_REGISTRY_PASSWORD
+  only:
+    - main
+    - develop
+```
+
+## K8s Deploy Template
+```yaml
+.deploy-k8s:
+  image: bitnami/kubectl:latest
+  script:
+    - kubectl -n $NAMESPACE set image deployment/$SERVICE app=$IMAGE:$TAG
+    - kubectl -n $NAMESPACE rollout status deployment/$SERVICE --timeout=120s
+```
+
+## Security Scan Template
+```yaml
+.security-scan:
+  stage: security
+  script:
+    - ./mvnw org.owasp:dependency-check-maven:check
+  allow_failure: true
+  artifacts:
+    paths:
+      - target/dependency-check-report.html
+```
+
+## CI Variables to Configure
+| Variable | Purpose |
+|---|---|
+| `CI_REGISTRY_IMAGE` | Docker registry URL |
+| `CI_REGISTRY_USER` | Registry username |
+| `CI_REGISTRY_PASSWORD` | Registry password |
+| `K3S_NAMESPACE` | Kubernetes namespace |
+| `KUBECONFIG` | K8s config (file variable) |

package/templates/bundle-jhipster-microservices/skills/clean-architecture/SKILL.md

@@ -1,28 +1,49 @@
 ---
 name: clean-architecture
-description: Implementar Clean Architecture com camadas de domínio, aplicação e infraestrutura. Use quando for criar módulos, organizar código em camadas, separar regras de negócio de infraestrutura, ou estruturar um projeto novo.
+description: Implement Clean Architecture with domain, application, and infrastructure layers. Use when creating modules, organizing code in layers, separating business rules from infrastructure, or structuring a new project.
+version: 1.0.0
+author: Maestro
 ---
 
 # Clean Architecture
 
-## Camadas
+Implement Clean Architecture with properly separated layers, dependency inversion, and domain-centric design.
+
+## When to Use
+- When creating a new module or bounded context
+- When organizing code into proper layers
+- When separating business rules from infrastructure
+- When reviewing architecture compliance
+- When refactoring a monolithic service class
+
+## Available Operations
+1. Create domain layer with entities and repository interfaces
+2. Create application layer with use cases
+3. Create infrastructure layer with adapters
+4. Verify dependency direction compliance
+5. Refactor code to follow Clean Architecture
+
+## Multi-Step Workflow
+
+### Step 1: Understand the Layer Structure
 
 ```
-┌──────────────────────────────┐
-│         API / CLI            │  ← Controllers, Routers
-├──────────────────────────────┤
-│        APPLICATION           │  ← Use Cases, DTOs
-├──────────────────────────────┤
-│          DOMAIN              │  ← Entities, VOs, Events, Repos (interface)
-├──────────────────────────────┤
-│       INFRASTRUCTURE         │  ← DB, HTTP clients, Frameworks
-└──────────────────────────────┘
-
-Dependency Rule: setas apontam para DENTRO (infra → domain)
-Domain NUNCA importa de infrastructure
++------------------------------+
+|         API / CLI            |  <-- Controllers, Routers
++------------------------------+
+|        APPLICATION           |  <-- Use Cases, DTOs
++------------------------------+
+|          DOMAIN              |  <-- Entities, VOs, Events, Repos (interface)
++------------------------------+
+|       INFRASTRUCTURE         |  <-- DB, HTTP clients, Frameworks
++------------------------------+
+
+Dependency Rule: arrows point INWARD (infra -> domain)
+Domain NEVER imports from infrastructure
 ```
 
-## Domain Layer
+### Step 2: Implement the Domain Layer
+The domain layer contains entities, value objects, domain events, and repository interfaces (ports).
 
 ```python
 # domain/entities/demand.py
@@ -45,7 +66,7 @@ class Demand:
     def pending_events(self) -> list[DomainEvent]:
         return list(self._events)
 
-# domain/repositories/demand_repository.py (PORT - apenas interface)
+# domain/repositories/demand_repository.py (PORT - interface only)
 class DemandRepository(ABC):
     @abstractmethod
     def find_by_id(self, id: DemandId) -> Demand: ...
@@ -53,7 +74,8 @@ class DemandRepository(ABC):
     def save(self, demand: Demand) -> None: ...
 ```
 
-## Application Layer
+### Step 3: Implement the Application Layer
+Use cases orchestrate domain operations. They contain NO business rules.
 
 ```python
 # application/use_cases/decompose_demand.py
@@ -72,7 +94,8 @@ class DecomposeDemand:
         return DecomposeDemandOutput(tasks=[TaskDTO.from_entity(t) for t in tasks])
 ```
 
-## Infrastructure Layer
+### Step 4: Implement the Infrastructure Layer
+Adapters implement the ports defined in the domain layer.
 
 ```python
 # infrastructure/persistence/pg_demand_repository.py (ADAPTER)
@@ -92,8 +115,51 @@ class PgDemandRepository(DemandRepository):
         self._session.commit()
 ```
 
-## Regra de ouro
+### Step 5: Verify Architecture Compliance
+
+```bash
+# Check for dependency violations: domain should not import infrastructure
+grep -rn "from infrastructure" src/domain/ --include="*.py"
+grep -rn "from.*infrastructure" src/domain/ --include="*.java"
 
-Use Case orquestra → Entity contém regra → Repository persiste
+# Run tests per layer
+pytest tests/domain/       # Unit tests (no infra deps)
+pytest tests/application/  # Use case tests (mocked deps)
+pytest tests/infrastructure/  # Integration tests
+```
 
-Nunca colocar regra de negócio no Controller, Repository ou "Service" genérico.
+## Resources
+- `references/layer-rules.md` - Layer dependency rules and package organization
+
+## Examples
+### Example 1: Create a New Domain Module
+User asks: "Create the demand management module with Clean Architecture"
+Response approach:
+1. Create `domain/entities/demand.py` with entity and behavior
+2. Create `domain/repositories/demand_repository.py` as interface (port)
+3. Create `application/use_cases/create_demand.py` as orchestrator
+4. Create `infrastructure/persistence/pg_demand_repository.py` as adapter
+5. Wire dependencies via DI container
+
+### Example 2: Refactor a Fat Service
+User asks: "This service has 500 lines and mixes business logic with database calls"
+Response approach:
+1. Extract business rules into domain entities
+2. Extract repository interface from data access code
+3. Create use case class for orchestration
+4. Move database code to infrastructure adapter
+5. Verify no domain imports from infrastructure
+
+### Example 3: Verify Architecture
+User asks: "Check if our code follows Clean Architecture"
+Response approach:
+1. Search for dependency violations with grep
+2. Check that domain layer has no framework imports
+3. Verify use cases only orchestrate, not contain logic
+4. Check that entities have behavior, not just data
+
+## Notes
+- Golden Rule: Use Case orchestrates -> Entity contains rules -> Repository persists
+- Never put business logic in Controller, Repository, or generic "Service"
+- Domain layer must be testable without any infrastructure
+- Use dependency injection to wire adapters to ports

package/templates/bundle-jhipster-microservices/skills/clean-architecture/references/layer-rules.md

@@ -0,0 +1,78 @@
+# Clean Architecture Layer Rules
+
+## Dependency Direction
+```
+API/CLI --> APPLICATION --> DOMAIN <-- INFRASTRUCTURE
+```
+- All dependencies point toward DOMAIN
+- Domain NEVER imports from Application, Infrastructure, or API
+- Infrastructure implements Domain interfaces (Dependency Inversion)
+
+## Layer Contents
+
+### Domain Layer
+- Entities (with behavior, not anemic)
+- Value Objects (immutable, validated)
+- Domain Events
+- Repository Interfaces (Ports)
+- Domain Services (cross-entity logic)
+- Exceptions (business exceptions)
+
+### Application Layer
+- Use Cases (one per operation)
+- Input/Output DTOs
+- Application Services (orchestration only)
+- NO business rules here
+
+### Infrastructure Layer
+- Repository Implementations (Adapters)
+- Database Models/Mappings
+- HTTP Clients
+- Message Queue Producers/Consumers
+- Framework Configuration
+
+### API Layer
+- REST Controllers
+- GraphQL Resolvers
+- CLI Commands
+- Request/Response mapping
+
+## Package Organization (Java)
+```
+com.myapp/
+  domain/
+    model/         # Entities, VOs
+    event/         # Domain Events
+    repository/    # Repository interfaces
+    service/       # Domain Services
+    exception/     # Business exceptions
+  application/
+    usecase/       # Use Cases
+    dto/           # Input/Output DTOs
+  infrastructure/
+    persistence/   # JPA Repositories
+    messaging/     # Kafka/RabbitMQ
+    http/          # REST clients
+  web/
+    rest/          # Controllers
+```
+
+## Package Organization (Python)
+```
+src/
+  domain/
+    entities/
+    value_objects/
+    events/
+    repositories/  # ABC interfaces
+    services/
+  application/
+    use_cases/
+    dto/
+  infrastructure/
+    persistence/
+    messaging/
+    http_clients/
+  api/
+    routes/
+```

package/templates/bundle-jhipster-microservices/skills/ddd-tactical/SKILL.md

@@ -1,13 +1,32 @@
 ---
 name: ddd-tactical
-description: Implementar padrões táticos do DDD - Entities, Value Objects, Aggregates, Domain Events, Repositories e Domain Services. Use quando for modelar domínio, criar entidades ricas, ou aplicar DDD no código.
+description: Implement DDD tactical patterns -- Entities, Value Objects, Aggregates, Domain Events, Repositories, and Domain Services. Use when modeling domain, creating rich entities, defining aggregates, or applying DDD patterns.
+version: 1.0.0
+author: Maestro
 ---
 
-# DDD Tático
+# DDD Tactical Patterns
 
-## Value Objects
+Implement Domain-Driven Design tactical patterns including Entities, Value Objects, Aggregates, Domain Events, Repositories, and Domain Services.
 
-Imutáveis, comparados por valor, contêm validação.
+## When to Use
+- When modeling domain entities with rich behavior
+- When creating value objects for validated types
+- When defining aggregate boundaries and invariants
+- When implementing domain events for cross-aggregate communication
+- When business logic spans multiple entities (Domain Services)
+
+## Available Operations
+1. Create Value Objects with validation
+2. Create Entities with identity and behavior
+3. Define Aggregates with invariant protection
+4. Implement Domain Events
+5. Create Domain Services for cross-entity logic
+
+## Multi-Step Workflow
+
+### Step 1: Identify Value Objects
+Value Objects are immutable, compared by value, and contain self-validation.
 
 ```python
 @dataclass(frozen=True)
@@ -24,7 +43,7 @@ class ComplianceScore:
 
     def __post_init__(self):
         if not 0 <= self.value <= 100:
-            raise ValueError("Score deve ser entre 0 e 100")
+            raise ValueError("Score must be between 0 and 100")
 
     def is_passing(self) -> bool:
         return self.value >= 80.0
@@ -33,9 +52,8 @@ class ComplianceScore:
         return f"{self.value:.1f}%"
 ```
 
-## Entities
-
-Identidade única, mutáveis, contêm comportamento.
+### Step 2: Create Entities
+Entities have unique identity, are mutable, and contain behavior.
 
 ```python
 class Task:
@@ -66,31 +84,29 @@ class Task:
         return None
 ```
 
-## Aggregates
-
-Cluster de entities com uma raiz que protege invariantes.
+### Step 3: Define Aggregates
+An Aggregate is a cluster of entities with a root that protects invariants.
 
 ```python
 class Demand:  # Aggregate Root
-    """Demand é a raiz. Tasks só são acessadas via Demand."""
+    """Demand is the root. Tasks are only accessed via Demand."""
 
     def add_task(self, task: Task) -> None:
         if len(self._tasks) >= 20:
-            raise TooManyTasksException("Máximo 20 tasks por demanda")
+            raise TooManyTasksException("Maximum 20 tasks per demand")
         self._tasks.append(task)
 
     def start_task(self, task_id: TaskId) -> None:
         task = self._find_task(task_id)
-        # Verificar invariante: não ter mais de 3 tasks simultâneas
+        # Invariant: no more than 3 concurrent tasks
         active = [t for t in self._tasks if t.status == TaskStatus.IN_PROGRESS]
         if len(active) >= 3:
             raise TooManyActiveTasksException()
         task.start()
 ```
 
-## Domain Events
-
-Notificam que algo aconteceu no domínio.
+### Step 4: Implement Domain Events
+Domain Events notify that something happened in the domain.
 
 ```python
 @dataclass(frozen=True)
@@ -112,9 +128,8 @@ class ComplianceViolationDetected(DomainEvent):
     severity: str  # "warning" | "critical"
 ```
 
-## Domain Services
-
-Lógica que não pertence a uma única entidade.
+### Step 5: Create Domain Services
+For logic that does not belong to a single entity.
 
 ```python
 class TeamRecruitmentService:
@@ -130,9 +145,63 @@ class TeamRecruitmentService:
         return team
 ```
 
-## Ordem de prioridade para regras
+### Step 6: Write Tests for Domain Logic
+
+```bash
+# Run domain unit tests (no infrastructure dependencies)
+pytest tests/domain/ -v
+
+# For Java/JUnit
+./mvnw test -Dtest="*DomainTest,*ValueObjectTest"
+```
+
+```python
+class TestComplianceScore:
+    def test_passing_score(self):
+        score = ComplianceScore(85.0)
+        assert score.is_passing() is True
+
+    def test_invalid_score_raises(self):
+        with pytest.raises(ValueError):
+            ComplianceScore(150.0)
+```
 
-1. **Value Object** — validação e comportamento simples
-2. **Entity** — regras que envolvem estado da entidade
-3. **Domain Service** — regras que envolvem múltiplas entidades
-4. **Use Case** — orquestração (NÃO contém regras)
+## Resources
+- `references/ddd-patterns.md` - DDD pattern decision guide and examples
+
+## Examples
+### Example 1: Create a Value Object
+User asks: "Create a value object for email validation"
+Response approach:
+1. Create immutable dataclass/record with validation in constructor
+2. Add behavior methods (e.g., `domain()`, `is_corporate()`)
+3. Ensure equality by value, not reference
+4. Write unit tests for valid and invalid cases
+
+### Example 2: Define an Aggregate
+User asks: "Model a Demand that contains Tasks with business rules"
+Response approach:
+1. Make Demand the Aggregate Root
+2. Tasks are only accessed through Demand methods
+3. Add invariants: max tasks, max concurrent, completion rules
+4. Emit domain events on state changes
+5. Write tests for each invariant
+
+### Example 3: Implement a Domain Service
+User asks: "I need logic that involves both Demands and Agents"
+Response approach:
+1. Create a Domain Service (not a generic "Service")
+2. Accept entities as parameters, not IDs
+3. Implement the cross-entity logic
+4. Return results, let the use case persist
+5. Write tests with test doubles for entities
+
+## Notes
+- Priority for placing business rules:
+  1. **Value Object** -- validation and simple behavior
+  2. **Entity** -- rules involving entity state
+  3. **Domain Service** -- rules involving multiple entities
+  4. **Use Case** -- orchestration only (NO business rules)
+- Aggregates should be small -- prefer separate aggregates connected by ID
+- Domain Events are immutable records of what happened
+- Domain layer must have zero framework dependencies

package/templates/bundle-jhipster-microservices/skills/ddd-tactical/references/ddd-patterns.md

@@ -0,0 +1,48 @@
+# DDD Tactical Patterns Reference
+
+## Decision Guide: Where to Put Business Logic
+
+| Pattern | When to Use | Example |
+|---|---|---|
+| Value Object | Validation, simple behavior, no identity | Email, Money, ComplianceScore |
+| Entity | Has identity, mutable state, behavior | Task, Agent, Demand |
+| Aggregate | Cluster with invariants, transactional boundary | Demand (root) + Tasks (children) |
+| Domain Event | Notify something happened | TaskCompleted, DemandCreated |
+| Domain Service | Logic spanning multiple entities | TeamRecruitmentService |
+| Repository (Port) | Persistence abstraction | DemandRepository (interface) |
+
+## Value Object Checklist
+- [ ] Immutable (frozen dataclass / Java record)
+- [ ] Validated in constructor
+- [ ] Compared by value, not reference
+- [ ] Contains behavior methods
+- [ ] No identity field
+
+## Entity Checklist
+- [ ] Has unique identity (ID)
+- [ ] Mutable state with controlled transitions
+- [ ] Contains behavior (not anemic)
+- [ ] State changes enforce invariants
+- [ ] Compared by identity, not value
+
+## Aggregate Checklist
+- [ ] Has a single root entity
+- [ ] Children accessed only through root
+- [ ] Invariants enforced by root
+- [ ] Small boundary (prefer separate aggregates)
+- [ ] Cross-aggregate references by ID only
+- [ ] One aggregate per transaction
+
+## Domain Event Checklist
+- [ ] Immutable (record/frozen dataclass)
+- [ ] Contains occurred_at timestamp
+- [ ] Named in past tense (TaskCompleted, not CompleteTask)
+- [ ] Contains only IDs and primitives (no entity references)
+- [ ] Published after aggregate state change
+
+## Domain Service Checklist
+- [ ] Logic involves multiple aggregates
+- [ ] Stateless (no internal state)
+- [ ] Named after the operation (TeamRecruitmentService)
+- [ ] Accepts entities as parameters
+- [ ] Does not persist (caller persists)

package/templates/bundle-jhipster-microservices/skills/jhipster-angular/SKILL.md

@@ -1,25 +1,42 @@
 ---
 name: jhipster-angular
-description: Desenvolver frontend Angular no Gateway JHipster que consome múltiplos microsserviços. Use quando precisar criar telas que agregam dados de vários serviços, ou customizar o frontend do Gateway.
+description: Develop Angular frontend in the JHipster Gateway consuming multiple microservices. Use when creating screens that aggregate data from multiple services, handling partial failures, or customizing the Gateway frontend.
+version: 1.0.0
+author: Maestro
 ---
 
-# JHipster Angular — Microservices
+# JHipster Angular -- Microservices
 
-## Diferença do Monorepo
+Develop the Angular frontend hosted in the Gateway, which transparently consumes multiple microservices through the Gateway's routing.
 
-No microservices, o Angular fica no **Gateway**. Ele não sabe que existem múltiplos serviços — o Gateway roteia transparentemente.
+## When to Use
+- When creating screens that aggregate data from multiple services
+- When building dashboards with data from different microservices
+- When handling partial service failures gracefully in the UI
+- When adding WebSocket real-time features via the Gateway
+
+## Available Operations
+1. Create services that aggregate data from multiple backends
+2. Handle partial service failures with fallback UI
+3. Add WebSocket real-time updates
+4. Build cross-service dashboards
+5. Customize entity components from different services
+
+## Multi-Step Workflow
+
+### Step 1: Understand the Architecture
 
 ```
-Browser → Gateway:8080/api/demands → demand-service:8081/api/demands
-Browser → Gateway:8080/api/agents  → agent-service:8082/api/agents
+Browser --> Gateway:8080/api/demands --> demand-service:8081/api/demands
+Browser --> Gateway:8080/api/agents  --> agent-service:8082/api/agents
 ```
 
-Do ponto de vista do Angular, tudo é uma API só.
+The Angular app lives in the Gateway. From Angular's perspective, everything is a single API.
 
-## Services que agregam dados
+### Step 2: Create Services That Aggregate Data
 
 ```typescript
-// dashboard.service.ts — agrega dados de múltiplos serviços (via gateway)
+// dashboard.service.ts -- aggregates data from multiple services (via gateway)
 @Injectable({ providedIn: 'root' })
 export class DashboardService {
   constructor(
@@ -39,15 +56,13 @@ export class DashboardService {
 }
 ```
 
-## Tratamento de falha parcial
-
-Se um serviço estiver fora do ar, mostrar o que conseguir:
+### Step 3: Handle Partial Service Failures
 
 ```typescript
 getMetrics(): Observable<DashboardMetrics> {
   return forkJoin({
     activeDemands: this.demandService.countByStatus('IN_PROGRESS').pipe(
-      catchError(() => of({ count: -1 }))  // -1 = indisponível
+      catchError(() => of({ count: -1 }))  // -1 = unavailable
     ),
     activeAgents: this.agentService.countByStatus('BUSY').pipe(
       catchError(() => of({ count: -1 }))
@@ -61,14 +76,13 @@ getMetrics(): Observable<DashboardMetrics> {
   {{ metrics.activeDemands.count }}
 </div>
 <ng-template #unavailable>
-  <span class="text-muted">Indisponível</span>
+  <span class="text-muted">Unavailable</span>
 </ng-template>
 ```
 
-## WebSocket para real-time
+### Step 4: Add WebSocket for Real-Time Updates
 
 ```typescript
-// No Gateway, conectar via STOMP
 @Injectable({ providedIn: 'root' })
 export class WebSocketService {
   private stompClient: RxStomp;
@@ -89,9 +103,37 @@ export class WebSocketService {
 }
 ```
 
-## Regras
+### Step 5: Build and Verify
+
+```bash
+npm start
+npm test
+npm run lint
+npm run build
+```
 
-- Frontend no Gateway, não nos serviços
-- Tratar falha de serviços individuais gracefully
-- Usar `forkJoin` para agregar, `catchError` para resiliência
-- Lazy loading por módulo/feature
+## Resources
+- `references/angular-microservices.md` - Angular patterns for microservices architecture
+
+## Examples
+### Example 1: Build a Cross-Service Dashboard
+User asks: "Create a dashboard showing demands, agents, and metrics"
+Response approach:
+1. Create `DashboardService` using `forkJoin` to aggregate data
+2. Add `catchError` for each service call
+3. Create dashboard component with metric cards
+4. Show "Unavailable" when a service is down
+5. Run `npm start` to verify
+
+### Example 2: Handle Service Outage
+User asks: "The agent-service is down, the dashboard crashes"
+Response approach:
+1. Add `catchError(() => of(fallbackValue))` to the agent-service call
+2. Show graceful "unavailable" UI instead of error
+3. Other service data should still display correctly
+
+## Notes
+- Frontend lives in the Gateway, NOT in individual services
+- Treat partial failures gracefully -- show what you can
+- Use `forkJoin` for aggregation, `catchError` for resilience
+- Use lazy loading per module/feature