ultra-dex 1.7.3 → 2.2.0

package/README.md

@@ -1,205 +1,238 @@
 # Ultra-Dex CLI
 
-> Scaffold Ultra-Dex projects from the command line.
+> Scaffold Ultra-Dex projects from the command line, now with **AI-powered plan generation**.
 
-## First 10 Minutes
+## What's New in v2.1
 
 ```bash
-# 1. Create your project (2 min)
-npx ultra-dex init
+# 🚀 Generate a complete 34-section plan with AI
+npx ultra-dex generate "A task management SaaS for remote teams"
+
+# 🔧 Start AI-assisted development
+npx ultra-dex build --agent planner
 
-# 2. Open and review QUICK-START.md (3 min)
-cd your-project
-cat QUICK-START.md
+# 🔍 Review code against plan
+npx ultra-dex review
+
+# 📊 Quick alignment check
+npx ultra-dex align
+```
 
-# 3. Load Cursor rules for AI assistance (1 min)
-npx degit Srujan0798/Ultra-Dex/cursor-rules .cursor/rules
-# Then: cd .cursor/rules && ./load.sh database api auth
+## First 10 Minutes
 
-# 4. Start building with AI agents (4 min)
-# Use @Backend, @Frontend, @Database agents
-npx ultra-dex agents
+```bash
+# Option 1: AI-Generated Plan (Recommended)
+export ANTHROPIC_API_KEY=your-key  # or OPENAI_API_KEY or GOOGLE_AI_KEY
+npx ultra-dex generate "Your SaaS idea here"
 
-# You're ready to code!
+# Option 2: Manual Setup
+npx ultra-dex init
 ```
 
 ## Installation
 
 ```bash
 # Run directly with npx (no installation needed)
-npx ultra-dex init
+npx ultra-dex generate "Your idea"
 
 # Or install globally
 npm install -g ultra-dex
-ultra-dex init
+ultra-dex generate "Your idea"
 ```
 
-## Usage
+## AI Commands (v2.0+)
+
+### `generate` - AI Plan Generation
 
-### Initialize a new project
+Generate a complete implementation plan using AI:
 
 ```bash
-npx ultra-dex init
+# Basic usage
+npx ultra-dex generate "A booking platform for dog groomers"
+
+# With options
+npx ultra-dex generate "idea" --provider openai --output ./my-project
+
+# Preview without calling AI
+npx ultra-dex generate "idea" --dry-run
 ```
 
-This will:
-1. Ask you about your SaaS idea
-2. Gather tech stack preferences
-3. Create starter files:
-   - `QUICK-START.md` - Pre-filled with your answers
-   - `CONTEXT.md` - Project context for AI agents
-   - `IMPLEMENTATION-PLAN.md` - Links to full resources
+**Options:**
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-p, --provider` | AI provider (claude, openai, gemini) | claude |
+| `-m, --model` | Specific model to use | provider default |
+| `-o, --output` | Output directory | current |
+| `-k, --key` | API key | env variable |
+| `--dry-run` | Show structure only | false |
 
-### List examples
+### `build` - AI-Assisted Development
+
+Start development with AI agents:
 
 ```bash
-npx ultra-dex examples
+# Interactive agent selection
+npx ultra-dex build
+
+# Specific agent
+npx ultra-dex build --agent backend --task "Create user API endpoints"
+
+# Copy to clipboard for external AI
+npx ultra-dex build --agent planner --copy
 ```
 
-Shows links to fully filled Ultra-Dex examples:
-- TaskFlow (Task Management)
-- InvoiceFlow (Invoicing)
-- HabitStack (Habit Tracking)
+**Available Agents:**
+| Agent | Role |
+|-------|------|
+| `planner` | Break down features into atomic tasks |
+| `cto` | Architecture decisions |
+| `backend` | API endpoints and business logic |
+| `frontend` | UI components and pages |
+| `database` | Schema design and migrations |
+| `auth` | Authentication and authorization |
+| `security` | Security audit |
+| `testing` | Write and run tests |
+| `reviewer` | Code review |
+| `devops` | Deployment and CI/CD |
+
+### `review` - Code Review
 
-### Audit your project
+Check code alignment with plan:
 
 ```bash
-npx ultra-dex audit
+npx ultra-dex review
+npx ultra-dex review --dir ./src
 ```
 
-Checks your project for completeness:
-- Required files (QUICK-START.md, CONTEXT.md, etc.)
-- Key sections (idea, problem, MVP, tech stack)
-- Implementation details (database, API, auth)
+### `align` - Quick Score
 
-Outputs a score and grade (A-F) with suggestions.
+Get alignment score instantly:
 
-### List AI agents
+```bash
+npx ultra-dex align
+npx ultra-dex align --json  # Machine-readable output
+```
 
+**Environment Variables:**
 ```bash
-npx ultra-dex agents
+ANTHROPIC_API_KEY=sk-ant-...  # Claude (recommended)
+OPENAI_API_KEY=sk-...         # OpenAI
+GOOGLE_AI_KEY=...             # Gemini
 ```
 
-Shows available AI agent prompts:
-- CTO, Backend, Frontend, Database
-- Auth, DevOps, Reviewer, Debugger, Planner
+### `init`
 
-### Get agent prompt
+Interactive project setup:
 
 ```bash
-npx ultra-dex agent backend
+npx ultra-dex init
+```
+
+Generate a runnable scaffold:
+
+```bash
+npx ultra-dex init --live --stack next15-prisma-clerk
 ```
 
-Prints the full agent prompt. Copy and paste into your AI tool (Cursor, Claude, ChatGPT).
+Presets: `next15-prisma-clerk`, `remix-supabase`, `sveltekit-drizzle`.
 
-### Set up git hooks
+### `audit`
+
+Check project completeness:
 
 ```bash
-npx ultra-dex hooks
+npx ultra-dex audit
 ```
 
-Installs a pre-commit hook that:
-- Validates project structure before each commit
-- Blocks commits if required files are missing
-- Can be bypassed with `git commit --no-verify`
+### `agents`
+
+List and use AI agent prompts:
 
-Remove with: `npx ultra-dex hooks --remove`
+```bash
+npx ultra-dex agents           # List all agents
+npx ultra-dex agent backend    # Show specific agent
+npx ultra-dex pack backend     # Package context + agent
+```
 
-### Fetch assets for offline use
+### `fetch`
+
+Download assets for offline use:
 
 ```bash
 npx ultra-dex fetch
+npx ultra-dex fetch --agents --rules
 ```
 
-Downloads all Ultra-Dex assets locally for offline development:
-- Cursor rules (12 .mdc files)
-- Agent prompts (16 agents)
-- Documentation and guides
+### `sync`
 
-Options:
-- `--dir <path>` - Target directory (default: `.ultra-dex`)
-- `--agents` - Fetch only agent prompts
-- `--rules` - Fetch only cursor rules
-- `--docs` - Fetch only documentation
+Auto-update CONTEXT.md with a codebase snapshot:
 
-After fetching, copy to your project:
 ```bash
-cp -r .ultra-dex/cursor-rules .cursor/rules
-cp -r .ultra-dex/agents .agents
+npx ultra-dex sync
 ```
 
-## Commands
+### Other Commands
 
 | Command | Description |
 |---------|-------------|
-| `ultra-dex init` | Initialize a new project |
-| `ultra-dex audit` | Audit project for completeness |
-| `ultra-dex examples` | List available examples |
-| `ultra-dex agents` | List available AI agents |
-| `ultra-dex agent <name>` | Show specific agent prompt |
-| `ultra-dex pack <agent>` | Package context + agent for any AI |
-| `ultra-dex hooks` | Set up git pre-commit hooks |
-| `ultra-dex fetch` | Download assets for offline use |
-| `ultra-dex validate` | Validate project structure |
-| `ultra-dex workflow <feature>` | Show workflow for a feature |
-| `ultra-dex suggest` | Get AI agent suggestions |
-| `ultra-dex --help` | Show help |
-| `ultra-dex --version` | Show version |
+| `init` | Initialize a new project |
+| `init --preview` | Preview files without creating them |
+| `init --live` | Generate a runnable scaffold |
+| `audit` | Audit project for completeness |
+| `examples` | List available examples |
+| `agents` | List AI agents |
+| `agent <name>` | Show specific agent prompt |
+| `pack <agent>` | Package context + agent |
+| `hooks` | Set up git pre-commit hooks |
+| `fetch` | Download assets for offline |
+| `serve` | Serve context over HTTP |
+| `sync` | Auto-sync CONTEXT.md |
+| `validate` | Validate project structure |
+| `workflow <feature>` | Show workflow for a feature |
+| `suggest` | Get AI agent suggestions |
+| `--help` | Show help |
+| `--version` | Show version |
+
+## Example: AI Generation
 
-## Options
+```bash
+$ npx ultra-dex generate "A booking platform for dog groomers"
 
-### init
+🚀 Ultra-Dex AI Plan Generator
 
-| Option | Description |
-|--------|-------------|
-| `-n, --name <name>` | Project name (skips prompt) |
-| `-d, --dir <directory>` | Output directory (default: current) |
+✔ AI modules loaded
 
-### audit
+📝 Idea: "A booking platform for dog groomers"
 
-| Option | Description |
-|--------|-------------|
-| `-d, --dir <directory>` | Directory to audit (default: current) |
+✓ Using Claude (Anthropic) (claude-sonnet-4-20250514)
 
-## Example
+📊 Estimated Generation:
+   Input tokens:  ~2,650
+   Output tokens: ~40,000
+   Estimated cost: ~$0.45
 
-```bash
-$ npx ultra-dex init
-
-╔═══════════════════════════════════════════════════════════╗
-║   ULTRA-DEX                                               ║
-║   From Idea to Production-Ready SaaS                      ║
-╚═══════════════════════════════════════════════════════════╝
-
-Welcome to Ultra-Dex! Let's plan your SaaS.
-
-? What's your project name? my-saas
-? What are you building? A booking platform for dog groomers
-? Who is it for? Independent dog grooming businesses
-? Problem #1 you're solving: Manual booking via phone is time-consuming
-? Problem #2 you're solving: No-shows cost money
-? Problem #3 you're solving: No online presence
-? Most important MVP feature: Online booking calendar
-? Frontend framework: Next.js
-? Database: PostgreSQL
-? Authentication: NextAuth
-? Payments: Stripe
-? Hosting: Vercel
-
-✔ Project created successfully!
-
-Files created:
-  my-saas/
-  ├── QUICK-START.md
-  ├── CONTEXT.md
-  ├── IMPLEMENTATION-PLAN.md
-  ├── .cursor/rules/ (11 AI rule files)
-  └── .agents/ (9 AI agent prompts)
+? Proceed with generation? Yes
+
+⚡ Generating 34-section implementation plan...
+
+✔ Generation complete!
+
+✅ All 34 sections generated
+   Tokens used: 42,350 tokens (2,650 in / 39,700 out)
+   Actual cost: $0.52
+
+📦 Project: GroomBook
+
+✓ Created ./IMPLEMENTATION-PLAN.md
+✓ Created ./QUICK-START.md
+✓ Created ./CONTEXT.md
+
+🎉 Generation complete!
 
 Next steps:
-  1. cd my-saas
-  2. Open QUICK-START.md and complete it
-  3. Start building! 🚀
+  1. Review IMPLEMENTATION-PLAN.md
+  2. Customize sections as needed
+  3. Start building with: npx ultra-dex init
 ```
 
 ## Links

package/assets/agents/0-orchestration/orchestrator.md

@@ -0,0 +1,225 @@
+# @Orchestrator - Meta Agent
+
+> **Role**: Coordinate all 15 agents for complete feature implementation
+> **When to Use**: Building a complete feature that spans architecture, implementation, security, testing, and deployment
+
+---
+
+## System Prompt
+
+You are the **Ultra-Dex Orchestrator**, a meta-agent that coordinates all 15 specialized agents to build complete, production-ready features. Your job is to break down features into agent handoffs and ensure nothing falls through the cracks.
+
+---
+
+## Your Responsibilities
+
+1. **Analyze** the feature request and identify all required components
+2. **Plan** the agent workflow sequence
+3. **Coordinate** handoffs between agents with clear context
+4. **Verify** each phase before moving to the next
+5. **Ensure** production readiness at the end
+
+---
+
+## Agent Workflow Template
+
+For any feature, follow this sequence:
+
+### Phase 1: Planning (Leadership Tier)
+```
+@Planner → Break down into atomic tasks (4-9 hours each)
+@Research → Evaluate technology options if needed
+@CTO → Approve architecture and tech decisions
+```
+
+### Phase 2: Implementation (Development Tier)
+```
+@Database → Schema design and migrations
+@Backend → API endpoints and business logic
+@Frontend → UI components and user flows
+```
+
+### Phase 3: Security (Security Tier)
+```
+@Auth → Authentication and authorization
+@Security → Security audit and vulnerability check
+```
+
+### Phase 4: Quality (Quality Tier)
+```
+@Testing → Write and run tests
+@Reviewer → Code review and approval
+@Documentation → Update docs if needed
+```
+
+### Phase 5: Deployment (DevOps Tier)
+```
+@DevOps → Deploy to staging → production
+```
+
+### Phase 6: Optimization (Specialist Tier - if needed)
+```
+@Performance → Optimize slow paths
+@Refactoring → Clean up code debt
+```
+
+---
+
+## Orchestration Prompt
+
+Use this prompt to start any complete feature:
+
+```markdown
+## Feature: [FEATURE NAME]
+
+### 1. Requirements
+- [What the feature does]
+- [Who uses it]
+- [Success criteria]
+
+### 2. Agent Workflow
+| Phase | Agent | Task | Status |
+|-------|-------|------|--------|
+| Planning | @Planner | Break down tasks | [ ] |
+| Planning | @CTO | Architecture approval | [ ] |
+| Implementation | @Database | Schema design | [ ] |
+| Implementation | @Backend | API endpoints | [ ] |
+| Implementation | @Frontend | UI components | [ ] |
+| Security | @Auth | Auth implementation | [ ] |
+| Security | @Security | Security audit | [ ] |
+| Quality | @Testing | Write tests | [ ] |
+| Quality | @Reviewer | Code review | [ ] |
+| Deployment | @DevOps | Deploy to production | [ ] |
+
+### 3. Current Phase
+[PHASE NAME] - [AGENT] working on [TASK]
+
+### 4. Handoff Context
+[What the next agent needs to know]
+
+### 5. Blockers
+[Any issues preventing progress]
+```
+
+---
+
+## Example: Authentication Feature
+
+```markdown
+## Feature: User Authentication with Email + OAuth
+
+### 1. Requirements
+- Email/password login
+- Google OAuth
+- Protected routes
+- Session management
+
+### 2. Agent Workflow
+| Phase | Agent | Task | Status |
+|-------|-------|------|--------|
+| Planning | @Planner | Break into 6 tasks | [x] |
+| Planning | @CTO | Approve Clerk vs NextAuth | [x] |
+| Implementation | @Database | User schema + sessions | [x] |
+| Implementation | @Backend | Auth API routes | [x] |
+| Implementation | @Frontend | Login/signup pages | [x] |
+| Security | @Auth | Middleware + RLS | [x] |
+| Security | @Security | Security audit | [x] |
+| Quality | @Testing | Auth tests | [ ] |
+| Quality | @Reviewer | Code review | [ ] |
+| Deployment | @DevOps | Deploy with env vars | [ ] |
+
+### 3. Current Phase
+Quality - @Testing working on auth tests
+
+### 4. Handoff Context
+Auth implementation complete with:
+- Clerk integration (auth.ts)
+- Protected middleware (middleware.ts)
+- Login page (app/login/page.tsx)
+- User dashboard (app/dashboard/page.tsx)
+Test coverage needed for: login, logout, OAuth, protected routes
+
+### 5. Blockers
+None
+```
+
+---
+
+## Quick Orchestration Commands
+
+**Complete Feature:**
+```
+Orchestrate: [Feature Name]
+- Start from planning
+- Full agent workflow
+- Deploy when ready
+```
+
+**Partial Feature (skip planning):**
+```
+Orchestrate: [Feature Name]
+- Architecture: [Already decided]
+- Start from: @Database
+- End at: @Reviewer (no deploy yet)
+```
+
+**Hotfix (minimal workflow):**
+```
+Orchestrate Hotfix: [Bug Description]
+- @Debugger → @Testing → @DevOps
+- Skip planning/architecture
+```
+
+---
+
+## Handoff Protocol
+
+When transitioning between agents:
+
+1. **Summarize** what was completed
+2. **List** all files changed/created
+3. **Specify** what the next agent needs to do
+4. **Include** any constraints or decisions made
+5. **Link** to relevant documentation
+
+Example handoff:
+```markdown
+## Handoff: @Database → @Backend
+
+### Completed
+- User schema with multi-tenancy (orgId)
+- Session table for auth
+- Migration: 20240115_add_users.sql
+
+### Files Changed
+- prisma/schema.prisma (User, Session, Organization models)
+- prisma/migrations/20240115_add_users/
+
+### For @Backend
+- Create CRUD endpoints for User
+- Implement org-scoped queries (WHERE orgId = ?)
+- Auth middleware should set orgId from session
+
+### Constraints
+- All queries must be org-scoped (multi-tenant)
+- Use Prisma client, not raw SQL
+```
+
+---
+
+## When NOT to Use Orchestrator
+
+- **Simple bug fix**: Just use @Debugger
+- **Documentation update**: Just use @Documentation
+- **Performance tuning**: Just use @Performance
+- **Single component**: Use the specific agent directly
+
+**Use Orchestrator when:**
+- Building a complete new feature
+- Feature spans multiple tiers (DB + API + UI)
+- Security-sensitive features (auth, payments)
+- Features requiring deployment coordination
+
+---
+
+*Ultra-Dex v1.7.0 - Meta Orchestration for Production Features*