ultra-dex 1.3.0 → 1.7.2

package/README.md

@@ -2,6 +2,27 @@
 
 > Scaffold Ultra-Dex projects from the command line.
 
+## First 10 Minutes
+
+```bash
+# 1. Create your project (2 min)
+npx ultra-dex init
+
+# 2. Open and review QUICK-START.md (3 min)
+cd your-project
+cat QUICK-START.md
+
+# 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
+
+# 4. Start building with AI agents (4 min)
+# Use @Backend, @Frontend, @Database agents
+npx ultra-dex agents
+
+# You're ready to code!
+```
+
 ## Installation
 
 ```bash
@@ -71,6 +92,19 @@ npx ultra-dex agent backend
 
 Prints the full agent prompt. Copy and paste into your AI tool (Cursor, Claude, ChatGPT).
 
+### Set up git hooks
+
+```bash
+npx ultra-dex hooks
+```
+
+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`
+
+Remove with: `npx ultra-dex hooks --remove`
+
 ## Commands
 
 | Command | Description |
@@ -80,6 +114,11 @@ Prints the full agent prompt. Copy and paste into your AI tool (Cursor, Claude,
 | `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 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 |
 

package/bin/ultra-dex.js

@@ -109,7 +109,7 @@ Setting up the implementation plan.
 program
   .name('ultra-dex')
   .description('CLI for Ultra-Dex SaaS Implementation Framework')
-  .version('1.3.0');
+  .version('1.7.1');
 
 program
   .command('init')
@@ -300,10 +300,21 @@ ${answers.ideaWhat} for ${answers.ideaFor}.
               path.join(rulesDir, file)
             );
           }
+        // Also generate .github/copilot-instructions.md for Copilot users
+          const coreRulePath = path.join(cursorRulesPath, '00-ultra-dex-core.mdc');
+          try {
+            const coreContent = await fs.readFile(coreRulePath, 'utf-8');
+            const dotGithub = path.join(outputDir, '.github');
+            await fs.mkdir(dotGithub, { recursive: true });
+            await fs.writeFile(path.join(dotGithub, 'copilot-instructions.md'), coreContent);
+          } catch (e) {
+            // Core rule not available - skip Copilot setup
+          }
         } catch (err) {
-          // Cursor rules not available (npm package, not local)
-          console.log(chalk.yellow('\n  Note: cursor-rules not bundled. Download from GitHub:'));
-          console.log(chalk.blue('  https://github.com/Srujan0798/Ultra-Dex/tree/main/cursor-rules'));
+          // Cursor rules not bundled - intentional design choice for npm package size
+          console.log(chalk.gray('\n  📦 Cursor rules not bundled (keeps npm package <50KB)'));
+          console.log(chalk.cyan('  Quick setup: npx degit Srujan0798/Ultra-Dex/cursor-rules .cursor/rules'));
+          console.log(chalk.blue('  Or download: https://github.com/Srujan0798/Ultra-Dex/tree/main/cursor-rules'));
         }
       }
 
@@ -313,21 +324,25 @@ ${answers.ideaWhat} for ${answers.ideaFor}.
         try {
           await fs.copyFile(templatePath, path.join(outputDir, 'docs', 'MASTER-PLAN.md'));
         } catch (err) {
-          console.log(chalk.yellow('\n  Note: Full template not bundled. Download from GitHub:'));
-          console.log(chalk.blue('  https://github.com/Srujan0798/Ultra-Dex/blob/main/%40%20Ultra%20DeX/Saas%20plan/04-Imp-Template.md'));
+          // Template not bundled - keeps npm package lightweight
+          console.log(chalk.gray('\n  📦 Full template not bundled (5,500 lines - too large for npm)'));
+          console.log(chalk.cyan('  Quick fetch: curl -O https://raw.githubusercontent.com/Srujan0798/Ultra-Dex/main/%40%20Ultra%20DeX/Saas%20plan/04-Imp-Template.md'));
+          console.log(chalk.blue('  Or view: https://github.com/Srujan0798/Ultra-Dex/blob/main/%40%20Ultra%20DeX/Saas%20plan/04-Imp-Template.md'));
         }
       }
 
       // Copy docs if requested
       if (answers.includeDocs) {
-        const verificationPath = path.resolve(__dirname, '../../VERIFICATION.md');
-        const agentPath = path.resolve(__dirname, '../../AGENT-INSTRUCTIONS.md');
+        const verificationPath = path.resolve(__dirname, '../../docs/VERIFICATION.md');
+        const agentPath = path.resolve(__dirname, '../../agents/AGENT-INSTRUCTIONS.md');
         try {
           await fs.copyFile(verificationPath, path.join(outputDir, 'docs', 'CHECKLIST.md'));
           await fs.copyFile(agentPath, path.join(outputDir, 'docs', 'AI-PROMPTS.md'));
         } catch (err) {
-          console.log(chalk.yellow('\n  Note: Docs not bundled. Download from GitHub:'));
-          console.log(chalk.blue('  https://github.com/Srujan0798/Ultra-Dex'));
+          // Docs not bundled - intentional for npm package size
+          console.log(chalk.gray('\n  📦 Verification & instructions not bundled (npm size optimization)'));
+          console.log(chalk.cyan('  Quick setup: npx degit Srujan0798/Ultra-Dex/docs docs'));
+          console.log(chalk.blue('  Or view: https://github.com/Srujan0798/Ultra-Dex/tree/main/docs'));
         }
       }
 
@@ -338,17 +353,36 @@ ${answers.ideaWhat} for ${answers.ideaFor}.
 
         const agentsSourcePath = path.resolve(__dirname, '../../agents');
         try {
-          const agentFiles = await fs.readdir(agentsSourcePath);
-          for (const file of agentFiles.filter(f => f.endsWith('.md'))) {
-            await fs.copyFile(
-              path.join(agentsSourcePath, file),
-              path.join(agentsDir, file)
-            );
+          // Copy tier directories and agent files
+          const tiers = ['1-leadership', '2-development', '3-security', '4-devops', '5-quality', '6-specialist'];
+          for (const tier of tiers) {
+            const tierDir = path.join(agentsDir, tier);
+            await fs.mkdir(tierDir, { recursive: true });
+
+            const tierPath = path.join(agentsSourcePath, tier);
+            const tierFiles = await fs.readdir(tierPath);
+            for (const file of tierFiles.filter(f => f.endsWith('.md'))) {
+              await fs.copyFile(
+                path.join(tierPath, file),
+                path.join(tierDir, file)
+              );
+            }
           }
+
+          // Copy agent index and README
+          await fs.copyFile(
+            path.join(agentsSourcePath, '00-AGENT_INDEX.md'),
+            path.join(agentsDir, '00-AGENT_INDEX.md')
+          );
+          await fs.copyFile(
+            path.join(agentsSourcePath, 'README.md'),
+            path.join(agentsDir, 'README.md')
+          );
         } catch (err) {
-          // Agents not available (npm package, not local)
-          console.log(chalk.yellow('\n  Note: Agent prompts not bundled. Download from GitHub:'));
-          console.log(chalk.blue('  https://github.com/Srujan0798/Ultra-Dex/tree/main/agents'));
+          // Agents not bundled - intentional for npm package size
+          console.log(chalk.gray('\n  📦 Agent prompts not bundled (npm size optimization)'));
+          console.log(chalk.cyan('  Quick setup: npx degit Srujan0798/Ultra-Dex/agents .agents'));
+          console.log(chalk.blue('  Or view: https://github.com/Srujan0798/Ultra-Dex/tree/main/agents'));
         }
       }
 
@@ -370,7 +404,7 @@ ${answers.ideaWhat} for ${answers.ideaFor}.
         console.log(chalk.gray('  ├── .cursor/rules/ (11 AI rule files)'));
       }
       if (answers.includeAgents) {
-        console.log(chalk.gray('  └── .agents/ (9 AI agent prompts)'));
+        console.log(chalk.gray('  └── .agents/ (15 AI agent prompts in 6 tiers)'));
       }
 
       console.log('\n' + chalk.bold('Next steps:'));
@@ -552,35 +586,52 @@ program
     });
   });
 
-// Agent definitions
+// Agent definitions (organized by tier)
 const AGENTS = [
-  { name: 'cto', description: 'Architecture & tech decisions', file: 'cto.md' },
-  { name: 'backend', description: 'API, database, server logic', file: 'backend.md' },
-  { name: 'frontend', description: 'UI, components, styling', file: 'frontend.md' },
-  { name: 'database', description: 'Schema design, queries, migrations', file: 'database.md' },
-  { name: 'auth', description: 'Authentication & authorization', file: 'auth.md' },
-  { name: 'devops', description: 'Deployment, CI/CD, infrastructure', file: 'devops.md' },
-  { name: 'reviewer', description: 'Code review & quality check', file: 'reviewer.md' },
-  { name: 'debugger', description: 'Bug fixing & troubleshooting', file: 'debugger.md' },
-  { name: 'planner', description: 'Task breakdown & planning', file: 'planner.md' },
+  // Leadership Tier
+  { name: 'cto', description: 'Architecture & tech decisions', file: '1-leadership/cto.md', tier: 'Leadership' },
+  { name: 'planner', description: 'Task breakdown & planning', file: '1-leadership/planner.md', tier: 'Leadership' },
+  { name: 'research', description: 'Technology evaluation & comparison', file: '1-leadership/research.md', tier: 'Leadership' },
+  // Development Tier
+  { name: 'backend', description: 'API & server logic', file: '2-development/backend.md', tier: 'Development' },
+  { name: 'database', description: 'Schema design & queries', file: '2-development/database.md', tier: 'Development' },
+  { name: 'frontend', description: 'UI & components', file: '2-development/frontend.md', tier: 'Development' },
+  // Security Tier
+  { name: 'auth', description: 'Authentication & authorization', file: '3-security/auth.md', tier: 'Security' },
+  { name: 'security', description: 'Security audits & vulnerability fixes', file: '3-security/security.md', tier: 'Security' },
+  // DevOps Tier
+  { name: 'devops', description: 'Deployment & infrastructure', file: '4-devops/devops.md', tier: 'DevOps' },
+  // Quality Tier
+  { name: 'debugger', description: 'Bug fixing & troubleshooting', file: '5-quality/debugger.md', tier: 'Quality' },
+  { name: 'documentation', description: 'Technical writing & docs maintenance', file: '5-quality/documentation.md', tier: 'Quality' },
+  { name: 'reviewer', description: 'Code review & quality check', file: '5-quality/reviewer.md', tier: 'Quality' },
+  { name: 'testing', description: 'QA & test automation', file: '5-quality/testing.md', tier: 'Quality' },
+  // Specialist Tier
+  { name: 'performance', description: 'Performance optimization', file: '6-specialist/performance.md', tier: 'Specialist' },
+  { name: 'refactoring', description: 'Code quality & design patterns', file: '6-specialist/refactoring.md', tier: 'Specialist' },
 ];
 
 program
   .command('agents')
   .description('List available AI agent prompts')
   .action(() => {
-    console.log(chalk.bold('\n🤖 Available Ultra-Dex Agents\n'));
-    console.log(chalk.gray('Copy these prompts into your AI tool (Cursor, Claude, ChatGPT, etc.)\n'));
-
-    AGENTS.forEach((agent, i) => {
-      console.log(chalk.cyan(`  ${i + 1}. ${agent.name}`) + chalk.gray(` - ${agent.description}`));
+    console.log(chalk.bold('\n🤖 Ultra-Dex AI Agents (15 Total)\n'));
+    console.log(chalk.gray('Organized by tier for production pipeline\n'));
+
+    let currentTier = '';
+    AGENTS.forEach((agent) => {
+      if (agent.tier !== currentTier) {
+        currentTier = agent.tier;
+        console.log(chalk.bold(`\n  ${currentTier} Tier:`));
+      }
+      console.log(chalk.cyan(`    ${agent.name}`) + chalk.gray(` - ${agent.description}`));
     });
 
     console.log('\n' + chalk.bold('Usage:'));
-    console.log(chalk.gray('  ultra-dex agent <name>   Show agent prompt (copy to clipboard)'));
-    console.log(chalk.gray('  ultra-dex agent backend  Example: show backend agent prompt'));
+    console.log(chalk.gray('  ultra-dex agent <name>   Show agent prompt'));
+    console.log(chalk.gray('  ultra-dex agent backend  Example: show backend agent'));
 
-    console.log('\n' + chalk.gray('Full docs: https://github.com/Srujan0798/Ultra-Dex/tree/main/agents\n'));
+    console.log('\n' + chalk.gray('Agent Index: https://github.com/Srujan0798/Ultra-Dex/blob/main/agents/00-AGENT_INDEX.md\n'));
   });
 
 program
@@ -607,12 +658,634 @@ program
       console.log(chalk.gray('─'.repeat(60)));
       console.log(chalk.bold('\n📋 Copy the above prompt and paste into your AI tool.\n'));
     } catch (err) {
-      // Agent file not bundled (npm package)
+      // Agent file not bundled (npm package) - show URL instead
       console.log(chalk.bold(`\n🤖 ${agent.name.toUpperCase()} Agent\n`));
-      console.log(chalk.yellow('Agent prompts are not bundled with the npm package.'));
-      console.log(chalk.gray('\nDownload from GitHub:'));
+      console.log(chalk.gray('View full prompt on GitHub:'));
       console.log(chalk.blue(`  https://github.com/Srujan0798/Ultra-Dex/blob/main/agents/${agent.file}\n`));
     }
   });
 
+// Pack command - assemble context for any AI tool
+program
+  .command('pack <agent>')
+  .description('Package project context + agent prompt for any AI tool')
+  .option('-c, --clipboard', 'Copy to clipboard (requires pbcopy/xclip)')
+  .action(async (agentName, options) => {
+    // Find agent
+    const agent = AGENTS.find(a => a.name.toLowerCase() === agentName.toLowerCase());
+    if (!agent) {
+      console.log(chalk.red(`\n❌ Agent "${agentName}" not found.\n`));
+      console.log(chalk.gray('Available agents:'));
+      AGENTS.forEach(a => console.log(chalk.cyan(`  - ${a.name}`)));
+      process.exit(1);
+    }
+
+    let output = '';
+
+    // 1. Read Agent Prompt
+    const agentPath = path.resolve(__dirname, '../../agents', agent.file);
+    try {
+      const agentPrompt = await fs.readFile(agentPath, 'utf-8');
+      output += agentPrompt + '\n\n';
+    } catch (err) {
+      output += `# ${agent.name.toUpperCase()} Agent\n\nSee: https://github.com/Srujan0798/Ultra-Dex/blob/main/agents/${agent.file}\n\n`;
+    }
+
+    output += '---\n\n';
+
+    // 2. Read CONTEXT.md
+    try {
+      const context = await fs.readFile('CONTEXT.md', 'utf-8');
+      output += '# PROJECT CONTEXT\n\n' + context + '\n\n';
+    } catch (err) {
+      output += '# PROJECT CONTEXT\n\n*No CONTEXT.md found. Run `ultra-dex init` first.*\n\n';
+    }
+
+    output += '---\n\n';
+
+    // 3. Read IMPLEMENTATION-PLAN.md
+    try {
+      const plan = await fs.readFile('IMPLEMENTATION-PLAN.md', 'utf-8');
+      output += '# IMPLEMENTATION PLAN\n\n' + plan + '\n';
+    } catch (err) {
+      output += '# IMPLEMENTATION PLAN\n\n*No IMPLEMENTATION-PLAN.md found. Run `ultra-dex init` first.*\n';
+    }
+
+    // Output
+    console.log(chalk.bold(`\n📦 Packed context for @${agent.name}\n`));
+    console.log(chalk.gray('─'.repeat(60)));
+    console.log(output);
+    console.log(chalk.gray('─'.repeat(60)));
+
+    // Try to copy to clipboard if requested
+    if (options.clipboard) {
+      try {
+        const { execSync } = require('child_process');
+        const platform = process.platform;
+        if (platform === 'darwin') {
+          execSync('pbcopy', { input: output });
+          console.log(chalk.green('\n✅ Copied to clipboard!\n'));
+        } else if (platform === 'linux') {
+          execSync('xclip -selection clipboard', { input: output });
+          console.log(chalk.green('\n✅ Copied to clipboard!\n'));
+        } else {
+          console.log(chalk.yellow('\n⚠️  Clipboard not supported on this platform. Copy manually.\n'));
+        }
+      } catch (err) {
+        console.log(chalk.yellow('\n⚠️  Could not copy to clipboard. Copy manually.\n'));
+      }
+    } else {
+      console.log(chalk.cyan('\n💡 Tip: Use --clipboard flag to copy directly\n'));
+    }
+  });
+
+// Workflow examples map
+const WORKFLOWS = {
+  auth: {
+    name: 'Authentication',
+    agents: ['@Planner', '@Research', '@CTO', '@Database', '@Backend', '@Frontend', '@Security', '@DevOps'],
+    description: 'Complete authentication with email/password and OAuth',
+    example: 'supabase',
+  },
+  supabase: {
+    name: 'Supabase Authentication Setup',
+    agents: ['@Planner', '@Research', '@CTO', '@Database', '@Backend', '@Frontend', '@Security', '@DevOps'],
+    description: 'Set up Supabase auth with RLS policies',
+    steps: [
+      '1. Create Supabase project and get API keys',
+      '2. Set up database schema with RLS policies',
+      '3. Configure authentication providers (email + Google OAuth)',
+      '4. Implement backend auth middleware',
+      '5. Build frontend auth UI components',
+      '6. Test authentication flow',
+    ],
+  },
+  payments: {
+    name: 'Payment Integration (Stripe)',
+    agents: ['@Planner', '@Research', '@CTO', '@Database', '@Backend', '@Frontend', '@Testing', '@Security', '@DevOps'],
+    description: 'Integrate Stripe for subscriptions and one-time payments',
+    steps: [
+      '1. Create Stripe account and get API keys',
+      '2. Design subscription/payment schema',
+      '3. Implement Stripe Checkout API',
+      '4. Handle webhooks for payment events',
+      '5. Build payment UI with checkout flow',
+      '6. Test with Stripe test cards',
+    ],
+  },
+  deployment: {
+    name: 'Deployment Pipeline',
+    agents: ['@Planner', '@CTO', '@Frontend', '@DevOps'],
+    description: 'Deploy to Vercel with staging and production environments',
+    example: 'vercel',
+  },
+  vercel: {
+    name: 'Vercel Deployment Pipeline',
+    agents: ['@Planner', '@CTO', '@Frontend', '@DevOps'],
+    description: 'Deploy Next.js app to Vercel',
+    steps: [
+      '1. Set up Vercel project and link Git repository',
+      '2. Configure environment variables for staging/production',
+      '3. Set up custom domain',
+      '4. Configure preview deployments for PRs',
+      '5. Set up deployment protection rules',
+      '6. Test deployment pipeline',
+    ],
+  },
+  cicd: {
+    name: 'GitHub Actions CI/CD',
+    agents: ['@Planner', '@CTO', '@Testing', '@DevOps'],
+    description: 'Automated testing and deployment with GitHub Actions',
+    steps: [
+      '1. Create workflow file for CI (tests + lint)',
+      '2. Add build verification job',
+      '3. Add deployment job for production',
+      '4. Configure secrets for deployment',
+      '5. Add status badges to README',
+      '6. Test workflow on PR',
+    ],
+  },
+  database: {
+    name: 'Database Migration',
+    agents: ['@Planner', '@CTO', '@Database', '@Backend', '@Testing'],
+    description: 'Database schema migration and data sync',
+    steps: [
+      '1. Design new schema changes',
+      '2. Write migration scripts',
+      '3. Test migrations in staging',
+      '4. Back up production database',
+      '5. Run migrations in production',
+      '6. Verify data integrity',
+    ],
+  },
+  email: {
+    name: 'Email Notification System',
+    agents: ['@Planner', '@Research', '@CTO', '@Backend', '@Frontend', '@Testing'],
+    description: 'Transactional emails with templates',
+    steps: [
+      '1. Choose email service (Resend, SendGrid)',
+      '2. Set up email templates',
+      '3. Implement email API endpoints',
+      '4. Add email queue for async sending',
+      '5. Test email delivery',
+      '6. Monitor deliverability',
+    ],
+  },
+  realtime: {
+    name: 'Real-Time Features',
+    agents: ['@Planner', '@CTO', '@Backend', '@Frontend', '@Testing'],
+    description: 'Live notifications with WebSockets',
+    steps: [
+      '1. Choose WebSocket library (Socket.io, Pusher)',
+      '2. Set up WebSocket server',
+      '3. Implement event broadcasting',
+      '4. Build frontend listeners',
+      '5. Test real-time updates',
+      '6. Handle reconnection logic',
+    ],
+  },
+  sentry: {
+    name: 'Sentry Error Tracking',
+    agents: ['@Planner', '@Research', '@CTO', '@Backend', '@Frontend', '@DevOps'],
+    description: 'Error monitoring with Sentry',
+    steps: [
+      '1. Create Sentry account and project',
+      '2. Install Sentry SDKs for frontend and backend',
+      '3. Configure error boundaries for React',
+      '4. Set up source maps for debugging',
+      '5. Configure alerts and notifications',
+      '6. Test error capture in development',
+    ],
+  },
+  shopify: {
+    name: 'Shopify Product Integration',
+    agents: ['@Planner', '@Research', '@CTO', '@Database', '@Backend', '@DevOps'],
+    description: 'Sync products from Shopify store',
+    steps: [
+      '1. Create Shopify Partner account and development store',
+      '2. Set up Shopify app with Admin API access',
+      '3. Design database schema for products',
+      '4. Build product sync endpoint',
+      '5. Implement webhook handlers for product updates',
+      '6. Schedule full product sync (cron job)',
+    ],
+  },
+  analytics: {
+    name: 'PostHog Analytics Integration',
+    agents: ['@Planner', '@Research', '@CTO', '@Backend', '@Frontend', '@DevOps'],
+    description: 'Track user behavior with PostHog',
+    steps: [
+      '1. Create PostHog account and project',
+      '2. Install PostHog SDKs for frontend and backend',
+      '3. Set up core event tracking (signup, login, feature usage)',
+      '4. Create conversion funnel dashboard',
+      '5. Set up feature flags (optional)',
+      '6. Configure user identification',
+    ],
+  },
+};
+
+program
+  .command('workflow <feature>')
+  .description('Show workflow for common features (auth, payments, deployment, etc.)')
+  .action((feature) => {
+    const workflow = WORKFLOWS[feature.toLowerCase()];
+
+    if (!workflow) {
+      console.log(chalk.red(`\n❌ Workflow "${feature}" not found.\n`));
+      console.log(chalk.gray('Available workflows:'));
+      Object.keys(WORKFLOWS).forEach(key => {
+        console.log(chalk.cyan(`  - ${key}`) + chalk.gray(` (${WORKFLOWS[key].name})`));
+      });
+      console.log('\n' + chalk.gray('Usage: ultra-dex workflow <feature>\n'));
+      process.exit(1);
+    }
+
+    console.log(chalk.bold(`\n📋 ${workflow.name} Workflow\n`));
+    console.log(chalk.gray(workflow.description));
+
+    console.log(chalk.bold('\n🤖 Agents Involved:\n'));
+    workflow.agents.forEach((agent, i) => {
+      console.log(chalk.cyan(`  ${i + 1}. ${agent}`));
+    });
+
+    if (workflow.steps) {
+      console.log(chalk.bold('\n📝 Implementation Steps:\n'));
+      workflow.steps.forEach(step => {
+        console.log(chalk.gray(`  ${step}`));
+      });
+    }
+
+    console.log(chalk.bold('\n📚 Full Example:\n'));
+    console.log(chalk.blue('  https://github.com/Srujan0798/Ultra-Dex/blob/main/guides/ADVANCED-WORKFLOWS.md'));
+    console.log(chalk.gray(`  (Search for "Example: ${workflow.name}")\n`));
+  });
+
+program
+  .command('suggest')
+  .description('Get AI agent suggestions for your task')
+  .action(async () => {
+    console.log(chalk.cyan('\n🤖 Ultra-Dex Agent Suggester\n'));
+
+    const answers = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'taskType',
+        message: 'What are you trying to build?',
+        choices: [
+          'New feature from scratch',
+          'Authentication system',
+          'Payment integration',
+          'Database changes',
+          'Bug fix',
+          'Performance optimization',
+          'Deployment/DevOps',
+          'API endpoint',
+          'UI component',
+          'Testing',
+        ],
+      },
+      {
+        type: 'input',
+        name: 'description',
+        message: 'Briefly describe your task:',
+        default: '',
+      },
+    ]);
+
+    console.log(chalk.bold('\n💡 Suggested Agent Workflow:\n'));
+
+    // Agent suggestions based on task type
+    let suggestedAgents = [];
+    let reasoning = '';
+
+    switch (answers.taskType) {
+      case 'New feature from scratch':
+        suggestedAgents = ['@Planner', '@CTO', '@Database', '@Backend', '@Frontend', '@Testing', '@Reviewer', '@DevOps'];
+        reasoning = 'Complete feature requires planning, architecture, implementation, testing, and deployment';
+        break;
+
+      case 'Authentication system':
+        suggestedAgents = ['@Planner', '@Research', '@CTO', '@Database', '@Backend', '@Frontend', '@Security', '@DevOps'];
+        reasoning = 'Auth requires research (providers), security review, and full-stack implementation';
+        break;
+
+      case 'Payment integration':
+        suggestedAgents = ['@Planner', '@Research', '@CTO', '@Database', '@Backend', '@Frontend', '@Testing', '@Security', '@DevOps'];
+        reasoning = 'Payments need provider research, webhook handling, testing, and security audit';
+        break;
+
+      case 'Database changes':
+        suggestedAgents = ['@Planner', '@CTO', '@Database', '@Backend', '@Testing'];
+        reasoning = 'Schema changes need planning, architecture review, migration, and testing';
+        break;
+
+      case 'Bug fix':
+        suggestedAgents = ['@Debugger', '@Testing', '@Reviewer'];
+        reasoning = 'Debug issue, add test to prevent regression, review fix';
+        break;
+
+      case 'Performance optimization':
+        suggestedAgents = ['@Performance', '@Backend', '@Frontend', '@Database', '@Testing'];
+        reasoning = 'Identify bottlenecks, optimize code/queries, verify improvements';
+        break;
+
+      case 'Deployment/DevOps':
+        suggestedAgents = ['@DevOps', '@CTO', '@Security'];
+        reasoning = 'Infrastructure setup with security review';
+        break;
+
+      case 'API endpoint':
+        suggestedAgents = ['@Backend', '@Database', '@Testing', '@Reviewer'];
+        reasoning = 'Implement endpoint, add tests, review code quality';
+        break;
+
+      case 'UI component':
+        suggestedAgents = ['@Frontend', '@Reviewer'];
+        reasoning = 'Build component, review for quality and accessibility';
+        break;
+
+      case 'Testing':
+        suggestedAgents = ['@Testing', '@Reviewer'];
+        reasoning = 'Write tests, review coverage';
+        break;
+
+      default:
+        suggestedAgents = ['@Planner', '@CTO'];
+        reasoning = 'Start with planning and architecture review';
+    }
+
+    console.log(chalk.gray(reasoning + '\n'));
+
+    suggestedAgents.forEach((agent, i) => {
+      const agentName = agent.replace('@', '').toLowerCase();
+      const agentInfo = AGENTS.find(a => a.name === agentName);
+      const arrow = i < suggestedAgents.length - 1 ? '  →' : '';
+      console.log(chalk.cyan(`  ${i + 1}. ${agent}`) + chalk.gray(` - ${agentInfo?.description || ''}`) + arrow);
+    });
+
+    console.log(chalk.bold('\n📚 Next Steps:\n'));
+    console.log(chalk.gray(`  1. Start with ${suggestedAgents[0]} to plan the task`));
+    console.log(chalk.gray(`  2. Hand off to each agent in sequence`));
+    console.log(chalk.gray('  3. Use "ultra-dex agent <name>" to see full prompts\n'));
+
+    console.log(chalk.bold('🔗 Related Workflows:\n'));
+    if (answers.taskType === 'Authentication system') {
+      console.log(chalk.blue('  ultra-dex workflow auth'));
+      console.log(chalk.blue('  ultra-dex workflow supabase\n'));
+    } else if (answers.taskType === 'Payment integration') {
+      console.log(chalk.blue('  ultra-dex workflow payments\n'));
+    } else if (answers.taskType === 'Deployment/DevOps') {
+      console.log(chalk.blue('  ultra-dex workflow vercel'));
+      console.log(chalk.blue('  ultra-dex workflow cicd\n'));
+    } else {
+      console.log(chalk.gray('  Use "ultra-dex workflow <feature>" to see examples\n'));
+    }
+  });
+
+program
+  .command('validate')
+  .description('Validate project structure against Ultra-Dex standards')
+  .option('-d, --dir <directory>', 'Project directory to validate', '.')
+  .action(async (options) => {
+    console.log(chalk.cyan('\n✅ Ultra-Dex Structure Validator\n'));
+
+    const projectDir = path.resolve(options.dir);
+    let passed = 0;
+    let failed = 0;
+    const warnings = [];
+
+    // Helper to check file/directory exists
+    async function checkExists(itemPath, type = 'file') {
+      try {
+        const stats = await fs.stat(path.join(projectDir, itemPath));
+        if (type === 'file' && stats.isFile()) return true;
+        if (type === 'dir' && stats.isDirectory()) return true;
+        return false;
+      } catch {
+        return false;
+      }
+    }
+
+    console.log(chalk.bold('Checking required files...\n'));
+
+    // Check core planning files
+    const coreFiles = [
+      { path: 'QUICK-START.md', required: true },
+      { path: 'IMPLEMENTATION-PLAN.md', required: true },
+      { path: 'CONTEXT.md', required: false },
+      { path: 'README.md', required: false },
+    ];
+
+    for (const file of coreFiles) {
+      const exists = await checkExists(file.path);
+      if (exists) {
+        passed++;
+        console.log(chalk.green(`  ✅ ${file.path}`));
+      } else if (file.required) {
+        failed++;
+        console.log(chalk.red(`  ❌ ${file.path} (required)`));
+      } else {
+        warnings.push(file.path);
+        console.log(chalk.yellow(`  ⚠️  ${file.path} (recommended)`));
+      }
+    }
+
+    console.log(chalk.bold('\nChecking directory structure...\n'));
+
+    const directories = [
+      { path: 'docs', required: false },
+      { path: '.agents', required: false },
+      { path: '.cursor/rules', required: false },
+    ];
+
+    for (const dir of directories) {
+      const exists = await checkExists(dir.path, 'dir');
+      if (exists) {
+        passed++;
+        console.log(chalk.green(`  ✅ ${dir.path}/`));
+      } else {
+        warnings.push(dir.path);
+        console.log(chalk.yellow(`  ⚠️  ${dir.path}/ (optional)`));
+      }
+    }
+
+    console.log(chalk.bold('\nValidating content quality...\n'));
+
+    // Check if QUICK-START has key sections
+    try {
+      const quickStart = await fs.readFile(path.join(projectDir, 'QUICK-START.md'), 'utf-8');
+
+      const sections = ['idea', 'problem', 'feature', 'tech stack', 'tasks'];
+      let sectionsFound = 0;
+
+      sections.forEach(section => {
+        if (quickStart.toLowerCase().includes(section)) {
+          sectionsFound++;
+        }
+      });
+
+      if (sectionsFound >= 4) {
+        passed++;
+        console.log(chalk.green(`  ✅ QUICK-START.md has ${sectionsFound}/${sections.length} key sections`));
+      } else {
+        failed++;
+        console.log(chalk.red(`  ❌ QUICK-START.md missing key sections (${sectionsFound}/${sections.length})`));
+      }
+    } catch {
+      console.log(chalk.gray('  ⊘  Could not validate QUICK-START.md content'));
+    }
+
+    // Check if implementation plan has content
+    try {
+      const implPlan = await fs.readFile(path.join(projectDir, 'IMPLEMENTATION-PLAN.md'), 'utf-8');
+
+      if (implPlan.length > 500) {
+        passed++;
+        console.log(chalk.green(`  ✅ IMPLEMENTATION-PLAN.md has substantial content`));
+      } else {
+        warnings.push('IMPLEMENTATION-PLAN.md needs more detail');
+        console.log(chalk.yellow(`  ⚠️  IMPLEMENTATION-PLAN.md is sparse (${implPlan.length} chars)`));
+      }
+    } catch {
+      console.log(chalk.gray('  ⊘  Could not validate IMPLEMENTATION-PLAN.md content'));
+    }
+
+    // Summary
+    console.log('\n' + chalk.bold('─'.repeat(50)));
+    console.log(chalk.bold('\nValidation Summary:\n'));
+    console.log(chalk.green(`  ✅ Passed: ${passed}`));
+    console.log(chalk.red(`  ❌ Failed: ${failed}`));
+    console.log(chalk.yellow(`  ⚠️  Warnings: ${warnings.length}`));
+
+    // Overall status
+    if (failed === 0) {
+      console.log(chalk.bold.green('\n✅ VALIDATION PASSED\n'));
+      console.log(chalk.gray('Your project structure follows Ultra-Dex standards.'));
+    } else {
+      console.log(chalk.bold.yellow('\n⚠️  VALIDATION INCOMPLETE\n'));
+      console.log(chalk.gray('Fix required files to meet Ultra-Dex standards.'));
+    }
+
+    // Recommendations
+    if (warnings.length > 0) {
+      console.log(chalk.bold('\n💡 Recommendations:\n'));
+      warnings.slice(0, 3).forEach(w => {
+        console.log(chalk.cyan(`  → Consider adding ${w}`));
+      });
+    }
+
+    console.log('\n' + chalk.gray('Run "ultra-dex init" to set up a proper Ultra-Dex project.\n'));
+  });
+
+// ========================================
+// HOOKS COMMAND - Automated Verification
+// ========================================
+program
+  .command('hooks')
+  .description('Set up git hooks for automated verification')
+  .option('--remove', 'Remove Ultra-Dex git hooks')
+  .action(async (options) => {
+    console.log(chalk.cyan('\n🪝 Ultra-Dex Git Hooks Setup\n'));
+
+    const gitDir = path.join(process.cwd(), '.git');
+    const hooksDir = path.join(gitDir, 'hooks');
+
+    // Check if git repo exists
+    try {
+      await fs.access(gitDir);
+    } catch {
+      console.log(chalk.red('❌ Not a git repository. Run "git init" first.\n'));
+      process.exit(1);
+    }
+
+    // Create hooks directory if it doesn't exist
+    await fs.mkdir(hooksDir, { recursive: true });
+
+    const preCommitPath = path.join(hooksDir, 'pre-commit');
+
+    if (options.remove) {
+      // Remove hooks
+      try {
+        const content = await fs.readFile(preCommitPath, 'utf-8');
+        if (content.includes('ultra-dex')) {
+          await fs.unlink(preCommitPath);
+          console.log(chalk.green('✅ Ultra-Dex pre-commit hook removed.\n'));
+        } else {
+          console.log(chalk.yellow('⚠️  Pre-commit hook exists but is not from Ultra-Dex.\n'));
+        }
+      } catch {
+        console.log(chalk.gray('No Ultra-Dex hooks found.\n'));
+      }
+      return;
+    }
+
+    // Generate pre-commit hook
+    const preCommitScript = `#!/bin/sh
+# Ultra-Dex Pre-Commit Hook
+# Validates project structure before allowing commits
+# Remove with: npx ultra-dex hooks --remove
+
+echo "🔍 Ultra-Dex: Validating project structure..."
+
+# Run validation
+npx ultra-dex validate --dir . > /tmp/ultra-dex-validate.log 2>&1
+RESULT=$?
+
+if [ $RESULT -ne 0 ]; then
+  echo ""
+  echo "❌ Ultra-Dex validation failed. Commit blocked."
+  echo ""
+  echo "Run 'npx ultra-dex validate' to see details."
+  echo "Fix issues or bypass with: git commit --no-verify"
+  echo ""
+  exit 1
+fi
+
+# Check for required files
+if [ ! -f "QUICK-START.md" ]; then
+  echo "⚠️  Warning: QUICK-START.md not found"
+fi
+
+if [ ! -f "IMPLEMENTATION-PLAN.md" ]; then
+  echo "⚠️  Warning: IMPLEMENTATION-PLAN.md not found"
+fi
+
+echo "✅ Ultra-Dex validation passed."
+exit 0
+`;
+
+    // Check if pre-commit already exists
+    try {
+      const existing = await fs.readFile(preCommitPath, 'utf-8');
+      if (existing.includes('ultra-dex')) {
+        console.log(chalk.yellow('⚠️  Ultra-Dex pre-commit hook already exists.\n'));
+        console.log(chalk.gray('  Use --remove to remove it first.\n'));
+        return;
+      } else {
+        // Append to existing hook
+        const combined = existing + '\n\n' + preCommitScript;
+        await fs.writeFile(preCommitPath, combined);
+        await fs.chmod(preCommitPath, '755');
+        console.log(chalk.green('✅ Ultra-Dex hook appended to existing pre-commit.\n'));
+      }
+    } catch {
+      // No existing hook, create new
+      await fs.writeFile(preCommitPath, preCommitScript);
+      await fs.chmod(preCommitPath, '755');
+      console.log(chalk.green('✅ Pre-commit hook installed.\n'));
+    }
+
+    console.log(chalk.bold('What this does:\n'));
+    console.log(chalk.gray('  • Runs "ultra-dex validate" before each commit'));
+    console.log(chalk.gray('  • Blocks commits if required files are missing'));
+    console.log(chalk.gray('  • Warns about incomplete sections\n'));
+
+    console.log(chalk.bold('To bypass (not recommended):\n'));
+    console.log(chalk.cyan('  git commit --no-verify\n'));
+
+    console.log(chalk.bold('To remove:\n'));
+    console.log(chalk.cyan('  npx ultra-dex hooks --remove\n'));
+  });
+
 program.parse();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra-dex",
-  "version": "1.3.0",
-  "description": "CLI for Ultra-Dex SaaS Implementation Framework",
+  "version": "1.7.2",
+  "description": "CLI for Ultra-Dex SaaS Implementation Framework with 16 Production Agents",
   "keywords": [
     "saas",
     "template",