orchestr8 2.6.1 → 2.7.0

package/src/classifier.js

@@ -0,0 +1,173 @@
+/**
+ * Smart Story Routing - Feature Classifier Module
+ *
+ * Classifies features as "technical" or "user-facing" to determine
+ * whether the Cass (story writing) stage should be included in the pipeline.
+ */
+
+// Technical keywords indicate infrastructure/internal work
+const TECHNICAL_KEYWORDS = [
+  'refactor',
+  'token',
+  'performance',
+  'module',
+  'internal',
+  'infrastructure',
+  'optimization',
+  'extract',
+  'compress',
+  'cache',
+  'schema',
+  'validation',
+  'helper',
+  'utility',
+  'config'
+];
+
+// User-facing keywords indicate customer-visible features
+const USER_FACING_KEYWORDS = [
+  'user',
+  'customer',
+  'ui',
+  'screen',
+  'journey',
+  'flow',
+  'experience',
+  'interface',
+  'form',
+  'button',
+  'login',
+  'signup',
+  'dashboard',
+  'notification',
+  'email'
+];
+
+/**
+ * Classify a feature specification as technical or user-facing
+ * @param {string} content - The feature specification content
+ * @returns {Object} Classification result with type, counts, and reason
+ */
+function classifyFeature(content) {
+  const lowerContent = (content || '').toLowerCase();
+
+  let technicalCount = 0;
+  let userFacingCount = 0;
+  const technicalMatches = [];
+  const userFacingMatches = [];
+
+  // Count technical keyword matches
+  for (const keyword of TECHNICAL_KEYWORDS) {
+    const regex = new RegExp(`\\b${keyword}\\b`, 'gi');
+    const matches = lowerContent.match(regex);
+    if (matches) {
+      technicalCount += matches.length;
+      technicalMatches.push(keyword);
+    }
+  }
+
+  // Count user-facing keyword matches
+  for (const keyword of USER_FACING_KEYWORDS) {
+    const regex = new RegExp(`\\b${keyword}\\b`, 'gi');
+    const matches = lowerContent.match(regex);
+    if (matches) {
+      userFacingCount += matches.length;
+      userFacingMatches.push(keyword);
+    }
+  }
+
+  // Determine type - tie goes to user-facing (conservative default)
+  const type = technicalCount > userFacingCount ? 'technical' : 'user-facing';
+
+  // Build reason string
+  let reason;
+  if (technicalCount === 0 && userFacingCount === 0) {
+    reason = 'No keywords found, defaulting to user-facing';
+  } else if (technicalCount > userFacingCount) {
+    reason = `Technical keywords (${technicalMatches.join(', ')}) outweigh user-facing`;
+  } else if (userFacingCount > technicalCount) {
+    reason = `User-facing keywords (${userFacingMatches.join(', ')}) outweigh technical`;
+  } else {
+    reason = 'Tie between technical and user-facing, defaulting to user-facing';
+  }
+
+  return {
+    type,
+    technicalCount,
+    userFacingCount,
+    reason
+  };
+}
+
+/**
+ * Parse story-related flags from command arguments
+ * @param {string[]} args - Array of command arguments
+ * @returns {Object} Parsed flags with override value
+ */
+function parseStoryFlags(args) {
+  const argList = args || [];
+
+  if (argList.includes('--with-stories')) {
+    return { override: 'include' };
+  }
+
+  if (argList.includes('--skip-stories')) {
+    return { override: 'skip' };
+  }
+
+  return { override: null };
+}
+
+/**
+ * Determine whether stories should be included in the pipeline
+ * @param {string} featureType - 'technical' or 'user-facing'
+ * @param {string|null} override - 'include', 'skip', or null
+ * @returns {boolean} Whether to include stories in the pipeline
+ */
+function shouldIncludeStories(featureType, override) {
+  // Override takes precedence
+  if (override === 'include') {
+    return true;
+  }
+  if (override === 'skip') {
+    return false;
+  }
+
+  // Default behavior based on classification
+  return featureType === 'user-facing';
+}
+
+/**
+ * Build queue state object with classification data
+ * @param {string} slug - Feature slug
+ * @param {string} featureType - 'technical' or 'user-facing'
+ * @param {boolean} includeStories - Whether stories are included
+ * @returns {Object} Queue state object with featureType and skippedCass fields
+ */
+function buildClassifiedQueueState(slug, featureType, includeStories) {
+  return {
+    slug,
+    featureType,
+    skippedCass: !includeStories
+  };
+}
+
+/**
+ * Log classification result to console
+ * @param {Object} result - Classification result from classifyFeature
+ */
+function logClassification(result) {
+  console.log(`Feature classified as ${result.type}: ${result.reason}`);
+  console.log(`  Technical indicators: ${result.technicalCount}`);
+  console.log(`  User-facing indicators: ${result.userFacingCount}`);
+}
+
+module.exports = {
+  TECHNICAL_KEYWORDS,
+  USER_FACING_KEYWORDS,
+  classifyFeature,
+  parseStoryFlags,
+  shouldIncludeStories,
+  buildClassifiedQueueState,
+  logClassification
+};

package/src/feedback.js

@@ -3,6 +3,36 @@ const path = require('path');
 
 const CONFIG_FILE = '.claude/feedback-config.json';
 
+/**
+ * Normalizes abbreviated keys to full names.
+ * Converts "rec" to "recommendation" while preserving existing full key.
+ * @param {Object} feedback - Raw feedback object
+ * @returns {Object} - Normalized feedback object
+ */
+function normalizeFeedbackKeys(feedback) {
+  const normalized = { ...feedback };
+  if ('rec' in normalized && !('recommendation' in normalized)) {
+    normalized.recommendation = normalized.rec;
+    delete normalized.rec;
+  }
+  return normalized;
+}
+
+/**
+ * Parses FEEDBACK: JSON from agent output text.
+ * @param {string} output - Raw agent output
+ * @returns {Object|null} - Parsed feedback or null if not found/invalid
+ */
+function parseFeedbackFromOutput(output) {
+  const match = output.match(/FEEDBACK:\s*(\{[^}]+\})/);
+  if (!match) return null;
+  try {
+    return JSON.parse(match[1]);
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Returns the default feedback configuration.
  * Per FEATURE_SPEC.md defaults.
@@ -60,34 +90,32 @@ function writeConfig(config) {
 /**
  * Validates a feedback object against the schema.
  * Per FEATURE_SPEC.md:Rule 1.
+ * Accepts both "rec" and "recommendation" keys for recommendation field.
  * @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');
+  // Rating validation
+  if (typeof feedback.rating !== 'number' || !Number.isInteger(feedback.rating)) {
+    errors.push('rating must be an integer');
+  } else if (feedback.rating < 1 || feedback.rating > 5) {
+    errors.push('rating must be between 1 and 5');
   }
 
+  // Issues validation
   if (!Array.isArray(feedback.issues)) {
-    errors.push('Invalid "issues" field');
+    errors.push('issues must be an array');
+  } else if (!feedback.issues.every(i => typeof i === 'string')) {
+    errors.push('issues must be an array of strings');
   }
 
-  if (!['proceed', 'pause', 'revise'].includes(feedback.recommendation)) {
-    errors.push('Invalid "recommendation" field');
+  // Recommendation validation - accept both "rec" and "recommendation" keys
+  const rec = feedback.recommendation || feedback.rec;
+  const validRecs = ['proceed', 'pause', 'revise'];
+  if (!validRecs.includes(rec)) {
+    errors.push(`recommendation must be one of: ${validRecs.join(', ')}`);
   }
 
   return { valid: errors.length === 0, errors };
@@ -163,6 +191,8 @@ module.exports = {
   getDefaultConfig,
   readConfig,
   writeConfig,
+  normalizeFeedbackKeys,
+  parseFeedbackFromOutput,
   validateFeedback,
   shouldPause,
   setConfigValue,

package/src/handoff.js

@@ -0,0 +1,148 @@
+/**
+ * Handoff summary helper functions.
+ * Parses and validates handoff summary format for agent-to-agent communication.
+ */
+
+/**
+ * Parses a handoff summary and extracts key fields.
+ * @param {string} content - The handoff summary markdown content
+ * @returns {object} Parsed summary fields
+ */
+function parseHandoffSummary(content) {
+  return {
+    hasHeading: /^## Handoff Summary/m.test(content),
+    forField: content.match(/\*\*For:\*\*\s*(.+)/)?.[1]?.trim(),
+    featureField: content.match(/\*\*Feature:\*\*\s*(.+)/)?.[1]?.trim(),
+    hasKeyDecisions: /### Key Decisions/m.test(content),
+    hasFilesCreated: /### Files Created/m.test(content),
+    hasOpenQuestions: /### Open Questions/m.test(content),
+    hasCriticalContext: /### Critical Context/m.test(content),
+    lineCount: content.split('\n').length
+  };
+}
+
+/**
+ * Extracts a named section from the summary.
+ * @param {string} content - The handoff summary markdown content
+ * @param {string} sectionName - Name of the section (e.g., 'Key Decisions')
+ * @returns {string} The section content, or empty string if not found
+ */
+function extractSection(content, sectionName) {
+  const regex = new RegExp(`### ${sectionName}\\n([\\s\\S]*?)(?=\\n###|$)`);
+  const match = content.match(regex);
+  return match ? match[1].trim() : '';
+}
+
+/**
+ * Counts bullet items in a section.
+ * @param {string} section - Section content
+ * @returns {number} Number of bullet items
+ */
+function countBulletItems(section) {
+  return section.split('\n').filter(line => /^[-*]\s/.test(line)).length;
+}
+
+/**
+ * Extracts file paths from a section.
+ * @param {string} section - Section content
+ * @returns {string[]} Array of file paths
+ */
+function extractFilePaths(section) {
+  const lines = section.split('\n').filter(line => /^[-*]\s/.test(line));
+  return lines.map(line => line.replace(/^[-*]\s+/, '').trim());
+}
+
+/**
+ * Validates a handoff summary against format rules.
+ * @param {string} content - The handoff summary markdown content
+ * @returns {object} { valid: boolean, errors: string[] }
+ */
+function validateHandoffSummary(content) {
+  const errors = [];
+  const parsed = parseHandoffSummary(content);
+
+  if (!parsed.hasHeading) {
+    errors.push('Missing ## Handoff Summary heading');
+  }
+
+  if (!parsed.forField) {
+    errors.push('Missing **For:** field');
+  }
+
+  if (!parsed.featureField) {
+    errors.push('Missing **Feature:** field');
+  }
+
+  if (!parsed.hasKeyDecisions) {
+    errors.push('Missing ### Key Decisions section');
+  }
+
+  if (!parsed.hasFilesCreated) {
+    errors.push('Missing ### Files Created section');
+  }
+
+  if (!parsed.hasOpenQuestions) {
+    errors.push('Missing ### Open Questions section');
+  }
+
+  if (!parsed.hasCriticalContext) {
+    errors.push('Missing ### Critical Context section');
+  }
+
+  if (parsed.lineCount >= 30) {
+    errors.push(`Summary exceeds 30 lines (found ${parsed.lineCount})`);
+  }
+
+  // Validate Key Decisions bullet count
+  const keyDecisions = extractSection(content, 'Key Decisions');
+  const bulletCount = countBulletItems(keyDecisions);
+  if (bulletCount < 1 || bulletCount > 5) {
+    errors.push(`Key Decisions should have 1-5 items (found ${bulletCount})`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Returns the handoff file path for an agent.
+ * @param {string} featureDir - Feature directory path
+ * @param {string} agent - Agent name (alex, cass, nigel)
+ * @returns {string} Full path to handoff file
+ */
+function getHandoffPath(featureDir, agent) {
+  return `${featureDir}/handoff-${agent.toLowerCase()}.md`;
+}
+
+/**
+ * Generates a handoff summary template.
+ * @param {string} forAgent - Target agent name
+ * @param {string} featureSlug - Feature slug
+ * @returns {string} Template markdown content
+ */
+function getHandoffTemplate(forAgent, featureSlug) {
+  return `## Handoff Summary
+**For:** ${forAgent}
+**Feature:** ${featureSlug}
+
+### Key Decisions
+-
+
+### Files Created
+-
+
+### Open Questions
+- None
+
+### Critical Context
+`;
+}
+
+module.exports = {
+  parseHandoffSummary,
+  extractSection,
+  countBulletItems,
+  extractFilePaths,
+  validateHandoffSummary,
+  getHandoffPath,
+  getHandoffTemplate
+};

package/src/index.js

@@ -25,6 +25,32 @@ const {
   recommendThreshold,
   displayFeedbackInsights
 } = require('./insights');
+const {
+  parseHandoffSummary,
+  extractSection,
+  countBulletItems,
+  extractFilePaths,
+  validateHandoffSummary,
+  getHandoffPath,
+  getHandoffTemplate
+} = require('./handoff');
+const {
+  needsBusinessContext,
+  parseIncludeBusinessContextFlag,
+  shouldIncludeBusinessContext,
+  buildQueueState,
+  generateBusinessContextDirective
+} = require('./business-context');
+const {
+  classifyFeature,
+  parseStoryFlags,
+  shouldIncludeStories,
+  buildClassifiedQueueState,
+  logClassification,
+  TECHNICAL_KEYWORDS,
+  USER_FACING_KEYWORDS
+} = require('./classifier');
+const tools = require('./tools');
 
 module.exports = {
   init,
@@ -56,5 +82,29 @@ module.exports = {
   calculateCalibration,
   correlateIssues,
   recommendThreshold,
-  displayFeedbackInsights
+  displayFeedbackInsights,
+  // Handoff summary exports
+  parseHandoffSummary,
+  extractSection,
+  countBulletItems,
+  extractFilePaths,
+  validateHandoffSummary,
+  getHandoffPath,
+  getHandoffTemplate,
+  // Business context exports
+  needsBusinessContext,
+  parseIncludeBusinessContextFlag,
+  shouldIncludeBusinessContext,
+  buildQueueState,
+  generateBusinessContextDirective,
+  // Classifier module exports (smart story routing)
+  classifyFeature,
+  parseStoryFlags,
+  shouldIncludeStories,
+  buildClassifiedQueueState,
+  logClassification,
+  TECHNICAL_KEYWORDS,
+  USER_FACING_KEYWORDS,
+  // Tools module (model native features)
+  tools
 };

package/src/tools/index.js

@@ -0,0 +1,27 @@
+/**
+ * Tools Module - Model Native Features
+ * Exports tool schemas, validation, and prompt utilities
+ */
+
+const { FEEDBACK_TOOL_SCHEMA, HANDOFF_TOOL_SCHEMA } = require('./schemas');
+const { validateToolInput, normalizeFeedbackInput } = require('./validation');
+const {
+  buildPromptMessages,
+  identifyCacheableContent,
+  SYSTEM_PROMPT_TEMPLATE,
+  USER_PROMPT_TEMPLATE
+} = require('./prompts');
+
+module.exports = {
+  // Schemas
+  FEEDBACK_TOOL_SCHEMA,
+  HANDOFF_TOOL_SCHEMA,
+  // Validation
+  validateToolInput,
+  normalizeFeedbackInput,
+  // Prompts
+  buildPromptMessages,
+  identifyCacheableContent,
+  SYSTEM_PROMPT_TEMPLATE,
+  USER_PROMPT_TEMPLATE
+};

package/src/tools/prompts.js

@@ -0,0 +1,45 @@
+/**
+ * Prompt Structure Utilities
+ * Helpers for system/user prompt separation and caching
+ */
+
+const SYSTEM_PROMPT_TEMPLATE = {
+  role: 'system',
+  content: '[AGENT_SPEC]\n[GUARDRAILS]\n[TEMPLATES]',
+  cache_control: { type: 'ephemeral' }
+};
+
+const USER_PROMPT_TEMPLATE = {
+  role: 'user',
+  content: '[TASK_INSTRUCTIONS]\n[INPUTS]\n[OUTPUTS]'
+};
+
+/**
+ * Build prompt messages with system and user separation
+ * @param {string} staticContent - Content for system prompt (agent specs, guardrails)
+ * @param {string} dynamicContent - Content for user prompt (task instructions, inputs)
+ * @returns {Array<Object>} Array of message objects
+ */
+function buildPromptMessages(staticContent, dynamicContent) {
+  return [
+    { ...SYSTEM_PROMPT_TEMPLATE, content: staticContent },
+    { ...USER_PROMPT_TEMPLATE, content: dynamicContent }
+  ];
+}
+
+/**
+ * Identify if content should be cached (static, reusable content)
+ * @param {string} content - Content to analyze
+ * @returns {boolean} True if content is cacheable
+ */
+function identifyCacheableContent(content) {
+  const cacheablePatterns = ['AGENT_', 'GUARDRAIL', 'TEMPLATE', 'SPEC.md'];
+  return cacheablePatterns.some(p => content.includes(p));
+}
+
+module.exports = {
+  SYSTEM_PROMPT_TEMPLATE,
+  USER_PROMPT_TEMPLATE,
+  buildPromptMessages,
+  identifyCacheableContent
+};

package/src/tools/schemas.js

@@ -0,0 +1,38 @@
+/**
+ * Tool Schema Definitions
+ * Reusable schema constants for Claude tool use
+ */
+
+const FEEDBACK_TOOL_SCHEMA = {
+  name: 'submit_feedback',
+  description: 'Submit quality rating for prior stage',
+  input_schema: {
+    type: 'object',
+    properties: {
+      rating: { type: 'number', minimum: 1, maximum: 5 },
+      issues: { type: 'array', items: { type: 'string' } },
+      recommendation: { enum: ['proceed', 'pause', 'revise'] }
+    },
+    required: ['rating', 'issues', 'recommendation']
+  }
+};
+
+const HANDOFF_TOOL_SCHEMA = {
+  name: 'submit_handoff',
+  description: 'Submit summary for next agent',
+  input_schema: {
+    type: 'object',
+    properties: {
+      from_agent: { type: 'string', enum: ['alex', 'cass', 'nigel', 'codey'] },
+      to_agent: { type: 'string', enum: ['alex', 'cass', 'nigel', 'codey'] },
+      summary: { type: 'string', maxLength: 500 },
+      artifacts: { type: 'array', items: { type: 'string' } }
+    },
+    required: ['from_agent', 'to_agent', 'summary']
+  }
+};
+
+module.exports = {
+  FEEDBACK_TOOL_SCHEMA,
+  HANDOFF_TOOL_SCHEMA
+};

package/src/tools/validation.js

@@ -0,0 +1,83 @@
+/**
+ * Tool Input Validation Utilities
+ * Validates inputs against tool schema constraints
+ */
+
+/**
+ * Validate tool input against a schema
+ * @param {Object} schema - Tool schema with input_schema
+ * @param {Object} input - Input to validate
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateToolInput(schema, input) {
+  const errors = [];
+  const props = schema.input_schema.properties;
+  const required = schema.input_schema.required || [];
+
+  // Check required fields
+  for (const field of required) {
+    if (!(field in input)) {
+      errors.push(`missing required field: ${field}`);
+    }
+  }
+
+  // Validate each field
+  for (const [key, value] of Object.entries(input)) {
+    const propSchema = props[key];
+    if (!propSchema) continue;
+
+    // Type: number with bounds
+    if (propSchema.type === 'number') {
+      if (typeof value !== 'number') {
+        errors.push(`${key} must be number`);
+      } else {
+        if (propSchema.minimum !== undefined && value < propSchema.minimum) {
+          errors.push(`${key} below minimum ${propSchema.minimum}`);
+        }
+        if (propSchema.maximum !== undefined && value > propSchema.maximum) {
+          errors.push(`${key} above maximum ${propSchema.maximum}`);
+        }
+      }
+    }
+
+    // Type: array
+    if (propSchema.type === 'array') {
+      if (!Array.isArray(value)) {
+        errors.push(`${key} must be array`);
+      }
+    }
+
+    // Type: string with maxLength
+    if (propSchema.type === 'string') {
+      if (typeof value !== 'string') {
+        errors.push(`${key} must be string`);
+      } else if (propSchema.maxLength && value.length > propSchema.maxLength) {
+        errors.push(`${key} exceeds maxLength ${propSchema.maxLength}`);
+      }
+    }
+
+    // Enum constraint
+    if (propSchema.enum && !propSchema.enum.includes(value)) {
+      errors.push(`${key} must be one of: ${propSchema.enum.join(', ')}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Normalize feedback input to handle "rec" shorthand for "recommendation"
+ * @param {Object} input - Raw feedback input
+ * @returns {Object} - Normalized input
+ */
+function normalizeFeedbackInput(input) {
+  if (input.rec && !input.recommendation) {
+    return { ...input, recommendation: input.rec };
+  }
+  return input;
+}
+
+module.exports = {
+  validateToolInput,
+  normalizeFeedbackInput
+};