ultra-dex 1.7.2 → 1.8.0

package/assets/cursor-rules/load.ps1

@@ -0,0 +1,108 @@
+# Ultra-Dex Cursor Rules Loader for Windows
+# Usage: .\load.ps1 [domain|core|all]
+
+param(
+    [Parameter(Position=0)]
+    [string]$Selection = "core"
+)
+
+$SCRIPT_DIR = Split-Path -Parent $MyInvocation.MyCommand.Path
+$TARGET_DIR = ".cursor\rules"
+
+# Create target directory if it doesn't exist
+if (!(Test-Path $TARGET_DIR)) {
+    New-Item -ItemType Directory -Path $TARGET_DIR -Force | Out-Null
+}
+
+function Copy-Rules {
+    param([string[]]$Files)
+    foreach ($file in $Files) {
+        $sourcePath = Join-Path $SCRIPT_DIR $file
+        if (Test-Path $sourcePath) {
+            Copy-Item $sourcePath -Destination $TARGET_DIR -Force
+            Write-Host "  Copied: $file" -ForegroundColor Green
+        } else {
+            Write-Host "  Not found: $file" -ForegroundColor Yellow
+        }
+    }
+}
+
+Write-Host ""
+Write-Host "Ultra-Dex Cursor Rules Loader" -ForegroundColor Cyan
+Write-Host "=============================" -ForegroundColor Cyan
+Write-Host ""
+
+switch ($Selection.ToLower()) {
+    "core" {
+        Write-Host "Loading core rules..." -ForegroundColor White
+        Copy-Rules @("00-ultra-dex-core.mdc")
+    }
+    "database" {
+        Write-Host "Loading database rules..." -ForegroundColor White
+        Copy-Rules @("00-ultra-dex-core.mdc", "01-database.mdc")
+    }
+    "api" {
+        Write-Host "Loading API rules..." -ForegroundColor White
+        Copy-Rules @("00-ultra-dex-core.mdc", "02-api.mdc")
+    }
+    "auth" {
+        Write-Host "Loading auth rules..." -ForegroundColor White
+        Copy-Rules @("00-ultra-dex-core.mdc", "03-auth.mdc")
+    }
+    "frontend" {
+        Write-Host "Loading frontend rules..." -ForegroundColor White
+        Copy-Rules @("00-ultra-dex-core.mdc", "04-frontend.mdc")
+    }
+    "payments" {
+        Write-Host "Loading payments rules..." -ForegroundColor White
+        Copy-Rules @("00-ultra-dex-core.mdc", "05-payments.mdc")
+    }
+    "testing" {
+        Write-Host "Loading testing rules..." -ForegroundColor White
+        Copy-Rules @("00-ultra-dex-core.mdc", "06-testing.mdc")
+    }
+    "security" {
+        Write-Host "Loading security rules..." -ForegroundColor White
+        Copy-Rules @("00-ultra-dex-core.mdc", "07-security.mdc")
+    }
+    "deployment" {
+        Write-Host "Loading deployment rules..." -ForegroundColor White
+        Copy-Rules @("00-ultra-dex-core.mdc", "08-deployment.mdc")
+    }
+    "errors" {
+        Write-Host "Loading error handling rules..." -ForegroundColor White
+        Copy-Rules @("00-ultra-dex-core.mdc", "09-error-handling.mdc")
+    }
+    "performance" {
+        Write-Host "Loading performance rules..." -ForegroundColor White
+        Copy-Rules @("00-ultra-dex-core.mdc", "10-performance.mdc")
+    }
+    "all" {
+        Write-Host "Loading ALL rules..." -ForegroundColor White
+        $allFiles = Get-ChildItem -Path $SCRIPT_DIR -Filter "*.mdc" | Select-Object -ExpandProperty Name
+        Copy-Rules $allFiles
+    }
+    default {
+        Write-Host "Usage: .\load.ps1 [option]" -ForegroundColor Yellow
+        Write-Host ""
+        Write-Host "Options:" -ForegroundColor White
+        Write-Host "  core        Load core rules only (default)"
+        Write-Host "  database    Load core + database rules"
+        Write-Host "  api         Load core + API rules"
+        Write-Host "  auth        Load core + auth rules"
+        Write-Host "  frontend    Load core + frontend rules"
+        Write-Host "  payments    Load core + payments rules"
+        Write-Host "  testing     Load core + testing rules"
+        Write-Host "  security    Load core + security rules"
+        Write-Host "  deployment  Load core + deployment rules"
+        Write-Host "  errors      Load core + error handling rules"
+        Write-Host "  performance Load core + performance rules"
+        Write-Host "  all         Load ALL rules"
+        Write-Host ""
+        exit 1
+    }
+}
+
+Write-Host ""
+Write-Host "Rules loaded to: $TARGET_DIR" -ForegroundColor Green
+Write-Host ""

package/assets/cursor-rules/load.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# Ultra-Dex Cursor Rules Loader v2.0
+# Usage: ./load.sh [domains...]
+# Example: ./load.sh database api auth
+# Example: ./load.sh all (loads all rules)
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TARGET_DIR=".cursor/rules"
+
+echo "🚀 Ultra-Dex Cursor Rules Loader v2.0"
+echo ""
+
+# Check if Cursor is installed
+if command -v cursor &> /dev/null; then
+  echo "✓ Cursor detected"
+elif [ -d "/Applications/Cursor.app" ] || [ -d "$HOME/Applications/Cursor.app" ]; then
+  echo "✓ Cursor.app detected"
+else
+  echo "⚠️  Cursor not detected. Rules will still be copied."
+  echo "   Install Cursor: https://cursor.com"
+  echo ""
+fi
+
+# Create target directory
+mkdir -p "$TARGET_DIR"
+
+# Always copy core rules
+cp "$SCRIPT_DIR/00-ultra-dex-core.mdc" "$TARGET_DIR/"
+echo "✓ Loaded: 00-ultra-dex-core.mdc (core rules)"
+
+# If "all" is specified, copy everything
+if [ "$1" = "all" ]; then
+  for file in "$SCRIPT_DIR"/*.mdc; do
+    filename=$(basename "$file")
+    if [ "$filename" != "00-ultra-dex-core.mdc" ]; then
+      cp "$file" "$TARGET_DIR/"
+      echo "✓ Loaded: $filename"
+    fi
+  done
+  echo ""
+  echo "📁 All rules loaded to $TARGET_DIR/"
+  exit 0
+fi
+
+# If no arguments, show help
+if [ $# -eq 0 ]; then
+  echo ""
+  echo "Usage: ./load.sh [domains...]"
+  echo ""
+  echo "Available domains:"
+  echo "  database    - Prisma, schema, queries"
+  echo "  api         - API routes, validation, responses"
+  echo "  auth        - NextAuth configuration"
+  echo "  frontend    - React, components, state"
+  echo "  payments    - Stripe integration"
+  echo "  testing     - Vitest, Playwright"
+  echo "  security    - Input validation, auth, headers"
+  echo "  deployment  - Vercel, CI/CD, migrations"
+  echo "  error       - Error patterns, logging"
+  echo "  performance - Optimization, caching"
+  echo "  nextjs      - Next.js 15 App Router patterns"
+  echo "  tenancy     - SaaS multi-tenancy patterns"
+  echo "  all         - Load all rules"
+  echo ""
+  echo "Example: ./load.sh database api auth"
+  exit 0
+fi
+
+# Copy requested domains
+for domain in "$@"; do
+  # Map short names to file numbers
+  case "$domain" in
+    database)    file="01-database.mdc" ;;
+    api)         file="02-api.mdc" ;;
+    auth)        file="03-auth.mdc" ;;
+    frontend)    file="04-frontend.mdc" ;;
+    payments)    file="05-payments.mdc" ;;
+    testing)     file="06-testing.mdc" ;;
+    security)    file="07-security.mdc" ;;
+    deployment)  file="08-deployment.mdc" ;;
+    error)       file="09-error-handling.mdc" ;;
+    performance) file="10-performance.mdc" ;;
+    nextjs)      file="11-nextjs-v15.mdc" ;;
+    tenancy)     file="12-multi-tenancy.mdc" ;;
+    *)
+      echo "✗ Unknown domain: $domain"
+      continue
+      ;;
+  esac
+  
+  if [ -f "$SCRIPT_DIR/$file" ]; then
+    cp "$SCRIPT_DIR/$file" "$TARGET_DIR/"
+    echo "✓ Loaded: $file"
+  else
+    echo "✗ File not found: $file"
+  fi
+done
+
+echo ""
+echo "📁 Rules loaded to $TARGET_DIR/"
+echo ""
+echo "💡 Tip: Restart Cursor to apply new rules"

package/assets/docs/BUILD-AUTH-30M.md

@@ -0,0 +1,113 @@
+# Build Auth in 30 Minutes with Ultra-Dex
+
+> A practical, time-boxed script that uses Ultra-Dex agents to design and implement authentication.
+
+## Goal
+Build production-ready authentication (signup, login, session, and basic protections) in 30 minutes using Ultra-Dex.
+
+## Prerequisites
+- A project initialized with `npx ultra-dex init`.
+- A baseline tech stack (Next.js + Prisma) and auth approach (NextAuth or custom JWT).
+- `IMPLEMENTATION-PLAN.md` and `CONTEXT.md` available.
+
+---
+
+## 0–5 min: Planner + CTO alignment
+**Agent:** `@Planner` then `@CTO`
+
+**Planner prompt:**
+```
+Read IMPLEMENTATION-PLAN.md and CONTEXT.md.
+Act as @Planner.
+Task: Break down authentication into 4-5 atomic tasks (4-9h each) with acceptance criteria.
+```
+
+**CTO prompt:**
+```
+Read IMPLEMENTATION-PLAN.md and CONTEXT.md.
+Act as @CTO.
+Task: Approve auth architecture (session/JWT), password policy, and data model changes.
+```
+
+Output checklist:
+- Auth flow decided (JWT or session)
+- Password policy defined
+- Auth-related schema changes approved
+
+---
+
+## 5–12 min: Database + Backend design
+**Agent:** `@Database` then `@Backend`
+
+**Database prompt:**
+```
+Read IMPLEMENTATION-PLAN.md Section 5 and CONTEXT.md.
+Act as @Database.
+Task: Add/verify User + Session tables, indexes, and constraints for auth.
+Return Prisma schema changes.
+```
+
+**Backend prompt:**
+```
+Read IMPLEMENTATION-PLAN.md Sections 6-8 and CONTEXT.md.
+Act as @Backend.
+Task: Draft endpoints for signup/login/logout + validation + error handling.
+```
+
+Output checklist:
+- Schema changes with indexes
+- API endpoints defined
+- Validation schema defined
+
+---
+
+## 12–20 min: Security + Testing plan
+**Agent:** `@Security` then `@Testing`
+
+**Security prompt:**
+```
+Read IMPLEMENTATION-PLAN.md Sections 7 & 12.
+Act as @Security.
+Task: Audit auth design for OWASP risks; add rate limiting + secure cookie policy.
+```
+
+**Testing prompt:**
+```
+Read IMPLEMENTATION-PLAN.md Section 10.
+Act as @Testing.
+Task: Define test cases for signup/login/session invalidation.
+```
+
+Output checklist:
+- Rate limiting rules
+- Secure cookie settings
+- Test plan with edge cases
+
+---
+
+## 20–30 min: Implement + verify
+**Execution steps:**
+1. Implement schema changes (Prisma migration).
+2. Implement API endpoints with validation and error handling.
+3. Add basic tests for auth endpoints.
+4. Run quick verification checklist.
+
+**Quick verification (5-step):**
+- [ ] Works locally (signup/login)
+- [ ] Errors handled and validated
+- [ ] No secrets in code
+- [ ] Docs updated (if API changed)
+- [ ] Build passes
+
+---
+
+## Suggested Output Files
+- `prisma/schema.prisma`
+- `app/api/auth/*` (or `src/routes/auth/*`)
+- `src/**/__tests__/auth.test.ts`
+
+---
+
+## Next Step
+Use the 21-step checklist for full production readiness:
+- [CHECKLIST-21-STEP.md](./CHECKLIST-21-STEP.md)

package/assets/docs/CHECKLIST-21-STEP.md

@@ -0,0 +1,86 @@
+# 21-Step Task Verification Checklist
+
+> Use this for **EVERY atomic task** (4-9 hour completable units).
+> Copy this checklist into your PR or issue tracker.
+
+---
+
+## PLANNING (~20 min)
+
+- [ ] 1. **UNDERSTAND** - Requirements clearly defined (5 min)
+- [ ] 2. **ACCEPTANCE** - Acceptance criteria written (10 min)
+- [ ] 3. **DEPENDENCIES** - Dependencies identified (3 min)
+- [ ] 4. **ESTIMATE** - Estimated hours realistic 4-9h (2 min)
+
+## IMPLEMENTATION (~30 min review)
+
+- [ ] 5. **CONVENTIONS** - Code follows project conventions (5 min)
+- [ ] 6. **NO HARDCODE** - No hardcoded values - use env/constants (5 min)
+- [ ] 7. **ERRORS** - Error handling complete (10 min)
+- [ ] 8. **VALIDATION** - Input validation present (5 min)
+- [ ] 9. **TYPES** - TypeScript types - no `any` (5 min)
+
+## QUALITY (~45 min)
+
+- [ ] 10. **UNIT TESTS** - Unit tests written (included in dev time)
+- [ ] 11. **INTEGRATION** - Integration test if API/DB (15 min)
+- [ ] 12. **EDGE CASES** - Edge cases handled (15 min)
+- [ ] 13. **NO LOGS** - No console.logs left (2 min)
+- [ ] 14. **NO COMMENTS** - No commented-out code (2 min)
+
+## SECURITY (~15 min)
+
+- [ ] 15. **NO SECRETS** - No secrets in code (5 min)
+- [ ] 16. **AUTH** - Auth/permissions checked (5 min)
+- [ ] 17. **SANITIZE** - Input sanitized (5 min)
+
+## DOCUMENTATION (~10 min)
+
+- [ ] 18. **SELF-DOC** - Code is self-documenting (3 min)
+- [ ] 19. **COMMENTS** - Complex logic has comments (5 min)
+- [ ] 20. **API DOCS** - API changes documented (2 min)
+
+## FINAL (~15 min)
+
+- [ ] 21. **PRODUCTION** - Works in production environment (15 min)
+
+---
+
+## When to Use
+
+| Task Type | Checklist | Why |
+|-----------|-----------|-----|
+| **New feature** (4-9 hours) | Full 21-step | Production quality required |
+| **Bug fix** (<2 hours) | 5-step mini | Full version is overkill |
+| **Refactor** | Full 21-step | Quality gates matter |
+| **Docs update** | Skip | Not code |
+
+## Adaptive Time Estimates
+
+| Task Size | Planning | Implementation | Validation | Delivery |
+|-----------|----------|----------------|------------|----------|
+| 1 hour (small fix) | 5 min | 30 min | 10 min | 5 min |
+| 3 hours (medium) | 10 min | 2 hrs | 20 min | 10 min |
+| 6 hours (large feature) | 20 min | 4 hrs | 30 min | 20 min |
+
+**For tasks <2 hours:** Use the 5-step mini-checklist in [02-HOW-TO-USE.md](../@%20Ultra%20DeX/Saas%20plan/02-HOW-TO-USE.md)
+
+---
+
+## How to Use in Git Workflow
+
+### Option 1: GitHub PR Template (Recommended)
+```bash
+cp CHECKLIST-21-STEP.md .github/PULL_REQUEST_TEMPLATE.md
+```
+Every PR automatically includes the checklist.
+
+### Option 2: Copy into PR Description
+Copy the checklist above into your PR description.
+
+### Option 3: Issue Tracker
+Copy into Jira/Linear/GitHub Issues to track per task.
+
+---
+
+**Rule:** If any box is unchecked, the task is NOT complete.

package/assets/docs/CODEMAP.md

@@ -0,0 +1,229 @@
+## Ultra-Dex: End-to-End SaaS Development Framework
+Ultra-Dex codemap traces the complete SaaS development framework from idea capture through production deployment. Key flows include user onboarding [1a-1d], the 34-section template system [2a-2d], quality verification [3a-3d], phased development approach [4a-4d], AI agent integration [5a-5c], and the production pipeline [6a-6d].
+### 1. User Onboarding Journey
+How a developer discovers, initializes, and starts using Ultra-Dex
+### 1a. Entry Point Navigation (`README.md:23`)
+Main README guides users to 5-minute QUICK-START
+```text
+## Quick Start
+
+|| Your Goal | Go Here ||
+||-----------|---------||
+|| **Start in 5 minutes** | [QUICK-START.md](../@%20Ultra%20DeX/Saas%20plan/01-QUICK-START.md) |
+```
+### 1b. CLI Initialization (`ultra-dex.js:115`)
+CLI tool scaffolds new projects interactively
+```text
+program
+  .command('init')
+  .description('Initialize a new Ultra-Dex project')
+```
+### 1c. Project Setup Questions (`ultra-dex.js:124`)
+Gathers core project information and tech stack
+```text
+const answers = await inquirer.prompt([
+  {
+    type: 'input',
+    name: 'projectName',
+    message: 'What\'s your project name?',
+```
+### 1d. Template Generation (`ultra-dex.js:235`)
+Creates personalized starter files
+```text
+await fs.writeFile(path.join(outputDir, 'QUICK-START.md'), quickStart);
+      await fs.writeFile(path.join(outputDir, 'CONTEXT.md'), context);
+```
+### 2. Idea to Implementation Plan
+Transforming raw ideas into structured 34-section implementation plans
+### 2a. Rapid Idea Capture (`QUICK-START.md:7`)
+5-minute template to capture core concept
+```text
+## 1. Your Idea (2 sentences max)
+
+**What:**
+**For whom:**
+```
+### 2b. AI Agent Instructions (`04-Imp-Template.md:3`)
+Template header guides AI to fill all 34 sections
+```text
+RAW IDEA: "[YOUR IDEA HERE]"
+
+INSTRUCTIONS FOR AI AGENTS:
+
+**Content Requirements:**
+- Generate complete, detailed content for ALL sections (1-34)
+```
+### 2c. Structured Planning Start (`04-Imp-Template.md:41`)
+First section of comprehensive template
+```text
+## SECTION 1: HIGH-LEVEL SUMMARY
+
+### 1.1 Product Vision (One-liner)
+
+[Clear, compelling statement of what the product does]
+```
+### 2d. Feature Definition (`04-Imp-Template.md:79`)
+Structured MVP feature planning with acceptance criteria
+```text
+### 2.1 MVP Features (Must-Have - P0)
+
+List core features required for minimum viable product:
+
+**Feature 1: [Name]**
+- Simple Description: [What it does in one sentence]
+```
+### 3. Quality Verification System
+The 21-step verification framework ensuring production-ready code
+### 3a. Atomic Task Principle (`METHODOLOGY.md:9`)
+Core methodology: tasks sized for single sessions
+```text
+### 1. Atomic Tasks (4-9 Hours)
+
+Every task must be completable in **one focused session**.
+```
+### 3b. Verification Checklist (`METHODOLOGY.md:23`)
+Mandatory 21-step quality gates
+```text
+### 2. The 21-Step Verification
+
+Every completed task MUST pass this checklist:
+
+```
+PLANNING
+|[ ] 1. Requirements clearly defined
+|[ ] 2. Acceptance criteria written
+```
+### 3c. Realistic Estimation (`METHODOLOGY.md:66`)
+Buffer calculations for accurate timelines
+```text
+### 3. Overhead Calculation
+
+Raw estimates are always wrong. Apply these multipliers:
+
+|| Factor | Add | When ||
+||--------|-----|------||
+|| Testing | +25% | Always |
+```
+### 3d. PR Checklist Template (`VERIFICATION.md:10`)
+Copy-paste template for pull requests
+```text
+## 21-Step Verification
+
+### PLANNING (~20 min)
+- [ ] 1. **UNDERSTAND** - Requirements clearly defined
+```
+### 4. Phased Development Approach
+How teams adapt the framework for different development phases
+### 4a. Anti-Paralysis Principle (`02-HOW-TO-USE.md:7`)
+Key guidance to avoid documentation overwhelm
+```text
+## The Golden Rule
+
+**Start coding after 20% of documentation.**
+
+Don't fill all 34 sections before writing code. That's the paralysis trap.
+```
+### 4b. Phase 1 Foundation (`02-HOW-TO-USE.md:17`)
+Minimal sections needed before coding begins
+```text
+### Phase 1: Foundation (Week 1-2)
+
+**Fill ONLY these sections before coding:**
+
+|| Section | What to Fill | Time ||
+||---------|--------------|------||
+|| 1. High-Level Summary | 2-sentence description | 10 min |
+```
+### 4c. Solo Developer Adaptation (`02-HOW-TO-USE.md:79`)
+Streamlined approach for individual developers
+```text
+### For Solo Developers
+
+**Simplified workflow:**
+
+```
+1. Fill Sections 1-12 only (2-3 hours)
+2. Skip to Section 16 for tasks
+3. Use 5-step mini-checklist (below)
+```
+### 4d. App-Specific Guidance (`02-HOW-TO-USE.md:142`)
+Tailored section priorities by product type
+```text
+### Section Picker by App Type
+
+### B2B SaaS (Stripe, Linear, Notion style)
+
+**High Priority:**
+|- Section 21: Security Guidelines
+|- Section 27: Error Handling
+```
+### 5. AI Agent Integration
+How Ultra-Dex works with various AI assistants for implementation
+### 5a. AI Agent Support (`README.md:105`)
+Framework designed to work with any AI
+```text
+## Using with AI Agents
+
+See [agents/](../agents/) and [00-AGENT_INDEX.md](../agents/00-AGENT_INDEX.md) for prompts:
+
+|| Agent | Purpose ||
+||-------|---------||
+|| Planner | Generate implementation plan from idea |
+```
+### 5b. Planner Agent Prompt (`agents/1-leadership/planner.md`)
+System prompt for AI planning assistance
+```text
+You are an Ultra-Dex Planner Agent. Your role is to take a raw idea and generate a complete, production-ready implementation plan.
+```
+### 5c. AI-Agnostic Design (`README.md:8`)
+Framework philosophy of flexibility
+```text
+## Core Philosophy: "Your Skeleton, Not Your Cage"
+
+Ultra-Dex is a **backbone** that works with ANY AI/LLM:
+- Users bring their own AI (Claude, GPT, Gemini, Copilot, etc.)
+```
+### 6. Production Pipeline Flow
+The complete journey from idea to production-ready application
+### 6a. Main Pipeline (`README.md:69`)
+Visual representation of the development flow
+```text
+```
+💡 IDEA
+    ↓
+📋 QUICK-START (5 minutes)
+    ↓
+📝 FULL TEMPLATE (34 sections)
+    ↓
+✅ 21-STEP VERIFICATION (per task)
+    ↓
+🚀 PRODUCTION-READY
+```
+### 6b. Detailed Workflow (`SaaS Workflow.md:5`)
+Extended workflow with execution phase
+```text
+```text
+💡 IDEA
+    ↓
+📋 IMPLEMENTATION PLAN (what to build, in what order)
+    ↓
+📏 THESE RULES (how to build with quality)
+    ↓
+⚙️ EXECUTION (AI agents + your guidance)
+```
+### 6c. Progression Guidance (`QUICK-START.md:54`)
+Clear next steps after initial capture
+```text
+**Done? Next Steps:**
+
+**Ready for full planning?**
+Copy this into [04-Imp-Template.md](../@%20Ultra%20DeX/Saas%20plan/04-Imp-Template.md) Section 1 and continue filling out the detailed sections.
+```
+### 6d. Onboarding Path (`README.md:131`)
+Multiple entry points for different user needs
+```text
+## Get Started
+
+1. **New to Ultra-Dex?** → Start with [QUICK-START.md](../@%20Ultra%20DeX/Saas%20plan/01-QUICK-START.md)
+2. **Want to see it in action?** → Read [TaskFlow-Complete.md](../@%20Ultra%20DeX/Saas%20plan/Examples/TaskFlow-Complete.md)
+```