@itz4blitz/agentful 1.3.0 → 1.4.1

package/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/bin/hooks/post-action-suggestions.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+/**
+ * Post-Action Suggestions Hook
+ *
+ * Runs after specific slash commands complete.
+ * Provides smart suggestions for what to do next.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Try to import context-awareness module
+let contextModule = null;
+try {
+  const modulePath = path.join(__dirname, './context-awareness.js');
+  if (fs.existsSync(modulePath)) {
+    contextModule = await import(modulePath);
+  }
+} catch (error) {
+  // Silently fail
+}
+
+// Detect which action was just completed
+const lastAction = process.env.LAST_COMMAND || '';
+
+// Map of slash commands to action names
+const actionMap = {
+  'agentful-generate': 'agentful-generate',
+  'agentful-start': 'agentful-start',
+  'agentful-decide': 'agentful-decide',
+  'agentful-validate': 'agentful-validate',
+  'agentful-status': 'agentful-status',
+  'agentful-product': 'agentful-product'
+};
+
+// Find matching action
+let detectedAction = null;
+for (const [cmd, action] of Object.entries(actionMap)) {
+  if (lastAction.includes(cmd)) {
+    detectedAction = action;
+    break;
+  }
+}
+
+// Show suggestions if we have context module and detected action
+if (contextModule && contextModule.generatePostActionSuggestions && detectedAction) {
+  try {
+    const suggestions = contextModule.generatePostActionSuggestions(
+      detectedAction,
+      process.cwd()
+    );
+
+    if (suggestions.length > 0) {
+      const formatted = contextModule.formatSuggestions(suggestions, {
+        maxSuggestions: 3,
+        includeNumbers: true
+      });
+
+      console.log('');
+      console.log('─'.repeat(60));
+      console.log(formatted);
+      console.log('─'.repeat(60));
+    }
+  } catch (error) {
+    // Silently fail - don't disrupt user experience
+    if (process.env.VERBOSE) {
+      console.log(`Post-action suggestion error: ${error.message}`);
+    }
+  }
+}

package/bin/hooks/session-start.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+/**
+ * Session Start Hook
+ *
+ * Runs when Claude Code session starts.
+ * Provides intelligent context awareness and suggests next actions.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Try to import context-awareness module from agentful package
+let contextModule = null;
+try {
+  // Import from same directory (bin/hooks/)
+  const modulePath = path.join(__dirname, './context-awareness.js');
+  if (fs.existsSync(modulePath)) {
+    contextModule = await import(modulePath);
+  }
+} catch (error) {
+  // Silently fail - we'll show basic status instead
+}
+
+/**
+ * Detect if TeammateTool (parallel execution) is enabled
+ */
+function detectParallelExecution() {
+  try {
+    // Find Claude Code binary
+    const npmRoot = execSync('npm root -g', { encoding: 'utf8' }).trim();
+    const cliPath = path.join(npmRoot, '@anthropic-ai', 'claude-code', 'cli.js');
+
+    if (!fs.existsSync(cliPath)) {
+      return { enabled: false, reason: 'Claude Code binary not found' };
+    }
+
+    // Check for TeammateTool pattern
+    const content = fs.readFileSync(cliPath, 'utf8');
+    const hasTeammateTool = /TeammateTool|teammate_mailbox|launchSwarm/.test(content);
+
+    if (!hasTeammateTool) {
+      return { enabled: false, reason: 'Claude Code version too old' };
+    }
+
+    // Check if gate is disabled (means it's patched/enabled)
+    const SWARM_GATE_MARKER = /tengu_brass_pebble/;
+    const gateExists = SWARM_GATE_MARKER.test(content);
+
+    if (!gateExists) {
+      return { enabled: true, method: 'patched' };
+    }
+
+    return { enabled: false, reason: 'TeammateTool not enabled' };
+  } catch (error) {
+    return { enabled: false, reason: error.message };
+  }
+}
+
+// Main execution
+const detection = detectParallelExecution();
+
+// Basic parallel execution status
+const parallelStatus = detection.enabled
+  ? '✅ Agentful ready (parallel execution: ON)'
+  : '⚠️  Agentful ready (parallel execution: OFF - agents will run sequentially)';
+
+// Try to show intelligent context awareness
+if (contextModule && contextModule.generateSessionStartMessage) {
+  try {
+    const message = contextModule.generateSessionStartMessage(process.cwd());
+    console.log(parallelStatus);
+    console.log('');
+    console.log(message);
+  } catch (error) {
+    // Fall back to basic status
+    console.log(parallelStatus);
+    if (process.env.VERBOSE) {
+      console.log(`   Context awareness error: ${error.message}`);
+    }
+  }
+} else {
+  // No context module - show basic status
+  console.log(parallelStatus);
+  if (process.env.VERBOSE && !detection.enabled) {
+    console.log(`   Reason: ${detection.reason}`);
+  }
+}