ultra-dex 1.7.2 → 1.8.0

package/assets/agents/README.md

@@ -0,0 +1,232 @@
+# Ultra-Dex AI Agents
+
+> 15 specialized AI agent prompts organized by production tier
+
+---
+
+## What Are Agents?
+
+Agents are specialized AI prompts that you copy into your AI tool (Cursor, Claude, ChatGPT, etc.). Each agent has a specific role in the production pipeline and knows how to coordinate with other agents.
+
+---
+
+## Quick Reference
+
+See [00-AGENT_INDEX.md](./00-AGENT_INDEX.md) for complete agent directory with "when to use" guidance.
+
+---
+
+## Agent Organization
+
+Agents are organized into **6 tiers** representing the production pipeline:
+
+### 1. Leadership Tier (`1-leadership/`)
+**Strategic planning and architecture decisions**
+
+- **[@CTO](./1-leadership/cto.md)** - Architecture & tech stack decisions
+  - Use for: Major features, system design, technology choices
+  - Example: "Should we use Next.js or separate React + Express?"
+
+- **[@Planner](./1-leadership/planner.md)** - Task breakdown & sprint planning
+  - Use for: Starting any feature, breaking down complex work
+  - Example: "Break down 'user authentication' into implementation tasks"
+
+- **[@Research](./1-leadership/research.md)** - Technology evaluation & comparison
+  - Use for: Choosing frameworks, libraries, comparing approaches
+  - Example: "Compare Prisma vs Drizzle ORM for PostgreSQL"
+
+### 2. Development Tier (`2-development/`)
+**Core feature implementation**
+
+- **[@Backend](./2-development/backend.md)** - API & server logic
+  - Use for: Building endpoints, business logic, server code
+  - Example: "Build REST API for user authentication"
+
+- **[@Database](./2-development/database.md)** - Schema & queries
+  - Use for: Database changes, migrations, query optimization
+  - Example: "Create User and Post tables with relationships"
+
+- **[@Frontend](./2-development/frontend.md)** - UI & components
+  - Use for: Building pages, components, user flows
+  - Example: "Build login page with form validation"
+
+### 3. Security Tier (`3-security/`)
+**Authentication, authorization, and security audits**
+
+- **[@Auth](./3-security/auth.md)** - Auth flows & permissions
+  - Use for: Login, permissions, user management
+  - Example: "Implement JWT authentication with refresh tokens"
+
+- **[@Security](./3-security/security.md)** - Vulnerability audits
+  - Use for: Before deployment, security reviews, OWASP checks
+  - Example: "Audit authentication system for security vulnerabilities"
+
+### 4. DevOps Tier (`4-devops/`)
+**Deployment and infrastructure management**
+
+- **[@DevOps](./4-devops/devops.md)** - CI/CD & deployment
+  - Use for: Shipping to production, deployment pipelines
+  - Example: "Deploy to Vercel with PostgreSQL on Railway"
+
+### 5. Quality Tier (`5-quality/`)
+**Testing, debugging, code review, and documentation**
+
+- **[@Debugger](./5-quality/debugger.md)** - Bug investigation
+  - Use for: When something breaks, troubleshooting issues
+  - Example: "Fix: Login endpoint returns 500 error"
+
+- **[@Documentation](./5-quality/documentation.md)** - Technical writing & docs maintenance
+  - Use for: Updating docs, API documentation, user guides
+  - Example: "Document API endpoints with examples"
+
+- **[@Reviewer](./5-quality/reviewer.md)** - Code review
+  - Use for: Before merging, final approval, quality checks
+  - Example: "Review authentication implementation for best practices"
+
+- **[@Testing](./5-quality/testing.md)** - Test automation
+  - Use for: Writing tests, ensuring coverage, QA
+  - Example: "Write unit tests for auth API (80% coverage)"
+
+### 6. Specialist Tier (`6-specialist/`)
+**Advanced optimization and code improvement**
+
+- **[@Performance](./6-specialist/performance.md)** - Performance optimization
+  - Use for: Slow pages/APIs, optimization needed
+  - Example: "Optimize user list page (currently 5s load time)"
+
+- **[@Refactoring](./6-specialist/refactoring.md)** - Code quality improvement
+  - Use for: Cleaning up code, reducing complexity, applying patterns
+  - Example: "Refactor authentication code to use strategy pattern"
+
+---
+
+## How to Use
+
+### Single Agent (Simple Tasks)
+
+```
+1. Open your AI tool (Cursor, Claude, ChatGPT)
+2. Copy contents of an agent file (e.g., backend.md)
+3. Paste into chat
+4. Say: "Build the user authentication API"
+5. AI follows agent instructions + your project plan
+```
+
+### Multi-Agent Workflow (Complex Features)
+
+For complex features, use multiple agents in sequence:
+
+```
+1. @Planner → Break down feature into tasks
+2. @CTO → Review architecture
+3. @Backend → Build API
+4. @Frontend → Build UI
+5. @Testing → Write tests
+6. @Reviewer → Code review
+7. @DevOps → Deploy
+```
+
+See [Project Orchestration Guide](../guides/PROJECT-ORCHESTRATION.md) for complete multi-agent workflows.
+
+---
+
+## Multi-Agent Orchestration
+
+For coordinating multiple agents on complex features, see:
+
+**Production Guides:**
+- **[Project Orchestration](../guides/PROJECT-ORCHESTRATION.md)** - Step-by-step multi-agent workflows
+- **[Advanced Workflows](../guides/ADVANCED-WORKFLOWS.md)** - Stripe, emails, migrations, real-time
+- **[Multi-Tool Workflow](../guides/MULTI-TOOL-WORKFLOW.md)** - Coordinate multiple AI tools
+
+**Examples:**
+- **[Orchestration Examples](../Orchestration/EXAMPLES.md)** - Real-world workflow examples
+- **[Orchestration README](../Orchestration/README.md)** - Pattern overview
+
+---
+
+## Integration with Ultra-Dex
+
+All agents are designed to work with:
+- `IMPLEMENTATION-PLAN.md` - Your 34-section project plan
+- `CONTEXT.md` - Project background and decisions
+- `QUICK-START.md` - Core project summary
+- `.cursor/rules/` - AI coding patterns (if installed)
+
+Agents reference these files to stay aligned with your project vision.
+
+---
+
+## Customization
+
+These are YOUR files after installing Ultra-Dex. Feel free to:
+
+- **Modify** - Change instructions to fit your workflow
+- **Delete** - Remove agents you don't need
+- **Add new** - Create custom agents in appropriate tier
+- **Reorganize** - Adjust tier structure as needed
+
+---
+
+## Creating Custom Agents
+
+Follow this template:
+
+```markdown
+# [Role Name] Agent
+
+You are a [role description] for this project.
+
+## Your Context
+- Read `IMPLEMENTATION-PLAN.md` for full specification
+- Read `CONTEXT.md` for project background
+
+## Your Responsibilities
+- [List specific tasks]
+
+## Works With
+- Request review from: @[OtherAgent]
+- Hand off to: @[NextAgent]
+
+## Quality Checklist
+Before handing off work, verify:
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+
+## Handoff Protocol
+[Use standardized handoff format from other agents]
+```
+
+---
+
+## Multi-Tool Support
+
+Ultra-Dex agents work with **ANY AI tool**:
+
+- **Claude Code** (best for complex reasoning)
+- **Cursor** (fast coding)
+- **GitHub Copilot** (inline suggestions)
+- **ChatGPT** (research & planning)
+- **Gemini** (free alternative)
+
+See [Multi-Tool Workflow Guide](../guides/MULTI-TOOL-WORKFLOW.md) for details.
+
+---
+
+## CLI Usage
+
+```bash
+# List all agents
+npx ultra-dex agents
+
+# Show specific agent
+npx ultra-dex agent backend
+
+# Include agents when initializing project
+npx ultra-dex init
+# Answer "yes" to "Include AI agent prompts?"
+```
+
+---
+
+*Part of [Ultra-Dex v1.7.0](https://github.com/Srujan0798/Ultra-Dex) - Professional AI Orchestration Meta Layer*

package/assets/cursor-rules/00-ultra-dex-core.mdc

@@ -0,0 +1,48 @@
+# Ultra-Dex Core Rules
+
+> Load this as your base ruleset. Add domain-specific rules as needed.
+
+## Project Philosophy
+
+- Build production-ready from day 1
+- Every task: 4-9 hours with clear acceptance criteria
+- 21-step verification for features (simplified for fixes)
+- Code > Documentation (but document decisions)
+
+## Code Standards
+
+- TypeScript strict mode always
+- Zod validation at all API boundaries
+- Error handling: never swallow errors silently
+- Logging: structured JSON, include request IDs
+- Tests: minimum 80% coverage for business logic
+
+## Architecture Defaults
+
+- Next.js App Router (or specified framework)
+- PostgreSQL with Prisma ORM
+- NextAuth.js for authentication
+- Stripe for payments
+- Vercel for deployment
+
+## Task Completion Checklist (Quick 5-Step)
+
+1. Does it work? (Manual test)
+2. Are there tests? (Automated)
+3. Is it secure? (No secrets exposed, inputs validated)
+4. Is it documented? (Code comments for complex logic)
+5. Is it deployable? (No breaking changes)
+
+## When to Use Full 21-Step
+
+- New features affecting multiple files
+- Security-sensitive changes
+- Database schema changes
+- API contract changes
+
+## File Naming
+
+- Components: PascalCase (`UserProfile.tsx`)
+- Utilities: camelCase (`formatDate.ts`)
+- API routes: kebab-case (`/api/user-profile`)
+- Database: snake_case (`user_profiles`)

package/assets/cursor-rules/01-database.mdc

@@ -0,0 +1,50 @@
+# Database Rules
+
+## Schema Design
+
+- Use UUIDs for primary keys (not auto-increment)
+- Always include: `id`, `createdAt`, `updatedAt`
+- Soft delete with `deletedAt` for user data
+- Foreign keys with `ON DELETE CASCADE` or `SET NULL` (explicit)
+
+## Prisma Conventions
+
+```prisma
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  name      String?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  deletedAt DateTime?
+
+  // Relations
+  posts     Post[]
+
+  @@map("users")
+}
+```
+
+## Indexes
+
+- Always index foreign keys
+- Index frequently queried fields
+- Composite indexes for common query patterns
+
+## Migrations
+
+- Never edit existing migrations
+- Test migrations on staging before production
+- Include rollback strategy for destructive changes
+
+## Query Patterns
+
+- Use `select` to limit returned fields
+- Paginate all list queries (default: 20 items)
+- Use transactions for multi-table updates
+
+## Security
+
+- Never expose internal IDs in URLs (use slugs or public IDs)
+- Validate ownership before update/delete
+- Rate limit database-heavy operations

package/assets/cursor-rules/02-api.mdc

@@ -0,0 +1,81 @@
+# API Rules
+
+## Route Structure
+
+```
+/api/
+├── auth/           # Authentication endpoints
+├── users/          # User CRUD
+├── [resource]/     # Resource CRUD
+└── webhooks/       # External service webhooks
+```
+
+## Request Validation
+
+ALWAYS validate with Zod at the API boundary:
+
+```typescript
+import { z } from 'zod';
+
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+});
+
+export async function POST(req: Request) {
+  const body = await req.json();
+  const data = createUserSchema.parse(body); // Throws on invalid
+  // ... proceed with validated data
+}
+```
+
+## Response Format
+
+```typescript
+// Success
+{ data: T, meta?: { page, total } }
+
+// Error
+{ error: { code: string, message: string, details?: any } }
+```
+
+## HTTP Status Codes
+
+- 200: Success (GET, PUT, PATCH)
+- 201: Created (POST)
+- 204: No Content (DELETE)
+- 400: Bad Request (validation error)
+- 401: Unauthorized (not logged in)
+- 403: Forbidden (logged in, no permission)
+- 404: Not Found
+- 429: Rate Limited
+- 500: Server Error
+
+## Rate Limiting
+
+- Auth endpoints: 5 req/min
+- Write endpoints: 30 req/min
+- Read endpoints: 100 req/min
+
+Use `@upstash/ratelimit` or similar.
+
+## Error Handling
+
+```typescript
+try {
+  // operation
+} catch (error) {
+  if (error instanceof ZodError) {
+    return Response.json({ error: { code: 'VALIDATION_ERROR', message: error.message } }, { status: 400 });
+  }
+  console.error('API Error:', error);
+  return Response.json({ error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' } }, { status: 500 });
+}
+```
+
+## Security
+
+- Validate auth on every protected route
+- Check resource ownership
+- Sanitize user input
+- Never expose stack traces in production

package/assets/cursor-rules/03-auth.mdc

@@ -0,0 +1,70 @@
+# Authentication Rules
+
+## Provider: NextAuth.js (Auth.js)
+
+## Configuration
+
+```typescript
+// auth.ts
+import NextAuth from 'next-auth';
+import { PrismaAdapter } from '@auth/prisma-adapter';
+import Google from 'next-auth/providers/google';
+import { prisma } from '@/lib/prisma';
+
+export const { handlers, auth, signIn, signOut } = NextAuth({
+  adapter: PrismaAdapter(prisma),
+  providers: [Google],
+  callbacks: {
+    session: ({ session, user }) => ({
+      ...session,
+      user: { ...session.user, id: user.id },
+    }),
+  },
+});
+```
+
+## Protected Routes
+
+```typescript
+// Server Component
+import { auth } from '@/auth';
+import { redirect } from 'next/navigation';
+
+export default async function DashboardPage() {
+  const session = await auth();
+  if (!session) redirect('/login');
+
+  return <Dashboard user={session.user} />;
+}
+```
+
+## API Route Protection
+
+```typescript
+import { auth } from '@/auth';
+
+export async function GET() {
+  const session = await auth();
+  if (!session) {
+    return Response.json({ error: { code: 'UNAUTHORIZED' } }, { status: 401 });
+  }
+  // ... proceed
+}
+```
+
+## Role-Based Access
+
+```typescript
+// Check role in session callback or middleware
+if (session.user.role !== 'ADMIN') {
+  return Response.json({ error: { code: 'FORBIDDEN' } }, { status: 403 });
+}
+```
+
+## Security Checklist
+
+- [ ] Session expiry configured (default: 30 days)
+- [ ] CSRF protection enabled (NextAuth default)
+- [ ] Secure cookies in production
+- [ ] Rate limit login attempts
+- [ ] Log authentication events

package/assets/cursor-rules/04-frontend.mdc

@@ -0,0 +1,92 @@
+# Frontend Rules
+
+## Component Structure
+
+```
+src/
+├── app/                 # Next.js App Router pages
+├── components/
+│   ├── ui/              # Reusable UI (Button, Input, Modal)
+│   ├── features/        # Feature-specific (TaskCard, UserAvatar)
+│   └── layout/          # Layout (Header, Footer, Sidebar)
+├── hooks/               # Custom React hooks
+├── lib/                 # Utilities (api, utils, constants)
+└── types/               # TypeScript types
+```
+
+## Component Patterns
+
+### Server vs Client Components
+
+```typescript
+// Default: Server Component (no 'use client')
+// Use for: data fetching, SEO, static content
+
+// Client Component
+'use client';
+// Use for: interactivity, useState, useEffect, event handlers
+```
+
+### Props Interface
+
+```typescript
+interface ButtonProps {
+  variant?: 'primary' | 'secondary' | 'danger';
+  size?: 'sm' | 'md' | 'lg';
+  loading?: boolean;
+  children: React.ReactNode;
+  onClick?: () => void;
+}
+
+export function Button({ variant = 'primary', size = 'md', ...props }: ButtonProps) {
+  // ...
+}
+```
+
+## State Management
+
+- Local state: `useState`
+- Form state: `react-hook-form` + Zod
+- Server state: `@tanstack/react-query` or Server Components
+- Global state: Zustand (if needed)
+
+## Data Fetching
+
+```typescript
+// Server Component (preferred)
+async function TaskList() {
+  const tasks = await prisma.task.findMany();
+  return <ul>{tasks.map(t => <li key={t.id}>{t.title}</li>)}</ul>;
+}
+
+// Client Component with React Query
+const { data, isLoading } = useQuery({
+  queryKey: ['tasks'],
+  queryFn: () => fetch('/api/tasks').then(r => r.json()),
+});
+```
+
+## Forms
+
+```typescript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+
+const form = useForm({
+  resolver: zodResolver(taskSchema),
+  defaultValues: { title: '', description: '' },
+});
+```
+
+## Loading & Error States
+
+- Always show loading indicator
+- Always handle error state
+- Use Suspense boundaries for streaming
+
+## Accessibility
+
+- Semantic HTML (button, nav, main, article)
+- ARIA labels for icons
+- Keyboard navigation support
+- Focus management in modals

package/assets/cursor-rules/05-payments.mdc

@@ -0,0 +1,88 @@
+# Payments Rules (Stripe)
+
+## Setup
+
+```typescript
+// lib/stripe.ts
+import Stripe from 'stripe';
+
+export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
+  apiVersion: '2023-10-16',
+});
+```
+
+## Checkout Flow
+
+```typescript
+// Create checkout session
+const session = await stripe.checkout.sessions.create({
+  customer_email: user.email,
+  line_items: [{ price: priceId, quantity: 1 }],
+  mode: 'subscription', // or 'payment'
+  success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${baseUrl}/pricing`,
+  metadata: { userId: user.id },
+});
+
+return Response.json({ url: session.url });
+```
+
+## Webhook Handling
+
+```typescript
+// api/webhooks/stripe/route.ts
+import { headers } from 'next/headers';
+
+export async function POST(req: Request) {
+  const body = await req.text();
+  const signature = headers().get('stripe-signature')!;
+
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
+  } catch (err) {
+    return Response.json({ error: 'Invalid signature' }, { status: 400 });
+  }
+
+  switch (event.type) {
+    case 'checkout.session.completed':
+      await handleCheckoutComplete(event.data.object);
+      break;
+    case 'customer.subscription.updated':
+      await handleSubscriptionUpdate(event.data.object);
+      break;
+    case 'customer.subscription.deleted':
+      await handleSubscriptionCancel(event.data.object);
+      break;
+  }
+
+  return Response.json({ received: true });
+}
+```
+
+## Database Schema
+
+```prisma
+model Subscription {
+  id                 String   @id @default(cuid())
+  userId             String   @unique
+  stripeCustomerId   String   @unique
+  stripeSubscriptionId String @unique
+  stripePriceId      String
+  status             String   // active, canceled, past_due
+  currentPeriodEnd   DateTime
+  user               User     @relation(fields: [userId], references: [id])
+}
+```
+
+## Security
+
+- Verify webhook signatures
+- Use metadata to link Stripe to your users
+- Never trust client-side payment data
+- Log all payment events
+
+## Testing
+
+- Use Stripe CLI for local webhooks: `stripe listen --forward-to localhost:3000/api/webhooks/stripe`
+- Test cards: `4242424242424242` (success), `4000000000000002` (decline)