omgkit 2.3.0 → 2.4.0

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

package/templates/devlogs/README.md

@@ -0,0 +1,29 @@
+# Development Logs
+
+This folder contains development artifacts that are **NOT committed to git**.
+
+## What Goes Here
+
+- **Plans**: Implementation plans, upgrade plans, migration plans
+- **Ideas**: Brainstorming notes, feature ideas, improvement proposals
+- **Logs**: Development session logs, debug logs, experiment notes
+- **Tracking**: Project status, task breakdowns, progress notes
+- **Management**: Sprint notes, retrospectives, decision logs
+
+## Why Separate?
+
+- Keep repository clean from temporary development artifacts
+- Allow free-form planning without polluting git history
+- Separate internal notes from public documentation
+- Enable AI agents to maintain persistent context
+
+## Best Practices
+
+1. Use descriptive filenames: `plan-auth-refactor-v2.md`
+2. Date prefix for logs: `2024-12-31-session-notes.md`
+3. Clean up completed plans periodically
+4. Move finalized decisions to `docs/` when ready for sharing
+
+---
+
+*This folder is git-ignored by default.*

package/templates/stdrules/README.md

@@ -0,0 +1,34 @@
+# Standards & Rules
+
+This folder contains standards and rules that govern project development.
+
+## What Goes Here
+
+- **Coding Standards**: Code style, naming conventions, patterns
+- **Architecture Rules**: System design constraints, technology choices
+- **Quality Gates**: Testing requirements, coverage thresholds
+- **Security Policies**: Authentication, authorization, data handling
+- **Documentation Standards**: API docs, README templates, comments
+
+## Included Files
+
+- `SKILL_STANDARDS.md` - Standards for creating AI agent skills
+
+## How AI Agents Use This
+
+AI agents in OMGKIT read from this folder to:
+1. Understand project-specific conventions
+2. Generate code that follows your standards
+3. Review code against established rules
+4. Propose improvements aligned with constraints
+
+## Adding New Standards
+
+1. Create a descriptive filename: `API_STANDARDS.md`, `TESTING_RULES.md`
+2. Use clear, actionable language
+3. Include examples of good and bad practices
+4. Reference from your `OMEGA.md` if needed
+
+---
+
+*Think Omega. Build Omega. Be Omega.*