snow-flow 1.4.4 → 1.4.6

package/.mcp.json.template

@@ -9,15 +9,6 @@
         "SNOW_CLIENT_SECRET": "{{SNOW_CLIENT_SECRET}}"
       }
     },
-    "servicenow-flow-composer": {
-      "command": "node",
-      "args": ["{{PROJECT_ROOT}}/dist/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": ["{{PROJECT_ROOT}}/dist/mcp/servicenow-update-set-mcp.js"],

package/CLAUDE.md

@@ -1,186 +1,262 @@
-# Claude Code Configuration - SPARC Development Environment (Batchtools Optimized)
+# Snow-Flow Development with Claude Code
 
-⚠️ **WARNING: FLOW CREATION REMOVED (v1.4.0+)** ⚠️
+## 🚨 CRITICAL: MCP-FIRST WORKFLOW (READ THIS FIRST!)
 
-Flow Designer functionality has been removed due to critical issues.
-Please use ServiceNow's native Flow Designer interface directly.
+**Snow-flow's core value is REAL ServiceNow integration through MCP tools. NEVER work in offline mode!**
 
-Snow-flow now focuses on:
-- Widget development and deployment
-- Update Set management
-- ServiceNow authentication
-- Table/field discovery  
-- Multi-agent coordination
+### ⚠️ MANDATORY WORKFLOW - NO EXCEPTIONS
 
-## 🚨 CRITICAL: CONCURRENT EXECUTION FOR ALL ACTIONS
+**Every ServiceNow task MUST start with this sequence:**
 
-**ABSOLUTE RULE**: ALL operations MUST be concurrent/parallel in a single message:
+```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);
+}
+
+// 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
+});
+```
 
-### 🔴 MANDATORY CONCURRENT PATTERNS:
-1. **TodoWrite**: ALWAYS batch ALL todos in ONE call (5-10+ todos minimum)
-2. **Task tool**: ALWAYS spawn ALL agents in ONE message with full instructions
-3. **File operations**: ALWAYS batch ALL reads/writes/edits in ONE message
-4. **Bash commands**: ALWAYS batch ALL terminal operations in ONE message
-5. **Memory operations**: ALWAYS batch ALL memory store/retrieve in ONE message
+### 🚫 FORBIDDEN ACTIONS
 
-### ⚡ GOLDEN RULE: "1 MESSAGE = ALL RELATED OPERATIONS"
+**THESE ACTIONS ARE BANNED - NEVER DO THESE:**
 
-**Examples of CORRECT concurrent execution:**
-```javascript
-// ✅ CORRECT: Everything in ONE message
-[Single Message]:
-  - TodoWrite { todos: [10+ todos with all statuses/priorities] }
-  - Task("Agent 1 with full instructions and hooks")
-  - Task("Agent 2 with full instructions and hooks")
-  - Task("Agent 3 with full instructions and hooks")
-  - Read("file1.js")
-  - Read("file2.js")
-  - Write("output1.js", content)
-  - Write("output2.js", content)
-  - Bash("npm install")
-  - Bash("npm test")
-  - Bash("npm run build")
-```
+❌ **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
 
-**Examples of WRONG sequential execution:**
-```javascript
-// ❌ WRONG: Multiple messages (NEVER DO THIS)
-Message 1: TodoWrite { todos: [single todo] }
-Message 2: Task("Agent 1")
-Message 3: Task("Agent 2")
-Message 4: Read("file1.js")
-Message 5: Write("output1.js")
-Message 6: Bash("npm install")
-// This is 6x slower and breaks coordination!
-```
+### ✅ CORRECT: MCP-First Decision Tree
 
-### 🎯 CONCURRENT EXECUTION CHECKLIST:
+```
+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! ✅
+```
 
-Before sending ANY message, ask yourself:
-- ✅ Are ALL related TodoWrite operations batched together?
-- ✅ Are ALL Task spawning operations in ONE message?
-- ✅ Are ALL file operations (Read/Write/Edit) batched together?
-- ✅ Are ALL bash commands grouped in ONE message?
-- ✅ Are ALL memory operations concurrent?
+## 🚀 Snow-Flow Swarm Command - MCP-Orchestrated Multi-Agent Intelligence
 
-If ANY answer is "No", you MUST combine operations into a single message!
+**The Swarm system is MCP-native and ALWAYS uses ServiceNow tools first!**
 
-## Project Overview
-This project uses the SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) methodology for systematic Test-Driven Development with AI assistance through Claude-Flow orchestration.
+### 🧠 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
 
-**🚀 Batchtools Optimization Enabled**: This configuration includes optimized prompts and parallel processing capabilities for improved performance and efficiency.
+### Swarm Command Examples
+```bash
+# Simple widget creation
+snow-flow swarm "create incident dashboard widget"
 
-## SPARC Development Commands
+# Complex development
+snow-flow swarm "build employee onboarding portal with approval workflows"
 
-### Core SPARC Commands
-- `npx claude-flow sparc modes`: List all available SPARC development modes
-- `npx claude-flow sparc run <mode> "<task>"`: Execute specific SPARC mode for a task
-- `npx claude-flow sparc tdd "<feature>"`: Run complete TDD workflow using SPARC methodology
-- `npx claude-flow sparc info <mode>`: Get detailed information about a specific mode
+# With specific options
+snow-flow swarm "create service catalog item" --no-auto-deploy --monitor
+```
 
-### Batchtools Commands (Optimized)
-- `npx claude-flow sparc batch <modes> "<task>"`: Execute multiple SPARC modes in parallel
-- `npx claude-flow sparc pipeline "<task>"`: Execute full SPARC pipeline with parallel processing
-- `npx claude-flow sparc concurrent <mode> "<tasks-file>"`: Process multiple tasks concurrently
+## 🛠️ Complete ServiceNow MCP Tools Reference
 
-### Standard Build Commands
-- `npm run build`: Build the project
-- `npm run test`: Run the test suite
-- `npm run lint`: Run linter and format checks
-- `npm run typecheck`: Run TypeScript type checking
+### Discovery & Search Tools
+```javascript
+// Find any ServiceNow artifact using natural language
+snow_find_artifact({
+  query: "the widget that shows incidents on homepage",
+  type: "widget" // or "flow", "script", "application", "any"
+});
+
+// Search catalog items with fuzzy matching
+snow_catalog_item_search({
+  query: "laptop",
+  fuzzy_match: true,        // Finds variations: notebook, MacBook, etc.
+  include_variables: true   // Include catalog variables
+});
+
+// Comprehensive search across all tables
+snow_comprehensive_search({
+  query: "approval",
+  include_inactive: false
+});
+```
 
-## SPARC Methodology Workflow (Batchtools Enhanced)
+### Deployment Tools
+```javascript
+// Universal deployment tool
+snow_deploy({
+  type: "widget",
+  config: {
+    name: "Incident Dashboard",
+    template: "<html>...</html>",
+    css: "/* styles */",
+    server_script: "// server code",
+    client_script: "// client code"
+  },
+  auto_update_set: true
+});
+
+// Bulk deployment
+snow_bulk_deploy({
+  artifacts: [...],
+  transaction_mode: true,
+  rollback_on_error: true
+});
+```
 
-### 1. Specification Phase (Parallel Analysis)
-```bash
-# Create detailed specifications with concurrent requirements analysis
-npx claude-flow sparc run spec-pseudocode "Define user authentication requirements" --parallel
+### Update Set Management
+```javascript
+// Ensure active Update Set
+snow_ensure_active_update_set({
+  context: "Widget development"
+});
+
+// Track artifacts
+snow_update_set_add_artifact({
+  type: "widget",
+  sys_id: "abc123",
+  name: "My Widget"
+});
+
+// Preview changes
+snow_update_set_preview({
+  update_set_id: "current"
+});
 ```
-**Batchtools Optimization**: Simultaneously analyze multiple requirement sources, validate constraints in parallel, and generate comprehensive specifications.
 
-### 2. Pseudocode Phase (Concurrent Logic Design)
-```bash
-# Develop algorithmic logic with parallel pattern analysis
-npx claude-flow sparc run spec-pseudocode "Create authentication flow pseudocode" --batch-optimize
+### Testing Tools
+```javascript
+// 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
+});
+
+// Link catalog to flow
+snow_link_catalog_to_flow({
+  catalog_item_id: "iPhone 6S",
+  flow_id: "mobile_provisioning_flow",
+  test_link: true
+});
 ```
-**Batchtools Optimization**: Process multiple algorithm patterns concurrently, validate logic flows in parallel, and optimize data structures simultaneously.
 
-### 3. Architecture Phase (Parallel Component Design)
-```bash
-# Design system architecture with concurrent component analysis
-npx claude-flow sparc run architect "Design authentication service architecture" --parallel
+## 📋 Essential Patterns
+
+### Authentication Handling
+```javascript
+// 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
+}
 ```
-**Batchtools Optimization**: Generate multiple architectural alternatives simultaneously, validate integration points in parallel, and create comprehensive documentation concurrently.
 
-### 4. Refinement Phase (Parallel TDD Implementation)
-```bash
-# Execute Test-Driven Development with parallel test generation
-npx claude-flow sparc tdd "implement user authentication system" --batch-tdd
+### Error Recovery
+```javascript
+// Implement fallback strategies
+if (deployment.failed) {
+  // Try global scope
+  const globalAttempt = await snow_deploy({ 
+    ...config, 
+    scope_preference: 'global' 
+  });
+  
+  if (globalAttempt.failed) {
+    // Provide manual instructions
+    return createManualStepsGuide(config, error);
+  }
+}
 ```
-**Batchtools Optimization**: Generate multiple test scenarios simultaneously, implement and validate code in parallel, and optimize performance concurrently.
 
-### 5. Completion Phase (Concurrent Integration)
+## 🔧 Configuration
+
+### 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 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
-# Integration with parallel validation and documentation
-npx claude-flow sparc run integration "integrate authentication with user management" --parallel
+# .env file
+SNOW_INSTANCE=dev123456
+SNOW_CLIENT_ID=your_oauth_client_id
+SNOW_CLIENT_SECRET=your_oauth_client_secret
 ```
-**Batchtools Optimization**: Run integration tests in parallel, generate documentation concurrently, and validate requirements simultaneously.
-
-## Batchtools Integration Features
-
-### Parallel Processing Capabilities
-- **Concurrent File Operations**: Read, analyze, and modify multiple files simultaneously
-- **Parallel Code Analysis**: Analyze dependencies, patterns, and architecture concurrently
-- **Batch Test Generation**: Create comprehensive test suites in parallel
-- **Concurrent Documentation**: Generate multiple documentation formats simultaneously
-
-### Performance Optimizations
-- **Smart Batching**: Group related operations for optimal performance
-- **Pipeline Processing**: Chain dependent operations with parallel stages
-- **Resource Management**: Efficient utilization of system resources
-- **Error Resilience**: Robust error handling with parallel recovery
-
-## Performance Benchmarks
-
-### Batchtools Performance Improvements
-- **File Operations**: Up to 300% faster with parallel processing
-- **Code Analysis**: 250% improvement with concurrent pattern recognition
-- **Test Generation**: 400% faster with parallel test creation
-- **Documentation**: 200% improvement with concurrent content generation
-- **Memory Operations**: 180% faster with batched read/write operations
-
-## Code Style and Best Practices (Batchtools Enhanced)
-
-### SPARC Development Principles with Batchtools
-- **Modular Design**: Keep files under 500 lines, optimize with parallel analysis
-- **Environment Safety**: Never hardcode secrets, validate with concurrent checks
-- **Test-First**: Always write tests before implementation using parallel generation
-- **Clean Architecture**: Separate concerns with concurrent validation
-- **Parallel Documentation**: Maintain clear, up-to-date documentation with concurrent updates
-
-### Batchtools Best Practices
-- **Parallel Operations**: Use batchtools for independent tasks
-- **Concurrent Validation**: Validate multiple aspects simultaneously
-- **Batch Processing**: Group similar operations for efficiency
-- **Pipeline Optimization**: Chain operations with parallel stages
-- **Resource Management**: Monitor and optimize resource usage
-
-## Important Notes (Enhanced)
-
-- Always run tests before committing with parallel execution (`npm run test --parallel`)
-- Use SPARC memory system with concurrent operations to maintain context across sessions
-- Follow the Red-Green-Refactor cycle with parallel test generation during TDD phases
-- Document architectural decisions with concurrent validation in memory
-- Regular security reviews with parallel analysis for authentication or data handling code
-- Claude Code slash commands provide quick access to batchtools-optimized SPARC modes
-- Monitor system resources during parallel operations for optimal performance
-
-For more information about SPARC methodology and batchtools optimization, see: 
-- SPARC Guide: https://github.com/ruvnet/claude-code-flow/docs/sparc.md
-- Batchtools Documentation: https://github.com/ruvnet/claude-code-flow/docs/batchtools.md
-
-# important-instruction-reminders
-Do what has been asked; nothing more, nothing less.
-NEVER create files unless they're absolutely necessary for achieving your goal.
-ALWAYS prefer editing an existing file to creating a new one.
-NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+
+## 💡 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  
+
+### 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 MCP servers
+2. Configure ServiceNow credentials in .env file  
+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