axiom-coding-agent-setup 1.0.0 → 1.0.2

package/.agents/skills/ai-integration/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: ai-integration
+description: Patterns and best practices for integrating AI/LLM capabilities into applications. Use when implementing chat, RAG, agents, or other AI features.
+---
+
+# AI Integration Patterns Guide
+
+## Overview
+
+This skill covers patterns for integrating Large Language Models (LLMs) into applications effectively and safely.
+
+---
+
+## When to Use This Skill
+
+- Building chat interfaces
+- Implementing RAG (Retrieval-Augmented Generation)
+- Creating AI agents
+- Adding AI-powered features to existing apps
+- Choosing between different AI approaches
+
+---
+
+## Core Patterns
+
+### 1. Chat Interface
+
+**Basic Streaming Chat**
+```typescript
+// Server-side (API route)
+import { streamText } from 'ai';
+import { openai } from '@/lib/ai/providers';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: openai('gpt-4'),
+    messages,
+    system: "You are a helpful assistant.",
+  });
+
+  return result.toDataStreamResponse();
+}
+```
+
+```typescript
+// Client-side (React)
+import { useChat } from 'ai/react';
+
+function ChatComponent() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat();
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {messages.map(m => (
+        <div key={m.id}>{m.content}</div>
+      ))}
+      <input 
+        value={input} 
+        onChange={handleInputChange}
+        placeholder="Type a message..."
+      />
+    </form>
+  );
+}
+```
+
+### 2. RAG (Retrieval-Augmented Generation)
+
+**Basic RAG Flow**
+```
+User Query → Embed Query → Vector Search → Retrieve Context → 
+Augment Prompt → Generate Response → Return with Sources
+```
+
+**Implementation Pattern**
+```typescript
+async function generateWithRAG(query: string) {
+  // 1. Generate embedding for query
+  const embedding = await generateEmbedding(query);
+  
+  // 2. Search vector database
+  const relevantDocs = await vectorDB.query({
+    embedding,
+    topK: 5,
+  });
+  
+  // 3. Build augmented prompt
+  const context = relevantDocs.map(d => d.content).join('\n\n');
+  const prompt = `Context:\n${context}\n\nQuestion: ${query}`;
+  
+  // 4. Generate response
+  const response = await llm.generate(prompt);
+  
+  // 5. Return with source citations
+  return {
+    answer: response,
+    sources: relevantDocs.map(d => ({
+      title: d.title,
+      url: d.url,
+    })),
+  };
+}
+```
+
+### 3. Tool Use / Function Calling
+
+**Defining Tools**
+```typescript
+import { tool } from 'ai';
+import { z } from 'zod';
+
+const searchDocuments = tool({
+  description: "Search the knowledge base for relevant information",
+  parameters: z.object({
+    query: z.string().describe("The search query"),
+  }),
+  execute: async ({ query }) => {
+    // Implementation
+    return await searchKnowledgeBase(query);
+  },
+});
+
+const calculateMortgage = tool({
+  description: "Calculate monthly mortgage payment",
+  parameters: z.object({
+    principal: z.number().describe("Loan amount"),
+    rate: z.number().describe("Annual interest rate (decimal)"),
+    years: z.number().describe("Loan term in years"),
+  }),
+  execute: async ({ principal, rate, years }) => {
+    const monthlyRate = rate / 12;
+    const numPayments = years * 12;
+    const payment = 
+      (principal * monthlyRate * Math.pow(1 + monthlyRate, numPayments)) /
+      (Math.pow(1 + monthlyRate, numPayments) - 1);
+    return { monthlyPayment: payment.toFixed(2) };
+  },
+});
+```
+
+**Using Tools**
+```typescript
+const result = await generateText({
+  model: openai('gpt-4'),
+  tools: { searchDocuments, calculateMortgage },
+  prompt: userMessage,
+});
+```
+
+### 4. Multi-Step Agents
+
+**Simple Agent Loop**
+```typescript
+async function runAgent(userInput: string, maxSteps = 5) {
+  const messages: Message[] = [
+    { role: 'system', content: 'You are a helpful agent...' },
+    { role: 'user', content: userInput },
+  ];
+  
+  for (let i = 0; i < maxSteps; i++) {
+    const response = await llm.generate({
+      messages,
+      tools: availableTools,
+    });
+    
+    if (response.finishReason === 'stop') {
+      return response.content;
+    }
+    
+    if (response.toolCalls) {
+      // Execute tool calls
+      for (const call of response.toolCalls) {
+        const result = await executeTool(call);
+        messages.push({
+          role: 'tool',
+          tool_call_id: call.id,
+          content: JSON.stringify(result),
+        });
+      }
+    }
+  }
+  
+  return "Maximum steps reached";
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Prompt Engineering
+
+**System Prompts**
+- Be specific about the assistant's role
+- Include constraints and boundaries
+- Provide output format examples
+
+```
+You are a customer support agent for TechCorp.
+- Be friendly but professional
+- If you don't know something, say so
+- Always verify account details before making changes
+- Format responses in markdown
+```
+
+**Few-Shot Prompting**
+Include examples for complex tasks:
+```
+Classify the sentiment of the following text.
+
+Examples:
+Text: "I love this product!"
+Sentiment: Positive
+
+Text: "Terrible experience, never again"
+Sentiment: Negative
+
+Text: {{user_input}}
+Sentiment:
+```
+
+### 2. Context Management
+
+**Token Budgets**
+- Track token usage
+- Implement context window management
+- Summarize long conversations when needed
+
+**Relevant Context Selection**
+- Don't dump entire documents into context
+- Use semantic search to find relevant chunks
+- Prioritize recent and relevant information
+
+### 3. Error Handling
+
+**Common Errors**
+- Rate limits: Implement exponential backoff
+- Timeout: Break requests into smaller chunks
+- Content policy: Handle refusals gracefully
+- JSON parsing: Use structured output when possible
+
+```typescript
+try {
+  const response = await llm.generate(prompt);
+  return response;
+} catch (error) {
+  if (error.code === 'rate_limit_exceeded') {
+    await sleep(1000);
+    return retry(prompt);
+  }
+  if (error.code === 'content_policy_violation') {
+    return { error: 'I cannot respond to that request' };
+  }
+  throw error;
+}
+```
+
+### 4. Safety & Guardrails
+
+**Input Validation**
+- Sanitize user inputs
+- Limit input length
+- Validate against injection attacks
+
+**Output Filtering**
+- Check for PII in outputs
+- Filter inappropriate content
+- Add human review for sensitive actions
+
+**Cost Controls**
+- Set token limits per request
+- Cache common responses
+- Monitor usage and set budgets
+
+---
+
+## Provider Selection Guide
+
+| Use Case | Recommended Provider | Model |
+|----------|---------------------|-------|
+| General chat | OpenAI / Anthropic | GPT-4 / Claude Sonnet |
+| Reasoning tasks | OpenAI / Anthropic | o3 / Claude Opus |
+| Long context | Google | Gemini 2.5 Pro |
+| Cost-sensitive | OpenAI | GPT-4o-mini |
+| Code generation | Anthropic | Claude Sonnet |
+| Multimodal | OpenAI / Google | GPT-4o / Gemini |
+
+---
+
+## Evaluation
+
+**Test Your AI Integration**
+
+1. **Create test cases** with expected outputs
+2. **Test edge cases** (empty input, very long input, special characters)
+3. **Measure latency** and cost per request
+4. **Monitor error rates** and failure modes
+
+**Example Evaluation Questions**
+- Can the system handle ambiguous queries?
+- Does it refuse inappropriate requests?
+- Are sources correctly cited in RAG?
+- Does it maintain context across multiple turns?
+
+---
+
+## Resources
+
+- **Vercel AI SDK**: https://sdk.vercel.ai/docs
+- **OpenAI API**: https://platform.openai.com/docs
+- **Anthropic API**: https://docs.anthropic.com/
+- **LangChain**: https://python.langchain.com/ / https://js.langchain.com/

package/.agents/skills/deployment-patterns/SKILL.md

@@ -0,0 +1,408 @@
+---
+name: deployment-patterns
+description: Deployment patterns and best practices for various platforms. Use when setting up deployment pipelines, choosing infrastructure, or configuring CI/CD.
+---
+
+# Deployment Patterns Guide
+
+## Overview
+
+This skill covers deployment patterns for different types of applications across various platforms.
+
+---
+
+## When to Use This Skill
+
+- Setting up deployment for a new project
+- Choosing between deployment platforms
+- Configuring CI/CD pipelines
+- Migrating between hosting providers
+- Setting up staging/production environments
+
+---
+
+## Platform Selection Guide
+
+### Vercel
+**Best for:** Next.js, React, static sites
+
+**Pros:**
+- Zero-config for Next.js
+- Automatic preview deployments
+- Edge functions
+- Built-in analytics
+
+**When to use:**
+- Frontend applications
+- Full-stack Next.js apps
+- JAMstack sites
+
+**Configuration:**
+```json
+// vercel.json
+{
+  "buildCommand": "npm run build",
+  "outputDirectory": ".next",
+  "framework": "nextjs",
+  "rewrites": [
+    { "source": "/api/(.*)", "destination": "/api/$1" }
+  ]
+}
+```
+
+### Railway / Render / Fly.io
+**Best for:** Full-stack apps, APIs, databases
+
+**Pros:**
+- Easy environment variable management
+- Automatic HTTPS
+- Native Docker support
+- Good for Node.js/Python/Go
+
+**When to use:**
+- Backend APIs
+- Full-stack apps with persistent storage
+- Applications needing databases
+
+### AWS (ECS, Lambda, EC2)
+**Best for:** Enterprise, complex infrastructure
+
+**Pros:**
+- Full control
+- Scalable
+- Extensive service ecosystem
+
+**When to use:**
+- Production enterprise apps
+- Complex microservices
+- When you need specific AWS services
+
+**Lambda Example:**
+```yaml
+# serverless.yml
+service: my-api
+
+provider:
+  name: aws
+  runtime: nodejs20.x
+  region: us-east-1
+
+functions:
+  api:
+    handler: dist/index.handler
+    events:
+      - httpApi: '*'
+```
+
+### Docker + VPS (DigitalOcean, Hetzner, etc.)
+**Best for:** Cost-conscious, full control
+
+**Pros:**
+- Cheapest for steady traffic
+- Full control over server
+- No vendor lock-in
+
+**When to use:**
+- Side projects
+- Predictable traffic
+- Learning/DevOps practice
+
+---
+
+## CI/CD Patterns
+
+### GitHub Actions
+
+**Basic Setup**
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  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 lint
+      - run: npm run test
+      - run: npm run build
+
+  deploy:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Deploy to Vercel
+        uses: vercel/action-deploy@v1
+        with:
+          vercel-token: ${{ secrets.VERCEL_TOKEN }}
+```
+
+**Matrix Testing**
+```yaml
+strategy:
+  matrix:
+    node-version: [18, 20, 21]
+    os: [ubuntu-latest, windows-latest]
+```
+
+### Environment Strategy
+
+**Typical Setup**
+```
+Development → Staging → Production
+     ↓             ↓           ↓
+  Local        Preview     Live
+```
+
+**Branch-Based**
+```
+feature/*   → Deploy to Preview/Staging
+main        → Deploy to Production
+```
+
+---
+
+## Database Deployment
+
+### PostgreSQL Options
+
+| Platform | Type | Best For |
+|----------|------|----------|
+| **Neon** | Serverless | Auto-scaling, scale-to-zero |
+| **Supabase** | Managed | Full backend-as-a-service |
+| **Railway** | Managed | Simple setup, good pricing |
+| **AWS RDS** | Managed | Enterprise, compliance needs |
+| **Self-hosted** | VPS | Cost control, full access |
+
+### Migration Strategy
+
+**Prisma (Node.js)**
+```bash
+# Generate migration
+npx prisma migrate dev --name add_user_table
+
+# Deploy migration
+npx prisma migrate deploy
+```
+
+**Alembic (Python)**
+```bash
+# Generate migration
+alembic revision --autogenerate -m "Add user table"
+
+# Run migration
+alembic upgrade head
+```
+
+---
+
+## Environment Configuration
+
+### Environment Variables
+
+**Required Variables**
+```bash
+# App
+NODE_ENV=production
+PORT=3000
+
+# Database
+DATABASE_URL=postgresql://...
+
+# Auth
+JWT_SECRET=...
+NEXTAUTH_SECRET=...
+
+# APIs
+OPENAI_API_KEY=...
+```
+
+**Configuration Pattern**
+```typescript
+// config.ts
+const config = {
+  development: {
+    apiUrl: 'http://localhost:3000',
+    debug: true,
+  },
+  production: {
+    apiUrl: process.env.API_URL,
+    debug: false,
+  },
+}[process.env.NODE_ENV || 'development'];
+```
+
+---
+
+## Docker Deployment
+
+### Dockerfile Patterns
+
+**Node.js**
+```dockerfile
+# Build stage
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY package*.json ./
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+```
+
+**Python**
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install uv
+RUN pip install uv
+
+# Copy and install dependencies
+COPY pyproject.toml ./
+RUN uv pip install --system -e "."
+
+# Copy source
+COPY src/ ./src/
+
+EXPOSE 8000
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+### Docker Compose
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp
+    depends_on:
+      - db
+
+  db:
+    image: postgres:15-alpine
+    environment:
+      - POSTGRES_USER=postgres
+      - POSTGRES_PASSWORD=password
+      - POSTGRES_DB=myapp
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data:
+```
+
+---
+
+## Health Checks & Monitoring
+
+### Health Check Endpoint
+
+```typescript
+// Simple health check
+app.get('/health', (req, res) => {
+  res.json({ 
+    status: 'ok', 
+    timestamp: new Date().toISOString(),
+    version: process.env.npm_package_version
+  });
+});
+
+// With dependencies check
+app.get('/health', async (req, res) => {
+  const checks = {
+    database: await checkDatabase(),
+    cache: await checkCache(),
+    externalApi: await checkExternalApi(),
+  };
+  
+  const healthy = Object.values(checks).every(c => c.status === 'ok');
+  
+  res.status(healthy ? 200 : 503).json({
+    status: healthy ? 'ok' : 'error',
+    checks,
+    timestamp: new Date().toISOString(),
+  });
+});
+```
+
+### Monitoring Tools
+
+| Tool | Purpose | Cost |
+|------|---------|------|
+| **Sentry** | Error tracking | Free tier |
+| **Datadog** | Full observability | Paid |
+| **Grafana Cloud** | Metrics/dashboards | Free tier |
+| **UptimeRobot** | Uptime monitoring | Free tier |
+
+---
+
+## Security Checklist
+
+- [ ] HTTPS enforced
+- [ ] Secrets in environment variables (never in code)
+- [ ] Database credentials rotated regularly
+- [ ] CORS properly configured
+- [ ] Rate limiting implemented
+- [ ] Input validation on all endpoints
+- [ ] Dependencies kept up to date
+- [ ] Security headers set (HSTS, CSP, etc.)
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Build fails**
+- Check Node.js/Python version matches
+- Clear cache and reinstall dependencies
+- Check for missing environment variables
+
+**Deployment succeeds but app crashes**
+- Check logs: `vercel logs` / `railway logs` / `docker logs`
+- Verify environment variables are set
+- Check database connectivity
+
+**Slow cold starts**
+- Use smaller dependencies
+- Implement connection pooling
+- Use edge functions where appropriate
+
+---
+
+## Resources
+
+- **Vercel Docs**: https://vercel.com/docs
+- **Railway Docs**: https://docs.railway.app/
+- **Docker Docs**: https://docs.docker.com/
+- **GitHub Actions**: https://docs.github.com/en/actions