@torka/claude-workflows 0.7.1 → 0.9.0

package/skills/agent-creator/expertise/backend-api.md

@@ -0,0 +1,161 @@
+# Backend API Expertise Profile
+
+Use this profile for agents that build API routes, handle authentication, implement validation, and manage server-side logic.
+
+---
+
+## Trigger Keywords
+
+### High Signal (strongly suggests this profile)
+- `API`, `endpoint`, `route`, `middleware`, `auth`
+- `validation`, `Zod`, `request`, `response`
+- `error handling`, `401`, `403`, `500`
+
+### Medium Signal (consider this profile)
+- `backend`, `server`, `service`, `handler`
+- `session`, `token`, `cookie`, `CORS`
+- `rate limit`, `security`, `sanitize`
+
+---
+
+## Core Competencies
+
+1. **API Design** - RESTful patterns, consistent response formats, proper HTTP status codes
+2. **Authentication/Authorization** - Session validation, role checks, secure token handling
+3. **Input Validation** - Zod schemas, sanitization, error messages
+4. **Error Handling** - Structured error responses, proper status codes, logging
+5. **Security Practices** - CSRF protection, input sanitization, secrets management
+
+---
+
+## Typical Tasks
+
+- Create new API routes with validation
+- Add authentication checks to existing endpoints
+- Implement proper error handling with structured responses
+- Add rate limiting or other middleware
+- Integrate with external APIs (proxy pattern)
+- Handle file uploads securely
+- Build webhook handlers
+
+---
+
+## Quality Markers
+
+What separates good backend work:
+
+| Marker | What It Means |
+|--------|---------------|
+| **Consistent error format** | All errors use the same structure |
+| **Input validation first** | Validate before any business logic |
+| **Proper status codes** | 400 for client errors, 500 for server errors |
+| **No leaked secrets** | API keys never in responses or logs |
+| **Typed responses** | TypeScript types for request/response |
+| **Idempotency awareness** | Safe retry behavior for POST/PUT |
+
+---
+
+## Anti-Patterns
+
+Common mistakes to avoid:
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| Returning raw error messages | Use structured error responses |
+| 200 OK for errors | Use proper HTTP status codes |
+| Auth checks scattered | Centralize in middleware |
+| No input validation | Validate with Zod at entry |
+| Exposing internal errors | Map to safe error codes |
+| Hardcoded API keys | Use environment variables |
+| Missing rate limits | Add for public endpoints |
+
+---
+
+## Tool Affinities
+
+### Required MCPs
+None required - backend work uses core tools.
+
+### Optional MCPs
+| MCP | Usage |
+|-----|-------|
+| **Context7** | Query Supabase/Next.js API docs |
+
+### Core Tools
+- `Read` - Check existing API patterns
+- `Grep` - Find auth/validation patterns
+- `Bash` - Test endpoints with curl
+- `Write/Edit` - Create/modify routes
+
+---
+
+## Tech Stack (This Project)
+
+| Technology | Usage | Notes |
+|------------|-------|-------|
+| **Next.js Route Handlers** | API routes | In `src/app/api/` |
+| **Supabase Auth** | Authentication | Server client in `src/libs/supabase/server.ts` |
+| **Zod** | Validation | Schema + error formatting |
+| **API Error Utils** | Error handling | In `src/libs/api/errors.ts` |
+
+### Key Paths
+- API routes: `src/app/api/`
+- Supabase client: `src/libs/supabase/`
+- Error utilities: `src/libs/api/errors.ts`
+- Client utilities: `src/libs/api/client.ts`
+
+### Error Response Format
+```typescript
+// From src/libs/api/errors.ts
+{
+  error: {
+    code: 'AUTH_REQUIRED' | 'VALIDATION_ERROR' | 'NOT_FOUND' | 'INTERNAL_ERROR',
+    message: string,
+    details?: Record<string, string[]>  // For validation errors
+  }
+}
+```
+
+### Authentication Pattern
+```typescript
+// Standard auth check for API routes
+import { cookies } from 'next/headers';
+import { createClient } from '@/libs/supabase/server';
+import { unauthorizedError } from '@/libs/api/errors';
+
+export async function GET(request: Request) {
+  const cookieStore = await cookies();
+  const supabase = createClient(cookieStore);
+  const { data: { user } } = await supabase.auth.getUser();
+
+  if (!user) {
+    return unauthorizedError();
+  }
+
+  // Proceed with authenticated logic
+}
+```
+
+---
+
+## Example Agent Persona Snippet
+
+```markdown
+You are a backend API specialist with deep expertise in:
+- Building secure Next.js API routes with proper validation
+- Implementing authentication flows with Supabase
+- Creating consistent error handling with structured responses
+- Managing secrets and environment configuration
+
+You prioritize:
+- Input validation at every entry point (Zod schemas)
+- Consistent error response format (code, message, details)
+- Proper HTTP status codes (400 client, 500 server)
+- Never exposing internal errors or secrets
+
+You avoid:
+- Auth checks scattered across routes (centralize in middleware)
+- Returning 200 OK for errors (use proper status codes)
+- Exposing raw error messages (map to safe codes)
+- Hardcoded credentials (always use env vars)
+```

package/skills/agent-creator/expertise/database-orm.md

@@ -0,0 +1,181 @@
+# Database/ORM Expertise Profile
+
+Use this profile for agents that design schemas, write migrations, build queries, and manage data layer concerns.
+
+---
+
+## Trigger Keywords
+
+### High Signal (strongly suggests this profile)
+- `schema`, `migration`, `Drizzle`, `table`
+- `query`, `relation`, `foreign key`, `index`
+- `database`, `PostgreSQL`, `ORM`
+
+### Medium Signal (consider this profile)
+- `data`, `model`, `entity`, `record`
+- `join`, `transaction`, `constraint`
+- `seed`, `fixture`, `backup`
+
+---
+
+## Core Competencies
+
+1. **Schema Design** - Normalization, relationships, constraints, indexes
+2. **Migration Management** - Safe migrations, rollback strategies, data preservation
+3. **Query Optimization** - Efficient queries, N+1 avoidance, proper joins
+4. **Drizzle ORM** - Type-safe queries, relations, schema definition
+5. **Data Integrity** - Constraints, transactions, validation at DB level
+
+---
+
+## Typical Tasks
+
+- Design new database tables with proper relationships
+- Write migrations for schema changes
+- Build complex queries with joins/aggregations
+- Add indexes for performance
+- Set up seed data for development
+- Implement soft deletes or audit columns
+- Optimize slow queries
+
+---
+
+## Quality Markers
+
+What separates good database work:
+
+| Marker | What It Means |
+|--------|---------------|
+| **Proper normalization** | No redundant data, clear relationships |
+| **Meaningful names** | Tables/columns describe their purpose |
+| **Foreign key constraints** | Referential integrity enforced |
+| **Indexes on queries** | Indexes match common query patterns |
+| **Safe migrations** | Non-destructive, can rollback |
+| **Type-safe queries** | Drizzle types match schema |
+
+---
+
+## Anti-Patterns
+
+Common mistakes to avoid:
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| No foreign keys | Always define relationships |
+| Missing indexes | Index columns used in WHERE/JOIN |
+| Destructive migrations | Preserve data, add not remove |
+| Raw SQL everywhere | Use Drizzle's type-safe query builder |
+| N+1 queries | Use joins or batch queries |
+| No timestamps | Add created_at/updated_at columns |
+| Hardcoded IDs | Use proper foreign key references |
+
+---
+
+## Tool Affinities
+
+### Required MCPs
+None required - database work uses core tools.
+
+### Optional MCPs
+| MCP | Usage |
+|-----|-------|
+| **Context7** | Query Drizzle ORM docs |
+
+### Core Tools
+- `Read` - Check existing schema
+- `Grep` - Find query patterns, relations
+- `Bash` - Run migrations, open studio
+- `Write/Edit` - Modify schema
+
+---
+
+## Tech Stack (This Project)
+
+| Technology | Usage | Notes |
+|------------|-------|-------|
+| **Drizzle ORM** | Query builder | Type-safe, lightweight |
+| **PostgreSQL** | Database | Via Supabase or direct |
+| **drizzle-kit** | Migrations | Generate + apply |
+| **PGlite** | Local dev | Optional offline mode |
+
+### Key Paths
+- Schema: `src/models/Schema.ts`
+- DB client: `src/libs/DB.ts`
+- Migrations: `drizzle/` directory
+- Config: `drizzle.config.ts`
+
+### Database Commands
+```bash
+# Generate migration from schema changes
+npm run db:generate
+
+# Apply migrations (auto-runs on app start)
+npm run db:migrate
+
+# Open Drizzle Studio (visual DB browser)
+npm run db:studio
+```
+
+### Schema Pattern (Drizzle)
+```typescript
+// src/models/Schema.ts
+import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
+
+export const users = pgTable('users', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  email: text('email').notNull().unique(),
+  name: text('name'),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+});
+
+export const posts = pgTable('posts', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  title: text('title').notNull(),
+  content: text('content'),
+  authorId: uuid('author_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade' }),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+});
+```
+
+### Query Pattern
+```typescript
+import { db } from '@/libs/DB';
+import { users, posts } from '@/models/Schema';
+import { eq } from 'drizzle-orm';
+
+// Simple query
+const user = await db.select().from(users).where(eq(users.id, userId));
+
+// With join
+const postsWithAuthors = await db
+  .select()
+  .from(posts)
+  .leftJoin(users, eq(posts.authorId, users.id));
+```
+
+---
+
+## Example Agent Persona Snippet
+
+```markdown
+You are a database specialist with deep expertise in:
+- Designing normalized schemas with proper relationships
+- Writing safe, reversible migrations
+- Building efficient queries with Drizzle ORM
+- Optimizing performance with appropriate indexes
+
+You prioritize:
+- Data integrity (foreign keys, constraints)
+- Type safety (Drizzle's type-safe queries)
+- Performance (indexes on queried columns)
+- Safe migrations (non-destructive changes)
+
+You avoid:
+- Missing foreign key relationships
+- N+1 query patterns (use joins)
+- Destructive migrations without data preservation
+- Raw SQL when Drizzle's query builder suffices
+```

package/skills/agent-creator/expertise/devops-ci.md

@@ -0,0 +1,211 @@
+# DevOps/CI Expertise Profile
+
+Use this profile for agents that manage CI/CD pipelines, deployment, environment configuration, and infrastructure concerns.
+
+---
+
+## Trigger Keywords
+
+### High Signal (strongly suggests this profile)
+- `deploy`, `CI`, `CD`, `pipeline`, `GitHub Actions`
+- `Docker`, `container`, `build`, `release`
+- `secret`, `env`, `environment variable`
+
+### Medium Signal (consider this profile)
+- `workflow`, `automation`, `script`
+- `staging`, `production`, `preview`
+- `cache`, `artifact`, `matrix`
+
+---
+
+## Core Competencies
+
+1. **GitHub Actions** - Workflow syntax, triggers, jobs, steps, matrix builds
+2. **Environment Management** - Secrets, env vars, per-environment config
+3. **Deployment Strategies** - Preview deploys, staging, production rollouts
+4. **Build Optimization** - Caching, parallelization, conditional steps
+5. **Security Practices** - Secret handling, least privilege, audit logs
+
+---
+
+## Typical Tasks
+
+- Set up or modify CI/CD pipelines
+- Add new environment variables or secrets
+- Configure preview deployments
+- Optimize build times with caching
+- Add quality gates (lint, test, type-check)
+- Set up branch protection rules
+- Debug failing CI builds
+
+---
+
+## Quality Markers
+
+What separates good DevOps work:
+
+| Marker | What It Means |
+|--------|---------------|
+| **Fast feedback** | CI runs quickly (< 5 min ideal) |
+| **Deterministic builds** | Same input = same output |
+| **Proper secret handling** | Never in logs, proper scoping |
+| **Clear job dependencies** | Jobs run in logical order |
+| **Useful failure messages** | Easy to diagnose failures |
+| **Caching effective** | Dependencies cached properly |
+
+---
+
+## Anti-Patterns
+
+Common mistakes to avoid:
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| Secrets in code | Use GitHub Secrets / env vars |
+| No caching | Cache node_modules, build artifacts |
+| Sequential when parallel OK | Use `needs` only when required |
+| Hardcoded versions | Use version variables or matrices |
+| No branch protection | Require CI pass before merge |
+| Verbose logs with secrets | Use `::add-mask::` for sensitive values |
+| Manual deployments | Automate via CD pipeline |
+
+---
+
+## Tool Affinities
+
+### Required MCPs
+None required - DevOps work uses core tools.
+
+### Optional MCPs
+| MCP | Usage |
+|-----|-------|
+| **Context7** | Query GitHub Actions docs |
+
+### Core Tools
+- `Read` - Check workflow files, configs
+- `Glob` - Find all workflow files
+- `Grep` - Find env var usage, secret refs
+- `Bash` - Test commands locally, gh CLI
+- `Write/Edit` - Modify workflows
+
+---
+
+## Tech Stack (This Project)
+
+| Technology | Usage | Notes |
+|------------|-------|-------|
+| **GitHub Actions** | CI/CD | In `.github/workflows/` |
+| **Vercel** | Deployment | Preview + Production |
+| **Node.js 20** | Runtime | Specified in workflows |
+| **pnpm** | Package manager | Or npm depending on project |
+
+### Key Paths
+- Workflows: `.github/workflows/`
+- Environment: `.env.example`, `.env.local`
+- Vercel config: `vercel.json` (if exists)
+
+### CI Commands (Run Locally)
+```bash
+# Full CI check (same as pipeline)
+npm run lint && npm run check-types && npm test && npm run build
+
+# Individual checks
+npm run lint          # ESLint
+npm run check-types   # TypeScript
+npm test              # Vitest
+npm run build         # Next.js build
+npm run test:e2e      # Playwright (requires build)
+```
+
+### Required GitHub Secrets
+```
+DIFY_API_KEY
+DIFY_API_URL
+NEXT_PUBLIC_SUPABASE_URL
+NEXT_PUBLIC_SUPABASE_ANON_KEY
+SUPABASE_SERVICE_ROLE_KEY
+```
+
+### Workflow Pattern (GitHub Actions)
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run lint
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run check-types
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test
+
+  build:
+    needs: [lint, type-check, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+        env:
+          NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.NEXT_PUBLIC_SUPABASE_URL }}
+          NEXT_PUBLIC_SUPABASE_ANON_KEY: ${{ secrets.NEXT_PUBLIC_SUPABASE_ANON_KEY }}
+```
+
+---
+
+## Example Agent Persona Snippet
+
+```markdown
+You are a DevOps specialist with deep expertise in:
+- Building efficient GitHub Actions workflows
+- Managing environment variables and secrets securely
+- Configuring deployment pipelines with Vercel
+- Optimizing CI/CD for fast feedback loops
+
+You prioritize:
+- Fast CI runs (caching, parallelization)
+- Secure secret handling (never in logs)
+- Clear job dependencies (explicit `needs`)
+- Useful failure messages (easy debugging)
+
+You avoid:
+- Secrets in code or logs (use GitHub Secrets)
+- Sequential jobs when parallel is safe
+- Hardcoded versions (use variables)
+- Skipping quality gates (lint, test, build)
+```

package/skills/agent-creator/expertise/nextjs-fullstack.md

@@ -0,0 +1,159 @@
+# Next.js Full-Stack Expertise Profile
+
+Use this profile for agents that work with App Router features, Server Components, Server Actions, and full-page implementations.
+
+---
+
+## Trigger Keywords
+
+### High Signal (strongly suggests this profile)
+- `page`, `layout`, `App Router`, `Server Component`
+- `Server Action`, `loading.tsx`, `error.tsx`
+- `generateMetadata`, `dynamic`, `revalidate`
+
+### Medium Signal (consider this profile)
+- `fullstack`, `feature`, `route`, `navigation`
+- `SSR`, `streaming`, `Suspense`, `RSC`
+- `redirect`, `notFound`, `middleware`
+
+---
+
+## Core Competencies
+
+1. **App Router Architecture** - Layouts, pages, route groups, parallel routes
+2. **Server/Client Boundary** - When to use 'use client', data fetching patterns
+3. **Server Actions** - Form handling, mutations, revalidation
+4. **Metadata & SEO** - Dynamic metadata, Open Graph, structured data
+5. **Error Handling** - error.tsx, loading.tsx, not-found.tsx patterns
+
+---
+
+## Typical Tasks
+
+- Create new pages with proper metadata and SEO
+- Implement layouts with shared navigation/sidebars
+- Build Server Actions for form submissions
+- Add loading and error states to routes
+- Set up protected routes with auth checks
+- Implement data fetching with proper caching
+- Add internationalization to new routes
+
+---
+
+## Quality Markers
+
+What separates good full-stack work:
+
+| Marker | What It Means |
+|--------|---------------|
+| **Proper server/client split** | Logic on server, interactivity on client |
+| **Loading states** | Every async route has loading.tsx |
+| **Error boundaries** | error.tsx at appropriate levels |
+| **Metadata present** | Pages have title, description, OG tags |
+| **i18n support** | Uses next-intl for all text |
+| **Route grouping** | Logical grouping with (auth), (unauth) |
+
+---
+
+## Anti-Patterns
+
+Common mistakes to avoid:
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| 'use client' everywhere | Default to Server Components |
+| Fetching in useEffect | Fetch in Server Components |
+| Giant page components | Extract to smaller components |
+| Missing loading states | Add loading.tsx to async routes |
+| Hardcoded strings | Use next-intl translations |
+| No metadata | Add generateMetadata to pages |
+| Auth in every page | Handle in middleware |
+
+---
+
+## Tool Affinities
+
+### Required MCPs
+| MCP | Usage |
+|-----|-------|
+| **Playwright** | Full-page testing and screenshots |
+
+### Optional MCPs
+| MCP | Usage |
+|-----|-------|
+| **Context7** | Query Next.js App Router docs |
+| **shadcn** | Component integration in pages |
+
+### Core Tools
+- `Read` - Check existing page patterns
+- `Glob` - Find layouts, pages, route groups
+- `Grep` - Find metadata, Server Action patterns
+- `Write/Edit` - Create/modify routes
+
+---
+
+## Tech Stack (This Project)
+
+| Technology | Usage | Notes |
+|------------|-------|-------|
+| **Next.js 15** | Framework | App Router with async params |
+| **TypeScript** | Type safety | Strict mode enabled |
+| **next-intl** | i18n | Locale in URL path |
+| **Supabase** | Auth + DB | Session in middleware |
+
+### Key Paths
+- Pages: `src/app/[locale]/`
+- Layouts: `src/app/[locale]/layout.tsx`
+- Route groups: `(auth)/`, `(unauth)/`, `(chat)/`
+- Middleware: `src/middleware.ts`
+- Config: `src/utils/AppConfig.ts`
+
+### Route Group Structure
+```
+src/app/[locale]/
+├── (auth)/           # Protected routes (dashboard, settings)
+├── (unauth)/         # Public routes (sign-in, sign-up)
+├── (chat)/           # Chat interface
+├── layout.tsx        # Root layout with providers
+└── page.tsx          # Landing page
+```
+
+### Next.js 15 Async Params
+```typescript
+// IMPORTANT: params are now Promises in Next.js 15
+export default async function Page(props: {
+  params: Promise<{ locale: string; id: string }>;
+}) {
+  const { locale, id } = await props.params;
+  // use locale and id
+}
+```
+
+### Adding Protected Routes
+1. Add path to `protectedPaths` in `src/middleware.ts`
+2. Create route in `src/app/[locale]/(auth)/`
+3. Add loading.tsx and error.tsx as needed
+
+---
+
+## Example Agent Persona Snippet
+
+```markdown
+You are a Next.js full-stack specialist with deep expertise in:
+- Building pages with App Router (layouts, route groups, async params)
+- Implementing Server Components and Server Actions
+- Managing the server/client boundary effectively
+- Adding proper metadata, loading states, and error handling
+
+You prioritize:
+- Server Components by default (client only when interactive)
+- Loading and error states for every async route
+- Proper metadata for SEO
+- Translation support via next-intl
+
+You avoid:
+- 'use client' on components that don't need it
+- useEffect for data fetching (use Server Components)
+- Missing loading.tsx files for async routes
+- Hardcoded strings (use translations)
+```