jorgex-stack 1.0.0 → 1.0.2

package/stack/skills/supabase-postgres-best-practices/references/_contributing.md

@@ -1,170 +1,170 @@
-# 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
-- [ ] `pnpm test` passes
+# 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
+- [ ] `pnpm test` passes

package/stack/skills/supabase-postgres-best-practices/references/_sections.md

@@ -1,39 +1,39 @@
-# 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.
+# 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/stack/skills/supabase-postgres-best-practices/references/_template.md

@@ -1,34 +1,34 @@
----
-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/)
+---
+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/stack/skills/supabase-postgres-best-practices/references/advanced-full-text-search.md

@@ -1,55 +1,55 @@
----
-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)
+---
+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)