omgkit 2.3.0 → 2.3.1

package/README.md

@@ -7,7 +7,7 @@
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 > **AI Team System for Claude Code**
-> 23 Agents • 54 Commands • 43 Skills • 9 Modes
+> 23 Agents • 58 Commands • 76 Skills • 9 Modes
 > *"Think Omega. Build Omega. Be Omega."*
 
 OMGKIT transforms Claude Code into an autonomous AI development team with sprint management, specialized agents, and Omega-level thinking for 10x-1000x productivity improvements.
@@ -17,8 +17,8 @@ OMGKIT transforms Claude Code into an autonomous AI development team with sprint
 | Component | Count | Description |
 |-----------|-------|-------------|
 | **Agents** | 23 | Specialized AI team members |
-| **Commands** | 54 | Slash commands for every task |
-| **Skills** | 43 | Domain expertise modules |
+| **Commands** | 58 | Slash commands for every task |
+| **Skills** | 76 | Domain expertise modules |
 | **Modes** | 9 | Behavioral configurations |
 | **Sprint Management** | ✅ | Vision, backlog, team autonomy |
 | **Omega Thinking** | ✅ | 7 modes for 10x-1000x solutions |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omgkit",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Omega-Level Development Kit - AI Team System for Claude Code. 23 agents, 54 commands, 72 skills, sprint management.",
   "keywords": [
     "claude-code",

package/plugin/skills/databases/database-management/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: managing-databases
+description: AI agent performs database administration tasks including backup/restore, monitoring, replication, security hardening, and maintenance operations. Use when managing production databases, troubleshooting performance, or implementing high availability.
+category: databases
+triggers:
+  - DBA
+  - database management
+  - backup
+  - restore
+  - replication
+  - database monitoring
+  - VACUUM
+  - maintenance
+---
+
+# Managing Databases
+
+## Purpose
+
+Operate and maintain production databases with reliability and performance:
+
+- Implement backup and disaster recovery strategies
+- Configure monitoring and alerting
+- Manage replication and high availability
+- Perform routine maintenance operations
+- Troubleshoot performance issues
+
+## Quick Start
+
+```bash
+# PostgreSQL backup
+pg_dump -Fc -d mydb > backup_$(date +%Y%m%d).dump
+
+# Restore
+pg_restore -d mydb backup_20241230.dump
+
+# Check database health
+psql -c "SELECT pg_database_size('mydb');"
+psql -c "SELECT * FROM pg_stat_activity;"
+```
+
+## Features
+
+| Feature | Description | Tools/Commands |
+|---------|-------------|----------------|
+| Backup/Restore | Point-in-time recovery, full/incremental | pg_dump, pg_basebackup, WAL archiving |
+| Monitoring | Connections, queries, locks, replication | pg_stat_*, Prometheus, Grafana |
+| Replication | Master-replica, synchronous/async | streaming replication, logical replication |
+| Security | Users, roles, encryption, audit | pg_hba.conf, SSL, pgaudit |
+| Maintenance | VACUUM, ANALYZE, reindex | autovacuum tuning, pg_repack |
+| Connection Pooling | Reduce connection overhead | PgBouncer, pgpool-II |
+
+## Common Patterns
+
+### Backup Strategies
+
+```bash
+# Full backup with compression
+pg_dump -Fc -Z9 -d production > backup_$(date +%Y%m%d_%H%M%S).dump
+
+# Parallel backup for large databases
+pg_dump -Fc -j 4 -d production > backup.dump
+
+# Base backup for PITR (Point-in-Time Recovery)
+pg_basebackup -D /backups/base -Fp -Xs -P -R
+
+# Continuous WAL archiving (postgresql.conf)
+archive_mode = on
+archive_command = 'cp %p /archive/%f'
+
+# Restore to specific point in time
+recovery_target_time = '2024-12-30 14:30:00'
+```
+
+```sql
+-- Verify backup integrity
+SELECT pg_is_in_recovery();
+SELECT pg_last_wal_receive_lsn(), pg_last_wal_replay_lsn();
+```
+
+### Monitoring Queries
+
+```sql
+-- Active connections and queries
+SELECT pid, usename, application_name, state, query,
+       now() - query_start AS duration
+FROM pg_stat_activity
+WHERE state != 'idle'
+ORDER BY duration DESC;
+
+-- Table sizes and bloat
+SELECT schemaname, tablename,
+       pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS total_size,
+       pg_size_pretty(pg_relation_size(schemaname||'.'||tablename)) AS table_size,
+       pg_size_pretty(pg_indexes_size(schemaname||'.'||tablename)) AS index_size
+FROM pg_tables
+WHERE schemaname = 'public'
+ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;
+
+-- Slow queries (requires pg_stat_statements)
+SELECT query, calls, mean_exec_time, total_exec_time
+FROM pg_stat_statements
+ORDER BY mean_exec_time DESC
+LIMIT 20;
+
+-- Index usage
+SELECT schemaname, tablename, indexname, idx_scan, idx_tup_read
+FROM pg_stat_user_indexes
+ORDER BY idx_scan ASC;  -- Unused indexes at top
+
+-- Lock monitoring
+SELECT blocked_locks.pid AS blocked_pid,
+       blocking_locks.pid AS blocking_pid,
+       blocked_activity.query AS blocked_query
+FROM pg_locks blocked_locks
+JOIN pg_stat_activity blocked_activity ON blocked_activity.pid = blocked_locks.pid
+JOIN pg_locks blocking_locks ON blocking_locks.locktype = blocked_locks.locktype
+JOIN pg_stat_activity blocking_activity ON blocking_activity.pid = blocking_locks.pid
+WHERE NOT blocked_locks.granted;
+```
+
+### Replication Setup
+
+```sql
+-- On primary: Create replication user
+CREATE USER replicator WITH REPLICATION ENCRYPTED PASSWORD 'secret';
+
+-- pg_hba.conf on primary
+host replication replicator replica_ip/32 scram-sha-256
+```
+
+```bash
+# On replica: Initialize from primary
+pg_basebackup -h primary_host -U replicator -D /var/lib/postgresql/data -Fp -Xs -P -R
+
+# Verify replication status (on primary)
+SELECT client_addr, state, sent_lsn, write_lsn, flush_lsn, replay_lsn
+FROM pg_stat_replication;
+
+# Check replication lag (on replica)
+SELECT now() - pg_last_xact_replay_timestamp() AS replication_lag;
+```
+
+### Connection Pooling (PgBouncer)
+
+```ini
+# pgbouncer.ini
+[databases]
+mydb = host=localhost port=5432 dbname=mydb
+
+[pgbouncer]
+listen_addr = 0.0.0.0
+listen_port = 6432
+auth_type = scram-sha-256
+auth_file = /etc/pgbouncer/userlist.txt
+pool_mode = transaction  # transaction, session, statement
+max_client_conn = 1000
+default_pool_size = 25
+min_pool_size = 5
+reserve_pool_size = 5
+```
+
+### Maintenance Operations
+
+```sql
+-- Manual VACUUM and ANALYZE
+VACUUM ANALYZE orders;
+
+-- Aggressive vacuum for bloat
+VACUUM FULL orders;  -- Locks table, use pg_repack instead
+
+-- Reindex without locking (PostgreSQL 12+)
+REINDEX INDEX CONCURRENTLY idx_orders_status;
+
+-- Tune autovacuum per table (high-churn tables)
+ALTER TABLE orders SET (
+  autovacuum_vacuum_scale_factor = 0.01,
+  autovacuum_analyze_scale_factor = 0.005
+);
+
+-- Check autovacuum status
+SELECT schemaname, relname, last_vacuum, last_autovacuum,
+       last_analyze, last_autoanalyze, n_dead_tup
+FROM pg_stat_user_tables
+ORDER BY n_dead_tup DESC;
+```
+
+```bash
+# pg_repack: Online VACUUM FULL alternative
+pg_repack -d mydb -t orders
+```
+
+### Security Hardening
+
+```sql
+-- Create role with minimal privileges
+CREATE ROLE app_user WITH LOGIN PASSWORD 'secure_password';
+GRANT CONNECT ON DATABASE mydb TO app_user;
+GRANT USAGE ON SCHEMA public TO app_user;
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO app_user;
+
+-- Read-only user for reporting
+CREATE ROLE readonly WITH LOGIN PASSWORD 'secure_password';
+GRANT CONNECT ON DATABASE mydb TO readonly;
+GRANT USAGE ON SCHEMA public TO readonly;
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly;
+
+-- Revoke public access
+REVOKE ALL ON DATABASE mydb FROM PUBLIC;
+REVOKE ALL ON SCHEMA public FROM PUBLIC;
+```
+
+```bash
+# pg_hba.conf - Secure access rules
+# TYPE  DATABASE  USER       ADDRESS         METHOD
+local   all       postgres                   peer
+host    mydb      app_user   10.0.0.0/8      scram-sha-256
+hostssl mydb      app_user   0.0.0.0/0       scram-sha-256
+```
+
+## Use Cases
+
+- Setting up production database infrastructure
+- Troubleshooting slow queries and locks
+- Implementing disaster recovery plans
+- Scaling with read replicas
+- Security audits and compliance
+
+## Best Practices
+
+| Do | Avoid |
+|----|-------|
+| Test restore procedures regularly | Assuming backups work without testing |
+| Use connection pooling in production | Direct connections from all app instances |
+| Enable pg_stat_statements for query analysis | Waiting for problems to investigate queries |
+| Set up replication before you need it | Single point of failure in production |
+| Use CONCURRENTLY for index operations | Blocking operations during peak hours |
+| Create least-privilege database users | Using superuser for applications |
+| Monitor replication lag actively | Discovering lag during failover |
+| Document and automate runbooks | Manual, ad-hoc maintenance |
+
+## Daily Health Check
+
+```sql
+-- Run this checklist daily
+-- 1. Database size and growth
+SELECT pg_size_pretty(pg_database_size('mydb'));
+
+-- 2. Connection count
+SELECT count(*) FROM pg_stat_activity;
+
+-- 3. Long-running queries (>5 min)
+SELECT * FROM pg_stat_activity
+WHERE state != 'idle' AND query_start < now() - interval '5 minutes';
+
+-- 4. Replication lag
+SELECT now() - pg_last_xact_replay_timestamp() AS lag;
+
+-- 5. Bloat check (dead tuples)
+SELECT relname, n_dead_tup FROM pg_stat_user_tables
+WHERE n_dead_tup > 10000 ORDER BY n_dead_tup DESC;
+
+-- 6. Failed/pending transactions
+SELECT * FROM pg_prepared_xacts;
+```
+
+## Emergency Procedures
+
+```sql
+-- Kill long-running query
+SELECT pg_terminate_backend(pid) FROM pg_stat_activity
+WHERE query_start < now() - interval '30 minutes' AND state != 'idle';
+
+-- Cancel query without killing connection
+SELECT pg_cancel_backend(pid);
+
+-- Emergency: Kill all connections to database
+SELECT pg_terminate_backend(pid) FROM pg_stat_activity
+WHERE datname = 'mydb' AND pid != pg_backend_pid();
+```
+
+## Related Skills
+
+See also these related skill documents:
+
+- **optimizing-databases** - Query and index optimization
+- **managing-database-migrations** - Safe schema changes
+- **designing-database-schemas** - Schema architecture

package/plugin/skills/databases/database-migration/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: managing-database-migrations
+description: AI agent implements safe database migrations with zero-downtime strategies, rollback plans, and expand-contract patterns. Use when creating migrations, deploying schema changes, or implementing zero-downtime database updates.
+category: databases
+triggers:
+  - migration
+  - schema change
+  - database migration
+  - zero downtime
+  - rollback
+  - prisma migrate
+  - flyway
+---
+
+# Managing Database Migrations
+
+## Purpose
+
+Implement safe, reversible database migrations for production environments:
+
+- Apply expand-contract pattern for zero-downtime changes
+- Design rollback strategies for every migration
+- Handle large table alterations safely
+- Integrate migrations with CI/CD pipelines
+- Test migrations before production deployment
+
+## Quick Start
+
+```bash
+# Prisma
+npx prisma migrate dev --name add_user_roles
+npx prisma migrate deploy  # Production
+
+# TypeORM
+npm run typeorm migration:generate -- -n AddUserRoles
+npm run typeorm migration:run
+
+# Raw SQL with naming convention
+# migrations/20241230_001_add_user_roles.sql
+```
+
+```typescript
+// Prisma migration example
+// prisma/migrations/20241230_add_user_roles/migration.sql
+ALTER TABLE "users" ADD COLUMN "role" VARCHAR(50) DEFAULT 'user';
+CREATE INDEX "idx_users_role" ON "users"("role");
+```
+
+## Features
+
+| Feature | Strategy | When to Use |
+|---------|----------|-------------|
+| Add Column | Add nullable, then backfill, then NOT NULL | Always safe |
+| Remove Column | Stop using, deploy, then remove | Expand-contract |
+| Rename Column | Add new, copy data, remove old | Zero-downtime required |
+| Change Type | Add new column, migrate, swap | Data transformation |
+| Add Index | CREATE CONCURRENTLY | Large tables (>1M rows) |
+| Drop Table | Rename first, drop after verification | Reversible delete |
+
+## Common Patterns
+
+### Expand-Contract Pattern
+
+```sql
+-- EXPAND: Add new structure (backward compatible)
+-- Migration 1: Add new column
+ALTER TABLE users ADD COLUMN full_name VARCHAR(255);
+
+-- Application: Write to BOTH columns
+UPDATE users SET full_name = first_name || ' ' || last_name;
+
+-- Deploy application that reads from new column
+
+-- CONTRACT: Remove old structure
+-- Migration 2: (after app deployed)
+ALTER TABLE users DROP COLUMN first_name;
+ALTER TABLE users DROP COLUMN last_name;
+```
+
+### Safe Column Addition
+
+```sql
+-- Step 1: Add nullable column
+ALTER TABLE orders ADD COLUMN shipping_method VARCHAR(50);
+
+-- Step 2: Backfill in batches (avoid locking)
+UPDATE orders SET shipping_method = 'standard'
+WHERE id IN (SELECT id FROM orders WHERE shipping_method IS NULL LIMIT 10000);
+
+-- Step 3: Add NOT NULL constraint
+ALTER TABLE orders ALTER COLUMN shipping_method SET NOT NULL;
+ALTER TABLE orders ALTER COLUMN shipping_method SET DEFAULT 'standard';
+```
+
+### Safe Column Removal
+
+```sql
+-- Step 1: Stop application from using column
+-- (Deploy code that no longer reads/writes to column)
+
+-- Step 2: Drop default and constraints
+ALTER TABLE users ALTER COLUMN legacy_field DROP DEFAULT;
+ALTER TABLE users ALTER COLUMN legacy_field DROP NOT NULL;
+
+-- Step 3: Remove column (after verification period)
+ALTER TABLE users DROP COLUMN legacy_field;
+```
+
+### Safe Index Creation (Large Tables)
+
+```sql
+-- WRONG: Locks table for duration
+CREATE INDEX idx_orders_status ON orders(status);
+
+-- CORRECT: Non-blocking for PostgreSQL
+CREATE INDEX CONCURRENTLY idx_orders_status ON orders(status);
+
+-- Note: CONCURRENTLY cannot run in transaction
+-- For Prisma, use raw SQL migration:
+-- prisma/migrations/xxx/migration.sql
+-- /* Disable transaction for this migration */
+CREATE INDEX CONCURRENTLY idx_orders_status ON orders(status);
+```
+
+### Prisma Migration Workflow
+
+```bash
+# Development: Create and apply migration
+npx prisma migrate dev --name add_user_roles
+
+# Preview SQL without applying
+npx prisma migrate diff \
+  --from-schema-datamodel prisma/schema.prisma \
+  --to-schema-datamodel prisma/schema.prisma.new \
+  --script
+
+# Production deployment
+npx prisma migrate deploy
+
+# Reset for development (DESTRUCTIVE)
+npx prisma migrate reset
+```
+
+```prisma
+// schema.prisma - Example with relations
+model User {
+  id        String   @id @default(uuid())
+  email     String   @unique
+  role      Role     @default(USER)
+  posts     Post[]
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([email])
+}
+
+enum Role {
+  USER
+  ADMIN
+}
+```
+
+### TypeORM Migration
+
+```typescript
+// migrations/1703936400000-AddUserRoles.ts
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AddUserRoles1703936400000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE "users" ADD COLUMN "role" VARCHAR(50) DEFAULT 'user'
+    `);
+    await queryRunner.query(`
+      CREATE INDEX "idx_users_role" ON "users"("role")
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP INDEX "idx_users_role"`);
+    await queryRunner.query(`ALTER TABLE "users" DROP COLUMN "role"`);
+  }
+}
+```
+
+### Data Migration Pattern
+
+```typescript
+// Separate data migration from schema migration
+export class MigrateUserNames1703936500000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // Batch process to avoid memory issues
+    const batchSize = 1000;
+    let offset = 0;
+
+    while (true) {
+      const result = await queryRunner.query(`
+        UPDATE users
+        SET full_name = first_name || ' ' || last_name
+        WHERE full_name IS NULL
+        LIMIT ${batchSize}
+      `);
+
+      if (result.affectedRows === 0) break;
+      offset += batchSize;
+
+      // Optional: Add delay to reduce load
+      await new Promise(r => setTimeout(r, 100));
+    }
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    // Data migrations often aren't reversible
+    console.log('Data migration rollback: manual intervention required');
+  }
+}
+```
+
+## Use Cases
+
+- Adding new features requiring schema changes
+- Refactoring database structure safely
+- Splitting or merging tables
+- Changing column data types
+- Large-scale data migrations
+
+## Best Practices
+
+| Do | Avoid |
+|----|-------|
+| Test migrations on production-like data | Testing only on empty databases |
+| Use expand-contract for breaking changes | Direct column renames in production |
+| Create CONCURRENTLY for large table indexes | Blocking index creation on live tables |
+| Batch large data updates | Updating millions of rows in one transaction |
+| Include rollback in every migration | Forward-only migrations without escape |
+| Run migrations in CI before deploy | Manual migration execution |
+| Version control all migrations | Modifying applied migrations |
+| Separate schema and data migrations | Mixing DDL and large DML in one migration |
+
+## Migration Checklist
+
+```
+Pre-Migration:
+[ ] Migration tested on staging with production data volume
+[ ] Rollback script written and tested
+[ ] Estimated execution time documented
+[ ] Backup verified
+
+During Migration:
+[ ] Monitor database locks and connections
+[ ] Check application error rates
+[ ] Verify migration progress
+
+Post-Migration:
+[ ] Verify data integrity
+[ ] Check application functionality
+[ ] Monitor performance metrics
+[ ] Document completion
+```
+
+## CI/CD Integration
+
+```yaml
+# GitHub Actions example
+- name: Run Migrations
+  run: |
+    # Wait for healthy database
+    until pg_isready -h $DB_HOST; do sleep 1; done
+
+    # Run migrations with timeout
+    timeout 600 npx prisma migrate deploy
+
+    # Verify migration status
+    npx prisma migrate status
+  env:
+    DATABASE_URL: ${{ secrets.DATABASE_URL }}
+```
+
+## Related Skills
+
+See also these related skill documents:
+
+- **designing-database-schemas** - Schema design principles
+- **managing-databases** - DBA operations and maintenance
+- **optimizing-databases** - Performance tuning

package/plugin/skills/databases/database-schema-design/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: designing-database-schemas
+description: AI agent designs production-grade database schemas with proper normalization, indexing strategies, and data modeling patterns. Use when creating new databases, designing tables, modeling relationships, or reviewing schema architecture.
+category: databases
+triggers:
+  - schema design
+  - database design
+  - data modeling
+  - ERD
+  - entity relationship
+  - table design
+  - normalization
+---
+
+# Designing Database Schemas
+
+## Purpose
+
+Design scalable, maintainable database schemas that balance normalization with query performance:
+
+- Apply normalization principles (1NF-BCNF) appropriately
+- Choose optimal data types and constraints
+- Design efficient indexing strategies
+- Implement common patterns (audit trails, soft deletes, multi-tenancy)
+- Create clear entity relationships
+
+## Quick Start
+
+```sql
+-- Well-designed table with proper constraints
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email VARCHAR(255) NOT NULL UNIQUE,
+  username VARCHAR(50) NOT NULL UNIQUE,
+  password_hash VARCHAR(255) NOT NULL,
+  status VARCHAR(20) NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'suspended', 'deleted')),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  deleted_at TIMESTAMPTZ  -- Soft delete
+);
+
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_status ON users(status) WHERE deleted_at IS NULL;
+```
+
+## Features
+
+| Feature | Description | Pattern |
+|---------|-------------|---------|
+| Normalization | Eliminate redundancy while maintaining query efficiency | 3NF for OLTP, denormalize for read-heavy |
+| Primary Keys | UUID vs serial, natural vs surrogate keys | UUID for distributed, serial for simple apps |
+| Foreign Keys | Referential integrity with cascade options | CASCADE for owned data, RESTRICT for referenced |
+| Indexes | Query optimization with minimal write overhead | B-tree default, GIN for JSONB/arrays |
+| Constraints | Data integrity at database level | CHECK, UNIQUE, NOT NULL, EXCLUSION |
+| Partitioning | Horizontal scaling for large tables | Range (time), List (category), Hash (even dist) |
+
+## Common Patterns
+
+### Audit Trail Pattern
+
+```sql
+-- Add to every auditable table
+ALTER TABLE orders ADD COLUMN
+  created_by UUID REFERENCES users(id),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_by UUID REFERENCES users(id),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW();
+
+-- Automatic updated_at trigger
+CREATE OR REPLACE FUNCTION update_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER orders_updated_at
+  BEFORE UPDATE ON orders
+  FOR EACH ROW EXECUTE FUNCTION update_updated_at();
+```
+
+### Multi-Tenancy (Row-Level)
+
+```sql
+-- Tenant isolation with RLS
+CREATE TABLE projects (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id UUID NOT NULL REFERENCES tenants(id),
+  name VARCHAR(255) NOT NULL,
+  -- Always include tenant_id in indexes
+  UNIQUE (tenant_id, name)
+);
+
+CREATE INDEX idx_projects_tenant ON projects(tenant_id);
+
+-- Row Level Security
+ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON projects
+  USING (tenant_id = current_setting('app.tenant_id')::uuid);
+```
+
+### Polymorphic Associations
+
+```sql
+-- Option 1: Separate junction tables (recommended)
+CREATE TABLE comments (
+  id UUID PRIMARY KEY,
+  body TEXT NOT NULL,
+  author_id UUID REFERENCES users(id)
+);
+
+CREATE TABLE post_comments (
+  comment_id UUID PRIMARY KEY REFERENCES comments(id),
+  post_id UUID NOT NULL REFERENCES posts(id)
+);
+
+CREATE TABLE task_comments (
+  comment_id UUID PRIMARY KEY REFERENCES comments(id),
+  task_id UUID NOT NULL REFERENCES tasks(id)
+);
+
+-- Option 2: JSONB for flexible relations (when schema varies)
+CREATE TABLE activities (
+  id UUID PRIMARY KEY,
+  subject_type VARCHAR(50) NOT NULL,
+  subject_id UUID NOT NULL,
+  metadata JSONB DEFAULT '{}',
+  CHECK (subject_type IN ('post', 'task', 'comment'))
+);
+CREATE INDEX idx_activities_subject ON activities(subject_type, subject_id);
+```
+
+### JSONB for Semi-Structured Data
+
+```sql
+-- Good: Configuration, metadata, varying attributes
+CREATE TABLE products (
+  id UUID PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  base_price DECIMAL(10,2) NOT NULL,
+  attributes JSONB DEFAULT '{}'  -- Color, size, custom fields
+);
+
+CREATE INDEX idx_products_attrs ON products USING GIN (attributes);
+
+-- Query JSONB
+SELECT * FROM products
+WHERE attributes @> '{"color": "red"}'
+  AND (attributes->>'size')::int > 10;
+```
+
+## Use Cases
+
+- Greenfield database design for new applications
+- Schema reviews and optimization recommendations
+- Migration from NoSQL to relational or vice versa
+- Multi-tenant SaaS database architecture
+- Audit and compliance requirements implementation
+
+## Best Practices
+
+| Do | Avoid |
+|----|-------|
+| Use UUID for distributed systems, serial for simple apps | Auto-incrementing IDs exposed to users (enumeration risk) |
+| Apply 3NF for OLTP, denormalize strategically for reads | Over-normalizing lookup tables (country codes, etc.) |
+| Create indexes matching query WHERE/ORDER BY patterns | Indexing every column (write performance penalty) |
+| Use CHECK constraints for enum-like values | Storing booleans as strings or integers |
+| Add NOT NULL unless truly optional | Nullable columns without clear semantics |
+| Prefix indexes with table name: `idx_users_email` | Generic index names like `index1` |
+| Use TIMESTAMPTZ for all timestamps | Storing timestamps without timezone |
+| Design for the 80% use case first | Premature optimization for edge cases |
+
+## Schema Review Checklist
+
+```
+[ ] All tables have primary keys
+[ ] Foreign keys have appropriate ON DELETE actions
+[ ] Indexes exist for all foreign keys
+[ ] Indexes match common query patterns
+[ ] No nullable columns without clear use case
+[ ] Timestamps use TIMESTAMPTZ
+[ ] Audit columns (created_at, updated_at) present
+[ ] Naming follows consistent convention
+[ ] JSONB used only for truly variable schema
+[ ] Partitioning considered for tables > 10M rows
+```
+
+## Related Skills
+
+See also these related skill documents:
+
+- **managing-database-migrations** - Safe schema evolution patterns
+- **optimizing-databases** - Query and index optimization
+- **building-with-supabase** - PostgreSQL with RLS patterns

package/plugin/skills/databases/supabase/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: building-with-supabase
+description: AI agent builds full-stack applications with Supabase PostgreSQL, authentication, Row Level Security, Edge Functions, and real-time subscriptions. Use when building apps with Supabase, implementing RLS policies, or setting up Supabase Auth.
+category: databases
+triggers:
+  - supabase
+  - RLS
+  - row level security
+  - supabase auth
+  - edge functions
+  - real-time
+  - supabase storage
+---
+
+# Building with Supabase
+
+## Purpose
+
+Build secure, scalable applications using Supabase's PostgreSQL platform:
+
+- Design tables with proper Row Level Security (RLS)
+- Implement authentication flows (email, OAuth, magic link)
+- Create real-time subscriptions for live updates
+- Build Edge Functions for serverless logic
+- Manage file storage with security policies
+
+## Quick Start
+
+```typescript
+// Initialize Supabase client
+import { createClient } from '@supabase/supabase-js';
+import { Database } from './types/supabase';
+
+export const supabase = createClient<Database>(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+);
+
+// Server-side with service role (bypasses RLS)
+import { createClient } from '@supabase/supabase-js';
+export const supabaseAdmin = createClient<Database>(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!
+);
+```
+
+## Features
+
+| Feature | Description | Guide |
+|---------|-------------|-------|
+| PostgreSQL | Full Postgres with extensions (pgvector, PostGIS) | Direct SQL or Supabase client |
+| Row Level Security | Per-row access control policies | Enable RLS + create policies |
+| Authentication | Email, OAuth, magic link, phone OTP | Built-in auth.users table |
+| Real-time | Live database change subscriptions | Channel subscriptions |
+| Edge Functions | Deno serverless functions | TypeScript at edge |
+| Storage | S3-compatible file storage | Buckets with RLS policies |
+
+## Common Patterns
+
+### RLS Policy Patterns
+
+```sql
+-- Enable RLS on table
+ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
+
+-- Owner-based access
+CREATE POLICY "Users can CRUD own posts" ON posts
+  FOR ALL
+  USING (auth.uid() = user_id)
+  WITH CHECK (auth.uid() = user_id);
+
+-- Public read, authenticated write
+CREATE POLICY "Anyone can read posts" ON posts
+  FOR SELECT USING (published = true);
+
+CREATE POLICY "Authenticated users can create" ON posts
+  FOR INSERT
+  WITH CHECK (auth.uid() IS NOT NULL);
+
+-- Team-based access
+CREATE POLICY "Team members can access" ON documents
+  FOR ALL
+  USING (
+    team_id IN (
+      SELECT team_id FROM team_members
+      WHERE user_id = auth.uid()
+    )
+  );
+
+-- Role-based access using JWT claims
+CREATE POLICY "Admins can do anything" ON users
+  FOR ALL
+  USING (auth.jwt() ->> 'role' = 'admin');
+```
+
+### Authentication Flow
+
+```typescript
+// Sign up with email
+const { data, error } = await supabase.auth.signUp({
+  email: 'user@example.com',
+  password: 'secure-password',
+  options: {
+    data: { full_name: 'John Doe' },  // Custom user metadata
+    emailRedirectTo: 'https://app.com/auth/callback',
+  },
+});
+
+// OAuth sign in
+const { data, error } = await supabase.auth.signInWithOAuth({
+  provider: 'google',
+  options: {
+    redirectTo: 'https://app.com/auth/callback',
+    scopes: 'email profile',
+  },
+});
+
+// Magic link
+const { error } = await supabase.auth.signInWithOtp({
+  email: 'user@example.com',
+  options: { emailRedirectTo: 'https://app.com/auth/callback' },
+});
+
+// Get current user
+const { data: { user } } = await supabase.auth.getUser();
+
+// Sign out
+await supabase.auth.signOut();
+```
+
+### Real-time Subscriptions
+
+```typescript
+// Subscribe to table changes
+const channel = supabase
+  .channel('posts-changes')
+  .on(
+    'postgres_changes',
+    {
+      event: '*',  // INSERT, UPDATE, DELETE, or *
+      schema: 'public',
+      table: 'posts',
+      filter: 'user_id=eq.' + userId,  // Optional filter
+    },
+    (payload) => {
+      console.log('Change:', payload.eventType, payload.new);
+    }
+  )
+  .subscribe();
+
+// Cleanup
+channel.unsubscribe();
+```
+
+### Edge Functions
+
+```typescript
+// supabase/functions/process-webhook/index.ts
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts';
+import { createClient } from 'https://esm.sh/@supabase/supabase-js@2';
+
+serve(async (req) => {
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+  );
+
+  const { record } = await req.json();
+
+  // Process webhook...
+  await supabase.from('processed').insert({ data: record });
+
+  return new Response(JSON.stringify({ success: true }), {
+    headers: { 'Content-Type': 'application/json' },
+  });
+});
+```
+
+### Storage with Policies
+
+```sql
+-- Create bucket
+INSERT INTO storage.buckets (id, name, public)
+VALUES ('avatars', 'avatars', true);
+
+-- Storage policies
+CREATE POLICY "Users can upload own avatar" ON storage.objects
+  FOR INSERT WITH CHECK (
+    bucket_id = 'avatars' AND
+    auth.uid()::text = (storage.foldername(name))[1]
+  );
+
+CREATE POLICY "Anyone can view avatars" ON storage.objects
+  FOR SELECT USING (bucket_id = 'avatars');
+```
+
+```typescript
+// Upload file
+const { data, error } = await supabase.storage
+  .from('avatars')
+  .upload(`${userId}/avatar.png`, file, {
+    cacheControl: '3600',
+    upsert: true,
+  });
+
+// Get public URL
+const { data: { publicUrl } } = supabase.storage
+  .from('avatars')
+  .getPublicUrl(`${userId}/avatar.png`);
+```
+
+### Next.js Server Components
+
+```typescript
+// app/api/posts/route.ts
+import { createRouteHandlerClient } from '@supabase/auth-helpers-nextjs';
+import { cookies } from 'next/headers';
+
+export async function GET() {
+  const supabase = createRouteHandlerClient({ cookies });
+  const { data: posts } = await supabase.from('posts').select('*');
+  return Response.json(posts);
+}
+
+// Server Component
+import { createServerComponentClient } from '@supabase/auth-helpers-nextjs';
+import { cookies } from 'next/headers';
+
+export default async function Page() {
+  const supabase = createServerComponentClient({ cookies });
+  const { data: posts } = await supabase.from('posts').select('*');
+  return <PostList posts={posts} />;
+}
+```
+
+## Use Cases
+
+- Building SaaS applications with multi-tenant RLS
+- Real-time collaborative applications
+- Mobile app backends with authentication
+- Serverless APIs with Edge Functions
+- File upload systems with access control
+
+## Best Practices
+
+| Do | Avoid |
+|----|-------|
+| Enable RLS on all tables | Disabling RLS "temporarily" in production |
+| Use `auth.uid()` in policies, not session data | Trusting client-side user ID |
+| Create service role client only server-side | Exposing service role key to client |
+| Use TypeScript types from `supabase gen types` | Manual type definitions |
+| Filter subscriptions to reduce bandwidth | Subscribing to entire tables |
+| Use `supabase db push` for dev, migrations for prod | Pushing directly to production |
+| Set up proper bucket policies | Public buckets for sensitive files |
+| Use `signInWithOAuth` for social auth | Custom OAuth implementations |
+
+## CLI Commands
+
+```bash
+# Local development
+supabase start                      # Start local Supabase
+supabase db reset                   # Reset with migrations + seed
+
+# Migrations
+supabase migration new add_posts    # Create migration
+supabase db push                    # Push to linked project (dev only)
+supabase db diff --use-migra        # Generate migration from diff
+
+# Type generation
+supabase gen types typescript --local > types/supabase.ts
+
+# Edge Functions
+supabase functions serve            # Local development
+supabase functions deploy my-func   # Deploy to production
+```
+
+## Related Skills
+
+See also these related skill documents:
+
+- **designing-database-schemas** - Schema design patterns
+- **managing-database-migrations** - Migration strategies
+- **implementing-oauth** - OAuth flow details