@cubis/foundry 0.3.11 → 0.3.12

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/copilot/skills/sql-pro/SKILL.md

@@ -1,86 +0,0 @@
----
-name: sql-pro
-description: "Use for database-agnostic SQL query design and optimization (CTEs, window functions, joins, execution plans) across multiple SQL dialects."
-license: MIT
-metadata:
-  author: https://github.com/Jeffallan
-  version: "1.0.0"
-  domain: language
-  triggers: SQL optimization, query performance, database design, PostgreSQL, MySQL, SQL Server, window functions, CTEs, query tuning, EXPLAIN plan, database indexing
-  role: specialist
-  scope: implementation
-  output-format: code
-  related-skills: devops-engineer
----
-
-# SQL Pro
-
-Senior SQL developer with mastery across major database systems, specializing in complex query design, performance optimization, and database architecture.
-
-## Role Definition
-
-You are a senior SQL developer with 10+ years of experience across PostgreSQL, MySQL, SQL Server, and Oracle. You specialize in complex query optimization, advanced SQL patterns (CTEs, window functions, recursive queries), indexing strategies, and performance tuning. You build efficient, scalable database solutions with sub-100ms query targets.
-
-## When to Use This Skill
-
-- Optimizing slow queries and execution plans
-- Designing complex queries with CTEs, window functions, recursive patterns
-- Creating and optimizing database indexes
-- Implementing data warehousing and ETL patterns
-- Migrating queries between database platforms
-- Analyzing and tuning database performance
-
-## Core Workflow
-
-1. **Schema Analysis** - Review database structure, indexes, query patterns, performance bottlenecks
-2. **Design** - Create set-based operations using CTEs, window functions, appropriate joins
-3. **Optimize** - Analyze execution plans, implement covering indexes, eliminate table scans
-4. **Verify** - Test with production data volume, ensure linear scalability, confirm sub-100ms targets
-5. **Document** - Provide query explanations, index rationale, performance metrics
-
-## Reference Guide
-
-Load detailed guidance based on context:
-
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Query Patterns | `references/query-patterns.md` | JOINs, CTEs, subqueries, recursive queries |
-| Window Functions | `references/window-functions.md` | ROW_NUMBER, RANK, LAG/LEAD, analytics |
-| Optimization | `references/optimization.md` | EXPLAIN plans, indexes, statistics, tuning |
-| Database Design | `references/database-design.md` | Normalization, keys, constraints, schemas |
-| Dialect Differences | `references/dialect-differences.md` | PostgreSQL vs MySQL vs SQL Server specifics |
-
-## Constraints
-
-### MUST DO
-- Analyze execution plans before optimization
-- Use set-based operations over row-by-row processing
-- Apply filtering early in query execution
-- Use EXISTS over COUNT for existence checks
-- Handle NULLs explicitly
-- Create covering indexes for frequent queries
-- Test with production-scale data volumes
-- Document query intent and performance targets
-
-### MUST NOT DO
-- Use SELECT * in production queries
-- Create queries without analyzing execution plans
-- Ignore index usage and table scans
-- Use cursors when set-based operations work
-- Skip NULL handling in comparisons
-- Implement solutions without considering data volume
-- Ignore platform-specific optimizations
-- Leave queries undocumented
-
-## Output Templates
-
-When implementing SQL solutions, provide:
-1. Optimized query with inline comments
-2. Required indexes with rationale
-3. Execution plan analysis
-4. Performance metrics (before/after)
-5. Platform-specific notes if applicable
-
-## Knowledge Reference
-
-CTEs, window functions, recursive queries, EXPLAIN/ANALYZE, covering indexes, query hints, partitioning, materialized views, OLAP patterns, star schema, slowly changing dimensions, isolation levels, deadlock prevention, temporal tables, JSONB operations

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/copilot/skills/sql-pro/references/database-design.md

@@ -1,402 +0,0 @@
-# Database Design
-
-## Normalization Levels
-
-```sql
--- 1NF: Atomic values, no repeating groups
--- Bad: Non-atomic phone column
-CREATE TABLE customers_bad (
-    customer_id INT PRIMARY KEY,
-    name VARCHAR(100),
-    phones VARCHAR(500)  -- "555-1234,555-5678,555-9012"
-);
-
--- Good: Atomic values
-CREATE TABLE customers (
-    customer_id SERIAL PRIMARY KEY,
-    name VARCHAR(100) NOT NULL
-);
-
-CREATE TABLE customer_phones (
-    phone_id SERIAL PRIMARY KEY,
-    customer_id INT NOT NULL REFERENCES customers(customer_id),
-    phone_number VARCHAR(20) NOT NULL,
-    phone_type VARCHAR(20) CHECK (phone_type IN ('mobile', 'home', 'work'))
-);
-
--- 2NF: No partial dependencies (all non-key attributes depend on entire key)
--- Bad: Partial dependency on composite key
-CREATE TABLE order_items_bad (
-    order_id INT,
-    product_id INT,
-    product_name VARCHAR(100),  -- Depends only on product_id
-    product_price DECIMAL(10,2),  -- Depends only on product_id
-    quantity INT,
-    PRIMARY KEY (order_id, product_id)
-);
-
--- Good: Separate product attributes
-CREATE TABLE products (
-    product_id SERIAL PRIMARY KEY,
-    product_name VARCHAR(100) NOT NULL,
-    product_price DECIMAL(10,2) NOT NULL CHECK (product_price >= 0)
-);
-
-CREATE TABLE order_items (
-    order_id INT,
-    product_id INT,
-    quantity INT NOT NULL CHECK (quantity > 0),
-    unit_price DECIMAL(10,2) NOT NULL,  -- Snapshot at order time
-    PRIMARY KEY (order_id, product_id),
-    FOREIGN KEY (order_id) REFERENCES orders(order_id),
-    FOREIGN KEY (product_id) REFERENCES products(product_id)
-);
-
--- 3NF: No transitive dependencies
--- Bad: City/State depends on ZIP
-CREATE TABLE addresses_bad (
-    address_id INT PRIMARY KEY,
-    street VARCHAR(200),
-    city VARCHAR(100),
-    state VARCHAR(2),
-    zip_code VARCHAR(10)
-);
-
--- Good: Separate ZIP code reference
-CREATE TABLE zip_codes (
-    zip_code VARCHAR(10) PRIMARY KEY,
-    city VARCHAR(100) NOT NULL,
-    state VARCHAR(2) NOT NULL,
-    county VARCHAR(100)
-);
-
-CREATE TABLE addresses (
-    address_id SERIAL PRIMARY KEY,
-    street VARCHAR(200) NOT NULL,
-    zip_code VARCHAR(10) NOT NULL REFERENCES zip_codes(zip_code)
-);
-```
-
-## Primary and Foreign Keys
-
-```sql
--- Natural vs Surrogate keys
--- Natural key (business meaning)
-CREATE TABLE countries (
-    country_code CHAR(2) PRIMARY KEY,  -- ISO 3166-1 alpha-2
-    country_name VARCHAR(100) NOT NULL
-);
-
--- Surrogate key (technical, no business meaning)
-CREATE TABLE customers (
-    customer_id SERIAL PRIMARY KEY,  -- Auto-incrementing surrogate
-    email VARCHAR(255) NOT NULL UNIQUE,  -- Natural candidate key
-    name VARCHAR(100) NOT NULL,
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-);
-
--- Composite primary key
-CREATE TABLE student_courses (
-    student_id INT,
-    course_id INT,
-    enrollment_date DATE NOT NULL,
-    grade CHAR(2),
-    PRIMARY KEY (student_id, course_id),
-    FOREIGN KEY (student_id) REFERENCES students(student_id),
-    FOREIGN KEY (course_id) REFERENCES courses(course_id)
-);
-
--- UUID primary keys (distributed systems, no sequence conflicts)
-CREATE TABLE events (
-    event_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    event_type VARCHAR(50) NOT NULL,
-    event_data JSONB,
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-);
-
--- Foreign key with cascading actions
-CREATE TABLE orders (
-    order_id SERIAL PRIMARY KEY,
-    customer_id INT NOT NULL,
-    order_date DATE DEFAULT CURRENT_DATE,
-    FOREIGN KEY (customer_id) REFERENCES customers(customer_id)
-        ON DELETE CASCADE  -- Delete orders when customer deleted
-        ON UPDATE CASCADE  -- Update order.customer_id when customers.customer_id changes
-);
-
-CREATE TABLE order_items (
-    order_item_id SERIAL PRIMARY KEY,
-    order_id INT NOT NULL,
-    product_id INT NOT NULL,
-    quantity INT NOT NULL,
-    FOREIGN KEY (order_id) REFERENCES orders(order_id)
-        ON DELETE CASCADE,  -- Delete items when order deleted
-    FOREIGN KEY (product_id) REFERENCES products(product_id)
-        ON DELETE RESTRICT  -- Prevent deleting product if used in orders
-);
-```
-
-## Constraints and Validation
-
-```sql
--- CHECK constraints
-CREATE TABLE employees (
-    employee_id SERIAL PRIMARY KEY,
-    first_name VARCHAR(50) NOT NULL,
-    last_name VARCHAR(50) NOT NULL,
-    email VARCHAR(255) NOT NULL UNIQUE,
-    salary DECIMAL(12,2) NOT NULL,
-    hire_date DATE NOT NULL,
-    birth_date DATE NOT NULL,
-
-    CONSTRAINT chk_salary_positive CHECK (salary > 0),
-    CONSTRAINT chk_email_format CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z]{2,}$'),
-    CONSTRAINT chk_hire_after_birth CHECK (hire_date > birth_date + INTERVAL '16 years'),
-    CONSTRAINT chk_hire_not_future CHECK (hire_date <= CURRENT_DATE)
-);
-
--- Unique constraints (including composite)
-CREATE TABLE user_preferences (
-    user_id INT NOT NULL,
-    preference_key VARCHAR(50) NOT NULL,
-    preference_value TEXT,
-
-    CONSTRAINT uq_user_preference UNIQUE (user_id, preference_key)
-);
-
--- NOT NULL constraints with defaults
-CREATE TABLE products (
-    product_id SERIAL PRIMARY KEY,
-    name VARCHAR(200) NOT NULL,
-    description TEXT,
-    price DECIMAL(10,2) NOT NULL DEFAULT 0.00,
-    is_active BOOLEAN NOT NULL DEFAULT true,
-    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
-
--- Exclusion constraints (PostgreSQL - prevent overlapping ranges)
-CREATE TABLE room_bookings (
-    booking_id SERIAL PRIMARY KEY,
-    room_id INT NOT NULL,
-    booked_during TSTZRANGE NOT NULL,
-
-    EXCLUDE USING GIST (
-        room_id WITH =,
-        booked_during WITH &&
-    )  -- Prevent overlapping bookings for same room
-);
-```
-
-## Indexing Strategy
-
-```sql
--- Index foreign keys (critical for JOIN performance)
-CREATE INDEX idx_orders_customer_id ON orders(customer_id);
-CREATE INDEX idx_order_items_order_id ON order_items(order_id);
-CREATE INDEX idx_order_items_product_id ON order_items(product_id);
-
--- Composite index for common queries
-CREATE INDEX idx_orders_customer_date ON orders(customer_id, order_date DESC);
--- Supports:
--- WHERE customer_id = ? AND order_date > ?
--- WHERE customer_id = ? ORDER BY order_date DESC
-
--- Partial index for common filters
-CREATE INDEX idx_active_products ON products(category, price)
-WHERE is_active = true AND deleted_at IS NULL;
-
--- Unique index for business rules
-CREATE UNIQUE INDEX idx_users_active_email ON users(LOWER(email))
-WHERE deleted_at IS NULL;
--- Ensures no duplicate emails among active users
-```
-
-## Common Design Patterns
-
-```sql
--- Polymorphic associations (flexible but harder to enforce integrity)
-CREATE TABLE comments (
-    comment_id SERIAL PRIMARY KEY,
-    commentable_type VARCHAR(50) NOT NULL,  -- 'Post', 'Photo', 'Video'
-    commentable_id INT NOT NULL,
-    content TEXT NOT NULL,
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-
-    -- Cannot enforce FK without triggers/application logic
-    CHECK (commentable_type IN ('Post', 'Photo', 'Video'))
-);
-
--- Better: Separate tables with proper FKs
-CREATE TABLE post_comments (
-    comment_id SERIAL PRIMARY KEY,
-    post_id INT NOT NULL REFERENCES posts(post_id),
-    content TEXT NOT NULL,
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE TABLE photo_comments (
-    comment_id SERIAL PRIMARY KEY,
-    photo_id INT NOT NULL REFERENCES photos(photo_id),
-    content TEXT NOT NULL,
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-);
-
--- Many-to-many with attributes (junction/bridge table)
-CREATE TABLE students (
-    student_id SERIAL PRIMARY KEY,
-    name VARCHAR(100) NOT NULL
-);
-
-CREATE TABLE courses (
-    course_id SERIAL PRIMARY KEY,
-    course_name VARCHAR(100) NOT NULL
-);
-
-CREATE TABLE enrollments (
-    enrollment_id SERIAL PRIMARY KEY,
-    student_id INT NOT NULL REFERENCES students(student_id),
-    course_id INT NOT NULL REFERENCES courses(course_id),
-    enrollment_date DATE NOT NULL DEFAULT CURRENT_DATE,
-    grade CHAR(2),
-    status VARCHAR(20) DEFAULT 'active',
-
-    UNIQUE (student_id, course_id),
-    CHECK (status IN ('active', 'completed', 'dropped'))
-);
-
--- Self-referencing hierarchy
-CREATE TABLE categories (
-    category_id SERIAL PRIMARY KEY,
-    category_name VARCHAR(100) NOT NULL,
-    parent_category_id INT REFERENCES categories(category_id),
-    level INT NOT NULL DEFAULT 0,
-
-    CHECK (category_id != parent_category_id)  -- Prevent self-reference
-);
-
--- Adjacency list example
-INSERT INTO categories VALUES
-    (1, 'Electronics', NULL, 0),
-    (2, 'Computers', 1, 1),
-    (3, 'Laptops', 2, 2),
-    (4, 'Desktops', 2, 2);
-```
-
-## Temporal/Historical Data
-
-```sql
--- Slowly Changing Dimension Type 2 (SCD2) - Full history
-CREATE TABLE customer_history (
-    customer_history_id SERIAL PRIMARY KEY,
-    customer_id INT NOT NULL,
-    name VARCHAR(100) NOT NULL,
-    email VARCHAR(255) NOT NULL,
-    address TEXT,
-    valid_from TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    valid_to TIMESTAMP,
-    is_current BOOLEAN NOT NULL DEFAULT true,
-
-    CHECK (valid_to IS NULL OR valid_to > valid_from)
-);
-
--- Ensure only one current record per customer
-CREATE UNIQUE INDEX idx_customer_current ON customer_history(customer_id)
-WHERE is_current = true;
-
--- Temporal tables (PostgreSQL system-versioning)
-CREATE TABLE products (
-    product_id SERIAL PRIMARY KEY,
-    name VARCHAR(200) NOT NULL,
-    price DECIMAL(10,2) NOT NULL,
-    sys_period TSTZRANGE NOT NULL DEFAULT tstzrange(CURRENT_TIMESTAMP, NULL)
-);
-
-CREATE TABLE products_history (LIKE products);
-
-CREATE TRIGGER versioning_trigger
-BEFORE INSERT OR UPDATE OR DELETE ON products
-FOR EACH ROW EXECUTE FUNCTION versioning('sys_period', 'products_history', true);
-```
-
-## Soft Deletes
-
-```sql
--- Soft delete pattern
-CREATE TABLE posts (
-    post_id SERIAL PRIMARY KEY,
-    title VARCHAR(255) NOT NULL,
-    content TEXT NOT NULL,
-    author_id INT NOT NULL REFERENCES users(user_id),
-    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-    deleted_at TIMESTAMP,  -- NULL = active, non-NULL = deleted
-    deleted_by INT REFERENCES users(user_id)
-);
-
--- Index for filtering active records
-CREATE INDEX idx_posts_active ON posts(created_at DESC)
-WHERE deleted_at IS NULL;
-
--- View for active posts only
-CREATE VIEW active_posts AS
-SELECT post_id, title, content, author_id, created_at, updated_at
-FROM posts
-WHERE deleted_at IS NULL;
-```
-
-## Audit Trails
-
-```sql
--- Audit table pattern
-CREATE TABLE audit_log (
-    audit_id BIGSERIAL PRIMARY KEY,
-    table_name VARCHAR(100) NOT NULL,
-    record_id BIGINT NOT NULL,
-    action VARCHAR(10) NOT NULL CHECK (action IN ('INSERT', 'UPDATE', 'DELETE')),
-    old_values JSONB,
-    new_values JSONB,
-    changed_by INT REFERENCES users(user_id),
-    changed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE INDEX idx_audit_table_record ON audit_log(table_name, record_id);
-CREATE INDEX idx_audit_timestamp ON audit_log(changed_at DESC);
-
--- Trigger function for automatic auditing
-CREATE OR REPLACE FUNCTION audit_trigger_func()
-RETURNS TRIGGER AS $$
-BEGIN
-    IF (TG_OP = 'DELETE') THEN
-        INSERT INTO audit_log (table_name, record_id, action, old_values)
-        VALUES (TG_TABLE_NAME, OLD.product_id, 'DELETE', row_to_json(OLD));
-        RETURN OLD;
-    ELSIF (TG_OP = 'UPDATE') THEN
-        INSERT INTO audit_log (table_name, record_id, action, old_values, new_values)
-        VALUES (TG_TABLE_NAME, NEW.product_id, 'UPDATE', row_to_json(OLD), row_to_json(NEW));
-        RETURN NEW;
-    ELSIF (TG_OP = 'INSERT') THEN
-        INSERT INTO audit_log (table_name, record_id, action, new_values)
-        VALUES (TG_TABLE_NAME, NEW.product_id, 'INSERT', row_to_json(NEW));
-        RETURN NEW;
-    END IF;
-END;
-$$ LANGUAGE plpgsql;
-
-CREATE TRIGGER products_audit
-AFTER INSERT OR UPDATE OR DELETE ON products
-FOR EACH ROW EXECUTE FUNCTION audit_trigger_func();
-```
-
-## Schema Design Best Practices
-
-1. **Choose appropriate data types**: Use smallest type that fits (INT vs BIGINT, VARCHAR(50) vs TEXT)
-2. **Index foreign keys**: Always index FK columns for JOIN performance
-3. **Avoid NULLs when possible**: Use NOT NULL with defaults
-4. **Use constraints**: Enforce data integrity at database level
-5. **Normalize to 3NF**: Then denormalize strategically for performance
-6. **Consider soft deletes**: For auditing and data recovery
-7. **Plan for growth**: Use BIGINT for high-volume PKs
-8. **Document schema**: Comment tables and complex constraints
-9. **Version control**: Track schema changes with migrations
-10. **Test with realistic data**: Validate design with production-scale data