maestro-bundle 1.3.1 → 1.4.0

package/templates/bundle-base/skills/code-review/SKILL.md

@@ -1,54 +1,139 @@
 ---
 name: code-review
-description: Revisar código seguindo os padrões da organização. Use quando for revisar um PR, avaliar qualidade de código, ou quando o desenvolvedor pedir review.
+description: Review code following organization standards for quality, security, and patterns. Use when reviewing a PR, evaluating code quality, or when a developer asks for a review.
+version: 1.0.0
+author: Maestro
 ---
 
-# Code Review — Padrões da organização
+# Code Review
 
-## Checklist de Review
+Perform structured code reviews following the organization's quality, security, and pattern standards.
 
-### 1. Correção
-- O código faz o que a task/spec pede?
-- Os edge cases estão cobertos?
-- Os fluxos de exceção estão tratados?
+## When to Use
+- When asked to review a pull request or merge request
+- When evaluating code quality of a file or module
+- When a developer asks for feedback on their code
+- Before approving a merge
 
-### 2. Qualidade
-- Arquivos com mais de 500 linhas? Dividir.
-- Funções com mais de 20 linhas? Extrair.
-- Ifs aninhados (hadouken)? Usar early return.
-- Nomes descritivos? (`calculateComplianceScore` > `calc`)
-- Código duplicado? Extrair se repetir 3+ vezes.
-- Código morto? Remover.
+## Available Operations
+1. Full PR review with categorized feedback
+2. Focused review (security-only, quality-only, tests-only)
+3. Quick review of a single file
+4. Compliance check against organization patterns
 
-### 3. Segurança
-- Inputs validados nas fronteiras?
-- Secrets hardcoded? REJEITAR.
-- SQL injection possível? Usar parameterized queries.
-- Rate limiting presente nas APIs?
+## Multi-Step Workflow
 
-### 4. Testes
-- Testes unitários para regras de negócio?
-- Nomes de testes descritivos?
-- Testes cobrem caminho feliz E fluxos alternativos?
+### Step 1: Gather Context
+Read the changed files and understand the purpose of the changes.
 
-### 5. Padrões
-- Commit segue Conventional Commits?
-- Branch segue nomenclatura?
-- Estrutura de diretórios por domínio?
-- Linguagem ubíqua do projeto respeitada?
+```bash
+# If reviewing a PR/MR
+git diff main...HEAD --stat
+git diff main...HEAD
+git log main...HEAD --oneline
 
-## Formato do Feedback
+# If reviewing specific files
+git diff --cached
+```
+
+### Step 2: Run Automated Checks
+Execute linters, tests, and static analysis before manual review.
+
+```bash
+# Backend (Java/Spring)
+./mvnw checkstyle:check
+./mvnw test
+
+# Frontend (Angular)
+npm run lint
+npm run test
+```
+
+### Step 3: Apply Review Checklist
+
+**Correctness:**
+- Does the code do what the task/spec requires?
+- Are edge cases covered?
+- Are exception flows handled?
+
+**Quality:**
+- Files with more than 500 lines? Split them.
+- Functions with more than 20 lines? Extract.
+- Nested ifs (hadouken)? Use early return.
+- Descriptive names? (`calculateComplianceScore` > `calc`)
+- Duplicated code? Extract if repeated 3+ times.
+- Dead code? Remove it.
+
+**Security:**
+- Inputs validated at boundaries?
+- Hardcoded secrets? REJECT.
+- SQL injection possible? Use parameterized queries.
+- Rate limiting present on APIs?
 
-Categorizar cada comentário:
+**Tests:**
+- Unit tests for business rules?
+- Descriptive test names?
+- Tests cover happy path AND alternative flows?
 
-- **[BLOCKER]** — Deve ser corrigido antes do merge
-- **[SUGGESTION]** — Melhoria recomendada, não obrigatória
-- **[QUESTION]** — Dúvida sobre a intenção do código
-- **[PRAISE]** — Algo bem feito que vale destacar
+**Patterns:**
+- Commit follows Conventional Commits?
+- Branch follows naming convention?
+- Directory structure by domain?
+- Project ubiquitous language respected?
 
-Exemplo:
+### Step 4: Categorize and Deliver Feedback
+
+Use these categories for each comment:
+
+- **[BLOCKER]** -- Must be fixed before merge
+- **[SUGGESTION]** -- Recommended improvement, not mandatory
+- **[QUESTION]** -- Question about code intent
+- **[PRAISE]** -- Something well done worth highlighting
+
+Format:
 ```
-[BLOCKER] linha 45: API key hardcoded. Mover para variável de ambiente.
-[SUGGESTION] linha 120: Esse if aninhado ficaria mais legível com early return.
-[PRAISE] Boa extração do value object ComplianceScore.
+[BLOCKER] line 45: API key hardcoded. Move to environment variable.
+[SUGGESTION] line 120: This nested if would be more readable with early return.
+[PRAISE] Good extraction of the ComplianceScore value object.
 ```
+
+### Step 5: Provide Summary
+End the review with an overall assessment:
+- APPROVE: Ready to merge
+- REQUEST CHANGES: Has blockers that must be fixed
+- COMMENT: Has suggestions but no blockers
+
+## Resources
+- `references/review-checklist.md` - Complete review checklist with detailed criteria
+
+## Examples
+### Example 1: Full PR Review
+User asks: "Review this PR"
+Response approach:
+1. Run `git diff main...HEAD` to see all changes
+2. Read each changed file
+3. Apply the checklist to each file
+4. Deliver categorized feedback with line references
+5. Provide overall assessment (APPROVE / REQUEST CHANGES / COMMENT)
+
+### Example 2: Security-Focused Review
+User asks: "Check this code for security issues"
+Response approach:
+1. Read the target files
+2. Check for hardcoded secrets, SQL injection, missing input validation
+3. Verify CORS, CSRF, rate limiting configuration
+4. Report findings with severity
+
+### Example 3: Quick File Review
+User asks: "Is this service class well-structured?"
+Response approach:
+1. Read the file
+2. Check method length, naming, separation of concerns
+3. Verify dependency injection patterns
+4. Provide focused feedback
+
+## Notes
+- Always read the full file context before commenting -- do not review snippets in isolation
+- Be specific with line numbers and concrete suggestions
+- Balance criticism with praise -- highlight what was done well
+- For security issues, always mark as [BLOCKER]

package/templates/bundle-base/skills/code-review/references/review-checklist.md

@@ -0,0 +1,45 @@
+# Code Review Checklist
+
+## Correctness
+- [ ] Code implements the task/spec requirements
+- [ ] Edge cases are handled
+- [ ] Exception flows are treated properly
+- [ ] No off-by-one errors
+- [ ] Null/undefined values are handled
+
+## Quality
+- [ ] Files under 500 lines
+- [ ] Functions under 20 lines
+- [ ] No nested ifs (use early return)
+- [ ] Descriptive variable and function names
+- [ ] No duplicated code (DRY: extract if repeated 3+ times)
+- [ ] No dead code or commented-out code
+- [ ] Single Responsibility Principle followed
+
+## Security
+- [ ] Inputs validated at boundaries (controllers, API endpoints)
+- [ ] No hardcoded secrets, API keys, or passwords
+- [ ] Parameterized queries used (no SQL injection risk)
+- [ ] Rate limiting on public endpoints
+- [ ] CORS properly configured (not `*` in production)
+- [ ] Authentication/authorization enforced on protected endpoints
+
+## Tests
+- [ ] Unit tests for business rules
+- [ ] Descriptive test names (`test_should_X_when_Y`)
+- [ ] Happy path covered
+- [ ] Error/alternative flows covered
+- [ ] No test interdependencies
+
+## Patterns
+- [ ] Commits follow Conventional Commits
+- [ ] Branch follows naming convention
+- [ ] Directory structure follows domain organization
+- [ ] Ubiquitous language respected
+- [ ] DTOs at API boundary, entities in domain
+
+## Feedback Categories
+- **[BLOCKER]** -- Must fix before merge
+- **[SUGGESTION]** -- Recommended, not mandatory
+- **[QUESTION]** -- Clarification needed
+- **[PRAISE]** -- Well done, worth highlighting

package/templates/bundle-base/skills/commit-pattern/SKILL.md

@@ -1,58 +1,117 @@
 ---
 name: commit-pattern
-description: Gerar mensagens de commit seguindo o padrão Conventional Commits da organização. Use sempre que for fazer um commit, commitar mudanças, ou precisar de uma mensagem de commit.
+description: Generate commit messages following Conventional Commits standard. Use when committing changes, creating commit messages, staging files, or finishing a task.
+version: 1.0.0
+author: Maestro
 ---
 
-# Padrão de Commit Maestro
+# Commit Pattern
 
-## Formato
+Generate structured commit messages following Conventional Commits and the organization's standards.
 
-```
-<tipo>(<escopo>): <descrição imperativa em português>
+## When to Use
+- When committing code changes
+- When asked to generate a commit message
+- When finishing a task and need to commit the result
+- When reviewing commit messages for compliance
+
+## Available Operations
+1. Generate a commit message from staged changes
+2. Validate an existing commit message
+3. Create a multi-line commit with body and footer
+4. Stage and commit changes in one workflow
+
+## Multi-Step Workflow
+
+### Step 1: Review Staged Changes
+Inspect what has been changed to determine the appropriate commit type and scope.
+
+```bash
+git status
+git diff --cached --stat
+git diff --cached
 ```
 
-## Tipos
+### Step 2: Determine Commit Type
 
-| Tipo | Quando usar |
+| Type | When to use |
 |---|---|
-| `feat` | Nova funcionalidade para o usuário |
-| `fix` | Correção de bug |
-| `refactor` | Mudança de código que não altera comportamento |
-| `docs` | Mudanças apenas em documentação |
-| `test` | Adição ou correção de testes |
-| `chore` | Build, deps, configs, tarefas de manutenção |
-| `ci` | Mudanças em CI/CD (pipelines, workflows) |
-| `perf` | Melhoria de performance |
-
-## Regras
-
-1. Descrição no imperativo: "adicionar", não "adicionado" ou "adicionando"
-2. Primeira letra minúscula
-3. Sem ponto final
-4. Máximo 72 caracteres na primeira linha
-5. Escopo é o módulo/feature afetada
-6. Se a mudança quebra compatibilidade, adicionar `BREAKING CHANGE:` no corpo
-
-## Exemplos
+| `feat` | New user-facing functionality |
+| `fix` | Bug fix |
+| `refactor` | Code change that does not alter behavior |
+| `docs` | Documentation-only changes |
+| `test` | Adding or fixing tests |
+| `chore` | Build, deps, configs, maintenance tasks |
+| `ci` | CI/CD changes (pipelines, workflows) |
+| `perf` | Performance improvement |
 
+### Step 3: Compose the Message
+Follow the format:
 ```
-feat(demands): adicionar decomposição automática de tasks
-fix(agents): corrigir timeout na execução de skill
-refactor(bundles): extrair validação para value object
-test(tracking): adicionar testes para eventos MCP
-docs(readme): atualizar instruções de instalação
-chore(deps): atualizar langchain para 0.3.x
-ci(gitlab): adicionar stage de compliance check
+<type>(<scope>): <imperative description in Portuguese>
 ```
 
-## Corpo (opcional)
+Rules:
+1. Imperative mood: "adicionar", not "adicionado" or "adicionando"
+2. First letter lowercase
+3. No period at the end
+4. Maximum 72 characters on the first line
+5. Scope is the affected module/feature
+6. If the change breaks compatibility, add `BREAKING CHANGE:` in the body
 
-Para mudanças complexas, adicionar corpo explicando o **porquê**:
+### Step 4: Commit
 
-```
-refactor(orchestrator): simplificar alocação de agentes
+```bash
+# Simple commit
+git commit -m "feat(demands): adicionar decomposicao automatica de tasks"
+
+# Commit with body for complex changes
+git commit -m "refactor(orchestrator): simplificar alocacao de agentes
 
-A alocação anterior usava um loop O(n²) comparando todos os agentes
+A alocacao anterior usava um loop O(n^2) comparando todos os agentes
 com todas as tasks. Agora usa um mapa indexado por tipo de agente,
-reduzindo para O(n).
+reduzindo para O(n)."
+```
+
+### Step 5: Verify
+```bash
+git log --oneline -1
 ```
+
+## Resources
+- `references/conventional-commits.md` - Full Conventional Commits specification and examples
+
+## Examples
+### Example 1: New Feature
+User asks: "Commit these changes that add automatic task decomposition"
+Response approach:
+1. Run `git diff --cached --stat` to see changed files
+2. Identify scope from file paths (e.g., `demands/`)
+3. Generate: `feat(demands): adicionar decomposicao automatica de tasks`
+4. Run `git commit -m "..."` with the message
+
+### Example 2: Bug Fix with Context
+User asks: "Commit the timeout fix"
+Response approach:
+1. Run `git diff --cached` to understand the fix
+2. Generate: `fix(agents): corrigir timeout na execucao de skill`
+3. If the fix is complex, add a body explaining why it happened
+
+### Example 3: Breaking Change
+User asks: "Commit these API changes that break backward compatibility"
+Response approach:
+1. Review changes to confirm breaking nature
+2. Generate message with BREAKING CHANGE footer:
+```
+feat(api): alterar formato de resposta do endpoint de demands
+
+BREAKING CHANGE: o campo 'tasks' agora retorna objetos completos
+ao inves de apenas IDs. Clientes que dependem do formato antigo
+precisam atualizar.
+```
+
+## Notes
+- Always check `git diff --cached` before composing the message to ensure accuracy
+- When in doubt about scope, use the top-level directory name of the changed files
+- For commits touching multiple scopes, use the most significant one or omit the scope
+- Never commit secrets, credentials, or `.env` files

package/templates/bundle-base/skills/commit-pattern/references/conventional-commits.md

@@ -0,0 +1,40 @@
+# Conventional Commits Reference
+
+## Format
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## Types
+| Type | Description | Example |
+|---|---|---|
+| `feat` | New feature | `feat(demands): adicionar decomposicao automatica de tasks` |
+| `fix` | Bug fix | `fix(agents): corrigir timeout na execucao de skill` |
+| `refactor` | Code restructuring | `refactor(bundles): extrair validacao para value object` |
+| `docs` | Documentation | `docs(readme): atualizar instrucoes de instalacao` |
+| `test` | Tests | `test(tracking): adicionar testes para eventos MCP` |
+| `chore` | Maintenance | `chore(deps): atualizar langchain para 0.3.x` |
+| `ci` | CI/CD | `ci(gitlab): adicionar stage de compliance check` |
+| `perf` | Performance | `perf(queries): otimizar consulta de demands ativas` |
+
+## Rules
+1. Imperative mood in Portuguese: "adicionar" not "adicionado"
+2. First letter lowercase
+3. No period at end
+4. Max 72 characters on first line
+5. Scope = affected module/feature
+6. Breaking changes: add `BREAKING CHANGE:` in footer
+
+## Body Guidelines
+- Explain **why**, not what (the diff shows what)
+- Wrap at 72 characters
+- Separate from subject with blank line
+
+## Footer Guidelines
+- `BREAKING CHANGE: <description>` for incompatible changes
+- `Refs: #123` for issue references
+- `Co-authored-by: Name <email>` for pair programming

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

@@ -1,22 +1,60 @@
 ---
 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.
+description: Preprocess data with Pandas and NumPy including cleaning, transformation, and exploratory analysis. Use when you need to clean data, run EDA, validate schemas, or prepare datasets for ML pipelines.
+version: 1.0.0
+author: Maestro
 ---
 
 # Data Preprocessing
 
-## EDA (Análise Exploratória)
+Build data cleaning and preparation pipelines using Pandas, NumPy, and Pandera.
 
+## When to Use
+- User needs to clean a raw CSV/Parquet/JSON dataset
+- User asks for exploratory data analysis (EDA)
+- User needs to handle missing values, duplicates, or type conversions
+- User wants to validate data against a schema
+- User needs to prepare data before feature engineering or model training
+
+## Available Operations
+1. Run exploratory data analysis (EDA) on a dataset
+2. Build a cleaning pipeline (dedup, nulls, types, normalization)
+3. Validate data with Pandera schemas
+4. Profile data quality and generate reports
+5. Export cleaned data to Parquet/CSV
+
+## Multi-Step Workflow
+
+### Step 1: Install Dependencies
+```bash
+pip install pandas numpy pandera pyarrow openpyxl
+```
+
+### Step 2: Load and Inspect Data
 ```python
 import pandas as pd
 import numpy as np
 
+# Load data (adjust path/format as needed)
+df = pd.read_csv("data/raw/dataset.csv")
+# or: df = pd.read_parquet("data/raw/dataset.parquet")
+# or: df = pd.read_json("data/raw/dataset.json")
+
+# Quick inspection
+print(f"Shape: {df.shape}")
+print(f"Columns: {list(df.columns)}")
+print(df.dtypes)
+print(df.head())
+```
+
+### Step 3: Run Exploratory Data Analysis
+```python
 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(),
+        "null_pct": (df.isnull().sum() / len(df) * 100).round(2).to_dict(),
         "duplicates": df.duplicated().sum(),
         "numeric_stats": df.describe().to_dict(),
         "categorical_counts": {
@@ -24,52 +62,105 @@ def eda_report(df: pd.DataFrame) -> dict:
             for col in df.select_dtypes(include='object').columns
         }
     }
-```
 
-## Pipeline de limpeza
+report = eda_report(df)
+for key, value in report.items():
+    print(f"\n--- {key} ---")
+    print(value)
+```
 
+### Step 4: Build and Run Cleaning Pipeline
 ```python
 def clean_pipeline(df: pd.DataFrame) -> pd.DataFrame:
     df = df.copy()
 
-    # 1. Remover duplicatas
+    # 1. Remove duplicates
+    before = len(df)
     df = df.drop_duplicates()
+    print(f"Removed {before - len(df)} duplicate rows")
 
-    # 2. Tratar tipos
-    date_cols = [c for c in df.columns if 'date' in c.lower() or 'at' in c.lower()]
+    # 2. Fix date columns
+    date_cols = [c for c in df.columns if 'date' in c.lower() or c.endswith('_at')]
     for col in date_cols:
         df[col] = pd.to_datetime(df[col], errors='coerce')
 
-    # 3. Tratar nulos numéricos
+    # 3. Handle numeric nulls
     for col in df.select_dtypes(include=[np.number]).columns:
-        if df[col].isnull().sum() / len(df) < 0.05:
+        null_pct = df[col].isnull().sum() / len(df)
+        if null_pct < 0.05:
             df[col] = df[col].fillna(df[col].median())
-        else:
-            df = df.drop(columns=[col])  # >5% nulos: remover coluna
+        elif null_pct > 0.5:
+            print(f"Dropping column '{col}' ({null_pct:.0%} nulls)")
+            df = df.drop(columns=[col])
 
-    # 4. Tratar nulos categóricos
+    # 4. Handle categorical nulls
     for col in df.select_dtypes(include='object').columns:
         df[col] = df[col].fillna('unknown')
 
-    # 5. Normalizar strings
+    # 5. Normalize strings
     for col in df.select_dtypes(include='object').columns:
         df[col] = df[col].str.strip().str.lower()
 
     return df
-```
 
-## Validação com Pandera
+df_clean = clean_pipeline(df)
+```
 
+### Step 5: Validate with Pandera
 ```python
 import pandera as pa
 
 schema = pa.DataFrameSchema({
-    "demand_id": pa.Column(str, nullable=False, unique=True),
+    "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),
+    "score": pa.Column(float, pa.Check.between(0, 100), nullable=True),
     "created_at": pa.Column("datetime64[ns]", nullable=False),
 })
 
-validated_df = schema.validate(df)
+validated_df = schema.validate(df_clean)
+print("Validation passed!")
+```
+
+### Step 6: Export Cleaned Data
+```bash
+mkdir -p data/processed
 ```
+```python
+df_clean.to_parquet("data/processed/dataset_clean.parquet", index=False)
+# or: df_clean.to_csv("data/processed/dataset_clean.csv", index=False)
+print(f"Exported {len(df_clean)} rows to data/processed/")
+```
+
+### Step 7: Verify Output
+```bash
+python -c "import pandas as pd; df = pd.read_parquet('data/processed/dataset_clean.parquet'); print(f'Rows: {len(df)}, Cols: {len(df.columns)}'); print(df.dtypes)"
+```
+
+## Resources
+- `references/pandas-cheatsheet.md` - Common Pandas operations and patterns
+- `references/pandera-schemas.md` - Schema validation examples
+
+## Examples
+### Example 1: Clean a CSV for Analysis
+User asks: "Clean this sales data CSV and remove duplicates"
+Response approach:
+1. Load CSV with `pd.read_csv()`
+2. Run `eda_report()` to understand the data
+3. Apply `clean_pipeline()` to remove duplicates and handle nulls
+4. Export cleaned data to Parquet
+5. Print before/after comparison of row counts and null percentages
+
+### Example 2: Validate Data Before Training
+User asks: "Make sure this dataset matches our expected schema before training"
+Response approach:
+1. Load dataset and inspect dtypes
+2. Define Pandera schema matching expected columns and constraints
+3. Run `schema.validate(df)` and fix any failures
+4. Export validated dataset
+
+## Notes
+- Always run EDA before cleaning to understand data distribution
+- Use Parquet over CSV for production pipelines (better types, compression)
+- Log the number of rows removed at each cleaning step
+- Never modify the original data file -- write to a separate output path

package/templates/bundle-data-pipeline/skills/data-preprocessing/references/pandas-cheatsheet.md

@@ -0,0 +1,63 @@
+# Pandas Cheatsheet
+
+## Loading Data
+```python
+pd.read_csv("file.csv")
+pd.read_parquet("file.parquet")
+pd.read_json("file.json")
+pd.read_excel("file.xlsx", sheet_name="Sheet1")
+pd.read_sql("SELECT * FROM table", connection)
+```
+
+## Inspection
+```python
+df.shape              # (rows, cols)
+df.dtypes             # column types
+df.info()             # memory usage + types
+df.describe()         # numeric statistics
+df.head(10)           # first 10 rows
+df.sample(5)          # random 5 rows
+df.nunique()          # unique values per column
+df.isnull().sum()     # null counts per column
+df.duplicated().sum() # total duplicate rows
+```
+
+## Filtering
+```python
+df[df['col'] > 10]
+df[df['col'].isin(['a', 'b'])]
+df.query("col > 10 and status == 'active'")
+df[df['col'].between(5, 15)]
+df[df['col'].str.contains('pattern', na=False)]
+```
+
+## Transformations
+```python
+df['col'] = df['col'].astype(int)
+df['date'] = pd.to_datetime(df['date'])
+df['col'] = df['col'].str.strip().str.lower()
+df['new'] = df['a'] + df['b']
+df['binned'] = pd.cut(df['value'], bins=5)
+```
+
+## Aggregations
+```python
+df.groupby('category')['value'].mean()
+df.groupby('category').agg({'value': ['mean', 'std', 'count']})
+df.pivot_table(values='value', index='category', columns='type', aggfunc='mean')
+```
+
+## Handling Nulls
+```python
+df.dropna(subset=['critical_col'])
+df['col'].fillna(df['col'].median())
+df['col'].fillna(method='ffill')
+df.interpolate()
+```
+
+## Export
+```python
+df.to_csv("output.csv", index=False)
+df.to_parquet("output.parquet", index=False)
+df.to_json("output.json", orient="records")
+```