maestro-bundle 1.0.0

package/templates/bundle-frontend-spa/skills/state-management/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: state-management
+description: Gerenciar estado com Zustand para estado global e React Query para server state. Use quando precisar gerenciar estado da aplicação, cache de API, ou estado compartilhado entre componentes.
+---
+
+# State Management
+
+## Regra de ouro
+
+| Tipo de estado | Solução | Exemplo |
+|---|---|---|
+| Server state (API data) | React Query | Lista de demands, dados de agentes |
+| UI state global | Zustand | Sidebar aberta, tema, user logado |
+| UI state local | useState | Modal aberto, input controlado |
+| Form state | React Hook Form | Dados do formulário, validação |
+| Real-time state | Zustand + WebSocket | Status dos agentes, eventos ao vivo |
+
+## React Query — Server State
+
+```tsx
+// services/demandApi.ts
+export const demandApi = {
+  list: (filters?: DemandFilters) =>
+    api.get<PaginatedResponse<Demand>>('/api/v1/demands', { params: filters }),
+  get: (id: string) =>
+    api.get<Demand>(`/api/v1/demands/${id}`),
+  create: (data: CreateDemandDto) =>
+    api.post<Demand>('/api/v1/demands', data),
+};
+
+// hooks/useDemands.ts — nunca duplicar dados da API no Zustand
+export function useDemands(filters?: DemandFilters) {
+  return useQuery({
+    queryKey: ['demands', filters],
+    queryFn: () => demandApi.list(filters),
+  });
+}
+```
+
+## Zustand — UI State Global
+
+```tsx
+interface AppStore {
+  sidebarOpen: boolean;
+  toggleSidebar: () => void;
+  selectedDemandId: string | null;
+  selectDemand: (id: string | null) => void;
+}
+
+export const useAppStore = create<AppStore>((set) => ({
+  sidebarOpen: true,
+  toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
+  selectedDemandId: null,
+  selectDemand: (id) => set({ selectedDemandId: id }),
+}));
+```
+
+## WebSocket — Real-time
+
+```tsx
+interface RealtimeStore {
+  agentStatuses: Record<string, AgentStatus>;
+  events: TrackingEvent[];
+  connect: () => void;
+  disconnect: () => void;
+}
+
+export const useRealtimeStore = create<RealtimeStore>((set) => {
+  let socket: Socket | null = null;
+
+  return {
+    agentStatuses: {},
+    events: [],
+    connect: () => {
+      socket = io(WS_URL);
+      socket.on('agent:status', (data) =>
+        set((s) => ({ agentStatuses: { ...s.agentStatuses, [data.agentId]: data.status } }))
+      );
+      socket.on('tracking:event', (event) =>
+        set((s) => ({ events: [event, ...s.events].slice(0, 100) }))
+      );
+    },
+    disconnect: () => socket?.disconnect(),
+  };
+});
+```

package/templates/bundle-jhipster-microservices/.spec/constitution.md

@@ -0,0 +1,37 @@
+# Constitution — Projeto JHipster Microservices
+
+## Princípios
+
+1. **Spec primeiro, código depois** — Toda demanda passa pelo fluxo SDD antes de implementação
+2. **Database per service** — Cada microsserviço tem seu próprio banco, nunca acessar banco de outro
+3. **Eventos sobre chamadas síncronas** — Preferir Kafka para comunicação, Feign apenas para queries
+4. **Resiliência obrigatória** — Circuit breaker em toda chamada inter-serviço
+5. **Deploy independente** — Cada serviço pode ser deployado sozinho
+6. **Saga over 2PC** — Transações distribuídas via Saga pattern, nunca Two-Phase Commit
+
+## Padrões de desenvolvimento
+
+### Java / Spring Boot
+- Java 21+, Records para DTOs e Events
+- Constructor injection
+- Idempotência em consumers Kafka
+- Fallback methods para circuit breakers
+- Entidades pertencem a UM serviço
+
+### Comunicação
+- Kafka para eventos de domínio (assíncrono)
+- Feign Client para queries (síncrono)
+- DTOs compartilhados por contrato, nunca por JAR
+
+### Infraestrutura
+- Docker Compose para dev
+- Kubernetes/K3s para prod
+- Consul para service discovery
+- Keycloak para OAuth2
+
+## Padrões de qualidade
+
+- Spring Cloud Contract entre serviços
+- Testcontainers para integração
+- Gatling para load testing
+- Deploy via CI/CD, nunca manual

package/templates/bundle-jhipster-microservices/AGENTS.md

@@ -0,0 +1,307 @@
+# Projeto: JHipster Microservices
+
+Você está construindo uma arquitetura de microsserviços com JHipster. Múltiplos serviços Spring Boot, gateway centralizado, service discovery, messaging assíncrono e frontend Angular.
+
+## Specification-Driven Development (SDD)
+
+Este projeto usa **GitHub Spec Kit** para governança. Antes de implementar qualquer demanda:
+
+1. Rodar `/speckit.constitution` — se `.spec/constitution.md` não existir
+2. Rodar `/speckit.specify` — descrever O QUE e POR QUÊ (não como)
+3. Rodar `/speckit.plan` — arquitetura e decisões técnicas
+4. Rodar `/speckit.tasks` — quebrar em tasks atômicas
+5. Rodar `/speckit.implement` — executar as tasks
+
+Nunca pular direto para código. Spec primeiro, código depois.
+
+## References
+
+Documentos de referência que o agente deve consultar quando necessário:
+
+- `references/jhipster-microservices-guide.md` — Guia de microsserviços JHipster
+- `references/kafka-patterns.md` — Padrões de eventos Kafka
+- `references/saga-patterns.md` — Saga pattern para transações distribuídas
+- `references/k8s-deployment.md` — Deploy em Kubernetes
+
+## Stack do projeto
+
+- **Backend:** Java 21 + Spring Boot 3.x (múltiplos serviços JHipster)
+- **Gateway:** JHipster Gateway (Spring Cloud Gateway)
+- **Service Discovery:** JHipster Registry (Eureka) ou Consul
+- **Frontend:** Angular 17+ (no Gateway ou app separado)
+- **Banco:** PostgreSQL (um banco por serviço)
+- **Messaging:** Apache Kafka (padrão JHipster para microservices)
+- **Cache:** Redis (compartilhado)
+- **Auth:** OAuth2 + Keycloak (recomendado para microservices)
+- **Containers:** Docker Compose (dev) + Kubernetes/K3s (prod)
+- **Migrations:** Liquibase (por serviço)
+- **CI/CD:** GitLab CI
+- **Monitoring:** Prometheus + Grafana + ELK/Loki
+
+## Estrutura Multi-Repo ou Monorepo
+
+### Monorepo (recomendado para times pequenos)
+```
+maestro/
+├── gateway/                    # JHipster Gateway + Angular
+│   ├── src/main/java/
+│   ├── src/main/webapp/        # Angular app
+│   └── pom.xml
+├── demand-service/             # Microserviço de demandas
+│   ├── src/main/java/com/empresa/demand/
+│   │   ├── domain/
+│   │   ├── repository/
+│   │   ├── service/
+│   │   ├── web/rest/
+│   │   └── config/
+│   ├── src/main/resources/
+│   │   └── config/liquibase/
+│   └── pom.xml
+├── agent-service/              # Microserviço de agentes
+│   └── ...
+├── tracking-service/           # Microserviço de rastreamento
+│   └── ...
+├── bundle-service/             # Microserviço de bundles/skills
+│   └── ...
+├── docker-compose/             # Docker Compose para dev
+│   ├── docker-compose.yml
+│   ├── keycloak.yml
+│   ├── kafka.yml
+│   ├── postgresql.yml
+│   └── monitoring.yml
+├── k8s/                        # Kubernetes manifests
+│   ├── demand-service/
+│   ├── agent-service/
+│   ├── gateway/
+│   └── registry/
+└── jhipster-jdl.jdl           # JDL completo
+```
+
+## JDL para Microservices
+
+```jdl
+application {
+    config {
+        baseName gateway
+        applicationType gateway
+        packageName com.empresa.gateway
+        serviceDiscoveryType consul
+        authenticationType oauth2
+        prodDatabaseType postgresql
+        buildTool maven
+        clientFramework angular
+    }
+}
+
+application {
+    config {
+        baseName demandService
+        applicationType microservice
+        packageName com.empresa.demand
+        serviceDiscoveryType consul
+        authenticationType oauth2
+        prodDatabaseType postgresql
+        buildTool maven
+        serverPort 8081
+    }
+    entities Demand, Task
+}
+
+application {
+    config {
+        baseName agentService
+        applicationType microservice
+        packageName com.empresa.agent
+        serviceDiscoveryType consul
+        authenticationType oauth2
+        prodDatabaseType postgresql
+        buildTool maven
+        serverPort 8082
+    }
+    entities Agent, AgentTeam, Worktree
+}
+
+application {
+    config {
+        baseName trackingService
+        applicationType microservice
+        packageName com.empresa.tracking
+        serviceDiscoveryType consul
+        authenticationType oauth2
+        prodDatabaseType postgresql
+        buildTool maven
+        serverPort 8083
+    }
+    entities TrackingEvent, TrackingSession
+}
+
+/* Entities */
+entity Demand {
+    description TextBlob required
+    status DemandStatus required
+    priority Priority required
+}
+
+entity Task {
+    description String required
+    status TaskStatus required
+    branchName String
+}
+
+entity Agent {
+    name String required
+    type AgentType required
+    status AgentStatus required
+}
+
+/* Enums */
+enum DemandStatus { CREATED, PLANNED, IN_PROGRESS, COMPLETED }
+enum TaskStatus { PENDING, IN_PROGRESS, COMPLETED, FAILED }
+enum AgentType { FRONTEND, BACKEND, DEVOPS, ML, QA }
+enum AgentStatus { IDLE, BUSY, OFFLINE }
+
+/* Relationships */
+relationship OneToMany {
+    Demand{tasks} to Task{demand required}
+}
+
+/* Options */
+paginate * with pagination
+dto * with mapstruct
+service * with serviceImpl
+
+/* Deployments */
+deployment {
+    deploymentType docker-compose
+    dockerRepositoryName "registry.local/maestro"
+    appsFolders [gateway, demandService, agentService, trackingService]
+    monitoring yes
+    serviceDiscoveryType consul
+}
+
+deployment {
+    deploymentType kubernetes
+    kubernetesNamespace maestro
+    kubernetesServiceType Ingress
+    appsFolders [gateway, demandService, agentService, trackingService]
+    dockerRepositoryName "registry.local/maestro"
+    monitoring yes
+    serviceDiscoveryType consul
+}
+```
+
+## Comunicação entre serviços
+
+### Síncrona — Feign Client (entre serviços)
+```java
+@FeignClient(name = "agentService")
+public interface AgentServiceClient {
+    @GetMapping("/api/agents/available")
+    List<AgentDTO> getAvailableAgents(@RequestParam("type") AgentType type);
+
+    @PostMapping("/api/agents/{id}/allocate")
+    AgentDTO allocateAgent(@PathVariable Long id, @RequestBody AllocateRequest request);
+}
+```
+
+### Assíncrona — Kafka (eventos de domínio)
+```java
+// Producer — demand-service
+@Service
+public class DemandEventProducer {
+    private final KafkaTemplate<String, DemandEvent> kafka;
+
+    public void publishDemandDecomposed(Demand demand) {
+        DemandDecomposed event = new DemandDecomposed(
+            demand.getId(), demand.getTasks().stream().map(Task::getId).toList()
+        );
+        kafka.send("demand-events", demand.getId().toString(), event);
+    }
+}
+
+// Consumer — agent-service
+@Service
+public class DemandEventConsumer {
+    @KafkaListener(topics = "demand-events", groupId = "agent-service")
+    public void onDemandDecomposed(DemandDecomposed event) {
+        // Alocar agentes para as tasks
+        taskAllocationService.allocateForDemand(event.demandId(), event.taskIds());
+    }
+}
+```
+
+## Padrões obrigatórios
+
+### Database per Service
+Cada microsserviço tem seu próprio banco PostgreSQL. Nunca acessar banco de outro serviço diretamente.
+
+### Saga Pattern para transações distribuídas
+```
+demand-service: CreateDemand
+    → kafka: DemandCreated
+        → agent-service: AllocateAgents
+            → kafka: AgentsAllocated
+                → demand-service: UpdateDemandStatus(PLANNED)
+
+Se AgentAllocation falhar:
+    → kafka: AllocationFailed
+        → demand-service: CompensateDemand(CANCELLED)
+```
+
+### Circuit Breaker
+```java
+@CircuitBreaker(name = "agentService", fallbackMethod = "fallbackGetAgents")
+public List<AgentDTO> getAvailableAgents(AgentType type) {
+    return agentServiceClient.getAvailableAgents(type);
+}
+
+public List<AgentDTO> fallbackGetAgents(AgentType type, Throwable t) {
+    log.warn("Agent service unavailable, returning cached agents", t);
+    return cachedAgentService.getCachedAgents(type);
+}
+```
+
+## Docker Compose para dev
+
+```bash
+# Subir tudo
+docker-compose -f docker-compose/docker-compose.yml up -d
+
+# Subir serviço específico
+docker-compose -f docker-compose/docker-compose.yml up -d demand-service
+```
+
+## Kubernetes para prod
+
+```bash
+# Deploy via JHipster
+jhipster kubernetes
+
+# Aplicar
+kubectl apply -f k8s/
+```
+
+## Testes
+
+- **Unit:** JUnit 5 — entidades e services (>= 90% domínio)
+- **Integration:** Testcontainers + PostgreSQL real (>= 70%)
+- **Contract:** Spring Cloud Contract — contratos entre serviços
+- **E2E:** Cypress no gateway
+- **Load:** Gatling (incluso no JHipster)
+
+## Git
+
+- Commits: `feat(demand-service): adicionar saga de alocação`
+- Branches: `feature/<service>-<descricao>`
+- Um PR por serviço quando possível
+- Nunca fazer breaking change em API sem versionar
+
+## O que NÃO fazer
+
+- Não acessar banco de outro serviço diretamente
+- Não fazer chamadas síncronas em cadeia (A→B→C→D) — usar eventos
+- Não compartilhar entities entre serviços — cada um tem seus DTOs
+- Não deployar todos os serviços juntos — deploy independente
+- Não ignorar circuit breakers em chamadas inter-serviço
+- Não usar transações distribuídas (2PC) — usar Saga
+- Não criar um "serviço de tudo" — manter bounded contexts

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

@@ -0,0 +1,112 @@
+---
+name: ci-cd-pipeline
+description: Criar pipelines CI/CD com GitLab CI incluindo lint, test, build, compliance check e deploy. Use quando for configurar CI/CD, criar pipelines, ou automatizar deploy.
+---
+
+# CI/CD Pipeline — GitLab CI
+
+## Pipeline completo
+
+```yaml
+# .gitlab-ci.yml
+stages:
+  - lint
+  - test
+  - security
+  - compliance
+  - build
+  - deploy-staging
+  - deploy-prod
+
+variables:
+  DOCKER_IMAGE: $CI_REGISTRY_IMAGE
+  K3S_NAMESPACE: maestro
+
+# ===== LINT =====
+lint:python:
+  stage: lint
+  image: python:3.11-slim
+  script:
+    - pip install ruff mypy
+    - ruff check src/
+    - mypy src/ --ignore-missing-imports
+
+lint:frontend:
+  stage: lint
+  image: node:20-slim
+  script:
+    - npm ci
+    - npm run lint
+    - npm run type-check
+
+# ===== TEST =====
+test:backend:
+  stage: test
+  image: python:3.11-slim
+  services:
+    - postgres:16
+    - redis:7
+  variables:
+    DATABASE_URL: postgresql://test:test@postgres/testdb
+    REDIS_URL: redis://redis:6379
+  script:
+    - pip install -r requirements.txt
+    - pytest --cov=src --cov-report=xml --cov-fail-under=80
+  artifacts:
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
+
+test:frontend:
+  stage: test
+  image: node:20-slim
+  script:
+    - npm ci
+    - npm run test -- --coverage
+
+# ===== SECURITY =====
+security:scan:
+  stage: security
+  image: python:3.11-slim
+  script:
+    - pip install bandit safety
+    - bandit -r src/ -ll
+    - safety check
+
+# ===== COMPLIANCE =====
+compliance:bundle:
+  stage: compliance
+  script:
+    - python scripts/check_bundle_compliance.py --bundle $BUNDLE_NAME
+    - python scripts/check_structure.py
+  allow_failure: false
+
+# ===== BUILD =====
+build:api:
+  stage: build
+  script:
+    - docker build -f docker/Dockerfile.api -t $DOCKER_IMAGE/api:$CI_COMMIT_SHA .
+    - docker push $DOCKER_IMAGE/api:$CI_COMMIT_SHA
+  only:
+    - main
+    - develop
+
+# ===== DEPLOY =====
+deploy:staging:
+  stage: deploy-staging
+  script:
+    - kubectl -n $K3S_NAMESPACE-staging set image deployment/api api=$DOCKER_IMAGE/api:$CI_COMMIT_SHA
+    - kubectl -n $K3S_NAMESPACE-staging rollout status deployment/api --timeout=120s
+  only:
+    - develop
+
+deploy:prod:
+  stage: deploy-prod
+  script:
+    - kubectl -n $K3S_NAMESPACE set image deployment/api api=$DOCKER_IMAGE/api:$CI_COMMIT_SHA
+    - kubectl -n $K3S_NAMESPACE rollout status deployment/api --timeout=120s
+  only:
+    - main
+  when: manual
+```

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

@@ -0,0 +1,99 @@
+---
+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.
+---
+
+# Clean Architecture
+
+## Camadas
+
+```
+┌──────────────────────────────┐
+│         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
+```
+
+## Domain Layer
+
+```python
+# domain/entities/demand.py
+class Demand:
+    def __init__(self, id: DemandId, description: str):
+        self._id = id
+        self._description = description
+        self._status = DemandStatus.CREATED
+        self._events: list[DomainEvent] = []
+
+    def decompose(self, planner: TaskPlanner) -> list[Task]:
+        if self._status != DemandStatus.CREATED:
+            raise DemandAlreadyDecomposedException(self._id)
+        tasks = planner.plan(self._description)
+        self._status = DemandStatus.PLANNED
+        self._events.append(DemandDecomposed(self._id, [t.id for t in tasks]))
+        return tasks
+
+    @property
+    def pending_events(self) -> list[DomainEvent]:
+        return list(self._events)
+
+# domain/repositories/demand_repository.py (PORT - apenas interface)
+class DemandRepository(ABC):
+    @abstractmethod
+    def find_by_id(self, id: DemandId) -> Demand: ...
+    @abstractmethod
+    def save(self, demand: Demand) -> None: ...
+```
+
+## Application Layer
+
+```python
+# application/use_cases/decompose_demand.py
+class DecomposeDemand:
+    def __init__(self, repo: DemandRepository, planner: TaskPlanner, event_bus: EventBus):
+        self._repo = repo
+        self._planner = planner
+        self._event_bus = event_bus
+
+    def execute(self, demand_id: str) -> DecomposeDemandOutput:
+        demand = self._repo.find_by_id(DemandId(demand_id))
+        tasks = demand.decompose(self._planner)
+        self._repo.save(demand)
+        for event in demand.pending_events:
+            self._event_bus.publish(event)
+        return DecomposeDemandOutput(tasks=[TaskDTO.from_entity(t) for t in tasks])
+```
+
+## Infrastructure Layer
+
+```python
+# infrastructure/persistence/pg_demand_repository.py (ADAPTER)
+class PgDemandRepository(DemandRepository):
+    def __init__(self, session: Session):
+        self._session = session
+
+    def find_by_id(self, id: DemandId) -> Demand:
+        model = self._session.query(DemandModel).get(str(id))
+        if not model:
+            raise DemandNotFoundException(id)
+        return self._to_entity(model)
+
+    def save(self, demand: Demand) -> None:
+        model = self._to_model(demand)
+        self._session.merge(model)
+        self._session.commit()
+```
+
+## Regra de ouro
+
+Use Case orquestra → Entity contém regra → Repository persiste
+
+Nunca colocar regra de negócio no Controller, Repository ou "Service" genérico.