snow-flow 1.1.78 → 1.1.80

package/CLAUDE.md

@@ -112,6 +112,239 @@ snow-flow queen-memory export my-patterns.json
 - CHECK current update set before starting work
 - COMPLETE update sets before moving between environments
 
+## 🔒 MANDATORY ServiceNow Development Workflow (v1.1.79+)
+
+### 🚨 CRITICAL: All ServiceNow Operations MUST Follow This Workflow
+
+**Every single ServiceNow operation must start with authentication validation!** The MCP servers now automatically enforce this workflow.
+
+#### **STEP 1: MANDATORY Authentication Validation**
+
+```javascript
+// This happens automatically in ALL MCP tools
+const connectionResult = await validateServiceNowConnection();
+if (!connectionResult.success) {
+  return createAuthenticationError(connectionResult.error);
+}
+```
+
+**What This Checks:**
+1. ✅ **Credentials Exist**: .env file has OAuth settings
+2. ✅ **OAuth Session Active**: Valid access token exists  
+3. ✅ **Token Valid**: Not expired, auto-refresh if needed
+4. ✅ **Live Connection**: Actual ServiceNow instance responds
+
+**If Authentication Fails, You Get:**
+```
+❌ ServiceNow Connection Failed
+
+OAuth authentication required. Run "snow-flow auth login" to authenticate.
+
+🔧 To fix this:
+
+1. Ensure .env file has OAuth credentials:
+   SNOW_INSTANCE=your-instance.service-now.com
+   SNOW_CLIENT_ID=your_oauth_client_id
+   SNOW_CLIENT_SECRET=your_oauth_client_secret
+
+2. Authenticate with ServiceNow:
+   snow-flow auth login
+
+3. If you still get errors, run diagnostics:
+   snow_auth_diagnostics()
+```
+
+#### **STEP 2: Smart Artifact Discovery (DRY Principle)**
+
+```javascript
+// Automatic discovery before creating anything new
+const discovery = await discoverExistingArtifacts(
+  type,           // 'widget', 'flow', 'script', etc.
+  artifactName,   // Extracted from instruction/config
+  searchTerms     // Related keywords for comprehensive search
+);
+
+if (discovery.found) {
+  console.log(`🔍 Found ${discovery.artifacts.length} existing artifacts`);
+  console.log(`💡 Suggestions: ${discovery.suggestions.join(', ')}`);
+}
+```
+
+**Discovery Results Include:**
+- 📋 **Existing Artifacts**: Similar names and functionality
+- 💡 **Reuse Suggestions**: "Consider reusing: Widget A, Widget B"  
+- 🔍 **Related Items**: Found by description and keywords
+- ⚠️ **Duplication Warnings**: Prevents creating identical artifacts
+
+#### **STEP 3: Automatic Update Set Management**
+
+```javascript
+// Automatic Update Set creation and tracking
+const updateSetId = await ensureUpdateSet(context, purpose);
+
+// After every deployment
+await trackArtifact(sysId, type, name, updateSetId);
+```
+
+**Update Set Features:**
+- 📦 **Auto-Creation**: Creates Update Set if none exists
+- 🏷️ **Smart Naming**: `Snow-Flow Widget Deployment - 2024-01-15`
+- 📋 **Auto-Tracking**: Every artifact automatically tracked
+- 🔄 **Session Management**: Links to Agent session for coordination
+
+### 🛡️ Error Recovery Patterns with Specific Next Steps
+
+#### **Authentication Errors (403, 401)**
+
+```javascript
+// OLD: Generic error
+❌ "Authentication failed"
+
+// NEW: Specific recovery steps
+❌ ServiceNow Connection Failed
+
+OAuth token expired and refresh failed. Run "snow-flow auth login" to re-authenticate.
+
+🔧 To fix this:
+1. Check .env credentials are correct
+2. Run: snow-flow auth login  
+3. If issues persist: snow_auth_diagnostics()
+```
+
+#### **Deployment Errors with Fallback Strategies**
+
+```javascript
+// Automatic fallback strategies
+if (deployment.failed) {
+  // Strategy 1: Try global scope
+  if (error.includes('insufficient privileges')) {
+    await escalateToGlobalScope();
+  }
+  
+  // Strategy 2: Manual steps guide  
+  if (fallback_strategy === 'manual_steps') {
+    return createManualStepsGuide(artifact, error);
+  }
+  
+  // Strategy 3: Update Set only
+  if (fallback_strategy === 'update_set_only') {
+    await createUpdateSetWithInstructions(artifact);
+  }
+}
+```
+
+#### **Discovery Conflicts with Resolution Options**
+
+```javascript
+// When existing artifacts found
+if (discovery.found) {
+  return {
+    options: [
+      "1. Reuse existing: incident_dashboard_v2 (recommended)",
+      "2. Extend existing with new features", 
+      "3. Create new with different name: incident_dashboard_v3",
+      "4. Override existing (not recommended)"
+    ],
+    recommendations: [
+      "✅ Reusing saves development time",
+      "⚠️ Check if existing meets requirements first",
+      "💡 Consider extending instead of duplicating"
+    ]
+  };
+}
+```
+
+### 🔧 Enhanced OAuth Implementation (v1.1.79+)
+
+#### **Environment Variable Fallback**
+
+The OAuth system now properly supports .env fallback:
+
+```javascript
+// 1. Try OAuth tokens from ~/.snow-flow/auth.json
+// 2. Fallback to .env credentials if no tokens
+// 3. Provide specific error messages for each failure
+
+async loadCredentials(): Promise<ServiceNowCredentials | null> {
+  // Try saved OAuth tokens first
+  const tokens = await this.loadTokens();
+  if (tokens?.accessToken) {
+    return tokens;  // ✅ Valid session found
+  }
+  
+  // 🔧 NEW: Fallback to .env file
+  const envCredentials = this.loadFromEnv();
+  if (envCredentials) {
+    // Return credentials without accessToken - signals OAuth login needed
+    return envCredentials;
+  }
+  
+  // ❌ No credentials found anywhere
+  return null;
+}
+```
+
+#### **Automatic Token Refresh**
+
+```javascript
+// Smart token management
+if (token.expired) {
+  console.log('🔄 Token expired, attempting refresh...');
+  
+  const refreshResult = await oauth.refreshAccessToken();
+  if (refreshResult.success) {
+    console.log('✅ Token refreshed successfully');
+  } else {
+    return authenticationError('Token refresh failed - login required');
+  }
+}
+```
+
+### 📋 MANDATORY Pre-Flight Checklist
+
+Before ANY ServiceNow development, ensure:
+
+#### **Environment Setup**
+- [ ] ✅ `.env` file has SNOW_INSTANCE, SNOW_CLIENT_ID, SNOW_CLIENT_SECRET
+- [ ] ✅ `snow-flow auth login` completed successfully  
+- [ ] ✅ `snow_validate_live_connection()` returns success
+
+#### **Development Workflow**
+- [ ] ✅ Start with discovery: `snow_find_artifact()` or `snow_comprehensive_search()`
+- [ ] ✅ Check for reusable components before creating new
+- [ ] ✅ Ensure active Update Set before deployment
+- [ ] ✅ Test with mock data first: `snow_test_flow_with_mock()`
+
+#### **Deployment Verification** 
+- [ ] ✅ All artifacts tracked in Update Set
+- [ ] ✅ Authentication validated before each operation
+- [ ] ✅ Error recovery plan in place
+- [ ] ✅ Rollback strategy documented
+
+### 🚨 Queen Agent Must Develop IN ServiceNow First
+
+**CRITICAL RULE**: The Queen Agent and all specialists must always develop directly in the live ServiceNow instance using the MCP tools, never create local documentation or placeholder code.
+
+```bash
+# ✅ CORRECT: Live development
+snow-flow queen "create incident widget"
+# → Queen uses snow_deploy() with real ServiceNow instance
+# → Creates actual widget in ServiceNow
+# → Tracks in Update Set
+# → Returns sys_id and live URL
+
+# ❌ INCORRECT: Local/mock development  
+# → Creates local HTML/CSS files
+# → Uses placeholder data
+# → No ServiceNow integration
+```
+
+**Why This Matters:**
+- 🎯 **Real Validation**: Only live environment shows real constraints
+- 🔗 **Actual Integration**: Real data connections and dependencies
+- 📋 **Proper Tracking**: Update Sets only work with live changes
+- 🚀 **Immediate Value**: User can see and test results instantly
+
 ## 🎯 Simplified Deployment API (v1.1.73+)
 
 ### One Tool for All Deployments

package/dist/cli.js

@@ -479,7 +479,14 @@ Task("${taskAnalysis.primaryAgent}", \`
   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
-  ${isAuthenticated ? '6. Use ServiceNow MCP tools for deployment' : '6. Create artifacts in servicenow/ directory'}
+  
+  🔐 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!
 \`);
 \`\`\`
 
@@ -502,6 +509,11 @@ Task("${agent}", \`
   4. Enhance/support with your ${agent} expertise
   5. Store outputs in Memory with prefix: "agent_${agent}_"
   6. Update relevant TodoWrite items
+  
+  🔐 AUTHENTICATION REQUIREMENTS:
+  - ALWAYS use MCP tools first - inherit auth status from primary agent
+  - If auth fails, contribute to the PLANNING documentation
+  - Store all plans in Memory for future deployment
 \`);
 \`\`\``).join('\n')}
 
@@ -545,7 +557,9 @@ ${hasIntelligentFeatures ? `✅ **INTELLIGENT MODE ACTIVE** - The following feat
 
 ## 🎯 ServiceNow Execution Strategy
 
-${isAuthenticated ? `### ✅ Live ServiceNow Integration Active
+### 🚀 MANDATORY: Live ServiceNow Development First!
+
+**CRITICAL RULE**: All agents MUST attempt to use ServiceNow MCP tools first, regardless of authentication status.
 
 ${hasIntelligentFeatures ? `#### 🧠 Intelligent Orchestration Available
 Use the unified orchestration tool for complete automation:
@@ -565,9 +579,17 @@ snow_orchestrate_development({
 \`\`\`
 ` : ''}
 
-#### ServiceNow MCP Tools Available
-Your agents have access to comprehensive MCP tools:
+#### ServiceNow MCP Tools (ALWAYS TRY THESE FIRST!)
+${isAuthenticated ? '✅ Authentication detected - full deployment capabilities' : '⚠️ No authentication detected - MCP tools will provide specific instructions if auth needed'}
+
+Your agents MUST use these MCP tools IN THIS ORDER:
 
+🔍 **PRE-FLIGHT CHECKS** (Always do first!):
+1. \`snow_find_artifact\` with a simple query to test authentication
+2. If auth fails, the tool provides specific instructions
+3. Continue with appropriate strategy based on auth status
+
+📦 **CORE DEVELOPMENT TOOLS**:
 1. **Deployment Tools** (servicenow-deployment-mcp)
    - \`snow_deploy\` - Unified deployment for all artifact types
    - \`snow_preview_widget\` - Preview widgets before deployment
@@ -588,6 +610,12 @@ Your agents have access to comprehensive MCP tools:
    - \`snow_update_set_add_artifact\` - Track artifacts
    - \`snow_update_set_complete\` - Complete update sets
 
+🚨 **ERROR RECOVERY PATTERNS**:
+- Auth Error → Document complete solution → Store in Memory → Guide user
+- Permission Error → Try global scope → Document if fails
+- Not Found → Create new → Track in Update Set
+- Any Error → Provide SPECIFIC next steps, not generic messages
+
 ${options.autoDeploy ? `
 #### ⚠️ AUTO-DEPLOYMENT ACTIVE ⚠️
 - Real artifacts will be created in ServiceNow
@@ -598,17 +626,18 @@ ${options.autoDeploy ? `
 - No real artifacts will be created
 - Analysis and recommendations only
 - Use --auto-deploy to enable deployment
-`}` : `### ❌ ServiceNow Integration Disabled
+`}
+${!isAuthenticated ? `### ❌ ServiceNow Integration Disabled
 
-#### File-Based Development Mode
-Agents will create artifacts as files in these directories:
-- \`servicenow/widgets/\` - Widget definitions
-- \`servicenow/flows/\` - Flow configurations
-- \`servicenow/scripts/\` - Script files
-- \`servicenow/apps/\` - Application definitions
+#### Planning Mode (Auth Required)
+When authentication is not available, agents will:
+1. Document the COMPLETE solution architecture
+2. Create detailed implementation guides
+3. Store all plans in Memory for future deployment
+4. Provide SPECIFIC instructions: "Run snow-flow auth login"
 
-Run \`snow-flow auth login\` to enable live ServiceNow integration.
-`}
+⚠️ IMPORTANT: This is a FALLBACK mode only!
+Agents must ALWAYS try MCP tools first!` : ''}
 
 ## 👑 Queen Agent Coordination Instructions
 
@@ -730,6 +759,81 @@ Your Queen Agent orchestration is successful when:
 5. **Validate outputs** before marking complete
 6. **Store all decisions** in Memory for audit trail
 
+## 📋 Agent-Specific Authentication & Discovery Workflows
+
+### 🛠️ Widget Creator Agent
+\`\`\`javascript
+// Pre-flight check
+const authCheck = await snow_find_artifact({ query: "test auth", type: "widget" });
+if (authCheck.error?.includes("OAuth")) {
+  // Switch to planning mode
+  Memory.store("widget_plan", {
+    html_template: "<!-- Complete HTML structure -->",
+    server_script: "// Complete server logic",
+    client_script: "// Complete client controller",
+    css_styles: "/* Complete styles */",
+    deployment_instructions: "Run snow-flow auth login, then use snow_deploy"
+  });
+  TodoWrite([{ content: "Widget plan ready - auth required for deployment", status: "completed" }]);
+} else {
+  // Continue with live development
+  const existing = await snow_comprehensive_search({ query: "similar widget" });
+  // ... proceed with snow_deploy
+}
+\`\`\`
+
+### 🔄 Flow Builder Agent
+\`\`\`javascript
+// Check existing flows first
+const flows = await snow_discover_existing_flows({ flow_purpose: "objective" });
+if (flows.error?.includes("OAuth")) {
+  // Document flow architecture
+  Memory.store("flow_plan", {
+    trigger: "When record created on [table]",
+    steps: ["Step 1: Validate data", "Step 2: Process", "Step 3: Notify"],
+    natural_language: "Complete flow instruction for snow_create_flow",
+    deployment_command: "snow_create_flow with instruction from Memory"
+  });
+} else {
+  // Create flow directly
+  await snow_create_flow({ instruction: "natural language description" });
+}
+\`\`\`
+
+### 📝 Script Writer Agent
+\`\`\`javascript
+// Verify permissions
+const permCheck = await snow_get_by_sysid({ 
+  sys_id: "test", 
+  table: "sys_script_include" 
+});
+if (permCheck.error?.includes("OAuth")) {
+  // Complete script documentation
+  Memory.store("script_solution", {
+    script_type: "Business Rule/Script Include/etc",
+    code: "// Complete implementation",
+    when: "before/after/async",
+    table: "target_table",
+    deployment_ready: true
+  });
+}
+\`\`\`
+
+### 🧪 Tester Agent
+\`\`\`javascript
+// Tester can start with mock (always works)
+const mockTest = await snow_test_flow_with_mock({
+  flow_id: "flow_name",
+  test_inputs: { /* test data */ }
+});
+// Then try comprehensive if authenticated
+const liveTest = await snow_comprehensive_flow_test({ flow_sys_id: "id" });
+if (liveTest.error) {
+  // Document test results from mock only
+  Memory.store("test_results", mockTest);
+}
+\`\`\`
+
 ## 🚀 Begin Orchestration
 
 Now execute this Queen Agent orchestration plan: