agileflow 3.0.2 → 3.2.0

package/scripts/lib/context-loader.js

@@ -682,6 +682,7 @@ async function prefetchAllData(options = {}) {
     sessionClaims: true,
     fileOverlaps: true,
   };
+  const verbosityMode = options.verbosityMode || 'full';
 
   // Define all files to read
   const jsonFiles = {
@@ -690,20 +691,31 @@ async function prefetchAllData(options = {}) {
     sessionState: 'docs/09-agents/session-state.json',
   };
 
-  const textFiles = {
-    busLog: 'docs/09-agents/bus/log.jsonl',
-    claudeMd: 'CLAUDE.md',
-    readmeMd: 'README.md',
-    archReadme: 'docs/04-architecture/README.md',
-    practicesReadme: 'docs/02-practices/README.md',
-    roadmap: 'docs/08-project/roadmap.md',
-  };
-
-  const directories = {
-    docs: 'docs',
-    research: 'docs/10-research',
-    epics: 'docs/05-epics',
-  };
+  // Text files: skip heavy content in lite/minimal modes
+  const textFiles = {};
+  if (verbosityMode === 'full') {
+    textFiles.busLog = 'docs/09-agents/bus/log.jsonl';
+    textFiles.claudeMd = 'CLAUDE.md';
+    textFiles.readmeMd = 'README.md';
+    textFiles.archReadme = 'docs/04-architecture/README.md';
+    textFiles.practicesReadme = 'docs/02-practices/README.md';
+    textFiles.roadmap = 'docs/08-project/roadmap.md';
+  } else if (verbosityMode === 'lite') {
+    textFiles.busLog = 'docs/09-agents/bus/log.jsonl';
+    // Skip: claudeMd, readmeMd, archReadme, practicesReadme, roadmap
+  }
+  // minimal: skip all text files
+
+  // Directories: skip in minimal mode
+  const directories = {};
+  if (verbosityMode !== 'minimal') {
+    directories.docs = 'docs';
+    directories.research = 'docs/10-research';
+    directories.epics = 'docs/05-epics';
+  } else {
+    // minimal still needs epics dir for count
+    directories.epics = 'docs/05-epics';
+  }
 
   // Git commands to run in parallel
   const gitCommands = {
@@ -750,7 +762,7 @@ async function prefetchAllData(options = {}) {
   const git = Object.fromEntries(gitResults);
 
   // Determine most recent research file
-  const researchFiles = dirs.research
+  const researchFiles = (dirs.research || [])
     .filter(f => f.endsWith('.md') && f !== 'README.md')
     .sort()
     .reverse();

package/scripts/lib/damage-control-utils.js

@@ -393,6 +393,7 @@ function parseBashPatterns(content) {
     bashToolPatterns: 'patterns',
     askPatterns: 'patterns',
     agileflowProtections: 'patterns',
+    releaseProtections: 'patterns',
   });
 }
 
@@ -483,7 +484,12 @@ function createPathHook(operation) {
 function createBashHook() {
   return function runHook() {
     const projectRoot = findProjectRoot();
-    const defaultConfig = { bashToolPatterns: [], askPatterns: [], agileflowProtections: [] };
+    const defaultConfig = {
+      bashToolPatterns: [],
+      askPatterns: [],
+      agileflowProtections: [],
+      releaseProtections: [],
+    };
 
     /**
      * Test command against a single pattern rule
@@ -514,6 +520,7 @@ function createBashHook() {
       const allPatterns = [
         ...(config.bashToolPatterns || []),
         ...(config.agileflowProtections || []),
+        ...(config.releaseProtections || []),
       ];
 
       for (const rule of allPatterns) {

package/scripts/lib/feature-catalog.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+/**
+ * feature-catalog.js
+ *
+ * Static catalog of all major AgileFlow features with descriptions,
+ * usage hints, and dynamic status computation.
+ *
+ * Solves the "invisible features" problem: when smart-detect detectors
+ * don't trigger, features vanish from the AI's context. This catalog
+ * ensures the AI always knows what's available.
+ *
+ * Usage:
+ *   const { FEATURE_CATALOG, buildCatalogWithStatus } = require('./feature-catalog');
+ *   const catalog = buildCatalogWithStatus(signals, recommendations, autoEnabled, metadata);
+ */
+
+'use strict';
+
+// =============================================================================
+// Static Feature Catalog
+// =============================================================================
+
+/**
+ * All major AgileFlow features organized by category.
+ *
+ * Fields:
+ *   feature     - Unique key (matches detector/command names)
+ *   name        - Human-readable display name
+ *   description - What it does (1 sentence)
+ *   how_to_use  - Command or trigger hint
+ *   category    - Grouping: modes | collaboration | workflow | analysis | automation
+ *   detector    - Name of signal detector that triggers this (null if none)
+ *   auto_mode   - Key in auto_enabled that maps to this feature (null if none)
+ *   prerequisites - Lightweight prereq checks as { signal_path, description } or null
+ */
+const FEATURE_CATALOG = [
+  // --- modes ---
+  {
+    feature: 'loop-mode',
+    name: 'Loop Mode',
+    description: 'Auto-claim and implement multiple stories in sequence without pausing',
+    how_to_use: '3+ ready stories in same epic + test setup',
+    category: 'modes',
+    detector: null,
+    auto_mode: 'loop_mode',
+    prerequisites: [
+      { signal_path: 'story.epic', description: 'Active story with epic' },
+      { signal_path: 'tests.hasTestSetup', description: 'Test setup configured' },
+    ],
+  },
+  {
+    feature: 'coverage-mode',
+    name: 'Coverage Mode',
+    description: 'Track and enforce code coverage thresholds during implementation',
+    how_to_use: 'Coverage data in coverage/coverage-summary.json',
+    category: 'modes',
+    detector: null,
+    auto_mode: 'coverage_mode',
+    prerequisites: [{ signal_path: 'files.coverage', description: 'Coverage summary exists' }],
+  },
+
+  // --- collaboration ---
+  {
+    feature: 'agent-teams',
+    name: 'Agent Teams',
+    description: 'Coordinate multiple specialized agents working in parallel on complex tasks',
+    how_to_use: '/agileflow:team:start <template>',
+    category: 'collaboration',
+    detector: null,
+    auto_mode: null,
+    prerequisites: null,
+  },
+  {
+    feature: 'council',
+    name: 'AI Council',
+    description: 'Three-perspective decision making: Optimist, Advocate, and Analyst',
+    how_to_use: '/agileflow:council "<decision>"',
+    category: 'collaboration',
+    detector: null,
+    auto_mode: null,
+    prerequisites: null,
+  },
+  {
+    feature: 'multi-expert',
+    name: 'Multi-Expert',
+    description: 'Deploy 3-5 domain experts on the same problem and synthesize results',
+    how_to_use: '/agileflow:multi-expert "<question>"',
+    category: 'collaboration',
+    detector: null,
+    auto_mode: null,
+    prerequisites: null,
+  },
+  {
+    feature: 'sessions',
+    name: 'Parallel Sessions',
+    description: 'Run multiple Claude instances in git worktrees for parallel development',
+    how_to_use: '/agileflow:session:new <name>',
+    category: 'collaboration',
+    detector: null,
+    auto_mode: null,
+    prerequisites: null,
+  },
+
+  // --- workflow ---
+  {
+    feature: 'rpi',
+    name: 'RPI Workflow',
+    description: 'Structured Research-Plan-Implement cycle with phase gates',
+    how_to_use: '/agileflow:rpi "<feature>"',
+    category: 'workflow',
+    detector: null,
+    auto_mode: null,
+    prerequisites: null,
+  },
+  {
+    feature: 'discovery',
+    name: 'Discovery',
+    description: 'Brainstorm, research, and synthesize findings into a Product Brief',
+    how_to_use: '/agileflow:discovery:new "<topic>"',
+    category: 'workflow',
+    detector: null,
+    auto_mode: null,
+    prerequisites: null,
+  },
+  {
+    feature: 'batch',
+    name: 'Batch Processing',
+    description: 'Process multiple items with map/pmap/filter patterns',
+    how_to_use: '/agileflow:batch <pattern> <items>',
+    category: 'workflow',
+    detector: null,
+    auto_mode: null,
+    prerequisites: null,
+  },
+  {
+    feature: 'sprint',
+    name: 'Sprint Planning',
+    description: 'Data-driven sprint planning with velocity forecasting',
+    how_to_use: '/agileflow:sprint',
+    category: 'workflow',
+    detector: null,
+    auto_mode: null,
+    prerequisites: [{ signal_path: 'storyCount', description: 'Stories exist in status.json' }],
+  },
+
+  // --- analysis ---
+  {
+    feature: 'research',
+    name: 'Research',
+    description: 'Generate research prompts, save notes, and maintain a research index',
+    how_to_use: '/agileflow:research:ask "<question>"',
+    category: 'analysis',
+    detector: null,
+    auto_mode: null,
+    prerequisites: null,
+  },
+  {
+    feature: 'impact-analysis',
+    name: 'Impact Analysis',
+    description: 'Analyze change impact across the codebase before making modifications',
+    how_to_use: '/agileflow:impact "<change>"',
+    category: 'analysis',
+    detector: 'impact',
+    auto_mode: null,
+    prerequisites: null,
+  },
+  {
+    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',
+    category: 'analysis',
+    detector: null,
+    auto_mode: null,
+    prerequisites: null,
+  },
+  {
+    feature: 'diagnose',
+    name: 'Diagnose',
+    description: 'System health diagnostics for hooks, config, and runtime issues',
+    how_to_use: '/agileflow:diagnose',
+    category: 'analysis',
+    detector: null,
+    auto_mode: null,
+    prerequisites: null,
+  },
+
+  // --- testing ---
+  {
+    feature: 'browser-qa',
+    name: 'UI Testing (Bowser)',
+    description:
+      'Agentic browser testing + visual verification during development. Playwright-based screenshot evidence and workflow validation.',
+    how_to_use: '/agileflow:browser-qa SCENARIO=<spec.yaml> or VISUAL=true on babysit',
+    category: 'testing',
+    detector: null,
+    auto_mode: 'browser_qa_mode',
+    prerequisites: [{ signal_path: 'files.playwright', description: 'Playwright config exists' }],
+  },
+
+  // --- automation ---
+  {
+    feature: 'ideation',
+    name: 'Ideation',
+    description: 'Generate categorized improvement ideas using multi-expert analysis',
+    how_to_use: '/agileflow:ideate:new',
+    category: 'automation',
+    detector: null,
+    auto_mode: null,
+    prerequisites: null,
+  },
+];
+
+// Valid categories for validation
+const VALID_CATEGORIES = [
+  'modes',
+  'collaboration',
+  'workflow',
+  'analysis',
+  'testing',
+  'automation',
+];
+
+// Valid statuses
+const VALID_STATUSES = ['triggered', 'available', 'unavailable', 'disabled'];
+
+// =============================================================================
+// Status Computation
+// =============================================================================
+
+/**
+ * Resolve a dot-path signal (e.g. 'story.epic') against the signals object.
+ * Returns the value at that path, or undefined if any segment is missing.
+ */
+function resolveSignalPath(signals, dotPath) {
+  const parts = dotPath.split('.');
+  let current = signals;
+  for (const part of parts) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+/**
+ * Check if all prerequisites are met for a feature.
+ * Returns true if prerequisites is null (no requirements) or all paths are truthy.
+ */
+function checkPrerequisites(signals, prerequisites) {
+  if (!prerequisites || prerequisites.length === 0) return true;
+  return prerequisites.every(prereq => {
+    const value = resolveSignalPath(signals, prereq.signal_path);
+    return !!value;
+  });
+}
+
+/**
+ * Build the feature catalog with dynamic status for each entry.
+ *
+ * Status logic:
+ *   1. If feature is in metadata.smart_detect.disabled_features -> 'disabled'
+ *   2. If feature's auto_mode key is truthy in autoEnabled -> 'triggered'
+ *   3. If feature's detector triggered (in recommendations) -> 'triggered'
+ *   4. If prerequisites all met -> 'available'
+ *   5. Otherwise -> 'unavailable'
+ *
+ * @param {Object} signals - Extracted signals from smart-detect
+ * @param {{ immediate: Object[], available: Object[] }} recommendations - Filtered recommendations
+ * @param {Object} autoEnabled - Auto-enabled mode flags (loop_mode, visual_mode, etc.)
+ * @param {Object} metadata - AgileFlow metadata (for disabled_features)
+ * @returns {Object[]} Catalog entries with 'status' field added
+ */
+function buildCatalogWithStatus(signals, recommendations, autoEnabled, metadata) {
+  const disabledFeatures = new Set(metadata?.smart_detect?.disabled_features || []);
+
+  // Collect all triggered feature names from recommendations
+  const triggeredFeatures = new Set();
+  const allRecs = [...(recommendations?.immediate || []), ...(recommendations?.available || [])];
+  for (const rec of allRecs) {
+    triggeredFeatures.add(rec.feature);
+  }
+
+  // Collect auto-enabled mode keys that are truthy
+  const autoEnabledKeys = new Set();
+  if (autoEnabled) {
+    for (const [key, value] of Object.entries(autoEnabled)) {
+      if (value) autoEnabledKeys.add(key);
+    }
+  }
+
+  return FEATURE_CATALOG.map(entry => {
+    let status;
+
+    if (disabledFeatures.has(entry.feature)) {
+      status = 'disabled';
+    } else if (entry.auto_mode && autoEnabledKeys.has(entry.auto_mode)) {
+      status = 'triggered';
+    } else if (
+      triggeredFeatures.has(entry.feature) ||
+      (entry.detector && triggeredFeatures.has(entry.detector))
+    ) {
+      status = 'triggered';
+    } else if (checkPrerequisites(signals, entry.prerequisites)) {
+      status = 'available';
+    } else {
+      status = 'unavailable';
+    }
+
+    return { ...entry, status };
+  });
+}
+
+module.exports = {
+  FEATURE_CATALOG,
+  VALID_CATEGORIES,
+  VALID_STATUSES,
+  buildCatalogWithStatus,
+  // Exported for testing
+  resolveSignalPath,
+  checkPrerequisites,
+};

package/scripts/lib/portable-tasks-cli.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+
+/**
+ * portable-tasks-cli.js - CLI wrapper for portable task tracking
+ *
+ * Usage:
+ *   node portable-tasks-cli.js list [--status=pending] [--owner=AG-API] [--json]
+ *   node portable-tasks-cli.js add --subject="..." [--description="..."] [--owner=...] [--status=pending]
+ *   node portable-tasks-cli.js update T-001 --status=completed
+ *   node portable-tasks-cli.js get T-001
+ *   node portable-tasks-cli.js delete T-001
+ *
+ * Exit codes:
+ *   0 = Success
+ *   1 = Error
+ */
+
+const path = require('path');
+const {
+  loadTasks,
+  addTask,
+  updateTask,
+  deleteTask,
+  getTask,
+  listTasks,
+} = require('./portable-tasks');
+
+// Get project directory (current working directory)
+const projectDir = process.cwd();
+
+/**
+ * Parse command-line arguments into command and options
+ * @returns {Object} { command, taskId, options }
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  if (args.length === 0) {
+    return { command: 'help' };
+  }
+
+  const command = args[0];
+  const taskId = args[1] && !args[1].startsWith('--') ? args[1] : null;
+
+  const options = {};
+  for (let i = taskId ? 2 : 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const eqIndex = arg.indexOf('=');
+      const key = eqIndex === -1 ? arg.substring(2) : arg.substring(2, eqIndex);
+      const value = eqIndex === -1 ? undefined : arg.substring(eqIndex + 1);
+      options[key] = value === undefined ? true : value;
+    }
+  }
+
+  return { command, taskId, options };
+}
+
+/**
+ * Format task for human-readable output
+ */
+function formatTaskHuman(task) {
+  let output = `${task.id} [${task.status}] ${task.title}`;
+  if (task.owner) output += ` (${task.owner})`;
+  if (task.blockedBy) output += ` [blocked by ${task.blockedBy}]`;
+  return output;
+}
+
+/**
+ * Run a command
+ */
+function run() {
+  const { command, taskId, options } = parseArgs();
+
+  switch (command) {
+    case 'list':
+    case 'ls': {
+      const tasks = listTasks(projectDir, {
+        status: options.status,
+        owner: options.owner,
+        includeCompleted:
+          options['include-completed'] === true || options['include-completed'] === 'true',
+      });
+
+      if (options.json) {
+        console.log(JSON.stringify(tasks, null, 2));
+      } else {
+        if (tasks.length === 0) {
+          console.log('No tasks found');
+        } else {
+          tasks.forEach(task => console.log(formatTaskHuman(task)));
+        }
+      }
+      process.exit(0);
+      break;
+    }
+
+    case 'add': {
+      if (!options.subject) {
+        console.error('[ERROR] --subject is required');
+        process.exit(1);
+      }
+
+      const result = addTask(projectDir, {
+        subject: options.subject,
+        description: options.description,
+        owner: options.owner,
+        status: options.status || 'pending',
+        story: options.story,
+        blockedBy: options['blocked-by'],
+      });
+
+      if (result.ok) {
+        console.log(`Created: ${result.taskId}`);
+        process.exit(0);
+      } else {
+        console.error(`[ERROR] ${result.error}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'update': {
+      if (!taskId) {
+        console.error('[ERROR] Task ID is required (e.g., T-001)');
+        process.exit(1);
+      }
+
+      const task = getTask(projectDir, taskId);
+      if (!task) {
+        console.error(`[ERROR] Task ${taskId} not found`);
+        process.exit(1);
+      }
+
+      const updates = {};
+      if (options.status && typeof options.status === 'string') updates.status = options.status;
+      if (options.description !== undefined && typeof options.description === 'string')
+        updates.description = options.description;
+      if (options.owner !== undefined && typeof options.owner === 'string')
+        updates.owner = options.owner;
+      if (options.title !== undefined && typeof options.title === 'string')
+        updates.title = options.title;
+      if (options.story !== undefined && typeof options.story === 'string')
+        updates.story = options.story;
+      if (options['blocked-by'] !== undefined && typeof options['blocked-by'] === 'string')
+        updates.blockedBy = options['blocked-by'];
+
+      if (Object.keys(updates).length === 0) {
+        console.error('[ERROR] No updates specified');
+        process.exit(1);
+      }
+
+      const result = updateTask(projectDir, taskId, updates);
+      if (result.ok) {
+        console.log(`Updated: ${taskId}`);
+        process.exit(0);
+      } else {
+        console.error(`[ERROR] ${result.error}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'get': {
+      if (!taskId) {
+        console.error('[ERROR] Task ID is required (e.g., T-001)');
+        process.exit(1);
+      }
+
+      const task = getTask(projectDir, taskId);
+      if (!task) {
+        console.error(`[ERROR] Task ${taskId} not found`);
+        process.exit(1);
+      }
+
+      if (options.json) {
+        console.log(JSON.stringify(task, null, 2));
+      } else {
+        console.log(formatTaskHuman(task));
+        if (task.description) console.log(`  Description: ${task.description}`);
+        if (task.story) console.log(`  Story: ${task.story}`);
+        if (task.created) console.log(`  Created: ${task.created}`);
+        if (task.completed) console.log(`  Completed: ${task.completed}`);
+      }
+      process.exit(0);
+      break;
+    }
+
+    case 'delete':
+    case 'rm': {
+      if (!taskId) {
+        console.error('[ERROR] Task ID is required (e.g., T-001)');
+        process.exit(1);
+      }
+
+      const task = getTask(projectDir, taskId);
+      if (!task) {
+        console.error(`[ERROR] Task ${taskId} not found`);
+        process.exit(1);
+      }
+
+      const result = deleteTask(projectDir, taskId);
+      if (result.ok) {
+        console.log(`Deleted: ${taskId}`);
+        process.exit(0);
+      } else {
+        console.error(`[ERROR] ${result.error}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'help':
+    case '-h':
+    case '--help': {
+      console.log(`
+Portable Task Tracking - File-based task management for all IDEs
+
+Usage:
+  portable-tasks-cli.js list [OPTIONS]
+  portable-tasks-cli.js add --subject="..." [OPTIONS]
+  portable-tasks-cli.js update <TASK_ID> --status=... [OPTIONS]
+  portable-tasks-cli.js get <TASK_ID>
+  portable-tasks-cli.js delete <TASK_ID>
+
+Commands:
+  list (ls)       List tasks (default: active only)
+  add             Create a new task
+  update          Update an existing task
+  get             Show task details
+  delete (rm)     Delete a task
+  help            Show this message
+
+List Options:
+  --status=<status>              Filter by status (pending, in_progress, completed, blocked)
+  --owner=<owner>                Filter by owner (e.g., AG-API, AG-UI)
+  --include-completed            Include completed tasks (default: false)
+  --json                         Output as JSON
+
+Add Options:
+  --subject=<text>               Task title (required)
+  --description=<text>           Task description
+  --owner=<owner>                Task owner (e.g., AG-API)
+  --status=<status>              Initial status (default: pending)
+  --story=<story-id>             Link to story (e.g., US-0040)
+  --blocked-by=<task-id>         Block this task (e.g., T-001)
+
+Update Options:
+  --status=<status>              New status
+  --description=<text>           New description
+  --owner=<owner>                New owner
+  --title=<text>                 New title
+  --story=<story-id>             Update story link
+  --blocked-by=<task-id>         Update blocker
+
+Examples:
+  node portable-tasks-cli.js list
+  node portable-tasks-cli.js list --status=pending --owner=AG-API
+  node portable-tasks-cli.js add --subject="Write tests" --owner=AG-CI
+  node portable-tasks-cli.js update T-001 --status=completed
+  node portable-tasks-cli.js get T-001 --json
+      `);
+      process.exit(0);
+      break;
+    }
+
+    default: {
+      console.error(`[ERROR] Unknown command: ${command}`);
+      console.log('Run with --help for usage');
+      process.exit(1);
+    }
+  }
+}
+
+run();