@howlil/ez-agents 3.5.0 → 4.0.0

package/bin/guards/team-overhead-guard.cjs

@@ -0,0 +1,266 @@
+/**
+ * EDGE-06: Team Overhead Guard
+ * 
+ * Detects organizational change suggestions.
+ * Prevents suggesting team restructuring without explicit need.
+ */
+
+// Organizational change keywords
+const ORG_CHANGE_KEYWORDS = [
+  // Team structure
+  'team structure', 'reorganize team', 'restructure team', 'new team',
+  'scrum team', 'squad', 'tribe', 'chapter', 'guild',
+  
+  // Roles and positions
+  'new role', 'create role', 'hire', 'recruiting', 'job description',
+  'team lead', 'tech lead', 'engineering manager', 'product owner',
+  'scrum master', 'architect role', 'dedicated person',
+  
+  // Meetings and ceremonies
+  'daily standup', 'sprint planning', 'retrospective', 'sprint review',
+  'new meeting', 'weekly sync', 'bi-weekly', 'ceremony',
+  
+  // Process changes
+  'change process', 'new workflow', 'approval process', 'sign-off',
+  'gate keeping', 'code review process', 'pr review requirement',
+  
+  // Communication
+  'communication channel', 'slack channel', 'teams channel',
+  'reporting structure', 'escalation path', 'chain of command',
+  
+  // Documentation overhead
+  'documentation requirement', 'design doc', 'rfc process',
+  'architecture review board', 'change advisory board'
+];
+
+// Legitimate technical suggestions (not org changes)
+const TECHNICAL_SUGGESTIONS = [
+  'add test', 'write test', 'create component', 'implement feature',
+  'refactor', 'optimize', 'fix bug', 'update dependency',
+  'add logging', 'add monitoring', 'improve performance'
+];
+
+/**
+ * Detect organizational changes in text
+ * @param {string} output - AI generated text
+ * @returns {object} { hasOrgChanges: boolean, suggestions: array, overhead: string }
+ */
+function detectOrgChanges(output) {
+  const lowerOutput = output.toLowerCase();
+  const foundKeywords = [];
+  const suggestions = [];
+  
+  // Check for org change keywords
+  for (const keyword of ORG_CHANGE_KEYWORDS) {
+    if (lowerOutput.includes(keyword)) {
+      foundKeywords.push(keyword);
+      
+      // Extract the surrounding suggestion
+      const context = extractContext(output, keyword);
+      suggestions.push({
+        keyword,
+        context: context.trim()
+      });
+    }
+  }
+  
+  // Check if these are actually org changes vs technical suggestions
+  const isTechnicalOnly = TECHNICAL_SUGGESTIONS.some(tech => 
+    lowerOutput.includes(tech) && foundKeywords.length === 0
+  );
+  
+  return {
+    hasOrgChanges: foundKeywords.length > 0 && !isTechnicalOnly,
+    suggestions,
+    keywordCount: foundKeywords.length,
+    overhead: estimateOverhead(suggestions),
+    recommendation: foundKeywords.length > 0
+      ? 'Consider if organizational changes are necessary for this task'
+      : 'No organizational changes detected'
+  };
+}
+
+/**
+ * Flag team restructuring suggestions
+ * @param {string} suggestion - The suggestion text
+ * @returns {object} Flagged suggestion details
+ */
+function flagTeamRestructure(suggestion) {
+  const result = detectOrgChanges(suggestion);
+  
+  return {
+    flagged: result.hasOrgChanges,
+    ...result,
+    severity: result.keywordCount > 3 
+      ? 'high' 
+      : result.keywordCount > 1 
+        ? 'medium' 
+        : 'low',
+    action: result.hasOrgChanges
+      ? 'Requires explicit justification and user approval'
+      : 'No action needed'
+  };
+}
+
+/**
+ * Check overhead of organizational changes
+ * @param {array} suggestions - Array of organizational suggestions
+ * @returns {string} Estimated overhead description
+ */
+function estimateOverhead(suggestions) {
+  if (suggestions.length === 0) {
+    return 'No organizational overhead';
+  }
+  
+  const categories = new Set();
+  
+  for (const suggestion of suggestions) {
+    if (['team structure', 'reorganize', 'restructure', 'squad', 'tribe'].some(k => suggestion.keyword.includes(k))) {
+      categories.add('team-restructure');
+    }
+    if (['role', 'hire', 'recruit', 'lead', 'manager'].some(k => suggestion.keyword.includes(k))) {
+      categories.add('hiring-roles');
+    }
+    if (['meeting', 'standup', 'ceremony', 'sync'].some(k => suggestion.keyword.includes(k))) {
+      categories.add('meeting-overhead');
+    }
+    if (['process', 'workflow', 'approval', 'sign-off'].some(k => suggestion.keyword.includes(k))) {
+      categories.add('process-overhead');
+    }
+  }
+  
+  const overheadEstimates = {
+    'team-restructure': 'High: Team restructuring has long-term impact',
+    'hiring-roles': 'High: New roles require budget and time',
+    'meeting-overhead': 'Medium: Recurring time commitment',
+    'process-overhead': 'Medium: Ongoing process overhead'
+  };
+  
+  const estimates = Array.from(categories).map(c => overheadEstimates[c]);
+  
+  if (estimates.length === 0) {
+    return 'Low: Minor organizational impact';
+  }
+  
+  return estimates.join('; ');
+}
+
+/**
+ * Check for team overhead in task context
+ * @param {string} taskContext - Task description
+ * @returns {object} Team overhead analysis
+ */
+function checkOverhead(taskContext) {
+  const orgChanges = detectOrgChanges(taskContext);
+  const flagged = flagTeamRestructure(taskContext);
+  
+  return {
+    hasOrgChanges: orgChanges.hasOrgChanges,
+    suggestions: orgChanges.suggestions,
+    overhead: orgChanges.overhead,
+    severity: flagged.severity,
+    actionable: flagged.flagged,
+    recommendation: flagged.flagged
+      ? 'Remove organizational suggestions or explicitly justify them'
+      : 'Task context is appropriate'
+  };
+}
+
+/**
+ * Extract context around a keyword
+ * @param {string} text - Full text
+ * @param {string} keyword - Keyword to find context for
+ * @returns {string} Context around keyword
+ */
+function extractContext(text, keyword) {
+  const index = text.toLowerCase().indexOf(keyword);
+  if (index === -1) return '';
+  
+  const start = Math.max(0, index - 50);
+  const end = Math.min(text.length, index + keyword.length + 100);
+  
+  return text.substring(start, end)
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Full team overhead check
+ * @param {string} output - AI generated output
+ * @returns {object} Complete team overhead analysis
+ */
+function checkTeamOverhead(output) {
+  const orgChanges = detectOrgChanges(output);
+  
+  return {
+    ...orgChanges,
+    summary: orgChanges.hasOrgChanges
+      ? `⚠️  Found ${orgChanges.keywordCount} organizational change suggestion(s)`
+      : '✅ No organizational changes detected',
+    actionable: orgChanges.hasOrgChanges
+  };
+}
+
+/**
+ * CLI entry point
+ */
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  
+  if (command === 'check') {
+    const text = args.slice(1).join(' ') || process.stdin.read();
+    
+    if (!text.trim()) {
+      console.log('Usage: node team-overhead-guard.cjs check <text>');
+      console.log('  or:  echo "text" | node team-overhead-guard.cjs check');
+      process.exit(1);
+    }
+    
+    const result = checkTeamOverhead(text);
+    
+    console.log('Team Overhead Analysis');
+    console.log('======================');
+    console.log(result.summary);
+    
+    if (result.suggestions.length > 0) {
+      console.log('');
+      console.log('Organizational suggestions found:');
+      result.suggestions.forEach((s, i) => {
+        console.log(`  ${i + 1}. "${s.context}"`);
+        console.log(`     Keyword: ${s.keyword}`);
+      });
+      
+      console.log('');
+      console.log(`Estimated overhead: ${result.overhead}`);
+      console.log('');
+      console.log('Recommendation:');
+      console.log(`  ${result.recommendation}`);
+    }
+    
+    process.exit(result.hasOrgChanges ? 1 : 0);
+    
+  } else if (command === 'keywords') {
+    console.log('Organizational change keywords:');
+    ORG_CHANGE_KEYWORDS.forEach(k => console.log(`  - ${k}`));
+    process.exit(0);
+    
+  } else {
+    console.log('Usage: node team-overhead-guard.cjs <command> [args]');
+    console.log('Commands:');
+    console.log('  check [text]     - Analyze for organizational changes');
+    console.log('  keywords         - List organizational change keywords');
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  detectOrgChanges,
+  flagTeamRestructure,
+  estimateOverhead,
+  checkOverhead,
+  checkTeamOverhead,
+  extractContext,
+  ORG_CHANGE_KEYWORDS,
+  TECHNICAL_SUGGESTIONS
+};

package/bin/guards/tool-sprawl-guard.cjs

@@ -0,0 +1,271 @@
+/**
+ * EDGE-05: Tool Sprawl Guard
+ * 
+ * Enforces 3-7 skills/tools per task limit.
+ * Prevents cognitive overload and maintains focus.
+ */
+
+// Recommended skill/tool categories
+const SKILL_CATEGORIES = {
+  core: ['runtime', 'framework', 'language'],
+  testing: ['test-runner', 'assertion', 'mocking', 'coverage'],
+  database: ['orm', 'query-builder', 'migration', 'driver'],
+  ui: ['component-library', 'styling', 'state-management', 'routing'],
+  devops: ['bundler', 'linter', 'formatter', 'ci-cd']
+};
+
+/**
+ * Get active tools/skills from task context
+ * @param {string} taskContext - Task description or context
+ * @returns {string[]} Array of active tools/skills
+ */
+function getActiveTools(taskContext) {
+  const toolPatterns = [
+    /(?:using|with|via|through|use|via)\s+(?:the\s+)?(['"]?)([^'"\s,]+)\1(?:\s+(?:library|tool|package|framework|skill))?/gi,
+    /(?:tool|library|package|framework|skill)[:\s]+(['"]?)([^'"\s,]+)\1/gi,
+    /@([a-z0-9_-]+\/[a-z0-9_-]+)/gi,  // npm scoped packages
+    /(?:npm|yarn|pnpm)\s+(?:install|add)\s+([^&|;\n]+)/gi
+  ];
+  
+  const tools = new Set();
+  
+  for (const pattern of toolPatterns) {
+    let match;
+    while ((match = pattern.exec(taskContext)) !== null) {
+      // Extract the tool name (group 2 for most patterns, group 1 for scoped)
+      const toolName = match[2] || match[1];
+      if (toolName) {
+        tools.add(toolName.toLowerCase().replace(/['"]/g, ''));
+      }
+    }
+  }
+  
+  return Array.from(tools);
+}
+
+/**
+ * Check tool count against limits
+ * @param {string[]} activeTools - Array of active tools/skills
+ * @returns {object} { count: number, withinLimit: boolean, exceeded: number }
+ */
+function checkToolCount(activeTools) {
+  const count = activeTools.length;
+  const minRecommended = 3;
+  const maxRecommended = 7;
+  
+  let withinLimit = true;
+  let exceeded = 0;
+  
+  if (count > maxRecommended) {
+    withinLimit = false;
+    exceeded = count - maxRecommended;
+  }
+  
+  return {
+    count,
+    withinLimit,
+    exceeded,
+    minRecommended,
+    maxRecommended,
+    status: count < minRecommended 
+      ? 'below-recommended' 
+      : count > maxRecommended 
+        ? 'exceeded' 
+        : 'optimal'
+  };
+}
+
+/**
+ * Enforce skill limit on a task
+ * @param {string} taskContext - Task description
+ * @returns {object} Enforcement result with recommendations
+ */
+function enforceSkillLimit(taskContext) {
+  const activeTools = getActiveTools(taskContext);
+  const toolCheck = checkToolCount(activeTools);
+  
+  if (toolCheck.withinLimit) {
+    return {
+      enforced: true,
+      tools: activeTools,
+      ...toolCheck,
+      recommendation: 'Tool count is within recommended limits'
+    };
+  }
+  
+  // Categorize tools
+  const categorized = categorizeTools(activeTools);
+  
+  // Recommend which tools to keep
+  const recommended = recommendTools(categorized, taskContext);
+  
+  return {
+    enforced: false,
+    tools: activeTools,
+    ...toolCheck,
+    categorized,
+    recommended,
+    recommendation: `Reduce from ${toolCheck.count} to ${toolCheck.maxRecommended} tools. Consider removing: ${activeTools.filter(t => !recommended.includes(t)).join(', ')}`
+  };
+}
+
+/**
+ * Categorize tools by function
+ * @param {string[]} tools - Array of tools
+ * @returns {object} Categorized tools
+ */
+function categorizeTools(tools) {
+  const categories = {
+    core: [],
+    testing: [],
+    database: [],
+    ui: [],
+    devops: [],
+    other: []
+  };
+  
+  // Simple categorization based on tool name patterns
+  const categoryPatterns = {
+    testing: ['jest', 'vitest', 'mocha', 'chai', 'sinon', 'playwright', 'cypress', 'test'],
+    database: ['prisma', 'mongoose', 'sequelize', 'typeorm', 'knex', 'mongo', 'postgres', 'mysql'],
+    ui: ['react', 'vue', 'angular', 'svelte', 'tailwind', 'bootstrap', 'material', 'chakra'],
+    devops: ['webpack', 'vite', 'rollup', 'eslint', 'prettier', 'husky', 'lint']
+  };
+  
+  for (const tool of tools) {
+    let categorized = false;
+    
+    for (const [category, patterns] of Object.entries(categoryPatterns)) {
+      if (patterns.some(p => tool.toLowerCase().includes(p))) {
+        categories[category].push(tool);
+        categorized = true;
+        break;
+      }
+    }
+    
+    if (!categorized) {
+      categories.other.push(tool);
+    }
+  }
+  
+  return categories;
+}
+
+/**
+ * Recommend which tools to keep based on task context
+ * @param {object} categorized - Categorized tools
+ * @param {string} taskContext - Task description
+ * @returns {string[]} Recommended tools to keep
+ */
+function recommendTools(categorized, taskContext) {
+  const recommended = [];
+  const lowerContext = taskContext.toLowerCase();
+  
+  // Always keep core tools
+  recommended.push(...categorized.core);
+  
+  // Add category based on task context
+  if (lowerContext.includes('test') || lowerContext.includes('spec')) {
+    recommended.push(...categorized.testing.slice(0, 2));
+  }
+  if (lowerContext.includes('database') || lowerContext.includes('model') || lowerContext.includes('schema')) {
+    recommended.push(...categorized.database.slice(0, 2));
+  }
+  if (lowerContext.includes('ui') || lowerContext.includes('component') || lowerContext.includes('render')) {
+    recommended.push(...categorized.ui.slice(0, 2));
+  }
+  if (lowerContext.includes('build') || lowerContext.includes('bundle') || lowerContext.includes('deploy')) {
+    recommended.push(...categorized.devops.slice(0, 2));
+  }
+  
+  // Add some other tools if space allows
+  const remaining = 7 - recommended.length;
+  if (remaining > 0) {
+    recommended.push(...categorized.other.slice(0, remaining));
+  }
+  
+  // Deduplicate
+  return [...new Set(recommended)];
+}
+
+/**
+ * Full tool sprawl check
+ * @param {string} taskContext - Task description
+ * @returns {object} Complete tool sprawl analysis
+ */
+function checkToolSprawl(taskContext) {
+  const activeTools = getActiveTools(taskContext);
+  const toolCheck = checkToolCount(activeTools);
+  const enforcement = enforceSkillLimit(taskContext);
+  
+  return {
+    ...toolCheck,
+    tools: activeTools,
+    enforcement,
+    actionable: !toolCheck.withinLimit,
+    summary: toolCheck.withinLimit
+      ? `✅ Using ${toolCheck.count} tools (optimal: 3-7)`
+      : `⚠️  Using ${toolCheck.count} tools (${toolCheck.exceeded} over limit)`
+  };
+}
+
+/**
+ * CLI entry point
+ */
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  
+  if (command === 'check') {
+    const context = args.slice(1).join(' ') || process.stdin.read();
+    
+    if (!context.trim()) {
+      console.log('Usage: node tool-sprawl-guard.cjs check <task context>');
+      console.log('  or:  echo "task context" | node tool-sprawl-guard.cjs check');
+      process.exit(1);
+    }
+    
+    const result = checkToolSprawl(context);
+    
+    console.log('Tool Sprawl Analysis');
+    console.log('====================');
+    console.log(`Tools found: ${result.count}`);
+    console.log(`Status: ${result.status}`);
+    console.log('');
+    
+    if (result.tools.length > 0) {
+      console.log('Active tools:');
+      result.tools.forEach(t => console.log(`  - ${t}`));
+    }
+    
+    console.log('');
+    console.log(result.summary);
+    
+    if (!result.withinLimit) {
+      console.log('');
+      console.log('Recommendation:');
+      console.log(`  ${result.enforcement.recommendation}`);
+      console.log('');
+      console.log('Recommended tools to keep:');
+      result.enforcement.recommended.forEach(t => console.log(`  - ${t}`));
+    }
+    
+    process.exit(result.withinLimit ? 0 : 1);
+    
+  } else {
+    console.log('Usage: node tool-sprawl-guard.cjs <command> [args]');
+    console.log('Commands:');
+    console.log('  check [context]  - Analyze tool usage (reads from stdin if no args)');
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  getActiveTools,
+  checkToolCount,
+  enforceSkillLimit,
+  categorizeTools,
+  recommendTools,
+  checkToolSprawl,
+  SKILL_CATEGORIES
+};

package/bin/lib/analytics/analytics-collector.cjs

@@ -0,0 +1,86 @@
+/**
+ * Analytics Collector — Feature usage event collection and local storage
+ * Stores events in .planning/analytics/events.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class AnalyticsCollector {
+  constructor(cwd) {
+    this.cwd = cwd || process.cwd();
+    this.eventsPath = path.join(this.cwd, '.planning', 'analytics', 'events.json');
+    this.ensureDir();
+  }
+
+  /**
+   * Track an analytics event
+   * @param {Object} event - Event data { type, userId, properties }
+   */
+  async trackEvent(event) {
+    const data = {
+      timestamp: new Date().toISOString(),
+      eventType: event.type,
+      userId: event.userId || 'anonymous',
+      properties: event.properties || {}
+    };
+
+    await this.appendToJsonFile(data);
+  }
+
+  /**
+   * Get events by type
+   * @param {string} type - Event type to filter
+   * @returns {Array} Filtered events
+   */
+  getEventsByType(type) {
+    if (!fs.existsSync(this.eventsPath)) return [];
+    
+    const events = JSON.parse(fs.readFileSync(this.eventsPath, 'utf8'));
+    return events.filter(e => e.eventType === type);
+  }
+
+  /**
+   * Get all events
+   * @returns {Array} All events
+   */
+  getAllEvents() {
+    if (!fs.existsSync(this.eventsPath)) return [];
+    return JSON.parse(fs.readFileSync(this.eventsPath, 'utf8'));
+  }
+
+  /**
+   * Ensure analytics directory exists
+   */
+  ensureDir() {
+    const dir = path.dirname(this.eventsPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    if (!fs.existsSync(this.eventsPath)) {
+      fs.writeFileSync(this.eventsPath, '[]', 'utf8');
+    }
+  }
+
+  /**
+   * Append data to JSON file
+   * @param {Object} data - Data to append
+   */
+  async appendToJsonFile(data) {
+    const events = this.getAllEvents();
+    events.push(data);
+    fs.writeFileSync(this.eventsPath, JSON.stringify(events, null, 2), 'utf8');
+  }
+}
+
+/**
+ * Track an analytics event
+ * @param {Object} event - Event data
+ * @param {string} cwd - Working directory
+ */
+async function trackEvent(event, cwd) {
+  const collector = new AnalyticsCollector(cwd);
+  return collector.trackEvent(event);
+}
+
+module.exports = { AnalyticsCollector, trackEvent };