guild-agents 1.2.0 → 1.4.0

package/src/templates/skills/session-end/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "skill": "session-end",
+  "matcherType": "keyword",
+  "description": "Saves current state to SESSION.md",
+  "threshold": 0.3,
+  "tests": [
+    { "prompt": "save the session state", "shouldTrigger": true },
+    { "prompt": "end my session and save to SESSION.md", "shouldTrigger": true },
+    { "prompt": "save current state to SESSION", "shouldTrigger": true },
+    { "prompt": "I'm done for today, save my progress", "shouldTrigger": true, "keywordExpected": false },
+    { "prompt": "start my session", "shouldTrigger": false },
+    { "prompt": "create a pull request", "shouldTrigger": false },
+    { "prompt": "review my code", "shouldTrigger": false },
+    { "prompt": "debug this bug", "shouldTrigger": false }
+  ]
+}

package/src/templates/skills/session-start/evals/evals.json

@@ -0,0 +1,50 @@
+{
+  "skill": "session-start",
+  "evals": [
+    {
+      "id": "ss-has-core-steps",
+      "description": "Session start has load, detect, present, suggest, update steps",
+      "expectations": [
+        { "text": "Has load-context step", "assertion": "step-exists:load-context" },
+        { "text": "Has detect-resumable step", "assertion": "step-exists:detect-resumable" },
+        { "text": "Has present-state step", "assertion": "step-exists:present-state" },
+        { "text": "Has suggest-continuation step", "assertion": "step-exists:suggest-continuation" },
+        { "text": "Has update-session step", "assertion": "step-exists:update-session" }
+      ]
+    },
+    {
+      "id": "ss-all-system",
+      "description": "All steps are system role",
+      "expectations": [
+        { "text": "load-context is system", "assertion": "step-role:load-context:system" },
+        { "text": "detect-resumable is system", "assertion": "step-role:detect-resumable:system" },
+        { "text": "present-state is system", "assertion": "step-role:present-state:system" },
+        { "text": "suggest-continuation is system", "assertion": "step-role:suggest-continuation:system" },
+        { "text": "update-session is system", "assertion": "step-role:update-session:system" }
+      ]
+    },
+    {
+      "id": "ss-gates",
+      "description": "Gates at presentation, suggestion, and session update",
+      "expectations": [
+        { "text": "present-state has gate", "assertion": "gate-exists:present-state" },
+        { "text": "suggest-continuation has gate", "assertion": "gate-exists:suggest-continuation" },
+        { "text": "update-session has gate", "assertion": "gate-exists:update-session" }
+      ]
+    },
+    {
+      "id": "ss-detect-requires-session",
+      "description": "Detect-resumable requires session state",
+      "expectations": [
+        { "text": "detect-resumable requires session-md", "assertion": "step-requires:detect-resumable:session-md" }
+      ]
+    },
+    {
+      "id": "ss-minimum-steps",
+      "description": "Has at least 5 steps",
+      "expectations": [
+        { "text": "At least 5 steps", "assertion": "step-count:5" }
+      ]
+    }
+  ]
+}

package/src/templates/skills/session-start/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "skill": "session-start",
+  "matcherType": "keyword",
+  "description": "Loads context and resumes work from SESSION.md",
+  "threshold": 0.3,
+  "tests": [
+    { "prompt": "load my session context", "shouldTrigger": true },
+    { "prompt": "resume work from SESSION.md", "shouldTrigger": true },
+    { "prompt": "start session and load context", "shouldTrigger": true },
+    { "prompt": "where did I leave off", "shouldTrigger": true, "keywordExpected": false },
+    { "prompt": "save my progress", "shouldTrigger": false },
+    { "prompt": "create a new feature", "shouldTrigger": false },
+    { "prompt": "review my code", "shouldTrigger": false },
+    { "prompt": "run the tests", "shouldTrigger": false }
+  ]
+}

package/src/templates/skills/status/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill": "status",
+  "evals": [
+    {
+      "id": "st-has-core-steps",
+      "description": "Status has read-state, scan-resources, present steps",
+      "expectations": [
+        { "text": "Has read-state step", "assertion": "step-exists:read-state" },
+        { "text": "Has scan-resources step", "assertion": "step-exists:scan-resources" },
+        { "text": "Has present-status step", "assertion": "step-exists:present-status" }
+      ]
+    },
+    {
+      "id": "st-all-system",
+      "description": "All steps are system role",
+      "expectations": [
+        { "text": "read-state is system", "assertion": "step-role:read-state:system" },
+        { "text": "scan-resources is system", "assertion": "step-role:scan-resources:system" },
+        { "text": "present-status is system", "assertion": "step-role:present-status:system" }
+      ]
+    },
+    {
+      "id": "st-presentation-gate",
+      "description": "Present-status has gate",
+      "expectations": [
+        { "text": "present-status has gate", "assertion": "gate-exists:present-status" }
+      ]
+    },
+    {
+      "id": "st-dependencies",
+      "description": "Present-status requires project and session data",
+      "expectations": [
+        { "text": "present-status requires project-md", "assertion": "step-requires:present-status:project-md" },
+        { "text": "present-status requires session-md", "assertion": "step-requires:present-status:session-md" },
+        { "text": "present-status requires agent-list", "assertion": "step-requires:present-status:agent-list" },
+        { "text": "present-status requires skill-list", "assertion": "step-requires:present-status:skill-list" }
+      ]
+    }
+  ]
+}

package/src/templates/skills/status/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "skill": "status",
+  "matcherType": "keyword",
+  "description": "Shows current project and session state",
+  "threshold": 0.3,
+  "tests": [
+    { "prompt": "show the project status", "shouldTrigger": true },
+    { "prompt": "show current session state", "shouldTrigger": true },
+    { "prompt": "what is the current project state", "shouldTrigger": true },
+    { "prompt": "how is the project going", "shouldTrigger": true },
+    { "prompt": "create a pull request", "shouldTrigger": false },
+    { "prompt": "review my code", "shouldTrigger": false },
+    { "prompt": "debug this bug", "shouldTrigger": false },
+    { "prompt": "save my session", "shouldTrigger": false }
+  ]
+}

package/src/templates/skills/tdd/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "skill": "tdd",
+  "matcherType": "keyword",
+  "description": "Discipline skill — TDD red-green-refactor cycle. Use when implementing any feature or bugfix, before writing implementation code.",
+  "threshold": 0.3,
+  "tests": [
+    { "prompt": "use TDD for this implementation", "shouldTrigger": true },
+    { "prompt": "red green refactor cycle", "shouldTrigger": true },
+    { "prompt": "follow the TDD red-green-refactor discipline", "shouldTrigger": true },
+    { "prompt": "implement this feature with TDD", "shouldTrigger": true },
+    { "prompt": "create a pull request", "shouldTrigger": false },
+    { "prompt": "review my code", "shouldTrigger": false },
+    { "prompt": "save my session", "shouldTrigger": false },
+    { "prompt": "show project status", "shouldTrigger": false }
+  ]
+}

package/src/templates/skills/verify/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "skill": "verify",
+  "matcherType": "keyword",
+  "description": "Discipline skill — verification before completion. Use when about to claim work is complete, fixed, or passing, before committing or creating PRs.",
+  "threshold": 0.3,
+  "tests": [
+    { "prompt": "verify before committing", "shouldTrigger": true },
+    { "prompt": "run verification before completion", "shouldTrigger": true },
+    { "prompt": "verify the work is complete", "shouldTrigger": true },
+    { "prompt": "make sure everything passes before the PR", "shouldTrigger": true, "keywordExpected": false },
+    { "prompt": "create a pull request", "shouldTrigger": false },
+    { "prompt": "review my code", "shouldTrigger": false },
+    { "prompt": "debug this bug", "shouldTrigger": false },
+    { "prompt": "save my session", "shouldTrigger": false }
+  ]
+}

package/src/utils/accounting.js

@@ -0,0 +1,139 @@
+/**
+ * accounting.js — Token usage recording, persistence, and aggregation.
+ *
+ * Persists usage data to .claude/guild/usage.json.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { estimateCost } from './pricing.js';
+
+const USAGE_PATH = join('.claude', 'guild', 'usage.json');
+
+export function emptyUsage() {
+  return {
+    version: 1,
+    lastUpdated: new Date().toISOString(),
+    entries: [],
+    totals: {
+      totalTokens: 0,
+      totalInputTokens: 0,
+      totalOutputTokens: 0,
+      totalCostUSD: 0,
+      tokensByModel: {},
+      tokensByTier: {},
+      tokensByWorkflow: {},
+      workflowCount: 0,
+    },
+  };
+}
+
+export function createEntry({ workflow, agent, tier, model, inputTokens, outputTokens }) {
+  const totalTokens = inputTokens + outputTokens;
+  return {
+    timestamp: new Date().toISOString(),
+    workflow,
+    agent,
+    tier,
+    model,
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    estimatedCostUSD: estimateCost(model, inputTokens, outputTokens),
+  };
+}
+
+export function loadUsage(root) {
+  const filePath = join(root, USAGE_PATH);
+  if (!existsSync(filePath)) return emptyUsage();
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return emptyUsage();
+  }
+}
+
+export function saveUsage(root, usage) {
+  const filePath = join(root, USAGE_PATH);
+  mkdirSync(dirname(filePath), { recursive: true });
+  usage.lastUpdated = new Date().toISOString();
+  writeFileSync(filePath, JSON.stringify(usage, null, 2) + '\n');
+}
+
+function updateTotals(totals, entry) {
+  totals.totalTokens += entry.totalTokens;
+  totals.totalInputTokens += entry.inputTokens;
+  totals.totalOutputTokens += entry.outputTokens;
+  totals.totalCostUSD += entry.estimatedCostUSD;
+  totals.tokensByModel[entry.model] = (totals.tokensByModel[entry.model] || 0) + entry.totalTokens;
+  totals.tokensByTier[entry.tier] = (totals.tokensByTier[entry.tier] || 0) + entry.totalTokens;
+  totals.tokensByWorkflow[entry.workflow] = (totals.tokensByWorkflow[entry.workflow] || 0) + entry.totalTokens;
+  totals.workflowCount += 1;
+}
+
+export function recordStep(root, params) {
+  const usage = loadUsage(root);
+  const entry = createEntry(params);
+  usage.entries.push(entry);
+  updateTotals(usage.totals, entry);
+  saveUsage(root, usage);
+}
+
+const PROFILES = {
+  max: { reasoning: 'claude-opus-4-6', execution: 'claude-sonnet-4-5', routine: 'claude-haiku-4-5' },
+  pro: { reasoning: 'claude-sonnet-4-5', execution: 'claude-sonnet-4-5', routine: 'claude-haiku-4-5' },
+  'all-opus': { reasoning: 'claude-opus-4-6', execution: 'claude-opus-4-6', routine: 'claude-opus-4-6' },
+};
+
+export function aggregate(root, period) {
+  const usage = loadUsage(root);
+  const now = new Date();
+  let cutoff;
+
+  switch (period) {
+    case 'today':
+      cutoff = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+      break;
+    case 'week':
+      cutoff = new Date(now);
+      cutoff.setDate(cutoff.getDate() - 7);
+      break;
+    case 'month':
+      cutoff = new Date(now);
+      cutoff.setDate(cutoff.getDate() - 30);
+      break;
+    default:
+      cutoff = new Date(0);
+  }
+
+  const filtered = usage.entries.filter(e => new Date(e.timestamp) >= cutoff);
+
+  const totals = {
+    totalTokens: 0,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalCostUSD: 0,
+    tokensByModel: {},
+    tokensByTier: {},
+    tokensByWorkflow: {},
+    workflowCount: 0,
+  };
+
+  for (const entry of filtered) {
+    updateTotals(totals, entry);
+  }
+
+  return totals;
+}
+
+export function estimateWithProfile(entries, profileName) {
+  const profile = PROFILES[profileName];
+  if (!profile) return 0;
+
+  let cost = 0;
+  for (const entry of entries) {
+    const model = profile[entry.tier] || entry.model;
+    cost += estimateCost(model, entry.inputTokens, entry.outputTokens);
+  }
+  return cost;
+}

package/src/utils/benchmark.js

@@ -0,0 +1,128 @@
+/**
+ * benchmark.js — Records, reports, and detects regressions in eval benchmarks.
+ *
+ * Persists results to benchmarks/benchmark.json with 30-entry rotation.
+ * Generates benchmarks/benchmark.md as a human-readable report.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+const MAX_ENTRIES = 30;
+
+/**
+ * Appends a benchmark entry to the JSON file, rotating old entries.
+ * @param {object} entry - Benchmark entry with timestamp, matcher, skills, aggregate
+ * @param {string} filePath - Path to benchmark.json
+ */
+export function recordBenchmark(entry, filePath) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  let entries = [];
+  if (existsSync(filePath)) {
+    entries = JSON.parse(readFileSync(filePath, 'utf8'));
+  }
+
+  entries.push(entry);
+
+  if (entries.length > MAX_ENTRIES) {
+    entries = entries.slice(entries.length - MAX_ENTRIES);
+  }
+
+  writeFileSync(filePath, JSON.stringify(entries, null, 2));
+}
+
+/**
+ * Generates a markdown report from a benchmark entry.
+ * @param {object} current - Current benchmark entry
+ * @param {object|null} previous - Previous entry for delta comparison
+ * @returns {string} Markdown report
+ */
+export function generateReport(current, previous) {
+  const lines = [];
+  const date = current.timestamp;
+  const matcher = current.matcher;
+  const model = current.model ? ` (${current.model})` : '';
+
+  lines.push(`# Eval Benchmark — ${date}`);
+  lines.push(`Matcher: ${matcher}${model} | Skills: ${current.skills.length} | Total tests: ${current.aggregate.total}`);
+  lines.push('');
+  lines.push('| Skill | Accuracy | Precision | Recall | Delta |');
+  lines.push('|-------|----------|-----------|--------|-------|');
+
+  for (const skill of current.skills) {
+    let delta = '—';
+    if (previous) {
+      const prev = previous.skills.find(s => s.name === skill.name);
+      if (prev) {
+        const diff = (skill.accuracy - prev.accuracy) * 100;
+        if (Math.abs(diff) >= 0.1) {
+          const sign = diff > 0 ? '+' : '';
+          const warn = diff < -5 ? ' !!' : '';
+          delta = `${sign}${diff.toFixed(1)}%${warn}`;
+        }
+      }
+    }
+
+    lines.push(`| ${skill.name} | ${(skill.accuracy * 100).toFixed(1)}% | ${(skill.precision * 100).toFixed(1)}% | ${(skill.recall * 100).toFixed(1)}% | ${delta} |`);
+  }
+
+  lines.push('');
+  lines.push('## Aggregate');
+
+  let aggDelta = '';
+  if (previous) {
+    const diff = (current.aggregate.accuracy - previous.aggregate.accuracy) * 100;
+    if (Math.abs(diff) >= 0.1) {
+      const sign = diff > 0 ? '+' : '';
+      aggDelta = ` (Delta ${sign}${diff.toFixed(1)}%)`;
+    }
+  }
+
+  lines.push(`Accuracy: ${(current.aggregate.accuracy * 100).toFixed(1)}%${aggDelta}`);
+  lines.push(`Precision: ${(current.aggregate.precision * 100).toFixed(1)}%`);
+  lines.push(`Recall: ${(current.aggregate.recall * 100).toFixed(1)}%`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Detects regressions between two benchmark entries.
+ * A regression is: accuracy dropped >5% AND at least 2 tests flipped.
+ * @param {object} current
+ * @param {object|null} previous
+ * @returns {Array<{ skill: string, currentAccuracy: number, previousAccuracy: number, delta: number, flippedTests: number }>}
+ */
+export function detectRegressions(current, previous) {
+  if (!previous) return [];
+
+  const regressions = [];
+
+  for (const skill of current.skills) {
+    const prev = previous.skills.find(s => s.name === skill.name);
+    if (!prev) continue;
+
+    const delta = skill.accuracy - prev.accuracy;
+    if (delta > -0.05) continue;
+
+    const currentCorrect = skill.tp + skill.tn;
+    const prevCorrect = prev.tp + prev.tn;
+    const flippedTests = Math.abs(currentCorrect - prevCorrect);
+
+    if (flippedTests < 2) continue;
+
+    regressions.push({
+      skill: skill.name,
+      currentAccuracy: skill.accuracy,
+      previousAccuracy: prev.accuracy,
+      delta,
+      flippedTests,
+    });
+  }
+
+  return regressions;
+}

package/src/utils/description-analyzer.js

@@ -0,0 +1,92 @@
+/**
+ * description-analyzer.js — Analyzes keyword gaps in skill descriptions.
+ *
+ * Uses token analysis to identify which keywords are missing from
+ * skill descriptions based on failed trigger tests. No LLM required.
+ */
+
+import { tokenize } from './trigger-matcher.js';
+
+const STOP_WORDS = new Set([
+  'the', 'is', 'at', 'in', 'on', 'to', 'of', 'for', 'and', 'or', 'an',
+  'it', 'by', 'as', 'be', 'do', 'if', 'no', 'so', 'up', 'we', 'my',
+  'use', 'when', 'with', 'from', 'this', 'that', 'will', 'can', 'has',
+  'not', 'are', 'was', 'but', 'all', 'any', 'its', 'you', 'your',
+  'want', 'need', 'just', 'let', 'get', 'make', 'help', 'me',
+]);
+
+/**
+ * Checks if a token matches any description token (full or substring).
+ */
+function tokenMatchesDescription(token, descTokens) {
+  for (const dt of descTokens) {
+    if (dt === token || dt.includes(token) || token.includes(dt)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Analyzes gaps between failed trigger prompts and a skill description.
+ * @param {Array} triggerResults - Results from runTriggerTests
+ * @param {string} description - Skill description
+ * @returns {{ missingKeywords: string[], failedPrompts: string[] }}
+ */
+export function analyzeGaps(triggerResults, description) {
+  const failedPositives = triggerResults.filter(r => r.expected && !r.actual);
+
+  if (failedPositives.length === 0) {
+    return { missingKeywords: [], failedPrompts: [] };
+  }
+
+  const descTokens = tokenize(description).filter(w => !STOP_WORDS.has(w));
+  const missingKeywords = [];
+  const failedPrompts = [];
+
+  for (const result of failedPositives) {
+    failedPrompts.push(result.prompt);
+    const promptTokens = tokenize(result.prompt).filter(w => !STOP_WORDS.has(w));
+
+    for (const token of promptTokens) {
+      if (!tokenMatchesDescription(token, descTokens)) {
+        missingKeywords.push(token);
+      }
+    }
+  }
+
+  return { missingKeywords, failedPrompts };
+}
+
+/**
+ * Generates keyword suggestions from gap analysis results.
+ * @param {Array<{ skill: string, currentDescription: string, missingKeywords: string[], failedPrompts: string[] }>} gapsList
+ * @returns {Array<{ skill: string, currentDescription: string, suggestedKeywords: Array<{ word: string, confidence: string }> }>}
+ */
+export function generateSuggestions(gapsList) {
+  const suggestions = [];
+
+  for (const gaps of gapsList) {
+    if (gaps.missingKeywords.length === 0) continue;
+
+    const freq = new Map();
+    for (const word of gaps.missingKeywords) {
+      freq.set(word, (freq.get(word) || 0) + 1);
+    }
+
+    const suggestedKeywords = [...freq.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .map(([word, count]) => ({
+        word,
+        confidence: count >= 2 ? 'high' : 'medium',
+      }));
+
+    suggestions.push({
+      skill: gaps.skill,
+      currentDescription: gaps.currentDescription,
+      suggestedKeywords,
+    });
+  }
+
+  return suggestions;
+}

package/src/utils/eval-runner.js

@@ -0,0 +1,139 @@
+/**
+ * eval-runner.js — Skill evaluation framework for Guild.
+ *
+ * Runs assertions against parsed skill workflows to verify
+ * structural correctness. Compatible with anthropics/skills eval format.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { parseSkill } from './workflow-parser.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, '..', 'templates', 'skills');
+
+/**
+ * Evaluates a single assertion against a parsed workflow.
+ * @param {object} workflow - Parsed workflow with { version, steps[] }
+ * @param {string} assertion - Assertion string (e.g. "step-exists:evaluate")
+ * @returns {{ passed: boolean, evidence: string }}
+ */
+export function evaluateAssertion(workflow, assertion) {
+  const colonIdx = assertion.indexOf(':');
+  if (colonIdx === -1) {
+    return { passed: false, evidence: `Malformed assertion: "${assertion}"` };
+  }
+
+  const type = assertion.slice(0, colonIdx);
+  const args = assertion.slice(colonIdx + 1);
+
+  switch (type) {
+    case 'step-exists': {
+      const step = workflow.steps.find(s => s.id === args);
+      return step
+        ? { passed: true, evidence: `Step "${args}" found` }
+        : { passed: false, evidence: `Step "${args}" not found in ${workflow.steps.map(s => s.id).join(', ')}` };
+    }
+
+    case 'step-role': {
+      const [stepId, expectedRole] = args.split(':');
+      const step = workflow.steps.find(s => s.id === stepId);
+      if (!step) return { passed: false, evidence: `Step "${stepId}" not found` };
+      return step.role === expectedRole
+        ? { passed: true, evidence: `Step "${stepId}" has role "${expectedRole}"` }
+        : { passed: false, evidence: `Step "${stepId}" has role "${step.role}", expected "${expectedRole}"` };
+    }
+
+    case 'step-model-tier': {
+      const [stepId, expectedTier] = args.split(':');
+      const step = workflow.steps.find(s => s.id === stepId);
+      if (!step) return { passed: false, evidence: `Step "${stepId}" not found` };
+      return step.modelTier === expectedTier
+        ? { passed: true, evidence: `Step "${stepId}" uses tier "${expectedTier}"` }
+        : { passed: false, evidence: `Step "${stepId}" uses tier "${step.modelTier}", expected "${expectedTier}"` };
+    }
+
+    case 'step-requires': {
+      const [stepId, dep] = args.split(':');
+      const step = workflow.steps.find(s => s.id === stepId);
+      if (!step) return { passed: false, evidence: `Step "${stepId}" not found` };
+      return step.requires.includes(dep)
+        ? { passed: true, evidence: `Step "${stepId}" requires "${dep}"` }
+        : { passed: false, evidence: `Step "${stepId}" requires [${step.requires.join(', ')}], missing "${dep}"` };
+    }
+
+    case 'step-parallel': {
+      const step = workflow.steps.find(s => s.id === args);
+      if (!step) return { passed: false, evidence: `Step "${args}" not found` };
+      return step.parallel && step.parallel.length > 0
+        ? { passed: true, evidence: `Step "${args}" is parallel with [${step.parallel.join(', ')}]` }
+        : { passed: false, evidence: `Step "${args}" has no parallel group` };
+    }
+
+    case 'gate-exists': {
+      const step = workflow.steps.find(s => s.id === args);
+      if (!step) return { passed: false, evidence: `Step "${args}" not found` };
+      return step.gate === true
+        ? { passed: true, evidence: `Step "${args}" has gate: true` }
+        : { passed: false, evidence: `Step "${args}" has gate: ${step.gate}` };
+    }
+
+    case 'step-count': {
+      const min = parseInt(args, 10);
+      const actual = workflow.steps.length;
+      return actual >= min
+        ? { passed: true, evidence: `Workflow has ${actual} steps (minimum ${min})` }
+        : { passed: false, evidence: `Workflow has ${actual} steps, expected at least ${min}` };
+    }
+
+    default:
+      return { passed: false, evidence: `Unknown assertion type: "${type}"` };
+  }
+}
+
+/**
+ * Loads evals.json for a skill template.
+ * @param {string} skillName - Skill directory name (e.g. 'build-feature')
+ * @returns {object|null} Parsed evals object or null if no evals exist
+ */
+export function loadEvals(skillName) {
+  const evalsPath = join(TEMPLATES_DIR, skillName, 'evals', 'evals.json');
+  if (!existsSync(evalsPath)) return null;
+  return JSON.parse(readFileSync(evalsPath, 'utf8'));
+}
+
+/**
+ * Runs all evals for a skill template.
+ * Parses the SKILL.md, loads evals.json, and evaluates each assertion.
+ * @param {string} skillName - Skill directory name
+ * @returns {{ skill: string, results: Array<{ id: string, description: string, passed: boolean, expectations: Array }> }}
+ */
+export function runEvals(skillName) {
+  const evals = loadEvals(skillName);
+  if (!evals) throw new Error(`No evals found for skill "${skillName}"`);
+
+  const skillPath = join(TEMPLATES_DIR, skillName, 'SKILL.md');
+  const content = readFileSync(skillPath, 'utf8');
+  const skill = parseSkill(content);
+
+  if (!skill.workflow) {
+    throw new Error(`Skill "${skillName}" has no workflow definition`);
+  }
+
+  const results = evals.evals.map(evalCase => {
+    const expectations = evalCase.expectations.map(exp => {
+      const result = evaluateAssertion(skill.workflow, exp.assertion);
+      return { text: exp.text, assertion: exp.assertion, ...result };
+    });
+    const passed = expectations.every(e => e.passed);
+    return {
+      id: evalCase.id,
+      description: evalCase.description,
+      passed,
+      expectations,
+    };
+  });
+
+  return { skill: skillName, results };
+}