ai-devx 1.0.0

package/templates/.agent/skills/api-patterns/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: api-patterns
+description: REST API design patterns, authentication, and best practices
+version: "1.0.0"
+requires: []
+related:
+  - backend-specialist
+  - security-best-practices
+---
+
+# API Patterns Skill
+
+## REST API Design
+
+### Resource Naming
+- Use nouns, not verbs
+- Use plural forms
+- Use kebab-case for multi-word resources
+
+```
+✅ GET    /users
+✅ GET    /users/:id
+✅ POST   /users
+✅ PUT    /users/:id
+✅ DELETE /users/:id
+✅ GET    /user-profiles
+
+❌ GET    /getUsers
+❌ GET    /getUserById
+❌ POST   /createUser
+```
+
+### HTTP Methods
+| Method | Action | Idempotent |
+|--------|--------|------------|
+| GET | Read | Yes |
+| POST | Create | No |
+| PUT | Update (full) | Yes |
+| PATCH | Update (partial) | No |
+| DELETE | Remove | Yes |
+
+### Status Codes
+- **200** - OK (GET, PUT, PATCH, DELETE)
+- **201** - Created (POST)
+- **204** - No Content (DELETE)
+- **400** - Bad Request
+- **401** - Unauthorized
+- **403** - Forbidden
+- **404** - Not Found
+- **409** - Conflict
+- **422** - Unprocessable Entity
+- **500** - Internal Server Error
+
+### Response Format
+```json
+{
+  "success": true,
+  "data": {
+    "id": "123",
+    "name": "John Doe"
+  },
+  "meta": {
+    "page": 1,
+    "limit": 10,
+    "total": 100
+  }
+}
+```
+
+### Error Response
+```json
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input data",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format"
+      }
+    ]
+  }
+}
+```
+
+## Authentication Patterns
+
+### JWT Authentication
+```typescript
+// Login endpoint
+POST /auth/login
+{
+  "email": "user@example.com",
+  "password": "password123"
+}
+
+// Response
+{
+  "success": true,
+  "data": {
+    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
+    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
+    "expiresIn": 3600
+  }
+}
+
+// Protected endpoint
+GET /users
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+```
+
+### API Key Authentication
+```
+GET /api/resources
+X-API-Key: your-api-key-here
+```
+
+## Pagination Patterns
+
+### Offset Pagination
+```
+GET /users?page=1&limit=20
+
+Response:
+{
+  "data": [...],
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 100,
+    "totalPages": 5
+  }
+}
+```
+
+### Cursor Pagination
+```
+GET /users?cursor=xyz&limit=20
+
+Response:
+{
+  "data": [...],
+  "meta": {
+    "nextCursor": "abc",
+    "hasMore": true
+  }
+}
+```
+
+## Filtering & Sorting
+
+```
+GET /users?role=admin&status=active&sort=-created_at,name
+
+// Multiple filters (OR)
+GET /users?role=admin,moderator
+
+// Range filters
+GET /orders?created_at[gte]=2024-01-01&created_at[lte]=2024-12-31
+
+// Full-text search
+GET /products?q=laptop&category=electronics
+```
+
+## Validation Patterns
+
+### Input Validation
+```typescript
+// Using Zod
+const createUserSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+  name: z.string().min(1).max(100),
+  age: z.number().int().min(0).optional()
+});
+
+// Middleware
+app.post('/users', validate(createUserSchema), createUserHandler);
+```
+
+## Rate Limiting
+```
+Headers:
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1640995200
+```
+
+## API Versioning
+
+### URL Versioning
+```
+/api/v1/users
+/api/v2/users
+```
+
+### Header Versioning
+```
+Accept: application/vnd.api+json;version=1
+```
+
+## Best Practices
+
+### 1. Idempotency
+```
+Idempotency-Key: unique-key-for-request
+```
+
+### 2. Caching Headers
+```
+Cache-Control: max-age=3600
+ETag: "abc123"
+Last-Modified: Wed, 21 Oct 2024 07:28:00 GMT
+```
+
+### 3. Request IDs
+```
+X-Request-ID: uuid-for-tracing
+```
+
+### 4. Documentation
+- Use OpenAPI/Swagger
+- Include examples
+- Document error cases
+
+## Security Checklist
+- [ ] HTTPS only
+- [ ] Input validation
+- [ ] Authentication on protected routes
+- [ ] Authorization checks
+- [ ] Rate limiting
+- [ ] CORS configuration
+- [ ] Security headers
+- [ ] SQL injection prevention
+- [ ] XSS protection

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

@@ -0,0 +1,303 @@
+---
+name: database-design
+description: Database schema design, normalization, and optimization patterns
+version: "1.0.0"
+requires: []
+related:
+  - backend-specialist
+  - sql-optimization
+---
+
+# Database Design Skill
+
+## Design Principles
+
+### 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
+
+### Normalization
+
+#### 1NF - First Normal Form
+- Atomic values (no arrays/objects in columns)
+- Each cell contains single value
+
+```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
+}
+```
+
+## Migration Strategy
+
+### 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
+);
+
+-- Down
+DROP TABLE IF EXISTS new_feature;
+```
+
+## Query Optimization
+
+### 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 }
+});
+```
+
+### EXPLAIN ANALYZE
+```sql
+EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';
+```