@girardmedia/bootspring 1.1.0

package/intelligence/prd.js

@@ -0,0 +1,447 @@
+#!/usr/bin/env node
+
+/**
+ * Bootspring PRD (Product Requirements Document) Manager
+ *
+ * Manages structured task files for autonomous loop execution.
+ * Compatible with Ralph's prd.json format.
+ *
+ * @package bootspring
+ * @module intelligence/prd
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * PRD Schema
+ *
+ * {
+ *   "name": "feature-name",
+ *   "description": "Feature description",
+ *   "created": "ISO timestamp",
+ *   "stories": [
+ *     {
+ *       "id": "story-1",
+ *       "title": "Short title",
+ *       "description": "Detailed description",
+ *       "acceptance": ["Criteria 1", "Criteria 2"],
+ *       "priority": 1,
+ *       "status": "pending|in_progress|complete|blocked",
+ *       "completedAt": null | "ISO timestamp"
+ *     }
+ *   ]
+ * }
+ */
+
+const DEFAULT_PRD_DIR = 'tasks';
+const DEFAULT_PRD_FILE = 'prd.json';
+
+/**
+ * Create a new PRD
+ */
+function createPRD(name, description, stories = []) {
+  return {
+    name,
+    description,
+    created: new Date().toISOString(),
+    updated: new Date().toISOString(),
+    stories: stories.map((story, index) => ({
+      id: story.id || `story-${index + 1}`,
+      title: story.title,
+      description: story.description || '',
+      acceptance: story.acceptance || [],
+      priority: story.priority || index + 1,
+      status: 'pending',
+      completedAt: null
+    }))
+  };
+}
+
+/**
+ * Load PRD from file
+ */
+function loadPRD(filePath = path.join(DEFAULT_PRD_DIR, DEFAULT_PRD_FILE)) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+  } catch (e) {
+    console.error(`Error loading PRD: ${e.message}`);
+    return null;
+  }
+}
+
+/**
+ * Save PRD to file
+ */
+function savePRD(prd, filePath = path.join(DEFAULT_PRD_DIR, DEFAULT_PRD_FILE)) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  prd.updated = new Date().toISOString();
+  fs.writeFileSync(filePath, JSON.stringify(prd, null, 2));
+  return filePath;
+}
+
+/**
+ * Get next incomplete story (highest priority)
+ */
+function getNextStory(prd) {
+  if (!prd || !prd.stories) return null;
+
+  return prd.stories
+    .filter(s => s.status === 'pending' || s.status === 'in_progress')
+    .sort((a, b) => a.priority - b.priority)[0] || null;
+}
+
+/**
+ * Update story status
+ */
+function updateStoryStatus(prd, storyId, status) {
+  const story = prd.stories.find(s => s.id === storyId);
+  if (!story) {
+    throw new Error(`Story not found: ${storyId}`);
+  }
+
+  story.status = status;
+  if (status === 'complete') {
+    story.completedAt = new Date().toISOString();
+  }
+
+  return prd;
+}
+
+/**
+ * Get PRD progress summary
+ */
+function getProgress(prd) {
+  if (!prd || !prd.stories) {
+    return { total: 0, complete: 0, pending: 0, blocked: 0, percent: 0 };
+  }
+
+  const total = prd.stories.length;
+  const complete = prd.stories.filter(s => s.status === 'complete').length;
+  const pending = prd.stories.filter(s => s.status === 'pending' || s.status === 'in_progress').length;
+  const blocked = prd.stories.filter(s => s.status === 'blocked').length;
+
+  return {
+    total,
+    complete,
+    pending,
+    blocked,
+    percent: total > 0 ? Math.round((complete / total) * 100) : 0
+  };
+}
+
+/**
+ * Check if all stories are complete
+ */
+function isComplete(prd) {
+  if (!prd || !prd.stories || prd.stories.length === 0) return false;
+  return prd.stories.every(s => s.status === 'complete');
+}
+
+/**
+ * Parse markdown PRD into structured format
+ * Converts human-readable PRD to prd.json
+ */
+function parseMarkdownPRD(markdown) {
+  const lines = markdown.split('\n');
+  const stories = [];
+
+  let currentStory = null;
+  let inAcceptance = false;
+  let name = '';
+  let description = '';
+  let sawTitle = false;
+
+  for (const line of lines) {
+    // Extract name from H1
+    if (line.startsWith('# ')) {
+      name = line.replace('# ', '').trim();
+      sawTitle = true;
+      continue;
+    }
+
+    // Extract top-level description (content after title and before first story heading)
+    if (sawTitle && !currentStory && line.trim() && !line.startsWith('#')) {
+      description += line.trim() + ' ';
+      continue;
+    }
+
+    // Acceptance criteria header (check BEFORE story header to avoid false matches)
+    if (line.match(/^#{3,4}\s+acceptance/i) || line.match(/^\*\*acceptance/i)) {
+      inAcceptance = true;
+      continue;
+    }
+
+    // Story header supports both manual PRDs (## Story X) and exported markdown (### [ ] Story)
+    const storyMatch = line.match(/^#{2,3}\s+(?:\[[ x!]\]\s*)?(?:Story\s+)?(\d+)?[:.]?\s*(.+)/i);
+    if (storyMatch && !line.match(/acceptance|criteria|progress/i)) {
+      if (currentStory) {
+        stories.push(currentStory);
+      }
+      currentStory = {
+        id: `story-${stories.length + 1}`,
+        title: storyMatch[2].trim(),
+        description: '',
+        acceptance: [],
+        priority: stories.length + 1
+      };
+      inAcceptance = false;
+      continue;
+    }
+
+    // Acceptance criteria items
+    if (inAcceptance && line.match(/^[-*]\s+/)) {
+      const criteria = line.replace(/^[-*]\s+/, '').trim();
+      if (criteria && currentStory) {
+        currentStory.acceptance.push(criteria);
+      }
+      continue;
+    }
+
+    // Story description (non-list content under story header)
+    if (currentStory && !inAcceptance && line.trim() && !line.startsWith('#')) {
+      currentStory.description += line.trim() + ' ';
+    }
+  }
+
+  // Don't forget last story
+  if (currentStory) {
+    stories.push(currentStory);
+  }
+
+  // Clean up descriptions
+  stories.forEach(s => {
+    s.description = s.description.trim();
+  });
+
+  return createPRD(name, description.trim(), stories);
+}
+
+/**
+ * Generate markdown from PRD
+ */
+function toMarkdown(prd) {
+  let md = `# ${prd.name}\n\n`;
+
+  if (prd.description) {
+    md += `${prd.description}\n\n`;
+  }
+
+  const progress = getProgress(prd);
+  md += `## Progress: ${progress.percent}% (${progress.complete}/${progress.total})\n\n`;
+
+  for (const story of prd.stories) {
+    const statusIcon = story.status === 'complete' ? '[x]' :
+                       story.status === 'blocked' ? '[!]' : '[ ]';
+
+    md += `### ${statusIcon} ${story.title}\n\n`;
+
+    if (story.description) {
+      md += `${story.description}\n\n`;
+    }
+
+    if (story.acceptance.length > 0) {
+      md += `**Acceptance Criteria:**\n`;
+      for (const criteria of story.acceptance) {
+        md += `- ${criteria}\n`;
+      }
+      md += '\n';
+    }
+  }
+
+  return md;
+}
+
+/**
+ * Validate story is right-sized for autonomous execution
+ * Stories should be completable in a single AI context window
+ */
+function validateStorySize(story) {
+  const warnings = [];
+
+  // Check title length (should be concise)
+  if (story.title.length > 100) {
+    warnings.push('Title too long - consider breaking down');
+  }
+
+  // Check for scope indicators (use word boundaries to avoid false positives)
+  const scopeIndicators = [
+    /\bentire\b/i, /\ball\s+(the|of)\b/i, /\bcomplete\s+system\b/i,
+    /\bfull\s+(system|implementation)\b/i, /\bwhole\b/i,
+    /\bauthentication system\b/i, /\bpayment system\b/i, /\buser management\b/i,
+    /\bbuild\s+(the|entire|full)\b/i
+  ];
+
+  const titleLower = story.title.toLowerCase();
+  const descLower = (story.description || '').toLowerCase();
+  const combined = `${titleLower} ${descLower}`;
+
+  for (const pattern of scopeIndicators) {
+    if (pattern.test(combined)) {
+      warnings.push(`Scope might be too large (matches pattern)`);
+      break; // Only add one scope warning
+    }
+  }
+
+  // Check acceptance criteria count
+  if (story.acceptance.length > 5) {
+    warnings.push('Many acceptance criteria - consider splitting');
+  }
+
+  return {
+    valid: warnings.length === 0,
+    warnings
+  };
+}
+
+// CLI
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  switch (command) {
+    case 'create': {
+      const name = args[1] || 'feature';
+      const prd = createPRD(name, 'Created by bootspring', [
+        { title: 'First task', description: 'Implement the first piece' },
+        { title: 'Second task', description: 'Implement the second piece' }
+      ]);
+      const filePath = savePRD(prd);
+      console.log(`Created PRD: ${filePath}`);
+      break;
+    }
+
+    case 'status': {
+      const prd = loadPRD(args[1]);
+      if (!prd) {
+        console.error('PRD not found');
+        process.exit(1);
+      }
+      const progress = getProgress(prd);
+      console.log(`PRD: ${prd.name}`);
+      console.log(`Progress: ${progress.percent}% (${progress.complete}/${progress.total})`);
+      console.log(`Pending: ${progress.pending} | Blocked: ${progress.blocked}`);
+
+      const next = getNextStory(prd);
+      if (next) {
+        console.log(`\nNext story: ${next.title}`);
+      }
+      break;
+    }
+
+    case 'next': {
+      const prd = loadPRD(args[1]);
+      if (!prd) {
+        console.error('PRD not found');
+        process.exit(1);
+      }
+      const next = getNextStory(prd);
+      if (next) {
+        console.log(JSON.stringify(next, null, 2));
+      } else {
+        console.log('No pending stories');
+      }
+      break;
+    }
+
+    case 'complete': {
+      const storyId = args[1];
+      const prdPath = args[2] || path.join(DEFAULT_PRD_DIR, DEFAULT_PRD_FILE);
+
+      if (!storyId) {
+        console.error('Usage: prd.js complete <story-id> [prd-path]');
+        process.exit(1);
+      }
+
+      const prd = loadPRD(prdPath);
+      if (!prd) {
+        console.error('PRD not found');
+        process.exit(1);
+      }
+
+      updateStoryStatus(prd, storyId, 'complete');
+      savePRD(prd, prdPath);
+      console.log(`Marked ${storyId} as complete`);
+
+      if (isComplete(prd)) {
+        console.log('\nAll stories complete!');
+      }
+      break;
+    }
+
+    case 'parse': {
+      const mdPath = args[1];
+      if (!mdPath || !fs.existsSync(mdPath)) {
+        console.error('Usage: prd.js parse <markdown-file>');
+        process.exit(1);
+      }
+
+      const markdown = fs.readFileSync(mdPath, 'utf-8');
+      const prd = parseMarkdownPRD(markdown);
+
+      // Validate stories
+      console.log(`Parsed PRD: ${prd.name}`);
+      console.log(`Stories: ${prd.stories.length}\n`);
+
+      for (const story of prd.stories) {
+        const validation = validateStorySize(story);
+        console.log(`- ${story.title}`);
+        if (!validation.valid) {
+          validation.warnings.forEach(w => console.log(`  ⚠️  ${w}`));
+        }
+      }
+
+      // Save
+      const outPath = savePRD(prd);
+      console.log(`\nSaved to: ${outPath}`);
+      break;
+    }
+
+    case 'markdown': {
+      const prd = loadPRD(args[1]);
+      if (!prd) {
+        console.error('PRD not found');
+        process.exit(1);
+      }
+      console.log(toMarkdown(prd));
+      break;
+    }
+
+    default:
+      console.log(`
+Bootspring PRD Manager
+
+Usage:
+  prd.js create [name]           Create new PRD
+  prd.js status [path]           Show PRD progress
+  prd.js next [path]             Get next story as JSON
+  prd.js complete <id> [path]    Mark story complete
+  prd.js parse <markdown>        Convert markdown to prd.json
+  prd.js markdown [path]         Convert prd.json to markdown
+`);
+  }
+}
+
+module.exports = {
+  createPRD,
+  loadPRD,
+  savePRD,
+  getNextStory,
+  updateStoryStatus,
+  getProgress,
+  isComplete,
+  parseMarkdownPRD,
+  toMarkdown,
+  validateStorySize,
+  DEFAULT_PRD_DIR,
+  DEFAULT_PRD_FILE
+};

package/intelligence/recommendation-weights.json

@@ -0,0 +1,18 @@
+{
+  "workflow": {
+    "base": 10,
+    "completed": 6,
+    "started": 2,
+    "checkpointCap": 10,
+    "completionRateMultiplier": 20,
+    "contextMatch": 12,
+    "packBonus": 3,
+    "premiumUnlock": 4
+  },
+  "skill": {
+    "base": 25,
+    "usage": 4,
+    "premiumUnlock": 3
+  },
+  "eventWindowLimit": 1000
+}

package/intelligence/recommendations.js

@@ -0,0 +1,234 @@
+/**
+ * Recommendation engine v1
+ * Ranks workflows and skills from context + telemetry outcomes.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_WEIGHTS_PATH = path.join(__dirname, 'recommendation-weights.json');
+
+function tokenize(text) {
+  return String(text || '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/g)
+    .filter(Boolean);
+}
+
+function buildWorkflowStats(events) {
+  const stats = new Map();
+
+  for (const event of events) {
+    const workflow = event?.payload?.workflow;
+    if (!workflow) continue;
+    if (!stats.has(workflow)) {
+      stats.set(workflow, {
+        started: 0,
+        completed: 0,
+        checkpoints: 0,
+        premiumUnlocks: 0,
+        lastEventAt: null
+      });
+    }
+    const current = stats.get(workflow);
+    if (event.event === 'workflow_started') current.started += 1;
+    if (event.event === 'workflow_completed') current.completed += 1;
+    if (event.event === 'workflow_checkpoint_completed' || event.event === 'pack_signal_checkpoint') {
+      current.checkpoints += 1;
+    }
+    if (event.event === 'premium_unlocked') {
+      current.premiumUnlocks += 1;
+    }
+    current.lastEventAt = event.timestamp || current.lastEventAt;
+  }
+
+  return stats;
+}
+
+function buildSkillUsage(events) {
+  const usage = new Map();
+  const premiumUnlocks = new Map();
+  for (const event of events) {
+    const skillId = event?.payload?.skillId;
+    if (!skillId) continue;
+    usage.set(skillId, (usage.get(skillId) || 0) + 1);
+    if (event.event === 'premium_unlocked') {
+      premiumUnlocks.set(skillId, (premiumUnlocks.get(skillId) || 0) + 1);
+    }
+  }
+  return { usage, premiumUnlocks };
+}
+
+function workflowMatchesContext(workflow, tokens) {
+  if (tokens.length === 0) return false;
+  const haystack = [
+    workflow.name,
+    workflow.description,
+    ...(workflow.outcomes || []),
+    ...(workflow.completionSignals || [])
+  ]
+    .join(' ')
+    .toLowerCase();
+
+  return tokens.some(token => haystack.includes(token));
+}
+
+function mergeWeights(overrides = {}) {
+  let base = {};
+  try {
+    if (fs.existsSync(DEFAULT_WEIGHTS_PATH)) {
+      base = JSON.parse(fs.readFileSync(DEFAULT_WEIGHTS_PATH, 'utf-8'));
+    }
+  } catch {
+    base = {};
+  }
+  return {
+    workflow: {
+      ...(base.workflow || {}),
+      ...((overrides.workflow) || {})
+    },
+    skill: {
+      ...(base.skill || {}),
+      ...((overrides.skill) || {})
+    },
+    eventWindowLimit: Number(overrides.eventWindowLimit || base.eventWindowLimit || 1000)
+  };
+}
+
+function resolveWeights(options = {}) {
+  if (options.weights && typeof options.weights === 'object') {
+    return mergeWeights(options.weights);
+  }
+
+  const customPath = options.weightsPath || process.env.BOOTSPRING_RECOMMENDATION_WEIGHTS_PATH;
+  if (customPath) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(customPath, 'utf-8'));
+      return mergeWeights(raw);
+    } catch {
+      return mergeWeights({});
+    }
+  }
+
+  return mergeWeights({});
+}
+
+function createRecommendationsEngine({ intelligence, telemetry, skills, entitlements, weights }) {
+  const resolvedWeights = resolveWeights({ weights });
+
+  return {
+    recommend({ contextText = '', limit = 5, accessOptions = {} } = {}) {
+      const parsedLimit = Number(limit);
+      const maxItems = Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : 5;
+      const events = telemetry.listEvents({ limit: resolvedWeights.eventWindowLimit });
+      const analysis = intelligence.analyzeContext(contextText || '');
+      const tokens = tokenize(contextText);
+      const workflowStats = buildWorkflowStats(events);
+      const skillStats = buildSkillUsage(events);
+
+      const available = intelligence.listWorkflows();
+      const accessible = entitlements.filterAccessibleWorkflows(available, accessOptions).allowed;
+      const workflows = accessible
+        .map(workflow => {
+          const stats = workflowStats.get(workflow.key) || {
+            started: 0,
+            completed: 0,
+            checkpoints: 0,
+            premiumUnlocks: 0,
+            lastEventAt: null
+          };
+
+          const completionRate = stats.started > 0 ? (stats.completed / stats.started) : 0;
+          let score = Number(resolvedWeights.workflow.base || 10)
+            + (stats.completed * Number(resolvedWeights.workflow.completed || 6))
+            + (stats.started * Number(resolvedWeights.workflow.started || 2))
+            + Math.min(Number(resolvedWeights.workflow.checkpointCap || 10), stats.checkpoints);
+          const reasons = [];
+
+          if (stats.completed > 0) reasons.push(`completed ${stats.completed} time(s)`);
+          if (completionRate > 0) {
+            score += Math.round(completionRate * Number(resolvedWeights.workflow.completionRateMultiplier || 20));
+            reasons.push(`completion rate ${(completionRate * 100).toFixed(0)}%`);
+          }
+          if (workflowMatchesContext(workflow, tokens)) {
+            score += Number(resolvedWeights.workflow.contextMatch || 12);
+            reasons.push('matches current context');
+          }
+          if (workflow.pack) {
+            score += Number(resolvedWeights.workflow.packBonus || 3);
+          }
+          if (stats.premiumUnlocks > 0) {
+            score += stats.premiumUnlocks * Number(resolvedWeights.workflow.premiumUnlock || 4);
+            reasons.push(`premium unlocks ${stats.premiumUnlocks}`);
+          }
+
+          return {
+            key: workflow.key,
+            name: workflow.name,
+            tier: workflow.tier || 'free',
+            pack: workflow.pack || null,
+            score,
+            reasons,
+            metrics: {
+              started: stats.started,
+              completed: stats.completed,
+              checkpoints: stats.checkpoints,
+              premiumUnlocks: stats.premiumUnlocks,
+              completionRate
+            }
+          };
+        })
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxItems);
+
+      const contextSkillIds = Array.from(new Set(analysis.skills || []));
+      let availableSkillIds = skills.listSkills({ includeExternal: true });
+      availableSkillIds = entitlements.filterAccessibleSkills(availableSkillIds, accessOptions).allowed;
+      const availableSkillSet = new Set(availableSkillIds);
+
+      const skillsRanked = contextSkillIds
+        .filter(skillId => availableSkillSet.has(skillId))
+        .map(skillId => {
+          const metadata = skills.getSkillMetadata(skillId) || {};
+          const usage = skillStats.usage.get(skillId) || 0;
+          const premiumUnlocks = skillStats.premiumUnlocks.get(skillId) || 0;
+          return {
+            id: skillId,
+            name: metadata.name || skillId,
+            description: metadata.description || '',
+            source: metadata.source || 'built-in',
+            score: Number(resolvedWeights.skill.base || 25)
+              + (usage * Number(resolvedWeights.skill.usage || 4))
+              + (premiumUnlocks * Number(resolvedWeights.skill.premiumUnlock || 3)),
+            reasons: [
+              'suggested by context analysis',
+              ...(usage > 0 ? [`used ${usage} time(s) in prior sessions`] : []),
+              ...(premiumUnlocks > 0 ? [`premium unlocks ${premiumUnlocks}`] : [])
+            ]
+          };
+        })
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxItems);
+
+      return {
+        context: {
+          phase: analysis.phase,
+          phaseName: analysis.phaseConfig?.name,
+          suggestions: analysis.suggestions
+        },
+        workflows,
+        skills: skillsRanked,
+        telemetryWindow: {
+          eventsAnalyzed: events.length
+        },
+        weights: resolvedWeights
+      };
+    }
+  };
+}
+
+module.exports = {
+  createRecommendationsEngine,
+  resolveWeights,
+  mergeWeights
+};