@cubis/foundry 0.3.11 → 0.3.12

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/supabase-postgres-best-practices/references/_contributing.md

@@ -1,171 +0,0 @@
-# Writing Guidelines for Postgres References
-
-This document provides guidelines for creating effective Postgres best
-practice references that work well with AI agents and LLMs.
-
-## Key Principles
-
-### 1. Concrete Transformation Patterns
-
-Show exact SQL rewrites. Avoid philosophical advice.
-
-**Good:** "Use `WHERE id = ANY(ARRAY[...])` instead of
-`WHERE id IN (SELECT ...)`" **Bad:** "Design good schemas"
-
-### 2. Error-First Structure
-
-Always show the problematic pattern first, then the solution. This trains agents
-to recognize anti-patterns.
-
-```markdown
-**Incorrect (sequential queries):** [bad example]
-
-**Correct (batched query):** [good example]
-```
-
-### 3. Quantified Impact
-
-Include specific metrics. Helps agents prioritize fixes.
-
-**Good:** "10x faster queries", "50% smaller index", "Eliminates N+1" 
-**Bad:** "Faster", "Better", "More efficient"
-
-### 4. Self-Contained Examples
-
-Examples should be complete and runnable (or close to it). Include `CREATE TABLE`
-if context is needed.
-
-```sql
--- Include table definition when needed for clarity
-CREATE TABLE users (
-  id bigint PRIMARY KEY,
-  email text NOT NULL,
-  deleted_at timestamptz
-);
-
--- Now show the index
-CREATE INDEX users_active_email_idx ON users(email) WHERE deleted_at IS NULL;
-```
-
-### 5. Semantic Naming
-
-Use meaningful table/column names. Names carry intent for LLMs.
-
-**Good:** `users`, `email`, `created_at`, `is_active`
-**Bad:** `table1`, `col1`, `field`, `flag`
-
----
-
-## Code Example Standards
-
-### SQL Formatting
-
-```sql
--- Use lowercase keywords, clear formatting
-CREATE INDEX CONCURRENTLY users_email_idx
-  ON users(email)
-  WHERE deleted_at IS NULL;
-
--- Not cramped or ALL CAPS
-CREATE INDEX CONCURRENTLY USERS_EMAIL_IDX ON USERS(EMAIL) WHERE DELETED_AT IS NULL;
-```
-
-### Comments
-
-- Explain _why_, not _what_
-- Highlight performance implications
-- Point out common pitfalls
-
-### Language Tags
-
-- `sql` - Standard SQL queries
-- `plpgsql` - Stored procedures/functions
-- `typescript` - Application code (when needed)
-- `python` - Application code (when needed)
-
----
-
-## When to Include Application Code
-
-**Default: SQL Only**
-
-Most references should focus on pure SQL patterns. This keeps examples portable.
-
-**Include Application Code When:**
-
-- Connection pooling configuration
-- Transaction management in application context
-- ORM anti-patterns (N+1 in Prisma/TypeORM)
-- Prepared statement usage
-
-**Format for Mixed Examples:**
-
-````markdown
-**Incorrect (N+1 in application):**
-
-```typescript
-for (const user of users) {
-  const posts = await db.query("SELECT * FROM posts WHERE user_id = $1", [
-    user.id,
-  ]);
-}
-```
-````
-
-**Correct (batch query):**
-
-```typescript
-const posts = await db.query("SELECT * FROM posts WHERE user_id = ANY($1)", [
-  userIds,
-]);
-```
-
----
-
-## Impact Level Guidelines
-
-| Level | Improvement | Use When |
-|-------|-------------|----------|
-| **CRITICAL** | 10-100x | Missing indexes, connection exhaustion, sequential scans on large tables |
-| **HIGH** | 5-20x | Wrong index types, poor partitioning, missing covering indexes |
-| **MEDIUM-HIGH** | 2-5x | N+1 queries, inefficient pagination, RLS optimization |
-| **MEDIUM** | 1.5-3x | Redundant indexes, query plan instability |
-| **LOW-MEDIUM** | 1.2-2x | VACUUM tuning, configuration tweaks |
-| **LOW** | Incremental | Advanced patterns, edge cases |
-
----
-
-## Reference Standards
-
-**Primary Sources:**
-
-- Official Postgres documentation
-- Supabase documentation
-- Postgres wiki
-- Established blogs (2ndQuadrant, Crunchy Data)
-
-**Format:**
-
-```markdown
-Reference:
-[Postgres Indexes](https://www.postgresql.org/docs/current/indexes.html)
-```
-
----
-
-## Review Checklist
-
-Before submitting a reference:
-
-- [ ] Title is clear and action-oriented
-- [ ] Impact level matches the performance gain
-- [ ] impactDescription includes quantification
-- [ ] Explanation is concise (1-2 sentences)
-- [ ] Has at least 1 **Incorrect** SQL example
-- [ ] Has at least 1 **Correct** SQL example
-- [ ] SQL uses semantic naming
-- [ ] Comments explain _why_, not _what_
-- [ ] Trade-offs mentioned if applicable
-- [ ] Reference links included
-- [ ] `npm run validate` passes
-- [ ] `npm run build` generates correct output

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/supabase-postgres-best-practices/references/_sections.md

@@ -1,39 +0,0 @@
-# Section Definitions
-
-This file defines the rule categories for Postgres best practices. Rules are automatically assigned to sections based on their filename prefix.
-
-Take the examples below as pure demonstrative. Replace each section with the actual rule categories for Postgres best practices.
-
----
-
-## 1. Query Performance (query)
-**Impact:** CRITICAL
-**Description:** Slow queries, missing indexes, inefficient query plans. The most common source of Postgres performance issues.
-
-## 2. Connection Management (conn)
-**Impact:** CRITICAL
-**Description:** Connection pooling, limits, and serverless strategies. Critical for applications with high concurrency or serverless deployments.
-
-## 3. Security & RLS (security)
-**Impact:** CRITICAL
-**Description:** Row-Level Security policies, privilege management, and authentication patterns.
-
-## 4. Schema Design (schema)
-**Impact:** HIGH
-**Description:** Table design, index strategies, partitioning, and data type selection. Foundation for long-term performance.
-
-## 5. Concurrency & Locking (lock)
-**Impact:** MEDIUM-HIGH
-**Description:** Transaction management, isolation levels, deadlock prevention, and lock contention patterns.
-
-## 6. Data Access Patterns (data)
-**Impact:** MEDIUM
-**Description:** N+1 query elimination, batch operations, cursor-based pagination, and efficient data fetching.
-
-## 7. Monitoring & Diagnostics (monitor)
-**Impact:** LOW-MEDIUM
-**Description:** Using pg_stat_statements, EXPLAIN ANALYZE, metrics collection, and performance diagnostics.
-
-## 8. Advanced Features (advanced)
-**Impact:** LOW
-**Description:** Full-text search, JSONB optimization, PostGIS, extensions, and advanced Postgres features.

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/supabase-postgres-best-practices/references/_template.md

@@ -1,34 +0,0 @@
----
-title: Clear, Action-Oriented Title (e.g., "Use Partial Indexes for Filtered Queries")
-impact: MEDIUM
-impactDescription: 5-20x query speedup for filtered queries
-tags: indexes, query-optimization, performance
----
-
-## [Rule Title]
-
-[1-2 sentence explanation of the problem and why it matters. Focus on performance impact.]
-
-**Incorrect (describe the problem):**
-
-```sql
--- Comment explaining what makes this slow/problematic
-CREATE INDEX users_email_idx ON users(email);
-
-SELECT * FROM users WHERE email = 'user@example.com' AND deleted_at IS NULL;
--- This scans deleted records unnecessarily
-```
-
-**Correct (describe the solution):**
-
-```sql
--- Comment explaining why this is better
-CREATE INDEX users_active_email_idx ON users(email) WHERE deleted_at IS NULL;
-
-SELECT * FROM users WHERE email = 'user@example.com' AND deleted_at IS NULL;
--- Only indexes active users, 10x smaller index, faster queries
-```
-
-[Optional: Additional context, edge cases, or trade-offs]
-
-Reference: [Postgres Docs](https://www.postgresql.org/docs/current/)

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/supabase-postgres-best-practices/references/advanced-full-text-search.md

@@ -1,55 +0,0 @@
----
-title: Use tsvector for Full-Text Search
-impact: MEDIUM
-impactDescription: 100x faster than LIKE, with ranking support
-tags: full-text-search, tsvector, gin, search
----
-
-## Use tsvector for Full-Text Search
-
-LIKE with wildcards can't use indexes. Full-text search with tsvector is orders of magnitude faster.
-
-**Incorrect (LIKE pattern matching):**
-
-```sql
--- Cannot use index, scans all rows
-select * from articles where content like '%postgresql%';
-
--- Case-insensitive makes it worse
-select * from articles where lower(content) like '%postgresql%';
-```
-
-**Correct (full-text search with tsvector):**
-
-```sql
--- Add tsvector column and index
-alter table articles add column search_vector tsvector
-  generated always as (to_tsvector('english', coalesce(title,'') || ' ' || coalesce(content,''))) stored;
-
-create index articles_search_idx on articles using gin (search_vector);
-
--- Fast full-text search
-select * from articles
-where search_vector @@ to_tsquery('english', 'postgresql & performance');
-
--- With ranking
-select *, ts_rank(search_vector, query) as rank
-from articles, to_tsquery('english', 'postgresql') query
-where search_vector @@ query
-order by rank desc;
-```
-
-Search multiple terms:
-
-```sql
--- AND: both terms required
-to_tsquery('postgresql & performance')
-
--- OR: either term
-to_tsquery('postgresql | mysql')
-
--- Prefix matching
-to_tsquery('post:*')
-```
-
-Reference: [Full Text Search](https://supabase.com/docs/guides/database/full-text-search)

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/supabase-postgres-best-practices/references/advanced-jsonb-indexing.md

@@ -1,49 +0,0 @@
----
-title: Index JSONB Columns for Efficient Querying
-impact: MEDIUM
-impactDescription: 10-100x faster JSONB queries with proper indexing
-tags: jsonb, gin, indexes, json
----
-
-## Index JSONB Columns for Efficient Querying
-
-JSONB queries without indexes scan the entire table. Use GIN indexes for containment queries.
-
-**Incorrect (no index on JSONB):**
-
-```sql
-create table products (
-  id bigint primary key,
-  attributes jsonb
-);
-
--- Full table scan for every query
-select * from products where attributes @> '{"color": "red"}';
-select * from products where attributes->>'brand' = 'Nike';
-```
-
-**Correct (GIN index for JSONB):**
-
-```sql
--- GIN index for containment operators (@>, ?, ?&, ?|)
-create index products_attrs_gin on products using gin (attributes);
-
--- Now containment queries use the index
-select * from products where attributes @> '{"color": "red"}';
-
--- For specific key lookups, use expression index
-create index products_brand_idx on products ((attributes->>'brand'));
-select * from products where attributes->>'brand' = 'Nike';
-```
-
-Choose the right operator class:
-
-```sql
--- jsonb_ops (default): supports all operators, larger index
-create index idx1 on products using gin (attributes);
-
--- jsonb_path_ops: only @> operator, but 2-3x smaller index
-create index idx2 on products using gin (attributes jsonb_path_ops);
-```
-
-Reference: [JSONB Indexes](https://www.postgresql.org/docs/current/datatype-json.html#JSON-INDEXING)

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/supabase-postgres-best-practices/references/conn-idle-timeout.md

@@ -1,46 +0,0 @@
----
-title: Configure Idle Connection Timeouts
-impact: HIGH
-impactDescription: Reclaim 30-50% of connection slots from idle clients
-tags: connections, timeout, idle, resource-management
----
-
-## Configure Idle Connection Timeouts
-
-Idle connections waste resources. Configure timeouts to automatically reclaim them.
-
-**Incorrect (connections held indefinitely):**
-
-```sql
--- No timeout configured
-show idle_in_transaction_session_timeout;  -- 0 (disabled)
-
--- Connections stay open forever, even when idle
-select pid, state, state_change, query
-from pg_stat_activity
-where state = 'idle in transaction';
--- Shows transactions idle for hours, holding locks
-```
-
-**Correct (automatic cleanup of idle connections):**
-
-```sql
--- Terminate connections idle in transaction after 30 seconds
-alter system set idle_in_transaction_session_timeout = '30s';
-
--- Terminate completely idle connections after 10 minutes
-alter system set idle_session_timeout = '10min';
-
--- Reload configuration
-select pg_reload_conf();
-```
-
-For pooled connections, configure at the pooler level:
-
-```ini
-# pgbouncer.ini
-server_idle_timeout = 60
-client_idle_timeout = 300
-```
-
-Reference: [Connection Timeouts](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-IDLE-IN-TRANSACTION-SESSION-TIMEOUT)

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/supabase-postgres-best-practices/references/conn-limits.md

@@ -1,44 +0,0 @@
----
-title: Set Appropriate Connection Limits
-impact: CRITICAL
-impactDescription: Prevent database crashes and memory exhaustion
-tags: connections, max-connections, limits, stability
----
-
-## Set Appropriate Connection Limits
-
-Too many connections exhaust memory and degrade performance. Set limits based on available resources.
-
-**Incorrect (unlimited or excessive connections):**
-
-```sql
--- Default max_connections = 100, but often increased blindly
-show max_connections;  -- 500 (way too high for 4GB RAM)
-
--- Each connection uses 1-3MB RAM
--- 500 connections * 2MB = 1GB just for connections!
--- Out of memory errors under load
-```
-
-**Correct (calculate based on resources):**
-
-```sql
--- Formula: max_connections = (RAM in MB / 5MB per connection) - reserved
--- For 4GB RAM: (4096 / 5) - 10 = ~800 theoretical max
--- But practically, 100-200 is better for query performance
-
--- Recommended settings for 4GB RAM
-alter system set max_connections = 100;
-
--- Also set work_mem appropriately
--- work_mem * max_connections should not exceed 25% of RAM
-alter system set work_mem = '8MB';  -- 8MB * 100 = 800MB max
-```
-
-Monitor connection usage:
-
-```sql
-select count(*), state from pg_stat_activity group by state;
-```
-
-Reference: [Database Connections](https://supabase.com/docs/guides/platform/performance#connection-management)

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/supabase-postgres-best-practices/references/conn-pooling.md

@@ -1,41 +0,0 @@
----
-title: Use Connection Pooling for All Applications
-impact: CRITICAL
-impactDescription: Handle 10-100x more concurrent users
-tags: connection-pooling, pgbouncer, performance, scalability
----
-
-## Use Connection Pooling for All Applications
-
-Postgres connections are expensive (1-3MB RAM each). Without pooling, applications exhaust connections under load.
-
-**Incorrect (new connection per request):**
-
-```sql
--- Each request creates a new connection
--- Application code: db.connect() per request
--- Result: 500 concurrent users = 500 connections = crashed database
-
--- Check current connections
-select count(*) from pg_stat_activity;  -- 487 connections!
-```
-
-**Correct (connection pooling):**
-
-```sql
--- Use a pooler like PgBouncer between app and database
--- Application connects to pooler, pooler reuses a small pool to Postgres
-
--- Configure pool_size based on: (CPU cores * 2) + spindle_count
--- Example for 4 cores: pool_size = 10
-
--- Result: 500 concurrent users share 10 actual connections
-select count(*) from pg_stat_activity;  -- 10 connections
-```
-
-Pool modes:
-
-- **Transaction mode**: connection returned after each transaction (best for most apps)
-- **Session mode**: connection held for entire session (needed for prepared statements, temp tables)
-
-Reference: [Connection Pooling](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pooler)

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/supabase-postgres-best-practices/references/conn-prepared-statements.md

@@ -1,46 +0,0 @@
----
-title: Use Prepared Statements Correctly with Pooling
-impact: HIGH
-impactDescription: Avoid prepared statement conflicts in pooled environments
-tags: prepared-statements, connection-pooling, transaction-mode
----
-
-## Use Prepared Statements Correctly with Pooling
-
-Prepared statements are tied to individual database connections. In transaction-mode pooling, connections are shared, causing conflicts.
-
-**Incorrect (named prepared statements with transaction pooling):**
-
-```sql
--- Named prepared statement
-prepare get_user as select * from users where id = $1;
-
--- In transaction mode pooling, next request may get different connection
-execute get_user(123);
--- ERROR: prepared statement "get_user" does not exist
-```
-
-**Correct (use unnamed statements or session mode):**
-
-```sql
--- Option 1: Use unnamed prepared statements (most ORMs do this automatically)
--- The query is prepared and executed in a single protocol message
-
--- Option 2: Deallocate after use in transaction mode
-prepare get_user as select * from users where id = $1;
-execute get_user(123);
-deallocate get_user;
-
--- Option 3: Use session mode pooling (port 5432 vs 6543)
--- Connection is held for entire session, prepared statements persist
-```
-
-Check your driver settings:
-
-```sql
--- Many drivers use prepared statements by default
--- Node.js pg: { prepare: false } to disable
--- JDBC: prepareThreshold=0 to disable
-```
-
-Reference: [Prepared Statements with Pooling](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pool-modes)

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/supabase-postgres-best-practices/references/data-batch-inserts.md

@@ -1,54 +0,0 @@
----
-title: Batch INSERT Statements for Bulk Data
-impact: MEDIUM
-impactDescription: 10-50x faster bulk inserts
-tags: batch, insert, bulk, performance, copy
----
-
-## Batch INSERT Statements for Bulk Data
-
-Individual INSERT statements have high overhead. Batch multiple rows in single statements or use COPY.
-
-**Incorrect (individual inserts):**
-
-```sql
--- Each insert is a separate transaction and round trip
-insert into events (user_id, action) values (1, 'click');
-insert into events (user_id, action) values (1, 'view');
-insert into events (user_id, action) values (2, 'click');
--- ... 1000 more individual inserts
-
--- 1000 inserts = 1000 round trips = slow
-```
-
-**Correct (batch insert):**
-
-```sql
--- Multiple rows in single statement
-insert into events (user_id, action) values
-  (1, 'click'),
-  (1, 'view'),
-  (2, 'click'),
-  -- ... up to ~1000 rows per batch
-  (999, 'view');
-
--- One round trip for 1000 rows
-```
-
-For large imports, use COPY:
-
-```sql
--- COPY is fastest for bulk loading
-copy events (user_id, action, created_at)
-from '/path/to/data.csv'
-with (format csv, header true);
-
--- Or from stdin in application
-copy events (user_id, action) from stdin with (format csv);
-1,click
-1,view
-2,click
-\.
-```
-
-Reference: [COPY](https://www.postgresql.org/docs/current/sql-copy.html)

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/supabase-postgres-best-practices/references/data-n-plus-one.md

@@ -1,53 +0,0 @@
----
-title: Eliminate N+1 Queries with Batch Loading
-impact: MEDIUM-HIGH
-impactDescription: 10-100x fewer database round trips
-tags: n-plus-one, batch, performance, queries
----
-
-## Eliminate N+1 Queries with Batch Loading
-
-N+1 queries execute one query per item in a loop. Batch them into a single query using arrays or JOINs.
-
-**Incorrect (N+1 queries):**
-
-```sql
--- First query: get all users
-select id from users where active = true;  -- Returns 100 IDs
-
--- Then N queries, one per user
-select * from orders where user_id = 1;
-select * from orders where user_id = 2;
-select * from orders where user_id = 3;
--- ... 97 more queries!
-
--- Total: 101 round trips to database
-```
-
-**Correct (single batch query):**
-
-```sql
--- Collect IDs and query once with ANY
-select * from orders where user_id = any(array[1, 2, 3, ...]);
-
--- Or use JOIN instead of loop
-select u.id, u.name, o.*
-from users u
-left join orders o on o.user_id = u.id
-where u.active = true;
-
--- Total: 1 round trip
-```
-
-Application pattern:
-
-```sql
--- Instead of looping in application code:
--- for user in users: db.query("SELECT * FROM orders WHERE user_id = $1", user.id)
-
--- Pass array parameter:
-select * from orders where user_id = any($1::bigint[]);
--- Application passes: [1, 2, 3, 4, 5, ...]
-```
-
-Reference: [N+1 Query Problem](https://supabase.com/docs/guides/database/query-optimization)

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/supabase-postgres-best-practices/references/data-pagination.md

@@ -1,50 +0,0 @@
----
-title: Use Cursor-Based Pagination Instead of OFFSET
-impact: MEDIUM-HIGH
-impactDescription: Consistent O(1) performance regardless of page depth
-tags: pagination, cursor, keyset, offset, performance
----
-
-## Use Cursor-Based Pagination Instead of OFFSET
-
-OFFSET-based pagination scans all skipped rows, getting slower on deeper pages. Cursor pagination is O(1).
-
-**Incorrect (OFFSET pagination):**
-
-```sql
--- Page 1: scans 20 rows
-select * from products order by id limit 20 offset 0;
-
--- Page 100: scans 2000 rows to skip 1980
-select * from products order by id limit 20 offset 1980;
-
--- Page 10000: scans 200,000 rows!
-select * from products order by id limit 20 offset 199980;
-```
-
-**Correct (cursor/keyset pagination):**
-
-```sql
--- Page 1: get first 20
-select * from products order by id limit 20;
--- Application stores last_id = 20
-
--- Page 2: start after last ID
-select * from products where id > 20 order by id limit 20;
--- Uses index, always fast regardless of page depth
-
--- Page 10000: same speed as page 1
-select * from products where id > 199980 order by id limit 20;
-```
-
-For multi-column sorting:
-
-```sql
--- Cursor must include all sort columns
-select * from products
-where (created_at, id) > ('2024-01-15 10:00:00', 12345)
-order by created_at, id
-limit 20;
-```
-
-Reference: [Pagination](https://supabase.com/docs/guides/database/pagination)