snow-flow 1.4.4 → 1.4.6

package/dist/cli.js

@@ -2064,6 +2064,7 @@ program
     .description('Initialize a Snow-Flow project with SPARC environment')
     .option('--sparc', 'Initialize with SPARC methodology and MCP servers (recommended)', true)
     .option('--skip-mcp', 'Skip MCP server activation prompt')
+    .option('--force', 'Overwrite existing files without prompting')
     .action(async (options) => {
     console.log(chalk_1.default.blue.bold(`\n🚀 Initializing Snow-Flow Project v${version_js_1.VERSION}...`));
     console.log('='.repeat(60));
@@ -2071,19 +2072,19 @@ program
     try {
         // Create directory structure
         console.log('\n📁 Creating project structure...');
-        await createDirectoryStructure(targetDir);
+        await createDirectoryStructure(targetDir, options.force);
         // Create .env file
         console.log('🔐 Creating environment configuration...');
-        await createEnvFile(targetDir);
+        await createEnvFile(targetDir, options.force);
         // Create MCP configuration
         if (options.sparc) {
             console.log('🔧 Setting up MCP servers for Claude Code...');
-            await createMCPConfig(targetDir);
+            await createMCPConfig(targetDir, options.force);
             // Copy CLAUDE.md file
             console.log('📚 Creating documentation files...');
-            await copyCLAUDEmd(targetDir);
+            await copyCLAUDEmd(targetDir, options.force);
             // Create README files
-            await createReadmeFiles(targetDir);
+            await createReadmeFiles(targetDir, options.force);
         }
         console.log(chalk_1.default.green.bold('\n✅ Snow-Flow project initialized successfully!'));
         console.log('\n📋 Created files and directories:');
@@ -2122,6 +2123,8 @@ program
         console.log('2. Run: ' + chalk_1.default.cyan('snow-flow auth login'));
         console.log('3. Start developing: ' + chalk_1.default.cyan('snow-flow swarm "your objective"'));
         console.log('\n📚 Full documentation: https://github.com/groeimetai/snow-flow');
+        // Force exit to prevent hanging
+        process.exit(0);
     }
     catch (error) {
         console.error(chalk_1.default.red('\n❌ Initialization failed:'), error);
@@ -2190,7 +2193,7 @@ program
     `);
 });
 // Helper functions for init command
-async function createDirectoryStructure(targetDir) {
+async function createDirectoryStructure(targetDir, force = false) {
     const directories = [
         '.claude', '.claude/commands', '.claude/commands/sparc', '.claude/configs',
         '.swarm', '.swarm/sessions', '.swarm/agents',
@@ -2229,10 +2232,10 @@ async function createBasicConfig(targetDir) {
     await fs_1.promises.writeFile((0, path_1.join)(targetDir, '.claude/config.json'), JSON.stringify(claudeConfig, null, 2));
     await fs_1.promises.writeFile((0, path_1.join)(targetDir, '.swarm/config.json'), JSON.stringify(swarmConfig, null, 2));
 }
-async function createReadmeFiles(targetDir) {
+async function createReadmeFiles(targetDir, force = false) {
     // Only create README.md if it doesn't exist already
     const readmePath = (0, path_1.join)(targetDir, 'README.md');
-    if (!(0, fs_2.existsSync)(readmePath)) {
+    if (!(0, fs_2.existsSync)(readmePath) || force) {
         const mainReadme = `# Snow-Flow: Multi-Agent ServiceNow Development Platform 🚀
 
 Snow-Flow is a powerful multi-agent AI platform that revolutionizes ServiceNow development through intelligent automation, natural language processing, and autonomous deployment capabilities. Built with 11 specialized MCP (Model Context Protocol) servers, Snow-Flow enables developers to create, manage, and deploy ServiceNow artifacts using simple natural language commands.
@@ -2269,17 +2272,17 @@ Most intelligent features are now **enabled by default** - één command voor al
 ### 🤖 11 Specialized MCP Servers
 Each server provides autonomous capabilities for different aspects of ServiceNow development:
 
-1. **Deployment MCP** - Autonomous widget, flow, and application deployment
-2. **Flow Composer MCP** - Natural language flow creation with intelligent analysis
-3. **Update Set MCP** - Professional change tracking and deployment management
-4. **Intelligent MCP** - AI-powered artifact discovery and editing
-5. **Graph Memory MCP** - Relationship tracking and impact analysis
-6. **Platform Development MCP** - Development workflow automation
-7. **Integration MCP** - Third-party system integration
-8. **Operations MCP** - Operations and monitoring management
-9. **Automation MCP** - Workflow and process automation
-10. **Security & Compliance MCP** - Security auditing and compliance
-11. **Reporting & Analytics MCP** - Data analysis and reporting
+1. **Deployment MCP** - Autonomous widget and application deployment
+2. **Update Set MCP** - Professional change tracking and deployment management
+3. **Intelligent MCP** - AI-powered artifact discovery and editing
+4. **Graph Memory MCP** - Relationship tracking and impact analysis
+5. **Platform Development MCP** - Development workflow automation
+6. **Integration MCP** - Third-party system integration
+7. **Operations MCP** - Operations and monitoring management
+8. **Automation MCP** - Workflow and process automation
+9. **Security & Compliance MCP** - Security auditing and compliance
+10. **Reporting & Analytics MCP** - Data analysis and reporting
+11. **Memory MCP** - Multi-agent coordination and todo management
 
 ### 🎯 Core Capabilities
 
@@ -2556,7 +2559,6 @@ npm run build
 
 - [MCP Server Documentation](./MCP_SERVERS.md) - Detailed info on all 11 MCP servers
 - [OAuth Setup Guide](./SERVICENOW-OAUTH-SETUP.md) - ServiceNow OAuth configuration
-- [Flow Composer Guide](./ENHANCED_FLOW_COMPOSER_DOCUMENTATION.md) - Advanced flow creation
 - [Update Set Guide](./UPDATE_SET_DEPLOYMENT_GUIDE.md) - Professional change management
 - [API Integration Guide](./API_INTEGRATION_GUIDE.md) - ServiceNow API details
 
@@ -3273,183 +3275,9 @@ await snow_update_set_add_artifact({
         ]
     };
     await fs_1.promises.writeFile((0, path_1.join)(targetDir, 'memory/patterns/workflow-templates.json'), JSON.stringify(workflowPatternsContent, null, 2));
-    // Create quick start guide
-    const quickStartContent = `# Snow-Flow Quick Start Guide
-
-## 🚀 5-Minute Setup
-
-### 1. Initialize Your Project
-\`\`\`bash
-snow-flow init --sparc
-\`\`\`
-
-### 2. Configure ServiceNow OAuth
-Edit the .env file with your ServiceNow credentials:
-\`\`\`env
-SNOW_INSTANCE=dev123456.service-now.com
-SNOW_CLIENT_ID=your_oauth_client_id
-SNOW_CLIENT_SECRET=your_oauth_client_secret
-\`\`\`
-
-### 3. Authenticate
-\`\`\`bash
-snow-flow auth login
-\`\`\`
-
-### 4. Create Your First Widget
-\`\`\`bash
-snow-flow swarm "create simple incident counter widget"
-\`\`\`
-
-## 📋 What Just Happened?
-
-When you ran the swarm command, Snow-Flow:
-1. ✅ Validated your ServiceNow connection
-2. ✅ Analyzed your objective using Queen Agent
-3. ✅ Spawned 6+ parallel agents (widget-creator, css-specialist, backend-specialist, frontend-specialist, integration-specialist, tester)
-4. ✅ Created a real widget in your ServiceNow instance
-5. ✅ Tracked everything in an Update Set
-6. ✅ Tested the widget automatically
-
-## 🎯 Next Steps
-
-### Try More Examples
-\`\`\`bash
-# Create a workflow
-snow-flow swarm "create simple approval workflow"
-
-# Build a dashboard
-snow-flow swarm "create IT dashboard with KPIs"
-
-# Develop an application
-snow-flow swarm "create basic ticketing system"
-\`\`\`
-
-### Explore Documentation
-- **Swarm Patterns**: .claude/commands/swarm-patterns.md
-- **Agent Types**: .claude/commands/agent-types.md
-- **MCP Tools**: .claude/commands/mcp-tools-quick-ref.md
-- **Examples**: ./examples/
-
-### Monitor Progress
-\`\`\`bash
-# Check swarm status
-snow-flow swarm-status <sessionId>
-
-# View system status
-snow-flow status
-\`\`\`
-
-## 💡 Pro Tips
-
-1. **Start Simple**: Let the Queen Agent handle complexity
-2. **Use Natural Language**: Describe what you want, not how
-3. **Trust the Defaults**: Intelligent features are enabled
-4. **Check Examples**: Run scripts in ./examples/ folder
-
-## 🆘 Need Help?
-
-- **Auth Issues**: Run \`snow-flow auth status\`
-- **MCP Tools**: Check .claude/commands/mcp-tools-quick-ref.md
-- **Agent Info**: See .claude/commands/agent-types.md
-- **GitHub**: https://github.com/groeimetai/snow-flow
-
-Happy ServiceNow Development! 🎉
-`;
-    await fs_1.promises.writeFile((0, path_1.join)(targetDir, 'QUICK_START.md'), quickStartContent);
-    // Create example scripts
-    const widgetExampleContent = `#!/bin/bash
-# Example: Create an incident dashboard widget
-
-# This example shows how to create a comprehensive incident dashboard
-# with real-time data, charts, and mobile responsiveness
-
-snow-flow swarm "create incident dashboard widget with:
-- Real-time incident counts by priority (Critical, High, Medium, Low)
-- Chart.js bar chart showing incidents by category
-- Line graph for incident trends over the last 7 days
-- Responsive grid layout for mobile devices
-- Auto-refresh every 30 seconds
-- Click-through to incident details
-- Color coding for priority levels (red for critical, orange for high)
-- Export to PDF functionality
-- Filter by assignment group"
-
-# The Queen Agent will:
-# 1. Spawn widget-creator as primary agent
-# 2. Add ui-designer for responsive design
-# 3. Add tester for validation
-# 4. Create complete widget in ServiceNow
-# 5. Test on mobile and desktop
-# 6. Deploy with Update Set tracking
-`;
-    await fs_1.promises.writeFile((0, path_1.join)(targetDir, 'examples/widget-dashboard.sh'), widgetExampleContent);
-    await fs_1.promises.chmod((0, path_1.join)(targetDir, 'examples/widget-dashboard.sh'), '755');
-    const approvalFlowExampleContent = `#!/bin/bash
-# Example: Create equipment approval workflow
-
-# This example demonstrates creating a multi-level approval workflow
-# with dynamic routing based on cost and department
-
-snow-flow swarm "create approval workflow for equipment requests with:
-- Automatic approval for items under $100
-- Manager approval for items $100-$1000
-- Department head approval for items $1000-$5000
-- VP approval for items over $5000
-- IT approval required for all technology items regardless of cost
-- Finance review for items over $10000
-- Email notifications at each approval step
-- Slack notifications for urgent requests
-- 48-hour SLA with escalation
-- Rejection reasons and resubmission process
-- Integration with catalog items for equipment selection
-- Automatic PO generation upon final approval"
-
-# The Queen Agent will:
-# 1. Spawn flow-builder as primary agent
-# 2. Add security agent for approval permissions
-# 3. Add tester for all approval paths
-# 4. Create complex flow with conditions
-# 5. Link to catalog items
-# 6. Test all approval scenarios
-# 7. Validate email notifications
-`;
-    await fs_1.promises.writeFile((0, path_1.join)(targetDir, 'examples/approval-workflow.sh'), approvalFlowExampleContent);
-    await fs_1.promises.chmod((0, path_1.join)(targetDir, 'examples/approval-workflow.sh'), '755');
-    const itsmApplicationExampleContent = `#!/bin/bash
-# Example: Create complete ITSM solution
-
-# This example shows how to build a full IT Service Management application
-# with custom tables, workflows, and user interfaces
-
-snow-flow swarm "create complete ITSM solution for laptop provisioning with:
-- Custom request table extending task table
-- Fields: laptop_model, specifications, justification, cost_center
-- Catalog item for laptop requests with dynamic pricing
-- Multi-stage approval workflow based on cost and user role
-- Integration with asset management for laptop assignment
-- Automated Active Directory account provisioning
-- Email notifications to user, manager, and IT
-- Dashboard showing request status and metrics
-- SLA tracking with 5-day fulfillment target
-- Mobile-friendly request portal
-- Reporting on request volumes and fulfillment times
-- Return process for laptop replacement
-- Integration with purchase order system"
-
-# The Queen Agent will:
-# 1. Spawn app-architect to design the solution
-# 2. Add flow-builder for approval workflows
-# 3. Add widget-creator for dashboards
-# 4. Add script-writer for integrations
-# 5. Add security for access controls
-# 6. Add tester for end-to-end validation
-# 7. Create all components in sequence
-# 8. Deploy complete solution
-`;
-    await fs_1.promises.writeFile((0, path_1.join)(targetDir, 'examples/itsm-application.sh'), itsmApplicationExampleContent);
-    await fs_1.promises.chmod((0, path_1.join)(targetDir, 'examples/itsm-application.sh'), '755');
-    // Create CLAUDE.md by copying from source (v1.1.62+)
+}
+// Helper functions
+async function copyCLAUDEmd(targetDir, force = false) {
     let claudeMdContent = '';
     try {
         // First try to find the CLAUDE.md in the source directory (for global installs)
@@ -3477,56 +3305,96 @@ snow-flow swarm "create complete ITSM solution for laptop provisioning with:
             }
         }
         if (!foundSource) {
-            // Fallback to a minimal CLAUDE.md if source not found
+            // Use Snow-Flow specific CLAUDE.md content
             console.log('⚠️  Could not find CLAUDE.md source, creating minimal version');
             claudeMdContent = `# Snow-Flow Development with Claude Code
 
-## 🚀 Core Development Principles
+## 🚨 CRITICAL: MCP-FIRST WORKFLOW (READ THIS FIRST!)
 
-### Concurrent Execution Strategy
-**Golden Rule**: "1 MESSAGE = ALL RELATED OPERATIONS"
-- Always batch related MCP tool calls in a single response
-- Use TodoWrite extensively for complex task coordination
-- Launch multiple agents concurrently for maximum performance
-- Leverage batch file operations whenever reading/writing multiple files
+**Snow-flow's core value is REAL ServiceNow integration through MCP tools. NEVER work in offline mode!**
 
-### ServiceNow Development Best Practices
-1. **Never hardcode credentials** - Use OAuth and environment variables
-2. **Always work in Update Sets** - Provides rollback safety
-3. **Test before deploy** - Use mock testing tools for validation
-4. **Validate permissions** - Check OAuth scopes before operations
-5. **Use fuzzy search** - ServiceNow names can vary (iPhone vs iPhone 6S)
+### ⚠️ MANDATORY WORKFLOW - NO EXCEPTIONS
 
-## 📋 Essential MCP Tool Patterns
+**Every ServiceNow task MUST start with this sequence:**
 
-### Batch Operations for Maximum Efficiency
 \`\`\`javascript
-// GOOD: Single message with multiple tool calls
-TodoWrite([...tasks]);
-Task("Architect", "Design system architecture");
-Task("Developer", "Implement components");
-Task("Tester", "Create test scenarios");
-
-// BAD: Sequential single operations
-TodoWrite([task1]);
-// wait for response
-TodoWrite([task2]);
-// wait for response
-\`\`\`
+// 1. MANDATORY: Pre-flight authentication check
+const authCheck = await snow_validate_live_connection({ test_level: "permissions" });
+if (!authCheck.success) {
+  // STOP! Fix authentication first
+  return authenticationError(authCheck.error);
+}
 
-### Memory-Driven Coordination
-Use Memory to coordinate information across agents:
-\`\`\`javascript
-// Store architecture decisions
-snow_memory_store({
-  key: "widget_architecture",
-  value: "Service Portal widget with Chart.js for data visualization"
+// 2. MANDATORY: Discovery before creation
+const discovery = await snow_find_artifact({ 
+  query: "your objective",
+  type: "widget|flow|script|any" 
 });
 
-// All agents can reference this
-Task("Frontend Dev", "Implement widget based on widget_architecture in memory");
-Task("Backend Dev", "Create REST endpoints for widget_architecture requirements");
+// 3. MANDATORY: Real ServiceNow deployment
+const deployment = await snow_deploy({
+  type: "widget|application",  // Note: flow removed in v1.4.0+
+  config: { /* your config */ },
+  auto_update_set: true  // Always track changes
+});
+
+// 4. MANDATORY: Track in Update Set
+await snow_update_set_add_artifact({
+  type: deployment.type,
+  sys_id: deployment.result.sys_id,
+  name: deployment.result.name
+});
+\`\`\`
+
+### 🚫 FORBIDDEN ACTIONS
+
+**THESE ACTIONS ARE BANNED - NEVER DO THESE:**
+
+❌ **Creating local files** without MCP check first  
+❌ **Generating mock data** instead of using MCP tools  
+❌ **Working in "offline mode"** when ServiceNow is available  
+❌ **Skipping authentication validation**  
+❌ **Planning mode** without trying MCP tools first
+
+### ✅ CORRECT: MCP-First Decision Tree
+
 \`\`\`
+User Request → ALWAYS START HERE:
+    ↓
+1. snow_validate_live_connection()
+    ↓
+   SUCCESS? → Continue to Step 2
+    ↓
+   FAILURE? → Fix auth: snow_auth_diagnostics()
+              Then guide user: "snow-flow auth login"
+              STOP until auth works
+    ↓
+2. snow_find_artifact() // Check if exists
+    ↓
+   FOUND? → Ask: "Reuse existing or create new?"
+    ↓
+   NOT FOUND? → Continue to Step 3
+    ↓
+3. snow_deploy() // Real deployment to ServiceNow
+    ↓
+   SUCCESS? → Step 4: Track in Update Set
+    ↓
+   FAILURE? → Use fallback strategies
+    ↓
+4. snow_update_set_add_artifact() // Always track
+    ↓
+   DONE! ✅
+\`\`\`
+
+## 🚀 Snow-Flow Swarm Command - MCP-Orchestrated Multi-Agent Intelligence
+
+**The Swarm system is MCP-native and ALWAYS uses ServiceNow tools first!**
+
+### 🧠 Queen Agent with Parallel Execution (v1.4.0+)
+- Automatically spawns 6+ specialized agents for widget development
+- Achieves proven 2.8x speedup through intelligent parallel execution
+- All agents coordinate through Snow-Flow's memory system
+- Every agent uses MCP tools directly - no offline mode
 
 ## 🛠️ Complete ServiceNow MCP Tools Reference
 
@@ -3887,101 +3755,123 @@ This is a minimal CLAUDE.md file. The full documentation should be available in
 For full documentation, visit: https://github.com/groeimetai/snow-flow
 `;
         }
-        await fs_1.promises.writeFile((0, path_1.join)(targetDir, 'CLAUDE.md'), claudeMdContent);
+        const claudeMdPath = (0, path_1.join)(targetDir, 'CLAUDE.md');
+        try {
+            await fs_1.promises.access(claudeMdPath);
+            if (force) {
+                console.log('⚠️  CLAUDE.md already exists, overwriting with --force flag');
+                await fs_1.promises.writeFile(claudeMdPath, claudeMdContent);
+            }
+            else {
+                console.log('⚠️  CLAUDE.md already exists, skipping (use --force to overwrite)');
+            }
+        }
+        catch {
+            await fs_1.promises.writeFile(claudeMdPath, claudeMdContent);
+        }
     }
     catch (error) {
-        console.log('⚠️  Error copying CLAUDE.md, creating minimal version');
-        // Minimal fallback
+        console.log('⚠️  Error copying CLAUDE.md, creating Snow-Flow specific version');
+        // Snow-Flow specific fallback content
         const claudeMdFallback = `# Snow-Flow Development with Claude Code
 
-## Quick Start  
-1. \`snow-flow init --sparc\` - Initialize project with SPARC environment
-2. Configure ServiceNow credentials in .env file
-3. \`snow-flow auth login\` - Authenticate with ServiceNow OAuth  
-4. \`snow-flow swarm "create a widget for incident management"\` - Everything automatic!
+## 🚨 CRITICAL: MCP-FIRST WORKFLOW (READ THIS FIRST!)
 
-For full documentation, visit: https://github.com/groeimetai/snow-flow
-`;
-        await fs_1.promises.writeFile((0, path_1.join)(targetDir, 'CLAUDE.md'), claudeMdFallback);
-    }
+**Snow-flow's core value is REAL ServiceNow integration through MCP tools. NEVER work in offline mode!**
+
+### ⚠️ MANDATORY WORKFLOW - NO EXCEPTIONS
+
+**Every ServiceNow task MUST start with this sequence:**
+
+\`\`\`javascript
+// 1. MANDATORY: Pre-flight authentication check
+const authCheck = await snow_validate_live_connection({ test_level: "permissions" });
+if (!authCheck.success) {
+  // STOP! Fix authentication first
+  return authenticationError(authCheck.error);
 }
-async function copyCLAUDEmd(targetDir) {
-    let claudeMdContent = '';
-    try {
-        // First try to find the CLAUDE.md in the source directory (for global installs)
-        const sourceClaudeFiles = [
-            // Try the project root (when running from dist/)
-            (0, path_1.join)(__dirname, '..', 'CLAUDE.md'),
-            // Try when running directly from src/
-            (0, path_1.join)(__dirname, 'CLAUDE.md'),
-            // Try npm global installation paths  
-            (0, path_1.join)(__dirname, '..', '..', '..', 'CLAUDE.md'),
-            (0, path_1.join)(__dirname, '..', '..', '..', '..', 'CLAUDE.md'),
-            // Try current working directory as fallback
-            (0, path_1.join)(process.cwd(), 'CLAUDE.md')
-        ];
-        let foundSource = false;
-        for (const sourcePath of sourceClaudeFiles) {
-            try {
-                claudeMdContent = await fs_1.promises.readFile(sourcePath, 'utf8');
-                foundSource = true;
-                console.log(`✅ Found CLAUDE.md source at: ${sourcePath}`);
-                break;
-            }
-            catch {
-                // Continue to next path
-            }
-        }
-        if (!foundSource) {
-            // Fallback to a minimal CLAUDE.md if source not found
-            console.log('⚠️  Could not find CLAUDE.md source, creating minimal version');
-            claudeMdContent = `# Snow-Flow Development with Claude Code
 
-## 🚀 Core Development Principles
+// 2. MANDATORY: Discovery before creation
+const discovery = await snow_find_artifact({ 
+  query: "your objective",
+  type: "widget|flow|script|any" 
+});
+
+// 3. MANDATORY: Real ServiceNow deployment
+const deployment = await snow_deploy({
+  type: "widget|application",  // Note: flow removed in v1.4.0+
+  config: { /* your config */ },
+  auto_update_set: true  // Always track changes
+});
+
+// 4. MANDATORY: Track in Update Set
+await snow_update_set_add_artifact({
+  type: deployment.type,
+  sys_id: deployment.result.sys_id,
+  name: deployment.result.name
+});
+\`\`\`
+
+### 🚫 FORBIDDEN ACTIONS
 
-### Concurrent Execution Strategy
-**Golden Rule**: "1 MESSAGE = ALL RELATED OPERATIONS"
-- Always batch related MCP tool calls in a single response
-- Use TodoWrite extensively for complex task coordination
-- Launch multiple agents concurrently for maximum performance
-- Leverage batch file operations whenever reading/writing multiple files
+**THESE ACTIONS ARE BANNED - NEVER DO THESE:**
 
-### ServiceNow Development Best Practices
-1. **Never hardcode credentials** - Use OAuth and environment variables
-2. **Always work in Update Sets** - Provides rollback safety
-3. **Test before deploy** - Use mock testing tools for validation
-4. **Validate permissions** - Check OAuth scopes before operations
-5. **Use fuzzy search** - ServiceNow names can vary (iPhone vs iPhone 6S)
+❌ **Creating local files** without MCP check first  
+❌ **Generating mock data** instead of using MCP tools  
+❌ **Working in "offline mode"** when ServiceNow is available  
+❌ **Skipping authentication validation**  
+❌ **Planning mode** without trying MCP tools first
 
-## 📋 Essential MCP Tool Patterns
+### ✅ CORRECT: MCP-First Decision Tree
 
-### Batch Operations for Maximum Efficiency
-\`\`\`javascript
-// GOOD: Single message with multiple tool calls
-TodoWrite([...tasks]);
-Task("Architect", "Design system architecture");
-Task("Developer", "Implement components");
-Task("Tester", "Create test scenarios");
-
-// BAD: Sequential single operations
-TodoWrite([task1]);
-// wait for response
-TodoWrite([task2]);
-// wait for response
+\`\`\`
+User Request → ALWAYS START HERE:
+    ↓
+1. snow_validate_live_connection()
+    ↓
+   SUCCESS? → Continue to Step 2
+    ↓
+   FAILURE? → Fix auth: snow_auth_diagnostics()
+              Then guide user: "snow-flow auth login"
+              STOP until auth works
+    ↓
+2. snow_find_artifact() // Check if exists
+    ↓
+   FOUND? → Ask: "Reuse existing or create new?"
+    ↓
+   NOT FOUND? → Continue to Step 3
+    ↓
+3. snow_deploy() // Real deployment to ServiceNow
+    ↓
+   SUCCESS? → Step 4: Track in Update Set
+    ↓
+   FAILURE? → Use fallback strategies
+    ↓
+4. snow_update_set_add_artifact() // Always track
+    ↓
+   DONE! ✅
 \`\`\`
 
-### Memory-Driven Coordination
-Use Memory to coordinate information across agents:
-\`\`\`javascript
-// Store architecture decisions
-snow_memory_store({
-  key: "widget_architecture",
-  value: "Service Portal widget with Chart.js for data visualization"
-});
+## 🚀 Snow-Flow Swarm Command - MCP-Orchestrated Multi-Agent Intelligence
 
-// All agents can reference this
-Task("Frontend Dev", "Implement widget based on widget_architecture in memory");
-Task("Backend Dev", "Create REST endpoints for widget_architecture requirements");
+**The Swarm system is MCP-native and ALWAYS uses ServiceNow tools first!**
+
+### 🧠 Queen Agent with Parallel Execution (v1.4.0+)
+- Automatically spawns 6+ specialized agents for widget development
+- Achieves proven 2.8x speedup through intelligent parallel execution
+- All agents coordinate through Snow-Flow's memory system
+- Every agent uses MCP tools directly - no offline mode
+
+### Swarm Command Examples
+\`\`\`bash
+# Simple widget creation
+snow-flow swarm "create incident dashboard widget"
+
+# Complex development
+snow-flow swarm "build employee onboarding portal with approval workflows"
+
+# With specific options
+snow-flow swarm "create service catalog item" --no-auto-deploy --monitor
 \`\`\`
 
 ## 🛠️ Complete ServiceNow MCP Tools Reference
@@ -3998,370 +3888,161 @@ snow_find_artifact({
 snow_catalog_item_search({
   query: "laptop",
   fuzzy_match: true,        // Finds variations: notebook, MacBook, etc.
-  category_filter: "hardware",
-  include_variables: true   // Get catalog variables too
+  include_variables: true   // Include catalog variables
 });
 
-// Direct sys_id lookup (faster than search)
-snow_get_by_sysid({
-  sys_id: "<artifact_sys_id>",
-  table: "sp_widget"
+// Comprehensive search across all tables
+snow_comprehensive_search({
+  query: "approval",
+  include_inactive: false
 });
 \`\`\`
 
-### Flow Development Tools
+### Deployment Tools
 \`\`\`javascript
-// Create flows from natural language
-snow_create_flow({
-  instruction: "create a flow that sends email when incident priority is high",
-  deploy_immediately: true  // Automatically deploys XML to ServiceNow
-});
-
-// Test flows with mock data
-snow_test_flow_with_mock({
-  flow_id: "incident_notification_flow",
-  create_test_user: true,
-  mock_catalog_items: true,
-  test_inputs: {
-    priority: "1",
-    category: "hardware"
+// Universal deployment tool
+snow_deploy({
+  type: "widget",
+  config: {
+    name: "Incident Dashboard",
+    template: "<html>...</html>",
+    css: "/* styles */",
+    server_script: "// server code",
+    client_script: "// client code"
   },
-  simulate_approvals: true
+  auto_update_set: true
 });
 
-// Link catalog items to flows
-snow_link_catalog_to_flow({
-  catalog_item_id: "New Laptop Request",
-  flow_id: "laptop_provisioning_flow",
-  link_type: "flow_catalog_process",
-  variable_mapping: [
-    {
-      catalog_variable: "laptop_model",
-      flow_input: "equipment_type"
-    }
-  ]
+// Bulk deployment
+snow_bulk_deploy({
+  artifacts: [...],
+  transaction_mode: true,
+  rollback_on_error: true
 });
 \`\`\`
 
-### Widget Development Tools
+### Update Set Management
 \`\`\`javascript
-// Deploy widgets with automatic validation
-snow_deploy_widget({
-  name: "incident_dashboard",
-  title: "Incident Dashboard",
-  template: htmlContent,
-  css: cssContent,
-  client_script: clientJS,
-  server_script: serverJS,
-  demo_data: { incidents: [...] }
+// Ensure active Update Set
+snow_ensure_active_update_set({
+  context: "Widget development"
 });
 
-// Preview and test widgets
-snow_preview_widget({
-  widget_id: "incident_dashboard",
-  check_dependencies: true
+// Track artifacts
+snow_update_set_add_artifact({
+  type: "widget",
+  sys_id: "abc123",
+  name: "My Widget"
 });
 
-snow_widget_test({
-  widget_id: "incident_dashboard",
-  test_scenarios: [
-    {
-      name: "Load with no data",
-      server_data: { incidents: [] }
-    }
-  ]
+// Preview changes
+snow_update_set_preview({
+  update_set_id: "current"
 });
 \`\`\`
 
-### Bulk Operations
-\`\`\`javascript
-// Deploy multiple artifacts at once
-snow_bulk_deploy({
-  artifacts: [
-    { type: "widget", data: widgetData },
-    { type: "flow", data: flowData },
-    { type: "script", data: scriptData }
-  ],
-  transaction_mode: true,     // All or nothing
-  parallel: true,            // Deploy simultaneously
-  dry_run: false
-});
-\`\`\`
-
-### Intelligent Analysis
+### Testing Tools
 \`\`\`javascript
-// Analyze incidents with AI
-snow_analyze_incident({
-  incident_id: "INC0010001",
-  include_similar: true,
-  suggest_resolution: true
+// Test flows with mock data
+snow_test_flow_with_mock({
+  flow_id: "equipment_provisioning_flow",
+  create_test_user: true,
+  mock_catalog_items: true,
+  simulate_approvals: true,
+  cleanup_after_test: true
 });
 
-// Pattern analysis
-snow_pattern_analysis({
-  analysis_type: "incident_patterns",
-  timeframe: "month"
+// Link catalog to flow
+snow_link_catalog_to_flow({
+  catalog_item_id: "iPhone 6S",
+  flow_id: "mobile_provisioning_flow",
+  test_link: true
 });
 \`\`\`
 
-## ⚡ Performance Optimization
-
-### Parallel Execution Patterns
-\`\`\`javascript
-// Execute multiple searches concurrently
-Promise.all([
-  snow_find_artifact({ query: "incident widget" }),
-  snow_catalog_item_search({ query: "laptop" }),
-  snow_query_incidents({ query: "priority=1" })
-]);
-\`\`\`
+## 📋 Essential Patterns
 
-### Batch File Operations
+### Authentication Handling
 \`\`\`javascript
-// Read multiple files in one operation
-MultiRead([
-  "/path/to/widget.html",
-  "/path/to/widget.css",
-  "/path/to/widget.js"
-]);
+// Always handle auth failures gracefully
+if (error.includes('401') || error.includes('403')) {
+  // Guide user to fix authentication
+  console.log('Run: snow-flow auth login');
+  console.log('Check .env file for credentials');
+  // STOP - don't continue without auth
+}
 \`\`\`
 
-## 📝 Workflow Guidelines
-
-### Standard Development Flow
-1. **Discovery Phase**: Use search tools to find existing artifacts
-2. **Planning Phase**: Use TodoWrite to plan all tasks
-3. **Development Phase**: Launch agents concurrently
-4. **Testing Phase**: Use mock testing tools
-5. **Deployment Phase**: Use bulk deploy with validation
-
-### Error Recovery Patterns
+### Error Recovery
 \`\`\`javascript
-// Always implement rollback strategies
+// Implement fallback strategies
 if (deployment.failed) {
-  snow_deployment_rollback_manager({
-    update_set_id: deployment.update_set,
-    restore_point: deployment.backup_id
+  // Try global scope
+  const globalAttempt = await snow_deploy({ 
+    ...config, 
+    scope_preference: 'global' 
   });
+  
+  if (globalAttempt.failed) {
+    // Provide manual instructions
+    return createManualStepsGuide(config, error);
+  }
 }
 \`\`\`
 
-## 🔧 Advanced Configuration
+## 🔧 Configuration
 
-## Build Commands
+### Build Commands
 - \`npm run build\`: Build the project
 - \`npm run test\`: Run the full test suite
 - \`npm run lint\`: Run ESLint and format checks
 - \`npm run typecheck\`: Run TypeScript type checking
 
-## Snow-Flow Commands
-- \`snow-flow init --sparc\`: Initialize project with SPARC environment
-- \`snow-flow auth login\`: Authenticate with ServiceNow OAuth
-- \`snow-flow swarm "<objective>"\`: Start multi-agent swarm - één command voor alles!
-- \`snow-flow sparc <mode> "<task>"\`: Run specific SPARC mode
-
-## Enhanced Swarm Command (v1.1.41+)
-The swarm command now includes intelligent features that are **enabled by default**:
+### Snow-Flow Commands
+- \`snow-flow init --sparc\`: Initialize project with MCP servers
+- \`snow-flow auth login\`: Authenticate with ServiceNow
+- \`snow-flow swarm "<objective>"\`: Execute multi-agent development
+- \`snow-flow mcp start\`: Start MCP servers manually
 
+### Environment Setup
 \`\`\`bash
-# Simple usage - ALL autonomous systems enabled by default!
-snow-flow swarm "create incident management dashboard"
-
-# Disable specific autonomous systems if needed
-snow-flow swarm "create simple widget" --no-autonomous-cost-optimization --no-autonomous-compliance
-
-# Disable ALL autonomous systems
-snow-flow swarm "basic development only" --no-autonomous-all
-
-# Force enable all (overrides any --no- flags)
-snow-flow swarm "full orchestration mode" --autonomous-all
-\`\`\`
-
-### 🤖 NEW: Autonomous Systems (v1.3.26+) - **ENABLED BY DEFAULT!**
-True orchestration with zero manual intervention - all systems active unless disabled:
-
-- ✅ **Documentation**: Self-documenting system (auto-generates and updates docs)
-- ✅ **Cost Optimization**: AI-driven cost management with auto-optimization  
-- ✅ **Compliance**: Multi-framework compliance monitoring with auto-remediation
-- ✅ **Self-Healing**: Predictive failure detection with automatic recovery
-
-**Disable Options**:
-- \`--no-autonomous-documentation\`: Disable documentation system
-- \`--no-autonomous-cost-optimization\`: Disable cost optimization
-- \`--no-autonomous-compliance\`: Disable compliance monitoring
-- \`--no-autonomous-healing\`: Disable self-healing
-- \`--no-autonomous-all\`: Disable ALL autonomous systems
-
-**Force Options**:
-- \`--autonomous-all\`: Force enable all (overrides --no- flags)
-
-**Perfect Orchestrator**: Systems work autonomously, make intelligent decisions, and continuously improve - no manual intervention needed!
-
-### Default Settings (no flags needed):
-- ✅ \`--smart-discovery\` - Automatically discovers and reuses existing artifacts
-- ✅ \`--live-testing\` - Tests in real-time on your ServiceNow instance
-- ✅ \`--auto-deploy\` - Deploys automatically (safe with update sets)
-- ✅ \`--auto-rollback\` - Automatically rollbacks on failures
-- ✅ \`--shared-memory\` - All agents share context and coordination
-- ✅ \`--progress-monitoring\` - Real-time progress tracking
-- ❌ \`--auto-permissions\` - Disabled by default (enable with flag for automatic role elevation)
-
-### Advanced Usage:
-\`\`\`bash
-# Enable automatic permission escalation
-snow-flow swarm "create global workflow" --auto-permissions
-
-# Disable specific features
-snow-flow swarm "test widget" --no-auto-deploy --no-live-testing
-
-# Full control
-snow-flow swarm "complex integration" \\
-  --max-agents 8 \\
-  --strategy development \\
-  --mode distributed \\
-  --parallel \\
-  --auto-permissions
-\`\`\`
-
-## New MCP Tools (v1.1.44+)
-
-### Catalog Item Search
-Find catalog items with intelligent fuzzy matching:
-\`\`\`javascript
-snow_catalog_item_search({
-  query: "iPhone",          // Will find iPhone 6S, iPhone 7, etc.
-  fuzzy_match: true,        // Enable intelligent variations
-  include_variables: true   // Include catalog variables
-})
-\`\`\`
-
-### Flow Testing with Mock Data
-Test flows without real data:
-\`\`\`javascript
-snow_test_flow_with_mock({
-  flow_id: "equipment_provisioning_flow",
-  create_test_user: true,      // Creates test user
-  mock_catalog_items: true,    // Creates test catalog items
-  simulate_approvals: true,    // Auto-approves during test
-  cleanup_after_test: true     // Removes test data after
-})
-\`\`\`
-
-### Direct Catalog-Flow Linking
-Link catalog items directly to flows:
-\`\`\`javascript
-snow_link_catalog_to_flow({
-  catalog_item_id: "iPhone 6S",
-  flow_id: "mobile_provisioning_flow",
-  link_type: "flow_catalog_process",  // Modern approach
-  variable_mapping: [
-    {
-      catalog_variable: "phone_model",
-      flow_input: "device_type"
-    }
-  ],
-  test_link: true  // Creates test request
-})
-\`\`\`
-
-### OAuth Configuration
-\`\`\`env
 # .env file
 SNOW_INSTANCE=dev123456
 SNOW_CLIENT_ID=your_oauth_client_id
 SNOW_CLIENT_SECRET=your_oauth_client_secret
-SNOW_USERNAME=admin
-SNOW_PASSWORD=admin_password
-\`\`\`
-
-### Update Set Management
-\`\`\`javascript
-// Smart update set creation
-snow_smart_update_set({
-  name: "Auto-generated for widget development",
-  detect_context: true,  // Auto-detects what you're working on
-  auto_switch: true     // Switches when context changes
-});
 \`\`\`
 
-## 🎯 Quick Start
-1. \`snow-flow init --sparc\` - Initialize project with SPARC environment
-2. Configure ServiceNow credentials in .env file
-3. \`snow-flow auth login\` - Authenticate with ServiceNow OAuth
-4. \`snow-flow swarm "create a widget for incident management"\` - Everything automatic!
-
-## 💡 Important Notes
-
-### Do's
-- ✅ Use TodoWrite extensively for task tracking
-- ✅ Batch MCP tool calls for performance
-- ✅ Store important data in Memory for coordination
-- ✅ Test with mock data before deploying
-- ✅ Work within Update Sets for safety
-- ✅ Use fuzzy search for finding artifacts
-
-### Don'ts
-- ❌ Don't make sequential tool calls when batch is possible
-- ❌ Don't hardcode credentials or sys_ids
-- ❌ Don't deploy without testing
-- ❌ Don't ignore OAuth permission errors
-- ❌ Don't create artifacts without checking if they exist
-
-## 🚀 Performance Benchmarks
-
-With concurrent execution and batch operations:
-- **Widget Development**: 3x faster than sequential
-- **Flow Creation**: 2.5x faster with parallel validation
-- **Bulk Deployment**: Up to 5x faster with parallel mode
-- **Search Operations**: 4x faster with concurrent queries
-
-## 📚 Additional Resources
-
-### MCP Server Documentation
-- **servicenow-deployment**: Widget, flow, and application deployment
-- **servicenow-intelligent**: Smart search and artifact discovery
-- **servicenow-operations**: Incident management and catalog operations
-- **servicenow-platform-development**: Scripts, rules, and policies
-
-### SPARC Modes
-- \`orchestrator\`: Coordinates complex multi-step tasks
-- \`coder\`: Focused code implementation
-- \`researcher\`: Deep analysis and discovery
-- \`tester\`: Comprehensive testing strategies
-- \`architect\`: System design and architecture
+## 💡 Best Practices
 
----
+### DO's
+✅ Always use \`snow_validate_live_connection()\` first  
+✅ Check for existing artifacts with \`snow_find_artifact()\`  
+✅ Use Update Sets for all changes  
+✅ Test with mock data before production  
+✅ Handle errors gracefully with fallbacks  
 
-This is a minimal CLAUDE.md file. The full documentation should be available in your Snow-Flow installation.
+### DON'Ts
+❌ Don't create local files first  
+❌ Don't skip authentication  
+❌ Don't hardcode sys_ids or credentials  
+❌ Don't work in offline mode  
+❌ Don't deploy without testing  
 
-## Quick Start
-1. \`snow-flow init --sparc\` - Initialize project with SPARC environment
+## 🎯 Quick Start
+1. \`snow-flow init --sparc\` - Initialize project with MCP servers
 2. Configure ServiceNow credentials in .env file  
-3. \`snow-flow auth login\` - Authenticate with ServiceNow OAuth
+3. \`snow-flow auth login\` - Authenticate with ServiceNow
 4. \`snow-flow swarm "create a widget for incident management"\` - Everything automatic!
 
 For full documentation, visit: https://github.com/groeimetai/snow-flow
 `;
+        const claudeMdPath = (0, path_1.join)(targetDir, 'CLAUDE.md');
+        if (force || !(0, fs_2.existsSync)(claudeMdPath)) {
+            await fs_1.promises.writeFile(claudeMdPath, claudeMdFallback);
         }
-        await fs_1.promises.writeFile((0, path_1.join)(targetDir, 'CLAUDE.md'), claudeMdContent);
-    }
-    catch (error) {
-        console.log('⚠️  Error copying CLAUDE.md, creating minimal version');
-        // Minimal fallback
-        const claudeMdFallback = `# Snow-Flow Development with Claude Code
-
-## Quick Start  
-1. \`snow-flow init --sparc\` - Initialize project with SPARC environment
-2. Configure ServiceNow credentials in .env file
-3. \`snow-flow auth login\` - Authenticate with ServiceNow OAuth  
-4. \`snow-flow swarm "create a widget for incident management"\` - Everything automatic!
-
-For full documentation, visit: https://github.com/groeimetai/snow-flow
-`;
-        await fs_1.promises.writeFile((0, path_1.join)(targetDir, 'CLAUDE.md'), claudeMdFallback);
     }
 }
-async function createEnvFile(targetDir) {
+async function createEnvFile(targetDir, force = false) {
     const envContent = `# ServiceNow OAuth Configuration
 # Replace these values with your actual ServiceNow instance and OAuth credentials
 
@@ -4416,10 +4097,17 @@ SNOW_FLOW_TIMEOUT_MINUTES=0
     // Check if .env already exists
     try {
         await fs_1.promises.access(envFilePath);
-        console.log('⚠️  .env file already exists, creating .env.example template instead');
-        console.log('📝 To recreate .env: delete existing .env file and run init again');
-        await fs_1.promises.writeFile((0, path_1.join)(targetDir, '.env.example'), envContent);
-        console.log('✅ .env.example template created');
+        if (force) {
+            console.log('⚠️  .env file already exists, overwriting with --force flag');
+            await fs_1.promises.writeFile(envFilePath, envContent);
+            console.log('✅ .env file overwritten successfully');
+        }
+        else {
+            console.log('⚠️  .env file already exists, creating .env.example template instead');
+            console.log('📝 To overwrite: use --force flag or delete existing .env file');
+            await fs_1.promises.writeFile((0, path_1.join)(targetDir, '.env.example'), envContent);
+            console.log('✅ .env.example template created');
+        }
     }
     catch {
         // .env doesn't exist, create it
@@ -4453,7 +4141,7 @@ async function checkNeo4jAvailability() {
         return false;
     }
 }
-async function createMCPConfig(targetDir) {
+async function createMCPConfig(targetDir, force = false) {
     // Determine the snow-flow installation directory
     let snowFlowRoot;
     // Check if we're in a global npm installation
@@ -4483,15 +4171,6 @@ async function createMCPConfig(targetDir) {
                     "SNOW_CLIENT_SECRET": "${SNOW_CLIENT_SECRET}"
                 }
             },
-            "servicenow-flow-composer": {
-                "command": "node",
-                "args": [(0, path_1.join)(distPath, "mcp/servicenow-flow-composer-mcp.js")],
-                "env": {
-                    "SNOW_INSTANCE": "${SNOW_INSTANCE}",
-                    "SNOW_CLIENT_ID": "${SNOW_CLIENT_ID}",
-                    "SNOW_CLIENT_SECRET": "${SNOW_CLIENT_SECRET}"
-                }
-            },
             "servicenow-update-set": {
                 "command": "node",
                 "args": [(0, path_1.join)(distPath, "mcp/servicenow-update-set-mcp.js")],
@@ -4580,7 +4259,19 @@ async function createMCPConfig(targetDir) {
     };
     // Create .mcp.json in project root for Claude Code discovery
     const mcpConfigPath = (0, path_1.join)(targetDir, '.mcp.json');
-    await fs_1.promises.writeFile(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
+    try {
+        await fs_1.promises.access(mcpConfigPath);
+        if (force) {
+            console.log('⚠️  .mcp.json already exists, overwriting with --force flag');
+            await fs_1.promises.writeFile(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
+        }
+        else {
+            console.log('⚠️  .mcp.json already exists, skipping (use --force to overwrite)');
+        }
+    }
+    catch {
+        await fs_1.promises.writeFile(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
+    }
     // Also create legacy config in .claude for backward compatibility
     const legacyConfigPath = (0, path_1.join)(targetDir, '.claude/mcp-config.json');
     await fs_1.promises.writeFile(legacyConfigPath, JSON.stringify(mcpConfig, null, 2));