@open-product-primer/cli 2.11.0 → 2.12.1

package/dist/lib/claude-mods.d.ts

@@ -5,11 +5,25 @@ export interface ClaudeModHookFile {
     matcher?: string;
     command: string;
 }
-export interface ClaudeMod {
+export interface ClaudeModPluginFile {
+    path: string;
+    content: string;
+}
+interface ClaudeModBase {
     id: string;
     title: string;
     description: string;
+}
+export interface ClaudeModClassic extends ClaudeModBase {
+    shape: 'classic';
     hookFiles: ClaudeModHookFile[];
 }
+export interface ClaudeModPlugin extends ClaudeModBase {
+    shape: 'plugin';
+    pluginFiles: ClaudeModPluginFile[];
+}
+export type ClaudeMod = ClaudeModClassic | ClaudeModPlugin;
+export declare function isPluginMod(mod: ClaudeMod): mod is ClaudeModPlugin;
 export declare const CLAUDE_MODS_REGISTRY: ClaudeMod[];
 export declare function getClaudeMod(id: string): ClaudeMod | undefined;
+export {};

package/dist/lib/claude-mods.js

@@ -1,74 +1,102 @@
 "use strict";
-// Static registry of installable Claude Code function-hook "mods" — see
-// oprim/bets/pending/BET-051-spec-delta-drift-interceptor-mod/design.md. Both `oprim init`'s
+// Static registry of installable Claude Code "mods" — see
+// oprim/bets/pending/BET-074-migrate-claude-mods-to-function-hooks/design.md. Both `oprim init`'s
 // mod-selection prompt and the `oprim claude-mods` command read from this single registry, so a
-// future mod (BET-052–066) is added here once rather than duplicated per entry point.
+// future mod (BET-052–073) is added here once rather than duplicated per entry point.
+//
+// A registry entry declares one of two shapes:
+//   - 'classic': a shell-command hook merged into .claude/settings.json's `hooks` block (text-only
+//     {decision, reason} protocol — cannot draw UI).
+//   - 'plugin': a Claude Code function-hooks plugin (manifest + hooks.json + a register(on) module)
+//     installed at .claude/skills/<id>/, loaded via the project-scope skills-directory auto-load
+//     convention. Can draw UI ($.ui.log, $.ui.render) but requires CLAUDE_CODE_ENABLE_FUNCTION_HOOKS
+//     and is early access — its API may move between releases.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CLAUDE_MODS_REGISTRY = void 0;
+exports.isPluginMod = isPluginMod;
 exports.getClaudeMod = getClaudeMod;
-// PostToolUse hook: on a Write/Edit to a bet's specs/<capability>/spec.md delta, shells out to
-// `oprim validate --json` (already runs checkSpecDeltaDrift()) and surfaces any MODIFIED/REMOVED
-// drift for that capability inline, at write time instead of only at validate/CI time. Silently
-// no-ops on any failure (oprim not resolvable, malformed hook input, etc.) — this is a
-// write-time convenience on top of `oprim validate`, never a second source of required failures.
-const SPEC_DELTA_DRIFT_INTERCEPTOR_SCRIPT = `#!/usr/bin/env node
-// PostToolUse hook (Write|Edit) — see claude-mods.ts's spec-delta-drift-interceptor entry.
-
-let raw = '';
-process.stdin.on('data', (chunk) => { raw += chunk; });
-process.stdin.on('end', () => {
-  try {
-    const input = JSON.parse(raw || '{}');
-    const filePath = input.tool_input && input.tool_input.file_path;
-    if (!filePath) return;
+function isPluginMod(mod) {
+    return mod.shape === 'plugin';
+}
+// register(on) module: on a Write/Edit tool.call to a bet's specs/<capability>/spec.md delta,
+// shells out to `oprim validate --json` (already runs checkSpecDeltaDrift()) and surfaces any
+// MODIFIED/REMOVED drift for that capability as a transcript line, at write time instead of only
+// at validate/CI time. Never denies the call — this is a write-time convenience on top of
+// `oprim validate`, never a second source of required failures. Silently no-ops on any failure
+// (oprim not resolvable, malformed report, etc.).
+const SPEC_DELTA_DRIFT_INTERCEPTOR_REGISTER = `// Function-hooks module for the spec-delta-drift-interceptor mod — see claude-mods.ts.
+// EARLY ACCESS: register(on)/$.ui.log/$.process.run are gated behind
+// CLAUDE_CODE_ENABLE_FUNCTION_HOOKS and may change shape between Claude Code releases. A hooks
+// module may only import its own files by relative path and "claude-code" — no Node builtins — so
+// shelling out goes through $.process.run, not node:child_process.
+//
+// Surfaces the drift as a transcript line via $.ui.log rather than $.ui.toast: a toast is a
+// transient overlay whose rendering depends on the session's UI surface, while $.ui.log's default
+// destination ("to: transcript") always lands as a plain line every surface shows — see the
+// anthropics/claude-code \`mods/diff\` example, which uses the same call for its panel-toggle
+// messages ("Diff panel shown"/"Diff panel hidden").
 
-    const match = String(filePath).replace(/\\\\/g, '/').match(
-      /oprim\\/bets\\/pending\\/[^/]+\\/specs\\/([^/]+)\\/spec\\.md$/
-    );
-    if (!match) return;
-    const capability = match[1];
+export function register(on) {
+  on('tool.call', { tool: ['Write', 'Edit'] }, async ($, e, next) => {
+    const result = await next(e);
 
-    const { execSync } = require('child_process');
-    let output;
     try {
-      output = execSync('npx --no-install oprim validate --json', {
-        encoding: 'utf-8',
-        stdio: ['ignore', 'pipe', 'ignore'],
-      });
-    } catch (err) {
-      // validate exits non-zero when a required check fails — stdout still carries the report
-      output = err && err.stdout ? err.stdout.toString() : null;
-    }
-    if (!output) return;
+      const filePath = String(e.file_path || '').replace(/\\\\/g, '/');
+      const match = filePath.match(/oprim\\/bets\\/pending\\/[^/]+\\/specs\\/([^/]+)\\/spec\\.md$/);
+      if (!match) return result;
+      const capability = match[1];
 
-    const report = JSON.parse(output);
-    const drift = (report.checks || []).filter(
-      (c) => c.name && c.name.startsWith('spec-delta:') && c.name.includes(\`in \${capability} \`) && !c.pass
-    );
-    if (drift.length === 0) return;
+      let output;
+      try {
+        // validate exits non-zero when a required check fails — stdout still carries the report
+        const res = await $.process.run(['npx', '--no-install', 'oprim', 'validate', '--json']);
+        output = res.stdout;
+      } catch {
+        output = null;
+      }
+      if (!output) return result;
+
+      const report = JSON.parse(output);
+      const drift = (report.checks || []).filter(
+        (c) => c.name && c.name.startsWith('spec-delta:') && c.name.includes(\`in \${capability} \`) && !c.pass
+      );
+      if (drift.length === 0) return result;
+
+      const reason = drift.map((c) => \`\${c.name}\${c.note ? \` (\${c.note})\` : ''}\`).join('; ');
+      $.ui.log(\`⚠ Spec-delta drift in \${capability}: \${reason}\`);
+    } catch {
+      // Graceful degradation — never error or block on interceptor failure.
+    }
 
-    const reason = drift.map((c) => \`- \${c.name}\${c.note ? \` (\${c.note})\` : ''}\`).join('\\n');
-    process.stdout.write(JSON.stringify({
-      decision: 'block',
-      reason: \`Spec-delta drift detected in \${capability}:\\n\${reason}\`,
-    }) + '\\n');
-  } catch {
-    // Graceful degradation — never error or block on interceptor failure.
-  }
-});
+    return result;
+  });
+}
 `;
 exports.CLAUDE_MODS_REGISTRY = [
     {
         id: 'spec-delta-drift-interceptor',
         title: 'Spec-delta drift interceptor',
         description: "Catches a bet's spec-delta MODIFIED/REMOVED requirement drifting from oprim/specs current truth at write time, instead of only at oprim validate/CI time.",
-        hookFiles: [
+        shape: 'plugin',
+        pluginFiles: [
+            {
+                path: '.claude-plugin/plugin.json',
+                content: JSON.stringify({
+                    name: 'spec-delta-drift-interceptor',
+                    description: "Catches a bet's spec-delta MODIFIED/REMOVED requirement drifting from oprim/specs current truth at write time.",
+                    version: '1.0.0',
+                }, null, 2) + '\n',
+            },
+            {
+                path: 'hooks/hooks.json',
+                content: JSON.stringify({
+                    description: 'Runs checkSpecDeltaDrift() on a bet spec-delta write and surfaces drift via a toast, at write time.',
+                    modules: ['./register.js'],
+                }, null, 2) + '\n',
+            },
             {
-                filename: 'spec-delta-drift-interceptor.js',
-                content: SPEC_DELTA_DRIFT_INTERCEPTOR_SCRIPT,
-                event: 'PostToolUse',
-                matcher: 'Write|Edit',
-                command: 'node ".claude/hooks/spec-delta-drift-interceptor.js"',
+                path: 'hooks/register.js',
+                content: SPEC_DELTA_DRIFT_INTERCEPTOR_REGISTER,
             },
         ],
     },

package/dist/lib/install-agent.d.ts

@@ -9,10 +9,12 @@ export declare function promptEnableFunctionHooks(): Promise<boolean>;
 export declare function enableFunctionHooks(projectRoot: string): void;
 export declare function printManualFunctionHooksActivation(): void;
 /**
- * Merges newly-selected mods' hookFiles into .claude/settings.json (additive, non-clobbering —
- * same convention as mergeClaudeSettingsHooks) and removes deselected mods' entries, writing/
- * deleting each mod's hook script file(s) to match. Persists the resulting selection to
- * oprim/config.yaml's claude_mods key.
+ * Merges newly-selected mods into the project and removes deselected mods' entries, writing/
+ * deleting each mod's files to match. A classic mod's hookFiles merge into .claude/settings.json
+ * (additive, non-clobbering — same convention as mergeClaudeSettingsHooks); a plugin mod's
+ * pluginFiles are written under .claude/skills/<mod.id>/ instead, where the skills-directory
+ * auto-load convention picks it up as a function-hooks plugin — settings.json is untouched for
+ * these. Persists the resulting selection to oprim/config.yaml's claude_mods key.
  */
 export declare function applyClaudeModsSelection(projectRoot: string, selectedIds: string[], previousIds: string[]): void;
 export declare function promptPdrSurfacing(): Promise<boolean>;

package/dist/lib/install-agent.js

@@ -245,27 +245,40 @@ function removeModHookFromSettings(settings, hookFile) {
     }
 }
 /**
- * Merges newly-selected mods' hookFiles into .claude/settings.json (additive, non-clobbering —
- * same convention as mergeClaudeSettingsHooks) and removes deselected mods' entries, writing/
- * deleting each mod's hook script file(s) to match. Persists the resulting selection to
- * oprim/config.yaml's claude_mods key.
+ * Merges newly-selected mods into the project and removes deselected mods' entries, writing/
+ * deleting each mod's files to match. A classic mod's hookFiles merge into .claude/settings.json
+ * (additive, non-clobbering — same convention as mergeClaudeSettingsHooks); a plugin mod's
+ * pluginFiles are written under .claude/skills/<mod.id>/ instead, where the skills-directory
+ * auto-load convention picks it up as a function-hooks plugin — settings.json is untouched for
+ * these. Persists the resulting selection to oprim/config.yaml's claude_mods key.
  */
 function applyClaudeModsSelection(projectRoot, selectedIds, previousIds) {
     const claudeDir = path.join(projectRoot, '.claude');
     const hooksDir = path.join(claudeDir, 'hooks');
+    const skillsDir = path.join(claudeDir, 'skills');
     const settingsPath = path.join(claudeDir, 'settings.json');
     const settings = readSettings(settingsPath);
+    let settingsChanged = false;
     const added = selectedIds.filter((id) => !previousIds.includes(id));
     const removed = previousIds.filter((id) => !selectedIds.includes(id));
     for (const id of added) {
         const mod = (0, claude_mods_1.getClaudeMod)(id);
         if (!mod)
             continue;
+        if ((0, claude_mods_1.isPluginMod)(mod)) {
+            const pluginDir = path.join(skillsDir, mod.id);
+            for (const file of mod.pluginFiles) {
+                (0, scaffold_1.writeFile)(path.join(pluginDir, file.path), file.content);
+            }
+            console.log(chalk_1.default.green('✓') + ` .claude/skills/${mod.id}/ (${mod.title})`);
+            continue;
+        }
         for (const hookFile of mod.hookFiles) {
             const scriptPath = path.join(hooksDir, hookFile.filename);
             (0, scaffold_1.writeFile)(scriptPath, hookFile.content);
             fs.chmodSync(scriptPath, 0o755);
             addModHookToSettings(settings, hookFile);
+            settingsChanged = true;
             console.log(chalk_1.default.green('✓') + ` .claude/hooks/${hookFile.filename} (${mod.title})`);
         }
     }
@@ -273,15 +286,23 @@ function applyClaudeModsSelection(projectRoot, selectedIds, previousIds) {
         const mod = (0, claude_mods_1.getClaudeMod)(id);
         if (!mod)
             continue;
+        if ((0, claude_mods_1.isPluginMod)(mod)) {
+            const pluginDir = path.join(skillsDir, mod.id);
+            if (fs.existsSync(pluginDir))
+                fs.rmSync(pluginDir, { recursive: true, force: true });
+            console.log(chalk_1.default.dim(`  removed .claude/skills/${mod.id}/ (${mod.title})`));
+            continue;
+        }
         for (const hookFile of mod.hookFiles) {
             const scriptPath = path.join(hooksDir, hookFile.filename);
             if (fs.existsSync(scriptPath))
                 fs.unlinkSync(scriptPath);
             removeModHookFromSettings(settings, hookFile);
+            settingsChanged = true;
             console.log(chalk_1.default.dim(`  removed .claude/hooks/${hookFile.filename} (${mod.title})`));
         }
     }
-    if (added.length > 0 || removed.length > 0) {
+    if (settingsChanged) {
         writeSettings(settingsPath, settings);
     }
     (0, detect_1.writeClaudeModsToConfig)(selectedIds, projectRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-product-primer/cli",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "description": "Open Product Primer CLI — product decisions, sequencing, and KPI tracking for repositories",
   "keywords": [
     "product",