@itz4blitz/agentful 1.4.0 → 1.5.0

package/template/bin/hooks/architect-drift-detector.js

@@ -32,10 +32,13 @@ function detectArchitectDrift() {
 
     // Check various drift indicators
     const driftReasons = [];
+    const newLibraries = [];
 
-    // 1. Check if dependency files changed
-    if (dependenciesChanged(arch)) {
-      driftReasons.push('dependencies_changed');
+    // 1. Check if NEW dependencies added (not just version bumps)
+    const depChange = dependenciesChanged(arch);
+    if (depChange.changed) {
+      newLibraries.push(...depChange.newLibraries);
+      driftReasons.push('new_libraries_added');
     }
 
     // 2. Check if tech stack files modified
@@ -53,12 +56,15 @@ function detectArchitectDrift() {
       driftReasons.push('new_patterns_detected');
     }
 
-    // If drift detected, mark for re-analysis
+    // If drift detected, evaluate if it's meaningful
     if (driftReasons.length > 0) {
-      markForReanalysis(arch, driftReasons);
-      console.log(`⚠️  Architect drift detected: ${driftReasons.join(', ')}`);
-      console.log('   Run /agentful-generate to update skills and agents');
-      return true;
+      // Only trigger if the drift is significant
+      if (isMeaningfulDrift(driftReasons, arch, newLibraries)) {
+        markForReanalysis(arch, driftReasons, newLibraries);
+        console.log(`⚠️  Architecture changed: ${formatDriftReasons(driftReasons, newLibraries)}`);
+        console.log('   Run /agentful-generate to update skills and agents');
+        return true;
+      }
     }
 
     return false;
@@ -87,36 +93,110 @@ function loadArchitecture() {
 
 /**
  * Check if dependency files changed
+ * Returns: { changed: boolean, newLibraries: string[] }
  */
 function dependenciesChanged(arch) {
   const depFiles = [
-    'package.json',
-    'package-lock.json',
-    'requirements.txt',
-    'pyproject.toml',
-    'Pipfile',
-    'go.mod',
-    'go.sum',
-    'Gemfile',
-    'Gemfile.lock',
-    'composer.json',
-    'pom.xml',
-    'build.gradle',
-    'Cargo.toml'
+    { file: 'package.json', type: 'json', key: 'dependencies' },
+    { file: 'package.json', type: 'json', key: 'devDependencies' },
+    { file: 'requirements.txt', type: 'txt' },
+    { file: 'pyproject.toml', type: 'toml', key: 'dependencies' },
+    { file: 'Pipfile', type: 'toml', key: 'packages' },
+    { file: 'go.mod', type: 'go' },
+    { file: 'Gemfile', type: 'ruby' },
+    { file: 'composer.json', type: 'json', key: 'require' },
+    { file: 'pom.xml', type: 'xml' },
+    { file: 'build.gradle', type: 'gradle' },
+    { file: 'Cargo.toml', type: 'toml', key: 'dependencies' }
   ];
 
-  for (const file of depFiles) {
-    if (!fs.existsSync(file)) continue;
+  const newLibraries = [];
 
-    const currentHash = hashFile(file);
-    const previousHash = arch.dependency_hashes?.[file];
+  for (const depFile of depFiles) {
+    if (!fs.existsSync(depFile.file)) continue;
+
+    const currentHash = hashFile(depFile.file);
+    const previousHash = arch.dependency_hashes?.[depFile.file];
 
     if (previousHash && currentHash !== previousHash) {
-      return true;
+      // Check if NEW libraries were added (not just version bumps)
+      const added = getNewLibraries(depFile.file, depFile, arch);
+      if (added.length > 0) {
+        newLibraries.push(...added);
+      }
     }
   }
 
-  return false;
+  return {
+    changed: newLibraries.length > 0,
+    newLibraries
+  };
+}
+
+/**
+ * Get list of new libraries added since last analysis
+ */
+function getNewLibraries(filePath, fileInfo, arch) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const previousContent = arch.previous_dependencies?.[filePath] || '';
+
+    if (!previousContent) return []; // First time, can't determine new vs old
+
+    // Parse current and previous dependencies
+    const currentDeps = parseDependencies(content, fileInfo);
+    const previousDeps = parseDependencies(previousContent, fileInfo);
+
+    // Find libraries in current but not in previous
+    const newLibs = Object.keys(currentDeps).filter(lib => !previousDeps[lib]);
+
+    return newLibs;
+  } catch (error) {
+    return [];
+  }
+}
+
+/**
+ * Parse dependencies from various file formats
+ */
+function parseDependencies(content, fileInfo) {
+  const deps = {};
+
+  try {
+    if (fileInfo.file === 'package.json') {
+      const json = JSON.parse(content);
+      const section = json[fileInfo.key] || {};
+      Object.keys(section).forEach(key => {
+        deps[key] = section[key];
+      });
+    } else if (fileInfo.file === 'requirements.txt') {
+      content.split('\n').forEach(line => {
+        line = line.trim();
+        if (line && !line.startsWith('#')) {
+          const name = line.split('==')[0].split('>=')[0].split('<=')[0].trim();
+          if (name) deps[name] = line;
+        }
+      });
+    } else if (fileInfo.file === 'go.mod') {
+      const lines = content.split('\n');
+      let inRequire = false;
+      lines.forEach(line => {
+        if (line.trim().startsWith('require (')) inRequire = true;
+        else if (line.trim() === ')') inRequire = false;
+        else if (inRequire || line.trim().startsWith('require ')) {
+          const parts = line.trim().split(/\s+/);
+          if (parts.length >= 2 && parts[0] !== 'require') {
+            deps[parts[0]] = parts[1];
+          }
+        }
+      });
+    }
+    // Add more formats as needed...
+  } catch (error) {
+    // Silently fail parsing
+  }
+
+  return deps;
 }
 
 /**
@@ -220,14 +300,101 @@ function hashFile(filePath) {
   return crypto.createHash('md5').update(content).digest('hex');
 }
 
+/**
+ * Determine if drift is meaningful enough to trigger re-analysis
+ *
+ * Meaningful changes:
+ * - NEW libraries added (not version bumps)
+ * - Tech stack fundamentally changed (switched frameworks)
+ * - Significant new patterns (20%+ file growth AND 50+ new files)
+ * - Stale analysis (>30 days)
+ *
+ * NOT meaningful:
+ * - Version bumps only
+ * - Small file additions
+ * - Recent analysis (<30 days ago)
+ */
+function isMeaningfulDrift(reasons, arch, newLibraries) {
+  // New libraries are ALWAYS meaningful (might create new skills/agents)
+  if (reasons.includes('new_libraries_added')) {
+    return true;
+  }
+
+  // If analysis is stale (>30 days), any drift is meaningful
+  if (analysisIsStale(arch)) {
+    const daysSinceAnalysis = getDaysSinceAnalysis(arch);
+    if (daysSinceAnalysis > 30) {
+      return true;
+    }
+  }
+
+  // Tech stack changes are always meaningful
+  if (reasons.includes('tech_stack_modified')) {
+    return true;
+  }
+
+  // New patterns are meaningful if significant growth
+  if (reasons.includes('new_patterns_detected')) {
+    const currentFileCount = countSourceFiles();
+    const previousFileCount = arch.file_count || 0;
+    const growthRatio = (currentFileCount - previousFileCount) / Math.max(previousFileCount, 1);
+
+    // Only if >20% growth AND at least 50 new files
+    const newFileCount = currentFileCount - previousFileCount;
+    if (growthRatio > 0.2 && newFileCount > 50) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Get days since last analysis
+ */
+function getDaysSinceAnalysis(arch) {
+  if (!arch.last_analysis) return 999;
+
+  const lastAnalysis = new Date(arch.last_analysis);
+  return (Date.now() - lastAnalysis.getTime()) / (1000 * 60 * 60 * 24);
+}
+
+/**
+ * Format drift reasons for display
+ */
+function formatDriftReasons(reasons, newLibraries) {
+  const labels = {
+    'new_libraries_added': `new libraries: ${newLibraries.slice(0, 3).join(', ')}${newLibraries.length > 3 ? '...' : ''}`,
+    'tech_stack_modified': 'tech stack changed',
+    'analysis_stale': 'analysis outdated',
+    'new_patterns_detected': 'new code patterns detected'
+  };
+
+  return reasons.map(r => labels[r] || r).join(', ');
+}
+
 /**
  * Mark architecture.json for re-analysis
+ * Also stores current dependencies for next comparison
  */
-function markForReanalysis(arch, reasons) {
+function markForReanalysis(arch, reasons, newLibraries) {
   arch.needs_reanalysis = true;
   arch.drift_reasons = reasons;
+  arch.new_libraries = newLibraries;
   arch.drift_detected_at = new Date().toISOString();
 
+  // Store current dependencies for future comparison
+  if (!arch.previous_dependencies) {
+    arch.previous_dependencies = {};
+  }
+
+  const depFiles = ['package.json', 'requirements.txt', 'go.mod', 'Pipfile', 'Cargo.toml'];
+  depFiles.forEach(file => {
+    if (fs.existsSync(file)) {
+      arch.previous_dependencies[file] = fs.readFileSync(file, 'utf8');
+    }
+  });
+
   // Ensure directory exists
   const dir = path.dirname(ARCHITECTURE_FILE);
   if (!fs.existsSync(dir)) {

package/template/bin/hooks/context-awareness.js

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+
+/**
+ * Context Awareness Module
+ *
+ * Analyzes project state and provides intelligent suggestions for next actions.
+ * Used by session-start and post-action hooks.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Read JSON file safely
+ */
+function readJSON(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const content = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(content);
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Check if file exists
+ */
+function fileExists(filePath) {
+  try {
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Analyze project state and return context
+ */
+export function analyzeProjectState(projectRoot = process.cwd()) {
+  const state = {
+    hasProductSpec: false,
+    hasArchitecture: false,
+    hasState: false,
+    hasCompletion: false,
+    hasPendingDecisions: false,
+    architectureValid: true,
+    architectureIssues: [],
+    currentPhase: 'idle',
+    completionPercent: 0,
+    totalFeatures: 0,
+    completedFeatures: 0,
+    pendingDecisionCount: 0,
+    blockingIssues: [],
+    suggestedActions: []
+  };
+
+  // Check product spec
+  const productIndex = path.join(projectRoot, '.claude/product/index.md');
+  const productDomains = path.join(projectRoot, '.claude/product/domains');
+  state.hasProductSpec = fileExists(productIndex) || fileExists(productDomains);
+
+  // Check architecture
+  const architecturePath = path.join(projectRoot, '.agentful/architecture.json');
+  if (fileExists(architecturePath)) {
+    state.hasArchitecture = true;
+    const arch = readJSON(architecturePath);
+
+    if (arch) {
+      // Validate architecture structure
+      if (!arch.techStack || !arch.agents) {
+        state.architectureValid = false;
+        state.architectureIssues.push('Missing techStack or agents fields');
+      }
+
+      // Check if architecture is stale (older than package.json)
+      try {
+        const packagePath = path.join(projectRoot, 'package.json');
+        if (fileExists(packagePath)) {
+          const archStat = fs.statSync(architecturePath);
+          const pkgStat = fs.statSync(packagePath);
+
+          if (pkgStat.mtime > archStat.mtime) {
+            state.architectureValid = false;
+            state.architectureIssues.push('Architecture older than package.json - may need regeneration');
+          }
+        }
+      } catch (error) {
+        // Ignore stat errors
+      }
+    } else {
+      state.architectureValid = false;
+      state.architectureIssues.push('Invalid JSON format');
+    }
+  }
+
+  // Check state
+  const statePath = path.join(projectRoot, '.agentful/state.json');
+  if (fileExists(statePath)) {
+    state.hasState = true;
+    const stateData = readJSON(statePath);
+    if (stateData) {
+      state.currentPhase = stateData.current_phase || 'idle';
+    }
+  }
+
+  // Check completion
+  const completionPath = path.join(projectRoot, '.agentful/completion.json');
+  if (fileExists(completionPath)) {
+    state.hasCompletion = true;
+    const completion = readJSON(completionPath);
+
+    if (completion && completion.features) {
+      const features = Object.values(completion.features);
+      state.totalFeatures = features.length;
+      state.completedFeatures = features.filter(f => f.completion >= 100).length;
+
+      if (state.totalFeatures > 0) {
+        state.completionPercent = Math.round((state.completedFeatures / state.totalFeatures) * 100);
+      }
+    }
+  }
+
+  // Check decisions
+  const decisionsPath = path.join(projectRoot, '.agentful/decisions.json');
+  if (fileExists(decisionsPath)) {
+    const decisions = readJSON(decisionsPath);
+
+    if (decisions && decisions.pending) {
+      state.pendingDecisionCount = decisions.pending.length;
+      state.hasPendingDecisions = state.pendingDecisionCount > 0;
+    }
+  }
+
+  // Determine blocking issues
+  if (!state.hasProductSpec) {
+    state.blockingIssues.push('No product specification found');
+  }
+
+  if (state.hasArchitecture && !state.architectureValid) {
+    state.blockingIssues.push('Architecture needs attention');
+  }
+
+  if (state.hasPendingDecisions) {
+    state.blockingIssues.push(`${state.pendingDecisionCount} pending decision(s)`);
+  }
+
+  // Generate suggested actions
+  state.suggestedActions = generateSuggestions(state);
+
+  return state;
+}
+
+/**
+ * Generate smart suggestions based on project state
+ */
+function generateSuggestions(state) {
+  const suggestions = [];
+
+  // First-time setup
+  if (!state.hasProductSpec) {
+    suggestions.push({
+      priority: 'critical',
+      action: 'Create product specification',
+      command: 'Edit .claude/product/index.md',
+      description: 'Define your product requirements'
+    });
+    return suggestions; // Block other suggestions until product spec exists
+  }
+
+  if (!state.hasArchitecture) {
+    suggestions.push({
+      priority: 'critical',
+      action: 'Generate architecture',
+      command: '/agentful-generate',
+      description: 'Analyze tech stack and create specialized agents'
+    });
+    return suggestions;
+  }
+
+  // Architecture issues
+  if (state.hasArchitecture && !state.architectureValid) {
+    suggestions.push({
+      priority: 'high',
+      action: 'Fix architecture',
+      command: '/agentful-generate',
+      description: state.architectureIssues.join('; ')
+    });
+  }
+
+  // Pending decisions block work
+  if (state.hasPendingDecisions) {
+    suggestions.push({
+      priority: 'high',
+      action: 'Answer pending decisions',
+      command: '/agentful-decide',
+      description: `${state.pendingDecisionCount} decision(s) blocking progress`
+    });
+  }
+
+  // Phase-specific suggestions
+  if (state.currentPhase === 'idle' || state.currentPhase === 'planning') {
+    suggestions.push({
+      priority: 'medium',
+      action: 'Start development',
+      command: '/agentful-start',
+      description: 'Begin or resume structured development'
+    });
+  }
+
+  if (state.currentPhase === 'implementation' || state.currentPhase === 'testing') {
+    suggestions.push({
+      priority: 'medium',
+      action: 'Check progress',
+      command: '/agentful-status',
+      description: `Current: ${state.completionPercent}% complete (${state.completedFeatures}/${state.totalFeatures} features)`
+    });
+  }
+
+  // Validation suggestion
+  if (state.hasCompletion && state.completionPercent > 0) {
+    suggestions.push({
+      priority: 'low',
+      action: 'Run quality checks',
+      command: '/agentful-validate',
+      description: 'Verify code quality and production readiness'
+    });
+  }
+
+  // Product analysis
+  suggestions.push({
+    priority: 'low',
+    action: 'Analyze product spec',
+    command: '/agentful-product',
+    description: 'Check for gaps and ambiguities'
+  });
+
+  return suggestions;
+}
+
+/**
+ * Format suggestions for display
+ */
+export function formatSuggestions(suggestions, options = {}) {
+  const { maxSuggestions = 5, includeNumbers = true } = options;
+
+  if (suggestions.length === 0) {
+    return '💡 All set! Type a command or ask what you need.';
+  }
+
+  // Sort by priority
+  const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+  const sorted = suggestions.sort((a, b) => {
+    return priorityOrder[a.priority] - priorityOrder[b.priority];
+  });
+
+  // Take top N
+  const topSuggestions = sorted.slice(0, maxSuggestions);
+
+  // Format output
+  let output = '💡 Suggested next steps:\n';
+
+  topSuggestions.forEach((suggestion, index) => {
+    const number = includeNumbers ? `${index + 1}. ` : '   • ';
+    const icon = suggestion.priority === 'critical' ? '🔴' :
+                 suggestion.priority === 'high' ? '⚠️ ' : '';
+
+    output += `   ${number}${icon}${suggestion.action} → ${suggestion.command}\n`;
+    if (suggestion.description) {
+      output += `      ${suggestion.description}\n`;
+    }
+  });
+
+  return output.trim();
+}
+
+/**
+ * Generate session start message
+ */
+export function generateSessionStartMessage(projectRoot = process.cwd()) {
+  const state = analyzeProjectState(projectRoot);
+  let message = '';
+
+  // Status line
+  if (state.hasCompletion && state.totalFeatures > 0) {
+    message += `📊 Project Status: ${state.completionPercent}% complete (${state.completedFeatures}/${state.totalFeatures} features)\n`;
+  } else if (state.hasArchitecture) {
+    message += '📊 Project Status: Architecture ready, no active development\n';
+  } else {
+    message += '📊 Project Status: Initial setup\n';
+  }
+
+  // Blocking issues
+  if (state.blockingIssues.length > 0) {
+    state.blockingIssues.forEach(issue => {
+      message += `⚠️  ${issue}\n`;
+    });
+    message += '\n';
+  }
+
+  // Current phase
+  if (state.currentPhase !== 'idle') {
+    message += `🔄 Current Phase: ${state.currentPhase}\n\n`;
+  }
+
+  // Suggestions
+  message += formatSuggestions(state.suggestedActions, { maxSuggestions: 3 });
+
+  return message;
+}
+
+/**
+ * Generate post-action suggestions
+ */
+export function generatePostActionSuggestions(action, projectRoot = process.cwd()) {
+  const state = analyzeProjectState(projectRoot);
+
+  // Action-specific follow-ups
+  const actionMap = {
+    'agentful-generate': () => {
+      if (state.completionPercent === 0) {
+        return [{
+          priority: 'high',
+          action: 'Start development',
+          command: '/agentful-start',
+          description: 'Begin building features'
+        }];
+      }
+      return [];
+    },
+
+    'agentful-start': () => [{
+      priority: 'medium',
+      action: 'Monitor progress',
+      command: '/agentful-status',
+      description: 'Check completion and active work'
+    }],
+
+    'agentful-decide': () => {
+      if (state.pendingDecisionCount === 0) {
+        return [{
+          priority: 'high',
+          action: 'Resume development',
+          command: '/agentful-start',
+          description: 'Continue with unblocked work'
+        }];
+      }
+      return [];
+    },
+
+    'agentful-validate': () => [{
+      priority: 'medium',
+      action: 'Fix validation issues',
+      command: 'Review output and address failures',
+      description: 'Fixer agent can auto-resolve some issues'
+    }]
+  };
+
+  const specificSuggestions = actionMap[action]?.() || [];
+  const generalSuggestions = state.suggestedActions.filter(s =>
+    s.command !== `/${action}`
+  );
+
+  return [...specificSuggestions, ...generalSuggestions];
+}

package/template/bin/hooks/health-check.js

@@ -110,7 +110,7 @@ if (!fs.existsSync(architecturePath)) {
   try {
     const archContent = fs.readFileSync(architecturePath, 'utf8');
     const arch = JSON.parse(archContent);
-    if (!arch.techStack || !arch.domains) {
+    if ((!arch.tech_stack && !arch.techStack) || !arch.domains) {
       console.log('⚠️  .agentful/architecture.json is malformed');
       console.log('   Run /agentful-generate to regenerate');
       warnings++;

package/template/bin/hooks/mcp-health-check.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * MCP Server Health Check Hook
+ *
+ * Checks if the Agentful MCP server is running and properly configured.
+ * This should be run in the SessionStart hook after the main health check.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Check if MCP server tools are available
+ * This is a basic check - actual tool testing happens when tools are called
+ */
+function checkMCPServerHealth() {
+  const mcpServerPath = path.resolve(process.cwd(), 'mcp-server');
+
+  // Skip check if MCP server directory doesn't exist
+  if (!fs.existsSync(mcpServerPath)) {
+    return; // Silent skip - MCP server is optional
+  }
+
+  // Check if MCP server is built
+  const distPath = path.join(mcpServerPath, 'dist');
+  if (!fs.existsSync(distPath)) {
+    console.log('⚠️  MCP server not built. Run: cd mcp-server && npm run build');
+    return;
+  }
+
+  // Check if WASM file exists
+  const wasmPaths = [
+    path.join(mcpServerPath, 'dist/infrastructure/sql-wasm.wasm'),
+    path.join(mcpServerPath, 'dist/sql-wasm.wasm'),
+    path.join(mcpServerPath, 'sql-wasm.wasm')
+  ];
+
+  const wasmExists = wasmPaths.some(p => fs.existsSync(p));
+  if (!wasmExists) {
+    console.log('⚠️  MCP server WASM file missing. Run: cd mcp-server && npm run build');
+    return;
+  }
+
+  // All checks passed
+  if (process.env.AGENTFUL_LOG_LEVEL === 'debug') {
+    console.log('✅ MCP server health check passed');
+  }
+}
+
+// Run health check
+checkMCPServerHealth();