snow-flow 4.5.13 → 4.5.15

package/CLAUDE.md

@@ -27,16 +27,72 @@ This document provides comprehensive instructions for Snow-Flow, an advanced Ser
 
 ## Core Philosophy
 
-### The Prime Directive: Verify, Don't Assume
+### The Prime Directive: Use Dedicated Tools First, Then Verify
 
-Snow-Flow operates on evidence-based development. Never make assumptions about what exists or doesn't exist in a ServiceNow environment. Every environment is unique with custom tables, fields, integrations, and configurations that you cannot predict.
+Snow-Flow operates on "**Tools-First, Evidence-Based**" development. Always use the highest-level, most specific tool available before falling back to generic approaches.
 
 **Cardinal Rules:**
-1. If code references something, it probably exists
-2. Test before declaring something broken
-3. Verify before modifying
-4. Fix only what's confirmed broken
-5. Respect existing configurations
+1. **🔍 Tool Discovery First** - Always search for dedicated MCP tools before using scripts
+2. **🎯 Use Highest-Level Tool** - Prefer domain-specific tools over generic database operations  
+3. **📊 Problem Categorization** - High-level business operations → dedicated tools, low-level data → scripts
+4. **✅ Verify, Don't Assume** - Test before declaring something broken
+5. **🔧 Fix Only Confirmed Issues** - Respect existing configurations
+
+### The Tools-First Approach
+
+**✅ CORRECT Decision Process:**
+```javascript
+// Step 1: User Request Analysis
+User: "Create agent workspace for IT support"
+
+// Step 2: Tool Discovery FIRST  
+Search Snow-Flow MCP tools for:
+- "create_workspace" → FOUND: snow_create_workspace
+- "workspace_create" → FOUND: snow_create_workspace  
+- "agent_workspace" → FOUND: snow_create_workspace
+
+// Step 3: Use Dedicated Tool
+const result = await snow_create_workspace({
+  name: "IT Support Workspace",
+  tables: ["incident", "task", "sys_user"],
+  description: "Agent workspace for IT support team"
+});
+
+// Step 4: Only if dedicated tool fails → verify with scripts
+if (!result.success && result.plugin_required) {
+  // Now use verification script to check plugin availability
+}
+```
+
+**❌ WRONG Approach (Anti-Pattern):**
+```javascript
+// DON'T DO THIS: Jumping straight to scripts for business operations
+User: "Create agent workspace"
+→ snow_execute_script_with_output({ script: "var gr = new GlideRecord('sys_aw_master_config')..." })
+
+// This bypasses all our error handling, plugin detection, and business logic!
+```
+
+### Problem Categorization Guide
+
+**🎯 High-Level Business Operations → Dedicated Tools:**
+- "Create workspace" → `snow_create_workspace`
+- "Create UI Builder page" → `snow_create_uib_page`  
+- "Deploy widget" → `snow_deploy`
+- "Create flow" → Flow Designer tools
+- "Add component to page" → `snow_add_uib_page_element`
+
+**🔧 Low-Level Data Operations → Scripts OK:**
+- "Check if field exists in table"
+- "Verify property value"  
+- "Test custom query"
+- "Debug specific record"
+
+**🚨 Decision Tree:**
+1. **User says "Create X"** → Search for `snow_create_X` or `snow_X_create` tools FIRST
+2. **User says "Configure Y"** → Search for `snow_configure_Y` tools FIRST  
+3. **User says "Custom script for Z"** → Scripts are appropriate
+4. **User says "Check/verify/test"** → Scripts for verification are good
 
 ### The Verification-First Approach
 

package/dist/cli.js

@@ -198,7 +198,7 @@ program
     }
     // Always show essential info
     cliLogger.info(`\n🚀 Snow-Flow v${version_js_1.VERSION}`);
-    cliLogger.info(`📋 Objective: ${objective}`);
+    console.log(chalk_1.default.blue(`📋 ${objective}`));
     // Only show detailed config in verbose mode
     if (options.verbose) {
         cliLogger.info(`⚙️  Strategy: ${options.strategy} | Mode: ${options.mode} | Max Agents: ${options.maxAgents}`);
@@ -251,7 +251,7 @@ program
     else {
         // In non-verbose mode, only show critical info
         if (options.autoDeploy) {
-            cliLogger.info(`🚀 Auto-Deploy: ENABLED - Will create real artifacts in ServiceNow`);
+            console.log(chalk_1.default.green(`✅ ServiceNow integration active - will create real artifacts`));
         }
         // Calculate autonomous systems for non-verbose mode (same logic as verbose)
         const noAutonomousAll = options.autonomousAll === false;
@@ -334,7 +334,7 @@ program
     }
     else if (!isAuthenticated) {
         // In non-verbose mode, only warn if not authenticated
-        cliLogger.warn('⚠️  Not authenticated. Run "snow-flow auth login" for ServiceNow integration');
+        console.log(chalk_1.default.yellow('⚠️  Not authenticated - run ') + chalk_1.default.cyan('snow-flow auth login') + chalk_1.default.yellow(' first'));
     }
     // Initialize Queen Agent memory system
     if (options.verbose) {
@@ -344,7 +344,10 @@ program
     const memorySystem = new QueenMemorySystem();
     // Generate swarm session ID
     const sessionId = `swarm_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-    cliLogger.info(`\n🔖 Session: ${sessionId}`);
+    // Session ID only in verbose mode
+    if (options.verbose) {
+        cliLogger.info(`🔖 Session: ${sessionId}`);
+    }
     // Store swarm session in memory
     memorySystem.storeLearning(`session_${sessionId}`, {
         objective,
@@ -411,10 +414,9 @@ program
             }
             else {
                 cliLogger.info('\n🔗 Live ServiceNow integration: ❌ Disabled');
-                cliLogger.info('📝 Artifacts will be saved to servicenow/ directory');
             }
         }
-        cliLogger.info('🚀 Launching Claude Code...');
+        console.log(chalk_1.default.blue('\n🚀 Starting Claude Code with 235+ ServiceNow tools...'));
         // Try to execute Claude Code directly with the prompt
         const success = await executeClaudeCode(orchestrationPrompt);
         if (success) {
@@ -510,20 +512,19 @@ async function executeClaudeCode(prompt) {
                 await manager.initialize();
                 const systemStatus = manager.getSystemStatus();
                 if (systemStatus.running === 0) {
-                    cliLogger.info('🚀 Starting MCP servers automatically for swarm operation...');
+                    console.log(chalk_1.default.yellow('🔧 Starting ServiceNow MCP servers...'));
                     await manager.startAllServers();
                     const newStatus = manager.getSystemStatus();
-                    cliLogger.info(`✅ Started ${newStatus.running}/${newStatus.total} MCP servers`);
+                    console.log(chalk_1.default.green(`✅ ${newStatus.running} MCP servers ready`));
                 }
                 else if (systemStatus.running < systemStatus.total) {
-                    cliLogger.info(`⚠️  Only ${systemStatus.running}/${systemStatus.total} MCP servers running`);
-                    cliLogger.info('🔄 Starting remaining servers...');
+                    console.log(chalk_1.default.yellow('🔄 Starting additional MCP servers...'));
                     await manager.startAllServers();
                     const newStatus = manager.getSystemStatus();
-                    cliLogger.info(`✅ All ${newStatus.running}/${newStatus.total} MCP servers running`);
+                    console.log(chalk_1.default.green(`✅ All ${newStatus.running} MCP servers ready`));
                 }
                 else {
-                    cliLogger.info(`✅ All ${systemStatus.running} MCP servers already running`);
+                    console.log(chalk_1.default.green(`✅ All ${systemStatus.running} MCP servers ready`));
                 }
             }
             catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snow-flow",
-  "version": "4.5.13",
+  "version": "4.5.15",
   "description": "Conversational ServiceNow development platform using Claude Code. Multi-agent orchestration with 20+ MCP servers providing 200+ ServiceNow tools for comprehensive platform development.",
   "main": "dist/index.js",
   "type": "commonjs",