snow-flow 1.1.83 → 1.1.85

package/dist/cli.js

@@ -409,30 +409,121 @@ You are the Queen Agent, master coordinator of the Snow-Flow hive-mind. Your mis
 
 ## 👑 Your Queen Agent Responsibilities
 
-### 1. Initialize Swarm Session
-First, store the swarm session context in memory:
+### 1. CRITICAL: Initialize Memory FIRST (Before Everything!)
+**THIS MUST BE YOUR VERY FIRST ACTION - Initialize the swarm memory session:**
 \`\`\`javascript
-// Initialize swarm session
-Memory.store("swarm_session_${sessionId}", {
-  objective: "${objective}",
-  status: "initializing",
-  started_at: new Date().toISOString(),
-  queen_agent_id: "queen_${sessionId}",
-  task_analysis: ${JSON.stringify(taskAnalysis, null, 2)},
-  configuration: {
-    strategy: "${options.strategy}",
-    mode: "${options.mode}",
-    max_agents: ${parseInt(options.maxAgents)},
-    parallel_execution: ${options.parallel ? 'true' : 'false'},
-    monitoring_enabled: ${options.monitor ? 'true' : 'false'}
+// 🚨 EXECUTE THIS IMMEDIATELY - DO NOT SKIP OR DELAY!
+mcp__claude-flow__memory_usage({
+  action: "store",
+  key: "swarm_session_${sessionId}",
+  value: JSON.stringify({
+    objective: "${objective}",
+    status: "initializing",
+    started_at: new Date().toISOString(),
+    queen_agent_id: "queen_${sessionId}",
+    task_analysis: ${JSON.stringify(taskAnalysis, null, 2)},
+    configuration: {
+      strategy: "${options.strategy}",
+      mode: "${options.mode}",
+      max_agents: ${parseInt(options.maxAgents)},
+      parallel_execution: ${options.parallel ? 'true' : 'false'},
+      monitoring_enabled: ${options.monitor ? 'true' : 'false'},
+      auth_required: ${!isAuthenticated}
+    }
+  }),
+  namespace: "swarm_${sessionId}"
+});
+
+// Initialize agent coordination memory namespace
+mcp__claude-flow__memory_namespace({
+  action: "create",
+  namespace: "agents_${sessionId}"
+});
+\`\`\`
+
+### 2. MANDATORY MCP-FIRST Workflow Steps
+**Execute these steps IN ORDER before spawning agents:**
+
+\`\`\`javascript
+// Step 2.1: Validate ServiceNow authentication
+const authCheck = await mcp__servicenow-intelligent__snow_validate_live_connection({
+  test_level: "permissions",
+  include_performance: false
+});
+
+if (!authCheck.connection_status === "success") {
+  throw new Error("Authentication failed! Run: snow-flow auth login");
+}
+
+// Step 2.2: Check for existing artifacts (DRY principle)
+const existingArtifacts = await mcp__servicenow-intelligent__snow_comprehensive_search({
+  query: "${objective}",
+  include_inactive: false
+});
+
+// Store discovery results in memory for agents
+await mcp__claude-flow__memory_usage({
+  action: "store",
+  key: "existing_artifacts_${sessionId}",
+  value: JSON.stringify(existingArtifacts),
+  namespace: "swarm_${sessionId}"
+});
+
+// Step 2.3: Create isolated Update Set for this objective
+const updateSetName = "Snow-Flow: ${objective.substring(0, 50)}... - ${new Date().toISOString().split('T')[0]}";
+const updateSet = await mcp__servicenow-update-set__snow_update_set_create({
+  name: updateSetName,
+  description: "Automated creation for: ${objective}\\n\\nSession: ${sessionId}",
+  auto_switch: true
+});
+
+// Store Update Set info in memory
+await mcp__claude-flow__memory_usage({
+  action: "store", 
+  key: "update_set_${sessionId}",
+  value: JSON.stringify(updateSet),
+  namespace: "swarm_${sessionId}"
+});
+
+// Step 2.4: For artifacts using tables, discover table schemas
+${taskAnalysis.serviceNowArtifacts.includes('widget') || taskAnalysis.serviceNowArtifacts.includes('flow') ? `
+// Discover common ITSM tables
+const tablesToDiscover = ['incident', 'sc_request', 'change_request', 'problem'];
+const tableSchemas = {};
+
+for (const table of tablesToDiscover) {
+  try {
+    const schema = await mcp__servicenow-platform-development__snow_table_schema_discovery({
+      tableName: table,
+      includeRelated: true,
+      includeIndexes: false
+    });
+    tableSchemas[table] = schema;
+  } catch (e) {
+    // Table might not exist, continue
   }
+}
+
+// Store table schemas in memory
+await mcp__claude-flow__memory_usage({
+  action: "store",
+  key: "table_schemas_${sessionId}",
+  value: JSON.stringify(tableSchemas),
+  namespace: "swarm_${sessionId}"
 });
+` : '// No table discovery needed for this task type'}
 \`\`\`
 
-### 2. Create Master Task List
-Use TodoWrite to create a comprehensive task breakdown:
+### 3. Create Master Task List
+After completing MCP-FIRST steps, create task breakdown:
 \`\`\`javascript
 TodoWrite([
+  {
+    id: "mcp_workflow_complete",
+    content: "✅ MCP-FIRST workflow: Auth, Discovery, Update Set, Tables",
+    status: "completed",
+    priority: "high"
+  },
   {
     id: "analyze_requirements",
     content: "Analyze user requirements: ${objective}",
@@ -460,7 +551,7 @@ TodoWrite([
 ]);
 \`\`\`
 
-### 3. Spawn Specialized Agents
+### 4. Spawn Specialized Agents
 Based on the task analysis, spawn the following agents using the Task tool:
 
 **Primary Agent**: ${taskAnalysis.primaryAgent}
@@ -474,19 +565,21 @@ Task("${taskAnalysis.primaryAgent}", \`
   Task Type: ${taskAnalysis.taskType}
   
   Instructions:
-  1. Read swarm context from Memory key: "swarm_session_${sessionId}"
-  2. Begin implementing the core ${taskAnalysis.taskType} requirements
-  3. Store all work progress in Memory with prefix: "agent_${taskAnalysis.primaryAgent}_"
-  4. Update TodoWrite items as you complete tasks
-  5. Coordinate with supporting agents through Memory
+  1. FIRST: Read ALL shared context from memory:
+     - mcp__claude-flow__memory_usage({action: "retrieve", key: "swarm_session_${sessionId}", namespace: "swarm_${sessionId}"})
+     - mcp__claude-flow__memory_usage({action: "retrieve", key: "existing_artifacts_${sessionId}", namespace: "swarm_${sessionId}"})
+     - mcp__claude-flow__memory_usage({action: "retrieve", key: "update_set_${sessionId}", namespace: "swarm_${sessionId}"})
+     - mcp__claude-flow__memory_usage({action: "retrieve", key: "table_schemas_${sessionId}", namespace: "swarm_${sessionId}"})
+  2. Use the discovered table schemas when creating artifacts that reference tables
+  3. Check existing_artifacts to avoid duplication - reuse or extend existing ones
+  4. ALL deployments MUST use the Update Set stored in memory
+  5. Begin implementing the core ${taskAnalysis.taskType} requirements
+  6. Store all work progress with: mcp__claude-flow__memory_usage({action: "store", key: "agent_${taskAnalysis.primaryAgent}_progress", value: "...", namespace: "agents_${sessionId}"})
+  7. Update TodoWrite items as you complete tasks
+  8. Read other agents' progress from namespace "agents_${sessionId}"
   
-  🔐 AUTHENTICATION WORKFLOW (MANDATORY):
-  1. ALWAYS start with an MCP tool to check authentication status
-  2. If any MCP tool returns auth error:
-     - The tool will provide SPECIFIC instructions (e.g., "Run snow-flow auth login")
-     - Switch to PLANNING MODE - document the COMPLETE solution
-     - Store all plans in Memory for future automated deployment
-  3. NEVER skip directly to local files - always try MCP first!
+  🔐 AUTHENTICATION: Already validated by Queen. Use MCP tools directly.
+  📦 UPDATE SET: Use the one from memory - DO NOT create a new one!
 \`);
 \`\`\`
 
@@ -503,12 +596,20 @@ Task("${agent}", \`
   Primary Agent: ${taskAnalysis.primaryAgent}
   
   Instructions:
-  1. Wait for primary agent to establish base structure
-  2. Read context from Memory: "swarm_session_${sessionId}"
-  3. Read primary agent's work from: "agent_${taskAnalysis.primaryAgent}_*"
-  4. Enhance/support with your ${agent} expertise
-  5. Store outputs in Memory with prefix: "agent_${agent}_"
-  6. Update relevant TodoWrite items
+  1. FIRST: Read ALL shared context from memory (same as primary agent):
+     - mcp__claude-flow__memory_usage({action: "retrieve", key: "swarm_session_${sessionId}", namespace: "swarm_${sessionId}"})
+     - mcp__claude-flow__memory_usage({action: "retrieve", key: "existing_artifacts_${sessionId}", namespace: "swarm_${sessionId}"})
+     - mcp__claude-flow__memory_usage({action: "retrieve", key: "update_set_${sessionId}", namespace: "swarm_${sessionId}"})
+     - mcp__claude-flow__memory_usage({action: "retrieve", key: "table_schemas_${sessionId}", namespace: "swarm_${sessionId}"})
+  2. Monitor primary agent's progress: mcp__claude-flow__memory_search({pattern: "agent_${taskAnalysis.primaryAgent}_*", namespace: "agents_${sessionId}"})
+  3. Wait for primary agent to establish base structure before major changes
+  4. Use discovered table schemas for any table references
+  5. Enhance/support with your ${agent} expertise
+  6. Store your progress: mcp__claude-flow__memory_usage({action: "store", key: "agent_${agent}_progress", value: "...", namespace: "agents_${sessionId}"})
+  7. Update relevant TodoWrite items
+  
+  🔐 AUTHENTICATION: Already validated by Queen. Use MCP tools directly.
+  📦 UPDATE SET: Use the one from memory - DO NOT create a new one!
   
   🔐 AUTHENTICATION REQUIREMENTS:
   - ALWAYS use MCP tools first - inherit auth status from primary agent
@@ -641,29 +742,97 @@ Agents must ALWAYS try MCP tools first!` : ''}
 
 ## 👑 Queen Agent Coordination Instructions
 
-### 5. Monitor Agent Progress
-As Queen Agent, continuously monitor swarm progress:
+### 5. Claude-Flow Memory Synchronization Pattern
+Implement continuous memory synchronization for real-time coordination:
 
 \`\`\`javascript
-// Monitor agent status
-const checkAgentProgress = () => {
-  const agents = [${[taskAnalysis.primaryAgent, ...taskAnalysis.supportingAgents].map(a => `"${a}"`).join(', ')}];
+// Initialize coordination heartbeat (Claude-Flow pattern)
+const coordinationInterval = setInterval(async () => {
+  // Sync agent states across namespace
+  const agentStates = await mcp__claude-flow__memory_search({
+    pattern: "agent_*_progress",
+    namespace: "agents_${sessionId}",
+    limit: 50
+  });
   
-  agents.forEach(agent => {
-    const progress = Memory.get(\`agent_\${agent}_progress\`);
-    const completion = Memory.get(\`agent_\${agent}_complete\`);
-    
-    console.log(\`Agent \${agent}: \${progress?.status || 'not started'}\`);
-    if (progress?.completion_percentage) {
-      console.log(\`  Progress: \${progress.completion_percentage}%\`);
-    }
+  // Update swarm coordination state with TTL for freshness
+  await mcp__claude-flow__memory_usage({
+    action: "store",
+    key: "swarm_coordination_${sessionId}",
+    value: JSON.stringify({
+      timestamp: new Date().toISOString(),
+      active_agents: agentStates.length,
+      completion_status: TodoRead().filter(t => t.status === 'completed').length,
+      memory_sync: true,
+      discovered_artifacts: agentStates.filter(s => s.includes("deployed")).length
+    }),
+    namespace: "swarm_${sessionId}",
+    ttl: 300 // 5 minute TTL for coordination data
   });
-};
-
-// Update swarm status
-Memory.update("swarm_session_${sessionId}", {
-  status: "agents_working",
-  last_check: new Date().toISOString()
+  
+  // Detect and resolve conflicts between agents
+  if (agentStates.some(s => s.includes("conflict") || s.includes("duplicate"))) {
+    await mcp__claude-flow__memory_usage({
+      action: "store",
+      key: "conflict_resolution_needed",
+      value: JSON.stringify({
+        agents: agentStates.filter(s => s.includes("conflict")),
+        timestamp: new Date().toISOString()
+      }),
+      namespace: "swarm_${sessionId}"
+    });
+  }
+  
+  // Track deployed artifacts in Update Set automatically
+  const deployedArtifacts = [];
+  for (const state of agentStates) {
+    if (state.includes("deployed") && state.includes("sys_id")) {
+      try {
+        const artifact = JSON.parse(state);
+        if (artifact.sys_id && !artifact.tracked_in_update_set) {
+          deployedArtifacts.push(artifact);
+        }
+      } catch (e) {
+        // Not valid JSON, skip
+      }
+    }
+  }
+  
+  // Add all deployed artifacts to Update Set
+  for (const artifact of deployedArtifacts) {
+    await mcp__servicenow-update-set__snow_update_set_add_artifact({
+      type: artifact.type,
+      sys_id: artifact.sys_id,
+      name: artifact.name
+    });
+    
+    // Mark as tracked
+    artifact.tracked_in_update_set = true;
+    await mcp__claude-flow__memory_usage({
+      action: "store",
+      key: \`agent_\${artifact.agent}_deployed_\${artifact.sys_id}\`,
+      value: JSON.stringify(artifact),
+      namespace: "agents_${sessionId}"
+    });
+  }
+  
+  // Monitor individual agent progress
+  const agents = [${[taskAnalysis.primaryAgent, ...taskAnalysis.supportingAgents].map(a => `"${a}"`).join(', ')}];
+  for (const agent of agents) {
+    const progress = agentStates.find(s => s.includes(\`agent_\${agent}_progress\`));
+    console.log(\`Agent \${agent}: \${progress ? 'active' : 'waiting'}\`);
+  }
+}, 10000); // Every 10 seconds
+
+// Also update main session state
+await mcp__claude-flow__memory_usage({
+  action: "store",
+  key: "swarm_session_${sessionId}",
+  value: JSON.stringify({
+    status: "agents_working",
+    last_check: new Date().toISOString()
+  }),
+  namespace: "swarm_${sessionId}"
 });
 \`\`\`
 
@@ -1747,6 +1916,799 @@ This mode provides specialized ${mode} capabilities for ServiceNow development p
 `;
         await fs_1.promises.writeFile((0, path_1.join)(targetDir, `.claude/commands/sparc/${mode}.md`), content);
     }
+    // Create additional swarm documentation files
+    console.log('📋 Creating swarm patterns documentation...');
+    // Create swarm-patterns.md
+    const swarmPatternsContent = `# Swarm Command Patterns - MCP-FIRST Workflow
+
+## 🎯 Primary Interface: snow-flow swarm
+
+The swarm command is your primary interface for ServiceNow development. It uses the Queen Agent backend to orchestrate multiple specialized agents through Claude Code.
+
+## Basic Widget Creation
+\`\`\`bash
+snow-flow swarm "create incident dashboard widget"
+snow-flow swarm "build responsive widget with Chart.js for incident analytics"
+snow-flow swarm "create service portal widget for hardware requests"
+\`\`\`
+
+## Flow Development  
+\`\`\`bash
+snow-flow swarm "create approval workflow for equipment requests"
+snow-flow swarm "build multi-step approval flow with email notifications"
+snow-flow swarm "create automated incident escalation workflow"
+\`\`\`
+
+## Complex Integration
+\`\`\`bash
+snow-flow swarm "integrate ServiceNow with Slack notifications"
+snow-flow swarm "create REST API integration with external ticketing system"
+snow-flow swarm "build bi-directional sync with Microsoft Teams"
+\`\`\`
+
+## Testing Patterns
+\`\`\`bash
+snow-flow swarm "test existing flows and create comprehensive test report"
+snow-flow swarm "validate all widgets in service portal for mobile responsiveness"
+snow-flow swarm "performance test catalog item workflows"
+\`\`\`
+
+## Application Development
+\`\`\`bash
+snow-flow swarm "create complete ITSM solution with custom tables"
+snow-flow swarm "build employee onboarding application with approval flows"
+snow-flow swarm "develop asset management system with automated workflows"
+\`\`\`
+
+## Advanced Patterns with Options
+
+### Disable Auto-Deploy for Testing
+\`\`\`bash
+snow-flow swarm "test new widget locally" --no-auto-deploy --no-live-testing
+\`\`\`
+
+### Enable Permission Escalation
+\`\`\`bash
+snow-flow swarm "create global enterprise workflow" --auto-permissions
+\`\`\`
+
+### Parallel Execution for Large Projects
+\`\`\`bash
+snow-flow swarm "migrate 50 workflows from legacy system" --parallel --max-agents 8
+\`\`\`
+
+### Monitor Real-Time Progress
+\`\`\`bash
+snow-flow swarm "complex ITSM implementation" --monitor
+\`\`\`
+
+## 🔐 MCP-FIRST Workflow
+
+Every swarm command follows this mandatory workflow:
+
+1. **Authentication Check**: Validates ServiceNow OAuth credentials
+2. **Smart Discovery**: Finds existing artifacts to prevent duplication
+3. **Live Development**: Creates real artifacts in ServiceNow
+4. **Update Set Tracking**: All changes tracked for deployment
+
+## 💡 Best Practices
+
+- Start simple: Let the Queen Agent determine complexity
+- Use natural language: Describe what you want, not how to build it
+- Trust the defaults: Intelligent features are enabled automatically
+- Monitor progress: Use --monitor for long-running tasks
+
+## 🎯 Common Success Patterns
+
+### Pattern 1: Quick Widget
+\`\`\`bash
+snow-flow swarm "simple dashboard widget"
+# Queen Agent will:
+# - Spawn widget-creator agent
+# - Create HTML/CSS/JS
+# - Deploy to ServiceNow
+# - Test automatically
+\`\`\`
+
+### Pattern 2: Complex Flow
+\`\`\`bash
+snow-flow swarm "multi-department approval workflow with dynamic routing"
+# Queen Agent will:
+# - Spawn flow-builder, tester, and security agents
+# - Design flow architecture
+# - Implement with conditions
+# - Test all paths
+# - Validate permissions
+\`\`\`
+
+### Pattern 3: Full Application
+\`\`\`bash
+snow-flow swarm "complete HR onboarding system"
+# Queen Agent will:
+# - Spawn app-architect, flow-builder, widget-creator, tester
+# - Design data model
+# - Create tables and relationships
+# - Build UI components
+# - Implement workflows
+# - Test end-to-end
+\`\`\`
+`;
+    await fs_1.promises.writeFile((0, path_1.join)(targetDir, '.claude/commands/swarm-patterns.md'), swarmPatternsContent);
+    // Create agent-types.md
+    const agentTypesContent = `# Agent Types and Specializations
+
+## 🤖 Primary Development Agents
+
+### widget-creator
+**Specialization**: Service Portal widgets, HTML/CSS/JS, responsive design
+**When spawned**: Any widget-related objective
+**Key capabilities**:
+- HTML template generation
+- CSS styling and animations
+- Client-side JavaScript controllers
+- Server-side data scripts
+- Chart.js and data visualization
+- Mobile responsiveness
+
+### flow-builder
+**Specialization**: Flow Designer, process automation, approvals
+**When spawned**: Workflow and automation objectives
+**Key capabilities**:
+- Trigger configuration
+- Conditional logic
+- Approval routing
+- Email notifications
+- Integration with catalog items
+- Subflow creation
+
+### script-writer
+**Specialization**: Business rules, script includes, client scripts
+**When spawned**: Scripting and automation objectives
+**Key capabilities**:
+- GlideRecord operations
+- Business rule creation
+- Script include development
+- Background scripts
+- Fix scripts
+- Scheduled jobs
+
+### app-architect
+**Specialization**: Application design, data modeling, system architecture
+**When spawned**: Full application development
+**Key capabilities**:
+- Table design and relationships
+- Application scoping
+- Security model design
+- Integration architecture
+- Performance optimization
+- Scalability planning
+
+## 🛠️ Supporting Agents
+
+### researcher
+**Specialization**: Discovery, best practices, documentation
+**When spawned**: Complex or unknown requirements
+**Key capabilities**:
+- ServiceNow best practices
+- Platform feature discovery
+- Existing artifact analysis
+- Documentation generation
+- Knowledge base creation
+
+### tester
+**Specialization**: Quality assurance, validation, performance testing
+**When spawned**: After any development task
+**Key capabilities**:
+- Unit test creation
+- Integration testing
+- UI/UX validation
+- Performance benchmarking
+- Security testing
+- Accessibility compliance
+
+### security
+**Specialization**: Access controls, compliance, vulnerability assessment
+**When spawned**: Enterprise or sensitive applications
+**Key capabilities**:
+- ACL configuration
+- Role management
+- Data encryption
+- Compliance validation
+- Security scanning
+- Audit trail setup
+
+### ui-designer
+**Specialization**: User experience, design patterns, accessibility
+**When spawned**: Complex UI requirements
+**Key capabilities**:
+- Design system implementation
+- Accessibility (WCAG) compliance
+- Responsive layouts
+- User journey mapping
+- Style guide creation
+
+## 🎯 How Agents are Selected
+
+The Queen Agent analyzes your objective and automatically selects the optimal team:
+
+### Example 1: "create incident dashboard"
+- **Primary**: widget-creator
+- **Supporting**: ui-designer, tester
+- **Reasoning**: Widget development with UI focus
+
+### Example 2: "build approval workflow"
+- **Primary**: flow-builder
+- **Supporting**: security, tester
+- **Reasoning**: Process automation with security needs
+
+### Example 3: "create ITSM application"
+- **Primary**: app-architect
+- **Supporting**: flow-builder, widget-creator, security, tester
+- **Reasoning**: Full application requiring all capabilities
+
+## 💡 Agent Coordination Patterns
+
+### Sequential Coordination
+Used when tasks have dependencies:
+\`\`\`
+app-architect → widget-creator → flow-builder → tester
+\`\`\`
+
+### Parallel Coordination
+Used when tasks are independent:
+\`\`\`
+widget-creator ⟷ flow-builder ⟷ script-writer
+         ↓            ↓              ↓
+                  tester
+\`\`\`
+
+### Hybrid Coordination
+Used for complex projects:
+\`\`\`
+Phase 1: app-architect (solo)
+Phase 2: widget-creator + flow-builder (parallel)
+Phase 3: security + tester (parallel)
+Phase 4: Final integration (sequential)
+\`\`\`
+
+## 🔧 Manual Agent Control
+
+While the Queen Agent handles selection automatically, you can influence agent selection:
+
+### Request Specific Expertise
+\`\`\`bash
+snow-flow swarm "create widget with heavy security focus"
+# Queen will prioritize security agent
+\`\`\`
+
+### Exclude Certain Agents
+\`\`\`bash
+snow-flow swarm "simple widget" --max-agents 2
+# Queen will use only essential agents
+\`\`\`
+
+### Force Comprehensive Team
+\`\`\`bash
+snow-flow swarm "production-ready incident system" --max-agents 8
+# Queen will assemble full team with all specialists
+\`\`\`
+`;
+    await fs_1.promises.writeFile((0, path_1.join)(targetDir, '.claude/commands/agent-types.md'), agentTypesContent);
+    // Create mcp-tools-quick-ref.md
+    const mcpToolsContent = `# MCP Tools Quick Reference
+
+## 🔐 Authentication & Connection
+
+### snow_validate_live_connection
+\`\`\`javascript
+snow_validate_live_connection({
+  test_level: "permissions" // basic, full, permissions
+})
+\`\`\`
+**Use for**: Checking ServiceNow connection and OAuth status
+
+### snow_auth_diagnostics
+\`\`\`javascript
+snow_auth_diagnostics({
+  include_recommendations: true,
+  run_write_test: true
+})
+\`\`\`
+**Use for**: Debugging authentication issues
+
+## 🔍 Discovery & Search
+
+### snow_find_artifact
+\`\`\`javascript
+snow_find_artifact({
+  query: "incident dashboard widget",
+  type: "widget" // widget, flow, script, application, any
+})
+\`\`\`
+**Use for**: Finding existing ServiceNow artifacts with natural language
+
+### snow_catalog_item_search
+\`\`\`javascript
+snow_catalog_item_search({
+  query: "laptop",
+  fuzzy_match: true,
+  include_variables: true
+})
+\`\`\`
+**Use for**: Finding catalog items with intelligent matching
+
+### snow_get_by_sysid
+\`\`\`javascript
+snow_get_by_sysid({
+  sys_id: "abc123...",
+  table: "sp_widget"
+})
+\`\`\`
+**Use for**: Direct lookup when you have the sys_id
+
+## 🚀 Deployment Tools
+
+### snow_deploy (Universal - v1.1.73+)
+\`\`\`javascript
+snow_deploy({
+  type: "widget", // widget, flow, application, script, batch
+  config: {
+    name: "incident_dashboard",
+    title: "Incident Dashboard",
+    template: htmlContent,
+    css: cssContent,
+    client_script: clientJS,
+    server_script: serverJS
+  },
+  auto_update_set: true
+})
+\`\`\`
+**Use for**: All deployments - replaces individual deploy tools
+
+## 🔄 Flow Development
+
+### snow_create_flow
+\`\`\`javascript
+snow_create_flow({
+  instruction: "create approval flow for purchases over $1000",
+  deploy_immediately: true,
+  enable_intelligent_analysis: true
+})
+\`\`\`
+**Use for**: Creating flows from natural language
+
+### snow_test_flow_with_mock
+\`\`\`javascript
+snow_test_flow_with_mock({
+  flow_id: "equipment_approval",
+  create_test_user: true,
+  mock_catalog_items: true,
+  simulate_approvals: true,
+  cleanup_after_test: true
+})
+\`\`\`
+**Use for**: Testing flows without affecting real data
+
+### snow_link_catalog_to_flow
+\`\`\`javascript
+snow_link_catalog_to_flow({
+  catalog_item_id: "New Laptop",
+  flow_id: "laptop_provisioning",
+  variable_mapping: [{
+    catalog_variable: "model",
+    flow_input: "equipment_type"
+  }]
+})
+\`\`\`
+**Use for**: Connecting catalog items to flows
+
+## 📦 Update Set Management
+
+### snow_update_set_create
+\`\`\`javascript
+snow_update_set_create({
+  name: "Widget Development - Jan 2024",
+  description: "Dashboard widgets for incident management",
+  auto_switch: true
+})
+\`\`\`
+**Use for**: Creating new update sets
+
+### snow_update_set_add_artifact
+\`\`\`javascript
+snow_update_set_add_artifact({
+  type: "widget",
+  sys_id: "abc123...",
+  name: "incident_dashboard"
+})
+\`\`\`
+**Use for**: Tracking artifacts in update sets
+
+### snow_smart_update_set
+\`\`\`javascript
+snow_smart_update_set({
+  detect_context: true,
+  separate_by_task: true,
+  close_previous: true
+})
+\`\`\`
+**Use for**: Automatic update set management
+
+## 🧪 Testing Tools
+
+### snow_widget_test
+\`\`\`javascript
+snow_widget_test({
+  sys_id: "widget_sys_id",
+  test_scenarios: [{
+    name: "No data test",
+    input: { incidents: [] },
+    expected: { message: "No incidents found" }
+  }],
+  validate_dependencies: true
+})
+\`\`\`
+**Use for**: Widget functionality testing
+
+### snow_comprehensive_flow_test
+\`\`\`javascript
+snow_comprehensive_flow_test({
+  flow_sys_id: "flow_id",
+  test_data_generation: "automatic",
+  edge_case_detection: true,
+  performance_validation: true
+})
+\`\`\`
+**Use for**: Comprehensive flow testing
+
+## 🔄 Batch Operations
+
+### Parallel Tool Execution
+\`\`\`javascript
+// Execute multiple operations in one message
+Promise.all([
+  snow_find_artifact({ query: "widget" }),
+  snow_catalog_item_search({ query: "laptop" }),
+  snow_update_set_current()
+])
+\`\`\`
+**Use for**: Maximum performance with concurrent operations
+
+## 💡 Common Patterns
+
+### Pre-flight Check Pattern
+\`\`\`javascript
+// Always start with authentication
+const auth = await snow_validate_live_connection();
+if (!auth.success) {
+  // Switch to planning mode
+  return "Run: snow-flow auth login";
+}
+
+// Then discover existing artifacts
+const existing = await snow_find_artifact({
+  query: "similar to what I want to create"
+});
+
+// Finally deploy new artifact
+const result = await snow_deploy({
+  type: "widget",
+  config: widgetConfig
+});
+\`\`\`
+
+### Error Recovery Pattern
+\`\`\`javascript
+try {
+  await snow_deploy({ type: "flow", config });
+} catch (error) {
+  if (error.includes("permissions")) {
+    // Try global scope
+    await snow_escalate_permissions();
+  } else if (error.includes("validation")) {
+    // Create manual deployment guide
+    await snow_create_manual_guide();
+  }
+}
+\`\`\`
+
+### Update Set Pattern
+\`\`\`javascript
+// Ensure update set exists
+await snow_smart_update_set();
+
+// Deploy artifact
+const artifact = await snow_deploy({ type: "widget", config });
+
+// Track in update set
+await snow_update_set_add_artifact({
+  type: "widget",
+  sys_id: artifact.sys_id,
+  name: artifact.name
+});
+\`\`\`
+`;
+    await fs_1.promises.writeFile((0, path_1.join)(targetDir, '.claude/commands/mcp-tools-quick-ref.md'), mcpToolsContent);
+    // Create examples directory
+    await fs_1.promises.mkdir((0, path_1.join)(targetDir, 'examples'), { recursive: true });
+    // Create memory patterns directory and sample patterns
+    await fs_1.promises.mkdir((0, path_1.join)(targetDir, 'memory/patterns'), { recursive: true });
+    const successfulPatternsContent = {
+        patterns: [
+            {
+                objective: "create incident dashboard widget",
+                agents: ["widget-creator", "ui-designer", "tester"],
+                mcpTools: ["snow_deploy", "snow_widget_test", "snow_preview_widget"],
+                successRate: 0.95,
+                avgDuration: "5-10 minutes",
+                commonIssues: ["Missing Chart.js dependency", "Mobile responsiveness"],
+                bestPractices: ["Always test on mobile", "Use Chart.js from CDN"]
+            },
+            {
+                objective: "create approval workflow",
+                agents: ["flow-builder", "security", "tester"],
+                mcpTools: ["snow_create_flow", "snow_test_flow_with_mock", "snow_link_catalog_to_flow"],
+                successRate: 0.92,
+                avgDuration: "10-15 minutes",
+                commonIssues: ["Complex approval routing", "Email notification setup"],
+                bestPractices: ["Test all approval paths", "Use mock data first"]
+            },
+            {
+                objective: "create ITSM application",
+                agents: ["app-architect", "flow-builder", "widget-creator", "security", "tester"],
+                mcpTools: ["snow_deploy", "snow_create_flow", "snow_update_set_create"],
+                successRate: 0.88,
+                avgDuration: "30-45 minutes",
+                commonIssues: ["Table relationships", "Permission model"],
+                bestPractices: ["Design data model first", "Use Update Sets throughout"]
+            }
+        ],
+        agentCapabilities: {
+            "widget-creator": {
+                strengths: ["HTML/CSS/JS", "Chart.js", "Responsive design"],
+                limitations: ["Complex backend logic", "Database design"]
+            },
+            "flow-builder": {
+                strengths: ["Process automation", "Conditional logic", "Approvals"],
+                limitations: ["UI development", "Complex integrations"]
+            },
+            "app-architect": {
+                strengths: ["System design", "Data modeling", "Architecture"],
+                limitations: ["Detailed implementation", "UI/UX design"]
+            }
+        },
+        mcpToolPatterns: {
+            "authentication_first": {
+                pattern: "Always start with snow_validate_live_connection",
+                reason: "Ensures OAuth is valid before attempting operations"
+            },
+            "discovery_before_creation": {
+                pattern: "Use snow_find_artifact before snow_deploy",
+                reason: "Prevents duplicate artifacts and wasted effort"
+            },
+            "update_set_tracking": {
+                pattern: "Create Update Set, deploy, then track artifacts",
+                reason: "Professional change management like ServiceNow pros"
+            }
+        }
+    };
+    await fs_1.promises.writeFile((0, path_1.join)(targetDir, 'memory/patterns/successful-deployments.json'), JSON.stringify(successfulPatternsContent, null, 2));
+    // Create workflow patterns JSON
+    const workflowPatternsContent = {
+        workflowTemplates: [
+            {
+                name: "Standard Widget Development",
+                steps: [
+                    "snow_validate_live_connection",
+                    "snow_find_artifact (check existing)",
+                    "snow_update_set_create",
+                    "snow_deploy (type: widget)",
+                    "snow_widget_test",
+                    "snow_update_set_add_artifact"
+                ]
+            },
+            {
+                name: "Flow Development with Testing",
+                steps: [
+                    "snow_validate_live_connection",
+                    "snow_discover_existing_flows",
+                    "snow_create_flow",
+                    "snow_test_flow_with_mock",
+                    "snow_link_catalog_to_flow (if needed)",
+                    "snow_comprehensive_flow_test (if authenticated)"
+                ]
+            },
+            {
+                name: "Full Application Deployment",
+                steps: [
+                    "snow_validate_live_connection",
+                    "snow_analyze_requirements",
+                    "snow_update_set_create",
+                    "snow_deploy (multiple artifacts)",
+                    "snow_create_flow (for workflows)",
+                    "snow_deploy (for widgets)",
+                    "snow_update_set_complete"
+                ]
+            }
+        ]
+    };
+    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 specialized agents (widget-creator, 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+)
     let claudeMdContent = '';
     try {
@@ -2924,7 +3886,13 @@ program
         if (options.sparc) {
             console.log('🎯 Creating SPARC environment...');
             await createSparcFiles(targetDir);
-            console.log('✅ SPARC environment created\n');
+            console.log('✅ SPARC environment created');
+            console.log('📋 Added swarm documentation:');
+            console.log('   - swarm-patterns.md: Common swarm command examples');
+            console.log('   - agent-types.md: Agent specializations guide');
+            console.log('   - mcp-tools-quick-ref.md: MCP tools reference');
+            console.log('   - examples/: Ready-to-run example scripts');
+            console.log('   - memory/patterns/: Success patterns and templates\n');
         }
         // Phase 4: Create .env file
         console.log('🔐 Creating environment configuration...');
@@ -3399,6 +4367,12 @@ echo "💡 Check MCP servers with: /mcp in Claude Code"
         console.log('   2. Run: snow-flow auth login');
         console.log('   3. Start your first swarm: snow-flow swarm "create a widget for incident management"');
         console.log('');
+        console.log('📚 Documentation created:');
+        console.log('   - QUICK_START.md: 5-minute getting started guide');
+        console.log('   - CLAUDE.md: Complete development guide with MCP-FIRST workflow');
+        console.log('   - .claude/commands/: Swarm patterns, agent types, MCP tools reference');
+        console.log('   - examples/: Ready-to-run example scripts for common tasks');
+        console.log('');
         console.log('✅ Project is ready to use!');
         console.log('');
         console.log('🔧 MCP Servers:');