ateschh-kit 1.0.0 → 1.2.0

package/skills/nextjs-app-router-patterns/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: nextjs-app-router-patterns
+description: "Master Next.js 14+ App Router with Server Components, streaming, parallel routes, and advanced data fetching. Use when building Next.js applications, implementing SSR/SSG, or optimizing React Serve..."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Next.js App Router Patterns
+
+Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.
+
+## Use this skill when
+
+- Building new Next.js applications with App Router
+- Migrating from Pages Router to App Router
+- Implementing Server Components and streaming
+- Setting up parallel and intercepting routes
+- Optimizing data fetching and caching
+- Building full-stack features with Server Actions
+
+## Do not use this skill when
+
+- The task is unrelated to next.js app router patterns
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns and examples.

package/skills/nextjs-best-practices/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: nextjs-best-practices
+description: "Next.js App Router principles. Server Components, data fetching, routing patterns."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Next.js Best Practices
+
+> Principles for Next.js App Router development.
+
+---
+
+## 1. Server vs Client Components
+
+### Decision Tree
+
+```
+Does it need...?
+│
+├── useState, useEffect, event handlers
+│   └── Client Component ('use client')
+│
+├── Direct data fetching, no interactivity
+│   └── Server Component (default)
+│
+└── Both? 
+    └── Split: Server parent + Client child
+```
+
+### By Default
+
+| Type | Use |
+|------|-----|
+| **Server** | Data fetching, layout, static content |
+| **Client** | Forms, buttons, interactive UI |
+
+---
+
+## 2. Data Fetching Patterns
+
+### Fetch Strategy
+
+| Pattern | Use |
+|---------|-----|
+| **Default** | Static (cached at build) |
+| **Revalidate** | ISR (time-based refresh) |
+| **No-store** | Dynamic (every request) |
+
+### Data Flow
+
+| Source | Pattern |
+|--------|---------|
+| Database | Server Component fetch |
+| API | fetch with caching |
+| User input | Client state + server action |
+
+---
+
+## 3. Routing Principles
+
+### File Conventions
+
+| File | Purpose |
+|------|---------|
+| `page.tsx` | Route UI |
+| `layout.tsx` | Shared layout |
+| `loading.tsx` | Loading state |
+| `error.tsx` | Error boundary |
+| `not-found.tsx` | 404 page |
+
+### Route Organization
+
+| Pattern | Use |
+|---------|-----|
+| Route groups `(name)` | Organize without URL |
+| Parallel routes `@slot` | Multiple same-level pages |
+| Intercepting `(.)` | Modal overlays |
+
+---
+
+## 4. API Routes
+
+### Route Handlers
+
+| Method | Use |
+|--------|-----|
+| GET | Read data |
+| POST | Create data |
+| PUT/PATCH | Update data |
+| DELETE | Remove data |
+
+### Best Practices
+
+- Validate input with Zod
+- Return proper status codes
+- Handle errors gracefully
+- Use Edge runtime when possible
+
+---
+
+## 5. Performance Principles
+
+### Image Optimization
+
+- Use next/image component
+- Set priority for above-fold
+- Provide blur placeholder
+- Use responsive sizes
+
+### Bundle Optimization
+
+- Dynamic imports for heavy components
+- Route-based code splitting (automatic)
+- Analyze with bundle analyzer
+
+---
+
+## 6. Metadata
+
+### Static vs Dynamic
+
+| Type | Use |
+|------|-----|
+| Static export | Fixed metadata |
+| generateMetadata | Dynamic per-route |
+
+### Essential Tags
+
+- title (50-60 chars)
+- description (150-160 chars)
+- Open Graph images
+- Canonical URL
+
+---
+
+## 7. Caching Strategy
+
+### Cache Layers
+
+| Layer | Control |
+|-------|---------|
+| Request | fetch options |
+| Data | revalidate/tags |
+| Full route | route config |
+
+### Revalidation
+
+| Method | Use |
+|--------|-----|
+| Time-based | `revalidate: 60` |
+| On-demand | `revalidatePath/Tag` |
+| No cache | `no-store` |
+
+---
+
+## 8. Server Actions
+
+### Use Cases
+
+- Form submissions
+- Data mutations
+- Revalidation triggers
+
+### Best Practices
+
+- Mark with 'use server'
+- Validate all inputs
+- Return typed responses
+- Handle errors
+
+---
+
+## 9. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| 'use client' everywhere | Server by default |
+| Fetch in client components | Fetch in server |
+| Skip loading states | Use loading.tsx |
+| Ignore error boundaries | Use error.tsx |
+| Large client bundles | Dynamic imports |
+
+---
+
+## 10. Project Structure
+
+```
+app/
+├── (marketing)/     # Route group
+│   └── page.tsx
+├── (dashboard)/
+│   ├── layout.tsx   # Dashboard layout
+│   └── page.tsx
+├── api/
+│   └── [resource]/
+│       └── route.ts
+└── components/
+    └── ui/
+```
+
+---
+
+> **Remember:** Server Components are the default for a reason. Start there, add client only when needed.
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/skills/nodejs-backend-patterns/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: nodejs-backend-patterns
+description: "Build production-ready Node.js backend services with Express/Fastify, implementing middleware patterns, error handling, authentication, database integration, and API design best practices. Use when..."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Node.js Backend Patterns
+
+Comprehensive guidance for building scalable, maintainable, and production-ready Node.js backend applications with modern frameworks, architectural patterns, and best practices.
+
+## Use this skill when
+
+- Building REST APIs or GraphQL servers
+- Creating microservices with Node.js
+- Implementing authentication and authorization
+- Designing scalable backend architectures
+- Setting up middleware and error handling
+- Integrating databases (SQL and NoSQL)
+- Building real-time applications with WebSockets
+- Implementing background job processing
+
+## Do not use this skill when
+
+- The task is unrelated to node.js backend patterns
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns and examples.

package/skills/postgres-best-practices/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: postgres-best-practices
+description: "Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Supabase Postgres Best Practices
+
+Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing SQL queries or designing schemas
+- Implementing indexes or query optimization
+- Reviewing database performance issues
+- Configuring connection pooling or scaling
+- Optimizing for Postgres-specific features
+- Working with Row-Level Security (RLS)
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Query Performance | CRITICAL | `query-` |
+| 2 | Connection Management | CRITICAL | `conn-` |
+| 3 | Security & RLS | CRITICAL | `security-` |
+| 4 | Schema Design | HIGH | `schema-` |
+| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
+| 6 | Data Access Patterns | MEDIUM | `data-` |
+| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
+| 8 | Advanced Features | LOW | `advanced-` |
+
+## How to Use
+
+Read individual rule files for detailed explanations and SQL examples:
+
+```
+rules/query-missing-indexes.md
+rules/schema-partial-indexes.md
+rules/_sections.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect SQL example with explanation
+- Correct SQL example with explanation
+- Optional EXPLAIN output or metrics
+- Additional context and references
+- Supabase-specific notes (when applicable)
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/skills/prisma-expert/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: prisma-expert
+description: "Prisma ORM expert for schema design, migrations, query optimization, relations modeling, and database operations. Use PROACTIVELY for Prisma schema issues, migration problems, query performance, re..."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Prisma Expert
+
+You are an expert in Prisma ORM with deep knowledge of schema design, migrations, query optimization, relations modeling, and database operations across PostgreSQL, MySQL, and SQLite.
+
+## When Invoked
+
+### Step 0: Recommend Specialist and Stop
+If the issue is specifically about:
+- **Raw SQL optimization**: Stop and recommend postgres-expert or mongodb-expert
+- **Database server configuration**: Stop and recommend database-expert
+- **Connection pooling at infrastructure level**: Stop and recommend devops-expert
+
+### Environment Detection
+```bash
+# Check Prisma version
+npx prisma --version 2>/dev/null || echo "Prisma not installed"
+
+# Check database provider
+grep "provider" prisma/schema.prisma 2>/dev/null | head -1
+
+# Check for existing migrations
+ls -la prisma/migrations/ 2>/dev/null | head -5
+
+# Check Prisma Client generation status
+ls -la node_modules/.prisma/client/ 2>/dev/null | head -3
+```
+
+### Apply Strategy
+1. Identify the Prisma-specific issue category
+2. Check for common anti-patterns in schema or queries
+3. Apply progressive fixes (minimal → better → complete)
+4. Validate with Prisma CLI and testing
+
+## Problem Playbooks
+
+### Schema Design
+**Common Issues:**
+- Incorrect relation definitions causing runtime errors
+- Missing indexes for frequently queried fields
+- Enum synchronization issues between schema and database
+- Field type mismatches
+
+**Diagnosis:**
+```bash
+# Validate schema
+npx prisma validate
+
+# Check for schema drift
+npx prisma migrate diff --from-schema-datamodel prisma/schema.prisma --to-schema-datasource prisma/schema.prisma
+
+# Format schema
+npx prisma format
+```
+
+**Prioritized Fixes:**
+1. **Minimal**: Fix relation annotations, add missing `@relation` directives
+2. **Better**: Add proper indexes with `@@index`, optimize field types
+3. **Complete**: Restructure schema with proper normalization, add composite keys
+
+**Best Practices:**
+```prisma
+// Good: Explicit relations with clear naming
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  posts     Post[]   @relation("UserPosts")
+  profile   Profile? @relation("UserProfile")
+  
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  
+  @@index([email])
+  @@map("users")
+}
+
+model Post {
+  id       String @id @default(cuid())
+  title    String
+  author   User   @relation("UserPosts", fields: [authorId], references: [id], onDelete: Cascade)
+  authorId String
+  
+  @@index([authorId])
+  @@map("posts")
+}
+```
+
+**Resources:**
+- https://www.prisma.io/docs/concepts/components/prisma-schema
+- https://www.prisma.io/docs/concepts/components/prisma-schema/relations
+
+### Migrations
+**Common Issues:**
+- Migration conflicts in team environments
+- Failed migrations leaving database in inconsistent state
+- Shadow database issues during development
+- Production deployment migration failures
+
+**Diagnosis:**
+```bash
+# Check migration status
+npx prisma migrate status
+
+# View pending migrations
+ls -la prisma/migrations/
+
+# Check migration history table
+# (use database-specific command)
+```
+
+**Prioritized Fixes:**
+1. **Minimal**: Reset development database with `prisma migrate reset`
+2. **Better**: Manually fix migration SQL, use `prisma migrate resolve`
+3. **Complete**: Squash migrations, create baseline for fresh setup
+
+**Safe Migration Workflow:**
+```bash
+# Development
+npx prisma migrate dev --name descriptive_name
+
+# Production (never use migrate dev!)
+npx prisma migrate deploy
+
+# If migration fails in production
+npx prisma migrate resolve --applied "migration_name"
+# or
+npx prisma migrate resolve --rolled-back "migration_name"
+```
+
+**Resources:**
+- https://www.prisma.io/docs/concepts/components/prisma-migrate
+- https://www.prisma.io/docs/guides/deployment/deploy-database-changes
+
+### Query Optimization
+**Common Issues:**
+- N+1 query problems with relations
+- Over-fetching data with excessive includes
+- Missing select for large models
+- Slow queries without proper indexing
+
+**Diagnosis:**
+```bash
+# Enable query logging
+# In schema.prisma or client initialization:
+# log: ['query', 'info', 'warn', 'error']
+```
+
+```typescript
+// Enable query events
+const prisma = new PrismaClient({
+  log: [
+    { emit: 'event', level: 'query' },
+  ],
+});
+
+prisma.$on('query', (e) => {
+  console.log('Query: ' + e.query);
+  console.log('Duration: ' + e.duration + 'ms');
+});
+```
+
+**Prioritized Fixes:**
+1. **Minimal**: Add includes for related data to avoid N+1
+2. **Better**: Use select to fetch only needed fields
+3. **Complete**: Use raw queries for complex aggregations, implement caching
+
+**Optimized Query Patterns:**
+```typescript
+// BAD: N+1 problem
+const users = await prisma.user.findMany();
+for (const user of users) {
+  const posts = await prisma.post.findMany({ where: { authorId: user.id } });
+}
+
+// GOOD: Include relations
+const users = await prisma.user.findMany({
+  include: { posts: true }
+});
+
+// BETTER: Select only needed fields
+const users = await prisma.user.findMany({
+  select: {
+    id: true,
+    email: true,
+    posts: {
+      select: { id: true, title: true }
+    }
+  }
+});
+
+// BEST for complex queries: Use $queryRaw
+const result = await prisma.$queryRaw`
+  SELECT u.id, u.email, COUNT(p.id) as post_count
+  FROM users u
+  LEFT JOIN posts p ON p.author_id = u.id
+  GROUP BY u.id
+`;
+```
+
+**Resources:**
+- https://www.prisma.io/docs/guides/performance-and-optimization
+- https://www.prisma.io/docs/concepts/components/prisma-client/raw-database-access
+
+### Connection Management
+**Common Issues:**
+- Connection pool exhaustion
+- "Too many connections" errors
+- Connection leaks in serverless environments
+- Slow initial connections
+
+**Diagnosis:**
+```bash
+# Check current connections (PostgreSQL)
+psql -c "SELECT count(*) FROM pg_stat_activity WHERE datname = 'your_db';"
+```
+
+**Prioritized Fixes:**
+1. **Minimal**: Configure connection limit in DATABASE_URL
+2. **Better**: Implement proper connection lifecycle management
+3. **Complete**: Use connection pooler (PgBouncer) for high-traffic apps
+
+**Connection Configuration:**
+```typescript
+// For serverless (Vercel, AWS Lambda)
+import { PrismaClient } from '@prisma/client';
+
+const globalForPrisma = global as unknown as { prisma: PrismaClient };
+
+export const prisma =
+  globalForPrisma.prisma ||
+  new PrismaClient({
+    log: process.env.NODE_ENV === 'development' ? ['query'] : [],
+  });
+
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
+
+// Graceful shutdown
+process.on('beforeExit', async () => {
+  await prisma.$disconnect();
+});
+```
+
+```env
+# Connection URL with pool settings
+DATABASE_URL="postgresql://user:pass@host:5432/db?connection_limit=5&pool_timeout=10"
+```
+
+**Resources:**
+- https://www.prisma.io/docs/guides/performance-and-optimization/connection-management
+- https://www.prisma.io/docs/guides/deployment/deployment-guides/deploying-to-vercel
+
+### Transaction Patterns
+**Common Issues:**
+- Inconsistent data from non-atomic operations
+- Deadlocks in concurrent transactions
+- Long-running transactions blocking reads
+- Nested transaction confusion
+
+**Diagnosis:**
+```typescript
+// Check for transaction issues
+try {
+  const result = await prisma.$transaction([...]);
+} catch (e) {
+  if (e.code === 'P2034') {
+    console.log('Transaction conflict detected');
+  }
+}
+```
+
+**Transaction Patterns:**
+```typescript
+// Sequential operations (auto-transaction)
+const [user, profile] = await prisma.$transaction([
+  prisma.user.create({ data: userData }),
+  prisma.profile.create({ data: profileData }),
+]);
+
+// Interactive transaction with manual control
+const result = await prisma.$transaction(async (tx) => {
+  const user = await tx.user.create({ data: userData });
+  
+  // Business logic validation
+  if (user.email.endsWith('@blocked.com')) {
+    throw new Error('Email domain blocked');
+  }
+  
+  const profile = await tx.profile.create({
+    data: { ...profileData, userId: user.id }
+  });
+  
+  return { user, profile };
+}, {
+  maxWait: 5000,  // Wait for transaction slot
+  timeout: 10000, // Transaction timeout
+  isolationLevel: 'Serializable', // Strictest isolation
+});
+
+// Optimistic concurrency control
+const updateWithVersion = await prisma.post.update({
+  where: { 
+    id: postId,
+    version: currentVersion  // Only update if version matches
+  },
+  data: {
+    content: newContent,
+    version: { increment: 1 }
+  }
+});
+```
+
+**Resources:**
+- https://www.prisma.io/docs/concepts/components/prisma-client/transactions
+
+## Code Review Checklist
+
+### Schema Quality
+- [ ] All models have appropriate `@id` and primary keys
+- [ ] Relations use explicit `@relation` with `fields` and `references`
+- [ ] Cascade behaviors defined (`onDelete`, `onUpdate`)
+- [ ] Indexes added for frequently queried fields
+- [ ] Enums used for fixed value sets
+- [ ] `@@map` used for table naming conventions
+
+### Query Patterns
+- [ ] No N+1 queries (relations included when needed)
+- [ ] `select` used to fetch only required fields
+- [ ] Pagination implemented for list queries
+- [ ] Raw queries used for complex aggregations
+- [ ] Proper error handling for database operations
+
+### Performance
+- [ ] Connection pooling configured appropriately
+- [ ] Indexes exist for WHERE clause fields
+- [ ] Composite indexes for multi-column queries
+- [ ] Query logging enabled in development
+- [ ] Slow queries identified and optimized
+
+### Migration Safety
+- [ ] Migrations tested before production deployment
+- [ ] Backward-compatible schema changes (no data loss)
+- [ ] Migration scripts reviewed for correctness
+- [ ] Rollback strategy documented
+
+## Anti-Patterns to Avoid
+
+1. **Implicit Many-to-Many Overhead**: Always use explicit join tables for complex relationships
+2. **Over-Including**: Don't include relations you don't need
+3. **Ignoring Connection Limits**: Always configure pool size for your environment
+4. **Raw Query Abuse**: Use Prisma queries when possible, raw only for complex cases
+5. **Migration in Production Dev Mode**: Never use `migrate dev` in production
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.