@vudovn/antigravity-kit 1.0.1

package/templates/.agent/skills/rest-api-expert/SKILL.md

@@ -0,0 +1,469 @@
+---
+name: rest-api-expert
+description: REST API design and development expert specializing in endpoint design, HTTP semantics, versioning, error handling, pagination, and OpenAPI documentation. Use PROACTIVELY for API architecture decisions, endpoint design issues, HTTP status code selection, or API documentation needs.
+---
+
+# REST API Expert
+
+You are an expert in REST API design and development with deep knowledge of HTTP semantics, resource modeling, versioning strategies, error handling, and API documentation.
+
+## When Invoked
+
+### Step 0: Recommend Specialist and Stop
+If the issue is specifically about:
+- **GraphQL APIs**: Stop and consider GraphQL patterns
+- **gRPC/Protocol Buffers**: Stop and recommend appropriate expert
+- **Authentication implementation**: Stop and recommend auth-expert
+- **Database query optimization**: Stop and recommend database-expert
+
+### Environment Detection
+```bash
+# Check for API framework
+grep -r "express\|fastify\|koa\|nestjs\|hono" package.json 2>/dev/null
+
+# Check for OpenAPI/Swagger
+ls -la swagger.* openapi.* 2>/dev/null
+find . -name "*.yaml" -o -name "*.json" | xargs grep -l "openapi" 2>/dev/null | head -3
+
+# Check existing API routes
+find . -type f \( -name "*.ts" -o -name "*.js" \) -path "*/routes/*" -o -path "*/controllers/*" | head -10
+```
+
+### Apply Strategy
+1. Identify the API design issue or requirement
+2. Apply RESTful principles and best practices
+3. Consider backward compatibility and versioning
+4. Validate with appropriate testing
+
+## Problem Playbooks
+
+### Endpoint Design
+**Common Issues:**
+- Non-RESTful URL patterns (verbs in URLs)
+- Inconsistent naming conventions
+- Poor resource hierarchy
+- Missing or unclear resource relationships
+
+**Prioritized Fixes:**
+1. **Minimal**: Rename endpoints to use nouns, not verbs
+2. **Better**: Restructure to proper resource hierarchy
+3. **Complete**: Implement full HATEOAS with links
+
+**RESTful URL Design:**
+```typescript
+// ❌ BAD: Verb-based endpoints
+GET    /getUsers
+POST   /createUser
+PUT    /updateUser/123
+DELETE /deleteUser/123
+GET    /getUserOrders/123
+
+// ✅ GOOD: Resource-based endpoints
+GET    /users              # List users
+POST   /users              # Create user
+GET    /users/123          # Get user
+PUT    /users/123          # Update user (full)
+PATCH  /users/123          # Update user (partial)
+DELETE /users/123          # Delete user
+GET    /users/123/orders   # User's orders (nested resource)
+
+// ✅ GOOD: Filtering, sorting, pagination
+GET    /users?status=active&sort=-createdAt&page=2&limit=20
+
+// ✅ GOOD: Search as sub-resource
+GET    /users/search?q=john&fields=name,email
+
+// ✅ GOOD: Actions as sub-resources (when needed)
+POST   /users/123/activate    # Action on resource
+POST   /orders/456/cancel     # State transition
+```
+
+**Resources:**
+- https://restfulapi.net/resource-naming/
+- https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
+
+### HTTP Methods & Status Codes
+**Common Issues:**
+- Using GET for state-changing operations
+- Inconsistent status code usage
+- Missing appropriate error codes
+- Ignoring idempotency
+
+**HTTP Methods Semantics:**
+```typescript
+// Method characteristics
+// GET     - Safe, Idempotent, Cacheable
+// POST    - Not Safe, Not Idempotent
+// PUT     - Not Safe, Idempotent
+// PATCH   - Not Safe, Not Idempotent
+// DELETE  - Not Safe, Idempotent
+
+// Express example with proper methods
+import { Router } from 'express';
+
+const router = Router();
+
+// GET - Retrieve resources (safe, idempotent)
+router.get('/products', listProducts);
+router.get('/products/:id', getProduct);
+
+// POST - Create resources (not idempotent)
+router.post('/products', createProduct);
+
+// PUT - Replace entire resource (idempotent)
+router.put('/products/:id', replaceProduct);
+
+// PATCH - Partial update (not idempotent typically)
+router.patch('/products/:id', updateProduct);
+
+// DELETE - Remove resource (idempotent)
+router.delete('/products/:id', deleteProduct);
+```
+
+**Status Code Guide:**
+```typescript
+// 2xx Success
+200 OK              // GET success, PUT/PATCH success with body
+201 Created         // POST success (include Location header)
+204 No Content      // DELETE success, PUT/PATCH success without body
+
+// 3xx Redirection
+301 Moved Permanently  // Resource URL changed permanently
+304 Not Modified       // Cached response is still valid
+
+// 4xx Client Errors
+400 Bad Request     // Invalid request body/params
+401 Unauthorized    // Missing or invalid authentication
+403 Forbidden       // Authenticated but not authorized
+404 Not Found       // Resource doesn't exist
+405 Method Not Allowed  // HTTP method not supported
+409 Conflict        // State conflict (e.g., duplicate)
+422 Unprocessable Entity  // Validation errors
+429 Too Many Requests    // Rate limit exceeded
+
+// 5xx Server Errors
+500 Internal Server Error  // Unexpected server error
+502 Bad Gateway           // Upstream service error
+503 Service Unavailable   // Temporary overload/maintenance
+```
+
+### Error Handling
+**Common Issues:**
+- Inconsistent error response formats
+- Exposing internal error details
+- Missing error codes for client handling
+- No error documentation
+
+**Standard Error Response Format:**
+```typescript
+// Error response structure
+interface ApiError {
+  status: number;          // HTTP status code
+  code: string;            // Application-specific error code
+  message: string;         // Human-readable message
+  details?: ErrorDetail[]; // Field-level errors (for validation)
+  requestId?: string;      // For debugging/support
+  timestamp?: string;      // ISO 8601
+}
+
+interface ErrorDetail {
+  field: string;
+  message: string;
+  code: string;
+}
+
+// Example responses
+// 400 Bad Request - Validation Error
+{
+  "status": 400,
+  "code": "VALIDATION_ERROR",
+  "message": "Request validation failed",
+  "details": [
+    { "field": "email", "message": "Invalid email format", "code": "INVALID_EMAIL" },
+    { "field": "age", "message": "Must be at least 18", "code": "MIN_VALUE" }
+  ],
+  "requestId": "req_abc123",
+  "timestamp": "2024-01-15T10:30:00Z"
+}
+
+// 404 Not Found
+{
+  "status": 404,
+  "code": "RESOURCE_NOT_FOUND",
+  "message": "User with ID '123' not found",
+  "requestId": "req_def456",
+  "timestamp": "2024-01-15T10:30:00Z"
+}
+
+// 500 Internal Server Error
+{
+  "status": 500,
+  "code": "INTERNAL_ERROR",
+  "message": "An unexpected error occurred. Please try again later.",
+  "requestId": "req_ghi789",
+  "timestamp": "2024-01-15T10:30:00Z"
+}
+```
+
+**Error Handling Middleware:**
+```typescript
+// Express error handler
+import { Request, Response, NextFunction } from 'express';
+
+class AppError extends Error {
+  constructor(
+    public status: number,
+    public code: string,
+    message: string,
+    public details?: ErrorDetail[]
+  ) {
+    super(message);
+  }
+}
+
+function errorHandler(
+  err: Error,
+  req: Request,
+  res: Response,
+  next: NextFunction
+) {
+  const requestId = req.headers['x-request-id'] || generateRequestId();
+  
+  if (err instanceof AppError) {
+    return res.status(err.status).json({
+      status: err.status,
+      code: err.code,
+      message: err.message,
+      details: err.details,
+      requestId,
+      timestamp: new Date().toISOString(),
+    });
+  }
+  
+  // Log unexpected errors
+  console.error('Unexpected error:', err);
+  
+  // Don't expose internal errors to clients
+  return res.status(500).json({
+    status: 500,
+    code: 'INTERNAL_ERROR',
+    message: 'An unexpected error occurred',
+    requestId,
+    timestamp: new Date().toISOString(),
+  });
+}
+```
+
+### Pagination
+**Common Issues:**
+- Inconsistent pagination parameters
+- Missing total count for UI
+- No cursor-based option for large datasets
+- Performance issues with offset pagination
+
+**Pagination Strategies:**
+```typescript
+// 1. Offset-based pagination (simple, but slow for large offsets)
+GET /products?page=2&limit=20
+
+{
+  "data": [...],
+  "pagination": {
+    "page": 2,
+    "limit": 20,
+    "total": 150,
+    "totalPages": 8,
+    "hasNext": true,
+    "hasPrev": true
+  }
+}
+
+// 2. Cursor-based pagination (efficient for large datasets)
+GET /products?cursor=eyJpZCI6MTAwfQ&limit=20
+
+{
+  "data": [...],
+  "pagination": {
+    "limit": 20,
+    "nextCursor": "eyJpZCI6MTIwfQ",
+    "prevCursor": "eyJpZCI6ODB9",
+    "hasNext": true,
+    "hasPrev": true
+  }
+}
+
+// Implementation example
+async function paginateWithCursor(
+  cursor: string | null,
+  limit: number = 20
+) {
+  const decodedCursor = cursor 
+    ? JSON.parse(Buffer.from(cursor, 'base64').toString())
+    : null;
+    
+  const items = await prisma.product.findMany({
+    take: limit + 1, // Fetch one extra to check hasNext
+    cursor: decodedCursor ? { id: decodedCursor.id } : undefined,
+    skip: decodedCursor ? 1 : 0,
+    orderBy: { id: 'asc' },
+  });
+  
+  const hasNext = items.length > limit;
+  const data = hasNext ? items.slice(0, -1) : items;
+  
+  return {
+    data,
+    pagination: {
+      limit,
+      nextCursor: hasNext 
+        ? Buffer.from(JSON.stringify({ id: data[data.length - 1].id })).toString('base64')
+        : null,
+      hasNext,
+    },
+  };
+}
+```
+
+### API Versioning
+**Common Issues:**
+- No versioning strategy
+- Breaking changes without version bump
+- Inconsistent versioning across endpoints
+- No deprecation communication
+
+**Versioning Strategies:**
+```typescript
+// 1. URL Path Versioning (recommended)
+GET /api/v1/users
+GET /api/v2/users
+
+// Implementation
+import { Router } from 'express';
+
+const v1Router = Router();
+const v2Router = Router();
+
+// V1 routes
+v1Router.get('/users', getUsersV1);
+
+// V2 routes with breaking changes
+v2Router.get('/users', getUsersV2);
+
+app.use('/api/v1', v1Router);
+app.use('/api/v2', v2Router);
+
+// 2. Header Versioning
+GET /api/users
+Accept: application/vnd.myapi.v2+json
+
+// 3. Query Parameter (not recommended for APIs)
+GET /api/users?version=2
+```
+
+**Deprecation Headers:**
+```typescript
+// Communicate deprecation
+res.setHeader('Deprecation', 'true');
+res.setHeader('Sunset', 'Sat, 01 Jun 2025 00:00:00 GMT');
+res.setHeader('Link', '</api/v2/users>; rel="successor-version"');
+```
+
+### Request/Response Design
+**Common Issues:**
+- Inconsistent field naming (camelCase vs snake_case)
+- Missing content type headers
+- No request validation
+- Overly verbose responses
+
+**Request/Response Best Practices:**
+```typescript
+// Consistent naming convention (pick one, stick to it)
+// JavaScript/TypeScript typically uses camelCase
+
+// Request validation with Zod
+import { z } from 'zod';
+
+const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).max(100),
+  age: z.number().int().min(18).optional(),
+  role: z.enum(['user', 'admin']).default('user'),
+});
+
+// Validate in middleware
+function validate(schema: z.ZodSchema) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    try {
+      req.body = schema.parse(req.body);
+      next();
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        return res.status(400).json({
+          status: 400,
+          code: 'VALIDATION_ERROR',
+          message: 'Request validation failed',
+          details: error.errors.map(e => ({
+            field: e.path.join('.'),
+            message: e.message,
+            code: e.code,
+          })),
+        });
+      }
+      next(error);
+    }
+  };
+}
+
+// Response envelope for consistency
+interface ApiResponse<T> {
+  data: T;
+  meta?: {
+    pagination?: PaginationInfo;
+    [key: string]: any;
+  };
+}
+
+// Partial responses (field selection)
+GET /users/123?fields=id,name,email
+```
+
+## Code Review Checklist
+
+### Endpoint Design
+- [ ] URLs use nouns, not verbs
+- [ ] Consistent naming convention (kebab-case or snake_case)
+- [ ] Proper resource hierarchy
+- [ ] No deeply nested resources (max 2 levels)
+
+### HTTP Semantics
+- [ ] Correct HTTP methods for operations
+- [ ] Appropriate status codes
+- [ ] Idempotency for PUT/DELETE
+- [ ] Safe methods (GET) don't modify state
+
+### Error Handling
+- [ ] Consistent error response format
+- [ ] Meaningful error codes
+- [ ] Validation errors include field details
+- [ ] No internal errors exposed to clients
+
+### Performance
+- [ ] Pagination for list endpoints
+- [ ] Field selection supported
+- [ ] Appropriate caching headers
+- [ ] Rate limiting implemented
+
+### Documentation
+- [ ] OpenAPI/Swagger spec up to date
+- [ ] Examples for all endpoints
+- [ ] Error codes documented
+- [ ] Deprecation warnings for old versions
+
+## Anti-Patterns to Avoid
+
+1. **RPC-style URLs**: `/createUser`, `/updateProduct` → Use nouns with HTTP methods
+2. **Ignoring HTTP Semantics**: Using POST for everything
+3. **Exposing Internal IDs**: Use UUIDs or opaque IDs instead of auto-increment
+4. **Overfetching**: Return only requested/needed fields
+5. **Version in Response Body**: Version in URL is cleaner
+6. **Tight Coupling**: API should be independent of frontend implementation

package/templates/.agent/skills/state-management-expert/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: state-management-expert
+description: Expert in React state management including Redux Toolkit, Zustand, Jotai, React Query/TanStack Query, and Context API. Use for state architecture decisions, performance issues, or complex state logic.
+---
+
+# State Management Expert
+
+Expert in React state management patterns and libraries.
+
+## When Invoked
+
+### Recommend Specialist
+- **React component issues**: recommend react-expert
+- **Performance profiling**: recommend react-performance-expert
+- **API data fetching only**: recommend rest-api-expert
+
+### Environment Detection
+```bash
+grep -E "redux|zustand|jotai|recoil|@tanstack/react-query" package.json 2>/dev/null
+find . -name "store*" -o -name "*slice*" | head -5
+```
+
+## State Management Decision Tree
+
+```
+State Type?
+├─ Server State (API data) → TanStack Query / SWR
+├─ Global UI State → Zustand / Redux Toolkit
+├─ Form State → React Hook Form / Formik
+├─ URL State → nuqs / useSearchParams
+└─ Local State → useState / useReducer
+```
+
+## Problem Playbooks
+
+### Zustand (Recommended for most apps)
+
+```typescript
+import { create } from 'zustand';
+import { devtools, persist } from 'zustand/middleware';
+
+interface UserStore {
+  user: User | null;
+  setUser: (user: User | null) => void;
+  logout: () => void;
+}
+
+export const useUserStore = create<UserStore>()(
+  devtools(
+    persist(
+      (set) => ({
+        user: null,
+        setUser: (user) => set({ user }),
+        logout: () => set({ user: null }),
+      }),
+      { name: 'user-store' }
+    )
+  )
+);
+
+// Usage
+function Component() {
+  const user = useUserStore((state) => state.user);
+  const setUser = useUserStore((state) => state.setUser);
+}
+```
+
+### Redux Toolkit
+
+```typescript
+import { createSlice, configureStore } from '@reduxjs/toolkit';
+
+const counterSlice = createSlice({
+  name: 'counter',
+  initialState: { value: 0 },
+  reducers: {
+    increment: (state) => { state.value += 1; },
+    decrement: (state) => { state.value -= 1; },
+  },
+});
+
+export const store = configureStore({
+  reducer: { counter: counterSlice.reducer },
+});
+
+export const { increment, decrement } = counterSlice.actions;
+```
+
+### TanStack Query (Server State)
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+function usePosts() {
+  return useQuery({
+    queryKey: ['posts'],
+    queryFn: () => fetch('/api/posts').then(r => r.json()),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+  });
+}
+
+function useCreatePost() {
+  const queryClient = useQueryClient();
+  
+  return useMutation({
+    mutationFn: (data: CreatePostDto) => 
+      fetch('/api/posts', {
+        method: 'POST',
+        body: JSON.stringify(data),
+      }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['posts'] });
+    },
+  });
+}
+```
+
+### Context API (Simple cases)
+
+```typescript
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState<'light' | 'dark'>('light');
+  
+  const value = useMemo(() => ({ theme, setTheme }), [theme]);
+  
+  return (
+    <ThemeContext.Provider value={value}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  const context = useContext(ThemeContext);
+  if (!context) throw new Error('useTheme must be within ThemeProvider');
+  return context;
+}
+```
+
+## Code Review Checklist
+
+- [ ] Server state uses TanStack Query or SWR
+- [ ] No prop drilling >2 levels
+- [ ] Selectors used for derived state
+- [ ] State normalized (no duplicates)
+- [ ] Optimistic updates for mutations
+- [ ] Loading/error states handled
+
+## Anti-Patterns
+
+1. **Storing server data in Redux** - Use React Query
+2. **Global state for local concerns** - Use useState
+3. **Over-fetching with Context** - Split contexts
+4. **Missing selectors** - Causes unnecessary re-renders
+5. **Duplicate state** - Single source of truth