maestro-bundle 1.0.0

package/templates/bundle-data-pipeline/AGENTS.md

@@ -0,0 +1,115 @@
+# Projeto: Pipeline de Dados e ML
+
+Você está construindo um pipeline de dados que inclui ingestão, processamento, treinamento de modelos e serving. O projeto usa Python com foco em engenharia de dados e machine learning.
+
+## 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/pandas-patterns.md` — Padrões de transformação com Pandas
+- `references/mlflow-guide.md` — Guia de experiment tracking
+- `references/data-validation.md` — Validação com Pandera/Great Expectations
+
+## Stack do projeto
+
+- **Linguagem:** Python 3.11+
+- **Dados:** Pandas, Polars, NumPy
+- **ML:** Scikit-learn, XGBoost, LightGBM
+- **Deep Learning:** PyTorch (quando necessário)
+- **Pipeline:** Apache Airflow ou Prefect
+- **Experiment Tracking:** MLflow
+- **RAG (se aplicável):** LangChain + pgvector
+- **Banco:** PostgreSQL
+- **Containers:** Docker
+- **Validação:** Pandera, Great Expectations
+
+## Estrutura do projeto
+
+```
+src/
+├── data/
+│   ├── raw/                    # Dados originais (imutáveis, nunca editar)
+│   ├── processed/              # Dados transformados
+│   └── features/               # Feature store
+├── pipelines/
+│   ├── ingestion/              # Ingestão de fontes externas
+│   ├── preprocessing/          # Limpeza e transformação
+│   ├── feature_engineering/    # Criação de features
+│   └── training/               # Pipeline de treino
+├── models/
+│   ├── training/               # Scripts de treino
+│   ├── evaluation/             # Avaliação e métricas
+│   └── serving/                # API de inferência (FastAPI)
+├── rag/                        # Se aplicável
+│   ├── ingest.py
+│   ├── retriever.py
+│   └── embeddings.py
+├── notebooks/                  # APENAS exploração (não vai para prod)
+├── tests/
+│   ├── test_preprocessing.py
+│   ├── test_features.py
+│   └── test_model.py
+└── config/
+    ├── settings.py
+    └── models_config.yaml
+```
+
+## Padrões de código
+
+- Máximo 500 linhas por arquivo, 20 linhas por função
+- Type hints em funções públicas
+- Docstrings em funções de transformação de dados (input/output)
+- Black + Ruff para formatação
+- Notebook → script Python antes de ir para produção
+
+## Padrões de dados
+
+- Dados originais são IMUTÁVEIS — nunca editar `raw/`
+- Cada transformação é uma função pura (input → output, sem side effects)
+- Validar schema na entrada de cada pipeline step (Pandera)
+- Versionamento de datasets com DVC
+- Logging de todas as transformações
+
+## Padrões de ML
+
+- Todo modelo precisa de baseline (majority class, média, regressão linear)
+- Cross-validation k=5 mínimo
+- Métricas documentadas: accuracy, precision, recall, F1, AUC
+- Feature importance registrada no MLflow
+- Modelo serializado com versão
+- A/B testing antes de substituir modelo em produção
+
+## Git
+
+- Commits: `feat(preprocessing): adicionar normalização de salários`
+- Branches: `feature/<pipeline>-<descricao>`
+- Nunca commitar dados (usar .gitignore, DVC para dados)
+- Nunca commitar modelos binários (usar MLflow registry)
+
+## Testes
+
+- Testes de schema (Pandera) para cada transformação
+- Testes unitários para funções de feature engineering
+- Testes de regressão para métricas do modelo
+- Cobertura mínima: 80% em pipelines de transformação
+
+## O que NÃO fazer
+
+- Não colocar notebook em produção sem refatorar
+- Não treinar sem baseline
+- Não ignorar data drift
+- Não usar random seed inconsistente
+- Não hardcodar paths — usar config
+- Não fazer SELECT * em queries de dados grandes

package/templates/bundle-data-pipeline/skills/data-preprocessing/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: data-preprocessing
+description: Preprocessar dados com Pandas e NumPy incluindo limpeza, transformação e análise exploratória. Use quando precisar limpar dados, fazer EDA, ou preparar datasets.
+---
+
+# Data Preprocessing
+
+## EDA (Análise Exploratória)
+
+```python
+import pandas as pd
+import numpy as np
+
+def eda_report(df: pd.DataFrame) -> dict:
+    return {
+        "shape": df.shape,
+        "dtypes": df.dtypes.to_dict(),
+        "nulls": df.isnull().sum().to_dict(),
+        "null_pct": (df.isnull().sum() / len(df) * 100).to_dict(),
+        "duplicates": df.duplicated().sum(),
+        "numeric_stats": df.describe().to_dict(),
+        "categorical_counts": {
+            col: df[col].value_counts().head(10).to_dict()
+            for col in df.select_dtypes(include='object').columns
+        }
+    }
+```
+
+## Pipeline de limpeza
+
+```python
+def clean_pipeline(df: pd.DataFrame) -> pd.DataFrame:
+    df = df.copy()
+
+    # 1. Remover duplicatas
+    df = df.drop_duplicates()
+
+    # 2. Tratar tipos
+    date_cols = [c for c in df.columns if 'date' in c.lower() or 'at' in c.lower()]
+    for col in date_cols:
+        df[col] = pd.to_datetime(df[col], errors='coerce')
+
+    # 3. Tratar nulos numéricos
+    for col in df.select_dtypes(include=[np.number]).columns:
+        if df[col].isnull().sum() / len(df) < 0.05:
+            df[col] = df[col].fillna(df[col].median())
+        else:
+            df = df.drop(columns=[col])  # >5% nulos: remover coluna
+
+    # 4. Tratar nulos categóricos
+    for col in df.select_dtypes(include='object').columns:
+        df[col] = df[col].fillna('unknown')
+
+    # 5. Normalizar strings
+    for col in df.select_dtypes(include='object').columns:
+        df[col] = df[col].str.strip().str.lower()
+
+    return df
+```
+
+## Validação com Pandera
+
+```python
+import pandera as pa
+
+schema = pa.DataFrameSchema({
+    "demand_id": pa.Column(str, nullable=False, unique=True),
+    "description": pa.Column(str, nullable=False),
+    "status": pa.Column(str, pa.Check.isin(["created", "planned", "completed"])),
+    "compliance_score": pa.Column(float, pa.Check.between(0, 100), nullable=True),
+    "created_at": pa.Column("datetime64[ns]", nullable=False),
+})
+
+validated_df = schema.validate(df)
+```

package/templates/bundle-data-pipeline/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-data-pipeline/skills/feature-engineering/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: feature-engineering
+description: Criar e transformar features para modelos de ML incluindo encoding, scaling, e feature selection. Use quando precisar preparar dados, criar features, ou selecionar variáveis relevantes.
+---
+
+# Feature Engineering
+
+## Fluxo
+
+```
+Dados brutos → Limpeza → Encoding → Scaling → Feature Selection → Dados prontos
+```
+
+## Limpeza
+
+```python
+import pandas as pd
+
+def clean_data(df: pd.DataFrame) -> pd.DataFrame:
+    # Remover duplicatas
+    df = df.drop_duplicates()
+
+    # Tratar nulos
+    df['age'] = df['age'].fillna(df['age'].median())
+    df['name'] = df['name'].fillna('Unknown')
+
+    # Remover outliers (IQR)
+    Q1, Q3 = df['salary'].quantile([0.25, 0.75])
+    IQR = Q3 - Q1
+    df = df[(df['salary'] >= Q1 - 1.5*IQR) & (df['salary'] <= Q3 + 1.5*IQR)]
+
+    # Tipagem
+    df['created_at'] = pd.to_datetime(df['created_at'])
+
+    return df
+```
+
+## Encoding
+
+```python
+from sklearn.preprocessing import OneHotEncoder, LabelEncoder, OrdinalEncoder
+
+# Categorias sem ordem → OneHotEncoder
+ohe = OneHotEncoder(sparse_output=False, handle_unknown='ignore')
+encoded = ohe.fit_transform(df[['department', 'city']])
+
+# Categorias com ordem → OrdinalEncoder
+oe = OrdinalEncoder(categories=[['junior', 'pleno', 'senior']])
+df['level_encoded'] = oe.fit_transform(df[['level']])
+
+# Target → LabelEncoder
+le = LabelEncoder()
+y = le.fit_transform(df['target'])
+```
+
+## Feature Selection
+
+```python
+from sklearn.feature_selection import SelectKBest, f_classif, mutual_info_classif
+
+# Filtro estatístico
+selector = SelectKBest(score_func=f_classif, k=10)
+X_selected = selector.fit_transform(X, y)
+
+# Feature importance do modelo
+model.fit(X, y)
+importances = pd.Series(model.feature_importances_, index=feature_names)
+top_features = importances.nlargest(10)
+```
+
+## Regras
+
+1. Nunca usar dados do test set para fit do scaler/encoder
+2. Salvar transformers junto com o modelo (pickle/joblib)
+3. Documentar cada feature criada (nome, tipo, origem)
+4. Verificar correlação entre features (remover redundantes)

package/templates/bundle-data-pipeline/skills/mlops-pipeline/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: mlops-pipeline
+description: Criar pipelines MLOps com MLflow para tracking, model registry e deployment automatizado. Use quando precisar versionar modelos, automatizar treino, ou configurar model registry.
+---
+
+# MLOps Pipeline
+
+## MLflow Tracking
+
+```python
+import mlflow
+
+mlflow.set_tracking_uri("http://mlflow.maestro.local")
+mlflow.set_experiment("compliance-classifier")
+
+with mlflow.start_run(run_name="rf-v1"):
+    mlflow.log_params({
+        "n_estimators": 200,
+        "max_depth": 20,
+        "cv_folds": 5
+    })
+
+    model.fit(X_train, y_train)
+    y_pred = model.predict(X_test)
+
+    mlflow.log_metrics({
+        "accuracy": accuracy_score(y_test, y_pred),
+        "f1": f1_score(y_test, y_pred, average='weighted'),
+        "precision": precision_score(y_test, y_pred, average='weighted'),
+    })
+
+    mlflow.sklearn.log_model(model, "model")
+```
+
+## Model Registry
+
+```python
+# Registrar modelo
+model_uri = f"runs:/{run_id}/model"
+mlflow.register_model(model_uri, "compliance-classifier")
+
+# Promover para produção
+client = mlflow.MlflowClient()
+client.transition_model_version_stage(
+    name="compliance-classifier",
+    version=2,
+    stage="Production"
+)
+```
+
+## Pipeline automatizado
+
+```python
+# pipelines/training.py
+def training_pipeline():
+    """Pipeline completo: dados → treino → avaliação → registro"""
+
+    # 1. Carregar dados
+    df = load_latest_data()
+
+    # 2. Preprocessar
+    X, y = preprocess(df)
+    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
+
+    # 3. Treinar com tracking
+    with mlflow.start_run():
+        model = train_model(X_train, y_train)
+        metrics = evaluate_model(model, X_test, y_test)
+        mlflow.log_metrics(metrics)
+
+        # 4. Registrar se melhor que produção
+        prod_metrics = get_production_metrics()
+        if metrics['f1'] > prod_metrics.get('f1', 0):
+            mlflow.sklearn.log_model(model, "model")
+            register_as_candidate(model)
+            notify_team("Novo modelo candidato disponível")
+```

package/templates/bundle-data-pipeline/skills/model-training/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: model-training
+description: Treinar modelos de ML com Scikit-learn incluindo pipeline de preprocessing, cross-validation e hyperparameter tuning. Use quando for treinar modelos, fazer cross-validation, ou otimizar hiperparâmetros.
+---
+
+# Model Training
+
+## Pipeline completo
+
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler, OneHotEncoder
+from sklearn.compose import ColumnTransformer
+from sklearn.model_selection import cross_val_score, GridSearchCV
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.metrics import classification_report
+import joblib
+
+# 1. Preprocessamento
+numeric_features = ['age', 'salary', 'experience']
+categorical_features = ['department', 'role']
+
+preprocessor = ColumnTransformer(
+    transformers=[
+        ('num', StandardScaler(), numeric_features),
+        ('cat', OneHotEncoder(handle_unknown='ignore'), categorical_features)
+    ]
+)
+
+# 2. Pipeline
+pipeline = Pipeline([
+    ('preprocessor', preprocessor),
+    ('classifier', RandomForestClassifier(random_state=42))
+])
+
+# 3. Cross-validation
+scores = cross_val_score(pipeline, X_train, y_train, cv=5, scoring='f1_weighted')
+print(f"F1 Score: {scores.mean():.3f} (+/- {scores.std():.3f})")
+
+# 4. Hyperparameter tuning
+param_grid = {
+    'classifier__n_estimators': [100, 200, 500],
+    'classifier__max_depth': [10, 20, None],
+    'classifier__min_samples_split': [2, 5, 10]
+}
+
+grid_search = GridSearchCV(pipeline, param_grid, cv=5, scoring='f1_weighted', n_jobs=-1)
+grid_search.fit(X_train, y_train)
+
+# 5. Avaliação final
+y_pred = grid_search.predict(X_test)
+print(classification_report(y_test, y_pred))
+
+# 6. Salvar modelo
+joblib.dump(grid_search.best_estimator_, 'models/model_v1.pkl')
+```
+
+## Sempre comparar com baseline
+
+```python
+from sklearn.dummy import DummyClassifier
+
+baseline = DummyClassifier(strategy='most_frequent')
+baseline.fit(X_train, y_train)
+baseline_score = baseline.score(X_test, y_test)
+print(f"Baseline accuracy: {baseline_score:.3f}")
+print(f"Model accuracy: {grid_search.score(X_test, y_test):.3f}")
+```

package/templates/bundle-data-pipeline/skills/rag-pipeline/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: rag-pipeline
+description: Construir pipeline RAG completo com ingestão, chunking, embedding, indexação e retrieval usando LangChain + pgvector. Use sempre que precisar implementar busca semântica, responder perguntas sobre documentos, ou criar um sistema de retrieval.
+---
+
+# RAG Pipeline
+
+## Pipeline completo
+
+```
+Documentos → Loader → Splitter → Embeddings → pgvector → Retriever → Re-ranker → LLM
+```
+
+## 1. Ingestão
+
+```python
+from langchain_community.document_loaders import DirectoryLoader, UnstructuredMarkdownLoader
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+
+# Loader por tipo de documento
+loader = DirectoryLoader(
+    "./documents/",
+    glob="**/*.md",
+    loader_cls=UnstructuredMarkdownLoader
+)
+docs = loader.load()
+
+# Splitter com separadores Markdown
+splitter = RecursiveCharacterTextSplitter(
+    chunk_size=1000,
+    chunk_overlap=200,
+    separators=["\n## ", "\n### ", "\n\n", "\n", ". ", " "]
+)
+chunks = splitter.split_documents(docs)
+```
+
+## 2. Metadados obrigatórios
+
+Cada chunk deve ter:
+```python
+for chunk in chunks:
+    chunk.metadata.update({
+        "source": chunk.metadata.get("source", "unknown"),
+        "doc_type": classify_document(chunk),  # skill, agent_md, prd, code
+        "language": detect_language(chunk),
+        "created_at": datetime.now().isoformat(),
+    })
+```
+
+## 3. Embedding + Indexação
+
+```python
+from langchain_openai import OpenAIEmbeddings
+from langchain_postgres import PGVector
+
+embeddings = OpenAIEmbeddings(model="text-embedding-3-large", dimensions=1536)
+
+vectorstore = PGVector(
+    collection_name="documents",
+    connection=DATABASE_URL,
+    embedding_function=embeddings,
+)
+vectorstore.add_documents(chunks)
+```
+
+## 4. Retrieval Híbrido
+
+```python
+from langchain.retrievers import EnsembleRetriever
+from langchain_community.retrievers import BM25Retriever
+
+# Semântico
+semantic_retriever = vectorstore.as_retriever(search_kwargs={"k": 20})
+
+# Keyword
+bm25_retriever = BM25Retriever.from_documents(chunks, k=20)
+
+# Ensemble com RRF
+hybrid_retriever = EnsembleRetriever(
+    retrievers=[semantic_retriever, bm25_retriever],
+    weights=[0.6, 0.4]
+)
+```
+
+## 5. Re-ranking
+
+```python
+from langchain.retrievers import ContextualCompressionRetriever
+from langchain_cohere import CohereRerank
+
+reranker = CohereRerank(top_n=5)
+final_retriever = ContextualCompressionRetriever(
+    base_compressor=reranker,
+    base_retriever=hybrid_retriever
+)
+```
+
+## 6. Query Chain
+
+```python
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.output_parsers import StrOutputParser
+
+prompt = ChatPromptTemplate.from_template("""
+Responda a pergunta baseado apenas no contexto fornecido.
+Se a resposta não estiver no contexto, diga "Não encontrei essa informação".
+
+Contexto: {context}
+Pergunta: {question}
+""")
+
+chain = (
+    {"context": final_retriever, "question": RunnablePassthrough()}
+    | prompt
+    | llm
+    | StrOutputParser()
+)
+
+result = chain.invoke("Qual skill usar para criar componentes React?")
+```
+
+## Checklist de qualidade
+
+- [ ] Chunks testados com perguntas reais
+- [ ] Metadados completos em todos os chunks
+- [ ] Retrieval quality medido com golden dataset
+- [ ] Re-ranking ativo para refinar top-k
+- [ ] Fallback para quando retrieval não encontra nada

package/templates/bundle-frontend-spa/.spec/constitution.md

@@ -0,0 +1,32 @@
+# Constitution — Projeto Frontend SPA
+
+## Princípios
+
+1. **Spec primeiro, código depois** — Toda demanda passa pelo fluxo SDD antes de implementação
+2. **Componente = 1 responsabilidade** — Componentes pequenos e focados
+3. **Server state no React Query** — Nunca duplicar dados da API no estado global
+4. **TypeScript strict** — Zero `any`, types para tudo
+5. **Mobile-first** — Escrever para mobile, breakpoints para desktop
+
+## Padrões de desenvolvimento
+
+- React 18+, TypeScript strict mode
+- Tailwind CSS + Shadcn/UI
+- Feature-based folder structure
+- Custom hooks para lógica reutilizável
+- React Hook Form + Zod para formulários
+
+## Padrões de componentes
+
+- Composição sobre configuração
+- Loading/Error/Empty states em todo async
+- Acessibilidade: semantic HTML, aria-labels
+- Lazy loading por rota
+- Máximo 200 linhas por componente
+
+## Padrões de qualidade
+
+- Vitest + Testing Library para componentes
+- Playwright para E2E
+- Cobertura mínima: 70%
+- Commits seguem Conventional Commits