@jaggerxtrm/specialists 2.1.1 → 2.1.3

package/README.md

@@ -86,15 +86,22 @@ The orchestrating agent can retrieve the `beadId` from `poll_specialist` output
 
 ## Installation
 
-### One-line installer (recommended)
+### Recommended
 
 ```bash
-npx --package=@jaggerxtrm/specialists install
+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/`.
 
-After running, **restart Claude Code** to load the MCP.
+After running, **restart Claude Code** to load the MCP. Re-run `specialists install` at any time to update or repair the installation.
+
+### One-time (no global install)
+
+```bash
+npx --package=@jaggerxtrm/specialists install
+```
 
 ---
 

package/bin/install.js

@@ -1,14 +1,18 @@
 #!/usr/bin/env node
-// OmniSpecialist Installer
-// Usage: npx --package=github:Jaggerxtrm/specialists install
+// Specialists Installer
+// Usage: npx --package=@jaggerxtrm/specialists install
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 const HOME            = homedir();
 const SPECIALISTS_DIR = join(HOME, '.agents', 'specialists');
+const CLAUDE_DIR      = join(HOME, '.claude');
+const HOOKS_DIR       = join(CLAUDE_DIR, 'hooks');
+const SETTINGS_FILE   = join(CLAUDE_DIR, 'settings.json');
+const HOOK_FILE       = join(HOOKS_DIR, 'specialists-main-guard.sh');
 const MCP_NAME        = 'specialists';
 const GITHUB_PKG      = '@jaggerxtrm/specialists';
 
@@ -72,8 +76,80 @@ function registerMCP() {
   return true;
 }
 
+// ── Hook installation ─────────────────────────────────────────────────────────
+
+const HOOK_SCRIPT = `#!/usr/bin/env bash
+# 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
+
+BRANCH=$(git branch --show-current 2>/dev/null)
+
+# Not in a git repo or not on a protected branch — allow
+if [ -z "$BRANCH" ] || { [ "$BRANCH" != "main" ] && [ "$BRANCH" != "master" ]; }; then
+  exit 0
+fi
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name' 2>/dev/null)
+
+BLOCK_MSG="⛔ Direct edits on '$BRANCH' are not allowed.
+Create a feature branch first: git checkout -b feature/<name>"
+
+case "$TOOL" in
+  Edit|Write|MultiEdit|NotebookEdit)
+    echo "$BLOCK_MSG" >&2
+    exit 2
+    ;;
+  Bash)
+    CMD=$(echo "$INPUT" | jq -r '.tool_input.command' 2>/dev/null)
+    if echo "$CMD" | grep -qE '^git (commit|push)'; then
+      echo "$BLOCK_MSG" >&2
+      exit 2
+    fi
+    exit 0
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+`;
+
+const HOOK_ENTRY = {
+  matcher: 'Edit|Write|MultiEdit|NotebookEdit|Bash',
+  hooks: [{ type: 'command', command: HOOK_FILE }],
+};
+
+function installHook() {
+  // 1. Write hook script
+  mkdirSync(HOOKS_DIR, { recursive: true });
+  writeFileSync(HOOK_FILE, HOOK_SCRIPT, 'utf8');
+  chmodSync(HOOK_FILE, 0o755);
+
+  // 2. Merge into ~/.claude/settings.json
+  let settings = {};
+  if (existsSync(SETTINGS_FILE)) {
+    try { settings = JSON.parse(readFileSync(SETTINGS_FILE, 'utf8')); } catch { /* malformed, overwrite */ }
+  }
+
+  if (!Array.isArray(settings.hooks?.PreToolUse)) {
+    settings.hooks = settings.hooks ?? {};
+    settings.hooks.PreToolUse = [];
+  }
+
+  // Idempotent: remove any previous specialists-main-guard entry, re-add
+  settings.hooks.PreToolUse = settings.hooks.PreToolUse
+    .filter(e => !e.hooks?.some(h => h.command?.includes('specialists-main-guard')));
+  settings.hooks.PreToolUse.push(HOOK_ENTRY);
+
+  mkdirSync(CLAUDE_DIR, { recursive: true });
+  writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+
 // ── Main ──────────────────────────────────────────────────────────────────────
-console.log('\n' + bold('  OmniSpecialist — full-stack installer'));
+console.log('\n' + bold('  Specialists — full-stack installer'));
 
 // 1. pi
 section('pi  (coding agent runtime)');
@@ -119,7 +195,16 @@ if (!existsSync(SPECIALISTS_DIR)) {
   skip('~/.agents/specialists/ already exists');
 }
 
-// 6. Health check
+// 6. Claude Code hooks
+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.sh');
+info('Blocks Edit/Write/git commit/push on main or master branch');
+
+// 7. Health check
 section('Health check');
 if (isInstalled('pi')) {
   const r = spawnSync('pi', ['--list-models'], { encoding: 'utf8' });
@@ -128,9 +213,9 @@ if (isInstalled('pi')) {
     : skip('No active provider — run pi config to set one up');
 }
 
-// 7. Done
+// 8. Done
 console.log('\n' + bold(green('  Done!')));
 console.log('\n' + bold('  Next steps:'));
 console.log(`  1. ${bold('Configure pi:')} run ${yellow('pi')} then ${yellow('pi config')} to enable model providers`);
-console.log(`  2. ${bold('Restart Claude Code')} to load the MCP`);
+console.log(`  2. ${bold('Restart Claude Code')} to load the MCP and hooks`);
 console.log(`  3. ${bold('Update later:')} re-run this installer\n`);

package/dist/index.js

@@ -13393,6 +13393,11 @@ var require_public_api = __commonJS((exports) => {
   exports.stringify = stringify;
 });
 
+// src/index.ts
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname as dirname2, join as join4 } from "node:path";
+
 // node_modules/zod/v3/external.js
 var exports_external = {};
 __export(exports_external, {
@@ -25396,7 +25401,7 @@ var useSpecialistSchema = exports_external.object({
 function createUseSpecialistTool(runner) {
   return {
     name: "use_specialist",
-    description: "Execute a specialist. Full lifecycle: load → agents.md → pi → validate → output.",
+    description: "Run a specialist synchronously and wait for the result. " + "Full lifecycle: load → agents.md → pi session → output. " + "Response includes output, model, durationMs, and beadId (string | undefined). " + "beadId is set when the specialist's beads_integration policy triggered bead creation " + "(default: auto — creates for LOW/MEDIUM/HIGH permission, skips for READ_ONLY). " + "If beadId is present, use `bd update <beadId> --notes` to attach findings or " + "`bd remember` to persist key discoveries for future sessions.",
     inputSchema: useSpecialistSchema,
     async execute(input, onProgress) {
       return runner.run({
@@ -25637,7 +25642,7 @@ var startSpecialistSchema = exports_external.object({
 function createStartSpecialistTool(runner, registry2) {
   return {
     name: "start_specialist",
-    description: "Start a specialist asynchronously. Returns job_id immediately — use poll_specialist to track progress and get output. Enables true parallel execution of multiple specialists.",
+    description: "Start a specialist asynchronously. Returns job_id immediately. " + "Use poll_specialist to track progress, receive output delta, and retrieve beadId " + "(the beads issue auto-created for this run, if beads_integration policy applies). " + "Use stop_specialist to cancel. Enables true parallel execution of multiple specialists.",
     inputSchema: startSpecialistSchema,
     async execute(input) {
       const jobId = await runner.startAsync({
@@ -25659,7 +25664,7 @@ var pollSpecialistSchema = exports_external.object({
 function createPollSpecialistTool(registry2) {
   return {
     name: "poll_specialist",
-    description: "Poll a running specialist job. Returns status (running|done|error), delta (new content since cursor), next_cursor, and full output only when done. Pass next_cursor from each response as cursor on the next poll to receive only new tokens.",
+    description: "Poll a running specialist job. Returns status (running|done|error|cancelled), " + "delta (new tokens since cursor), next_cursor, and full output when done. " + "Pass next_cursor back as cursor on each subsequent poll to receive only new content. " + "Response also includes beadId (string | undefined) once the specialist has started — " + "this is the beads issue tracking this run. If present after status=done, consider: " + '`bd update <beadId> --notes "<key finding>"` to attach results, or ' + '`bd remember "<insight>"` to persist discoveries across sessions.',
     inputSchema: pollSpecialistSchema,
     async execute(input) {
       const snapshot = registry2.snapshot(input.job_id, input.cursor ?? 0);
@@ -25703,7 +25708,7 @@ function createSpecialistInitTool(loader, deps) {
   };
   return {
     name: "specialist_init",
-    description: "Session bootstrap: initializes beads in the project if not already set up, " + "then returns available specialists. Call at session start for orientation.",
+    description: "Call this first at session start. Returns available specialists and initializes beads " + "tracking (runs `bd init` if not already set up). " + "Response includes: specialists[] (use with use_specialist/start_specialist), " + "beads.available (bool), beads.initialized (bool). " + "If beads.available is true, specialists with permission LOW/MEDIUM/HIGH will auto-create " + "a beads issue when they run — no action needed from you.",
     inputSchema: specialistInitSchema,
     async execute(_input) {
       const available = resolved.bdAvailable();
@@ -25823,6 +25828,12 @@ class SpecialistsServer {
 }
 
 // src/index.ts
+if (process.argv[2] === "install") {
+  const __dirname2 = dirname2(fileURLToPath(import.meta.url));
+  const installerPath = join4(__dirname2, "..", "bin", "install.js");
+  execFileSync(process.execPath, [installerPath], { stdio: "inherit" });
+  process.exit(0);
+}
 async function main() {
   logger.info("Starting Specialists MCP Server...");
   const server = new SpecialistsServer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "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",