@jaggerxtrm/specialists 2.1.7 → 2.1.9

package/README.md

@@ -92,7 +92,14 @@ npm install -g @jaggerxtrm/specialists
 specialists install
 ```
 
-Installs: **pi** (`@mariozechner/pi-coding-agent`), **beads** (`@beads/bd`), **dolt** (interactive sudo on Linux / brew on macOS), registers the `specialists` MCP at user scope, scaffolds `~/.agents/specialists/`, and installs the `main-guard` PreToolUse hook (`~/.claude/hooks/main-guard.mjs`) to protect `main`/`master` branches from direct edits.
+Installs: **pi** (`@mariozechner/pi-coding-agent`), **beads** (`@beads/bd`), **dolt** (interactive sudo on Linux / brew on macOS), registers the `specialists` MCP at user scope, scaffolds `~/.agents/specialists/`, copies built-in specialists, and installs four Claude Code hooks into `~/.claude/hooks/`:
+
+| Hook | Event | Enforces |
+|------|-------|---------|
+| `specialists-main-guard.mjs` | `PreToolUse` | No direct edits/commits on `main`/`master` — use a feature branch |
+| `beads-edit-gate.mjs` | `PreToolUse` | No file edits without an `in_progress` beads issue (beads projects only) |
+| `beads-commit-gate.mjs` | `PreToolUse` | No `git commit` while issues are still `in_progress` — close them first |
+| `beads-stop-gate.mjs` | `Stop` | Agent cannot declare done while `in_progress` issues remain |
 
 After running, **restart Claude Code** to load the MCP. Re-run `specialists install` at any time to update or repair the installation.
 

package/bin/install.js

@@ -138,24 +138,220 @@ const HOOK_ENTRY = {
   hooks: [{ type: 'command', command: HOOK_FILE }],
 };
 
+
+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: 10 }],
+};
+const BEADS_COMMIT_GATE_ENTRY = {
+  matcher: 'Bash',
+  hooks: [{ type: 'command', command: BEADS_COMMIT_GATE_FILE, timeout: 10 }],
+};
+const BEADS_STOP_GATE_ENTRY = {
+  hooks: [{ type: 'command', command: BEADS_STOP_GATE_FILE, timeout: 10 }],
+};
+
 function installHook() {
   mkdirSync(HOOKS_DIR, { recursive: true });
+
+  // Write all hook files
   writeFileSync(HOOK_FILE, HOOK_SCRIPT, 'utf8');
   chmodSync(HOOK_FILE, 0o755);
+  writeFileSync(BEADS_EDIT_GATE_FILE, BEADS_EDIT_GATE_SCRIPT, 'utf8');
+  chmodSync(BEADS_EDIT_GATE_FILE, 0o755);
+  writeFileSync(BEADS_COMMIT_GATE_FILE, BEADS_COMMIT_GATE_SCRIPT, 'utf8');
+  chmodSync(BEADS_COMMIT_GATE_FILE, 0o755);
+  writeFileSync(BEADS_STOP_GATE_FILE, BEADS_STOP_GATE_SCRIPT, 'utf8');
+  chmodSync(BEADS_STOP_GATE_FILE, 0o755);
 
   let settings = {};
   if (existsSync(SETTINGS_FILE)) {
     try { settings = JSON.parse(readFileSync(SETTINGS_FILE, 'utf8')); } catch {}
   }
 
-  if (!Array.isArray(settings.hooks?.PreToolUse)) {
-    settings.hooks = settings.hooks ?? {};
-    settings.hooks.PreToolUse = [];
-  }
-
-  settings.hooks.PreToolUse = settings.hooks.PreToolUse
-    .filter(e => !e.hooks?.some(h => h.command?.includes('specialists-main-guard')));
+  settings.hooks = settings.hooks ?? {};
+
+  // PreToolUse — replace any existing specialists-managed entries
+  if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(e =>
+    !e.hooks?.some(h =>
+      h.command?.includes('specialists-main-guard') ||
+      h.command?.includes('beads-edit-gate') ||
+      h.command?.includes('beads-commit-gate')
+    )
+  );
   settings.hooks.PreToolUse.push(HOOK_ENTRY);
+  settings.hooks.PreToolUse.push(BEADS_EDIT_GATE_ENTRY);
+  settings.hooks.PreToolUse.push(BEADS_COMMIT_GATE_ENTRY);
+
+  // Stop — replace any existing beads-stop-gate entry
+  if (!Array.isArray(settings.hooks.Stop)) settings.hooks.Stop = [];
+  settings.hooks.Stop = settings.hooks.Stop.filter(e =>
+    !e.hooks?.some(h => h.command?.includes('beads-stop-gate'))
+  );
+  settings.hooks.Stop.push(BEADS_STOP_GATE_ENTRY);
 
   mkdirSync(CLAUDE_DIR, { recursive: true });
   writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + '\n', 'utf8');
@@ -229,9 +425,12 @@ section('Claude Code hooks');
 const hookExisted = existsSync(HOOK_FILE);
 installHook();
 hookExisted
-  ? ok('main-guard hook updated')
-  : ok('main-guard hook installed → ~/.claude/hooks/specialists-main-guard.mjs');
-info('Blocks Edit/Write/git commit/push on main or master branch');
+  ? 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('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');
 
 // 7. Health check
 section('Health check');