agileflow 3.3.0 → 3.4.0

package/scripts/generators/inject-babysit.js

@@ -14,9 +14,11 @@ const { scanAgents } = require('./agent-registry');
 const { scanCommands } = require('./command-registry');
 
 /**
- * Generate agent list content with details
+ * Generate agent list content as category summary with counts.
+ * Uses compact format with discovery pointer instead of listing every agent name.
+ * Research (arXiv:2602.11988): Full lists increase context cost without improving performance.
  * @param {Array} agents - Array of agent metadata
- * @returns {string} Formatted agent list
+ * @returns {string} Formatted agent category summary
  */
 function generateAgentList(agents) {
   const lines = [];
@@ -24,16 +26,27 @@ function generateAgentList(agents) {
   lines.push(`**AVAILABLE AGENTS** (${agents.length} total):`);
   lines.push('');
 
-  let count = 1;
+  // Group agents by category for compact output (counts only, not full names)
+  const categories = {};
   for (const agent of agents) {
-    lines.push(`${count}. **${agent.name}** (model: ${agent.model})`);
-    lines.push(`   - **Purpose**: ${agent.description}`);
-    lines.push(`   - **Tools**: ${agent.tools.join(', ')}`);
-    lines.push(`   - **Category**: ${agent.category}`);
-    lines.push('');
-    count++;
+    const cat = agent.category || 'Other';
+    if (!categories[cat]) categories[cat] = { count: 0, examples: [] };
+    categories[cat].count++;
+    // Keep first 3 names as examples
+    if (categories[cat].examples.length < 3) {
+      categories[cat].examples.push(agent.name);
+    }
+  }
+
+  for (const [category, data] of Object.entries(categories)) {
+    const examples = data.examples.join(', ');
+    const more = data.count > 3 ? `, +${data.count - 3} more` : '';
+    lines.push(`**${category}** (${data.count}): ${examples}${more}`);
   }
 
+  lines.push('');
+  lines.push('Browse all: `ls .agileflow/agents/` or run `/agileflow:help agents`');
+
   return lines.join('\n');
 }
 

package/scripts/generators/inject-help.js

@@ -13,9 +13,11 @@ const path = require('path');
 const { scanCommands } = require('./command-registry');
 
 /**
- * Generate command list content grouped by category
+ * Generate command list content as category summary with counts and examples.
+ * Uses compact format with discovery pointer instead of listing every command.
+ * Research (arXiv:2602.11988): Full lists increase context cost without improving performance.
  * @param {Array} commands - Array of command metadata
- * @returns {string} Formatted command list
+ * @returns {string} Formatted command category summary
  */
 function generateCommandList(commands) {
   const lines = [];
@@ -29,16 +31,24 @@ function generateCommandList(commands) {
     categories[cmd.category].push(cmd);
   }
 
-  // Generate markdown for each category
+  lines.push(
+    `**${commands.length} commands** across ${Object.keys(categories).length} categories:`
+  );
+  lines.push('');
+
+  // Generate compact category summary with examples
   for (const [category, cmds] of Object.entries(categories)) {
-    lines.push(`**${category}:**`);
-    for (const cmd of cmds) {
-      const hint = cmd.argumentHint ? ` ${cmd.argumentHint}` : '';
-      lines.push(`- \`/agileflow:${cmd.name}${hint}\` - ${cmd.description}`);
-    }
-    lines.push(''); // Blank line between categories
+    const examples = cmds
+      .slice(0, 3)
+      .map(c => c.name)
+      .join(', ');
+    const more = cmds.length > 3 ? `, +${cmds.length - 3} more` : '';
+    lines.push(`- **${category}** (${cmds.length}): ${examples}${more}`);
   }
 
+  lines.push('');
+  lines.push('Browse all: `ls .agileflow/commands/` or run `/agileflow:help`');
+
   return lines.join('\n');
 }
 

package/scripts/lib/audit-cleanup.js

@@ -0,0 +1,250 @@
+/**
+ * audit-cleanup.js - Orphan cleanup for ULTRADEEP audit sessions
+ *
+ * Cleans up abandoned tmux sessions and incomplete sentinel directories
+ * from ULTRADEEP audit runs. Designed to be called from Stop hooks or
+ * manually for maintenance.
+ *
+ * Usage:
+ *   const { cleanupOrphanSessions } = require('./audit-cleanup');
+ *   cleanupOrphanSessions(rootDir);
+ *
+ * CLI:
+ *   node scripts/lib/audit-cleanup.js [--max-age=60] [--dry-run]
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const MAX_AGE_MINUTES = 60;
+
+/**
+ * Find all ultradeep trace directories.
+ * @param {string} rootDir - Project root
+ * @returns {Array<{ traceId: string, dir: string, status: object|null }>}
+ */
+function findTraceDirectories(rootDir) {
+  const ultradeepDir = path.join(rootDir, 'docs', '09-agents', 'ultradeep');
+
+  if (!fs.existsSync(ultradeepDir)) {
+    return [];
+  }
+
+  const traces = [];
+  try {
+    const entries = fs.readdirSync(ultradeepDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const traceDir = path.join(ultradeepDir, entry.name);
+      const statusFile = path.join(traceDir, '_status.json');
+      let status = null;
+
+      try {
+        if (fs.existsSync(statusFile)) {
+          status = JSON.parse(fs.readFileSync(statusFile, 'utf8'));
+        }
+      } catch (_) {
+        // Corrupt status file
+      }
+
+      traces.push({
+        traceId: entry.name,
+        dir: traceDir,
+        status,
+      });
+    }
+  } catch (_) {
+    // Directory read failure
+  }
+
+  return traces;
+}
+
+/**
+ * Check if a trace is stale (older than maxAge).
+ * @param {object} trace - Trace info from findTraceDirectories
+ * @param {number} maxAgeMinutes - Maximum age in minutes
+ * @returns {boolean}
+ */
+function isStaleTrace(trace, maxAgeMinutes) {
+  if (!trace.status || !trace.status.started_at) {
+    // No status = assume stale
+    return true;
+  }
+
+  const startedAt = new Date(trace.status.started_at).getTime();
+  if (isNaN(startedAt)) return true; // Invalid date = treat as stale
+  const age = Date.now() - startedAt;
+  return age > maxAgeMinutes * 60 * 1000;
+}
+
+/**
+ * Check if a trace is incomplete (not all analyzers have findings).
+ * @param {object} trace - Trace info from findTraceDirectories
+ * @returns {boolean}
+ */
+function isIncompleteTrace(trace) {
+  if (!trace.status || !trace.status.analyzers) return true;
+
+  const expected = trace.status.analyzers;
+  const completed = trace.status.completed || [];
+
+  return completed.length < expected.length;
+}
+
+/**
+ * Find orphaned tmux sessions matching audit pattern.
+ * @returns {string[]} Array of session names
+ */
+function findOrphanedTmuxSessions() {
+  try {
+    const output = execFileSync('tmux', ['list-sessions', '-F', '#{session_name}'], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+
+    if (!output) return [];
+
+    return output.split('\n').filter(name => name.startsWith('audit-'));
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * Kill a tmux session by name.
+ * @param {string} sessionName - Session name to kill
+ * @returns {boolean} True if killed successfully
+ */
+function killTmuxSession(sessionName) {
+  try {
+    execFileSync('tmux', ['kill-session', '-t', sessionName], {
+      stdio: 'pipe',
+    });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Remove a sentinel directory.
+ * @param {string} dir - Directory to remove
+ * @returns {boolean} True if removed successfully
+ */
+function removeSentinelDir(dir) {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Clean up orphaned ULTRADEEP audit sessions and stale sentinel dirs.
+ *
+ * @param {string} rootDir - Project root directory
+ * @param {object} [options] - Options
+ * @param {number} [options.maxAgeMinutes] - Max age for stale traces (default: 60)
+ * @param {boolean} [options.dryRun] - If true, report but don't delete
+ * @returns {{ sessionsKilled: string[], tracesRemoved: string[], errors: string[] }}
+ */
+function cleanupOrphanSessions(rootDir, options) {
+  const maxAge = (options && options.maxAgeMinutes) || MAX_AGE_MINUTES;
+  const dryRun = (options && options.dryRun) || false;
+
+  const result = {
+    sessionsKilled: [],
+    tracesRemoved: [],
+    errors: [],
+  };
+
+  // 1. Find and kill orphaned tmux sessions
+  const orphanedSessions = findOrphanedTmuxSessions();
+  for (const session of orphanedSessions) {
+    // Extract trace ID from session name: audit-{type}-{traceId}
+    const parts = session.split('-');
+    if (parts.length < 3) continue; // Malformed session name, skip
+    const traceId = parts.slice(2).join('-');
+
+    if (dryRun) {
+      result.sessionsKilled.push(`${session} (dry-run)`);
+      continue;
+    }
+
+    if (killTmuxSession(session)) {
+      result.sessionsKilled.push(session);
+    } else {
+      result.errors.push(`Failed to kill session: ${session}`);
+    }
+  }
+
+  // 2. Clean up stale sentinel directories
+  const traces = findTraceDirectories(rootDir);
+  for (const trace of traces) {
+    if (isStaleTrace(trace, maxAge) && isIncompleteTrace(trace)) {
+      if (dryRun) {
+        result.tracesRemoved.push(`${trace.traceId} (dry-run)`);
+        continue;
+      }
+
+      if (removeSentinelDir(trace.dir)) {
+        result.tracesRemoved.push(trace.traceId);
+      } else {
+        result.errors.push(`Failed to remove trace dir: ${trace.traceId}`);
+      }
+    }
+  }
+
+  return result;
+}
+
+// CLI
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  let maxAge = MAX_AGE_MINUTES;
+  let dryRun = false;
+
+  for (const arg of args) {
+    if (arg.startsWith('--max-age=')) {
+      const parsed = parseInt(arg.split('=')[1], 10);
+      maxAge = isNaN(parsed) ? MAX_AGE_MINUTES : parsed;
+    }
+    if (arg === '--dry-run') dryRun = true;
+  }
+
+  const rootDir = process.cwd();
+  const result = cleanupOrphanSessions(rootDir, { maxAgeMinutes: maxAge, dryRun });
+
+  if (result.sessionsKilled.length > 0) {
+    console.log(`Killed ${result.sessionsKilled.length} orphaned session(s):`);
+    result.sessionsKilled.forEach(s => console.log(`  - ${s}`));
+  }
+
+  if (result.tracesRemoved.length > 0) {
+    console.log(`Removed ${result.tracesRemoved.length} stale trace(s):`);
+    result.tracesRemoved.forEach(t => console.log(`  - ${t}`));
+  }
+
+  if (result.errors.length > 0) {
+    console.error(`${result.errors.length} error(s):`);
+    result.errors.forEach(e => console.error(`  - ${e}`));
+  }
+
+  if (result.sessionsKilled.length === 0 && result.tracesRemoved.length === 0) {
+    console.log('No orphaned sessions or stale traces found.');
+  }
+}
+
+module.exports = {
+  findTraceDirectories,
+  isStaleTrace,
+  isIncompleteTrace,
+  findOrphanedTmuxSessions,
+  killTmuxSession,
+  removeSentinelDir,
+  cleanupOrphanSessions,
+};

package/scripts/lib/audit-registry.js

@@ -0,0 +1,248 @@
+/**
+ * audit-registry.js - Static registry mapping audit types to analyzers
+ *
+ * Centralizes the mapping of 6 audit commands to their analyzer agents,
+ * consensus coordinators, and depth configurations. Previously this info
+ * was duplicated across 6 .md command files.
+ *
+ * Usage:
+ *   const { getAuditType, getAnalyzersForAudit } = require('./audit-registry');
+ *   const security = getAuditType('security');
+ *   const focused = getAnalyzersForAudit('security', 'deep', ['injection', 'auth']);
+ */
+
+/**
+ * Complete audit type registry.
+ * Each entry defines: name, short prefix for tmux, color for tab groups,
+ * all analyzers with their subagent_type, which are quick vs deep,
+ * and the consensus coordinator.
+ */
+const AUDIT_TYPES = {
+  logic: {
+    name: 'Logic Analysis',
+    prefix: 'Logic',
+    color: '#7aa2f7', // sky
+    command: 'code/logic',
+    analyzers: {
+      edge: { subagent_type: 'logic-analyzer-edge', label: 'Edge Cases' },
+      invariant: { subagent_type: 'logic-analyzer-invariant', label: 'Invariants' },
+      flow: { subagent_type: 'logic-analyzer-flow', label: 'Control Flow' },
+      type: { subagent_type: 'logic-analyzer-type', label: 'Type Safety' },
+      race: { subagent_type: 'logic-analyzer-race', label: 'Race Conditions' },
+    },
+    consensus: { subagent_type: 'logic-consensus', label: 'Logic Consensus' },
+    quick_analyzers: ['edge', 'invariant', 'flow', 'type', 'race'],
+    deep_analyzers: ['edge', 'invariant', 'flow', 'type', 'race'],
+  },
+
+  security: {
+    name: 'Security Vulnerability',
+    prefix: 'Sec',
+    color: '#f7768e', // coral
+    command: 'code/security',
+    analyzers: {
+      injection: { subagent_type: 'security-analyzer-injection', label: 'Injection' },
+      auth: { subagent_type: 'security-analyzer-auth', label: 'Authentication' },
+      authz: { subagent_type: 'security-analyzer-authz', label: 'Authorization' },
+      secrets: { subagent_type: 'security-analyzer-secrets', label: 'Secrets' },
+      input: { subagent_type: 'security-analyzer-input', label: 'Input Validation' },
+      deps: { subagent_type: 'security-analyzer-deps', label: 'Dependencies' },
+      infra: { subagent_type: 'security-analyzer-infra', label: 'Infrastructure' },
+      api: { subagent_type: 'security-analyzer-api', label: 'API Security' },
+    },
+    consensus: { subagent_type: 'security-consensus', label: 'Security Consensus' },
+    quick_analyzers: ['injection', 'auth', 'authz', 'secrets', 'input'],
+    deep_analyzers: ['injection', 'auth', 'authz', 'secrets', 'input', 'deps', 'infra', 'api'],
+  },
+
+  performance: {
+    name: 'Performance Bottleneck',
+    prefix: 'Perf',
+    color: '#73daca', // mint
+    command: 'code/performance',
+    analyzers: {
+      queries: { subagent_type: 'perf-analyzer-queries', label: 'Queries' },
+      rendering: { subagent_type: 'perf-analyzer-rendering', label: 'Rendering' },
+      memory: { subagent_type: 'perf-analyzer-memory', label: 'Memory' },
+      bundle: { subagent_type: 'perf-analyzer-bundle', label: 'Bundle Size' },
+      compute: { subagent_type: 'perf-analyzer-compute', label: 'Compute' },
+      network: { subagent_type: 'perf-analyzer-network', label: 'Network' },
+      caching: { subagent_type: 'perf-analyzer-caching', label: 'Caching' },
+      assets: { subagent_type: 'perf-analyzer-assets', label: 'Assets' },
+    },
+    consensus: { subagent_type: 'perf-consensus', label: 'Performance Consensus' },
+    quick_analyzers: ['queries', 'rendering', 'memory', 'bundle', 'compute'],
+    deep_analyzers: [
+      'queries',
+      'rendering',
+      'memory',
+      'bundle',
+      'compute',
+      'network',
+      'caching',
+      'assets',
+    ],
+  },
+
+  test: {
+    name: 'Test Quality',
+    prefix: 'Test',
+    color: '#e0af68', // amber
+    command: 'code/test',
+    analyzers: {
+      coverage: { subagent_type: 'test-analyzer-coverage', label: 'Coverage' },
+      fragility: { subagent_type: 'test-analyzer-fragility', label: 'Fragility' },
+      mocking: { subagent_type: 'test-analyzer-mocking', label: 'Mocking' },
+      assertions: { subagent_type: 'test-analyzer-assertions', label: 'Assertions' },
+      structure: { subagent_type: 'test-analyzer-structure', label: 'Structure' },
+      integration: { subagent_type: 'test-analyzer-integration', label: 'Integration' },
+      maintenance: { subagent_type: 'test-analyzer-maintenance', label: 'Maintenance' },
+      patterns: { subagent_type: 'test-analyzer-patterns', label: 'Anti-Patterns' },
+    },
+    consensus: { subagent_type: 'test-consensus', label: 'Test Consensus' },
+    quick_analyzers: ['coverage', 'fragility', 'mocking', 'assertions', 'structure'],
+    deep_analyzers: [
+      'coverage',
+      'fragility',
+      'mocking',
+      'assertions',
+      'structure',
+      'integration',
+      'maintenance',
+      'patterns',
+    ],
+  },
+
+  completeness: {
+    name: 'Completeness',
+    prefix: 'Comp',
+    color: '#bb9af7', // violet
+    command: 'code/completeness',
+    analyzers: {
+      handlers: { subagent_type: 'completeness-analyzer-handlers', label: 'Handlers' },
+      routes: { subagent_type: 'completeness-analyzer-routes', label: 'Routes' },
+      api: { subagent_type: 'completeness-analyzer-api', label: 'API Endpoints' },
+      stubs: { subagent_type: 'completeness-analyzer-stubs', label: 'Stubs' },
+      state: { subagent_type: 'completeness-analyzer-state', label: 'State' },
+      imports: { subagent_type: 'completeness-analyzer-imports', label: 'Imports' },
+      conditional: { subagent_type: 'completeness-analyzer-conditional', label: 'Conditionals' },
+    },
+    consensus: { subagent_type: 'completeness-consensus', label: 'Completeness Consensus' },
+    quick_analyzers: ['handlers', 'routes', 'api', 'stubs', 'state'],
+    deep_analyzers: ['handlers', 'routes', 'api', 'stubs', 'state', 'imports', 'conditional'],
+  },
+
+  legal: {
+    name: 'Legal Risk',
+    prefix: 'Legal',
+    color: '#9ece6a', // lime
+    command: 'code/legal',
+    analyzers: {
+      privacy: { subagent_type: 'legal-analyzer-privacy', label: 'Privacy' },
+      terms: { subagent_type: 'legal-analyzer-terms', label: 'Terms' },
+      a11y: { subagent_type: 'legal-analyzer-a11y', label: 'Accessibility' },
+      licensing: { subagent_type: 'legal-analyzer-licensing', label: 'Licensing' },
+      consumer: { subagent_type: 'legal-analyzer-consumer', label: 'Consumer' },
+      security: { subagent_type: 'legal-analyzer-security', label: 'Security' },
+      ai: { subagent_type: 'legal-analyzer-ai', label: 'AI Compliance' },
+      content: { subagent_type: 'legal-analyzer-content', label: 'Content' },
+      international: { subagent_type: 'legal-analyzer-international', label: 'International' },
+    },
+    consensus: { subagent_type: 'legal-consensus', label: 'Legal Consensus' },
+    quick_analyzers: ['privacy', 'terms', 'a11y', 'licensing', 'consumer'],
+    deep_analyzers: [
+      'privacy',
+      'terms',
+      'a11y',
+      'licensing',
+      'consumer',
+      'security',
+      'ai',
+      'content',
+      'international',
+    ],
+  },
+};
+
+/**
+ * Get audit type configuration.
+ *
+ * @param {string} type - Audit type key (logic, security, performance, test, completeness, legal)
+ * @returns {object|null} Audit type config or null if invalid
+ */
+function getAuditType(type) {
+  return AUDIT_TYPES[type] || null;
+}
+
+/**
+ * Get all valid audit type keys.
+ *
+ * @returns {string[]} Array of audit type keys
+ */
+function getAuditTypeKeys() {
+  return Object.keys(AUDIT_TYPES);
+}
+
+/**
+ * Get analyzers for a given audit type, depth, and focus.
+ *
+ * @param {string} type - Audit type key
+ * @param {string} [depth='quick'] - 'quick', 'deep', or 'ultradeep'
+ * @param {string[]} [focus] - Array of focus areas, or null/['all'] for all
+ * @returns {{ analyzers: Array<{ key: string, subagent_type: string, label: string }>, consensus: object }|null}
+ */
+function getAnalyzersForAudit(type, depth, focus) {
+  const audit = AUDIT_TYPES[type];
+  if (!audit) return null;
+
+  const effectiveDepth = depth === 'ultradeep' ? 'deep' : depth || 'quick';
+  const analyzerKeys = effectiveDepth === 'deep' ? audit.deep_analyzers : audit.quick_analyzers;
+
+  // Filter by focus if specified
+  let selectedKeys = analyzerKeys;
+  if (focus && focus.length > 0 && !focus.includes('all')) {
+    selectedKeys = analyzerKeys.filter(key => focus.includes(key));
+    // If focus specifies keys not in current depth, include them anyway
+    for (const f of focus) {
+      if (audit.analyzers[f] && !selectedKeys.includes(f)) {
+        selectedKeys.push(f);
+      }
+    }
+  }
+
+  const analyzers = selectedKeys.map(key => ({
+    key,
+    subagent_type: audit.analyzers[key].subagent_type,
+    label: audit.analyzers[key].label,
+  }));
+
+  return {
+    analyzers,
+    consensus: audit.consensus,
+  };
+}
+
+/**
+ * Get analyzer count for a given audit type at each depth.
+ *
+ * @param {string} type - Audit type key
+ * @returns {{ quick: number, deep: number, total: number }|null}
+ */
+function getAnalyzerCounts(type) {
+  const audit = AUDIT_TYPES[type];
+  if (!audit) return null;
+
+  return {
+    quick: audit.quick_analyzers.length,
+    deep: audit.deep_analyzers.length,
+    total: Object.keys(audit.analyzers).length,
+  };
+}
+
+module.exports = {
+  AUDIT_TYPES,
+  getAuditType,
+  getAuditTypeKeys,
+  getAnalyzersForAudit,
+  getAnalyzerCounts,
+};

package/scripts/lib/feature-catalog.js

@@ -116,7 +116,7 @@ const FEATURE_CATALOG = [
     feature: 'discovery',
     name: 'Discovery',
     description: 'Brainstorm, research, and synthesize findings into a Product Brief',
-    how_to_use: '/agileflow:discovery:new "<topic>"',
+    how_to_use: '/agileflow:ideate:discover "<topic>"',
     category: 'workflow',
     detector: null,
     auto_mode: null,
@@ -168,7 +168,7 @@ const FEATURE_CATALOG = [
     feature: 'logic-audit',
     name: 'Logic Audit',
     description: 'Multi-agent analysis for edge cases, race conditions, type bugs, and dead code',
-    how_to_use: '/agileflow:audit:logic',
+    how_to_use: '/agileflow:code:logic',
     category: 'analysis',
     detector: null,
     auto_mode: null,
@@ -179,7 +179,7 @@ const FEATURE_CATALOG = [
     name: 'Completeness Audit',
     description:
       'Multi-agent analysis for forgotten features, dead handlers, stub code, and incomplete implementations',
-    how_to_use: '/agileflow:audit:completeness',
+    how_to_use: '/agileflow:code:completeness',
     category: 'analysis',
     detector: null,
     auto_mode: null,