musubi-sdd 3.5.1 → 3.6.0

package/README.md

@@ -71,7 +71,15 @@ musubi init --windsurf  # Windsurf IDE
 
 ---
 
-## 📊 What's New in v2.1.0
+## 📊 What's New in v3.6.0
+
+- 🧠 **Dynamic Replanning Engine** - AI agents can now dynamically adjust plans when tasks fail
+- 🔌 **LLM Provider Abstraction** - Multi-provider support (Copilot, Anthropic, OpenAI)
+- 📡 **Real-time Plan Monitoring** - Detect failures, timeouts, and quality degradation
+- 🔄 **Alternative Path Generation** - LLM-powered alternative strategies with confidence scoring
+- 📝 **Replan History & Audit** - Full audit trail with JSONL persistence and export
+
+### Previous (v3.5.1)
 
 - 🔄 **Workflow Engine** - New `musubi-workflow` CLI for stage management and metrics
 - 📊 **Metrics Collection** - Track time per stage, iteration counts, feedback loops
@@ -80,7 +88,12 @@ musubi init --windsurf  # Windsurf IDE
 - 🔄 **Retrospective Stage** - Stage 9 for continuous improvement
 - ✅ **Stage Validation Guide** - Checklists for stage transition validation
 
-### Previous (v2.0.0)
+### Previous (v3.5.1)
+
+- 🔧 **CLI Integration** - Added CLI command references to all 8 Claude Code skills
+- 📚 **Platform Documentation** - CLI Commands section added to all 6 non-Claude platforms
+
+### v2.1.0
 
 - 🔌 **CodeGraphMCPServer Integration** - 14 MCP tools for enhanced code analysis
 - 🧠 **GraphRAG-Powered Search** - Semantic code understanding with Louvain community detection
@@ -89,7 +102,8 @@ musubi init --windsurf  # Windsurf IDE
 ## Features
 
 - 🤖 **Multi-Agent Support** - Works with 7 AI coding agents (Claude Code, GitHub Copilot, Cursor, Gemini CLI, Codex CLI, Qwen Code, Windsurf)
-- 🔌 **MCP Server Integration** - CodeGraphMCPServer for advanced code analysis (NEW in v2.0.0)
+- 🧠 **Dynamic Replanning** - AI agents dynamically adjust plans on failure with LLM-powered alternatives (NEW in v3.6.0)
+- 🔌 **MCP Server Integration** - CodeGraphMCPServer for advanced code analysis (v2.0.0)
 - 📄 **Flexible Command Formats** - Supports Markdown, TOML, and AGENTS.md formats
 - 🎯 **25 Specialized Agents (All Platforms)** - Orchestrator, Steering, Requirements, Architecture, Development, Quality, Security, Infrastructure
   - Claude Code: Skills API (25 skills)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musubi-sdd",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "description": "Ultimate Specification Driven Development Tool with 27 Agents for 7 AI Coding Platforms + MCP Integration (Claude Code, GitHub Copilot, Cursor, Gemini CLI, Windsurf, Codex, Qwen Code)",
   "main": "src/index.js",
   "bin": {

package/src/llm-providers/anthropic-provider.js

@@ -0,0 +1,175 @@
+/**
+ * @fileoverview Anthropic Claude API Provider for MUSUBI Replanning Engine
+ * @module llm-providers/anthropic-provider
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { LLMProvider } = require('./base-provider');
+
+/**
+ * Anthropic Claude API Provider
+ * Used when running outside VS Code or when Claude is preferred
+ */
+class AnthropicLMProvider extends LLMProvider {
+  /**
+   * Create an Anthropic provider
+   * @param {Object} config - Provider configuration
+   * @param {string} [config.apiKey] - Anthropic API key
+   * @param {string} [config.model='claude-sonnet-4-20250514'] - Model to use
+   */
+  constructor(config = {}) {
+    super(config);
+    this.name = 'anthropic';
+    this.apiKey = config.apiKey || process.env.ANTHROPIC_API_KEY;
+    this.config.model = config.model || 'claude-sonnet-4-20250514';
+    this.endpoint = config.endpoint || 'https://api.anthropic.com/v1/messages';
+    this.rateLimiter = this.createRateLimiter(60); // 60 RPM
+  }
+
+  /**
+   * Initialize the Anthropic provider
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    if (!this.apiKey) {
+      throw new Error('Anthropic API key not found. Set ANTHROPIC_API_KEY environment variable.');
+    }
+    this.isInitialized = true;
+  }
+
+  /**
+   * Complete a prompt using Anthropic Claude API
+   * @param {string} prompt - The prompt to complete
+   * @param {Object} [options={}] - Completion options
+   * @returns {Promise<LLMCompletionResult>} Completion result
+   */
+  async complete(prompt, options = {}) {
+    if (!this.isInitialized) {
+      await this.initialize();
+    }
+
+    const systemPrompt = options.systemPrompt || this.getDefaultSystemPrompt();
+
+    return this.rateLimiter(async () => {
+      return this.retryWithBackoff(async () => {
+        const response = await fetch(this.endpoint, {
+          method: 'POST',
+          headers: {
+            'x-api-key': this.apiKey,
+            'anthropic-version': '2023-06-01',
+            'content-type': 'application/json'
+          },
+          body: JSON.stringify({
+            model: this.config.model,
+            max_tokens: options.maxTokens || this.config.maxTokens,
+            system: systemPrompt,
+            messages: [
+              { role: 'user', content: prompt }
+            ]
+          }),
+          signal: AbortSignal.timeout(this.config.timeout)
+        });
+
+        if (!response.ok) {
+          const error = await response.text();
+          throw new Error(`Anthropic API error: ${response.status} - ${error}`);
+        }
+
+        const data = await response.json();
+
+        return {
+          content: data.content[0].text,
+          model: data.model,
+          usage: {
+            promptTokens: data.usage?.input_tokens || 0,
+            completionTokens: data.usage?.output_tokens || 0,
+            totalTokens: (data.usage?.input_tokens || 0) + (data.usage?.output_tokens || 0)
+          },
+          finishReason: data.stop_reason
+        };
+      });
+    });
+  }
+
+  /**
+   * Generate embeddings (not natively supported by Anthropic)
+   * @param {string} text - Text to embed
+   * @returns {Promise<number[]>}
+   */
+  async embed(text) {
+    throw new Error('Embedding not supported by Anthropic Claude API. Use OpenAI or a dedicated embedding service.');
+  }
+
+  /**
+   * Check if the provider is available
+   * @returns {Promise<boolean>}
+   */
+  async isAvailable() {
+    if (!this.apiKey) {
+      return false;
+    }
+
+    try {
+      // Simple validation - check if API key format is valid
+      // Anthropic API keys start with 'sk-ant-'
+      return this.apiKey.startsWith('sk-ant-') || this.apiKey.length > 20;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  /**
+   * Get provider information
+   * @returns {ProviderInfo}
+   */
+  getInfo() {
+    return {
+      name: this.name,
+      model: this.config.model,
+      isInitialized: this.isInitialized,
+      capabilities: {
+        completion: true,
+        embedding: false,
+        streaming: true,
+        functionCalling: true
+      }
+    };
+  }
+
+  /**
+   * Get default system prompt for replanning
+   * @returns {string}
+   * @private
+   */
+  getDefaultSystemPrompt() {
+    return `You are an AI assistant helping with task replanning in a software development workflow.
+Your role is to analyze failed tasks, understand the goal, and generate alternative approaches.
+
+Guidelines:
+1. Be concise and specific in your recommendations
+2. Prioritize practical, actionable alternatives
+3. Consider resource constraints and dependencies
+4. Provide confidence scores for each alternative (0.0 to 1.0)
+5. Explain the reasoning behind each suggestion
+
+When generating alternatives, output valid JSON with this structure:
+{
+  "analysis": "Brief analysis of the failure",
+  "goal": "Extracted goal from the task",
+  "alternatives": [
+    {
+      "id": "alt-1",
+      "description": "Alternative approach",
+      "task": { "name": "task-name", "skill": "skill-name", "parameters": {} },
+      "confidence": 0.8,
+      "reasoning": "Why this might work",
+      "risks": ["potential risk"]
+    }
+  ]
+}`;
+  }
+}
+
+module.exports = { AnthropicLMProvider };

package/src/llm-providers/base-provider.js

@@ -0,0 +1,221 @@
+/**
+ * @fileoverview Base LLM Provider class for MUSUBI Replanning Engine
+ * @module llm-providers/base-provider
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * Abstract base class for LLM providers
+ * Provides a unified interface for different LLM APIs
+ */
+class LLMProvider {
+  /**
+   * Create an LLM provider instance
+   * @param {Object} config - Provider configuration
+   * @param {string} [config.model] - Model identifier
+   * @param {number} [config.maxTokens=1024] - Maximum tokens for completion
+   * @param {number} [config.temperature=0.7] - Sampling temperature
+   * @param {number} [config.timeout=30000] - Request timeout in milliseconds
+   */
+  constructor(config = {}) {
+    this.config = {
+      maxTokens: 1024,
+      temperature: 0.7,
+      timeout: 30000,
+      ...config
+    };
+    this.name = 'base';
+    this.isInitialized = false;
+  }
+
+  /**
+   * Initialize the provider
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    this.isInitialized = true;
+  }
+
+  /**
+   * Complete a prompt with the LLM
+   * @param {string} prompt - The prompt to complete
+   * @param {Object} [options={}] - Completion options
+   * @param {number} [options.maxTokens] - Override max tokens
+   * @param {number} [options.temperature] - Override temperature
+   * @param {string} [options.systemPrompt] - System prompt
+   * @returns {Promise<LLMCompletionResult>} Completion result
+   * @abstract
+   */
+  async complete(prompt, options = {}) {
+    throw new Error('LLMProvider.complete() must be implemented by subclass');
+  }
+
+  /**
+   * Complete a structured prompt with JSON output
+   * @param {string} prompt - The prompt
+   * @param {Object} schema - JSON schema for expected output
+   * @param {Object} [options={}] - Completion options
+   * @returns {Promise<Object>} Parsed JSON result
+   */
+  async completeJSON(prompt, schema, options = {}) {
+    const jsonPrompt = `${prompt}
+
+Respond with valid JSON matching this schema:
+${JSON.stringify(schema, null, 2)}
+
+Output only the JSON, no explanation.`;
+
+    const result = await this.complete(jsonPrompt, {
+      ...options,
+      temperature: 0.3 // Lower temperature for structured output
+    });
+
+    try {
+      // Extract JSON from the response
+      const jsonMatch = result.content.match(/\{[\s\S]*\}/);
+      if (!jsonMatch) {
+        throw new Error('No JSON found in response');
+      }
+      return JSON.parse(jsonMatch[0]);
+    } catch (error) {
+      throw new Error(`Failed to parse JSON response: ${error.message}`);
+    }
+  }
+
+  /**
+   * Generate embeddings for text
+   * @param {string} text - Text to embed
+   * @returns {Promise<number[]>} Embedding vector
+   * @abstract
+   */
+  async embed(text) {
+    throw new Error('LLMProvider.embed() must be implemented by subclass');
+  }
+
+  /**
+   * Check if the provider is available and properly configured
+   * @returns {Promise<boolean>} Availability status
+   * @abstract
+   */
+  async isAvailable() {
+    throw new Error('LLMProvider.isAvailable() must be implemented by subclass');
+  }
+
+  /**
+   * Get provider information
+   * @returns {ProviderInfo} Provider information
+   */
+  getInfo() {
+    return {
+      name: this.name,
+      model: this.config.model,
+      isInitialized: this.isInitialized,
+      capabilities: {
+        completion: true,
+        embedding: false,
+        streaming: false,
+        functionCalling: false
+      }
+    };
+  }
+
+  /**
+   * Format messages for chat completion
+   * @param {string} systemPrompt - System prompt
+   * @param {string} userPrompt - User prompt
+   * @returns {Array<Message>} Formatted messages
+   * @protected
+   */
+  formatMessages(systemPrompt, userPrompt) {
+    const messages = [];
+    
+    if (systemPrompt) {
+      messages.push({ role: 'system', content: systemPrompt });
+    }
+    
+    messages.push({ role: 'user', content: userPrompt });
+    
+    return messages;
+  }
+
+  /**
+   * Create a rate limiter for API calls
+   * @param {number} requestsPerMinute - Rate limit
+   * @returns {Function} Rate limited function wrapper
+   * @protected
+   */
+  createRateLimiter(requestsPerMinute) {
+    const minInterval = 60000 / requestsPerMinute;
+    let lastCall = 0;
+
+    return async (fn) => {
+      const now = Date.now();
+      const timeSinceLastCall = now - lastCall;
+      
+      if (timeSinceLastCall < minInterval) {
+        await new Promise(resolve => 
+          setTimeout(resolve, minInterval - timeSinceLastCall)
+        );
+      }
+      
+      lastCall = Date.now();
+      return fn();
+    };
+  }
+
+  /**
+   * Retry a function with exponential backoff
+   * @param {Function} fn - Function to retry
+   * @param {number} [maxRetries=3] - Maximum retry attempts
+   * @param {number} [baseDelay=1000] - Base delay in milliseconds
+   * @returns {Promise<*>} Function result
+   * @protected
+   */
+  async retryWithBackoff(fn, maxRetries = 3, baseDelay = 1000) {
+    let lastError;
+    
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error;
+        
+        if (attempt < maxRetries) {
+          const delay = baseDelay * Math.pow(2, attempt);
+          await new Promise(resolve => setTimeout(resolve, delay));
+        }
+      }
+    }
+    
+    throw lastError;
+  }
+}
+
+/**
+ * @typedef {Object} LLMCompletionResult
+ * @property {string} content - Completion content
+ * @property {string} model - Model used
+ * @property {Object} usage - Token usage
+ * @property {number} usage.promptTokens - Prompt tokens
+ * @property {number} usage.completionTokens - Completion tokens
+ * @property {number} usage.totalTokens - Total tokens
+ * @property {string} [finishReason] - Reason for completion finish
+ */
+
+/**
+ * @typedef {Object} ProviderInfo
+ * @property {string} name - Provider name
+ * @property {string} model - Model identifier
+ * @property {boolean} isInitialized - Initialization status
+ * @property {Object} capabilities - Provider capabilities
+ */
+
+/**
+ * @typedef {Object} Message
+ * @property {string} role - Message role (system, user, assistant)
+ * @property {string} content - Message content
+ */
+
+module.exports = { LLMProvider };

package/src/llm-providers/copilot-provider.js

@@ -0,0 +1,262 @@
+/**
+ * @fileoverview GitHub Copilot LM API Provider for MUSUBI Replanning Engine
+ * @module llm-providers/copilot-provider
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { LLMProvider } = require('./base-provider');
+
+/**
+ * GitHub Copilot Language Model API Provider
+ * Primary provider for MUSUBI when running in VS Code with GitHub Copilot
+ */
+class CopilotLMProvider extends LLMProvider {
+  /**
+   * Create a GitHub Copilot LM provider
+   * @param {Object} config - Provider configuration
+   * @param {Object} [config.vscode] - VS Code API reference
+   * @param {string} [config.model='claude-sonnet-4'] - Model to use
+   */
+  constructor(config = {}) {
+    super(config);
+    this.name = 'github-copilot';
+    this.vscode = config.vscode || null;
+    this.config.model = config.model || 'claude-sonnet-4';
+    this.languageModelAPI = null;
+  }
+
+  /**
+   * Initialize the Copilot provider
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    if (this.vscode) {
+      // When running in VS Code extension context
+      this.languageModelAPI = this.vscode.lm;
+    } else {
+      // Try to get vscode module dynamically (for VS Code extension context)
+      try {
+        // This will only work when running inside VS Code
+        const vscode = require('vscode');
+        this.vscode = vscode;
+        this.languageModelAPI = vscode.lm;
+      } catch (e) {
+        // Not running in VS Code context - use fallback or mock
+        this.languageModelAPI = null;
+      }
+    }
+    
+    this.isInitialized = true;
+  }
+
+  /**
+   * Complete a prompt using GitHub Copilot LM API
+   * @param {string} prompt - The prompt to complete
+   * @param {Object} [options={}] - Completion options
+   * @returns {Promise<LLMCompletionResult>} Completion result
+   */
+  async complete(prompt, options = {}) {
+    if (!this.isInitialized) {
+      await this.initialize();
+    }
+
+    const systemPrompt = options.systemPrompt || this.getDefaultSystemPrompt();
+    const messages = this.formatMessages(systemPrompt, prompt);
+
+    // Use VS Code Language Model API if available
+    if (this.languageModelAPI) {
+      return this.completeWithVSCodeAPI(messages, options);
+    }
+
+    // Fallback: Use REST API if token is available
+    if (process.env.GITHUB_COPILOT_TOKEN) {
+      return this.completeWithRestAPI(messages, options);
+    }
+
+    throw new Error('GitHub Copilot LM API not available. Run inside VS Code with Copilot extension or provide GITHUB_COPILOT_TOKEN.');
+  }
+
+  /**
+   * Complete using VS Code Language Model API
+   * @param {Array<Message>} messages - Chat messages
+   * @param {Object} options - Completion options
+   * @returns {Promise<LLMCompletionResult>}
+   * @private
+   */
+  async completeWithVSCodeAPI(messages, options) {
+    const vscode = this.vscode;
+    
+    // Select the appropriate model
+    const models = await vscode.lm.selectChatModels({
+      vendor: 'copilot',
+      family: this.config.model
+    });
+
+    if (models.length === 0) {
+      throw new Error(`No Copilot model found matching: ${this.config.model}`);
+    }
+
+    const model = models[0];
+
+    // Convert messages to VS Code format
+    const chatMessages = messages.map(msg => {
+      if (msg.role === 'system') {
+        return vscode.LanguageModelChatMessage.User(msg.content);
+      } else if (msg.role === 'user') {
+        return vscode.LanguageModelChatMessage.User(msg.content);
+      } else {
+        return vscode.LanguageModelChatMessage.Assistant(msg.content);
+      }
+    });
+
+    // Create request options
+    const requestOptions = {
+      justification: 'MUSUBI Replanning Engine alternative path generation'
+    };
+
+    // Send request
+    const response = await model.sendRequest(
+      chatMessages,
+      requestOptions,
+      new vscode.CancellationTokenSource().token
+    );
+
+    // Collect response
+    let content = '';
+    for await (const fragment of response.text) {
+      content += fragment;
+    }
+
+    return {
+      content,
+      model: model.id,
+      usage: {
+        promptTokens: 0, // VS Code API doesn't expose token counts
+        completionTokens: 0,
+        totalTokens: 0
+      },
+      finishReason: 'stop'
+    };
+  }
+
+  /**
+   * Complete using REST API (fallback)
+   * @param {Array<Message>} messages - Chat messages
+   * @param {Object} options - Completion options
+   * @returns {Promise<LLMCompletionResult>}
+   * @private
+   */
+  async completeWithRestAPI(messages, options) {
+    const endpoint = process.env.GITHUB_COPILOT_ENDPOINT || 'https://api.githubcopilot.com/chat/completions';
+    const token = process.env.GITHUB_COPILOT_TOKEN;
+
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        'Editor-Version': 'MUSUBI/1.0.0',
+        'Editor-Plugin-Version': 'MUSUBI/1.0.0'
+      },
+      body: JSON.stringify({
+        model: this.config.model,
+        messages,
+        max_tokens: options.maxTokens || this.config.maxTokens,
+        temperature: options.temperature || this.config.temperature
+      }),
+      signal: AbortSignal.timeout(this.config.timeout)
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`GitHub Copilot API error: ${response.status} - ${error}`);
+    }
+
+    const data = await response.json();
+
+    return {
+      content: data.choices[0].message.content,
+      model: data.model,
+      usage: {
+        promptTokens: data.usage?.prompt_tokens || 0,
+        completionTokens: data.usage?.completion_tokens || 0,
+        totalTokens: data.usage?.total_tokens || 0
+      },
+      finishReason: data.choices[0].finish_reason
+    };
+  }
+
+  /**
+   * Generate embeddings (not supported by Copilot LM API)
+   * @param {string} text - Text to embed
+   * @returns {Promise<number[]>}
+   */
+  async embed(text) {
+    throw new Error('Embedding not supported by GitHub Copilot LM API');
+  }
+
+  /**
+   * Check if the provider is available
+   * @returns {Promise<boolean>}
+   */
+  async isAvailable() {
+    try {
+      if (!this.isInitialized) {
+        await this.initialize();
+      }
+
+      // Check VS Code LM API
+      if (this.languageModelAPI) {
+        const models = await this.vscode.lm.selectChatModels({
+          vendor: 'copilot'
+        });
+        return models.length > 0;
+      }
+
+      // Check REST API token
+      return !!process.env.GITHUB_COPILOT_TOKEN;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  /**
+   * Get provider information
+   * @returns {ProviderInfo}
+   */
+  getInfo() {
+    return {
+      name: this.name,
+      model: this.config.model,
+      isInitialized: this.isInitialized,
+      capabilities: {
+        completion: true,
+        embedding: false,
+        streaming: true,
+        functionCalling: false
+      },
+      context: this.languageModelAPI ? 'vscode' : 'rest'
+    };
+  }
+
+  /**
+   * Get default system prompt for replanning
+   * @returns {string}
+   * @private
+   */
+  getDefaultSystemPrompt() {
+    return `You are an AI assistant helping with task replanning in a software development workflow.
+Your role is to analyze failed tasks, understand the goal, and generate alternative approaches.
+
+Guidelines:
+1. Be concise and specific in your recommendations
+2. Prioritize practical, actionable alternatives
+3. Consider resource constraints and dependencies
+4. Provide confidence scores for each alternative
+5. Explain the reasoning behind each suggestion`;
+  }
+}
+
+module.exports = { CopilotLMProvider };