maestro-bundle 1.3.0 → 1.4.0

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

@@ -1,22 +1,42 @@
 ---
 name: jhipster-service
-description: Criar e configurar um microsserviço JHipster com Spring Boot, incluindo API, banco próprio e comunicação inter-serviço. Use quando precisar criar um novo microsserviço, configurar Feign clients, ou definir APIs internas.
+description: Create and configure JHipster microservices with Spring Boot, including API, own database, Feign clients, and Kafka communication. Use when creating a new microservice, configuring inter-service communication, or defining internal APIs.
+version: 1.0.0
+author: Maestro
 ---
 
 # JHipster Microservice
 
-## Criar novo serviço
+Create and configure JHipster microservices with their own database, Feign clients for synchronous communication, and Kafka for asynchronous messaging.
+
+## When to Use
+- When creating a new microservice
+- When configuring Feign clients for service-to-service calls
+- When setting up Kafka producers/consumers
+- When defining internal API contracts
+- When implementing circuit breakers and fallbacks
+
+## Available Operations
+1. Generate a new microservice with JHipster
+2. Configure database and service properties
+3. Create Feign clients with fallbacks
+4. Set up Kafka producers and consumers
+5. Define internal API contracts with DTOs
+
+## Multi-Step Workflow
+
+### Step 1: Generate the Microservice
 
 ```bash
-# Gerar via JDL (recomendado)
+# Generate via JDL (recommended)
 jhipster import-jdl jhipster-jdl.jdl
 
-# Ou gerar manualmente
+# Or generate manually
 mkdir bundle-service && cd bundle-service
 jhipster --blueprints="" --skip-client
 ```
 
-## Configuração do serviço
+### Step 2: Configure the Service
 
 ```yaml
 # application.yml
@@ -26,14 +46,14 @@ spring:
 server:
   port: 8084
 
-# Banco próprio (database per service)
+# Own database (database per service)
 spring:
   datasource:
     url: jdbc:postgresql://localhost:5432/bundle_service
     username: bundle
     password: bundle
 
-# Kafka
+# Kafka bindings
 spring:
   cloud:
     stream:
@@ -48,7 +68,7 @@ spring:
           group: bundle-service
 ```
 
-## Comunicação Síncrona — Feign
+### Step 3: Create Feign Clients (Synchronous Communication)
 
 ```java
 @FeignClient(name = "demand-service", fallback = DemandServiceFallback.class)
@@ -78,7 +98,7 @@ public class DemandServiceFallback implements DemandServiceClient {
 }
 ```
 
-## Comunicação Assíncrona — Kafka
+### Step 4: Set Up Kafka (Asynchronous Communication)
 
 ```java
 // Producer
@@ -104,12 +124,10 @@ public Consumer<DemandCreatedEvent> demandEvents() {
 }
 ```
 
-## Padrão de API interna
-
-APIs entre serviços usam DTOs compartilhados (nunca entities):
+### Step 5: Define Internal API DTOs
 
 ```java
-// Shared DTO — package separado ou duplicado (não compartilhar JARs)
+// Shared DTO -- package separado or duplicated (never share JARs)
 public record AgentAllocationRequest(
     Long taskId,
     AgentType requiredType,
@@ -123,9 +141,54 @@ public record AgentAllocationResponse(
 ) {}
 ```
 
-## Regras
+### Step 6: Build and Run
+
+```bash
+# Build the service
+./mvnw compile
+
+# Run tests
+./mvnw test
+
+# Start the service
+./mvnw spring-boot:run
+
+# Verify registration in Consul
+curl http://localhost:8500/v1/health/service/bundle-service
+```
 
-- Cada serviço tem seu próprio banco — NUNCA acessar banco de outro
-- Falha de um serviço NÃO pode derrubar outros (circuit breaker)
-- Eventos Kafka para notificação, Feign para query
-- Idempotência em consumers Kafka (mesmo evento pode chegar 2x)
+## Resources
+- `references/service-patterns.md` - Microservice communication patterns and best practices
+
+## Examples
+### Example 1: Create a New Microservice
+User asks: "Create a new notification-service"
+Response approach:
+1. Generate with `jhipster --skip-client` in a new directory
+2. Configure `spring.application.name: notification-service`
+3. Set up its own PostgreSQL database
+4. Register with Consul
+5. Add Kafka consumer for events it needs
+
+### Example 2: Add Inter-Service Communication
+User asks: "The demand-service needs to call agent-service to allocate an agent"
+Response approach:
+1. Create `AgentServiceClient` Feign interface in demand-service
+2. Add fallback class for circuit breaker
+3. Call Feign client from service layer
+4. Test with agent-service running
+
+### Example 3: Handle Service Unavailability
+User asks: "What happens if agent-service is down?"
+Response approach:
+1. Verify Feign fallback is implemented
+2. Add circuit breaker configuration
+3. Log warnings when fallback is triggered
+4. Consider using Kafka for non-critical operations
+
+## Notes
+- Each service has its own database -- NEVER access another service's database
+- One service failing MUST NOT bring down others (circuit breaker)
+- Kafka for notifications, Feign for queries
+- Kafka consumers MUST be idempotent (same event can arrive twice)
+- Duplicate DTOs between services rather than sharing JARs

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

@@ -0,0 +1,40 @@
+# Microservice Communication Patterns
+
+## Synchronous (Feign)
+- Use for: queries, real-time data needs
+- Pattern: Request/Response
+- Failure: Circuit breaker + fallback
+- Discovery: Resolved via Consul/Eureka
+
+```java
+@FeignClient(name = "service-name", fallback = Fallback.class)
+public interface ServiceClient {
+    @GetMapping("/api/resource/{id}")
+    ResourceDTO get(@PathVariable Long id);
+}
+```
+
+## Asynchronous (Kafka)
+- Use for: notifications, event-driven flows
+- Pattern: Publish/Subscribe
+- Failure: DLQ (Dead Letter Queue)
+- Guarantee: At-least-once delivery
+
+```java
+// Producer
+streamBridge.send("topic-out-0", event);
+
+// Consumer
+@Bean
+public Consumer<EventType> topicName() {
+    return event -> { /* handle */ };
+}
+```
+
+## Rules
+1. Database per service -- never share databases
+2. Feign for queries, Kafka for events
+3. Fallbacks for all Feign clients
+4. Idempotent Kafka consumers
+5. Duplicate DTOs, never share JARs
+6. One topic per bounded context

package/templates/bundle-jhipster-microservices/skills/testing-strategy/SKILL.md

@@ -1,27 +1,46 @@
 ---
 name: testing-strategy
-description: Implementar estratégia de testes com unitários, integração e e2e usando Pytest ou JUnit. Use quando for escrever testes, definir estratégia de testes, ou melhorar cobertura.
+description: Implement testing strategy with unit, integration, and e2e tests using Pytest or JUnit. Use when writing tests, defining test strategy, improving coverage, or setting up test infrastructure.
+version: 1.0.0
+author: Maestro
 ---
 
-# Estratégia de Testes
+# Testing Strategy
 
-## Pirâmide
+Implement a comprehensive testing strategy following the test pyramid with unit tests for domain logic, integration tests for infrastructure, and e2e tests for critical flows.
+
+## When to Use
+- When writing tests for new features
+- When defining the test strategy for a module
+- When improving test coverage
+- When setting up test infrastructure (fixtures, factories)
+- When reviewing test quality
+
+## Available Operations
+1. Write unit tests for domain entities and value objects
+2. Write integration tests for repositories
+3. Write API integration tests for controllers
+4. Set up test fixtures and factories
+5. Run tests with coverage reporting
+
+## Multi-Step Workflow
+
+### Step 1: Understand the Test Pyramid
 
 ```
-        /  E2E  \          Poucos, lentos, caros
-       /  Integr. \        Moderados
-      / Unitários   \      Muitos, rápidos, baratos
+        /  E2E  \          Few, slow, expensive
+       /  Integr. \        Moderate
+      / Unit Tests  \      Many, fast, cheap
 ```
 
-## Testes Unitários — Domínio
-
-Testar regras de negócio sem infraestrutura.
+### Step 2: Write Unit Tests for Domain Logic
+Test business rules without infrastructure dependencies.
 
 ```python
 # tests/domain/test_demand.py
 class TestDemand:
     def test_should_decompose_new_demand(self):
-        demand = Demand(id=DemandId.generate(), description="Criar CRUD")
+        demand = Demand(id=DemandId.generate(), description="Create CRUD")
         planner = FakePlanner(tasks=[Task(...), Task(...)])
 
         tasks = demand.decompose(planner)
@@ -30,14 +49,14 @@ class TestDemand:
         assert demand.status == DemandStatus.PLANNED
 
     def test_should_reject_decompose_if_already_planned(self):
-        demand = Demand(id=DemandId.generate(), description="Criar CRUD")
+        demand = Demand(id=DemandId.generate(), description="Create CRUD")
         demand.decompose(FakePlanner(tasks=[Task(...)]))
 
         with pytest.raises(DemandAlreadyDecomposedException):
             demand.decompose(FakePlanner(tasks=[]))
 
     def test_should_not_allow_more_than_20_tasks(self):
-        demand = Demand(id=DemandId.generate(), description="Mega projeto")
+        demand = Demand(id=DemandId.generate(), description="Large project")
         for i in range(20):
             demand.add_task(Task(...))
 
@@ -45,7 +64,7 @@ class TestDemand:
             demand.add_task(Task(...))
 ```
 
-## Testes Unitários — Value Objects
+### Step 3: Write Unit Tests for Value Objects
 
 ```python
 class TestComplianceScore:
@@ -62,7 +81,7 @@ class TestComplianceScore:
             ComplianceScore(150.0)
 ```
 
-## Testes de Integração — Repositórios
+### Step 4: Write Integration Tests for Repositories
 
 ```python
 # tests/infrastructure/test_pg_demand_repository.py
@@ -84,12 +103,74 @@ class TestPgDemandRepository:
         assert found.description == "Test"
 ```
 
-## Naming
-
+### Step 5: Run Tests with Coverage
+
+```bash
+# Python with Pytest
+pytest --cov=src --cov-report=html --cov-fail-under=80
+pytest tests/domain/ -v          # Unit tests only
+pytest tests/infrastructure/ -v  # Integration tests only
+
+# Java with Maven
+./mvnw test                                    # All tests
+./mvnw test -Dtest="*DomainTest"              # Domain tests only
+./mvnw test -Dtest="*RepositoryIT"            # Repository integration tests
+./mvnw test -Dtest="*ResourceIT"              # API integration tests
+./mvnw verify -Pcoverage                       # With coverage report
+
+# Angular
+npm test                        # Unit tests
+npm run test -- --code-coverage # With coverage
+npm run e2e                     # End-to-end tests
 ```
-test_should_<resultado>_when_<condição>
 
-test_should_return_error_when_email_is_invalid
-test_should_decompose_demand_when_status_is_created
-test_should_reject_merge_when_conflicts_exist
+### Step 6: Review Coverage Report
+
+```bash
+# Python
+open htmlcov/index.html
+
+# Java (JaCoCo)
+open target/site/jacoco/index.html
+
+# Angular
+open coverage/index.html
 ```
+
+## Resources
+- `references/test-naming.md` - Test naming conventions and patterns
+
+## Examples
+### Example 1: Test a New Entity
+User asks: "Write tests for the Demand entity"
+Response approach:
+1. Test happy path: create, decompose, complete
+2. Test invariants: max tasks, status transitions
+3. Test edge cases: empty description, null values
+4. Use `test_should_<result>_when_<condition>` naming
+5. Run `pytest tests/domain/test_demand.py -v`
+
+### Example 2: Test a Repository
+User asks: "Write integration tests for the DemandRepository"
+Response approach:
+1. Set up test database fixture with rollback
+2. Test save and find operations
+3. Test query methods (findByStatus, etc.)
+4. Test not-found scenarios
+5. Run `pytest tests/infrastructure/ -v`
+
+### Example 3: Improve Test Coverage
+User asks: "Our coverage is at 60%, we need 80%"
+Response approach:
+1. Run `pytest --cov=src --cov-report=html` to see uncovered lines
+2. Identify untested domain logic (highest priority)
+3. Write tests for uncovered business rules first
+4. Then cover integration points
+5. Verify with `pytest --cov-fail-under=80`
+
+## Notes
+- Test naming convention: `test_should_<result>_when_<condition>`
+- Domain tests should have ZERO infrastructure dependencies
+- Integration tests should use rollback to avoid polluting the database
+- Minimum coverage target: 80% for business logic
+- Use fakes/stubs for domain tests, real implementations for integration tests

package/templates/bundle-jhipster-microservices/skills/testing-strategy/references/test-naming.md

@@ -0,0 +1,55 @@
+# Test Naming Conventions
+
+## Pattern
+```
+test_should_<expected_result>_when_<condition>
+```
+
+## Examples
+```
+test_should_return_error_when_email_is_invalid
+test_should_decompose_demand_when_status_is_created
+test_should_reject_merge_when_conflicts_exist
+test_should_allocate_agent_when_team_has_capacity
+test_should_raise_exception_when_score_exceeds_100
+test_should_complete_demand_when_all_tasks_done
+```
+
+## Java/JUnit Equivalent
+```java
+@Test
+void shouldReturnErrorWhenEmailIsInvalid() { ... }
+
+@Test
+void shouldDecomposeDemandWhenStatusIsCreated() { ... }
+```
+
+## Test Structure (AAA Pattern)
+```python
+def test_should_decompose_new_demand(self):
+    # Arrange
+    demand = Demand(id=DemandId.generate(), description="Create CRUD")
+    planner = FakePlanner(tasks=[Task(...), Task(...)])
+
+    # Act
+    tasks = demand.decompose(planner)
+
+    # Assert
+    assert len(tasks) == 2
+    assert demand.status == DemandStatus.PLANNED
+```
+
+## Test Categories
+| Category | Location | Dependencies | Speed |
+|---|---|---|---|
+| Unit (Domain) | tests/domain/ | None | Fast |
+| Unit (Application) | tests/application/ | Mocked | Fast |
+| Integration | tests/infrastructure/ | DB, Kafka | Medium |
+| API/Controller | tests/api/ | Full stack | Medium |
+| E2E | tests/e2e/ | Full system | Slow |
+
+## Coverage Targets
+- Domain logic: 90%+
+- Application layer: 80%+
+- Infrastructure: 70%+
+- Overall minimum: 80%

package/templates/bundle-jhipster-monorepo/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-monorepo/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/
+```