agileflow 2.90.6 → 2.91.0

package/lib/validate-names.js

@@ -29,9 +29,9 @@ const PATTERNS = {
   // Examples: default, my-profile, dev_config
   profileName: /^[a-zA-Z][a-zA-Z0-9_-]*$/,
 
-  // Command name: alphanumeric with hyphens/colons, starts with letter
-  // Examples: babysit, story:list, agileflow:configure
-  commandName: /^[a-zA-Z][a-zA-Z0-9:-]*$/,
+  // Command name: alphanumeric with hyphens/colons/slashes, starts with letter
+  // Examples: babysit, story:list, agileflow:configure, research/ask
+  commandName: /^[a-zA-Z][a-zA-Z0-9:/-]*$/,
 
   // Session nickname: alphanumeric with hyphens/underscores
   // Examples: auth-work, feature_1, main

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "2.90.6",
+  "version": "2.91.0",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",
@@ -53,7 +53,10 @@
     "test:coverage": "jest --coverage"
   },
   "dependencies": {
+    "blessed": "^0.1.81",
+    "blessed-contrib": "^4.11.0",
     "chalk": "^4.1.2",
+    "chokidar": "^4.0.3",
     "commander": "^12.1.0",
     "fs-extra": "^11.2.0",
     "ink": "^3.2.0",

package/scripts/obtain-context.js

@@ -21,14 +21,21 @@
  * - File overlaps: Only load if parallel sessions are active
  * - Configurable via features.lazyContext in agileflow-metadata.json
  *
+ * QUERY MODE (US-0127):
+ * - When QUERY=<pattern> provided, uses codebase index for targeted search
+ * - Falls back to full context if query returns empty
+ * - Based on RLM pattern: programmatic search instead of loading everything
+ *
  * Usage:
  *   node scripts/obtain-context.js              # Just gather context
  *   node scripts/obtain-context.js babysit      # Gather + register 'babysit'
+ *   node scripts/obtain-context.js babysit QUERY="auth files"  # Query mode
  */
 
 const fs = require('fs');
 const fsPromises = require('fs').promises;
 const path = require('path');
+const os = require('os');
 const { execSync } = require('child_process');
 const { c: C, box } = require('../lib/colors');
 const { isValidCommandName } = require('../lib/validate');
@@ -77,6 +84,11 @@ function parseCommandArgs(args) {
     activeSections.push('visual-e2e');
   }
 
+  // Query mode: QUERY=<pattern> triggers targeted codebase search (US-0127)
+  if (params.QUERY) {
+    activeSections.push('query-mode');
+  }
+
   // Check for multi-session environment
   const registryPath = '.agileflow/sessions/registry.json';
   if (fs.existsSync(registryPath)) {
@@ -99,6 +111,40 @@ const commandName = process.argv[2];
 const commandArgs = process.argv.slice(3);
 const { activeSections, params: commandParams } = parseCommandArgs(commandArgs);
 
+// Helper to extract command type from frontmatter
+function getCommandType(cmdName) {
+  // Handle nested command paths like "research/ask" -> "research/ask.md"
+  // The command name may contain "/" for nested commands
+  const cmdPath = cmdName.includes('/')
+    ? `${cmdName.substring(0, cmdName.lastIndexOf('/'))}/${cmdName.substring(cmdName.lastIndexOf('/') + 1)}.md`
+    : `${cmdName}.md`;
+
+  // Try to find the command file and read its frontmatter type
+  const possiblePaths = [
+    `packages/cli/src/core/commands/${cmdPath}`,
+    `.agileflow/commands/${cmdPath}`,
+    `.claude/commands/agileflow/${cmdPath}`,
+    // Also try flat path for legacy commands
+    `packages/cli/src/core/commands/${cmdName.replace(/\//g, '-')}.md`,
+  ];
+
+  for (const searchPath of possiblePaths) {
+    if (fs.existsSync(searchPath)) {
+      try {
+        const content = fs.readFileSync(searchPath, 'utf8');
+        // Extract type from YAML frontmatter
+        const match = content.match(/^---\n[\s\S]*?type:\s*(\S+)/m);
+        if (match) {
+          return match[1].replace(/['"]/g, ''); // Remove quotes if any
+        }
+      } catch {
+        // Continue to next path
+      }
+    }
+  }
+  return 'interactive'; // Default to interactive
+}
+
 // Register command for PreCompact context preservation
 if (commandName && isValidCommandName(commandName)) {
   const sessionStatePath = 'docs/09-agents/session-state.json';
@@ -114,9 +160,13 @@ if (commandName && isValidCommandName(commandName)) {
       // Remove any existing entry for this command (avoid duplicates)
       state.active_commands = state.active_commands.filter(c => c.name !== commandName);
 
+      // Get command type from frontmatter (output-only vs interactive)
+      const commandType = getCommandType(commandName);
+
       // Add the new command with active sections for progressive disclosure
       state.active_commands.push({
         name: commandName,
+        type: commandType, // Used by PreCompact to skip output-only commands
         activated_at: new Date().toISOString(),
         state: {},
         active_sections: activeSections,
@@ -165,6 +215,121 @@ function safeExec(cmd) {
   }
 }
 
+// =============================================================================
+// Context Budget Tracking (GSD Integration)
+// =============================================================================
+
+/**
+ * Get current context usage percentage from Claude's session files.
+ * Reads token counts from the active session JSONL file.
+ *
+ * @returns {{ percent: number, tokens: number, max: number } | null}
+ */
+function getContextPercentage() {
+  try {
+    const homeDir = os.homedir();
+    const cwd = process.cwd();
+
+    // Convert current dir to Claude's session file path format
+    // e.g., /home/coder/AgileFlow -> home-coder-AgileFlow
+    const projectDir = cwd.replace(homeDir, '~').replace('~', homeDir).replace(/\//g, '-').replace(/^-/, '');
+    const sessionDir = path.join(homeDir, '.claude', 'projects', `-${projectDir}`);
+
+    if (!fs.existsSync(sessionDir)) {
+      return null;
+    }
+
+    // Find most recent .jsonl session file
+    const files = fs.readdirSync(sessionDir)
+      .filter(f => f.endsWith('.jsonl'))
+      .map(f => ({
+        name: f,
+        mtime: fs.statSync(path.join(sessionDir, f)).mtime.getTime(),
+      }))
+      .sort((a, b) => b.mtime - a.mtime);
+
+    if (files.length === 0) {
+      return null;
+    }
+
+    const sessionFile = path.join(sessionDir, files[0].name);
+    const content = fs.readFileSync(sessionFile, 'utf8');
+    const lines = content.trim().split('\n').slice(-20); // Last 20 lines
+
+    // Find latest usage entry
+    let latestTokens = 0;
+    for (const line of lines.reverse()) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry?.message?.usage) {
+          const usage = entry.message.usage;
+          latestTokens = (usage.input_tokens || 0) + (usage.cache_read_input_tokens || 0);
+          if (latestTokens > 0) break;
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    if (latestTokens === 0) {
+      return null;
+    }
+
+    // Default to 200K context for modern Claude models
+    const maxContext = 200000;
+    const percent = Math.min(100, Math.round((latestTokens * 100) / maxContext));
+
+    return { percent, tokens: latestTokens, max: maxContext };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate context budget warning box if usage exceeds threshold.
+ * Based on GSD research: 50% is where quality starts degrading.
+ *
+ * @param {number} percent - Context usage percentage
+ * @returns {string} Warning box or empty string
+ */
+function generateContextWarning(percent) {
+  if (percent < 50) {
+    return ''; // No warning needed
+  }
+
+  const width = 60;
+  const topLine = `┏${'━'.repeat(width - 2)}┓`;
+  const bottomLine = `┗${'━'.repeat(width - 2)}┛`;
+
+  let color, icon, message, suggestion;
+
+  if (percent >= 70) {
+    // Critical: Dumb Zone
+    color = C.coral;
+    icon = '🔴';
+    message = `Context usage: ${percent}% (in degradation zone)`;
+    suggestion = 'Strongly recommend: compact conversation or delegate to sub-agent';
+  } else {
+    // Warning: Approaching limit (50-69%)
+    color = C.amber;
+    icon = '⚠️';
+    message = `Context usage: ${percent}% (approaching 50% threshold)`;
+    suggestion = 'Consider: delegate to sub-agent or compact conversation';
+  }
+
+  // Pad messages to fit width
+  const msgPadded = ` ${icon} ${message}`.padEnd(width - 3) + '┃';
+  const sugPadded = ` → ${suggestion}`.padEnd(width - 3) + '┃';
+
+  return [
+    `${color}${C.bold}${topLine}${C.reset}`,
+    `${color}${C.bold}┃${msgPadded}${C.reset}`,
+    `${color}${C.bold}┃${sugPadded}${C.reset}`,
+    `${color}${C.bold}${bottomLine}${C.reset}`,
+    '',
+  ].join('\n');
+}
+
 // =============================================================================
 // Lazy Evaluation Configuration (US-0093)
 // =============================================================================
@@ -679,6 +844,13 @@ function generateFullContent(prefetched = null) {
     content += `${C.dim}Balance: Use at natural pause points. Don't ask permission for routine work.${C.reset}\n\n`;
   }
 
+  // 0.6 CONTEXT BUDGET WARNING (GSD Integration)
+  // Show warning when context usage approaches 50% threshold
+  const contextUsage = getContextPercentage();
+  if (contextUsage && contextUsage.percent >= 50) {
+    content += generateContextWarning(contextUsage.percent);
+  }
+
   // 0. PROGRESSIVE DISCLOSURE (section activation)
   if (activeSections.length > 0) {
     content += `\n${C.cyan}${C.bold}═══ 📖 Progressive Disclosure: Active Sections ═══${C.reset}\n`;
@@ -1081,6 +1253,54 @@ function generateFullContent(prefetched = null) {
   return content;
 }
 
+// ============================================
+// QUERY MODE: Targeted codebase search (US-0127)
+// ============================================
+
+/**
+ * Execute query mode using codebase index for targeted search.
+ * Falls back to full context if query returns no results.
+ *
+ * @param {string} query - Natural language or pattern query
+ * @returns {Object|null} Query results or null to fall back to full context
+ */
+function executeQueryMode(query) {
+  const queryScript = path.join(__dirname, 'query-codebase.js');
+
+  // Check if query script exists
+  if (!fs.existsSync(queryScript)) {
+    console.error('Query mode unavailable: query-codebase.js not found');
+    return null; // Fall back to full context
+  }
+
+  try {
+    // Execute query and capture output
+    const result = execSync(`node "${queryScript}" --query="${query}" --budget=15000`, {
+      encoding: 'utf8',
+      maxBuffer: 50 * 1024 * 1024, // 50MB buffer
+    });
+
+    // Check if we got results
+    if (result.includes('No files found') || result.trim() === '') {
+      return null; // Fall back to full context
+    }
+
+    return {
+      mode: 'query',
+      query: query,
+      results: result.trim(),
+    };
+  } catch (err) {
+    // Exit code 2 = no results, fall back to full context
+    if (err.status === 2) {
+      return null;
+    }
+    // Exit code 1 = error, report but fall back
+    console.error(`Query error: ${err.message}`);
+    return null;
+  }
+}
+
 // ============================================
 // MAIN: Output with smart summary positioning
 // ============================================
@@ -1089,6 +1309,24 @@ function generateFullContent(prefetched = null) {
  * Main execution function using parallel pre-fetching for optimal performance.
  */
 async function main() {
+  // Check for query mode first (US-0127)
+  if (activeSections.includes('query-mode') && commandParams.QUERY) {
+    const queryResult = executeQueryMode(commandParams.QUERY);
+
+    if (queryResult) {
+      // Output query results instead of full context
+      console.log(`=== QUERY MODE ===`);
+      console.log(`Query: "${queryResult.query}"`);
+      console.log(`---`);
+      console.log(queryResult.results);
+      console.log(`---`);
+      console.log(`[Query mode: targeted search. Run without QUERY= for full context]`);
+      return;
+    }
+    // Fall through to full context if query returned no results
+    console.log(`[Query "${commandParams.QUERY}" returned no results, loading full context...]`);
+  }
+
   // Check for multi-session environment before prefetching
   const registryPath = '.agileflow/sessions/registry.json';
   let isMultiSession = false;

package/scripts/precompact-context.sh

@@ -42,11 +42,23 @@ if [ -d "docs/05-epics" ]; then
 fi
 
 # Detect active commands and extract their Compact Summaries
+# IMPORTANT: Skip "output-only" commands like research:ask, research:list, research:view
+# These commands generate output for the user to copy - they're not ongoing tasks.
+# If we include them in PreCompact, Claude will try to re-execute them after compact.
 COMMAND_SUMMARIES=""
 if [ -f "docs/09-agents/session-state.json" ]; then
+  # Output-only commands that should NOT be preserved during compact
+  # These commands generate output once and are done - no ongoing state
+  # Note: Commands with type: output-only in frontmatter are also filtered
+  OUTPUT_ONLY_COMMANDS="research/ask research/list research/view help metrics board"
+
   ACTIVE_COMMANDS=$(node -p "
     const s = require('./docs/09-agents/session-state.json');
-    (s.active_commands || []).map(c => c.name).join(' ');
+    const outputOnly = '$OUTPUT_ONLY_COMMANDS'.split(' ');
+    (s.active_commands || [])
+      .filter(c => !outputOnly.includes(c.name) && c.type !== 'output-only')
+      .map(c => c.name)
+      .join(' ');
   " 2>/dev/null || echo "")
 
   for ACTIVE_COMMAND in $ACTIVE_COMMANDS; do