orchestr8 2.4.0 → 2.6.0

package/bin/cli.js

@@ -2,13 +2,36 @@
 
 const { init } = require('../src/init');
 const { update } = require('../src/update');
-const { addSkills, listSkills } = require('../src/skills');
 const { displayQueue, resetQueue } = require('../src/orchestrator');
+const { validate, formatOutput } = require('../src/validate');
+const { displayHistory, showStats, clearHistory } = require('../src/history');
+const { displayInsights } = require('../src/insights');
+const { displayConfig, setConfigValue, resetConfig } = require('../src/retry');
+const {
+  displayConfig: displayFeedbackConfig,
+  setConfigValue: setFeedbackConfigValue,
+  resetConfig: resetFeedbackConfig
+} = require('../src/feedback');
+const { displayFeedbackInsights } = require('../src/insights');
 
 const args = process.argv.slice(2);
 const command = args[0];
 const subArg = args[1];
 
+function parseFlags(args) {
+  const flags = {};
+  for (const arg of args) {
+    if (arg === '--all') flags.all = true;
+    if (arg === '--stats') flags.stats = true;
+    if (arg === '--force') flags.force = true;
+    if (arg === '--bottlenecks') flags.bottlenecks = true;
+    if (arg === '--failures') flags.failures = true;
+    if (arg === '--json') flags.json = true;
+    if (arg === '--feedback') flags.feedback = true;
+  }
+  return flags;
+}
+
 const commands = {
   init: {
     fn: init,
@@ -18,14 +41,6 @@ const commands = {
     fn: update,
     description: 'Update agents, templates, and rituals (preserves your content)'
   },
-  'add-skills': {
-    fn: () => addSkills(subArg || 'all'),
-    description: 'Install recommended skills for an agent (or all)'
-  },
-  skills: {
-    fn: () => listSkills(subArg),
-    description: 'List recommended skills for agents'
-  },
   queue: {
     fn: () => {
       if (subArg === 'reset') {
@@ -37,6 +52,83 @@ const commands = {
     },
     description: 'Show queue status (use "reset" to clear)'
   },
+  validate: {
+    fn: async () => {
+      const result = await validate();
+      const useColor = process.stdout.isTTY || false;
+      console.log(formatOutput(result, useColor));
+      process.exit(result.exitCode);
+    },
+    description: 'Run pre-flight checks to validate project configuration'
+  },
+  history: {
+    fn: async () => {
+      const flags = parseFlags(args);
+      if (subArg === 'clear') {
+        await clearHistory({ force: flags.force });
+      } else if (flags.stats) {
+        showStats();
+      } else {
+        displayHistory({ all: flags.all });
+      }
+    },
+    description: 'View pipeline execution history'
+  },
+  insights: {
+    fn: () => {
+      const flags = parseFlags(args);
+      if (flags.feedback) {
+        displayFeedbackInsights({ json: flags.json });
+      } else {
+        displayInsights({
+          bottlenecks: flags.bottlenecks,
+          failures: flags.failures,
+          json: flags.json
+        });
+      }
+    },
+    description: 'Analyze pipeline history for bottlenecks, failures, and trends'
+  },
+  'retry-config': {
+    fn: () => {
+      if (subArg === 'set') {
+        const key = args[2];
+        const value = args[3];
+        if (!key || !value) {
+          console.error('Usage: retry-config set <key> <value>');
+          console.error('Valid keys: maxRetries, windowSize, highFailureThreshold');
+          process.exit(1);
+        }
+        setConfigValue(key, value);
+      } else if (subArg === 'reset') {
+        resetConfig();
+        console.log('Retry configuration reset to defaults.');
+      } else {
+        displayConfig();
+      }
+    },
+    description: 'Manage retry configuration for adaptive retry logic'
+  },
+  'feedback-config': {
+    fn: () => {
+      if (subArg === 'set') {
+        const key = args[2];
+        const value = args[3];
+        if (!key || !value) {
+          console.error('Usage: feedback-config set <key> <value>');
+          console.error('Valid keys: minRatingThreshold, enabled');
+          process.exit(1);
+        }
+        setFeedbackConfigValue(key, value);
+      } else if (subArg === 'reset') {
+        resetFeedbackConfig();
+        console.log('Feedback configuration reset to defaults.');
+      } else {
+        displayFeedbackConfig();
+      }
+    },
+    description: 'Manage feedback loop configuration'
+  },
   help: {
     fn: showHelp,
     description: 'Show this help message'
@@ -45,27 +137,43 @@ const commands = {
 
 function showHelp() {
   console.log(`
-agent-workflow - Multi-agent workflow framework
+orchestr8 - Multi-agent workflow framework
 
-Usage: agent-workflow <command> [options]
+Usage: orchestr8 <command> [options]
 
 Commands:
   init                  Initialize .blueprint directory in current project
   update                Update agents, templates, and rituals (preserves your content)
-  add-skills [agent]    Install recommended skills for an agent (alex, cass, nigel, codey, all)
-  skills [agent]        List recommended skills for agents
+  validate              Run pre-flight checks to validate project configuration
   queue                 Show current queue state for /implement-feature pipeline
   queue reset           Clear the queue and reset all state
+  history               View recent pipeline runs (last 10 by default)
+  history --all         View all pipeline runs
+  history --stats       View aggregate statistics
+  history clear         Clear all pipeline history (with confirmation)
+  history clear --force Clear all pipeline history (no confirmation)
+  insights              Analyze pipeline for bottlenecks, failures, and trends
+  insights --bottlenecks Show only bottleneck analysis
+  insights --failures   Show only failure patterns
+  insights --feedback   Show feedback loop insights (calibration, correlations)
+  insights --json       Output analysis as JSON
+  retry-config          View current retry configuration
+  retry-config set <key> <value>  Modify a config value (maxRetries, windowSize, highFailureThreshold)
+  retry-config reset    Reset retry configuration to defaults
+  feedback-config       View current feedback loop configuration
+  feedback-config set <key> <value>  Modify a config value (minRatingThreshold, enabled)
+  feedback-config reset Reset feedback configuration to defaults
   help                  Show this help message
 
 Examples:
-  npx agent-workflow init
-  npx agent-workflow update
-  npx agent-workflow add-skills all
-  npx agent-workflow add-skills codey
-  npx agent-workflow skills
-  npx agent-workflow queue
-  npx agent-workflow queue reset
+  npx orchestr8 init
+  npx orchestr8 update
+  npx orchestr8 validate
+  npx orchestr8 queue
+  npx orchestr8 history
+  npx orchestr8 history --stats
+  npx orchestr8 insights --feedback
+  npx orchestr8 feedback-config
 `);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestr8",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Multi-agent workflow framework for automated feature development",
   "main": "src/index.js",
   "bin": {

package/src/feedback.js

@@ -0,0 +1,171 @@
+const fs = require('fs');
+const path = require('path');
+
+const CONFIG_FILE = '.claude/feedback-config.json';
+
+/**
+ * Returns the default feedback configuration.
+ * Per FEATURE_SPEC.md defaults.
+ */
+function getDefaultConfig() {
+  return {
+    minRatingThreshold: 3.0,
+    enabled: true,
+    issueMappings: {
+      'missing-error-handling': 'add-context',
+      'unclear-scope': 'simplify-prompt',
+      'too-complex': 'simplify-prompt',
+      'too-many-stories': 'reduce-stories',
+      'untestable-criteria': 'simplify-tests',
+      'missing-edge-cases': 'add-context'
+    }
+  };
+}
+
+/**
+ * Ensures the .claude directory exists.
+ */
+function ensureConfigDir() {
+  const dir = path.dirname(CONFIG_FILE);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Reads the feedback config from file.
+ * Returns defaults if file is missing or corrupted.
+ */
+function readConfig() {
+  ensureConfigDir();
+  if (!fs.existsSync(CONFIG_FILE)) {
+    return getDefaultConfig();
+  }
+  try {
+    const content = fs.readFileSync(CONFIG_FILE, 'utf8');
+    return JSON.parse(content);
+  } catch (err) {
+    return getDefaultConfig();
+  }
+}
+
+/**
+ * Writes the feedback config to file.
+ */
+function writeConfig(config) {
+  ensureConfigDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+/**
+ * Validates a feedback object against the schema.
+ * Per FEATURE_SPEC.md:Rule 1.
+ * @param {object} feedback - Feedback object to validate
+ * @returns {object} { valid: boolean, errors: string[] }
+ */
+function validateFeedback(feedback) {
+  const errors = [];
+
+  if (!['alex', 'cass', 'nigel'].includes(feedback.about)) {
+    errors.push('Invalid "about" field');
+  }
+
+  if (typeof feedback.rating !== 'number' ||
+      feedback.rating < 1 ||
+      feedback.rating > 5) {
+    errors.push('Invalid "rating" field');
+  }
+
+  if (typeof feedback.confidence !== 'number' ||
+      feedback.confidence < 0 ||
+      feedback.confidence > 1) {
+    errors.push('Invalid "confidence" field');
+  }
+
+  if (!Array.isArray(feedback.issues)) {
+    errors.push('Invalid "issues" field');
+  }
+
+  if (!['proceed', 'pause', 'revise'].includes(feedback.recommendation)) {
+    errors.push('Invalid "recommendation" field');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Determines whether the pipeline should pause based on feedback.
+ * Per FEATURE_SPEC.md:Rule 2.
+ * @param {object} feedback - Validated feedback object
+ * @param {object} config - Feedback configuration
+ * @returns {boolean} True if pipeline should pause
+ */
+function shouldPause(feedback, config) {
+  return feedback.rating < config.minRatingThreshold ||
+         feedback.recommendation === 'pause';
+}
+
+/**
+ * Validates and sets a config value.
+ * @param {string} key - Config key
+ * @param {string} value - New value (will be parsed)
+ */
+function setConfigValue(key, value) {
+  const config = readConfig();
+
+  if (key === 'minRatingThreshold') {
+    const numValue = parseFloat(value);
+    if (isNaN(numValue) || numValue < 1.0 || numValue > 5.0) {
+      throw new Error(
+        'minRatingThreshold must be a number between 1.0 and 5.0'
+      );
+    }
+    config.minRatingThreshold = numValue;
+  } else if (key === 'enabled') {
+    if (value !== 'true' && value !== 'false') {
+      throw new Error('enabled must be true or false');
+    }
+    config.enabled = value === 'true';
+  } else {
+    throw new Error(
+      `Unknown config key: ${key}. Valid keys: minRatingThreshold, enabled`
+    );
+  }
+
+  writeConfig(config);
+  console.log(`Set ${key} = ${config[key]}`);
+}
+
+/**
+ * Displays the current feedback configuration.
+ */
+function displayConfig() {
+  const config = readConfig();
+  console.log('\nFeedback Configuration\n');
+  console.log(`  Min rating threshold:   ${config.minRatingThreshold}`);
+  console.log(`  Enabled:                ${config.enabled}`);
+  console.log('\n  Issue Mappings:');
+  for (const [issue, strategy] of Object.entries(config.issueMappings)) {
+    console.log(`    ${issue.padEnd(24)}: ${strategy}`);
+  }
+  console.log('');
+}
+
+/**
+ * Resets feedback config to defaults.
+ */
+function resetConfig() {
+  writeConfig(getDefaultConfig());
+}
+
+module.exports = {
+  CONFIG_FILE,
+  getDefaultConfig,
+  readConfig,
+  writeConfig,
+  validateFeedback,
+  shouldPause,
+  setConfigValue,
+  displayConfig,
+  resetConfig
+};

package/src/history.js

@@ -0,0 +1,306 @@
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const HISTORY_FILE = '.claude/pipeline-history.json';
+
+function ensureHistoryDir() {
+  const dir = path.dirname(HISTORY_FILE);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function readHistoryFile() {
+  ensureHistoryDir();
+  if (!fs.existsSync(HISTORY_FILE)) {
+    return [];
+  }
+  try {
+    const content = fs.readFileSync(HISTORY_FILE, 'utf8');
+    return JSON.parse(content);
+  } catch (err) {
+    return { error: 'corrupted' };
+  }
+}
+
+function writeHistoryFile(entries) {
+  ensureHistoryDir();
+  fs.writeFileSync(HISTORY_FILE, JSON.stringify(entries, null, 2));
+}
+
+function recordHistory(entry) {
+  try {
+    const history = readHistoryFile();
+    if (history.error) {
+      console.warn('Warning: History file is corrupted, cannot record entry.');
+      return false;
+    }
+    history.push(entry);
+    writeHistoryFile(history);
+    return true;
+  } catch (err) {
+    console.warn(`Warning: Failed to record history: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Stores feedback for a specific stage in a feature's history entry.
+ * Per FEATURE_SPEC.md - feedback is stored at stages[stage].feedback
+ * @param {string} slug - Feature slug
+ * @param {string} stage - Stage name (alex, cass, nigel, etc.)
+ * @param {object} feedback - Feedback object to store
+ * @returns {boolean} True if stored successfully
+ */
+function storeStageFeedback(slug, stage, feedback) {
+  try {
+    const history = readHistoryFile();
+    if (history.error) {
+      console.warn('Warning: History file is corrupted, cannot store feedback.');
+      return false;
+    }
+
+    // Find the most recent entry for this slug
+    const entry = history.findLast(e => e.slug === slug);
+    if (!entry) {
+      console.warn(`Warning: No history entry found for slug: ${slug}`);
+      return false;
+    }
+
+    // Ensure stages object exists
+    if (!entry.stages) {
+      entry.stages = {};
+    }
+
+    // Ensure stage object exists
+    if (!entry.stages[stage]) {
+      entry.stages[stage] = {};
+    }
+
+    // Store feedback
+    entry.stages[stage].feedback = feedback;
+
+    writeHistoryFile(history);
+    return true;
+  } catch (err) {
+    console.warn(`Warning: Failed to store feedback: ${err.message}`);
+    return false;
+  }
+}
+
+function formatDuration(ms) {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const secs = seconds % 60;
+  if (minutes === 0) {
+    return `${secs}s`;
+  }
+  return `${minutes}m ${secs}s`;
+}
+
+function formatDate(isoString) {
+  const date = new Date(isoString);
+  return date.toISOString().replace('T', ' ').slice(0, 19);
+}
+
+function colorize(text, color, useColor) {
+  if (!useColor) return text;
+  const colors = {
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    reset: '\x1b[0m'
+  };
+  return `${colors[color] || ''}${text}${colors.reset}`;
+}
+
+function displayHistory(options = {}) {
+  const showAll = options.all || false;
+  const useColor = options.color !== false && process.stdout.isTTY;
+
+  const history = readHistoryFile();
+
+  if (history.error === 'corrupted') {
+    console.log("Warning: History file is corrupted. Run 'orchestr8 history clear' to reset.");
+    return;
+  }
+
+  if (!history || history.length === 0) {
+    console.log('No pipeline history found.');
+    return;
+  }
+
+  const sorted = [...history].sort((a, b) =>
+    new Date(b.completedAt) - new Date(a.completedAt)
+  );
+
+  const entries = showAll ? sorted : sorted.slice(0, 10);
+  const total = history.length;
+  const showing = entries.length;
+
+  console.log(`\nPipeline History (showing ${showing} of ${total} runs)\n`);
+  console.log('  SLUG                STATUS    DATE                  DURATION');
+
+  for (const entry of entries) {
+    const slug = entry.slug.padEnd(18);
+    let status = entry.status.padEnd(8);
+    const date = formatDate(entry.completedAt);
+    const duration = formatDuration(entry.totalDurationMs);
+
+    if (entry.status === 'success') {
+      status = colorize(status, 'green', useColor);
+    } else if (entry.status === 'failed') {
+      status = colorize(status, 'red', useColor);
+    } else if (entry.status === 'paused') {
+      status = colorize(status, 'yellow', useColor);
+    }
+
+    let suffix = '';
+    if (entry.status === 'failed' && entry.failedStage) {
+      suffix = ` (failed at: ${entry.failedStage})`;
+    } else if (entry.status === 'paused' && entry.pausedAfter) {
+      suffix = ` (paused at: ${entry.pausedAfter})`;
+    }
+
+    console.log(`  ${slug}  ${status}  ${date}   ${duration}${suffix}`);
+  }
+
+  if (!showAll && total > 10) {
+    console.log(`\nRun 'orchestr8 history --all' to see all entries.`);
+  }
+  console.log(`Run 'orchestr8 history --stats' for aggregate statistics.`);
+}
+
+function showStats() {
+  const history = readHistoryFile();
+
+  if (history.error === 'corrupted') {
+    console.log("Warning: History file is corrupted. Run 'orchestr8 history clear' to reset.");
+    return;
+  }
+
+  if (!history || history.length === 0) {
+    console.log('Insufficient data for statistics. Complete at least one pipeline run.');
+    return;
+  }
+
+  const total = history.length;
+  const successRuns = history.filter(e => e.status === 'success');
+  const failedRuns = history.filter(e => e.status === 'failed');
+  const pausedRuns = history.filter(e => e.status === 'paused');
+
+  const successCount = successRuns.length;
+  const successRate = Math.round((successCount / total) * 100);
+
+  console.log(`\nPipeline Statistics (based on ${total} runs)\n`);
+  console.log('  METRIC                    VALUE');
+  console.log(`  Success rate              ${successRate}% (${successCount}/${total} runs)`);
+  console.log(`  Total runs                ${total} (${successCount} success, ${failedRuns.length} failed, ${pausedRuns.length} paused)`);
+
+  if (successRuns.length > 0) {
+    const avgTotal = Math.round(
+      successRuns.reduce((sum, e) => sum + e.totalDurationMs, 0) / successRuns.length
+    );
+    console.log(`  Avg pipeline duration     ${formatDuration(avgTotal)}`);
+  }
+
+  const stages = ['alex', 'cass', 'nigel', 'codey-plan', 'codey-implement'];
+  const stageStats = {};
+  const failureCounts = {};
+
+  for (const stage of stages) {
+    stageStats[stage] = { durations: [], failures: 0 };
+  }
+
+  for (const entry of history) {
+    if (entry.stages) {
+      for (const stage of stages) {
+        if (entry.stages[stage] && entry.stages[stage].durationMs) {
+          stageStats[stage].durations.push(entry.stages[stage].durationMs);
+        }
+      }
+    }
+    if (entry.status === 'failed' && entry.failedStage) {
+      failureCounts[entry.failedStage] = (failureCounts[entry.failedStage] || 0) + 1;
+    }
+  }
+
+  console.log('\n  STAGE             AVG DURATION    FAILURES');
+  for (const stage of stages) {
+    const stats = stageStats[stage];
+    const avgDuration = stats.durations.length > 0
+      ? formatDuration(Math.round(stats.durations.reduce((a, b) => a + b, 0) / stats.durations.length))
+      : 'N/A';
+    const failures = failureCounts[stage] || 0;
+    console.log(`  ${stage.padEnd(16)}  ${avgDuration.padEnd(14)}  ${failures}`);
+  }
+
+  if (failedRuns.length === 0) {
+    console.log('\n  No failures recorded');
+  } else {
+    const maxFailures = Math.max(...Object.values(failureCounts));
+    const topFailures = Object.entries(failureCounts)
+      .filter(([, count]) => count === maxFailures)
+      .map(([stage]) => stage);
+
+    if (topFailures.length === 1) {
+      console.log(`\n  Most common failure: ${topFailures[0]} (${maxFailures} failures)`);
+    } else {
+      console.log(`\n  Most common failures: ${topFailures.join(', ')} (${maxFailures} each)`);
+    }
+  }
+}
+
+async function clearHistory(options = {}) {
+  const force = options.force || false;
+
+  const history = readHistoryFile();
+
+  if (history.error === 'corrupted') {
+    writeHistoryFile([]);
+    console.log('History file was corrupted. File has been reset.');
+    return;
+  }
+
+  if (!history || history.length === 0) {
+    console.log('No history to clear.');
+    return;
+  }
+
+  const count = history.length;
+
+  if (!force) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    const answer = await new Promise((resolve) => {
+      rl.question(`This will delete all ${count} history entries. Continue? (y/N) `, (ans) => {
+        rl.close();
+        resolve(ans.toLowerCase().trim());
+      });
+    });
+
+    if (answer !== 'y' && answer !== 'yes') {
+      console.log('Clear cancelled. History unchanged.');
+      return;
+    }
+  }
+
+  writeHistoryFile([]);
+  console.log(`Pipeline history cleared. ${count} entries removed.`);
+}
+
+module.exports = {
+  HISTORY_FILE,
+  readHistoryFile,
+  writeHistoryFile,
+  recordHistory,
+  storeStageFeedback,
+  displayHistory,
+  showStats,
+  clearHistory,
+  formatDuration
+};