@girardmedia/bootspring 2.0.21 → 2.0.22

package/src/cli/agent.ts

@@ -0,0 +1,703 @@
+/**
+ * Bootspring Agent Command
+ * Work with specialized AI agents
+ *
+ * @package bootspring
+ * @module cli/agent
+ */
+
+import * as utils from '../core/utils';
+import * as telemetry from '../core/telemetry';
+import * as auth from '../core/auth';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Agent definition
+ */
+export interface Agent {
+  name: string;
+  category: string;
+  description: string;
+  expertise: string[];
+  triggers: string[];
+}
+
+/**
+ * Agent map
+ */
+export type AgentMap = Record<string, Agent>;
+
+/**
+ * Agent access result
+ */
+interface AgentAccessResult {
+  allowed: boolean;
+  requiredTier?: string | undefined;
+}
+
+/**
+ * Agent context result from API
+ */
+interface AgentContextResult {
+  context?: string | undefined;
+  name?: string | undefined;
+  error?: 'upgrade_required' | 'auth_required' | undefined;
+  requiredTier?: string | undefined;
+}
+
+/**
+ * Tier enforcement module interface
+ */
+interface TierEnforcementModule {
+  AGENT_TIERS: Record<string, string>;
+  checkAgentAccess: (agentId: string) => AgentAccessResult;
+  getTier: () => string;
+  getUpgradePrompt: (featureName: string, requiredTier: string) => string;
+}
+
+/**
+ * API client module interface
+ */
+interface ApiClientModule {
+  getAgentContext: (agentId: string) => Promise<AgentContextResult>;
+}
+
+// =============================================================================
+// Module imports (JavaScript modules)
+// =============================================================================
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const tierEnforcement = require('../../core/tier-enforcement') as TierEnforcementModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const api = require('../../core/api-client') as ApiClientModule;
+
+const { AGENT_TIERS, checkAgentAccess: canAccessAgent } = tierEnforcement;
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Track agent invocation via telemetry
+ */
+function trackAgentInvocation(agentId: string, topic: string | null = null): void {
+  try {
+    telemetry.emitEvent('agent.invoked', {
+      agent: agentId,
+      topic: topic ? topic.substring(0, 100) : null, // Truncate for privacy
+      timestamp: new Date().toISOString()
+    });
+  } catch {
+    // Telemetry should never break the command
+  }
+}
+
+/**
+ * Fetch agent context from API (thin client model)
+ * Agent context is not bundled locally - must be fetched from API
+ */
+async function fetchAgentContext(agentId: string): Promise<AgentContextResult | null> {
+  if (!auth.isAuthenticated()) {
+    return null;
+  }
+
+  try {
+    const response = await api.getAgentContext(agentId);
+    return response;
+  } catch (error) {
+    const err = error as { status?: number; requiredTier?: string };
+    if (err.status === 403) {
+      // Tier not sufficient - will be handled by canAccessAgent
+      return { error: 'upgrade_required', requiredTier: err.requiredTier };
+    }
+    if (err.status === 401) {
+      return { error: 'auth_required' };
+    }
+    // Network error or other issue
+    return null;
+  }
+}
+
+// =============================================================================
+// Agent Definitions
+// =============================================================================
+
+/**
+ * All available agents
+ */
+export const AGENTS: AgentMap = {
+  'database-expert': {
+    name: 'Database Expert',
+    category: 'Backend',
+    description: 'Specializes in database design, queries, migrations, and optimization',
+    expertise: ['SQL', 'NoSQL', 'Prisma', 'Drizzle', 'PostgreSQL', 'MongoDB'],
+    triggers: ['database', 'schema', 'migration', 'query', 'prisma', 'sql']
+  },
+  'security-expert': {
+    name: 'Security Expert',
+    category: 'Security',
+    description: 'Focuses on application security, OWASP, authentication, and authorization',
+    expertise: ['OWASP', 'Authentication', 'Authorization', 'Input Validation', 'XSS', 'CSRF'],
+    triggers: ['security', 'auth', 'owasp', 'vulnerability', 'xss', 'csrf', 'injection']
+  },
+  'frontend-expert': {
+    name: 'Frontend Expert',
+    category: 'Frontend',
+    description: 'Expert in React, Next.js, UI components, and modern frontend patterns',
+    expertise: ['React', 'Next.js', 'TypeScript', 'Tailwind', 'Components', 'State Management'],
+    triggers: ['component', 'react', 'frontend', 'ui', 'tailwind', 'css', 'styling']
+  },
+  'backend-expert': {
+    name: 'Backend Expert',
+    category: 'Backend',
+    description: 'Specializes in server-side development, APIs, and business logic',
+    expertise: ['Node.js', 'APIs', 'Server Actions', 'Middleware', 'Business Logic'],
+    triggers: ['api', 'backend', 'server', 'endpoint', 'route', 'middleware']
+  },
+  'api-expert': {
+    name: 'API Expert',
+    category: 'Backend',
+    description: 'Focuses on API design, REST, GraphQL, and integration patterns',
+    expertise: ['REST', 'GraphQL', 'tRPC', 'OpenAPI', 'Webhooks', 'Integration'],
+    triggers: ['api', 'rest', 'graphql', 'trpc', 'webhook', 'endpoint']
+  },
+  'testing-expert': {
+    name: 'Testing Expert',
+    category: 'Quality',
+    description: 'Expert in testing strategies, test frameworks, and quality assurance',
+    expertise: ['Unit Testing', 'Integration Testing', 'E2E', 'Vitest', 'Jest', 'Playwright'],
+    triggers: ['test', 'testing', 'jest', 'vitest', 'playwright', 'coverage']
+  },
+  'performance-expert': {
+    name: 'Performance Expert',
+    category: 'DevOps',
+    description: 'Specializes in performance optimization, caching, and monitoring',
+    expertise: ['Optimization', 'Caching', 'Profiling', 'Core Web Vitals', 'Load Testing'],
+    triggers: ['performance', 'optimize', 'cache', 'slow', 'speed', 'profiling']
+  },
+  'devops-expert': {
+    name: 'DevOps Expert',
+    category: 'DevOps',
+    description: 'Focuses on deployment, CI/CD, infrastructure, and monitoring',
+    expertise: ['CI/CD', 'Docker', 'Kubernetes', 'Monitoring', 'Infrastructure'],
+    triggers: ['deploy', 'ci', 'cd', 'docker', 'kubernetes', 'infrastructure']
+  },
+  'ui-ux-expert': {
+    name: 'UI/UX Expert',
+    category: 'Frontend',
+    description: 'Expert in user interface design, user experience, and accessibility',
+    expertise: ['Design Systems', 'Accessibility', 'Responsive Design', 'Animation'],
+    triggers: ['ui', 'ux', 'design', 'accessibility', 'a11y', 'responsive']
+  },
+  'architecture-expert': {
+    name: 'Architecture Expert',
+    category: 'Backend',
+    description: 'Specializes in system architecture, design patterns, and scalability',
+    expertise: ['System Design', 'Design Patterns', 'Microservices', 'Scalability'],
+    triggers: ['architecture', 'design', 'pattern', 'scalability', 'structure']
+  },
+  'code-review-expert': {
+    name: 'Code Review Expert',
+    category: 'Quality',
+    description: 'Focuses on code quality, best practices, and constructive feedback',
+    expertise: ['Code Quality', 'Best Practices', 'Refactoring', 'Clean Code'],
+    triggers: ['review', 'refactor', 'quality', 'clean', 'improve']
+  },
+  'vercel-expert': {
+    name: 'Vercel Expert',
+    category: 'DevOps',
+    description: 'Expert in Vercel deployment, serverless, and edge functions',
+    expertise: ['Vercel', 'Serverless', 'Edge Functions', 'ISR', 'Deployment'],
+    triggers: ['vercel', 'serverless', 'edge', 'deployment', 'hosting']
+  },
+  'business-strategy-expert': {
+    name: 'Business Strategy Expert',
+    category: 'Business',
+    description: 'Specializes in business model design, market analysis, and strategic planning',
+    expertise: ['Business Models', 'Market Analysis', 'Competitive Strategy', 'Go-to-Market', 'Unit Economics'],
+    triggers: ['business', 'strategy', 'market', 'model', 'gtm', 'positioning']
+  },
+  'financial-expert': {
+    name: 'Financial Expert',
+    category: 'Business',
+    description: 'Expert in financial modeling, projections, and startup finance',
+    expertise: ['Financial Modeling', 'Revenue Projections', 'Unit Economics', 'Cash Flow', 'Budgeting'],
+    triggers: ['financial', 'finance', 'revenue', 'projection', 'budget', 'cash', 'model']
+  },
+  'fundraising-expert': {
+    name: 'Fundraising Expert',
+    category: 'Business',
+    description: 'Specializes in investor relations, pitch decks, and fundraising strategy',
+    expertise: ['Pitch Decks', 'Investor Relations', 'Term Sheets', 'Due Diligence', 'Fundraising Strategy'],
+    triggers: ['fundraise', 'investor', 'pitch', 'deck', 'seed', 'series', 'vc', 'angel']
+  },
+  'private-equity-expert': {
+    name: 'Private Equity Expert',
+    category: 'Business',
+    description: 'Expert in PE/VC dynamics, valuation, and deal structuring',
+    expertise: ['Valuation', 'Deal Structure', 'Cap Tables', 'Term Sheets', 'Exit Strategy'],
+    triggers: ['pe', 'equity', 'valuation', 'cap table', 'term sheet', 'dilution']
+  },
+  'investor-relations-expert': {
+    name: 'Investor Relations Expert',
+    category: 'Business',
+    description: 'Specializes in investor communications, reporting, and stakeholder management',
+    expertise: ['Investor Updates', 'Board Management', 'KPI Reporting', 'Stakeholder Communication'],
+    triggers: ['investor', 'board', 'update', 'reporting', 'stakeholder']
+  },
+  'legal-expert': {
+    name: 'Legal Expert',
+    category: 'Business',
+    description: 'Expert in startup legal matters, contracts, and compliance',
+    expertise: ['Terms of Service', 'Privacy Policy', 'Contracts', 'IP', 'Compliance', 'GDPR'],
+    triggers: ['legal', 'terms', 'privacy', 'contract', 'compliance', 'gdpr', 'ip']
+  },
+  'marketing-expert': {
+    name: 'Marketing Expert',
+    category: 'Business',
+    description: 'Specializes in digital marketing, content strategy, and brand building',
+    expertise: ['Content Marketing', 'SEO', 'Social Media', 'Email Marketing', 'Brand Strategy'],
+    triggers: ['marketing', 'content', 'seo', 'social', 'brand', 'campaign']
+  },
+  'sales-expert': {
+    name: 'Sales Expert',
+    category: 'Business',
+    description: 'Expert in sales strategy, pipeline management, and customer acquisition',
+    expertise: ['Sales Strategy', 'Pipeline Management', 'CRM', 'Lead Generation', 'Closing'],
+    triggers: ['sales', 'pipeline', 'lead', 'crm', 'close', 'deal', 'prospect']
+  },
+  'growth-expert': {
+    name: 'Growth Expert',
+    category: 'Business',
+    description: 'Specializes in growth hacking, metrics, and user acquisition',
+    expertise: ['Growth Hacking', 'User Acquisition', 'Retention', 'Viral Loops', 'A/B Testing'],
+    triggers: ['growth', 'acquisition', 'retention', 'viral', 'metrics', 'experiment']
+  },
+  'operations-expert': {
+    name: 'Operations Expert',
+    category: 'Business',
+    description: 'Expert in operational efficiency, processes, and team management',
+    expertise: ['Process Design', 'Team Management', 'Hiring', 'OKRs', 'Operational Efficiency'],
+    triggers: ['operations', 'ops', 'process', 'team', 'hiring', 'okr', 'efficiency']
+  },
+  'competitive-analysis-expert': {
+    name: 'Competitive Analysis Expert',
+    category: 'Business',
+    description: 'Specializes in market research, competitor analysis, and positioning',
+    expertise: ['Competitor Analysis', 'Market Research', 'SWOT', 'Positioning', 'Differentiation'],
+    triggers: ['competitive', 'competitor', 'analysis', 'market', 'swot', 'positioning']
+  },
+  'partnerships-expert': {
+    name: 'Partnerships Expert',
+    category: 'Business',
+    description: 'Expert in partnership development, BD, and strategic alliances',
+    expertise: ['Partnership Development', 'Business Development', 'Strategic Alliances', 'Channel Partners'],
+    triggers: ['partnership', 'partner', 'bd', 'alliance', 'channel', 'integration']
+  },
+  'railway-expert': {
+    name: 'Railway Expert',
+    category: 'DevOps',
+    description: 'Expert in Railway deployment, databases, and infrastructure',
+    expertise: ['Railway', 'PostgreSQL', 'Redis', 'Deployment', 'Scaling'],
+    triggers: ['railway', 'deploy', 'postgres', 'redis', 'infrastructure']
+  },
+  'monitoring-expert': {
+    name: 'Monitoring Expert',
+    category: 'DevOps',
+    description: 'Specializes in observability, logging, metrics, and alerting',
+    expertise: ['Observability', 'Logging', 'Metrics', 'Alerting', 'APM', 'Sentry', 'Datadog'],
+    triggers: ['monitoring', 'logging', 'metrics', 'alerts', 'observability', 'sentry']
+  },
+  'research-expert': {
+    name: 'Research Expert',
+    category: 'Research',
+    description: 'Expert in market research, user research, and data analysis',
+    expertise: ['Market Research', 'User Research', 'Surveys', 'Interviews', 'Data Analysis'],
+    triggers: ['research', 'survey', 'interview', 'user research', 'market research']
+  },
+  'data-modeling-expert': {
+    name: 'Data Modeling Expert',
+    category: 'Research',
+    description: 'Specializes in data architecture, ERD design, and schema optimization',
+    expertise: ['ERD Design', 'Schema Design', 'Normalization', 'Indexing', 'Data Architecture'],
+    triggers: ['data model', 'erd', 'schema', 'entity', 'relationship', 'normalization']
+  },
+  'payment-expert': {
+    name: 'Payment Expert',
+    category: 'Integration',
+    description: 'Expert in payment processing, Stripe integration, and subscription billing',
+    expertise: ['Stripe', 'Subscriptions', 'Billing', 'Webhooks', 'Checkout', 'Payment Processing'],
+    triggers: ['payment', 'stripe', 'subscription', 'billing', 'checkout', 'invoice']
+  },
+  'ai-integration-expert': {
+    name: 'AI Integration Expert',
+    category: 'Integration',
+    description: 'Specializes in AI/LLM integration, Anthropic Claude, and AI SDK',
+    expertise: ['Claude API', 'AI SDK', 'Streaming', 'Tool Use', 'RAG', 'Embeddings'],
+    triggers: ['ai', 'llm', 'claude', 'anthropic', 'openai', 'streaming', 'embedding']
+  },
+  'email-expert': {
+    name: 'Email Expert',
+    category: 'Integration',
+    description: 'Expert in email integration, Resend, and transactional emails',
+    expertise: ['Resend', 'React Email', 'Transactional Email', 'Templates', 'Email Delivery'],
+    triggers: ['email', 'resend', 'sendgrid', 'template', 'notification', 'transactional']
+  },
+  'auth-expert': {
+    name: 'Auth Expert',
+    category: 'Integration',
+    description: 'Specializes in authentication, Clerk, NextAuth, and session management',
+    expertise: ['Clerk', 'NextAuth', 'OAuth', 'JWT', 'Session Management', 'RBAC'],
+    triggers: ['auth', 'authentication', 'login', 'session', 'oauth', 'clerk', 'nextauth']
+  },
+  'content-expert': {
+    name: 'Content Expert',
+    category: 'Content',
+    description: 'Expert in technical writing, documentation, blogs, marketing copy, and content strategy',
+    expertise: ['Technical Writing', 'Documentation', 'Blog Posts', 'Release Notes', 'README', 'API Docs', 'SEO', 'Content Strategy'],
+    triggers: ['content', 'writing', 'documentation', 'docs', 'blog', 'readme', 'changelog', 'copy', 'article', 'marketing']
+  },
+  'product-expert': {
+    name: 'Product Expert',
+    category: 'Product',
+    description: 'Expert in product management, roadmapping, feature prioritization, and user research',
+    expertise: ['Product Strategy', 'Roadmapping', 'Feature Prioritization', 'User Research', 'PRDs', 'OKRs', 'Metrics', 'Product-Market Fit'],
+    triggers: ['product', 'roadmap', 'feature', 'prioritization', 'prd', 'requirements', 'user research', 'okr', 'metrics', 'backlog']
+  },
+  'mobile-expert': {
+    name: 'Mobile Expert',
+    category: 'Mobile',
+    description: 'Expert in mobile development with React Native, Flutter, iOS, and Android',
+    expertise: ['React Native', 'Flutter', 'iOS', 'Android', 'Mobile Architecture', 'App Store', 'Push Notifications', 'Offline-First'],
+    triggers: ['mobile', 'react native', 'flutter', 'ios', 'android', 'app', 'native', 'swift', 'kotlin', 'expo']
+  },
+  'infrastructure-expert': {
+    name: 'Infrastructure Expert',
+    category: 'DevOps',
+    description: 'Expert in cloud infrastructure, Terraform, Kubernetes, and DevOps practices',
+    expertise: ['AWS', 'GCP', 'Azure', 'Terraform', 'Kubernetes', 'Docker', 'CI/CD', 'Infrastructure-as-Code', 'Cloud Architecture'],
+    triggers: ['infrastructure', 'cloud', 'aws', 'gcp', 'terraform', 'kubernetes', 'k8s', 'docker', 'devops', 'iac']
+  }
+};
+
+// =============================================================================
+// Command Functions
+// =============================================================================
+
+/**
+ * List all available agents
+ */
+export function listAgents(): void {
+  const userTier = tierEnforcement.getTier();
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}\u26a1 Bootspring Agents${utils.COLORS.reset}
+${utils.COLORS.dim}Specialized AI expertise on demand${utils.COLORS.reset}
+${utils.COLORS.dim}Your tier: ${userTier}${utils.COLORS.reset}
+`);
+
+  // Group by category
+  const categories: Record<string, Array<Agent & { id: string }>> = {};
+  for (const [id, agent] of Object.entries(AGENTS)) {
+    if (!categories[agent.category]) {
+      categories[agent.category] = [];
+    }
+    const categoryGroup = categories[agent.category];
+    if (categoryGroup) {
+      categoryGroup.push({ id, ...agent });
+    }
+  }
+
+  let accessibleCount = 0;
+  let lockedCount = 0;
+
+  for (const [category, agents] of Object.entries(categories)) {
+    console.log(`${utils.COLORS.bold}${category}${utils.COLORS.reset}`);
+    for (const agent of agents) {
+      const access = canAccessAgent(agent.id);
+      const tierBadge = AGENT_TIERS[agent.id]
+        ? ` ${utils.COLORS.yellow}[${AGENT_TIERS[agent.id]}]${utils.COLORS.reset}`
+        : '';
+      const lockIcon = access.allowed ? '' : ` ${utils.COLORS.red}\ud83d\udd12${utils.COLORS.reset}`;
+
+      if (access.allowed) {
+        accessibleCount++;
+      } else {
+        lockedCount++;
+      }
+
+      console.log(`  ${utils.COLORS.cyan}${agent.id}${utils.COLORS.reset}${tierBadge}${lockIcon}`);
+      console.log(`    ${utils.COLORS.dim}${agent.description}${utils.COLORS.reset}`);
+    }
+    console.log();
+  }
+
+  utils.print.dim(`${accessibleCount} agents available, ${lockedCount} locked`);
+  utils.print.dim('Use "bootspring agent show <name>" for details');
+}
+
+/**
+ * Show agent details
+ */
+export function showAgent(agentId: string): void {
+  const agent = AGENTS[agentId];
+
+  if (!agent) {
+    utils.print.error(`Agent not found: ${agentId}`);
+    utils.print.dim('Use "bootspring agent list" to see available agents');
+    return;
+  }
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}\u26a1 ${agent.name}${utils.COLORS.reset}
+${utils.COLORS.dim}Category: ${agent.category}${utils.COLORS.reset}
+
+${utils.COLORS.bold}Description${utils.COLORS.reset}
+${agent.description}
+
+${utils.COLORS.bold}Expertise${utils.COLORS.reset}
+${agent.expertise.map(e => `  ${utils.COLORS.green}\u25cf${utils.COLORS.reset} ${e}`).join('\n')}
+
+${utils.COLORS.bold}Trigger Keywords${utils.COLORS.reset}
+${agent.triggers.map(t => `  ${utils.COLORS.dim}${t}${utils.COLORS.reset}`).join(', ')}
+
+${utils.COLORS.bold}Usage${utils.COLORS.reset}
+  bootspring agent invoke ${agentId} --topic "your question"
+`);
+}
+
+/**
+ * Invoke an agent
+ */
+export async function invokeAgent(agentId: string, args: string[]): Promise<void> {
+  const agent = AGENTS[agentId];
+
+  if (!agent) {
+    utils.print.error(`Agent not found: ${agentId}`);
+    utils.print.dim('Use "bootspring agent list" to see available agents');
+    return;
+  }
+
+  // Check authentication first
+  if (!auth.isAuthenticated()) {
+    console.log(`
+${utils.COLORS.yellow}${utils.COLORS.bold}\u26a1 ${agent.name}${utils.COLORS.reset}
+${utils.COLORS.red}Authentication required${utils.COLORS.reset}
+
+${utils.COLORS.dim}Agent context is served from the API. Please log in:${utils.COLORS.reset}
+  ${utils.COLORS.cyan}bootspring auth login${utils.COLORS.reset}
+`);
+    return;
+  }
+
+  // Check tier access (client-side check for UX, server enforces)
+  const access = canAccessAgent(agentId);
+  if (!access.allowed) {
+    console.log(`
+${utils.COLORS.yellow}${utils.COLORS.bold}\u26a1 ${agent.name}${utils.COLORS.reset}
+${utils.COLORS.red}This agent requires ${access.requiredTier ?? 'pro'} tier or higher.${utils.COLORS.reset}
+`);
+    console.log(tierEnforcement.getUpgradePrompt(agent.name, access.requiredTier ?? 'pro'));
+    return;
+  }
+
+  const isMCP = utils.isMCPContext();
+  const parsedArgs = utils.parseArgs(args);
+  const topic = (parsedArgs.topic as string) ?? args.filter(a => !a.startsWith('--')).join(' ');
+
+  // Track agent invocation
+  trackAgentInvocation(agentId, topic || null);
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}\u26a1 ${agent.name}${utils.COLORS.reset}
+${utils.COLORS.dim}${agent.description}${utils.COLORS.reset}
+`);
+
+  // Fetch agent context from API (thin client - no local content)
+  const spinner = utils.createSpinner('Loading agent context...');
+  spinner.start();
+
+  const contextResult = await fetchAgentContext(agentId);
+
+  if (!contextResult) {
+    spinner.fail('Failed to load agent context');
+    console.log(`${utils.COLORS.dim}Check your internet connection and try again.${utils.COLORS.reset}`);
+    return;
+  }
+
+  if (contextResult.error === 'upgrade_required') {
+    spinner.fail('Upgrade required');
+    console.log(tierEnforcement.getUpgradePrompt(agent.name, contextResult.requiredTier ?? 'pro'));
+    return;
+  }
+
+  if (contextResult.error === 'auth_required') {
+    spinner.fail('Authentication required');
+    console.log(`${utils.COLORS.dim}Run: bootspring auth login${utils.COLORS.reset}`);
+    return;
+  }
+
+  spinner.succeed('Agent context loaded');
+
+  // In MCP mode, output the context for the AI to use
+  if (isMCP) {
+    console.log(`\n${utils.COLORS.bold}Agent Context:${utils.COLORS.reset}\n`);
+    console.log(contextResult.context ?? '');
+    return;
+  }
+
+  // CLI mode - show context and guidance
+  console.log(`\n${utils.COLORS.bold}Agent Context:${utils.COLORS.reset}`);
+  console.log(`${utils.COLORS.dim}\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${utils.COLORS.reset}`);
+
+  // Show truncated context in CLI mode
+  const contextLines = (contextResult.context ?? '').split('\n');
+  const previewLines = contextLines.slice(0, 20);
+  console.log(previewLines.join('\n'));
+
+  if (contextLines.length > 20) {
+    console.log(`\n${utils.COLORS.dim}... (${contextLines.length - 20} more lines)${utils.COLORS.reset}`);
+  }
+
+  console.log(`${utils.COLORS.dim}\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${utils.COLORS.reset}`);
+
+  if (topic) {
+    console.log(`\n${utils.COLORS.bold}Your topic:${utils.COLORS.reset} "${topic}"
+${utils.COLORS.dim}Use this context with your AI assistant for the topic above.${utils.COLORS.reset}
+`);
+  }
+
+  console.log(`
+${utils.COLORS.bold}Usage:${utils.COLORS.reset}
+  Copy the context above and use it with your AI assistant.
+
+${utils.COLORS.yellow}${utils.COLORS.bold}Enhanced Mode${utils.COLORS.reset}
+${utils.COLORS.dim}With MCP integration, agents activate automatically.${utils.COLORS.reset}
+  ${utils.COLORS.cyan}bootspring mcp start${utils.COLORS.reset}
+`);
+}
+
+/**
+ * Search for agents by keyword
+ */
+export function searchAgents(query: string): void {
+  const queryLower = query.toLowerCase();
+
+  const matches = Object.entries(AGENTS).filter(([id, agent]) => {
+    return id.includes(queryLower) ||
+           agent.name.toLowerCase().includes(queryLower) ||
+           agent.description.toLowerCase().includes(queryLower) ||
+           agent.expertise.some(e => e.toLowerCase().includes(queryLower)) ||
+           agent.triggers.some(t => t.includes(queryLower));
+  });
+
+  if (matches.length === 0) {
+    utils.print.warning(`No agents found matching "${query}"`);
+    utils.print.dim('Use "bootspring agent list" to see all agents');
+    return;
+  }
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}\u26a1 Agent Search: "${query}"${utils.COLORS.reset}
+`);
+
+  for (const [id, agent] of matches) {
+    console.log(`  ${utils.COLORS.cyan}${id}${utils.COLORS.reset} - ${agent.description}`);
+  }
+
+  console.log();
+  utils.print.dim(`${matches.length} agents found`);
+}
+
+/**
+ * Show agent help
+ */
+function showHelp(): void {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}\u26a1 Bootspring Agent${utils.COLORS.reset}
+${utils.COLORS.dim}Work with specialized AI agents${utils.COLORS.reset}
+
+${utils.COLORS.bold}Usage:${utils.COLORS.reset}
+  bootspring agent <command> [args]
+
+${utils.COLORS.bold}Commands:${utils.COLORS.reset}
+  ${utils.COLORS.cyan}list${utils.COLORS.reset}              List all available agents
+  ${utils.COLORS.cyan}show${utils.COLORS.reset} <name>       Show agent details
+  ${utils.COLORS.cyan}invoke${utils.COLORS.reset} <name>     Invoke an agent
+  ${utils.COLORS.cyan}search${utils.COLORS.reset} <query>    Search for agents
+
+${utils.COLORS.bold}Examples:${utils.COLORS.reset}
+  bootspring agent list
+  bootspring agent show security-expert
+  bootspring agent invoke database-expert --topic "optimize queries"
+  bootspring agent search performance
+`);
+}
+
+// =============================================================================
+// Main Entry Point
+// =============================================================================
+
+/**
+ * Run agent command
+ */
+export async function run(args: string[]): Promise<void> {
+  const subcommand = args[0] ?? 'list';
+  const subargs = args.slice(1);
+
+  switch (subcommand) {
+    case 'list':
+    case 'ls':
+      listAgents();
+      break;
+
+    case 'show':
+    case 'info':
+      if (!subargs[0]) {
+        utils.print.error('Please specify an agent name');
+        utils.print.dim('Usage: bootspring agent show <name>');
+        return;
+      }
+      showAgent(subargs[0]);
+      break;
+
+    case 'invoke':
+    case 'use':
+    case 'call':
+      if (!subargs[0]) {
+        utils.print.error('Please specify an agent name');
+        utils.print.dim('Usage: bootspring agent invoke <name> --topic "your question"');
+        return;
+      }
+      await invokeAgent(subargs[0], subargs.slice(1));
+      break;
+
+    case 'search':
+    case 'find':
+      if (!subargs[0]) {
+        utils.print.error('Please specify a search query');
+        utils.print.dim('Usage: bootspring agent search <query>');
+        return;
+      }
+      searchAgents(subargs.join(' '));
+      break;
+
+    case 'help':
+    case '-h':
+    case '--help':
+      showHelp();
+      break;
+
+    default:
+      // Check if it's an agent name (shortcut for show)
+      if (AGENTS[subcommand]) {
+        showAgent(subcommand);
+      } else {
+        utils.print.error(`Unknown subcommand: ${subcommand}`);
+        showHelp();
+      }
+  }
+}