@jaggerxtrm/specialists 2.1.14 → 2.1.16

package/bin/install.js

@@ -18,6 +18,7 @@ const GITHUB_PKG      = '@jaggerxtrm/specialists';
 
 // Bundled specialists dir — resolved relative to this file (bin/../specialists/)
 const BUNDLED_SPECIALISTS_DIR = new URL('../specialists', import.meta.url).pathname;
+const BUNDLED_HOOKS_DIR       = new URL('../hooks', import.meta.url).pathname;
 
 // ── ANSI helpers ──────────────────────────────────────────────────────────────
 const dim    = (s) => `\x1b[2m${s}\x1b[0m`;
@@ -81,40 +82,6 @@ function registerMCP() {
 
 // ── Hook installation ─────────────────────────────────────────────────────────
 
-const HOOK_SCRIPT = `#!/usr/bin/env node
-// specialists — Claude Code PreToolUse hook
-// Blocks writes and git commit/push on main/master branch.
-// Exit 0: allow  |  Exit 2: block (message shown to user)
-//
-// Installed by: npx --package=@jaggerxtrm/specialists install
-
-import { execSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-
-let branch = '';
-try {
-  branch = execSync('git branch --show-current', {
-    encoding: 'utf8',
-    stdio: ['pipe', 'pipe', 'pipe'],
-  }).trim();
-} catch {}
-
-if (!branch || (branch !== 'main' && branch !== 'master')) {
-  process.exit(0);
-}
-
-let input;
-try {
-  input = JSON.parse(readFileSync(0, 'utf8'));
-} catch {
-  process.exit(0);
-}
-
-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)) {
@@ -143,164 +110,6 @@ const BEADS_EDIT_GATE_FILE   = join(HOOKS_DIR, 'beads-edit-gate.mjs');
 const BEADS_COMMIT_GATE_FILE = join(HOOKS_DIR, 'beads-commit-gate.mjs');
 const BEADS_STOP_GATE_FILE   = join(HOOKS_DIR, 'beads-stop-gate.mjs');
 
-const BEADS_EDIT_GATE_SCRIPT = `#!/usr/bin/env node
-// beads-edit-gate — Claude Code PreToolUse hook
-// Blocks file edits when no beads issue is in_progress.
-// 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
-
-import { execSync } from 'node:child_process';
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-
-let input;
-try {
-  input = JSON.parse(readFileSync(0, 'utf8'));
-} catch {
-  process.exit(0);
-}
-
-const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-if (!existsSync(join(cwd, '.beads'))) process.exit(0);
-
-let inProgress = 0;
-try {
-  const output = execSync('bd list --status=in_progress', {
-    encoding: 'utf8',
-    cwd,
-    stdio: ['pipe', 'pipe', 'pipe'],
-    timeout: 8000,
-  });
-  inProgress = (output.match(/in_progress/g) ?? []).length;
-} catch {
-  process.exit(0);
-}
-
-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' +
-    '  bd update <id> --status=in_progress\\n\\n' +
-    'No exceptions. Momentum is not an excuse.\\n'
-  );
-  process.exit(2);
-}
-
-process.exit(0);
-`;
-
-const BEADS_COMMIT_GATE_SCRIPT = `#!/usr/bin/env node
-// beads-commit-gate — Claude Code PreToolUse hook
-// Blocks \`git commit\` when in_progress beads issues still exist.
-// Forces: close issues first, THEN commit.
-// Exit 0: allow  |  Exit 2: block (stderr shown to Claude)
-//
-// Installed by: npx --package=@jaggerxtrm/specialists install
-
-import { execSync } from 'node:child_process';
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-
-let input;
-try {
-  input = JSON.parse(readFileSync(0, 'utf8'));
-} catch {
-  process.exit(0);
-}
-
-const tool = input.tool_name ?? '';
-if (tool !== 'Bash') process.exit(0);
-
-const cmd = input.tool_input?.command ?? '';
-if (!/\\bgit\\s+commit\\b/.test(cmd)) process.exit(0);
-
-const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-if (!existsSync(join(cwd, '.beads'))) process.exit(0);
-
-let inProgress = 0;
-let summary = '';
-try {
-  const output = execSync('bd list --status=in_progress', {
-    encoding: 'utf8',
-    cwd,
-    stdio: ['pipe', 'pipe', 'pipe'],
-    timeout: 8000,
-  });
-  inProgress = (output.match(/in_progress/g) ?? []).length;
-  summary = output.trim();
-} catch {
-  process.exit(0);
-}
-
-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\`
-  );
-  process.exit(2);
-}
-
-process.exit(0);
-`;
-
-const BEADS_STOP_GATE_SCRIPT = `#!/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
-
-import { execSync } from 'node:child_process';
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-
-let input;
-try {
-  input = JSON.parse(readFileSync(0, 'utf8'));
-} catch {
-  process.exit(0);
-}
-
-const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-if (!existsSync(join(cwd, '.beads'))) process.exit(0);
-
-let inProgress = 0;
-let summary = '';
-try {
-  const output = execSync('bd list --status=in_progress', {
-    encoding: 'utf8',
-    cwd,
-    stdio: ['pipe', 'pipe', 'pipe'],
-    timeout: 8000,
-  });
-  inProgress = (output.match(/in_progress/g) ?? []).length;
-  summary = output.trim();
-} catch {
-  process.exit(0);
-}
-
-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\`
-  );
-  process.exit(2);
-}
-
-process.exit(0);
-`;
-
 const BEADS_EDIT_GATE_ENTRY = {
   matcher: 'Edit|Write|MultiEdit|NotebookEdit|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol',
   hooks: [{ type: 'command', command: BEADS_EDIT_GATE_FILE, timeout: 10000 }],
@@ -316,14 +125,14 @@ const BEADS_STOP_GATE_ENTRY = {
 function installHook() {
   mkdirSync(HOOKS_DIR, { recursive: true });
 
-  // Write all hook files
-  writeFileSync(HOOK_FILE, HOOK_SCRIPT, 'utf8');
+  // Copy hook files from bundled hooks/ directory
+  copyFileSync(join(BUNDLED_HOOKS_DIR, 'specialists-main-guard.mjs'), HOOK_FILE);
   chmodSync(HOOK_FILE, 0o755);
-  writeFileSync(BEADS_EDIT_GATE_FILE, BEADS_EDIT_GATE_SCRIPT, 'utf8');
+  copyFileSync(join(BUNDLED_HOOKS_DIR, 'beads-edit-gate.mjs'), BEADS_EDIT_GATE_FILE);
   chmodSync(BEADS_EDIT_GATE_FILE, 0o755);
-  writeFileSync(BEADS_COMMIT_GATE_FILE, BEADS_COMMIT_GATE_SCRIPT, 'utf8');
+  copyFileSync(join(BUNDLED_HOOKS_DIR, 'beads-commit-gate.mjs'), BEADS_COMMIT_GATE_FILE);
   chmodSync(BEADS_COMMIT_GATE_FILE, 0o755);
-  writeFileSync(BEADS_STOP_GATE_FILE, BEADS_STOP_GATE_SCRIPT, 'utf8');
+  copyFileSync(join(BUNDLED_HOOKS_DIR, 'beads-stop-gate.mjs'), BEADS_STOP_GATE_FILE);
   chmodSync(BEADS_STOP_GATE_FILE, 0o755);
 
   let settings = {};
@@ -427,7 +236,7 @@ installHook();
 hookExisted
   ? ok('hooks updated (main-guard + beads gates)')
   : ok('hooks installed → ~/.claude/hooks/');
-info('main-guard: blocks Edit/Write/git commit/push on main or master branch');
+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');
 info('beads-stop-gate: requires issues closed before session end');

package/hooks/beads-commit-gate.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// beads-commit-gate — Claude Code PreToolUse hook
+// Blocks `git commit` when in_progress beads issues still exist.
+// Forces: close issues first, THEN commit.
+// Exit 0: allow  |  Exit 2: block (stderr shown to Claude)
+//
+// Installed by: specialists install
+
+import { execSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+let input;
+try {
+  input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+const tool = input.tool_name ?? '';
+if (tool !== 'Bash') process.exit(0);
+
+const cmd = input.tool_input?.command ?? '';
+if (!/\bgit\s+commit\b/.test(cmd)) process.exit(0);
+
+const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+if (!existsSync(join(cwd, '.beads'))) process.exit(0);
+
+let inProgress = 0;
+let summary = '';
+try {
+  const output = execSync('bd list --status=in_progress', {
+    encoding: 'utf8',
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 8000,
+  });
+  inProgress = (output.match(/in_progress/g) ?? []).length;
+  summary = output.trim();
+} catch {
+  process.exit(0);
+}
+
+if (inProgress > 0) {
+  process.stderr.write(
+    '🚫 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);
+}
+
+process.exit(0);

package/hooks/beads-edit-gate.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// beads-edit-gate — Claude Code PreToolUse hook
+// Blocks file edits when no beads issue is in_progress.
+// Only active in projects with a .beads/ directory.
+// Exit 0: allow  |  Exit 2: block (stderr shown to Claude)
+//
+// Installed by: specialists install
+
+import { execSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+let input;
+try {
+  input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+if (!existsSync(join(cwd, '.beads'))) process.exit(0);
+
+let inProgress = 0;
+try {
+  const output = execSync('bd list --status=in_progress', {
+    encoding: 'utf8',
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 8000,
+  });
+  inProgress = (output.match(/in_progress/g) ?? []).length;
+} catch {
+  process.exit(0);
+}
+
+if (inProgress === 0) {
+  process.stderr.write(
+    '🚫 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' +
+    '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);
+}
+
+process.exit(0);

package/hooks/beads-stop-gate.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// beads-stop-gate — Claude Code Stop hook
+// Blocks the agent from stopping when in_progress beads issues remain.
+// Exit 0: allow stop  |  Exit 2: block stop (stderr shown to Claude)
+//
+// Installed by: specialists install
+
+import { execSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+let input;
+try {
+  input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+const cwd = input.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+if (!existsSync(join(cwd, '.beads'))) process.exit(0);
+
+let inProgress = 0;
+let summary = '';
+try {
+  const output = execSync('bd list --status=in_progress', {
+    encoding: 'utf8',
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 8000,
+  });
+  inProgress = (output.match(/in_progress/g) ?? []).length;
+  summary = output.trim();
+} catch {
+  process.exit(0);
+}
+
+if (inProgress > 0) {
+  process.stderr.write(
+    '🚫 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);
+}
+
+process.exit(0);

package/hooks/specialists-main-guard.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Claude Code PreToolUse hook — block writes and direct master pushes
+// Exit 0: allow  |  Exit 2: block (message shown to user)
+//
+// Installed by: specialists install
+
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+let branch = '';
+try {
+  branch = execSync('git branch --show-current', {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  }).trim();
+} catch {}
+
+// Not in a git repo or not on a protected branch — allow
+if (!branch || (branch !== 'main' && branch !== 'master')) {
+  process.exit(0);
+}
+
+let input;
+try {
+  input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0);
+}
+
+const tool = input.tool_name ?? '';
+
+const WRITE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+
+if (WRITE_TOOLS.has(tool)) {
+  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);
+}
+
+// Block direct pushes to master — agents must use feature branches + gh pr create/merge
+if (tool === 'Bash') {
+  const cmd = (input.tool_input?.command ?? '').trim().replace(/\s+/g, ' ');
+  if (/^git push/.test(cmd)) {
+    const tokens = cmd.split(' ');
+    const lastToken = tokens[tokens.length - 1];
+    const explicitMaster = /^(master|main)$/.test(lastToken) || /:(master|main)$/.test(lastToken);
+    const impliedMaster = tokens.length <= 3 && (branch === 'main' || branch === 'master');
+    if (explicitMaster || impliedMaster) {
+      process.stderr.write(
+        `⛔ 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);
+    }
+  }
+}
+
+process.exit(0);

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "2.1.14",
+  "version": "2.1.16",
   "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",
   "files": [
     "dist/index.js",
     "bin/install.js",
-    "specialists/"
+    "specialists/",
+    "hooks/"
   ],
   "bin": {
     "specialists": "dist/index.js",