@jaggerxtrm/specialists 2.1.15 → 2.1.17

package/bin/install.js

@@ -122,6 +122,36 @@ const BEADS_STOP_GATE_ENTRY = {
   hooks: [{ type: 'command', command: BEADS_STOP_GATE_FILE, timeout: 10000 }],
 };
 
+function promptYN(question) {
+  if (!process.stdin.isTTY) return true; // non-interactive: default yes
+  process.stdout.write(`${question} [Y/n]: `);
+  const r = spawnSync('/bin/sh', ['-c', 'read ans; printf "%s" "$ans"'], {
+    stdio: ['inherit', 'pipe', 'inherit'],
+    encoding: 'utf8',
+  });
+  const ans = (r.stdout ?? '').trim().toLowerCase();
+  return ans === '' || ans === 'y' || ans === 'yes';
+}
+
+function getHookDrift() {
+  const pairs = [
+    ['specialists-main-guard.mjs', HOOK_FILE],
+    ['beads-edit-gate.mjs',        BEADS_EDIT_GATE_FILE],
+    ['beads-commit-gate.mjs',      BEADS_COMMIT_GATE_FILE],
+    ['beads-stop-gate.mjs',        BEADS_STOP_GATE_FILE],
+  ];
+  return pairs
+    .map(([bundled, dest]) => ({
+      name: bundled,
+      dest,
+      missing: !existsSync(dest),
+      changed: existsSync(dest) &&
+        readFileSync(join(BUNDLED_HOOKS_DIR, bundled), 'utf8') !==
+        readFileSync(dest, 'utf8'),
+    }))
+    .filter(h => h.missing || h.changed);
+}
+
 function installHook() {
   mkdirSync(HOOKS_DIR, { recursive: true });
 
@@ -231,11 +261,27 @@ info('Edit any .specialist.yaml in ~/.agents/specialists/ to customise models, p
 
 // 6. Claude Code hooks
 section('Claude Code hooks');
-const hookExisted = existsSync(HOOK_FILE);
-installHook();
-hookExisted
-  ? ok('hooks updated (main-guard + beads gates)')
-  : ok('hooks installed → ~/.claude/hooks/');
+const drift = getHookDrift();
+const hooksExist = existsSync(HOOK_FILE);
+
+if (!hooksExist) {
+  installHook();
+  ok('hooks installed → ~/.claude/hooks/');
+} else if (drift.length === 0) {
+  skip('hooks up to date');
+} else {
+  const label = (h) => h.missing ? red('missing') : yellow('updated');
+  console.log(`  ${yellow('○')} ${drift.length} of 4 hook(s) have changes:`);
+  for (const h of drift) info(`      ${h.name}  ${label(h)}`);
+  console.log();
+  const confirmed = promptYN('  Update hooks?');
+  if (confirmed) {
+    installHook();
+    ok('hooks updated');
+  } else {
+    skip('hooks update skipped');
+  }
+}
 info('main-guard: blocks file edits and direct master pushes (enforces PR workflow)');
 info('beads-edit-gate: requires in_progress bead before editing files');
 info('beads-commit-gate: requires issues closed before git commit');

package/hooks/beads-commit-gate.mjs

@@ -4,7 +4,7 @@
 // Forces: close issues first, THEN commit.
 // Exit 0: allow  |  Exit 2: block (stderr shown to Claude)
 //
-// Installed by: npx --package=@jaggerxtrm/specialists install
+// Installed by: specialists install
 
 import { execSync } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
@@ -43,11 +43,14 @@ try {
 
 if (inProgress > 0) {
   process.stderr.write(
-    '\u{1F6AB} BEADS GATE: Cannot commit with open in_progress issues.\n' +
-    'Close them first, THEN commit:\n\n' +
-    '  bd close <id1> <id2> ...\n' +
-    '  git add <files> && git commit -m "..."\n\n' +
-    `Open issues:\n${summary}\n`
+    '🚫 BEADS GATE: Close open issues before committing.\n\n' +
+    `Open issues:\n${summary}\n\n` +
+    'Next steps:\n' +
+    '  3. bd close <id1> <id2> ...             ← you are here\n' +
+    '  4. git add <files> && git commit -m "..."\n' +
+    '  5. git push -u origin <feature-branch>\n' +
+    '  6. gh pr create --fill && gh pr merge --squash\n' +
+    '  7. git checkout master && git reset --hard origin/master\n'
   );
   process.exit(2);
 }

package/hooks/beads-edit-gate.mjs

@@ -4,7 +4,7 @@
 // Only active in projects with a .beads/ directory.
 // Exit 0: allow  |  Exit 2: block (stderr shown to Claude)
 //
-// Installed by: npx --package=@jaggerxtrm/specialists install
+// Installed by: specialists install
 
 import { execSync } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
@@ -35,11 +35,17 @@ try {
 
 if (inProgress === 0) {
   process.stderr.write(
-    '\u{1F6AB} BEADS GATE: No in_progress issue tracked.\n' +
-    'You MUST create and claim a beads issue BEFORE editing any file:\n\n' +
-    '  bd create --title="<task summary>" --type=task --priority=2\n' +
+    '🚫 BEADS GATE: No active issue — create one before editing files.\n\n' +
+    '  bd create --title="<what you\'re doing>" --type=task --priority=2\n' +
     '  bd update <id> --status=in_progress\n\n' +
-    'No exceptions. Momentum is not an excuse.\n'
+    'Full workflow (do this every session):\n' +
+    '  1. bd create + bd update in_progress   ← you are here\n' +
+    '  2. Edit files / write code\n' +
+    '  3. bd close <id>                        close when done\n' +
+    '  4. git add <files> && git commit\n' +
+    '  5. git push -u origin <feature-branch>\n' +
+    '  6. gh pr create --fill && gh pr merge --squash\n' +
+    '  7. git checkout master && git reset --hard origin/master\n'
   );
   process.exit(2);
 }

package/hooks/beads-stop-gate.mjs

@@ -1,10 +1,9 @@
 #!/usr/bin/env node
 // beads-stop-gate — Claude Code Stop hook
 // Blocks the agent from stopping when in_progress beads issues remain.
-// Forces the session close protocol before declaring done.
 // Exit 0: allow stop  |  Exit 2: block stop (stderr shown to Claude)
 //
-// Installed by: npx --package=@jaggerxtrm/specialists install
+// Installed by: specialists install
 
 import { execSync } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
@@ -37,12 +36,15 @@ try {
 
 if (inProgress > 0) {
   process.stderr.write(
-    '\u{1F6AB} BEADS STOP GATE: Cannot stop with unresolved in_progress issues.\n' +
-    'Complete the session close protocol:\n\n' +
-    '  bd close <id1> <id2> ...\n' +
-    '  git add <files> && git commit -m "..."\n' +
-    '  git push\n\n' +
-    `Open issues:\n${summary}\n`
+    '🚫 BEADS STOP GATE: Unresolved issues — complete the session close protocol.\n\n' +
+    `Open issues:\n${summary}\n\n` +
+    'Session close protocol:\n' +
+    '  3. bd close <id1> <id2> ...               close all in_progress issues\n' +
+    '  4. git add <files> && git commit -m "..."  commit your changes\n' +
+    '  5. git push -u origin <feature-branch>     push feature branch\n' +
+    '  6. gh pr create --fill                     create PR\n' +
+    '  7. gh pr merge --squash                    merge PR\n' +
+    '  8. git checkout master && git reset --hard origin/master\n'
   );
   process.exit(2);
 }

package/hooks/specialists-main-guard.mjs

@@ -28,14 +28,21 @@ try {
 }
 
 const tool = input.tool_name ?? '';
-const blockMsg =
-  `⛔ Direct edits on '${branch}' are not allowed.\n` +
-  `Create a feature branch first: git checkout -b feature/<name>`;
 
 const WRITE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
 
 if (WRITE_TOOLS.has(tool)) {
-  process.stderr.write(blockMsg + '\n');
+  process.stderr.write(
+    `⛔ You are on '${branch}' — never edit files directly on master.\n\n` +
+    'Full workflow:\n' +
+    '  1. git checkout -b feature/<name>         ← start here\n' +
+    '  2. bd create + bd update in_progress      track your work\n' +
+    '  3. Edit files / write code\n' +
+    '  4. bd close <id> && git add && git commit\n' +
+    '  5. git push -u origin feature/<name>\n' +
+    '  6. gh pr create --fill && gh pr merge --squash\n' +
+    '  7. git checkout master && git reset --hard origin/master\n'
+  );
   process.exit(2);
 }
 
@@ -49,11 +56,15 @@ if (tool === 'Bash') {
     const impliedMaster = tokens.length <= 3 && (branch === 'main' || branch === 'master');
     if (explicitMaster || impliedMaster) {
       process.stderr.write(
-        `⛔ Direct push to '${branch}' is not allowed.\n` +
-        `Use the PR workflow instead:\n` +
-        `  git push -u origin <feature-branch>\n` +
-        `  gh pr create --fill\n` +
-        `  gh pr merge --squash\n`
+        `⛔ Don't push directly to '${branch}' — use the PR workflow.\n\n` +
+        'Next steps:\n' +
+        '  5. git push -u origin <feature-branch>     ← push your branch\n' +
+        '  6. gh pr create --fill                      create PR\n' +
+        '     gh pr merge --squash                     merge it\n' +
+        '  7. git checkout master                      sync master\n' +
+        '     git reset --hard origin/master\n\n' +
+        'If you\'re not on a feature branch yet:\n' +
+        '  git checkout -b feature/<name>    (then re-commit and push)\n'
       );
       process.exit(2);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "2.1.15",
+  "version": "2.1.17",
   "description": "OmniSpecialist — 7-tool MCP orchestration layer powered by the Specialist System. Discover and execute .specialist.yaml files across project/user/system scopes via pi.",
   "main": "dist/index.js",
   "type": "module",