ai-devx 1.0.0 → 1.0.1

package/templates/.agent/skills/database-design/SKILL.md

@@ -1,303 +1,52 @@
 ---
 name: database-design
-description: Database schema design, normalization, and optimization patterns
-version: "1.0.0"
-requires: []
-related:
-  - backend-specialist
-  - sql-optimization
+description: Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.
+allowed-tools: Read, Write, Edit, Glob, Grep
 ---
 
-# Database Design Skill
+# Database Design
 
-## Design Principles
+> **Learn to THINK, not copy SQL patterns.**
 
-### ACID Properties
-- **Atomicity**: All operations succeed or fail together
-- **Consistency**: Database remains in valid state
-- **Isolation**: Concurrent transactions don't interfere
-- **Durability**: Committed data persists
+## 🎯 Selective Reading Rule
 
-### Normalization
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
 
-#### 1NF - First Normal Form
-- Atomic values (no arrays/objects in columns)
-- Each cell contains single value
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `database-selection.md` | PostgreSQL vs Neon vs Turso vs SQLite | Choosing database |
+| `orm-selection.md` | Drizzle vs Prisma vs Kysely | Choosing ORM |
+| `schema-design.md` | Normalization, PKs, relationships | Designing schema |
+| `indexing.md` | Index types, composite indexes | Performance tuning |
+| `optimization.md` | N+1, EXPLAIN ANALYZE | Query optimization |
+| `migrations.md` | Safe migrations, serverless DBs | Schema changes |
 
-```sql
--- ❌ Not 1NF
-CREATE TABLE orders (
-  id INT PRIMARY KEY,
-  items VARCHAR(255) -- "item1, item2, item3"
-);
-
--- ✅ 1NF
-CREATE TABLE order_items (
-  order_id INT,
-  item_name VARCHAR(255),
-  quantity INT
-);
-```
-
-#### 2NF - Second Normal Form
-- Must be in 1NF
-- No partial dependencies (non-key columns depend on full PK)
-
-```sql
--- ❌ Not 2NF (price depends only on product_id, not order_id)
-CREATE TABLE order_items (
-  order_id INT,
-  product_id INT,
-  product_name VARCHAR(255),
-  product_price DECIMAL,
-  quantity INT,
-  PRIMARY KEY (order_id, product_id)
-);
-
--- ✅ 2NF
-CREATE TABLE products (
-  id INT PRIMARY KEY,
-  name VARCHAR(255),
-  price DECIMAL
-);
-
-CREATE TABLE order_items (
-  order_id INT,
-  product_id INT,
-  quantity INT,
-  PRIMARY KEY (order_id, product_id)
-);
-```
-
-#### 3NF - Third Normal Form
-- Must be in 2NF
-- No transitive dependencies
-
-```sql
--- ❌ Not 3NF (category_description depends on category, not directly on product)
-CREATE TABLE products (
-  id INT PRIMARY KEY,
-  name VARCHAR(255),
-  category VARCHAR(255),
-  category_description TEXT
-);
-
--- ✅ 3NF
-CREATE TABLE categories (
-  id INT PRIMARY KEY,
-  name VARCHAR(255),
-  description TEXT
-);
-
-CREATE TABLE products (
-  id INT PRIMARY KEY,
-  name VARCHAR(255),
-  category_id INT,
-  FOREIGN KEY (category_id) REFERENCES categories(id)
-);
-```
-
-## Schema Design Patterns
-
-### User Management
-```sql
-CREATE TABLE users (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  email VARCHAR(255) UNIQUE NOT NULL,
-  password_hash VARCHAR(255) NOT NULL,
-  name VARCHAR(255) NOT NULL,
-  role VARCHAR(50) DEFAULT 'user',
-  is_active BOOLEAN DEFAULT true,
-  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE TABLE user_profiles (
-  user_id UUID PRIMARY KEY,
-  bio TEXT,
-  avatar_url VARCHAR(500),
-  phone VARCHAR(20),
-  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-);
-```
-
-### E-Commerce
-```sql
-CREATE TABLE products (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  name VARCHAR(255) NOT NULL,
-  description TEXT,
-  price DECIMAL(10,2) NOT NULL,
-  stock_quantity INT DEFAULT 0,
-  category_id UUID,
-  is_active BOOLEAN DEFAULT true,
-  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-);
-
-CREATE TABLE orders (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  user_id UUID NOT NULL,
-  status VARCHAR(50) DEFAULT 'pending',
-  total_amount DECIMAL(10,2) NOT NULL,
-  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  FOREIGN KEY (user_id) REFERENCES users(id)
-);
-
-CREATE TABLE order_items (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  order_id UUID NOT NULL,
-  product_id UUID NOT NULL,
-  quantity INT NOT NULL,
-  unit_price DECIMAL(10,2) NOT NULL,
-  FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE,
-  FOREIGN KEY (product_id) REFERENCES products(id)
-);
-```
-
-### Many-to-Many Relationships
-```sql
--- Users and Roles (Many-to-Many)
-CREATE TABLE roles (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  name VARCHAR(100) UNIQUE NOT NULL,
-  permissions JSONB
-);
-
-CREATE TABLE user_roles (
-  user_id UUID,
-  role_id UUID,
-  assigned_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  PRIMARY KEY (user_id, role_id),
-  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
-  FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE
-);
-```
-
-## Indexing Strategy
-
-### When to Index
-- Primary keys (automatic)
-- Foreign keys
-- Columns in WHERE clauses
-- Columns in ORDER BY
-- Columns in JOIN conditions
-
-### Index Types
-```sql
--- B-Tree Index (default)
-CREATE INDEX idx_users_email ON users(email);
-
--- Unique Index
-CREATE UNIQUE INDEX idx_users_email_unique ON users(email);
-
--- Composite Index
-CREATE INDEX idx_orders_user_status ON orders(user_id, status);
-
--- Partial Index
-CREATE INDEX idx_active_users ON users(email) WHERE is_active = true;
-
--- GIN Index (for JSONB, arrays)
-CREATE INDEX idx_products_tags ON products USING GIN(tags);
-```
-
-### Index Best Practices
-- Don't over-index (slows writes)
-- Consider index selectivity
-- Index order matters in composite indexes
-- Regularly review and remove unused indexes
-
-## Prisma Schema Example
-
-```prisma
-model User {
-  id        String   @id @default(uuid())
-  email     String   @unique
-  password  String
-  name      String
-  role      Role     @default(USER)
-  isActive  Boolean  @default(true)
-  createdAt DateTime @default(now()) @map("created_at")
-  updatedAt DateTime @updatedAt @map("updated_at")
-  
-  profile   Profile?
-  posts     Post[]
-  orders    Order[]
-  
-  @@map("users")
-}
-
-model Profile {
-  id     String @id @default(uuid())
-  bio    String?
-  avatar String?
-  
-  userId String @unique @map("user_id")
-  user   User   @relation(fields: [userId], references: [id])
-  
-  @@map("profiles")
-}
-
-model Post {
-  id        String   @id @default(uuid())
-  title     String
-  content   String?
-  published Boolean  @default(false)
-  createdAt DateTime @default(now()) @map("created_at")
-  
-  authorId  String   @map("author_id")
-  author    User     @relation(fields: [authorId], references: [id])
-  
-  @@index([authorId])
-  @@map("posts")
-}
+---
 
-enum Role {
-  USER
-  ADMIN
-  MODERATOR
-}
-```
+## ⚠️ Core Principle
 
-## Migration Strategy
+- ASK user for database preferences when unclear
+- Choose database/ORM based on CONTEXT
+- Don't default to PostgreSQL for everything
 
-### Best Practices
-1. Always create migrations for schema changes
-2. Test migrations on staging first
-3. Backup before major migrations
-4. Keep migrations reversible
-5. Document breaking changes
+---
 
-### Migration Example
-```sql
--- Up
-CREATE TABLE new_feature (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  name VARCHAR(255) NOT NULL
-);
+## Decision Checklist
 
--- Down
-DROP TABLE IF EXISTS new_feature;
-```
+Before designing schema:
 
-## Query Optimization
+- [ ] Asked user about database preference?
+- [ ] Chosen database for THIS context?
+- [ ] Considered deployment environment?
+- [ ] Planned index strategy?
+- [ ] Defined relationship types?
 
-### N+1 Problem
-```typescript
-// ❌ N+1 queries
-const users = await prisma.user.findMany();
-for (const user of users) {
-  const posts = await prisma.post.findMany({
-    where: { authorId: user.id }
-  });
-}
+---
 
-// ✅ Single query with join
-const users = await prisma.user.findMany({
-  include: { posts: true }
-});
-```
+## Anti-Patterns
 
-### EXPLAIN ANALYZE
-```sql
-EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';
-```
+❌ Default to PostgreSQL for simple apps (SQLite may suffice)
+❌ Skip indexing
+❌ Use SELECT * in production
+❌ Store JSON when structured data is better
+❌ Ignore N+1 queries

package/templates/.agent/skills/database-design/database-selection.md

@@ -0,0 +1,43 @@
+# Database Selection (2025)
+
+> Choose database based on context, not default.
+
+## Decision Tree
+
+```
+What are your requirements?
+│
+├── Full relational features needed
+│   ├── Self-hosted → PostgreSQL
+│   └── Serverless → Neon, Supabase
+│
+├── Edge deployment / Ultra-low latency
+│   └── Turso (edge SQLite)
+│
+├── AI / Vector search
+│   └── PostgreSQL + pgvector
+│
+├── Simple / Embedded / Local
+│   └── SQLite
+│
+└── Global distribution
+    └── PlanetScale, CockroachDB, Turso
+```
+
+## Comparison
+
+| Database | Best For | Trade-offs |
+|----------|----------|------------|
+| **PostgreSQL** | Full features, complex queries | Needs hosting |
+| **Neon** | Serverless PG, branching | PG complexity |
+| **Turso** | Edge, low latency | SQLite limitations |
+| **SQLite** | Simple, embedded, local | Single-writer |
+| **PlanetScale** | MySQL, global scale | No foreign keys |
+
+## Questions to Ask
+
+1. What's the deployment environment?
+2. How complex are the queries?
+3. Is edge/serverless important?
+4. Vector search needed?
+5. Global distribution required?

package/templates/.agent/skills/database-design/indexing.md

@@ -0,0 +1,39 @@
+# Indexing Principles
+
+> When and how to create indexes effectively.
+
+## When to Create Indexes
+
+```
+Index these:
+├── Columns in WHERE clauses
+├── Columns in JOIN conditions
+├── Columns in ORDER BY
+├── Foreign key columns
+└── Unique constraints
+
+Don't over-index:
+├── Write-heavy tables (slower inserts)
+├── Low-cardinality columns
+├── Columns rarely queried
+```
+
+## Index Type Selection
+
+| Type | Use For |
+|------|---------|
+| **B-tree** | General purpose, equality & range |
+| **Hash** | Equality only, faster |
+| **GIN** | JSONB, arrays, full-text |
+| **GiST** | Geometric, range types |
+| **HNSW/IVFFlat** | Vector similarity (pgvector) |
+
+## Composite Index Principles
+
+```
+Order matters for composite indexes:
+├── Equality columns first
+├── Range columns last
+├── Most selective first
+└── Match query pattern
+```

package/templates/.agent/skills/database-design/migrations.md

@@ -0,0 +1,48 @@
+# Migration Principles
+
+> Safe migration strategy for zero-downtime changes.
+
+## Safe Migration Strategy
+
+```
+For zero-downtime changes:
+│
+├── Adding column
+│   └── Add as nullable → backfill → add NOT NULL
+│
+├── Removing column
+│   └── Stop using → deploy → remove column
+│
+├── Adding index
+│   └── CREATE INDEX CONCURRENTLY (non-blocking)
+│
+└── Renaming column
+    └── Add new → migrate data → deploy → drop old
+```
+
+## Migration Philosophy
+
+- Never make breaking changes in one step
+- Test migrations on data copy first
+- Have rollback plan
+- Run in transaction when possible
+
+## Serverless Databases
+
+### Neon (Serverless PostgreSQL)
+
+| Feature | Benefit |
+|---------|---------|
+| Scale to zero | Cost savings |
+| Instant branching | Dev/preview |
+| Full PostgreSQL | Compatibility |
+| Autoscaling | Traffic handling |
+
+### Turso (Edge SQLite)
+
+| Feature | Benefit |
+|---------|---------|
+| Edge locations | Ultra-low latency |
+| SQLite compatible | Simple |
+| Generous free tier | Cost |
+| Global distribution | Performance |

package/templates/.agent/skills/database-design/optimization.md

@@ -0,0 +1,36 @@
+# Query Optimization
+
+> N+1 problem, EXPLAIN ANALYZE, optimization priorities.
+
+## N+1 Problem
+
+```
+What is N+1?
+├── 1 query to get parent records
+├── N queries to get related records
+└── Very slow!
+
+Solutions:
+├── JOIN → Single query with all data
+├── Eager loading → ORM handles JOIN
+├── DataLoader → Batch and cache (GraphQL)
+└── Subquery → Fetch related in one query
+```
+
+## Query Analysis Mindset
+
+```
+Before optimizing:
+├── EXPLAIN ANALYZE the query
+├── Look for Seq Scan (full table scan)
+├── Check actual vs estimated rows
+└── Identify missing indexes
+```
+
+## Optimization Priorities
+
+1. **Add missing indexes** (most common issue)
+2. **Select only needed columns** (not SELECT *)
+3. **Use proper JOINs** (avoid subqueries when possible)
+4. **Limit early** (pagination at database level)
+5. **Cache** (when appropriate)

package/templates/.agent/skills/database-design/orm-selection.md

@@ -0,0 +1,30 @@
+# ORM Selection (2025)
+
+> Choose ORM based on deployment and DX needs.
+
+## Decision Tree
+
+```
+What's the context?
+│
+├── Edge deployment / Bundle size matters
+│   └── Drizzle (smallest, SQL-like)
+│
+├── Best DX / Schema-first
+│   └── Prisma (migrations, studio)
+│
+├── Maximum control
+│   └── Raw SQL with query builder
+│
+└── Python ecosystem
+    └── SQLAlchemy 2.0 (async support)
+```
+
+## Comparison
+
+| ORM | Best For | Trade-offs |
+|-----|----------|------------|
+| **Drizzle** | Edge, TypeScript | Newer, less examples |
+| **Prisma** | DX, schema management | Heavier, not edge-ready |
+| **Kysely** | Type-safe SQL builder | Manual migrations |
+| **Raw SQL** | Complex queries, control | Manual type safety |

package/templates/.agent/skills/database-design/schema-design.md

@@ -0,0 +1,56 @@
+# Schema Design Principles
+
+> Normalization, primary keys, timestamps, relationships.
+
+## Normalization Decision
+
+```
+When to normalize (separate tables):
+├── Data is repeated across rows
+├── Updates would need multiple changes
+├── Relationships are clear
+└── Query patterns benefit
+
+When to denormalize (embed/duplicate):
+├── Read performance critical
+├── Data rarely changes
+├── Always fetched together
+└── Simpler queries needed
+```
+
+## Primary Key Selection
+
+| Type | Use When |
+|------|----------|
+| **UUID** | Distributed systems, security |
+| **ULID** | UUID + sortable by time |
+| **Auto-increment** | Simple apps, single database |
+| **Natural key** | Rarely (business meaning) |
+
+## Timestamp Strategy
+
+```
+For every table:
+├── created_at → When created
+├── updated_at → Last modified
+└── deleted_at → Soft delete (if needed)
+
+Use TIMESTAMPTZ (with timezone) not TIMESTAMP
+```
+
+## Relationship Types
+
+| Type | When | Implementation |
+|------|------|----------------|
+| **One-to-One** | Extension data | Separate table with FK |
+| **One-to-Many** | Parent-children | FK on child table |
+| **Many-to-Many** | Both sides have many | Junction table |
+
+## Foreign Key ON DELETE
+
+```
+├── CASCADE → Delete children with parent
+├── SET NULL → Children become orphans
+├── RESTRICT → Prevent delete if children exist
+└── SET DEFAULT → Children get default value
+```