maestro-bundle 1.0.0

package/templates/bundle-ai-agents/skills/api-design/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: api-design
+description: Criar APIs REST com FastAPI ou Spring Boot seguindo padrões de versionamento, paginação, error handling e documentação. Use quando for criar endpoints, definir contratos de API, ou estruturar controllers.
+---
+
+# API Design
+
+## Padrões REST
+
+| Operação | Método | Path | Status | Body |
+|---|---|---|---|---|
+| Listar | GET | `/api/v1/demands` | 200 | Lista paginada |
+| Buscar | GET | `/api/v1/demands/{id}` | 200 | Objeto |
+| Criar | POST | `/api/v1/demands` | 201 | Objeto criado |
+| Atualizar | PUT | `/api/v1/demands/{id}` | 200 | Objeto atualizado |
+| Patch | PATCH | `/api/v1/demands/{id}` | 200 | Objeto atualizado |
+| Deletar | DELETE | `/api/v1/demands/{id}` | 204 | Vazio |
+
+## FastAPI — Template
+
+```python
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+router = APIRouter(prefix="/api/v1/demands", tags=["demands"])
+
+@router.get("/", response_model=PaginatedResponse[DemandResponse])
+async def list_demands(
+    page: int = Query(1, ge=1),
+    size: int = Query(20, ge=1, le=100),
+    status: str | None = None,
+    use_case: ListDemands = Depends()
+):
+    result = use_case.execute(page=page, size=size, status=status)
+    return PaginatedResponse(
+        items=result.items,
+        total=result.total,
+        page=page,
+        size=size
+    )
+
+@router.post("/", response_model=DemandResponse, status_code=201)
+async def create_demand(
+    body: CreateDemandRequest,
+    use_case: CreateDemand = Depends()
+):
+    return use_case.execute(body)
+
+@router.get("/{demand_id}", response_model=DemandResponse)
+async def get_demand(
+    demand_id: str,
+    use_case: GetDemand = Depends()
+):
+    result = use_case.execute(demand_id)
+    if not result:
+        raise HTTPException(status_code=404, detail="Demand not found")
+    return result
+```
+
+## Error Handling padronizado
+
+```python
+class ErrorResponse(BaseModel):
+    error: str
+    message: str
+    details: list[str] | None = None
+
+@app.exception_handler(DomainException)
+async def domain_exception_handler(request, exc: DomainException):
+    return JSONResponse(
+        status_code=422,
+        content=ErrorResponse(error="domain_error", message=str(exc)).dict()
+    )
+
+@app.exception_handler(NotFoundException)
+async def not_found_handler(request, exc: NotFoundException):
+    return JSONResponse(
+        status_code=404,
+        content=ErrorResponse(error="not_found", message=str(exc)).dict()
+    )
+```
+
+## Paginação
+
+```python
+class PaginatedResponse(BaseModel, Generic[T]):
+    items: list[T]
+    total: int
+    page: int
+    size: int
+    pages: int
+
+    @model_validator(mode="before")
+    def calc_pages(cls, values):
+        values["pages"] = ceil(values["total"] / values["size"])
+        return values
+```
+
+## Versionamento
+
+Usar path-based: `/api/v1/`, `/api/v2/`. Manter v1 funcionando até todos os clientes migrarem.

package/templates/bundle-ai-agents/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.

package/templates/bundle-ai-agents/skills/context-engineering/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: context-engineering
+description: Implementar as 4 estratégias de context engineering (Write, Select, Compress, Isolate) para agentes. Use quando precisar gerenciar a janela de contexto, otimizar o que o agente recebe, ou reduzir custos de tokens.
+---
+
+# Context Engineering
+
+As 4 estratégias conforme Anthropic:
+
+## 1. Write Context — Memória Persistente
+
+O que o agente "sabe" antes de começar.
+
+```
+CLAUDE.md          → Padrões do projeto, arquitetura, decisões
+agents.md          → Comportamento específico do agente
+skills/SKILL.md    → Capacidades on-demand
+memory/            → Aprendizados de execuções anteriores
+```
+
+**Regra:** CLAUDE.md deve ter no máximo 2000 tokens. Se precisar de mais, mover para skills que são carregadas on-demand.
+
+## 2. Select Context — Retrieval Inteligente
+
+Injetar apenas o contexto relevante para a task atual.
+
+```python
+def select_context(task: Task, retriever) -> str:
+    # Buscar skills relevantes para a task
+    relevant_skills = retriever.invoke(task.description)
+
+    # Buscar código relacionado no repo
+    related_code = code_search(task.description, worktree_path)
+
+    # Buscar decisões anteriores similares
+    past_decisions = memory_store.search(task.description, k=3)
+
+    return format_context(relevant_skills, related_code, past_decisions)
+```
+
+**Regra:** Nunca injetar mais de 30% da janela de contexto com contexto selecionado. Deixar espaço para o agente raciocinar.
+
+## 3. Compress Context — Resumo Eficiente
+
+Reduzir informação sem perder o essencial.
+
+```python
+async def compress_code(code: str, max_tokens: int = 2000) -> str:
+    if count_tokens(code) <= max_tokens:
+        return code
+
+    summary = await llm.ainvoke(f"""
+    Resuma este código mantendo:
+    - Assinaturas de funções/classes
+    - Tipos de entrada/saída
+    - Lógica principal (sem detalhes de implementação)
+    - Imports relevantes
+
+    Código:
+    {code}
+    """)
+    return summary.content
+```
+
+**Regra:** Comprimir apenas quando necessário. Código que o agente vai modificar deve estar completo, não comprimido.
+
+## 4. Isolate Context — Escopo por Agente
+
+Cada agente vê apenas o que precisa.
+
+```python
+agent_contexts = {
+    "frontend": {
+        "sees": ["src/features/", "src/shared/", "package.json"],
+        "not_sees": ["src/domain/", "infra/", "alembic/"],
+        "skills": ["react-patterns", "component-design"],
+    },
+    "backend": {
+        "sees": ["src/domain/", "src/application/", "src/api/"],
+        "not_sees": ["src/features/", "node_modules/"],
+        "skills": ["clean-architecture", "ddd-tactical"],
+    }
+}
+```
+
+**Regra:** Agentes nunca compartilham janela de contexto. Comunicação via mensagens estruturadas, não via contexto compartilhado.
+
+## Budget de contexto
+
+Para um modelo com 200k tokens:
+
+| Componente | % | Tokens |
+|---|---|---|
+| System prompt + CLAUDE.md | 5% | 10k |
+| Skills carregadas | 10% | 20k |
+| Código relevante (Select) | 25% | 50k |
+| Histórico de conversa | 15% | 30k |
+| **Espaço para raciocínio** | **45%** | **90k** |

package/templates/bundle-ai-agents/skills/database-modeling/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: database-modeling
+description: Modelar banco de dados PostgreSQL com migrations, índices, e pgvector. Use quando for criar tabelas, definir schema, criar migrations, ou otimizar queries.
+---
+
+# Modelagem de Banco — PostgreSQL
+
+## Convenções
+
+- Nomes de tabelas: `snake_case`, plural (`demands`, `tasks`, `agents`)
+- PKs: `id UUID DEFAULT gen_random_uuid()`
+- FKs: `<tabela_singular>_id` (ex: `demand_id`)
+- Timestamps: `created_at`, `updated_at` com default `NOW()`
+- Soft delete: `deleted_at TIMESTAMP NULL`
+
+## Migration com Alembic
+
+```python
+# alembic/versions/001_create_demands.py
+def upgrade():
+    op.create_table(
+        'demands',
+        sa.Column('id', sa.UUID(), primary_key=True, server_default=sa.text('gen_random_uuid()')),
+        sa.Column('description', sa.Text(), nullable=False),
+        sa.Column('status', sa.VARCHAR(20), nullable=False, server_default='created'),
+        sa.Column('requester', sa.VARCHAR(100), nullable=False),
+        sa.Column('created_at', sa.TIMESTAMP(timezone=True), server_default=sa.text('NOW()')),
+        sa.Column('updated_at', sa.TIMESTAMP(timezone=True), server_default=sa.text('NOW()')),
+    )
+
+def downgrade():
+    op.drop_table('demands')
+```
+
+## Índices
+
+```sql
+-- Queries frequentes devem ter índice
+CREATE INDEX idx_tasks_status ON tasks(status) WHERE status != 'completed';
+CREATE INDEX idx_tasks_demand ON tasks(demand_id);
+CREATE INDEX idx_tracking_events_demand_agent ON tracking_events(demand_id, agent_id, created_at DESC);
+
+-- pgvector para busca semântica
+CREATE INDEX idx_embeddings_vector ON bundle_embeddings
+  USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 200);
+
+-- Full-text search
+ALTER TABLE bundles ADD COLUMN search_vector tsvector
+  GENERATED ALWAYS AS (to_tsvector('portuguese', name || ' ' || description)) STORED;
+CREATE INDEX idx_bundles_search ON bundles USING GIN(search_vector);
+```
+
+## Anti-patterns a evitar
+
+- Não usar CASCADE DELETE sem pensar nas consequências
+- Não criar índice em toda coluna (custo de escrita)
+- Não fazer SELECT * em produção
+- Não ignorar EXPLAIN ANALYZE para queries lentas
+- Não alterar schema sem migration

package/templates/bundle-ai-agents/skills/docker-containerization/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: docker-containerization
+description: Criar Dockerfiles otimizados com multi-stage build, security hardening e docker-compose para desenvolvimento. Use quando for containerizar aplicações, criar Dockerfiles, ou configurar ambiente de dev.
+---
+
+# Docker Containerization
+
+## Dockerfile Python — Multi-stage
+
+```dockerfile
+# === Build stage ===
+FROM python:3.11-slim AS builder
+WORKDIR /app
+RUN apt-get update && apt-get install -y --no-install-recommends gcc && rm -rf /var/lib/apt/lists/*
+COPY requirements.txt .
+RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
+
+# === Runtime stage ===
+FROM python:3.11-slim
+WORKDIR /app
+RUN groupadd -r appuser && useradd -r -g appuser appuser
+COPY --from=builder /install /usr/local
+COPY src/ ./src/
+USER appuser
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=5s CMD curl -f http://localhost:8000/health || exit 1
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+## Dockerfile React — Multi-stage
+
+```dockerfile
+FROM node:20-slim AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM nginx:alpine
+COPY --from=builder /app/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+EXPOSE 80
+```
+
+## Docker Compose — Dev
+
+```yaml
+# docker-compose.dev.yml
+services:
+  api:
+    build:
+      context: .
+      dockerfile: docker/Dockerfile.api
+    ports:
+      - "8000:8000"
+    environment:
+      - DATABASE_URL=postgresql://maestro:maestro@postgres/maestro
+      - REDIS_URL=redis://redis:6379
+    volumes:
+      - ./src:/app/src  # Hot reload
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  postgres:
+    image: pgvector/pgvector:pg16
+    environment:
+      POSTGRES_DB: maestro
+      POSTGRES_USER: maestro
+      POSTGRES_PASSWORD: maestro
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U maestro"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+
+  minio:
+    image: minio/minio
+    command: server /data --console-address ":9001"
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+
+volumes:
+  pgdata:
+```
+
+## .dockerignore
+
+```
+.git
+node_modules
+__pycache__
+*.pyc
+.env
+.venv
+dist
+build
+coverage
+.pytest_cache
+```

package/templates/bundle-ai-agents/skills/eval-testing/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: eval-testing
+description: Criar framework de avaliação para agentes de AI com LLM-as-judge, rule-based evals e golden datasets. Use quando precisar testar agentes, avaliar qualidade de RAG, ou criar benchmarks de compliance.
+---
+
+# Avaliação de Agentes
+
+## Tipos de eval
+
+| Tipo | Quando usar | Velocidade |
+|---|---|---|
+| Rule-based | Validar formato, estrutura, compliance | Rápido |
+| LLM-as-judge | Avaliar qualidade, coerência, utilidade | Lento |
+| Golden dataset | Comparar com respostas esperadas | Médio |
+| RAGAS | Métricas de RAG (faithfulness, relevancy) | Médio |
+
+## 1. Rule-based Evals
+
+```python
+class ComplianceEvaluator:
+    """Verifica se o código segue o bundle"""
+
+    def evaluate(self, code: str, bundle: Bundle) -> EvalResult:
+        checks = []
+        checks.append(self._check_max_lines(code, max=500))
+        checks.append(self._check_no_hardcoded_secrets(code))
+        checks.append(self._check_function_length(code, max=20))
+        checks.append(self._check_naming_convention(code))
+        checks.append(self._check_test_coverage(code, min=80))
+
+        score = sum(c.passed for c in checks) / len(checks)
+        return EvalResult(score=score, checks=checks)
+
+    def _check_max_lines(self, code: str, max: int) -> Check:
+        lines = len(code.split('\n'))
+        return Check(
+            name="max_lines",
+            passed=lines <= max,
+            detail=f"{lines}/{max} linhas"
+        )
+```
+
+## 2. LLM-as-Judge
+
+```python
+JUDGE_PROMPT = """
+Avalie o código abaixo nos critérios:
+1. Clareza (1-5): O código é fácil de entender?
+2. Correção (1-5): O código faz o que deveria?
+3. Padrões (1-5): Segue Clean Architecture e DDD?
+4. Testes (1-5): Os testes são adequados?
+
+Código:
+{code}
+
+Responda em JSON:
+{{"clareza": X, "correcao": X, "padroes": X, "testes": X, "justificativa": "..."}}
+"""
+
+async def llm_judge(code: str) -> dict:
+    response = await llm.ainvoke(JUDGE_PROMPT.format(code=code))
+    return json.loads(response.content)
+```
+
+## 3. Golden Dataset
+
+```json
+{
+  "evals": [
+    {
+      "id": "eval-001",
+      "prompt": "Crie um endpoint GET /api/v1/demands que retorna lista paginada",
+      "expected": {
+        "has_controller": true,
+        "has_use_case": true,
+        "has_repository": true,
+        "has_pagination": true,
+        "follows_clean_arch": true
+      }
+    }
+  ]
+}
+```
+
+## 4. Runner de avaliação
+
+```python
+async def run_evals(agent, eval_set: list[dict]) -> BenchmarkResult:
+    results = []
+    for eval_case in eval_set:
+        output = await agent.ainvoke(eval_case["prompt"])
+
+        rule_score = rule_evaluator.evaluate(output)
+        judge_score = await llm_judge(output)
+
+        results.append({
+            "eval_id": eval_case["id"],
+            "rule_score": rule_score,
+            "judge_score": judge_score,
+            "output": output
+        })
+
+    return BenchmarkResult(results=results, aggregate=aggregate(results))
+```
+
+## No CI/CD
+
+```yaml
+eval:
+  stage: test
+  script:
+    - python -m evals.run_evals --dataset evals/golden_dataset.json
+    - python -m evals.check_threshold --min-score 0.8
+  allow_failure: false
+```

package/templates/bundle-ai-agents/skills/memory-management/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: memory-management
+description: Implementar memória de curto, médio e longo prazo para agentes usando LangGraph Store e checkpointers. Use quando precisar que agentes lembrem de interações anteriores, persistam estado, ou aprendam com execuções passadas.
+---
+
+# Gerenciamento de Memória
+
+## 3 Níveis de Memória
+
+| Nível | Duração | Mecanismo | Exemplo |
+|---|---|---|---|
+| Curto prazo | 1 sessão | Context window | Mensagens da conversa atual |
+| Médio prazo | 1 demanda | Checkpointer | Estado entre nós do grafo |
+| Longo prazo | Permanente | Store | Padrões aprendidos, preferências |
+
+## Curto Prazo — Context Window
+
+Gerenciado automaticamente pelo LangGraph. Usar `add_messages` para acumular.
+
+```python
+class AgentState(TypedDict):
+    messages: Annotated[list, add_messages]  # Acumula automaticamente
+```
+
+## Médio Prazo — Checkpointer
+
+Persiste o estado do grafo entre invocações da mesma demanda.
+
+```python
+from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+
+checkpointer = AsyncPostgresSaver.from_conn_string(DATABASE_URL)
+
+graph = StateGraph(OrchestratorState)
+# ... definir nós e edges ...
+app = graph.compile(checkpointer=checkpointer)
+
+# Usar thread_id consistente por demanda
+config = {"configurable": {"thread_id": f"demand-{demand_id}"}}
+result = await app.ainvoke({"messages": [...]}, config=config)
+
+# Próxima invocação com mesmo thread_id retoma do estado salvo
+result2 = await app.ainvoke({"messages": [nova_msg]}, config=config)
+```
+
+## Longo Prazo — Store
+
+Persiste conhecimento entre demandas diferentes.
+
+```python
+from langgraph.store.postgres import AsyncPostgresStore
+
+store = AsyncPostgresStore.from_conn_string(DATABASE_URL)
+
+# Salvar aprendizado
+await store.aput(
+    namespace=("agent", "backend", "patterns"),
+    key="spring-crud-pattern",
+    value={
+        "pattern": "Usar record para DTO, entity para domínio",
+        "learned_from": "demand-123",
+        "confidence": 0.95,
+        "created_at": "2026-03-27"
+    }
+)
+
+# Buscar aprendizados relevantes
+results = await store.asearch(
+    namespace=("agent", "backend", "patterns"),
+    query="como criar DTO para API REST",
+    limit=5
+)
+```
+
+## Memória no Deep Agent
+
+```python
+from deepagents import create_deep_agent
+from deepagents.backends import FilesystemBackend
+from langgraph.checkpoint.postgres import PostgresSaver
+from langgraph.store.postgres import PostgresStore
+
+agent = create_deep_agent(
+    model="claude-sonnet-4-5-20250929",
+    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
+    checkpointer=PostgresSaver(conn_string=DATABASE_URL),
+    store=PostgresStore(conn_string=DATABASE_URL),
+    system_prompt="Você é um agente backend..."
+)
+```
+
+## Limpeza de memória
+
+Memórias envelhecem. Implementar decay:
+
+```python
+async def cleanup_stale_memories(store, max_age_days: int = 90):
+    """Remove memórias antigas ou com baixa confiança"""
+    cutoff = datetime.now() - timedelta(days=max_age_days)
+    memories = await store.alist(namespace=("agent",))
+    for mem in memories:
+        if mem.value.get("created_at", "") < cutoff.isoformat():
+            await store.adelete(namespace=mem.namespace, key=mem.key)
+        elif mem.value.get("confidence", 1.0) < 0.3:
+            await store.adelete(namespace=mem.namespace, key=mem.key)
+```