orchestr8 2.5.0 → 2.6.1

package/src/retry.js

@@ -0,0 +1,274 @@
+const fs = require('fs');
+const path = require('path');
+const { readHistoryFile } = require('./history');
+
+const CONFIG_FILE = '.claude/retry-config.json';
+
+/**
+ * Returns the default retry configuration.
+ * Per FEATURE_SPEC.md defaults.
+ */
+function getDefaultConfig() {
+  return {
+    maxRetries: 3,
+    windowSize: 10,
+    highFailureThreshold: 0.2,
+    strategies: {
+      alex: ['simplify-prompt', 'add-context'],
+      cass: ['reduce-stories', 'simplify-prompt'],
+      nigel: ['simplify-tests', 'add-context'],
+      'codey-plan': ['add-context', 'simplify-prompt'],
+      'codey-implement': ['incremental', 'rollback']
+    }
+  };
+}
+
+/**
+ * Ensures the .claude directory exists.
+ */
+function ensureConfigDir() {
+  const dir = path.dirname(CONFIG_FILE);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Reads the retry 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) {
+    // Graceful degradation: return defaults on parse error
+    return getDefaultConfig();
+  }
+}
+
+/**
+ * Writes the retry config to file.
+ * Creates .claude directory if needed.
+ */
+function writeConfig(config) {
+  ensureConfigDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+/**
+ * Resets config to defaults by writing default config to file.
+ */
+function resetConfig() {
+  writeConfig(getDefaultConfig());
+}
+
+/**
+ * Calculates failure rate for a stage over a sliding window.
+ * @param {string} stage - The pipeline stage name
+ * @param {Array} history - Array of history entries
+ * @param {number} windowSize - Number of recent entries to consider
+ * @returns {number} Failure rate between 0 and 1
+ */
+function calculateFailureRate(stage, history, windowSize = 10) {
+  // Handle corrupted history gracefully
+  if (!Array.isArray(history) || history.length === 0) {
+    return 0;
+  }
+  const recent = history.slice(-windowSize);
+  if (recent.length === 0) return 0;
+  const failedAtStage = recent.filter(
+    e => e.status === 'failed' && e.failedStage === stage
+  ).length;
+  return failedAtStage / recent.length;
+}
+
+/**
+ * Recommends a retry strategy based on attempt count and failure rate.
+ * @param {string} stage - The pipeline stage name
+ * @param {number} attemptCount - Current attempt number (1-based)
+ * @param {number} failureRate - Calculated failure rate (0-1)
+ * @param {object} config - Retry configuration object
+ * @returns {string} Strategy name or 'abort-recommended'
+ */
+function recommendStrategy(stage, attemptCount, failureRate, config) {
+  if (attemptCount > config.maxRetries) {
+    return 'abort-recommended';
+  }
+  if (failureRate > config.highFailureThreshold) {
+    const strategies = config.strategies[stage] || [];
+    const idx = Math.min(attemptCount - 1, strategies.length - 1);
+    return strategies[idx] || 'retry';
+  }
+  return 'retry';
+}
+
+/**
+ * Applies a strategy by modifying the prompt.
+ * @param {string} strategy - The strategy name
+ * @param {string} originalPrompt - The original prompt text
+ * @returns {string} Modified prompt or original if no modification needed
+ */
+function applyStrategy(strategy, originalPrompt) {
+  const modifications = {
+    'retry': null,
+    'simplify-prompt': 'Focus on core requirements only. Skip edge cases and optional sections.',
+    'reduce-stories': 'Write only the 2-3 most critical user stories. Defer others to follow-up.',
+    'simplify-tests': 'Write only happy-path tests for each AC. Skip edge cases.',
+    'add-context': '[Context from previous stage prepended]',
+    'incremental': 'Implement one test at a time. Stop and report after each.',
+    'rollback': 'git checkout -- .'
+  };
+  const mod = modifications[strategy];
+  return mod ? `${originalPrompt}\n\n${mod}` : originalPrompt;
+}
+
+/**
+ * Orchestrator entry point: determines if/how to retry a failed stage.
+ * @param {string} stage - The pipeline stage that failed
+ * @param {string} featureSlug - The feature being implemented
+ * @param {Array|null} history - History entries (pass null to read from file)
+ * @param {object|null} config - Config object (pass null to read from file)
+ * @param {number} attemptCount - Current attempt number (1-based)
+ * @returns {object} Recommendation object with strategy and metadata
+ */
+function shouldRetry(stage, featureSlug, history, config, attemptCount) {
+  // Read history from file if not provided
+  let historyData = history;
+  if (historyData === null || historyData === undefined) {
+    historyData = readHistoryFile();
+    // Handle corrupted history
+    if (historyData && historyData.error === 'corrupted') {
+      historyData = [];
+    }
+  }
+
+  // Read config from file if not provided
+  const configData = config || readConfig();
+
+  const failureRate = calculateFailureRate(
+    stage,
+    historyData,
+    configData.windowSize
+  );
+
+  const strategy = recommendStrategy(
+    stage,
+    attemptCount,
+    failureRate,
+    configData
+  );
+
+  return {
+    stage,
+    featureSlug,
+    attemptCount,
+    failureRate,
+    strategy,
+    shouldRetry: strategy !== 'abort-recommended',
+    maxRetries: configData.maxRetries
+  };
+}
+
+/**
+ * Displays the current retry configuration.
+ */
+function displayConfig() {
+  const config = readConfig();
+  console.log('\nRetry Configuration\n');
+  console.log(`  Max retries:            ${config.maxRetries}`);
+  console.log(`  Window size:            ${config.windowSize}`);
+  console.log(`  High failure threshold: ${config.highFailureThreshold}`);
+  console.log('\n  Stage Strategies:');
+  for (const [stage, strategies] of Object.entries(config.strategies)) {
+    console.log(`    ${stage.padEnd(16)}: ${strategies.join(' -> ')}`);
+  }
+  console.log('');
+}
+
+/**
+ * Sets a config value by key.
+ * @param {string} key - Config key (maxRetries, windowSize, highFailureThreshold)
+ * @param {string} value - New value (will be parsed appropriately)
+ */
+function setConfigValue(key, value) {
+  const config = readConfig();
+  const numericKeys = ['maxRetries', 'windowSize', 'highFailureThreshold'];
+
+  if (!numericKeys.includes(key)) {
+    throw new Error(
+      `Unknown config key: ${key}. Valid keys: ${numericKeys.join(', ')}`
+    );
+  }
+
+  const numValue = parseFloat(value);
+  if (isNaN(numValue)) {
+    throw new Error(`Invalid value for ${key}: ${value}. Must be a number.`);
+  }
+
+  // Validate specific constraints
+  if (key === 'maxRetries' && (numValue < 0 || !Number.isInteger(numValue))) {
+    throw new Error('maxRetries must be a non-negative integer.');
+  }
+  if (key === 'windowSize' && (numValue < 1 || !Number.isInteger(numValue))) {
+    throw new Error('windowSize must be a positive integer.');
+  }
+  if (key === 'highFailureThreshold' && (numValue < 0 || numValue > 1)) {
+    throw new Error('highFailureThreshold must be between 0 and 1.');
+  }
+
+  config[key] = numValue;
+  writeConfig(config);
+  console.log(`Set ${key} = ${numValue}`);
+}
+
+/**
+ * Maps feedback issues to retry strategies using issue mappings config.
+ * Per FEATURE_SPEC.md:Rule 3.
+ * @param {Array} issues - Array of issue codes from feedback
+ * @param {object} config - Config with issueMappings (from feedback config)
+ * @returns {Array} Array of recommended strategies
+ */
+function mapIssuesToStrategies(issues, config) {
+  if (!issues || !Array.isArray(issues) || issues.length === 0) {
+    return ['retry'];
+  }
+
+  const mappings = config?.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'
+  };
+
+  const strategies = [];
+  for (const issue of issues) {
+    const strategy = mappings[issue];
+    if (strategy && !strategies.includes(strategy)) {
+      strategies.push(strategy);
+    }
+  }
+
+  return strategies.length > 0 ? strategies : ['retry'];
+}
+
+module.exports = {
+  CONFIG_FILE,
+  getDefaultConfig,
+  readConfig,
+  writeConfig,
+  resetConfig,
+  calculateFailureRate,
+  recommendStrategy,
+  applyStrategy,
+  shouldRetry,
+  displayConfig,
+  setConfigValue,
+  mapIssuesToStrategies
+};

package/src/validate.js

@@ -0,0 +1,172 @@
+const fs = require('fs');
+const path = require('path');
+
+const REQUIRED_DIRS = ['.blueprint', '.business_context', '.claude/commands'];
+const AGENT_FILES = [
+  'AGENT_SPECIFICATION_ALEX.md',
+  'AGENT_BA_CASS.md',
+  'AGENT_TESTER_NIGEL.md',
+  'AGENT_DEVELOPER_CODEY.md'
+];
+const SYSTEM_SPEC_PATH = '.blueprint/system_specification/SYSTEM_SPEC.md';
+const SKILL_PATH = '.claude/commands/implement-feature.md';
+const MIN_NODE_VERSION = 18;
+
+function checkDirectories() {
+  const missing = REQUIRED_DIRS.filter(dir => !fs.existsSync(dir));
+  const passed = missing.length === 0;
+  return {
+    name: 'Required directories',
+    passed,
+    message: passed
+      ? 'All required directories exist'
+      : `Missing directories: ${missing.join(', ')}`,
+    fix: passed ? null : 'Run `orchestr8 init` to initialize project'
+  };
+}
+
+function checkSystemSpec() {
+  const exists = fs.existsSync(SYSTEM_SPEC_PATH);
+  return {
+    name: 'System specification',
+    passed: exists,
+    message: exists
+      ? 'System specification exists'
+      : `Missing: ${SYSTEM_SPEC_PATH}`,
+    fix: exists ? null : 'Run `orchestr8 init` to create system specification'
+  };
+}
+
+function checkAgentSpecs() {
+  const agentsDir = '.blueprint/agents';
+  if (!fs.existsSync(agentsDir)) {
+    return {
+      name: 'agent specifications',
+      passed: false,
+      message: 'Missing: .blueprint/agents directory',
+      fix: 'Run `orchestr8 init` to create agent specification files'
+    };
+  }
+
+  const missing = AGENT_FILES.filter(f => !fs.existsSync(path.join(agentsDir, f)));
+  const passed = missing.length === 0;
+  return {
+    name: 'agent specifications',
+    passed,
+    message: passed
+      ? 'All agent specifications exist'
+      : `Missing agent files: ${missing.join(', ')}`,
+    fix: passed ? null : 'Run `orchestr8 init` to create agent specification files'
+  };
+}
+
+function checkBusinessContext() {
+  const dir = '.business_context';
+  if (!fs.existsSync(dir)) {
+    return {
+      name: 'business context',
+      passed: false,
+      message: 'Missing: .business_context directory',
+      fix: 'Run `orchestr8 init` to create .business_context directory'
+    };
+  }
+
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter(f => !f.startsWith('.'));
+  } catch {
+    files = [];
+  }
+
+  const passed = files.length > 0;
+  return {
+    name: 'business context',
+    passed,
+    message: passed
+      ? 'Business context directory has content'
+      : 'Business context directory is empty',
+    fix: passed ? null : 'Add at least one file to `.business_context/` directory'
+  };
+}
+
+function checkSkillsInstalled() {
+  const exists = fs.existsSync(SKILL_PATH);
+  return {
+    name: 'skills installed',
+    passed: exists,
+    message: exists
+      ? 'Required skills are installed'
+      : `Missing: ${SKILL_PATH}`,
+    fix: exists ? null : 'Run `orchestr8 init` to install required skills'
+  };
+}
+
+function checkNodeVersion() {
+  const versionStr = process.version;
+  const majorVersion = parseInt(versionStr.slice(1).split('.')[0], 10);
+  const passed = majorVersion >= MIN_NODE_VERSION;
+  return {
+    name: 'Node.js version',
+    passed,
+    message: passed
+      ? `Node.js ${majorVersion} meets minimum requirement (>=${MIN_NODE_VERSION})`
+      : `Node.js ${majorVersion} is below minimum requirement (>=${MIN_NODE_VERSION})`,
+    fix: passed ? null : `Upgrade Node.js to version ${MIN_NODE_VERSION} or higher`,
+    detectedVersion: versionStr
+  };
+}
+
+async function validate() {
+  const checks = [
+    checkDirectories(),
+    checkSystemSpec(),
+    checkAgentSpecs(),
+    checkBusinessContext(),
+    checkSkillsInstalled(),
+    checkNodeVersion()
+  ];
+
+  const success = checks.every(c => c.passed);
+  const exitCode = success ? 0 : 1;
+
+  return { success, exitCode, checks };
+}
+
+function formatOutput(result, useColor = false) {
+  const lines = [];
+
+  const green = useColor ? '\x1b[32m' : '';
+  const red = useColor ? '\x1b[31m' : '';
+  const reset = useColor ? '\x1b[0m' : '';
+
+  const passIndicator = useColor ? `${green}\u2713${reset}` : '[PASS]';
+  const failIndicator = useColor ? `${red}\u2717${reset}` : '[FAIL]';
+
+  for (const check of result.checks) {
+    const indicator = check.passed ? passIndicator : failIndicator;
+    lines.push(`${indicator} ${check.name}: ${check.message}`);
+    if (!check.passed && check.fix) {
+      lines.push(`  Fix: ${check.fix}`);
+    }
+  }
+
+  lines.push('');
+  if (result.success) {
+    lines.push(useColor
+      ? `${green}All checks passed. Project is ready.${reset}`
+      : 'All checks passed. Project is ready.');
+  } else {
+    const failedCount = result.checks.filter(c => !c.passed).length;
+    lines.push(useColor
+      ? `${red}${failedCount} check(s) failed.${reset}`
+      : `${failedCount} check(s) failed.`);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  validate,
+  formatOutput,
+  checkNodeVersion
+};

package/src/skills.js

@@ -1,93 +0,0 @@
-const { execSync } = require('child_process');
-
-const AGENT_SKILLS = {
-  alex: {
-    name: 'Alex',
-    role: 'System Specification & Chief-of-Staff',
-    skills: [
-      { repo: 'https://github.com/waynesutton/convexskills', skill: 'avoid-feature-creep' },
-      { repo: 'https://github.com/pproenca/dot-skills', skill: 'feature-spec' }
-    ]
-  },
-  cass: {
-    name: 'Cass',
-    role: 'Story Writer / BA',
-    skills: [
-      { repo: 'https://github.com/aj-geddes/useful-ai-prompts', skill: 'user-story-writing' }
-    ]
-  },
-  nigel: {
-    name: 'Nigel',
-    role: 'Tester',
-    skills: [
-      { repo: 'https://github.com/wshobson/agents', skill: 'javascript-testing-patterns' },
-      { repo: 'https://github.com/wshobson/agents', skill: 'modern-javascript-patterns' }
-    ]
-  },
-  codey: {
-    name: 'Codey',
-    role: 'Developer',
-    skills: [
-      { repo: 'https://github.com/martinholovsky/claude-skills-generator', skill: 'javascript-expert' },
-      { repo: 'https://github.com/wshobson/agents', skill: 'modern-javascript-patterns' }
-    ]
-  }
-};
-
-function installSkill(repo, skill) {
-  const cmd = `npx skills add ${repo} --skill ${skill}`;
-  console.log(`  Running: ${cmd}`);
-  try {
-    execSync(cmd, { stdio: 'inherit' });
-    return true;
-  } catch (error) {
-    console.error(`  Failed to install ${skill}`);
-    return false;
-  }
-}
-
-async function addSkills(agent) {
-  const agents = agent === 'all' ? Object.keys(AGENT_SKILLS) : [agent.toLowerCase()];
-
-  for (const agentKey of agents) {
-    const agentConfig = AGENT_SKILLS[agentKey];
-
-    if (!agentConfig) {
-      console.error(`Unknown agent: ${agentKey}`);
-      console.error(`Available agents: ${Object.keys(AGENT_SKILLS).join(', ')}, all`);
-      process.exit(1);
-    }
-
-    console.log(`\nInstalling skills for ${agentConfig.name} (${agentConfig.role}):`);
-
-    for (const { repo, skill } of agentConfig.skills) {
-      installSkill(repo, skill);
-    }
-  }
-
-  console.log('\nSkills installation complete.');
-}
-
-function listSkills(agent) {
-  const agents = agent ? [agent.toLowerCase()] : Object.keys(AGENT_SKILLS);
-
-  console.log('\nAgent Workflow - Recommended Skills\n');
-
-  for (const agentKey of agents) {
-    const agentConfig = AGENT_SKILLS[agentKey];
-
-    if (!agentConfig) {
-      console.error(`Unknown agent: ${agentKey}`);
-      process.exit(1);
-    }
-
-    console.log(`${agentConfig.name} (${agentConfig.role}):`);
-    for (const { repo, skill } of agentConfig.skills) {
-      console.log(`  - ${skill}`);
-      console.log(`    ${repo}`);
-    }
-    console.log('');
-  }
-}
-
-module.exports = { addSkills, listSkills, AGENT_SKILLS };