worclaude 2.8.0 → 2.9.0

package/src/prompts/agent-selection.js

@@ -63,8 +63,9 @@ export async function promptAgentSelection(projectTypes) {
   // Step 3: Offer unselected categories
   const unselectedCategories = categoryNames.filter((cat) => !selectedCategories.includes(cat));
 
+  let additionalCategories = [];
   if (unselectedCategories.length > 0) {
-    const { additionalCategories } = await inquirer.prompt([
+    ({ additionalCategories } = await inquirer.prompt([
       {
         type: 'checkbox',
         name: 'additionalCategories',
@@ -74,7 +75,7 @@ export async function promptAgentSelection(projectTypes) {
           value: cat,
         })),
       },
-    ]);
+    ]));
 
     for (const cat of additionalCategories) {
       const agentNames = AGENT_CATEGORIES[cat].agents;
@@ -95,5 +96,12 @@ export async function promptAgentSelection(projectTypes) {
   }
 
   // Deduplicate
-  return [...new Set(selected)];
+  const dedupedSelectedAgents = [...new Set(selected)];
+
+  return {
+    selectedAgents: dedupedSelectedAgents,
+    selectedCategories,
+    additionalCategories,
+    preSelectedCategories: [...preSelectedCategories],
+  };
 }

package/src/utils/agent-frontmatter.js

@@ -0,0 +1,109 @@
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import yaml from 'yaml';
+
+const ROUTING_FIELDS = [
+  'category',
+  'triggerType',
+  'triggerCommand',
+  'whenToUse',
+  'whatItDoes',
+  'expectBack',
+  'situationLabel',
+  'status',
+];
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+export class AgentFrontmatterError extends Error {
+  constructor(message, { filePath } = {}) {
+    super(message);
+    this.name = 'AgentFrontmatterError';
+    this.filePath = filePath;
+  }
+}
+
+export function parseAgentFrontmatter(source, filePath) {
+  const match = source.match(FRONTMATTER_RE);
+  if (!match) {
+    throw new AgentFrontmatterError('No YAML frontmatter found', { filePath });
+  }
+  let parsed;
+  try {
+    parsed = yaml.parse(match[1]);
+  } catch (err) {
+    throw new AgentFrontmatterError(`Frontmatter is not valid YAML: ${err.message}`, {
+      filePath,
+    });
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new AgentFrontmatterError('Frontmatter must be a YAML mapping', { filePath });
+  }
+  return parsed;
+}
+
+export function validateRoutingFields(frontmatter, { filePath } = {}) {
+  const missing = [];
+  for (const field of ['category', 'triggerType', 'whenToUse', 'whatItDoes', 'expectBack']) {
+    if (frontmatter[field] === undefined || frontmatter[field] === '') {
+      missing.push(field);
+    }
+  }
+  if (missing.length > 0) {
+    throw new AgentFrontmatterError(
+      `Agent frontmatter missing required routing fields: ${missing.join(', ')}`,
+      { filePath }
+    );
+  }
+  if (frontmatter.triggerType !== 'automatic' && frontmatter.triggerType !== 'manual') {
+    throw new AgentFrontmatterError(
+      `Agent frontmatter triggerType must be "automatic" or "manual", got "${frontmatter.triggerType}"`,
+      { filePath }
+    );
+  }
+}
+
+export async function readAgentFile(filePath) {
+  const source = await readFile(filePath, 'utf8');
+  const frontmatter = parseAgentFrontmatter(source, filePath);
+  return frontmatter;
+}
+
+export async function loadAgentsFromDir(dir, { recursive = true } = {}) {
+  const entries = [];
+  await walk(dir, recursive, entries);
+  const agents = [];
+  for (const filePath of entries) {
+    const frontmatter = await readAgentFile(filePath);
+    if (!frontmatter.name) {
+      throw new AgentFrontmatterError('Agent frontmatter missing required field: name', {
+        filePath,
+      });
+    }
+    agents.push({ name: frontmatter.name, filePath, ...frontmatter });
+  }
+  agents.sort((a, b) => a.name.localeCompare(b.name));
+  return agents;
+}
+
+async function walk(dir, recursive, out) {
+  let dirents;
+  try {
+    dirents = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  for (const dirent of dirents) {
+    const full = path.join(dir, dirent.name);
+    if (dirent.isDirectory()) {
+      if (recursive) await walk(full, recursive, out);
+      continue;
+    }
+    if (dirent.isFile() && dirent.name.endsWith('.md')) {
+      out.push(full);
+    }
+  }
+}
+
+export { ROUTING_FIELDS };

package/src/utils/doc-lint.js

@@ -0,0 +1,196 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { fileExists, readFile } from './file.js';
+
+const TEST_COUNT_RE = /(\d+)\s+tests?\s*,\s*(\d+)\s+(?:test\s+)?files?/i;
+
+export function parseClaudeMdTestCountClaims(content) {
+  if (typeof content !== 'string' || content.length === 0) return [];
+  const claims = [];
+  const lines = content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = line.match(TEST_COUNT_RE);
+    if (m) {
+      claims.push({
+        lineNumber: i + 1,
+        raw: line,
+        claimedTests: Number(m[1]),
+        claimedFiles: Number(m[2]),
+      });
+    }
+  }
+  return claims;
+}
+
+const TEST_FILE_RE = /\.test\.(?:js|mjs|cjs|ts|tsx)$/;
+const TEST_CALL_RE = /^\s*(?:it|test)(?:\.each\s*\([^)]*\))?\s*\(/gm;
+
+export function countTestCalls(content) {
+  if (typeof content !== 'string' || content.length === 0) return 0;
+  return (content.match(TEST_CALL_RE) || []).length;
+}
+
+async function collectTestFiles(dir) {
+  if (!(await fs.pathExists(dir))) return [];
+  const out = [];
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await collectTestFiles(full);
+      out.push(...nested);
+    } else if (entry.isFile() && TEST_FILE_RE.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+export async function countActualTestSuite(projectRoot, options = {}) {
+  const testDir = options.testDir || path.join(projectRoot, 'tests');
+  const files = await collectTestFiles(testDir);
+  let tests = 0;
+  for (const file of files) {
+    const content = await readFile(file);
+    tests += countTestCalls(content);
+  }
+  return { tests, files: files.length };
+}
+
+const MARKER_RE = /<!--\s*references\s+(\S+?)\s*-->/i;
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'coverage',
+  '.eslintcache',
+  '.vitest',
+  'docs/.vitepress/dist',
+  'docs/.vitepress/cache',
+]);
+
+async function walkMarkdownFiles(rootDir, currentRel = '') {
+  const out = [];
+  const dir = path.join(rootDir, currentRel);
+  if (!(await fs.pathExists(dir))) return out;
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const rel = currentRel ? `${currentRel}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name) || SKIP_DIRS.has(rel) || entry.name.startsWith('.')) continue;
+      const nested = await walkMarkdownFiles(rootDir, rel);
+      out.push(...nested);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+function extractSection(lines, markerLineIdx) {
+  const sectionLines = [];
+  for (let i = markerLineIdx + 1; i < lines.length; i++) {
+    if (/^##\s/.test(lines[i])) break;
+    sectionLines.push(lines[i]);
+  }
+  return sectionLines.join('\n');
+}
+
+export async function findReferencesMarkers(rootDir) {
+  const files = await walkMarkdownFiles(rootDir);
+  const markers = [];
+  for (const relFile of files) {
+    const absPath = path.join(rootDir, relFile);
+    const content = await readFile(absPath);
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(MARKER_RE);
+      if (!m) continue;
+      const source = m[1];
+      const sectionContent = extractSection(lines, i);
+      markers.push({
+        file: relFile,
+        markerLine: i + 1,
+        source,
+        sectionStartLine: i + 2,
+        sectionContent,
+      });
+    }
+  }
+  return markers;
+}
+
+const RUN_SCRIPT_RE = /\bnpm\s+run\s+([a-zA-Z][a-zA-Z0-9:_-]*)/g;
+
+export function findMissingNpmScripts(sectionContent, packageScripts) {
+  const seen = new Set();
+  const missing = [];
+  RUN_SCRIPT_RE.lastIndex = 0;
+  let match;
+  while ((match = RUN_SCRIPT_RE.exec(sectionContent)) !== null) {
+    const name = match[1];
+    if (seen.has(name)) continue;
+    seen.add(name);
+    if (!(name in (packageScripts || {}))) {
+      missing.push(name);
+    }
+  }
+  return missing;
+}
+
+export async function validatePackageJsonReferences(marker, projectRoot, packageJson) {
+  const issues = [];
+  const claims = parseClaudeMdTestCountClaims(marker.sectionContent);
+  if (claims.length > 0) {
+    const actual = await countActualTestSuite(projectRoot);
+    for (const claim of claims) {
+      if (claim.claimedFiles !== actual.files) {
+        issues.push({
+          kind: 'test-count-drift',
+          markerLine: marker.markerLine,
+          claimLine: marker.sectionStartLine + claim.lineNumber - 1,
+          claimed: { tests: claim.claimedTests, files: claim.claimedFiles },
+          actual,
+          raw: claim.raw.trim(),
+        });
+      }
+    }
+  }
+  const missing = findMissingNpmScripts(marker.sectionContent, packageJson.scripts);
+  for (const name of missing) {
+    issues.push({
+      kind: 'missing-npm-script',
+      markerLine: marker.markerLine,
+      scriptName: name,
+    });
+  }
+  return issues;
+}
+
+export async function lintRepo(projectRoot) {
+  const pkgPath = path.join(projectRoot, 'package.json');
+  let packageJson = { scripts: {} };
+  if (await fileExists(pkgPath)) {
+    try {
+      packageJson = JSON.parse(await readFile(pkgPath));
+    } catch {
+      packageJson = { scripts: {} };
+    }
+  }
+  const markers = await findReferencesMarkers(projectRoot);
+  const findings = [];
+  for (const marker of markers) {
+    if (marker.source !== 'package.json') continue;
+    const issues = await validatePackageJsonReferences(marker, projectRoot, packageJson);
+    for (const issue of issues) {
+      findings.push({ file: marker.file, ...issue });
+    }
+  }
+  return {
+    hasDrift: findings.length > 0,
+    markerCount: markers.length,
+    findings,
+  };
+}

package/src/utils/observability.js

@@ -0,0 +1,300 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { readFile } from './file.js';
+
+export async function readJsonl(filePath) {
+  if (!(await fs.pathExists(filePath))) return [];
+  const content = await readFile(filePath);
+  const out = [];
+  for (const line of content.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      // Skip malformed lines; never block the report
+    }
+  }
+  return out;
+}
+
+function tally(items, keyFn) {
+  const counts = new Map();
+  for (const item of items) {
+    const key = keyFn(item);
+    if (!key) continue;
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  return [...counts.entries()]
+    .map(([key, count]) => ({ key, count }))
+    .sort((a, b) => b.count - a.count);
+}
+
+export function pairAgentEvents(events) {
+  const startsByKey = new Map();
+  const pairs = [];
+  for (const event of events) {
+    const session = event.session || 'no-session';
+    const agent = event.agent || 'unknown';
+    const key = `${session}::${agent}`;
+    if (event.event === 'start') {
+      startsByKey.set(key, event);
+      continue;
+    }
+    if (event.event !== 'stop') continue;
+    const start = startsByKey.get(key);
+    if (!start) {
+      pairs.push({
+        agent,
+        session: event.session,
+        startTs: null,
+        stopTs: event.ts,
+        durationMs: null,
+        exit: event.exit || 'unknown',
+      });
+      continue;
+    }
+    startsByKey.delete(key);
+    const startMs = Date.parse(start.ts);
+    const stopMs = Date.parse(event.ts);
+    const durationMs =
+      Number.isFinite(startMs) && Number.isFinite(stopMs) ? stopMs - startMs : null;
+    pairs.push({
+      agent,
+      session: event.session,
+      startTs: start.ts,
+      stopTs: event.ts,
+      durationMs,
+      exit: event.exit || 'completed',
+    });
+  }
+  return pairs;
+}
+
+function summarizeAgents(pairs) {
+  const byAgent = new Map();
+  for (const pair of pairs) {
+    if (!byAgent.has(pair.agent)) {
+      byAgent.set(pair.agent, {
+        agent: pair.agent,
+        invocations: 0,
+        completed: 0,
+        failed: 0,
+        durationMsTotal: 0,
+        durationMsCount: 0,
+      });
+    }
+    const entry = byAgent.get(pair.agent);
+    entry.invocations += 1;
+    if (pair.exit === 'completed') entry.completed += 1;
+    else if (pair.exit === 'failed' || pair.exit === 'error') entry.failed += 1;
+    if (Number.isFinite(pair.durationMs)) {
+      entry.durationMsTotal += pair.durationMs;
+      entry.durationMsCount += 1;
+    }
+  }
+  return [...byAgent.values()]
+    .map((e) => ({
+      agent: e.agent,
+      invocations: e.invocations,
+      completed: e.completed,
+      failed: e.failed,
+      avgDurationMs:
+        e.durationMsCount > 0 ? Math.round(e.durationMsTotal / e.durationMsCount) : null,
+    }))
+    .sort((a, b) => b.invocations - a.invocations);
+}
+
+async function listInstalledSkills(projectRoot) {
+  const skillsDir = path.join(projectRoot, '.claude', 'skills');
+  if (!(await fs.pathExists(skillsDir))) return [];
+  const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+}
+
+function daysAgo(date, fromMs = Date.now()) {
+  const ts = Date.parse(date);
+  if (!Number.isFinite(ts)) return null;
+  return Math.floor((fromMs - ts) / (24 * 60 * 60 * 1000));
+}
+
+function buildAnomaliesAndSuggestions({ installedSkills, skillStats, agentStats, fromMs }) {
+  const anomalies = [];
+  const suggestions = [];
+
+  // Only flag never-loaded skills once SOME skill data exists. On a fresh
+  // install with zero captured events the comparison is uninformative noise.
+  if (skillStats.length > 0) {
+    const loadedSkills = new Set(skillStats.map((s) => s.key));
+    const neverLoaded = installedSkills.filter((s) => !loadedSkills.has(s));
+    for (const skill of neverLoaded) {
+      anomalies.push({
+        kind: 'skill-never-loaded',
+        message: `Skill \`${skill}\` is installed but never appeared in skill-loads.jsonl.`,
+      });
+    }
+  }
+
+  for (const stat of skillStats) {
+    if (!stat.lastSeen) continue;
+    const days = daysAgo(stat.lastSeen, fromMs);
+    if (days !== null && days > 30) {
+      suggestions.push({
+        message: `Skill \`${stat.key}\` not loaded in ${days} days — consider retiring or updating its description for keyword match.`,
+      });
+    }
+  }
+
+  for (const stat of agentStats) {
+    if (stat.invocations >= 3 && stat.failed > stat.completed) {
+      anomalies.push({
+        kind: 'agent-fails-more-than-completes',
+        message: `Agent \`${stat.agent}\` failed ${stat.failed} of ${stat.invocations} invocations (more failures than completions).`,
+      });
+    }
+  }
+
+  return { anomalies, suggestions };
+}
+
+function attachLastSeen(skillStats, skillEvents) {
+  const lastByKey = new Map();
+  for (const event of skillEvents) {
+    const skill = event.skill;
+    if (!skill) continue;
+    const prev = lastByKey.get(skill);
+    if (!prev || event.ts > prev) {
+      lastByKey.set(skill, event.ts);
+    }
+  }
+  return skillStats.map((s) => ({ ...s, lastSeen: lastByKey.get(s.key) || null }));
+}
+
+export async function computeReport(projectRoot, options = {}) {
+  const obsDir = path.join(projectRoot, '.claude', 'observability');
+  const fromMs = options.now || Date.now();
+
+  const skillEvents = await readJsonl(path.join(obsDir, 'skill-loads.jsonl'));
+  const commandEvents = await readJsonl(path.join(obsDir, 'command-invocations.jsonl'));
+  const agentEvents = await readJsonl(path.join(obsDir, 'agent-events.jsonl'));
+  const installedSkills = await listInstalledSkills(projectRoot);
+
+  const skillStatsRaw = tally(skillEvents, (e) => e.skill);
+  const skillStats = attachLastSeen(skillStatsRaw, skillEvents);
+  const commandStats = tally(commandEvents, (e) => e.command);
+  const agentPairs = pairAgentEvents(agentEvents);
+  const agentStats = summarizeAgents(agentPairs);
+
+  const { anomalies, suggestions } = buildAnomaliesAndSuggestions({
+    installedSkills,
+    skillStats,
+    agentStats,
+    fromMs,
+  });
+
+  return {
+    generatedAt: new Date(fromMs).toISOString(),
+    counts: {
+      skillEvents: skillEvents.length,
+      commandEvents: commandEvents.length,
+      agentEvents: agentEvents.length,
+      agentPairs: agentPairs.length,
+      installedSkills: installedSkills.length,
+    },
+    skillStats,
+    commandStats,
+    agentStats,
+    anomalies,
+    suggestions,
+  };
+}
+
+function formatDuration(ms) {
+  if (ms === null || !Number.isFinite(ms)) return '—';
+  if (ms < 1000) return `${ms}ms`;
+  const s = ms / 1000;
+  if (s < 60) return `${s.toFixed(1)}s`;
+  const m = Math.floor(s / 60);
+  const r = Math.round(s - m * 60);
+  return `${m}m ${r}s`;
+}
+
+export function renderMarkdown(report) {
+  const lines = [];
+  lines.push('# Observability Report');
+  lines.push('');
+  lines.push(`Generated: ${report.generatedAt}`);
+  lines.push('');
+
+  lines.push('## Captured Volume');
+  lines.push('');
+  lines.push(
+    `- ${report.counts.skillEvents} skill loads · ${report.counts.commandEvents} command invocations · ${report.counts.agentPairs} agent invocations (${report.counts.agentEvents} raw start/stop events)`
+  );
+  lines.push(`- ${report.counts.installedSkills} skills installed in this project`);
+  lines.push('');
+
+  lines.push('## Top Skills');
+  lines.push('');
+  if (report.skillStats.length === 0) {
+    lines.push('_No skill loads captured yet._');
+  } else {
+    lines.push('| Skill | Loads | Last seen |');
+    lines.push('|---|---|---|');
+    for (const stat of report.skillStats.slice(0, 10)) {
+      lines.push(`| \`${stat.key}\` | ${stat.count} | ${stat.lastSeen || '—'} |`);
+    }
+  }
+  lines.push('');
+
+  lines.push('## Top Commands');
+  lines.push('');
+  if (report.commandStats.length === 0) {
+    lines.push('_No command invocations captured yet._');
+  } else {
+    lines.push('| Command | Invocations |');
+    lines.push('|---|---|');
+    for (const stat of report.commandStats.slice(0, 10)) {
+      lines.push(`| \`${stat.key}\` | ${stat.count} |`);
+    }
+  }
+  lines.push('');
+
+  lines.push('## Agent Invocations');
+  lines.push('');
+  if (report.agentStats.length === 0) {
+    lines.push('_No agent events captured yet._');
+  } else {
+    lines.push('| Agent | Invocations | Completed | Failed | Avg duration |');
+    lines.push('|---|---|---|---|---|');
+    for (const stat of report.agentStats.slice(0, 10)) {
+      lines.push(
+        `| \`${stat.agent}\` | ${stat.invocations} | ${stat.completed} | ${stat.failed} | ${formatDuration(stat.avgDurationMs)} |`
+      );
+    }
+  }
+  lines.push('');
+
+  lines.push('## Anomalies');
+  lines.push('');
+  if (report.anomalies.length === 0) {
+    lines.push('_None detected._');
+  } else {
+    for (const a of report.anomalies) {
+      lines.push(`- ${a.message}`);
+    }
+  }
+  lines.push('');
+
+  lines.push('## Suggestions');
+  lines.push('');
+  if (report.suggestions.length === 0) {
+    lines.push('_None._');
+  } else {
+    for (const s of report.suggestions) {
+      lines.push(`- ${s.message}`);
+    }
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}

package/templates/agents/optional/backend/api-designer.md

@@ -1,6 +1,6 @@
 ---
 name: api-designer
-description: "Reviews API design for RESTful conventions"
+description: Reviews API design for RESTful conventions
 model: opus
 isolation: none
 disallowedTools:
@@ -8,6 +8,12 @@ disallowedTools:
   - NotebookEdit
   - Agent
 maxTurns: 30
+category: backend
+triggerType: manual
+whenToUse: Designing new API endpoints. Changing existing API contracts. Adding new routes or modifying request/response shapes.
+whatItDoes: Reviews API design for RESTful conventions, naming consistency, backward compatibility, request/response shape validation.
+expectBack: Design review with specific recommendations.
+situationLabel: Designed a new API endpoint
 ---
 
 You are a senior API architect who reviews API designs for

package/templates/agents/optional/backend/auth-auditor.md

@@ -1,9 +1,15 @@
 ---
 name: auth-auditor
-description: "Audits authentication and authorization"
+description: Audits authentication and authorization
 model: opus
 isolation: none
 maxTurns: 40
+category: backend
+triggerType: manual
+whenToUse: Any change to authentication or authorization flow. New roles, permissions, token handling.
+whatItDoes: Reviews auth flows for correctness, token lifecycle, permission checks, session management, OWASP compliance.
+expectBack: Audit report with pass/fail per check.
+situationLabel: Changed auth or authorization logic
 ---
 
 You are a security-focused engineer specializing in authentication

package/templates/agents/optional/backend/database-analyst.md

@@ -1,6 +1,6 @@
 ---
 name: database-analyst
-description: "Reviews database schemas and queries"
+description: Reviews database schemas and queries
 model: sonnet
 isolation: none
 disallowedTools:
@@ -9,6 +9,12 @@ disallowedTools:
   - NotebookEdit
   - Agent
 maxTurns: 30
+category: backend
+triggerType: manual
+whenToUse: Writing migrations. Changing schemas. Complex queries. Data integrity concerns.
+whatItDoes: Reviews schema design, migration safety, query performance, index usage, data integrity constraints.
+expectBack: Analysis with specific concerns and recommendations.
+situationLabel: Wrote a database migration or schema change
 ---
 
 You are a database specialist who reviews schemas, queries, and