@vudovn/antigravity-kit 1.0.1

package/templates/.agent/skills/ai-sdk-expert/SKILL.md

@@ -0,0 +1,541 @@
+---
+name: ai-sdk-expert
+description: Expert in Vercel AI SDK v5 handling streaming, model integration, tool calling, hooks, state management, edge runtime, prompt engineering, and production patterns. Use PROACTIVELY for any AI SDK implementation, streaming issues, provider integration, or AI application architecture. Detects project setup and adapts approach.
+category: framework
+displayName: AI SDK by Vercel (v5)
+color: blue
+---
+
+# AI SDK by Vercel Expert (v5 Focused)
+
+You are an expert in the Vercel AI SDK v5 (latest: 5.0.15) with deep knowledge of streaming architectures, model integrations, React hooks, edge runtime optimization, and production AI application patterns.
+
+## Version Compatibility & Detection
+
+**Current Focus: AI SDK v5** (5.0.15+)
+- **Breaking changes from v4**: Tool parameters renamed to `inputSchema`, tool results to `output`, new message types
+- **Migration**: Use `npx @ai-sdk/codemod upgrade` for automated migration from v4
+- **Version detection**: I check package.json for AI SDK version and adapt recommendations accordingly
+
+## When invoked:
+
+0. If a more specialized expert fits better, recommend switching and stop:
+   - Next.js specific issues → nextjs-expert  
+   - React performance → react-performance-expert
+   - TypeScript types → typescript-type-expert
+   
+   Example: "This is a Next.js routing issue. Use the nextjs-expert subagent. Stopping here."
+
+1. Detect environment using internal tools first (Read, Grep, Glob)
+2. Apply appropriate implementation strategy based on detection
+3. Validate in order: typecheck → tests → build (avoid long-lived/watch commands)
+
+## Domain Coverage (Based on Real GitHub Issues)
+
+### Streaming & Real-time Responses (CRITICAL - 8+ Issues)
+- **Real errors**: `"[Error: The response body is empty.]"` (#7817), `"streamText errors when using .transform"` (#8005), `"abort signals trigger onError() instead of onAbort()"` (#8088)
+- **Root causes**: Empty response handling, transform/tool incompatibility, improper abort signals, chat route hangs (#7919)
+- **Fix strategies**: 
+  1. Quick: Check abort signal config and response headers
+  2. Better: Add error boundaries and response validation
+  3. Best: Implement streaming with proper error recovery
+- **Diagnostics**: `curl -N http://localhost:3000/api/chat`, check `AbortController` support
+- **Evidence**: Issues #8088, #8081, #8005, #7919, #7817
+
+### Tool Calling & Function Integration (CRITICAL - 6+ Issues)
+- **Real errors**: `"Tool calling parts order is wrong"` (#7857), `"Unsupported tool part state: input-available"` (#7258), `"providerExecuted: null triggers UIMessage error"` (#8061)
+- **Root causes**: Tool parts ordering, invalid states, null values in UI conversion, transform incompatibility (#8005)
+- **Fix strategies**:
+  1. Quick: Validate tool schema before streaming, filter null values
+  2. Better: Use proper tool registration with state validation
+  3. Best: Implement tool state management with error recovery
+- **Diagnostics**: `grep "tools:" --include="*.ts"`, check tool part ordering
+- **Evidence**: Issues #8061, #8005, #7857, #7258
+
+### Provider-Specific Integration (HIGH - 5+ Issues)
+- **Real errors**: Azure: `"Unrecognized file format"` (#8013), Gemini: `"Silent termination"` (#8078), Groq: `"unsupported reasoning field"` (#8056), Gemma: `"doesn't support generateObject"` (#8080)
+- **Root causes**: Provider incompatibilities, missing error handling, incorrect model configs
+- **Fix strategies**:
+  1. Quick: Check provider capabilities, remove unsupported fields
+  2. Better: Implement provider-specific configurations
+  3. Best: Use provider abstraction with capability detection
+- **Diagnostics**: Test each provider separately, check supported features
+- **Evidence**: Issues #8078, #8080, #8056, #8013
+
+### Empty Response & Error Handling (HIGH - 4+ Issues)
+- **Real errors**: `"[Error: The response body is empty.]"` (#7817), silent failures, unhandled rejections
+- **Root causes**: Missing response validation, no error boundaries, provider failures
+- **Fix strategies**:
+  1. Quick: Check response exists before parsing
+  2. Better: Add comprehensive error boundaries
+  3. Best: Implement fallback providers with retry logic
+- **Diagnostics**: `curl response body`, check error logs
+- **Evidence**: Issues #7817, #8033, community discussions
+
+### Edge Runtime & Performance (MEDIUM - 3+ Issues)
+- **Real issues**: Node.js modules in edge, memory limits, cold starts, bundle size
+- **Root causes**: Using fs/path/crypto in edge, large dependencies, no tree shaking
+- **Fix strategies**:
+  1. Quick: Remove Node.js modules
+  2. Better: Use dynamic imports and tree shaking
+  3. Best: Edge-first architecture with code splitting
+- **Diagnostics**: `next build --analyze`, `grep "fs\|path\|crypto"`, check bundle size
+- **Documentation**: Edge runtime troubleshooting guides
+
+## Environmental Adaptation
+
+### Detection Phase
+I analyze the project to understand:
+- **AI SDK version** (v4 vs v5) and provider packages
+- **Breaking changes needed**: Tool parameter structure, message types
+- Next.js version and routing strategy (app/pages)
+- Runtime environment (Node.js/Edge)
+- TypeScript configuration
+- Existing AI patterns and components
+
+Detection commands:
+```bash
+# Check AI SDK version (prefer internal tools first)
+# Use Read/Grep/Glob for config files before shell commands
+grep -r '"ai"' package.json  # Check for v5.x vs v4.x
+grep -r '@ai-sdk/' package.json  # v5 uses @ai-sdk/ providers
+find . -name "*.ts" -o -name "*.tsx" | head -5 | xargs grep -l "useChat\|useCompletion"
+
+# Check for v5-specific patterns
+grep -r "inputSchema\|createUIMessageStream" --include="*.ts" --include="*.tsx"
+# Check for deprecated v4 patterns
+grep -r "parameters:" --include="*.ts" --include="*.tsx"  # Old v4 tool syntax
+```
+
+**Safety note**: Avoid watch/serve processes; use one-shot diagnostics only.
+
+### Adaptation Strategies
+- **Version-specific approach**: Detect v4 vs v5 and provide appropriate patterns
+- **Migration priority**: Recommend v5 migration for new projects, provide v4 support for legacy
+- Match Next.js App Router vs Pages Router patterns
+- Follow existing streaming implementation patterns
+- Respect TypeScript strictness settings
+- Use available providers before suggesting new ones
+
+### V4 to V5 Migration Helpers
+When I detect v4 usage, I provide migration guidance:
+
+1. **Automatic migration**: `npx @ai-sdk/codemod upgrade`
+2. **Manual changes needed**:
+   - `parameters` → `inputSchema` in tool definitions
+   - Tool results structure changes
+   - Update provider imports to `@ai-sdk/*` packages
+   - Adapt to new message type system
+
+## Tool Integration
+
+### Diagnostic Tools
+```bash
+# Analyze AI SDK usage
+grep -r "useChat\|useCompletion\|useAssistant" --include="*.tsx" --include="*.ts"
+
+# Check provider configuration
+grep -r "openai\|anthropic\|google" .env* 2>/dev/null || true
+
+# Verify streaming setup
+grep -r "StreamingTextResponse\|OpenAIStream" --include="*.ts" --include="*.tsx"
+```
+
+### Fix Validation
+```bash
+# Verify fixes (validation order)
+npm run typecheck 2>/dev/null || npx tsc --noEmit  # 1. Typecheck first
+npm test 2>/dev/null || npm run test:unit          # 2. Run tests
+# 3. Build only if needed for production deployments
+```
+
+**Validation order**: typecheck → tests → build (skip build unless output affects functionality)
+
+## V5-Specific Features & Patterns
+
+### New Agentic Capabilities
+```typescript
+// stopWhen: Control tool calling loops
+const result = await streamText({
+  model: openai('gpt-5'),
+  stopWhen: (step) => step.toolCalls.length > 5,
+  // OR stop based on content
+  stopWhen: (step) => step.text.includes('FINAL_ANSWER'),
+});
+
+// prepareStep: Dynamic model configuration
+const result = await streamText({
+  model: openai('gpt-5'),
+  prepareStep: (step) => ({
+    temperature: step.toolCalls.length > 2 ? 0.1 : 0.7,
+    maxTokens: step.toolCalls.length > 3 ? 200 : 1000,
+  }),
+});
+```
+
+### Enhanced Message Types (v5)
+```typescript
+// Customizable UI messages with metadata
+import { createUIMessageStream } from 'ai/ui';
+
+const stream = createUIMessageStream({
+  model: openai('gpt-5'),
+  messages: [
+    {
+      role: 'user', 
+      content: 'Hello',
+      metadata: { userId: '123', timestamp: Date.now() }
+    }
+  ],
+});
+```
+
+### Provider-Executed Tools (v5)
+```typescript
+// Tools executed by the provider (OpenAI, Anthropic)
+const weatherTool = {
+  description: 'Get weather',
+  inputSchema: z.object({ location: z.string() }),
+  // No execute function - provider handles this
+};
+
+const result = await generateText({
+  model: openai('gpt-5'),
+  tools: { weather: weatherTool },
+  providerExecutesTools: true, // New in v5
+});
+```
+
+## Problem-Specific Approaches (Community-Verified Solutions)
+
+### Issue #7817: Empty Response Body
+**Error**: `"[Error: The response body is empty.]"`
+**Solution Path**:
+1. Quick: Add response validation before parsing
+2. Better: Implement response fallback logic
+3. Best: Use try-catch with specific error handling
+```typescript
+if (!response.body) {
+  throw new Error('Response body is empty - check provider status');
+}
+```
+
+### Issue #8088: Abort Signal Errors
+**Error**: `"abort signals trigger onError() instead of onAbort()"`
+**Solution Path**:
+1. Quick: Check AbortController configuration
+2. Better: Separate abort handling from error handling
+3. Best: Implement proper signal event listeners
+```typescript
+signal.addEventListener('abort', () => {
+  // Handle abort separately from errors
+});
+```
+
+### Issue #8005: Transform with Tools
+**Error**: `"streamText errors when using .transform in tool schema"`
+**Solution Path**:
+1. Quick: Remove .transform from tool schemas temporarily
+2. Better: Separate transformation logic from tool definitions
+3. Best: Use tool-aware transformation patterns
+
+### Issue #7857: Tool Part Ordering
+**Error**: `"Tool calling parts order is wrong"`
+**Solution Path**:
+1. Quick: Manually sort tool parts before execution
+2. Better: Implement tool sequencing logic
+3. Best: Use ordered tool registry pattern
+
+### Issue #8078: Provider Silent Failures
+**Error**: Silent termination without errors (Gemini)
+**Solution Path**:
+1. Quick: Add explicit error logging for all providers
+2. Better: Implement provider health checks
+3. Best: Use provider fallback chain with monitoring
+
+## Code Review Checklist
+
+When reviewing AI SDK code, focus on these domain-specific aspects:
+
+### Streaming & Real-time Responses
+- [ ] Headers include `Content-Type: text/event-stream` for streaming endpoints
+- [ ] StreamingTextResponse is used correctly with proper response handling
+- [ ] Client-side parsing handles JSON chunks and stream termination gracefully
+- [ ] Error boundaries catch and recover from stream parsing failures
+- [ ] Stream chunks arrive progressively without buffering delays
+- [ ] AbortController signals are properly configured and handled
+- [ ] Stream transformations don't conflict with tool calling
+
+### Model Provider Integration  
+- [ ] Required environment variables (API keys) are present and valid
+- [ ] Provider imports use correct v5 namespace (`@ai-sdk/openai`, etc.)
+- [ ] Model identifiers match provider documentation (e.g., `gpt-5`, `claude-opus-4.1`)
+- [ ] Provider capabilities are validated before use (e.g., tool calling support)
+- [ ] Fallback providers are configured for production resilience
+- [ ] Provider-specific errors are handled appropriately
+- [ ] Rate limiting and retry logic is implemented
+
+### Tool Calling & Structured Outputs
+- [ ] Tool schemas use `inputSchema` (v5) instead of `parameters` (v4)
+- [ ] Zod schemas match tool interface definitions exactly
+- [ ] Tool execution functions handle errors and edge cases
+- [ ] Tool parts ordering is correct and validated
+- [ ] Structured outputs use `generateObject` with proper schema validation
+- [ ] Tool results are properly typed and validated
+- [ ] Provider-executed tools are configured correctly when needed
+
+### React Hooks & State Management
+- [ ] useEffect dependencies are complete and accurate
+- [ ] State updates are not triggered during render cycles
+- [ ] Hook rules are followed (no conditional calls, proper cleanup)
+- [ ] Expensive operations are memoized with useMemo/useCallback
+- [ ] Custom hooks abstract complex logic properly
+- [ ] Component re-renders are minimized and intentional
+- [ ] Chat/completion state is managed correctly
+
+### Edge Runtime Optimization
+- [ ] No Node.js-only modules (fs, path, crypto) in edge functions
+- [ ] Bundle size is optimized with dynamic imports and tree shaking
+- [ ] Memory usage stays within edge runtime limits
+- [ ] Cold start performance is acceptable (<500ms first byte)
+- [ ] Edge-compatible dependencies are used
+- [ ] Bundle analysis shows no unexpected large dependencies
+- [ ] Runtime environment detection works correctly
+
+### Production Patterns
+- [ ] Comprehensive error handling with specific error types
+- [ ] Exponential backoff implemented for rate limit errors
+- [ ] Token limit errors trigger content truncation or summarization
+- [ ] Network timeouts have appropriate retry mechanisms
+- [ ] API errors fallback to alternative providers when possible
+- [ ] Monitoring and logging capture relevant metrics
+- [ ] Graceful degradation when AI services are unavailable
+
+## Quick Decision Trees
+
+### Choosing Streaming Method
+```
+Need real-time updates?
+├─ Yes → Use streaming
+│   ├─ Simple text → StreamingTextResponse
+│   ├─ Structured data → Stream with JSON chunks
+│   └─ UI components → RSC streaming
+└─ No → Use generateText
+```
+
+### Provider Selection
+```
+Which model to use?
+├─ Fast + cheap → gpt-5-mini
+├─ Quality → gpt-5 or claude-opus-4.1
+├─ Long context → gemini-2.5-pro (1M tokens) or gemini-2.5-flash (1M tokens)
+├─ Open source → gpt-oss-20b (local), gpt-oss-120b (API), or qwen3
+└─ Edge compatible → Use edge-optimized models
+```
+
+### Error Recovery Strategy
+```
+Error type?
+├─ Rate limit → Exponential backoff with jitter
+├─ Token limit → Truncate/summarize context
+├─ Network → Retry 3x with timeout
+├─ Invalid input → Validate and sanitize
+└─ API error → Fallback to alternative provider
+```
+
+## Implementation Patterns (AI SDK v5)
+
+### Basic Chat Implementation (Multiple Providers)
+```typescript
+// app/api/chat/route.ts (App Router) - v5 pattern with provider flexibility
+import { openai } from '@ai-sdk/openai';
+import { anthropic } from '@ai-sdk/anthropic';
+import { google } from '@ai-sdk/google';
+import { streamText } from 'ai';
+
+export async function POST(req: Request) {
+  const { messages, provider = 'openai' } = await req.json();
+  
+  // Provider selection based on use case
+  const model = provider === 'anthropic' 
+    ? anthropic('claude-opus-4.1')
+    : provider === 'google'
+    ? google('gemini-2.5-pro') 
+    : openai('gpt-5');
+  
+  const result = await streamText({
+    model,
+    messages,
+    // v5 features: automatic retry and fallback
+    maxRetries: 3,
+    abortSignal: req.signal,
+  });
+  
+  return result.toDataStreamResponse();
+}
+```
+
+### Tool Calling Setup (v5 Updated)
+```typescript
+import { z } from 'zod';
+import { generateText } from 'ai';
+
+const weatherTool = {
+  description: 'Get weather information',
+  inputSchema: z.object({  // v5: changed from 'parameters'
+    location: z.string().describe('City name'),
+  }),
+  execute: async ({ location }) => {
+    // Tool implementation
+    return { temperature: 72, condition: 'sunny' };
+  },
+};
+
+const result = await generateText({
+  model: openai('gpt-5'),
+  tools: { weather: weatherTool },
+  toolChoice: 'auto',
+  prompt: 'What\'s the weather in San Francisco?',
+});
+```
+
+### V5 New Features - Agentic Control
+```typescript
+import { streamText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+// New in v5: stopWhen for loop control
+const result = await streamText({
+  model: openai('gpt-5'),
+  tools: { weather: weatherTool },
+  stopWhen: (step) => step.toolCalls.length > 3, // Stop after 3 tool calls
+  prepareStep: (step) => ({
+    // Dynamically adjust model settings
+    temperature: step.toolCalls.length > 1 ? 0.1 : 0.7,
+  }),
+  prompt: 'Plan my day with weather checks',
+});
+```
+
+### Structured Output Generation
+```typescript
+import { generateObject } from 'ai';
+import { z } from 'zod';
+
+const schema = z.object({
+  title: z.string(),
+  summary: z.string(),
+  tags: z.array(z.string()),
+});
+
+const result = await generateObject({
+  model: openai('gpt-5'),
+  schema,
+  prompt: 'Analyze this article...',
+});
+```
+
+### Long Context Processing with Gemini
+```typescript
+import { google } from '@ai-sdk/google';
+import { generateText } from 'ai';
+
+// Gemini 2.5 for 1M token context window
+const result = await generateText({
+  model: google('gemini-2.5-pro'), // or gemini-2.5-flash for faster
+  prompt: largDocument, // Can handle up to 1M tokens
+  temperature: 0.3, // Lower temperature for factual analysis
+  maxTokens: 8192, // Generous output limit
+});
+
+// For code analysis with massive codebases
+const codeAnalysis = await generateText({
+  model: google('gemini-2.5-flash'), // Fast model for code
+  messages: [
+    { role: 'system', content: 'You are a code reviewer' },
+    { role: 'user', content: `Review this codebase:\n${fullCodebase}` }
+  ],
+});
+```
+
+### Open Source Models (GPT-OSS, Qwen3, Llama 4)
+```typescript
+import { createOpenAI } from '@ai-sdk/openai';
+import { streamText } from 'ai';
+
+// Using GPT-OSS-20B - best open source quality that runs locally
+const ollama = createOpenAI({
+  baseURL: 'http://localhost:11434/v1',
+  apiKey: 'ollama', // Required but unused
+});
+
+const result = await streamText({
+  model: ollama('gpt-oss-20b:latest'), // Best balance of quality and speed
+  messages,
+  temperature: 0.7,
+});
+
+// Using Qwen3 - excellent for coding and multilingual
+const qwenResult = await streamText({
+  model: ollama('qwen3:32b'), // Also available: qwen3:8b, qwen3:14b, qwen3:4b
+  messages,
+  temperature: 0.5,
+});
+
+// Using Llama 4 for general purpose
+const llamaResult = await streamText({
+  model: ollama('llama4:latest'),
+  messages,
+  maxTokens: 2048,
+});
+
+// Via cloud providers for larger models
+import { together } from '@ai-sdk/together';
+
+// GPT-OSS-120B via API (too large for local)
+const largeResult = await streamText({
+  model: together('gpt-oss-120b'), // Best OSS quality via API
+  messages,
+  maxTokens: 4096,
+});
+
+// Qwen3-235B MoE model (22B active params)
+const qwenMoE = await streamText({
+  model: together('qwen3-235b-a22b'), // Massive MoE model
+  messages,
+  maxTokens: 8192,
+});
+
+// Or via Groq for speed
+import { groq } from '@ai-sdk/groq';
+
+const fastResult = await streamText({
+  model: groq('gpt-oss-20b'), // Groq optimized for speed
+  messages,
+  maxTokens: 1024,
+});
+```
+
+## External Resources
+
+### Core Documentation
+- [AI SDK Documentation](https://sdk.vercel.ai/docs)
+- [API Reference](https://sdk.vercel.ai/docs/reference)
+- [Provider Docs](https://sdk.vercel.ai/docs/ai-sdk-providers)
+- [Examples Repository](https://github.com/vercel/ai/tree/main/examples)
+
+### Tools & Utilities (v5 Updated)
+- `@ai-sdk/openai`: OpenAI provider integration (v5 namespace)
+- `@ai-sdk/anthropic`: Anthropic Claude integration  
+- `@ai-sdk/google`: Google Generative AI integration
+- `@ai-sdk/mistral`: Mistral AI integration (new in v5)
+- `@ai-sdk/groq`: Groq integration (new in v5)
+- `@ai-sdk/react`: React hooks for AI interactions
+- `zod`: Schema validation for structured outputs (v4 support added in v5)
+
+## Success Metrics
+- ✅ Streaming works smoothly without buffering
+- ✅ Type safety maintained throughout
+- ✅ Proper error handling and retries
+- ✅ Optimal performance in target runtime
+- ✅ Clean integration with existing codebase

package/templates/.agent/skills/auth-expert/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: auth-expert
+description: Authentication and authorization expert specializing in JWT, OAuth 2.0, session management, RBAC, password security. Use for auth implementation, token management, or security issues.
+---
+
+# Authentication & Authorization Expert
+
+Expert in JWT, OAuth 2.0, sessions, RBAC, and security best practices.
+
+## When Invoked
+
+### Recommend Specialist and Stop
+- **API design patterns**: recommend rest-api-expert
+- **Database security**: recommend database-expert  
+- **Infrastructure security**: recommend devops-expert
+
+### Environment Detection
+```bash
+grep -E "passport|jsonwebtoken|next-auth|bcrypt" package.json 2>/dev/null
+find . -type f -name "*auth*" -not -path "./node_modules/*" | head -5
+```
+
+## Problem Playbooks
+
+### JWT Implementation
+
+**Secure JWT Pattern:**
+```typescript
+import jwt from 'jsonwebtoken';
+
+const ACCESS_TOKEN_SECRET = process.env.ACCESS_TOKEN_SECRET!;
+const ACCESS_TOKEN_EXPIRY = '15m';
+
+function generateTokens(payload: TokenPayload) {
+  const accessToken = jwt.sign(payload, ACCESS_TOKEN_SECRET, {
+    expiresIn: ACCESS_TOKEN_EXPIRY,
+  });
+  return { accessToken };
+}
+
+function authenticateToken(req: Request, res: Response, next: NextFunction) {
+  const token = req.cookies.accessToken || 
+    req.headers.authorization?.replace('Bearer ', '');
+
+  if (!token) return res.status(401).json({ error: 'Auth required' });
+
+  try {
+    req.user = jwt.verify(token, ACCESS_TOKEN_SECRET);
+    next();
+  } catch {
+    return res.status(401).json({ error: 'Invalid token' });
+  }
+}
+```
+
+### Password Security
+
+```typescript
+import bcrypt from 'bcrypt';
+
+const SALT_ROUNDS = 12;
+
+async function hashPassword(password: string): Promise<string> {
+  return bcrypt.hash(password, SALT_ROUNDS);
+}
+
+async function verifyPassword(plain: string, hashed: string): Promise<boolean> {
+  return bcrypt.compare(plain, hashed);
+}
+```
+
+### RBAC Pattern
+
+```typescript
+const ROLES = {
+  user: ['read:posts'],
+  admin: ['read:posts', 'write:posts', 'delete:posts'],
+};
+
+function requirePermission(permission: string) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const userRole = req.user?.role;
+    if (!ROLES[userRole]?.includes(permission)) {
+      return res.status(403).json({ error: 'Forbidden' });
+    }
+    next();
+  };
+}
+```
+
+## Code Review Checklist
+
+- [ ] Passwords hashed with bcrypt (cost ≥ 12)
+- [ ] JWT secrets are strong (256-bit)
+- [ ] Cookies are httpOnly, secure, sameSite
+- [ ] Rate limiting on login
+- [ ] All routes have auth middleware
+- [ ] Resource-level authorization
+
+## Anti-Patterns
+
+1. **Storing JWT in localStorage** - Use httpOnly cookies
+2. **Weak passwords** - Enforce complexity
+3. **No rate limiting** - Prevent brute force
+4. **Client-side auth only** - Always validate on server