@cloudstreamsoftware/claude-tools 1.0.0

package/README.md

@@ -0,0 +1,74 @@
+# @cloudstream/claude-tools
+
+CloudStream Software's Claude Code productivity tools for Zoho development.
+
+## Features
+
+- **Prompt Routing**: Intelligent classification of your requests
+- **Quality Gates**: Automatic credential scanning and code validation
+- **Knowledge Server**: Access to CloudStream's Zoho/Deluge pattern library
+- **Compliance Support**: HIPAA, SOC2, PCI-DSS workflow guidance
+
+## Installation
+
+```bash
+npm install @cloudstream/claude-tools
+npx cloudstream-setup
+```
+
+## Setup Wizard
+
+The setup wizard will:
+
+1. **Detect installation type** - Internal (CloudStream employee) or Client
+2. **Validate license** - Verify your CloudStream license key
+3. **Configure MCP** - Connect to the CloudStream Knowledge Server
+4. **Install tools** - Set up hooks, skills, and agents in ~/.claude/
+
+## Usage
+
+After setup, start a new Claude Code session in any project:
+
+```bash
+claude
+```
+
+The CloudStream tools are now available globally.
+
+### Knowledge Server
+
+Ask about Zoho/Deluge patterns and the knowledge server will provide synthesized guidance:
+
+```
+"How do I create a workflow that syncs CRM to Books?"
+"What's the best practice for API calls in Deluge?"
+"How do I handle errors in scheduled functions?"
+```
+
+### Available Commands
+
+- `/help` - Show available commands
+- `/diagnose` - Check system status
+- `/checkpoint` - Create a session checkpoint
+- `/handoff` - Generate session handoff notes
+
+## Security
+
+- **No local caching** of proprietary knowledge data
+- **Synthesized responses only** - raw patterns never leave the server
+- **Short-lived tokens** - 15-minute OAuth 2.1 access tokens
+- **Audit trail** - all queries logged for compliance
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- Claude Code CLI installed
+- Valid CloudStream license key
+
+## Support
+
+Contact your CloudStream administrator for license keys and support.
+
+## License
+
+UNLICENSED - CloudStream Software proprietary.

package/bin/cloudstream-setup.js

@@ -0,0 +1,467 @@
+#!/usr/bin/env node
+
+/**
+ * CloudStream Claude Tools Setup Wizard
+ *
+ * This wizard handles:
+ * 1. Detecting existing installations (git clone → npm migration)
+ * 2. Creating directory structure in ~/.claude/
+ * 3. Copying config with merge strategy (never overwrite user customizations)
+ * 4. Updating hook paths to absolute paths
+ * 5. Configuring MCP server connection
+ * 6. Validating license
+ * 7. Storing credentials securely
+ */
+
+const readline = require('readline');
+const fs = require('fs').promises;
+const path = require('path');
+const os = require('os');
+const https = require('https');
+
+// Configuration
+const CONFIG = {
+  claudeDir: path.join(os.homedir(), '.claude'),
+  knowledgeApiUrl: 'https://knowledge.cloudstreamsoftware.com',
+  requiredDirs: [
+    'hooks/scripts',
+    'skills',
+    'agents',
+    'commands',
+    'rules',
+    'config',
+    'sessions',
+    'memory',
+    'analytics'
+  ],
+  skipOnMerge: [
+    'sessions/*',
+    'memory/*',
+    'analytics/*',
+    'config/*.local.json'
+  ]
+};
+
+// ANSI color codes for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m'
+};
+
+function log(message, color = '') {
+  console.log(`${color}${message}${colors.reset}`);
+}
+
+function logSuccess(message) {
+  log(`  ✓ ${message}`, colors.green);
+}
+
+function logWarning(message) {
+  log(`  ⚠ ${message}`, colors.yellow);
+}
+
+function logError(message) {
+  log(`  ✗ ${message}`, colors.red);
+}
+
+function logStep(step, message) {
+  log(`\n[${step}] ${message}`, colors.cyan + colors.bright);
+}
+
+/**
+ * Create readline interface for user input
+ */
+function createInterface() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+}
+
+/**
+ * Prompt user for input
+ */
+function question(rl, prompt) {
+  return new Promise(resolve => rl.question(prompt, resolve));
+}
+
+/**
+ * Detect existing git clone installation
+ */
+async function detectExistingInstallation() {
+  const claudeDir = CONFIG.claudeDir;
+
+  try {
+    await fs.access(claudeDir);
+
+    // Check for markers of existing installation
+    const markers = [
+      path.join(claudeDir, 'hooks', 'hooks.json'),
+      path.join(claudeDir, 'CLAUDE.md'),
+      path.join(claudeDir, 'skills')
+    ];
+
+    for (const marker of markers) {
+      try {
+        await fs.access(marker);
+        return true;
+      } catch {
+        // Continue checking
+      }
+    }
+  } catch {
+    // Directory doesn't exist
+  }
+
+  return false;
+}
+
+/**
+ * Create required directory structure
+ */
+async function createDirectoryStructure() {
+  const claudeDir = CONFIG.claudeDir;
+
+  for (const dir of CONFIG.requiredDirs) {
+    const fullPath = path.join(claudeDir, dir);
+    await fs.mkdir(fullPath, { recursive: true });
+  }
+
+  logSuccess('Directory structure created');
+}
+
+/**
+ * Copy configuration files with merge strategy
+ */
+async function copyConfigWithMerge(sourceDir, targetDir) {
+  const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await fs.mkdir(targetPath, { recursive: true });
+      await copyConfigWithMerge(sourcePath, targetPath);
+    } else {
+      // Check if this is a user customization file that should be preserved
+      const shouldSkip = CONFIG.skipOnMerge.some(pattern => {
+        const relativePath = path.relative(CONFIG.claudeDir, targetPath);
+        if (pattern.endsWith('*')) {
+          return relativePath.startsWith(pattern.slice(0, -1));
+        }
+        return relativePath === pattern;
+      });
+
+      if (shouldSkip) {
+        try {
+          await fs.access(targetPath);
+          // File exists, skip it
+          continue;
+        } catch {
+          // File doesn't exist, copy it
+        }
+      }
+
+      // For .default.json files, always overwrite
+      // For .json files (user config), only copy if doesn't exist
+      if (entry.name.endsWith('.default.json')) {
+        await fs.copyFile(sourcePath, targetPath);
+      } else if (entry.name.endsWith('.json')) {
+        try {
+          await fs.access(targetPath);
+          // User config exists, don't overwrite
+        } catch {
+          // User config doesn't exist, copy default as user config
+          await fs.copyFile(sourcePath, targetPath);
+        }
+      } else {
+        // Non-config files, copy normally
+        await fs.copyFile(sourcePath, targetPath);
+      }
+    }
+  }
+}
+
+/**
+ * Update hook paths to use absolute paths
+ */
+async function updateHookPaths() {
+  const hooksJsonPath = path.join(CONFIG.claudeDir, 'hooks', 'hooks.json');
+
+  try {
+    const content = await fs.readFile(hooksJsonPath, 'utf8');
+    let hooksConfig = JSON.parse(content);
+
+    // Replace ${CLAUDE_PLUGIN_ROOT} with actual home directory path
+    const homeDir = os.homedir().replace(/\\/g, '/');
+    const updatedContent = JSON.stringify(hooksConfig, null, 2)
+      .replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, `${homeDir}/.claude`)
+      .replace(/\$\{HOME\}/g, homeDir);
+
+    await fs.writeFile(hooksJsonPath, updatedContent);
+    logSuccess('Hook paths updated to absolute paths');
+  } catch (error) {
+    logWarning(`Could not update hook paths: ${error.message}`);
+  }
+}
+
+/**
+ * Validate license with server
+ */
+async function validateLicense(licenseKey) {
+  return new Promise((resolve) => {
+    const url = `${CONFIG.knowledgeApiUrl}/api/v1/license/validate`;
+
+    const postData = JSON.stringify({ key: licenseKey });
+
+    const options = {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(postData)
+      },
+      timeout: 10000
+    };
+
+    const req = https.request(url, options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const result = JSON.parse(data);
+          resolve(result.valid === true);
+        } catch {
+          resolve(false);
+        }
+      });
+    });
+
+    req.on('error', () => {
+      // Server unavailable, accept license for offline mode
+      logWarning('Could not reach license server, continuing in offline mode');
+      resolve(true);
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      logWarning('License validation timed out, continuing in offline mode');
+      resolve(true);
+    });
+
+    req.write(postData);
+    req.end();
+  });
+}
+
+/**
+ * Store credentials securely using platform-specific methods
+ */
+async function storeCredentials(licenseKey, installType) {
+  const credentialsDir = path.join(CONFIG.claudeDir, 'credentials');
+  await fs.mkdir(credentialsDir, { recursive: true });
+
+  // For now, store in a config file
+  // TODO: Integrate with keytar for secure storage
+  const credentials = {
+    licenseKey,
+    installType,
+    createdAt: new Date().toISOString()
+  };
+
+  const credentialsPath = path.join(credentialsDir, 'cloudstream.json');
+  await fs.writeFile(credentialsPath, JSON.stringify(credentials, null, 2));
+
+  // Set restrictive permissions (Unix only)
+  if (process.platform !== 'win32') {
+    await fs.chmod(credentialsPath, 0o600);
+  }
+
+  logSuccess('Credentials stored securely');
+}
+
+/**
+ * Configure MCP server connection
+ */
+async function configureMcpServer(licenseKey) {
+  const mcpConfigPath = path.join(CONFIG.claudeDir, 'mcp.json');
+
+  let existingConfig = { mcpServers: {} };
+  try {
+    const content = await fs.readFile(mcpConfigPath, 'utf8');
+    existingConfig = JSON.parse(content);
+  } catch {
+    // File doesn't exist or is invalid
+  }
+
+  // Add CloudStream knowledge server
+  existingConfig.mcpServers = existingConfig.mcpServers || {};
+  existingConfig.mcpServers['cloudstream-knowledge'] = {
+    command: 'npx',
+    args: ['@cloudstream/knowledge-mcp-client'],
+    env: {
+      CLOUDSTREAM_LICENSE: licenseKey,
+      CLOUDSTREAM_API: CONFIG.knowledgeApiUrl
+    }
+  };
+
+  await fs.writeFile(mcpConfigPath, JSON.stringify(existingConfig, null, 2));
+  logSuccess('MCP server configured');
+}
+
+/**
+ * Verify connection to knowledge server
+ */
+async function verifyConnection(licenseKey) {
+  return new Promise((resolve) => {
+    const url = `${CONFIG.knowledgeApiUrl}/api/v1/health`;
+
+    const options = {
+      headers: {
+        'Authorization': `Bearer ${licenseKey}`
+      },
+      timeout: 5000
+    };
+
+    https.get(url, options, (res) => {
+      resolve(res.statusCode === 200);
+    }).on('error', () => {
+      resolve(false);
+    }).on('timeout', () => {
+      resolve(false);
+    });
+  });
+}
+
+/**
+ * Main setup function
+ */
+async function setup() {
+  console.log('\n' + '='.repeat(50));
+  log('  CloudStream Claude Tools Setup', colors.bright + colors.cyan);
+  console.log('='.repeat(50) + '\n');
+
+  const rl = createInterface();
+
+  try {
+    // Step 1: Check for existing installation
+    logStep('1/7', 'Checking for existing installation...');
+    const existingInstall = await detectExistingInstallation();
+
+    if (existingInstall) {
+      logWarning('Existing installation detected');
+      const migrate = await question(rl, '  Migrate existing configuration? [Y/n]: ');
+      if (migrate.toLowerCase() === 'n') {
+        log('\nSetup cancelled by user.', colors.yellow);
+        rl.close();
+        process.exit(0);
+      }
+      logSuccess('Will migrate existing configuration');
+    } else {
+      logSuccess('Fresh installation');
+    }
+
+    // Step 2: Select installation type
+    logStep('2/7', 'Select installation type');
+    console.log('  1. Internal (CloudStream employee)');
+    console.log('  2. Client');
+    const installTypeInput = await question(rl, '\n  Select [1/2]: ');
+    const installType = installTypeInput === '1' ? 'internal' : 'client';
+    logSuccess(`Installation type: ${installType}`);
+
+    // Step 3: Get license key
+    logStep('3/7', 'License validation');
+    const licenseKey = await question(rl, '  Enter your license key: ');
+
+    if (!licenseKey.trim()) {
+      logError('License key is required');
+      rl.close();
+      process.exit(1);
+    }
+
+    const isValid = await validateLicense(licenseKey);
+    if (!isValid) {
+      logError('Invalid license key');
+      rl.close();
+      process.exit(1);
+    }
+    logSuccess('License validated');
+
+    // Step 4: Create directory structure
+    logStep('4/7', 'Creating directory structure...');
+    await createDirectoryStructure();
+
+    // Step 5: Copy configuration files
+    logStep('5/7', 'Installing configuration files...');
+    const packageConfigDir = path.join(__dirname, '..', 'config');
+    try {
+      await copyConfigWithMerge(packageConfigDir, CONFIG.claudeDir);
+      logSuccess('Configuration files installed');
+    } catch (error) {
+      logWarning(`Some configuration files could not be copied: ${error.message}`);
+    }
+
+    // Copy hook scripts
+    const packageHooksDir = path.join(__dirname, '..', 'dist', 'hooks');
+    const targetHooksDir = path.join(CONFIG.claudeDir, 'hooks', 'scripts');
+    try {
+      await copyConfigWithMerge(packageHooksDir, targetHooksDir);
+      await updateHookPaths();
+    } catch (error) {
+      logWarning(`Hook scripts could not be copied: ${error.message}`);
+    }
+
+    // Step 6: Configure MCP server
+    logStep('6/7', 'Configuring MCP server connection...');
+    await configureMcpServer(licenseKey);
+    await storeCredentials(licenseKey, installType);
+
+    // Step 7: Verify connection
+    logStep('7/7', 'Verifying knowledge server connection...');
+    const connected = await verifyConnection(licenseKey);
+
+    if (connected) {
+      logSuccess('Connected to CloudStream Knowledge Server');
+    } else {
+      logWarning('Could not connect to knowledge server');
+      console.log('  The tools will work offline with local skills.');
+      console.log('  Knowledge server features will be available when connected.');
+    }
+
+    // Complete
+    console.log('\n' + '='.repeat(50));
+    log('  Setup Complete!', colors.bright + colors.green);
+    console.log('='.repeat(50));
+    console.log('\nThe CloudStream tools are now available globally.');
+    console.log('Start a new Claude Code session to begin.\n');
+
+    if (installType === 'internal') {
+      console.log('Internal features enabled:');
+      console.log('  - Full pattern access');
+      console.log('  - Submit learned patterns');
+      console.log('  - Admin tools');
+    } else {
+      console.log('Client features enabled:');
+      console.log('  - Pattern guidance (synthesized)');
+      console.log('  - Best practice recommendations');
+    }
+
+    console.log('\nRun "claude" in any project to get started.\n');
+
+  } catch (error) {
+    logError(`Setup failed: ${error.message}`);
+    process.exit(1);
+  } finally {
+    rl.close();
+  }
+}
+
+// Run setup
+setup().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/bin/postinstall.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+/**
+ * CloudStream Claude Tools - Postinstall Script
+ *
+ * This script runs automatically after npm install.
+ * It displays setup instructions without running the full wizard automatically.
+ */
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  cyan: '\x1b[36m',
+  yellow: '\x1b[33m'
+};
+
+console.log(`
+${colors.cyan}${colors.bright}╔════════════════════════════════════════════════════════════╗
+║                                                            ║
+║   CloudStream Claude Tools installed successfully!         ║
+║                                                            ║
+╚════════════════════════════════════════════════════════════╝${colors.reset}
+
+${colors.yellow}To complete setup, run:${colors.reset}
+
+  ${colors.bright}npx cloudstream-setup${colors.reset}
+
+This will:
+  1. Configure your installation type (internal/client)
+  2. Validate your license key
+  3. Set up the knowledge server connection
+  4. Install hooks and skills to ~/.claude/
+
+${colors.cyan}Need a license key? Contact your CloudStream administrator.${colors.reset}
+`);

package/config/CLAUDE.md

@@ -0,0 +1,295 @@
+# CloudStream Software LLC - Claude Code Configuration
+
+## Company Context
+- Zoho One consultancy + full-stack development firm
+- Primary verticals: Healthcare (HIPAA), Finance (PCI-DSS), Enterprise (SOC2)
+- This is BILLABLE CLIENT WORK. Every action must be auditable, defensible, handoff-ready.
+
+## Technology Stack
+- **Zoho Platform:** CRM, Books, Creator, Analytics, Catalyst
+- **Full-Stack:** React/Next.js widgets, Node.js backends (Zoho + standalone)
+- **Google Cloud:** BigQuery, Dataflow, Cloud Functions, Cloud Storage
+- **Data Engineering:** Medallion architecture (bronze/silver/gold), dbt, Looker
+- **Languages:** JavaScript/TypeScript, Deluge, Python, SQL
+
+## Compliance Modes (set per-client in client CLAUDE.md)
+- `hipaa` - Healthcare clients (ePHI field handling, BAA, audit archival)
+- `soc2` - Enterprise clients (audit logging, change management, access controls)
+- `pci-dss` - Financial clients (Zoho Checkout only, tokenization, SAQ-A)
+- `standard` - Non-regulated clients
+
+## User Settings (configure in CLAUDE.local.md)
+
+The following settings are user-specific and should NOT be set in this parent repo.
+Create a `CLAUDE.local.md` file in your fork for personal preferences:
+
+- **Training Mode**: Set `enabled` or `disabled` based on your experience level
+- **Training Verbosity**: Set `minimal`, `standard`, or `detailed`
+- **Personal shortcuts**: Client-specific aliases, custom workflows
+
+See [docs/LOCAL-SETTINGS.md](docs/LOCAL-SETTINGS.md) for setup instructions.
+
+## Commit Convention
+[CLIENT-ID] type(scope): description | Time: Xh Xm
+
+## Zoho Critical Constraints (ALWAYS REMEMBER)
+- Deluge: 5000 statement limit per execution
+- Deluge invokeUrl: 40-second hard timeout
+- Catalyst I/O functions: 30-second timeout (use Cron for batch: 15min)
+- Catalyst: context.close() MANDATORY at end of ALL functions
+- Widgets: Do NOT work on published pages (use Publish API instead)
+- OAuth tokens: Expire in 1 hour (implement refresh logic)
+- Creator audit data: Retained only 1 year (implement archival)
+- CRM→Books sync: Native 2-hour cycle exists (don't rebuild)
+
+---
+
+## Available Skills (15)
+
+Skills are domain knowledge patterns automatically injected based on context.
+
+| Skill | Purpose |
+|-------|---------|
+| backend-patterns | Node.js, Express, API design, database optimization |
+| bigquery-patterns | BigQuery schema design, query optimization, partitioning |
+| cloudstream-project-template | New project scaffolding, directory layout, compliance mode |
+| coding-standards | Universal TypeScript/JS standards, best practices |
+| compliance-patterns | HIPAA, SOC2, PCI-DSS implementation patterns |
+| consultancy-workflows | Client isolation, time tracking, handoff procedures |
+| continuous-learning | Session-end pattern extraction and skill capture |
+| continuous-learning-v2 | Instinct-based pattern extraction and skill learning |
+| frontend-patterns | React, Next.js, state management, UI optimization |
+| gcp-data-engineering | Medallion architecture, Dataflow, dbt patterns |
+| security-review | OWASP Top 10, vulnerability detection, secret scanning |
+| strategic-compact | Context compaction at logical intervals |
+| tdd-workflow | Test-driven development, 80%+ coverage enforcement |
+| tutorial | Interactive onboarding system, lessons, accelerated track |
+| zoho-patterns | Creator, Catalyst, Deluge, Analytics, integrations |
+
+---
+
+## Available Agents (13)
+
+Agents are specialized subprocesses triggered for delegated tasks.
+
+| Agent | Purpose | Suggested Model |
+|-------|---------|-----------------|
+| planner | Implementation planning for complex features | Opus |
+| architect | System design, scalability, technical decisions | Opus |
+| creator-architect | Zoho Creator app architecture, form hierarchies | Opus |
+| security-reviewer | Security vulnerability detection, OWASP Top 10 | Opus |
+| compliance-auditor | HIPAA/SOC2/PCI-DSS regulatory audits | Opus |
+| code-reviewer | Code quality, maintainability, best practices | Sonnet |
+| deluge-reviewer | Deluge validation, 5000-statement limit awareness | Sonnet |
+| tdd-guide | Test-driven development enforcement | Sonnet |
+| build-error-resolver | Build and TypeScript error fixes | Sonnet |
+| catalyst-deployer | Catalyst AppSail/Functions deployment | Sonnet |
+| e2e-runner | Playwright E2E test generation and execution | Sonnet |
+| refactor-cleaner | Dead code cleanup with knip/depcheck/ts-prune | Sonnet |
+| doc-updater | Documentation sync, codemap generation | Sonnet |
+
+> **Note:** Model selection is suggested by the prompt router but not programmatically enforced. See [docs/MODEL-SELECTION.md](docs/MODEL-SELECTION.md) for guidance.
+
+---
+
+## Hooks System
+
+Hooks are automated scripts triggered at specific lifecycle points.
+
+| Event | Count | Purpose |
+|-------|-------|---------|
+| SessionStart | 1 | Load context, detect package manager |
+| SessionEnd | 2 | Persist state, evaluate session for patterns |
+| UserPromptSubmit | 2 | Prompt routing, correction detection |
+| PreToolUse | 8 | Credential scan, quality gates, skill injection, tmux reminders |
+| PostToolUse | 4 | Prettier format, TypeScript check, console.log warnings |
+| PreCompact | 1 | Save state before context compaction |
+| Stop | 1 | Check console.log in modified files |
+
+**Total: 19 hooks across 7 events**
+
+See `hooks/hooks.json` for full configuration.
+
+---
+
+## Agent Triggers
+
+When to use which agent:
+- Complex features → `planner`
+- System design → `architect` + `creator-architect` (for Zoho)
+- New/modified code → `code-reviewer`
+- Deluge scripts → `deluge-reviewer`
+- Security concerns → `security-reviewer`
+- Compliance audit → `compliance-auditor`
+- Build/deploy failures → `build-error-resolver` + `catalyst-deployer`
+- Standalone widget testing → `e2e-runner`
+- Documentation → `doc-updater`
+- Dead code cleanup → `refactor-cleaner`
+
+---
+
+## Interactive Prompt Routing (Golden Standard)
+
+**ENFORCED BY:** `rules/prompt-routing.md` and `rules/hook-awareness.md` (always active)
+
+Claude MUST analyze every user prompt and offer appropriate routing options using AskUserQuestion.
+
+### Routing Indicator (Visual Feedback)
+
+When the routing system processes a prompt, Claude shows a visual indicator in the AskUserQuestion header:
+
+```
+✅ Routed → TESTING (85%)
+
+"Which approach would you like?"
+- Use tdd-guide agent (Recommended)
+- Proceed directly
+```
+
+The `✅ Routed →` prefix confirms the prompt was analyzed by the intent classifier. The intent type and confidence percentage follow.
+
+**Multi-intent example:**
+```
+✅ Routed → PLANNING + TESTING + SECURITY
+
+"I've identified 3 objectives. How should we proceed?"
+```
+
+### Hook Integration
+
+The `prompt-router.js` hook outputs `[ROUTING SUGGESTION]` blocks that Claude must act on:
+- Check for these blocks in conversation context
+- Use the detected intent and recommended agent
+- Present options via AskUserQuestion as specified in the block
+- See `rules/hook-awareness.md` for full block types
+
+### Step 1: Analyze Prompt Complexity
+
+Before processing ANY user prompt, analyze for:
+1. **Single Intent** - One clear objective (e.g., "Fix this bug")
+2. **Multi-Intent** - Multiple objectives (e.g., "Plan the feature, write tests, and review security")
+3. **Compound Task** - One objective requiring multiple phases (e.g., "Build a full authentication system")
+
+**Complexity Indicators:**
+- Lists (numbered, bulleted, comma-separated)
+- Conjunctions: "and", "also", "then", "after that"
+- Multiple questions in one prompt
+- Words like "comprehensive", "full", "complete", "everything"
+
+### Step 2: For Single-Intent Prompts
+
+Detect intent and offer appropriate options via AskUserQuestion:
+
+| Intent | Triggers | Recommended Agent | Model |
+|--------|----------|-------------------|-------|
+| PLANNING | "plan", "design", "architect", "strategy" | planner | Opus |
+| SECURITY | "security", "audit", "vulnerabilities", "HIPAA" | security-reviewer | Opus |
+| COMPLIANCE | "compliance", "SOC2", "PCI", "regulations" | compliance-auditor | Opus |
+| REVIEW | "review", "check", "look over", "feedback" | code-reviewer | Sonnet |
+| TESTING | "test", "TDD", "coverage", "write tests" | tdd-guide | Sonnet |
+| DEBUG | "fix", "error", "bug", "broken", "failing" | build-error-resolver | Sonnet |
+| REFACTOR | "refactor", "clean up", "optimize", "improve" | refactor-cleaner | Sonnet |
+| ZOHO | "Zoho", "Creator", "Deluge", "Catalyst" | creator-architect | Opus |
+| DEPLOY | "deploy", "release", "ship", "production" | catalyst-deployer | Sonnet |
+| E2E | "e2e", "playwright", "end-to-end", "journey" | e2e-runner | Sonnet |
+| LEARNING | "learn", "extract", "pattern", "capture" | - | - |
+| SETUP | "setup", "configure", "install", "onboard" | - | - |
+| HANDOFF | "handoff", "transfer", "deliverable" | doc-updater | Sonnet |
+| DOCUMENTATION | "docs", "document", "readme", "update docs" | doc-updater | Sonnet |
+
+**Options to present:**
+1. "Use [agent] with [model] (Recommended)" - Specialized handling
+2. "Proceed directly" - Quick response without agent
+3. "Show all available agents" - Browse options
+
+### Step 3: For Multi-Intent Prompts (CRITICAL)
+
+When multiple objectives detected:
+
+1. **Present Breakdown** - Show user what tasks were detected
+2. **Offer Orchestration Options:**
+   - "Create a plan first (recommended)" - Uses planner to sequence tasks
+   - "Execute tasks in order" - Process sequentially as listed
+   - "Let me choose which tasks" - Multi-select for user control
+   - "Focus on one task first" - User picks priority
+
+3. **Use Multi-Select AskUserQuestion** when appropriate for task selection
+
+### Step 4: For Compound Tasks
+
+Large tasks requiring multiple phases (e.g., "Build full auth system"):
+
+1. **Always recommend planner first** - Complex tasks need a plan
+2. **Offer phased approach:**
+   - Phase 1: Architecture design (architect agent)
+   - Phase 2: Implementation (with TDD)
+   - Phase 3: Security review
+   - Phase 4: Documentation
+
+### Step 5: Context-Aware Suggestions
+
+Also consider:
+- **Current file context** - If editing a test file, suggest tdd-guide
+- **Recent activity** - If just finished planning, suggest implementation
+- **Compliance mode** - If HIPAA client, always suggest compliance check
+- **Error state** - If build failing, suggest build-error-resolver
+
+### Example: Complex Prompt Handling
+
+**User says:** "I need to add user authentication with OAuth, make sure it's HIPAA compliant, write comprehensive tests, and document the API."
+
+**Claude detects:** 4 objectives (Auth, HIPAA, tests, docs) + Compound nature
+
+**Claude responds with AskUserQuestion:**
+- Header: "✅ Routed → PLANNING + SECURITY + TESTING + DOCUMENTATION"
+- Question: "I've identified 4 objectives. How would you like to proceed?"
+- Options:
+  1. "Create a comprehensive plan first (Recommended)" - Uses planner agent
+  2. "Address each objective in order" - Auth → Compliance → Tests → Docs
+  3. "Let me prioritize these objectives" - Opens multi-select
+  4. "Focus on authentication first, handle rest later" - Narrows scope
+
+---
+
+## Quick Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `/plan` | Implementation planning before coding |
+| `/tdd` | Test-driven development workflow |
+| `/code-review` | Quality and security review |
+| `/verify` | Run verification loop |
+| `/build-fix` | Fix build and deployment errors |
+| `/e2e` | E2E test generation (Playwright) |
+| `/zoho-scaffold` | Scaffold Creator/Catalyst/Widget projects |
+| `/deluge` | Generate and fix Deluge scripts |
+| `/compliance-check` | Run HIPAA/SOC2/PCI-DSS audit |
+| `/client-switch` | Switch active client context |
+| `/handoff` | Generate client handoff documentation |
+| `/learn` | Extract reusable patterns mid-session |
+| `/health-check` | System health verification |
+| `/diagnose` | Deep diagnostic troubleshooting |
+| `/onboard` | Interactive setup wizard |
+| `/team-admin` | Team administration tools |
+
+See README.md for full command list (36 commands).
+
+---
+
+## Documentation
+
+- [README.md](README.md) - Quick start and full component overview
+- [GETTING-STARTED.md](GETTING-STARTED.md) - New employee onboarding
+- [CLIENT-SETUP-GUIDE.md](CLIENT-SETUP-GUIDE.md) - Setting up new client projects
+- [MCP-SETUP-GUIDE.md](MCP-SETUP-GUIDE.md) - Installing and configuring MCP servers
+- [ZOHO-QUICK-REFERENCE.md](ZOHO-QUICK-REFERENCE.md) - Zoho constraints and decision matrices
+- [CONTRIBUTING.md](CONTRIBUTING.md) - How to contribute to this repository
+
+---
+
+## Plan File Management
+
+Plans must only show current work. When a phase completes:
+1. Remove completed content from plan file
+2. Document completion in CHANGELOG.md
+3. Keep plan concise and scannable (<100 lines)

package/mcp/knowledge-connector.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "cloudstream-knowledge",
+  "description": "CloudStream Knowledge Server - Zoho/Deluge patterns and best practices",
+  "version": "1.0.0",
+  "server": {
+    "command": "npx",
+    "args": ["@cloudstream/knowledge-mcp-client"],
+    "env": {
+      "CLOUDSTREAM_LICENSE": "${LICENSE_KEY}",
+      "CLOUDSTREAM_API": "https://knowledge.cloudstreamsoftware.com"
+    }
+  },
+  "tools": [
+    {
+      "name": "get_deluge_guidance",
+      "description": "Get synthesized guidance for a Deluge task (pattern code processed server-side, never sent to client)",
+      "parameters": {
+        "task_type": {
+          "type": "string",
+          "enum": ["api_call", "record_create", "record_update", "workflow", "scheduled_function", "widget_backend", "custom_function"],
+          "required": true
+        },
+        "context": {
+          "type": "string",
+          "description": "What the code needs to accomplish",
+          "required": true
+        },
+        "module": {
+          "type": "string",
+          "enum": ["crm", "books", "creator", "analytics", "catalyst", "desk"],
+          "required": false
+        }
+      }
+    },
+    {
+      "name": "get_workflow_guidance",
+      "description": "Get workflow automation guidance (synthesized, not raw templates)",
+      "parameters": {
+        "source": {
+          "type": "string",
+          "description": "Source module (e.g., crm)",
+          "required": true
+        },
+        "target": {
+          "type": "string",
+          "description": "Target module (e.g., books)",
+          "required": false
+        },
+        "trigger": {
+          "type": "string",
+          "enum": ["record_create", "record_update", "field_change", "scheduled", "button"],
+          "required": true
+        }
+      }
+    },
+    {
+      "name": "get_schedule_guidance",
+      "description": "Get scheduled function guidance (synthesized, not raw templates)",
+      "parameters": {
+        "frequency": {
+          "type": "string",
+          "enum": ["minutely", "hourly", "daily", "weekly", "monthly"],
+          "required": true
+        },
+        "task_type": {
+          "type": "string",
+          "description": "Type of task (sync, cleanup, report, notification)",
+          "required": true
+        }
+      }
+    },
+    {
+      "name": "search_knowledge",
+      "description": "Search the CloudStream knowledge base for relevant information",
+      "parameters": {
+        "query": {
+          "type": "string",
+          "description": "Search query",
+          "required": true
+        },
+        "category": {
+          "type": "string",
+          "enum": ["deluge", "workflow", "integration", "compliance", "all"],
+          "required": false,
+          "default": "all"
+        },
+        "limit": {
+          "type": "number",
+          "required": false,
+          "default": 5
+        }
+      }
+    },
+    {
+      "name": "get_best_practice",
+      "description": "Get CloudStream-approved best practice for a topic",
+      "parameters": {
+        "topic": {
+          "type": "string",
+          "description": "Topic to get best practice for",
+          "required": true
+        },
+        "compliance_mode": {
+          "type": "string",
+          "enum": ["hipaa", "soc2", "pci-dss", "standard"],
+          "required": false,
+          "default": "standard"
+        }
+      }
+    },
+    {
+      "name": "submit_learned_pattern",
+      "description": "Submit a new pattern learned during a session (internal users only)",
+      "parameters": {
+        "pattern_type": {
+          "type": "string",
+          "required": true
+        },
+        "code": {
+          "type": "string",
+          "required": true
+        },
+        "explanation": {
+          "type": "string",
+          "required": true
+        },
+        "context": {
+          "type": "string",
+          "required": false
+        }
+      },
+      "internal_only": true
+    }
+  ],
+  "security": {
+    "no_cache": true,
+    "cache_control": "private, no-store, no-cache, max-age=0",
+    "synthesized_responses_only": true,
+    "token_ttl_minutes": 15
+  }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@cloudstreamsoftware/claude-tools",
+  "version": "1.0.0",
+  "description": "CloudStream Claude Code productivity tools - hooks, skills, agents, and knowledge server integration",
+  "main": "dist/index.js",
+  "bin": {
+    "cloudstream-setup": "./bin/cloudstream-setup.js"
+  },
+  "scripts": {
+    "postinstall": "node ./bin/postinstall.js",
+    "setup": "node ./bin/cloudstream-setup.js",
+    "build": "node ./scripts/build.js",
+    "test": "node ./scripts/test.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "zoho",
+    "deluge",
+    "productivity",
+    "ai-tools",
+    "mcp",
+    "cloudstream"
+  ],
+  "author": "CloudStream Software",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cloudstream-dev/flowstate.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "config/",
+    "mcp/",
+    "README.md"
+  ],
+  "dependencies": {
+    "keytar": "^7.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}