maestro-bundle 1.3.1 → 1.4.0

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

@@ -1,19 +1,55 @@
 ---
 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.
+description: Model PostgreSQL databases with migrations, indexes, and pgvector. Use when creating tables, defining schemas, writing migrations, or optimizing queries.
+version: 1.0.0
+author: Maestro
 ---
 
-# Modelagem de Banco — PostgreSQL
+# Database Modeling
 
-## Convenções
+Design PostgreSQL schemas with proper conventions, Alembic migrations, performant indexes, pgvector for semantic search, and full-text search capabilities.
 
-- 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()`
+## When to Use
+- Creating new database tables or modifying existing schemas
+- Writing Alembic migrations
+- Adding indexes to optimize slow queries
+- Setting up pgvector for embedding storage
+- Configuring full-text search
+- Reviewing schema design for anti-patterns
+
+## Available Operations
+1. Design tables following naming conventions
+2. Create Alembic migrations (upgrade and downgrade)
+3. Add indexes for query optimization
+4. Set up pgvector for semantic search
+5. Configure full-text search with tsvector
+6. Analyze and optimize slow queries with EXPLAIN
+
+## Multi-Step Workflow
+
+### Step 1: Design the Table Schema
+
+Follow these naming conventions strictly:
+
+- Table names: `snake_case`, plural (`demands`, `tasks`, `agents`)
+- Primary keys: `id UUID DEFAULT gen_random_uuid()`
+- Foreign keys: `<singular_table>_id` (e.g., `demand_id`)
+- Timestamps: `created_at`, `updated_at` with default `NOW()`
 - Soft delete: `deleted_at TIMESTAMP NULL`
 
-## Migration com Alembic
+### Step 2: Create the Alembic Migration
+
+Generate and write the migration file.
+
+```bash
+# Generate a new migration
+alembic revision --autogenerate -m "create_demands_table"
+
+# Or create manually
+alembic revision -m "create_demands_table"
+```
+
+Write the migration:
 
 ```python
 # alembic/versions/001_create_demands.py
@@ -32,28 +68,119 @@ def downgrade():
     op.drop_table('demands')
 ```
 
-## Índices
+Run the migration:
+
+```bash
+# Apply migration
+alembic upgrade head
+
+# Verify the table was created
+psql $DATABASE_URL -c "\d demands"
+
+# Check migration history
+alembic history
+```
+
+### Step 3: Add Performance Indexes
+
+Index columns used in WHERE clauses, JOINs, and ORDER BY.
 
 ```sql
--- Queries frequentes devem ter índice
+-- Partial index for active records (most queries filter by status)
 CREATE INDEX idx_tasks_status ON tasks(status) WHERE status != 'completed';
+
+-- Foreign key index for JOIN performance
 CREATE INDEX idx_tasks_demand ON tasks(demand_id);
+
+-- Composite index for common query patterns
 CREATE INDEX idx_tracking_events_demand_agent ON tracking_events(demand_id, agent_id, created_at DESC);
+```
 
--- pgvector para busca semântica
+### Step 4: Set Up pgvector for Semantic Search
+
+```bash
+# Enable pgvector extension
+psql $DATABASE_URL -c "CREATE EXTENSION IF NOT EXISTS vector;"
+```
+
+```sql
+-- Create embeddings table
+CREATE TABLE bundle_embeddings (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    content TEXT NOT NULL,
+    embedding vector(1536) NOT NULL,
+    metadata JSONB,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+-- HNSW index for fast cosine similarity search
 CREATE INDEX idx_embeddings_vector ON bundle_embeddings
   USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 200);
+```
+
+### Step 5: Configure Full-Text Search
 
--- Full-text search
+```sql
+-- Add generated tsvector column
 ALTER TABLE bundles ADD COLUMN search_vector tsvector
-  GENERATED ALWAYS AS (to_tsvector('portuguese', name || ' ' || description)) STORED;
+  GENERATED ALWAYS AS (to_tsvector('english', name || ' ' || description)) STORED;
+
+-- GIN index for full-text search
 CREATE INDEX idx_bundles_search ON bundles USING GIN(search_vector);
 ```
 
-## Anti-patterns a evitar
+### Step 6: Analyze and Optimize Queries
+
+```bash
+# Run EXPLAIN ANALYZE on slow queries
+psql $DATABASE_URL -c "EXPLAIN ANALYZE SELECT * FROM tasks WHERE demand_id = 'abc-123' AND status = 'pending';"
+
+# Check for missing indexes
+psql $DATABASE_URL -c "SELECT schemaname, tablename, indexname FROM pg_indexes WHERE tablename = 'tasks';"
+
+# Check table sizes
+psql $DATABASE_URL -c "SELECT pg_size_pretty(pg_total_relation_size('tasks'));"
+```
+
+## Resources
+- `references/naming-conventions.md` - Complete naming conventions for PostgreSQL schemas
+- `references/index-strategies.md` - When and how to create indexes for different query patterns
+
+## Examples
+
+### Example 1: Create a New Feature Table
+User asks: "Create a tasks table with status tracking and assignment to agents."
+Response approach:
+1. Design columns: id (UUID), title, description, status, demand_id (FK), agent_id (FK), timestamps
+2. Write Alembic migration with proper types and defaults
+3. Add foreign key constraints with ON DELETE behavior
+4. Create indexes on demand_id, agent_id, and status
+5. Run migration: `alembic upgrade head`
+6. Verify: `psql $DATABASE_URL -c "\d tasks"`
+
+### Example 2: Optimize a Slow Query
+User asks: "The demands list endpoint is slow when filtering by status."
+Response approach:
+1. Run `EXPLAIN ANALYZE` on the slow query
+2. Check if an index exists on the status column
+3. Create a partial index: `CREATE INDEX idx_demands_status ON demands(status) WHERE deleted_at IS NULL;`
+4. Re-run `EXPLAIN ANALYZE` and compare execution times
+5. Verify the index is being used (look for "Index Scan" in the plan)
+
+### Example 3: Add Soft Delete
+User asks: "Implement soft delete for the demands table."
+Response approach:
+1. Write migration to add `deleted_at TIMESTAMP NULL` column
+2. Update partial indexes to exclude soft-deleted rows: `WHERE deleted_at IS NULL`
+3. Update repository queries to filter `WHERE deleted_at IS NULL` by default
+4. Create a `restore` method that sets `deleted_at = NULL`
+5. Run: `alembic upgrade head`
 
-- 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
+## Notes
+- Never alter schema without a migration -- even in development
+- Always write both `upgrade()` and `downgrade()` functions
+- Do not create indexes on every column (increases write cost)
+- Do not use `SELECT *` in production code -- select only needed columns
+- Always run `EXPLAIN ANALYZE` before and after adding indexes to verify improvement
+- Use `CASCADE DELETE` with extreme caution -- prefer soft delete or application-level cleanup
+- Use `TIMESTAMP WITH TIME ZONE` for all timestamp columns

package/templates/bundle-ai-agents/skills/database-modeling/references/index-strategies.md

@@ -0,0 +1,48 @@
+# Index Strategies Reference
+
+## When to Create Indexes
+
+| Query Pattern | Index Type | Example |
+|---|---|---|
+| `WHERE column = value` | B-tree (default) | `CREATE INDEX idx_tasks_status ON tasks(status)` |
+| `WHERE col1 = X AND col2 = Y` | Composite | `CREATE INDEX idx_tasks_demand_status ON tasks(demand_id, status)` |
+| `WHERE status != 'completed'` | Partial | `CREATE INDEX idx_tasks_active ON tasks(status) WHERE status != 'completed'` |
+| `WHERE deleted_at IS NULL` | Partial | `CREATE INDEX idx_demands_live ON demands(id) WHERE deleted_at IS NULL` |
+| Full-text search | GIN on tsvector | `CREATE INDEX idx_search ON docs USING GIN(search_vector)` |
+| Vector similarity | HNSW | `CREATE INDEX idx_vec ON embeddings USING hnsw(embedding vector_cosine_ops)` |
+| JSONB queries | GIN | `CREATE INDEX idx_meta ON docs USING GIN(metadata)` |
+
+## When NOT to Create Indexes
+
+- Tables with fewer than 1,000 rows (sequential scan is faster)
+- Columns with very low cardinality (e.g., boolean with 50/50 distribution)
+- Columns that are rarely used in WHERE, JOIN, or ORDER BY
+- Write-heavy tables where index maintenance cost exceeds read benefit
+
+## Composite Index Column Order
+
+Put the most selective column first (the one that filters out the most rows).
+
+```sql
+-- Good: demand_id is more selective than status
+CREATE INDEX idx_tasks_demand_status ON tasks(demand_id, status);
+
+-- Bad: status has few distinct values, less selective
+CREATE INDEX idx_tasks_status_demand ON tasks(status, demand_id);
+```
+
+## Monitoring Index Usage
+
+```sql
+-- Find unused indexes
+SELECT indexrelname, idx_scan, idx_tup_read
+FROM pg_stat_user_indexes
+WHERE idx_scan = 0
+ORDER BY pg_relation_size(indexrelid) DESC;
+
+-- Find missing indexes (sequential scans on large tables)
+SELECT relname, seq_scan, idx_scan, n_live_tup
+FROM pg_stat_user_tables
+WHERE seq_scan > idx_scan AND n_live_tup > 10000
+ORDER BY seq_scan - idx_scan DESC;
+```

package/templates/bundle-ai-agents/skills/database-modeling/references/naming-conventions.md

@@ -0,0 +1,27 @@
+# Naming Conventions Reference
+
+## Tables
+- `snake_case`, plural: `demands`, `tasks`, `tracking_events`
+- Junction tables: `<table1>_<table2>` alphabetically: `agents_tasks`
+
+## Columns
+- Primary key: `id` (always UUID with `gen_random_uuid()`)
+- Foreign key: `<singular_table>_id`: `demand_id`, `agent_id`
+- Boolean: `is_<adjective>`: `is_active`, `is_verified`
+- Timestamps: `created_at`, `updated_at`, `deleted_at`
+- Status: `status VARCHAR(20)` with constrained values
+
+## Indexes
+- Format: `idx_<table>_<columns>`: `idx_tasks_status`, `idx_tasks_demand_id`
+- Unique: `uq_<table>_<columns>`: `uq_users_email`
+- Partial: suffix with purpose: `idx_tasks_status_active`
+
+## Constraints
+- Primary key: `pk_<table>`: `pk_demands`
+- Foreign key: `fk_<table>_<referenced>`: `fk_tasks_demands`
+- Unique: `uq_<table>_<columns>`: `uq_users_email`
+- Check: `ck_<table>_<rule>`: `ck_demands_status_valid`
+
+## Migrations
+- Format: `NNN_<action>_<table>.py`: `001_create_demands.py`, `002_add_tasks_status_index.py`
+- Actions: `create`, `add`, `alter`, `drop`, `rename`

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

@@ -1,11 +1,51 @@
 ---
 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.
+description: Create optimized Dockerfiles with multi-stage builds, security hardening, and docker-compose for development. Use when containerizing applications, creating Dockerfiles, or configuring dev environments.
+version: 1.0.0
+author: Maestro
 ---
 
 # Docker Containerization
 
-## Dockerfile Python — Multi-stage
+Build production-ready Docker images with multi-stage builds, non-root users, health checks, and docker-compose configurations for local development.
+
+## When to Use
+- Containerizing a Python (FastAPI/Django) or Node.js (React/Next.js) application
+- Creating or optimizing a Dockerfile
+- Setting up docker-compose for local development
+- Adding health checks, security hardening, or image size optimization
+- Configuring multi-service development environments (API + DB + Redis + MinIO)
+
+## Available Operations
+1. Create multi-stage Dockerfiles for Python applications
+2. Create multi-stage Dockerfiles for React/Node.js applications
+3. Configure docker-compose for development
+4. Add security hardening (non-root user, minimal base image)
+5. Add health checks for container orchestration
+6. Create .dockerignore for build optimization
+
+## Multi-Step Workflow
+
+### Step 1: Create .dockerignore
+
+Always start with .dockerignore to prevent unnecessary files from entering the build context.
+
+```
+.git
+node_modules
+__pycache__
+*.pyc
+.env
+.venv
+dist
+build
+coverage
+.pytest_cache
+```
+
+### Step 2: Create the Dockerfile (Python)
+
+Use multi-stage build for minimal image size.
 
 ```dockerfile
 # === Build stage ===
@@ -27,7 +67,7 @@ HEALTHCHECK --interval=30s --timeout=5s CMD curl -f http://localhost:8000/health
 CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]
 ```
 
-## Dockerfile React — Multi-stage
+### Step 3: Create the Dockerfile (React)
 
 ```dockerfile
 FROM node:20-slim AS builder
@@ -43,7 +83,7 @@ COPY nginx.conf /etc/nginx/conf.d/default.conf
 EXPOSE 80
 ```
 
-## Docker Compose — Dev
+### Step 4: Configure Docker Compose for Development
 
 ```yaml
 # docker-compose.dev.yml
@@ -98,17 +138,86 @@ volumes:
   pgdata:
 ```
 
-## .dockerignore
+### Step 5: Build and Test
+
+```bash
+# Build the image
+docker build -t maestro-api -f docker/Dockerfile.api .
+
+# Check image size
+docker images maestro-api
+
+# Run and test health check
+docker run -d --name test-api -p 8000:8000 maestro-api
+curl -f http://localhost:8000/health
+docker stop test-api && docker rm test-api
 
+# Start the full dev environment
+docker compose -f docker-compose.dev.yml up -d
+
+# Verify all services are healthy
+docker compose -f docker-compose.dev.yml ps
+
+# View logs
+docker compose -f docker-compose.dev.yml logs -f api
 ```
-.git
-node_modules
-__pycache__
-*.pyc
-.env
-.venv
-dist
-build
-coverage
-.pytest_cache
+
+### Step 6: Security Audit
+
+```bash
+# Scan for vulnerabilities
+docker scout cves maestro-api
+
+# Verify non-root user
+docker run --rm maestro-api whoami  # Should output "appuser"
+
+# Check no secrets in the image
+docker history maestro-api --no-trunc | grep -i "secret\|password\|key"
 ```
+
+## Resources
+- `references/dockerfile-checklist.md` - Security and optimization checklist for Dockerfiles
+- `references/compose-patterns.md` - Common docker-compose patterns for dev environments
+
+## Examples
+
+### Example 1: Containerize a FastAPI Application
+User asks: "Containerize our FastAPI backend for production."
+Response approach:
+1. Create .dockerignore to exclude .venv, __pycache__, .env
+2. Write multi-stage Dockerfile: builder installs deps, runtime copies only what's needed
+3. Add non-root user (appuser)
+4. Add HEALTHCHECK on /health endpoint
+5. Build: `docker build -t api -f Dockerfile .`
+6. Test: `docker run -p 8000:8000 api && curl localhost:8000/health`
+7. Check size: `docker images api` (target: < 200MB)
+
+### Example 2: Set Up Local Dev Environment
+User asks: "Set up docker-compose so new developers can run everything locally."
+Response approach:
+1. Create docker-compose.dev.yml with api, postgres (pgvector), redis, minio
+2. Add health checks on postgres so api waits for DB readiness
+3. Mount source code as volume for hot reload
+4. Set environment variables for local database URLs
+5. Start: `docker compose -f docker-compose.dev.yml up -d`
+6. Verify: `docker compose ps` (all services should be "healthy")
+
+### Example 3: Optimize Image Size
+User asks: "Our Docker image is 1.2GB. Make it smaller."
+Response approach:
+1. Switch to multi-stage build if not already using one
+2. Use `python:3.11-slim` instead of `python:3.11`
+3. Use `--no-cache-dir` on pip install
+4. Use `--no-install-recommends` on apt-get
+5. Remove apt cache: `rm -rf /var/lib/apt/lists/*`
+6. Check .dockerignore for missing exclusions
+7. Target: under 200MB for Python, under 50MB for React (nginx)
+
+## Notes
+- Always use multi-stage builds to keep production images small
+- Never run containers as root -- create a dedicated appuser
+- Never put secrets in Dockerfiles or docker-compose files -- use environment variables
+- Always add HEALTHCHECK for production containers
+- Use `docker compose` (v2) not `docker-compose` (v1)
+- Pin base image versions in production (e.g., `python:3.11.7-slim`, not `python:3.11-slim`)
+- Volume mounts for hot reload should only be used in development

package/templates/bundle-ai-agents/skills/docker-containerization/references/compose-patterns.md

@@ -0,0 +1,97 @@
+# Docker Compose Patterns Reference
+
+## Health Check Pattern
+
+Always use health checks so dependent services wait for readiness.
+
+```yaml
+postgres:
+  image: pgvector/pgvector:pg16
+  healthcheck:
+    test: ["CMD-SHELL", "pg_isready -U maestro"]
+    interval: 5s
+    timeout: 5s
+    retries: 5
+
+api:
+  depends_on:
+    postgres:
+      condition: service_healthy
+```
+
+## Hot Reload Pattern
+
+Mount source code for development, but never in production.
+
+```yaml
+api:
+  volumes:
+    - ./src:/app/src          # Source code hot reload
+    - /app/node_modules       # Exclude node_modules from mount
+```
+
+## Environment Variables Pattern
+
+```yaml
+# Development: inline values
+api:
+  environment:
+    - DATABASE_URL=postgresql://maestro:maestro@postgres/maestro
+    - DEBUG=true
+
+# Production: use .env file or secrets
+api:
+  env_file:
+    - .env.production
+```
+
+## Named Volumes for Persistence
+
+```yaml
+volumes:
+  pgdata:      # PostgreSQL data
+  redis-data:  # Redis persistence
+  minio-data:  # MinIO object storage
+
+services:
+  postgres:
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+```
+
+## Multi-Profile Pattern
+
+```yaml
+services:
+  api:
+    profiles: ["dev", "prod"]
+
+  debug-tools:
+    profiles: ["dev"]
+    image: busybox
+
+# Start only dev profile
+# docker compose --profile dev up
+```
+
+## Networking Pattern
+
+```yaml
+services:
+  api:
+    networks:
+      - backend
+
+  postgres:
+    networks:
+      - backend
+
+  frontend:
+    networks:
+      - frontend
+      - backend  # Needs to reach API
+
+networks:
+  frontend:
+  backend:
+```

package/templates/bundle-ai-agents/skills/docker-containerization/references/dockerfile-checklist.md

@@ -0,0 +1,37 @@
+# Dockerfile Checklist Reference
+
+## Security
+
+- [ ] Non-root user created and used (`USER appuser`)
+- [ ] Base image is minimal (`-slim` or `-alpine`)
+- [ ] No secrets or credentials in the Dockerfile
+- [ ] No `sudo` or `setuid` binaries
+- [ ] `COPY` specific files, not `COPY . .` without .dockerignore
+
+## Optimization
+
+- [ ] Multi-stage build (separate builder and runtime stages)
+- [ ] `--no-cache-dir` on pip install
+- [ ] `--no-install-recommends` on apt-get
+- [ ] `rm -rf /var/lib/apt/lists/*` after apt-get
+- [ ] `.dockerignore` excludes .git, node_modules, .env, __pycache__
+- [ ] Dependencies installed before source code (layer caching)
+- [ ] Final image size under 200MB (Python) or 50MB (React/nginx)
+
+## Production Readiness
+
+- [ ] HEALTHCHECK defined
+- [ ] EXPOSE declares the correct port
+- [ ] CMD uses exec form (`["cmd", "arg"]`), not shell form
+- [ ] WORKDIR is set
+- [ ] Labels for metadata (optional): `LABEL maintainer="team"`
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| `COPY . .` before `pip install` | Copy requirements.txt first, then install, then copy source |
+| Running as root | `RUN useradd appuser` + `USER appuser` |
+| Using `latest` tag | Pin version: `python:3.11.7-slim` |
+| Installing dev dependencies | Use `pip install --no-dev` or separate requirements files |
+| Large final image | Use multi-stage build; check with `docker images` |