worclaude 2.8.0 → 2.9.0

package/src/core/file-categorizer.js

@@ -16,6 +16,7 @@ const ALWAYS_SCAFFOLDED_TYPES = new Set([
   'command',
   'universal-skill',
   'hook',
+  'script',
   'root-file',
 ]);
 
@@ -150,6 +151,21 @@ export async function buildTemplateHashMap() {
     }
   }
 
+  // Slash-command helper scripts: collapse multi-line bash blocks into a
+  // single allowed invocation. Walked from templates/scripts/ so new helpers
+  // flow through automatically.
+  const scriptsDir = path.join(getTemplatesDir(), 'scripts');
+  if (await fs.pathExists(scriptsDir)) {
+    const entries = await fs.readdir(scriptsDir);
+    for (const entry of entries) {
+      if (!entry.endsWith('.sh')) continue;
+      const key = `scripts/${entry}`;
+      const templatePath = `scripts/${entry}`;
+      const content = await readTemplate(templatePath);
+      map[key] = { templatePath, hash: hashContent(content), type: 'script' };
+    }
+  }
+
   // Root-level files: key = root/<path>, templatePath points into templates/
   // AGENTS.md needs variable substitution at scaffold time; the raw-template hash
   // is used only to detect drift against a previously-substituted install hash,

package/src/core/merger.js

@@ -8,9 +8,9 @@ import {
   scaffoldAgentsMd,
   mergeSettings,
   scaffoldHooks,
-  scaffoldPluginJson,
-  scaffoldMemoryDocs,
+  scaffoldScripts,
 } from './scaffolder.js';
+import { OPTIONAL_FEATURES } from '../data/optional-features.js';
 import { workflowRefRelPath } from './file-categorizer.js';
 import { promptHookConflict } from '../prompts/conflict-resolution.js';
 import {
@@ -28,7 +28,7 @@ import {
   NOTIFICATION_COMMANDS,
   SPEC_MD_TEMPLATE_MAP,
 } from '../data/agents.js';
-import { buildAgentRoutingSkill } from '../generators/agent-routing.js';
+import { buildAgentRoutingSkill, loadShippedAgents } from '../generators/agent-routing.js';
 import * as display from '../utils/display.js';
 
 // --- Settings builder (shared with Scenario A) ---
@@ -144,7 +144,7 @@ async function mergeSkills(projectRoot, existingScan, variables, report, selecti
 
   // Generated skill: agent-routing
   const skillsDir = path.join('.claude', 'skills');
-  const routingContent = buildAgentRoutingSkill(selections.selectedAgents, selections.projectTypes);
+  const routingContent = buildAgentRoutingSkill(await loadShippedAgents(selections.selectedAgents));
   const routingExistsAsDir = existingScan.existingSkillDirs.includes('agent-routing');
   const routingExistsAsFlat = existingScan.existingSkills.includes('agent-routing.md');
 
@@ -240,13 +240,21 @@ export async function mergeSettingsPermissionsAndHooks(
   const existingRaw = await readFile(path.join(projectRoot, '.claude', 'settings.json'));
   const existing = parseUserJson(existingRaw, '.claude/settings.json');
 
-  // Merge permissions (Tier 1)
+  // Merge permissions (Tier 1) — union-merge both allow and deny
   const existingAllow = existing.permissions?.allow || [];
   const workflowAllow = workflowSettings.permissions?.allow || [];
-  const newPerms = workflowAllow.filter((p) => !existingAllow.includes(p));
+  const newAllow = workflowAllow.filter((p) => !existingAllow.includes(p));
   if (!existing.permissions) existing.permissions = {};
-  existing.permissions.allow = [...existingAllow, ...newPerms];
-  report.added.permissions = newPerms.length;
+  existing.permissions.allow = [...existingAllow, ...newAllow];
+
+  const existingDeny = existing.permissions?.deny || [];
+  const workflowDeny = workflowSettings.permissions?.deny || [];
+  const newDeny = workflowDeny.filter((p) => !existingDeny.includes(p));
+  if (newDeny.length > 0 || existingDeny.length > 0) {
+    existing.permissions.deny = [...existingDeny, ...newDeny];
+  }
+
+  report.added.permissions = newAllow.length + newDeny.length;
 
   // Merge hooks (Tier 1 + Tier 3)
   if (!existing.hooks) existing.hooks = {};
@@ -333,7 +341,9 @@ async function mergeSettingsJson(projectRoot, existingScan, selections, report)
   if (!existingScan.hasSettingsJson) {
     // No existing settings — create fresh
     await writeFile(path.join(projectRoot, '.claude', 'settings.json'), settingsStr);
-    report.added.permissions = workflowSettings.permissions?.allow?.length || 0;
+    report.added.permissions =
+      (workflowSettings.permissions?.allow?.length || 0) +
+      (workflowSettings.permissions?.deny?.length || 0);
     report.added.hooks = countHooks(workflowSettings.hooks);
     return;
   }
@@ -343,7 +353,9 @@ async function mergeSettingsJson(projectRoot, existingScan, selections, report)
   } catch {
     display.warn('Existing settings.json contains invalid JSON — creating fresh settings instead.');
     await writeFile(path.join(projectRoot, '.claude', 'settings.json'), settingsStr);
-    report.added.permissions = workflowSettings.permissions?.allow?.length || 0;
+    report.added.permissions =
+      (workflowSettings.permissions?.allow?.length || 0) +
+      (workflowSettings.permissions?.deny?.length || 0);
     report.added.hooks = countHooks(workflowSettings.hooks);
   }
 }
@@ -407,7 +419,8 @@ async function handleClaudeMd(projectRoot, existingScan, variables, selections,
   // Tier 3 notice: if user opted into GTD memory AND their CLAUDE.md already has
   // a Memory Architecture section, the pointer bullets from the rendered template
   // won't be merged in automatically. Surface this so the user can add them manually.
-  if (selections.scaffoldGtdMemory && !missingSections.includes('Memory Architecture')) {
+  const optedIn = new Set(selections.optionalFeatures || []);
+  if (optedIn.has('gtd-memory') && !missingSections.includes('Memory Architecture')) {
     report.memoryArchitectureSectionExists = true;
   }
 
@@ -477,19 +490,28 @@ export async function performMerge(
   // Copy hook scripts (preserves existing user modifications)
   await scaffoldHooks(projectRoot);
 
+  // Copy slash-command helper scripts (preserves existing user modifications)
+  await scaffoldScripts(projectRoot);
+
   // Create learnings directory for correction capture
   await writeFile(path.join(projectRoot, '.claude', 'learnings', '.gitkeep'), '');
 
-  // Opt-in: plugin.json (idempotent — scaffolder skips if file exists)
-  if (selections.generatePluginJson) {
-    await scaffoldPluginJson(projectRoot, selections);
-  }
+  // Create scratch directory for SHA-keyed transient artifacts (gitignored)
+  await writeFile(path.join(projectRoot, '.claude', 'scratch', '.gitkeep'), '');
+
+  // Create plans directory for active work guidance (tracked)
+  await writeFile(path.join(projectRoot, '.claude', 'plans', '.gitkeep'), '');
+
+  // Create observability directory for hook-captured event logs (gitignored)
+  await writeFile(path.join(projectRoot, '.claude', 'observability', '.gitkeep'), '');
 
-  // Opt-in: GTD memory scaffold (idempotent per-file). Tier 3 notice for
-  // existing Memory Architecture section is handled inside handleClaudeMd,
-  // which already reads CLAUDE.md and runs section detection.
-  if (selections.scaffoldGtdMemory) {
-    await scaffoldMemoryDocs(projectRoot);
+  // Opt-in scaffolders: each registry feature is idempotent. Tier 3 notices
+  // (e.g. existing Memory Architecture section for gtd-memory) are handled
+  // inside handleClaudeMd, which runs section detection.
+  const optedIn = new Set(selections.optionalFeatures || []);
+  for (const feature of OPTIONAL_FEATURES) {
+    if (!optedIn.has(feature.id)) continue;
+    await feature.scaffold(projectRoot, selections);
   }
 
   await mergeDocSpecs(projectRoot, existingScan, variables, selections, report);

package/src/core/scaffolder.js

@@ -76,6 +76,8 @@ export async function updateGitignore(projectDir) {
     '.claude/learnings/',
     '.claude/.stop-hook-active',
     '.claude/cache/',
+    '.claude/scratch/',
+    '.claude/observability/',
   ];
   const header = '# Worclaude (generated workflow files)';
 
@@ -136,6 +138,30 @@ export async function scaffoldHooks(projectRoot) {
   }
 }
 
+export async function scaffoldScripts(projectRoot) {
+  const scriptsTemplateDir = path.join(getTemplatesDir(), 'scripts');
+  if (!(await fs.pathExists(scriptsTemplateDir))) return;
+  const destDir = path.join(projectRoot, '.claude', 'scripts');
+  await fs.ensureDir(destDir);
+
+  const entries = await fs.readdir(scriptsTemplateDir);
+  for (const entry of entries) {
+    if (!entry.endsWith('.sh')) continue;
+    const destPath = path.join(destDir, entry);
+    await fs.copy(path.join(scriptsTemplateDir, entry), destPath, {
+      overwrite: false,
+      errorOnExist: false,
+    });
+    if (process.platform !== 'win32') {
+      try {
+        await fs.chmod(destPath, 0o755);
+      } catch (err) {
+        if (err.code !== 'ENOENT') throw err;
+      }
+    }
+  }
+}
+
 export function slugifyPluginName(projectName) {
   const slug = String(projectName || '')
     .toLowerCase()

package/src/data/agents.js

@@ -68,12 +68,6 @@ export const AGENT_CATALOG = {
     category: 'quality',
     description: 'Diagnoses and fixes build failures',
   },
-  'e2e-runner': {
-    model: 'sonnet',
-    isolation: 'worktree',
-    category: 'quality',
-    description: 'Writes and runs end-to-end tests',
-  },
   'dependency-manager': {
     model: 'haiku',
     isolation: 'none',
@@ -138,7 +132,6 @@ export const CATEGORY_RECOMMENDATIONS = {
     'security-reviewer',
     'bug-fixer',
     'doc-writer',
-    'e2e-runner',
   ],
   'Backend / API': [
     'api-designer',
@@ -149,13 +142,7 @@ export const CATEGORY_RECOMMENDATIONS = {
     'performance-auditor',
     'build-fixer',
   ],
-  'Frontend / UI': [
-    'ui-reviewer',
-    'style-enforcer',
-    'performance-auditor',
-    'bug-fixer',
-    'e2e-runner',
-  ],
+  'Frontend / UI': ['ui-reviewer', 'style-enforcer', 'performance-auditor', 'bug-fixer'],
   'CLI tool': ['bug-fixer', 'doc-writer', 'dependency-manager', 'build-fixer'],
   'Data / ML / AI': [
     'data-pipeline-reviewer',
@@ -183,10 +170,8 @@ export const COMMAND_FILES = [
   'end',
   'commit-push-pr',
   'review-plan',
-  'techdebt',
   'verify',
   'compact-safe',
-  'status',
   'update-claude-md',
   'setup',
   'sync',
@@ -196,7 +181,7 @@ export const COMMAND_FILES = [
   'refactor-clean',
   'test-coverage',
   'learn',
-  'upstream-check',
+  'observability',
 ];
 
 export const UNIVERSAL_SKILLS = [
@@ -208,6 +193,7 @@ export const UNIVERSAL_SKILLS = [
   'verification',
   'testing',
   'claude-md-maintenance',
+  'memory-architecture',
   'coding-principles',
   'subagent-usage',
   'security-checklist',
@@ -220,7 +206,15 @@ export const TEMPLATE_SKILLS = [
   'project-patterns',
 ];
 
-export const HOOK_FILES = ['pre-compact-save', 'correction-detect', 'learn-capture', 'skill-hint'];
+export const HOOK_FILES = [
+  'pre-compact-save',
+  'correction-detect',
+  'learn-capture',
+  'skill-hint',
+  'obs-skill-loads',
+  'obs-command-invocations',
+  'obs-agent-events',
+];
 
 export const PROJECT_TYPES = [
   'Full-stack web application',
@@ -275,16 +269,8 @@ export const AGENT_CATEGORIES = {
     description: 'ci-fixer, docker-helper, deploy-validator, dependency-manager',
   },
   Quality: {
-    agents: [
-      'bug-fixer',
-      'security-reviewer',
-      'performance-auditor',
-      'refactorer',
-      'build-fixer',
-      'e2e-runner',
-    ],
-    description:
-      'bug-fixer, security-reviewer, performance-auditor, refactorer, build-fixer, e2e-runner',
+    agents: ['bug-fixer', 'security-reviewer', 'performance-auditor', 'refactorer', 'build-fixer'],
+    description: 'bug-fixer, security-reviewer, performance-auditor, refactorer, build-fixer',
   },
   Documentation: {
     agents: ['doc-writer', 'changelog-generator'],

package/src/data/optional-features.js

@@ -0,0 +1,46 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { scaffoldPluginJson, scaffoldMemoryDocs } from '../core/scaffolder.js';
+
+export const OPTIONAL_FEATURES = [
+  {
+    id: 'plugin-json',
+    label: 'Generate .claude-plugin/plugin.json for marketplace compatibility?',
+    extrasLabel: 'plugin.json',
+    successPath: '.claude-plugin/plugin.json',
+    async detect(projectRoot) {
+      return fs.pathExists(path.join(projectRoot, '.claude-plugin', 'plugin.json'));
+    },
+    async scaffold(projectRoot, selections) {
+      await scaffoldPluginJson(projectRoot, selections);
+    },
+  },
+  {
+    id: 'gtd-memory',
+    label: 'Scaffold structured memory files (decisions.md, preferences.md)?',
+    extrasLabel: 'memory docs',
+    successPath: 'docs/memory/',
+    successDetail: 'decisions.md, preferences.md',
+    async detect(projectRoot) {
+      return fs.pathExists(path.join(projectRoot, 'docs', 'memory', 'decisions.md'));
+    },
+    async scaffold(projectRoot) {
+      await scaffoldMemoryDocs(projectRoot);
+    },
+  },
+];
+
+export function getOptionalFeature(id) {
+  return OPTIONAL_FEATURES.find((feature) => feature.id === id) || null;
+}
+
+export async function availableOptionalFeatures(projectRoot, meta) {
+  const optedOut = new Set(meta?.optedOutFeatures || []);
+  const result = [];
+  for (const feature of OPTIONAL_FEATURES) {
+    if (optedOut.has(feature.id)) continue;
+    if (await feature.detect(projectRoot)) continue;
+    result.push(feature);
+  }
+  return result;
+}

package/src/generators/agent-routing.js

@@ -1,38 +1,139 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
 import { UNIVERSAL_AGENTS } from '../data/agents.js';
-import { AGENT_REGISTRY } from '../data/agent-registry.js';
+import { loadAgentsFromDir, validateRoutingFields } from '../utils/agent-frontmatter.js';
 
-/**
- * Generates the agent-routing.md skill file content based on selected agents.
- * @param {string[]} selectedAgentNames - names of optional agents the user selected
- * @param {string[]} projectTypes - e.g. ['Backend / API', 'Frontend / UI']
- * @returns {string} - complete markdown content for agent-routing.md
- */
-export function buildAgentRoutingSkill(selectedAgentNames, _projectTypes) {
-  const allAgents = [...new Set([...UNIVERSAL_AGENTS, ...selectedAgentNames])];
+const AUTO_START = '<!-- AUTO-GENERATED-START -->';
+const AUTO_END = '<!-- AUTO-GENERATED-END -->';
+
+const MODEL_LABEL = { opus: 'Opus', sonnet: 'Sonnet', haiku: 'Haiku' };
 
-  const automaticAgents = [];
-  const manualAgents = [];
+function modelLabel(model) {
+  if (!model) return 'Sonnet';
+  return MODEL_LABEL[String(model).toLowerCase()] ?? model;
+}
+
+function isolationLabel(isolation) {
+  return String(isolation).toLowerCase() === 'worktree' ? 'Worktree' : 'None';
+}
 
-  for (const name of allAgents) {
-    const entry = AGENT_REGISTRY[name];
-    if (!entry) continue;
-    if (entry.triggerType === 'automatic') {
-      automaticAgents.push({ name, ...entry });
+function partition(agents) {
+  const automatic = [];
+  const manual = [];
+  const reserved = [];
+  for (const agent of agents) {
+    if (agent.status === 'reserved') {
+      reserved.push(agent);
+    } else if (agent.triggerType === 'automatic') {
+      automatic.push(agent);
     } else {
-      manualAgents.push({ name, ...entry });
+      manual.push(agent);
     }
   }
+  return { automatic, manual, reserved };
+}
+
+const SKILL_FRONTMATTER = [
+  '---',
+  'description: "Agent Routing Guide — when to spawn each installed agent"',
+  '---',
+  '',
+  '',
+].join('\n');
+
+/**
+ * Build only the AUTO-GENERATED canonical block — markers + headings + agent
+ * entries + decision matrix + rules. Used internally by the public file
+ * builder and the regenerator.
+ */
+function buildAgentRoutingCanonicalBlock(agents) {
+  for (const agent of agents) {
+    validateRoutingFields(agent, { filePath: agent.filePath });
+  }
+
+  const { automatic, manual, reserved } = partition(agents);
 
   const sections = [
     buildHeader(),
     buildHowAgentsWork(),
-    buildAutomaticTriggers(automaticAgents),
-    buildManualTriggers(manualAgents),
-    buildDecisionMatrix(allAgents),
+    buildAutomaticTriggers(automatic),
+    buildManualTriggers(manual),
+    buildReserved(reserved),
+    buildDecisionMatrix(agents, reserved),
     buildRules(),
-  ];
+  ].filter(Boolean);
+
+  return `${AUTO_START}\n${sections.join('\n')}${AUTO_END}\n`;
+}
+
+/**
+ * Build a complete agent-routing skill file from a list of fully-parsed
+ * agent frontmatter objects. The result is suitable for fresh writes: it
+ * starts with a YAML frontmatter block (so Claude Code's skill loader has
+ * a description) followed by the canonical block wrapped in
+ * `<!-- AUTO-GENERATED-START -->` / `<!-- AUTO-GENERATED-END -->` markers.
+ *
+ * For in-place updates of files that may carry user-authored prose,
+ * use {@link regenerateAgentRoutingContent} instead.
+ *
+ * @param {object[]} agents - parsed agent frontmatter objects
+ * @returns {string} complete file content
+ */
+export function buildAgentRoutingSkill(agents) {
+  return `${SKILL_FRONTMATTER}${buildAgentRoutingCanonicalBlock(agents)}`;
+}
+
+/**
+ * Replace the AUTO-GENERATED block in `existingContent` with newly-generated
+ * content. If `existingContent` has markers, content outside them is
+ * preserved verbatim (frontmatter, user notes). If markers are absent or
+ * `existingContent` is null/empty, the result is a fresh complete file.
+ *
+ * @param {string|null} existingContent - the current file contents, or null/empty for first write
+ * @param {object[]} agents - parsed agent frontmatter objects
+ * @returns {string} updated file content
+ */
+export function regenerateAgentRoutingContent(existingContent, agents) {
+  if (!existingContent) return buildAgentRoutingSkill(agents);
+  const startIdx = existingContent.indexOf(AUTO_START);
+  const endIdx = existingContent.indexOf(AUTO_END, startIdx + AUTO_START.length);
+  if (startIdx === -1 || endIdx === -1) return buildAgentRoutingSkill(agents);
+  const before = existingContent.slice(0, startIdx);
+  const after = existingContent.slice(endIdx + AUTO_END.length);
+  const fresh = buildAgentRoutingCanonicalBlock(agents);
+  return `${before}${fresh.trimEnd()}${after}`;
+}
+
+/**
+ * Convenience wrapper: load agent files from a directory, optionally
+ * filter to a subset of names, and return the markdown.
+ *
+ * @param {string} dir - path to a directory containing agent .md files (recursively)
+ * @param {object} [opts]
+ * @param {string[]|null} [opts.includeNames] - only include agents whose `name` is in this set; null = include all
+ * @returns {Promise<string>} marker-wrapped routing markdown
+ */
+export async function buildAgentRoutingSkillFromDir(dir, { includeNames = null } = {}) {
+  const all = await loadAgentsFromDir(dir);
+  const filtered = includeNames ? all.filter((a) => includeNames.includes(a.name)) : all;
+  return buildAgentRoutingSkill(filtered);
+}
 
-  return sections.join('\n');
+/**
+ * Load the default set of agents shipped with worclaude (universal + selected
+ * optionals) from the project's `templates/agents/` directory. Used by init
+ * and merger when scaffolding into a fresh project.
+ *
+ * @param {string[]} selectedOptionalNames - names of optional agents the user picked
+ * @returns {Promise<object[]>} parsed agent frontmatter objects
+ */
+export async function loadShippedAgents(selectedOptionalNames) {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const templatesDir = path.resolve(here, '..', '..', 'templates', 'agents');
+  const all = await loadAgentsFromDir(templatesDir);
+  const wanted = new Set([...UNIVERSAL_AGENTS, ...selectedOptionalNames]);
+  return all.filter((a) => wanted.has(a.name));
 }
 
 function buildHeader() {
@@ -50,12 +151,30 @@ function buildHowAgentsWork() {
 - Never spawn more than 3 agents simultaneously.
 - If a task is small enough to do yourself in 2 minutes, don't spawn an agent for it.
 
+## Background-Agent Concurrency
+
+Two background agents on the same branch coexist cleanly:
+
+- **Worktree-isolated agents** (\`isolation: "worktree"\`) each create their own
+  sibling worktree off \`origin/HEAD\`. They never collide on files, refs, or the
+  index — running multiple in parallel is safe by design.
+- **Non-isolated agents** share the main checkout but are read-only by
+  convention. The main session and these agents must avoid editing the same
+  files concurrently; otherwise behavior is up to whoever writes last.
+
+Worktree lock semantics: Claude Code locks each agent worktree with the agent's
+pid; the lock survives agent completion. Stale locks are normal. Clean up with
+\`git worktree remove -f -f <path>\` or the project's worktree-cleanup helper.
+
+The earlier "lock file per branch" plan was rejected after the 2026-04-26
+concurrency test — worktree isolation already provides the guarantee a lock
+file would have, and a lock would block the legitimate parallel-agents case.
+
 ---
 `;
 }
 
 function buildAgentEntry(agent) {
-  const isolation = agent.isolation === 'worktree' ? 'Worktree' : 'None';
   let trigger;
   if (agent.triggerType === 'automatic' && agent.triggerCommand) {
     trigger = `Automatic — spawn when trigger condition is met (also: ${agent.triggerCommand})`;
@@ -68,7 +187,7 @@ function buildAgentEntry(agent) {
   }
 
   return `### ${agent.name}
-- **Model:** ${agent.model} | **Isolation:** ${isolation}
+- **Model:** ${modelLabel(agent.model)} | **Isolation:** ${isolationLabel(agent.isolation)}
 - **When:** ${agent.whenToUse}
 - **Trigger:** ${trigger}
 - **What it does:** ${agent.whatItDoes}
@@ -91,8 +210,7 @@ No automatic-trigger agents installed.
 
 These agents should be spawned without being asked when their trigger condition is met.
 
-${entries}
----
+${entries}---
 `;
 }
 
@@ -111,23 +229,44 @@ No manual-trigger agents installed.
 
 These agents are spawned when you or the user explicitly requests them.
 
-${entries}
----
+${entries}---
 `;
 }
 
-function buildDecisionMatrix(allAgents) {
+function buildReserved(reservedAgents) {
+  if (reservedAgents.length === 0) return '';
+
+  const entries = reservedAgents
+    .map(
+      (agent) => `### ${agent.name}
+- **Model:** ${modelLabel(agent.model)} | **Isolation:** ${isolationLabel(agent.isolation)}
+- **Status:** Reserved — no in-session command currently invokes this agent.
+- **Why kept:** ${agent.whenToUse}
+- **Do NOT spawn this agent in regular sessions.** It exists for scheduled
+  automation (CI/Actions) and for future revival; spawning it manually has no
+  defined entry path today.
+`
+    )
+    .join('\n');
+
+  return `## Reserved
+
+${entries}---
+`;
+}
+
+function buildDecisionMatrix(allAgents, reservedAgents) {
+  const reservedSet = new Set(reservedAgents.map((a) => a.name));
   const header = `## Decision Matrix
 
 | You just... | Spawn this | Auto? |
 |---|---|---|`;
 
   const rows = [];
-  for (const name of allAgents) {
-    const entry = AGENT_REGISTRY[name];
-    if (!entry) continue;
-    const auto = entry.triggerType === 'automatic' ? 'Yes' : 'Manual';
-    rows.push(`| ${entry.situationLabel} | ${name} | ${auto} |`);
+  for (const agent of allAgents) {
+    if (reservedSet.has(agent.name)) continue;
+    const auto = agent.triggerType === 'automatic' ? 'Yes' : 'Manual';
+    rows.push(`| ${agent.situationLabel} | ${agent.name} | ${auto} |`);
   }
 
   return `${header}
@@ -147,3 +286,19 @@ function buildRules() {
 6. If you spawn an agent and it's not useful, tell the user — they may remove it.
 `;
 }
+
+export { AUTO_START, AUTO_END };
+
+/**
+ * Read a file and run regenerateAgentRoutingContent on it. Convenience for
+ * call sites that already have a target path.
+ */
+export async function regenerateAgentRoutingFile(filePath, agents) {
+  let existing = null;
+  try {
+    existing = await readFile(filePath, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  return regenerateAgentRoutingContent(existing, agents);
+}

package/src/index.js

@@ -12,6 +12,10 @@ import { deleteCommand } from './commands/delete.js';
 import { doctorCommand } from './commands/doctor.js';
 import { scanCommand } from './commands/scan.js';
 import { setupStateCommand } from './commands/setup-state.js';
+import { worktreesCleanCommand } from './commands/worktrees.js';
+import { regenerateRoutingCommand } from './commands/regenerate-routing.js';
+import { docLintCommand } from './commands/doc-lint.js';
+import { observabilityCommand } from './commands/observability.js';
 
 const program = new Command();
 
@@ -64,6 +68,26 @@ program
   .option('--json', 'Output results as JSON')
   .action((options) => doctorCommand(options));
 
+program
+  .command('regenerate-routing')
+  .description(
+    'Regenerate .claude/skills/agent-routing/SKILL.md from .claude/agents/*.md frontmatter'
+  )
+  .action(() => regenerateRoutingCommand());
+
+program
+  .command('doc-lint')
+  .description('Lint <!-- references X --> markers across .md files for drift against their source')
+  .option('--strict', 'Exit non-zero on any drift (for CI)')
+  .action((options) => docLintCommand(options));
+
+program
+  .command('observability')
+  .description('Aggregate .claude/observability/*.jsonl into a per-project Markdown report')
+  .option('--json', 'Emit the raw report object as JSON instead of Markdown')
+  .option('--out <file>', 'Write the report to a file instead of stdout')
+  .action((options) => observabilityCommand(options));
+
 program
   .command('scan')
   .description('Scan project for detectable facts (writes .claude/cache/detection-report.json)')
@@ -112,4 +136,17 @@ setupState.on('command:*', (operands) => {
   process.exitCode = 2;
 });
 
+const worktrees = program.command('worktrees').description('Manage agent worktrees');
+
+worktrees
+  .command('clean')
+  .description('Force-remove locked agent worktrees under .claude/worktrees/')
+  .option('--path <dir>', 'Project root', process.cwd())
+  .action((options) => worktreesCleanCommand(options));
+
+worktrees.on('command:*', (operands) => {
+  console.error(`Error: unknown worktrees subcommand: ${operands[0]} (expected one of clean)`);
+  process.exitCode = 2;
+});
+
 program.parse();