@jaggerxtrm/specialists 2.1.13 → 2.1.15

package/README.md

@@ -195,13 +195,18 @@ Pre-script output is formatted as `<pre_flight_context>` XML and available in `t
 
 ## CLI
 
-Once installed globally, the `specialists` command provides:
+Once installed globally, `specialists <command>` provides:
 
 | Command | Description |
 |---------|-------------|
-| `specialists install` | Full-stack installer: pi, beads, dolt, MCP registration, hooks, scaffold |
-| `specialists list` | List all discovered specialists with model, description, and scope |
-| `specialists version` | Print the installed package version |
+| `specialists install` | Full-stack installer: pi, beads, dolt, MCP registration, hooks |
+| `specialists init` | Scaffold `./specialists/` and inject usage block into `AGENTS.md` |
+| `specialists list` | List discovered specialists with model, description, and scope |
+| `specialists edit <name> --<field> <value>` | Edit a specialist field in-place |
+| `specialists run <name>` | Run a specialist and stream output to stdout |
+| `specialists status` | Show system health: specialists, pi, beads, MCP |
+| `specialists version` | Print installed package version |
+| `specialists help` | Show command reference |
 | `specialists` | Start the MCP server (called by Claude Code — not for direct use) |
 
 ### specialists list
@@ -218,6 +223,59 @@ Specialists (9)
 
 Scopes: `[project]` = `./specialists/` (or `.claude/specialists/`), `[user]` = `~/.agents/specialists/`
 
+Filter by scope or category: `specialists list --scope user --category analysis`
+
+### specialists edit
+
+Edit individual fields without opening the file:
+
+```bash
+specialists edit init-session --model anthropic/claude-sonnet-4-6
+specialists edit bug-hunt --permission MEDIUM
+specialists edit overthinker --timeout 300000
+specialists edit codebase-explorer --tags "analysis,architecture"
+specialists edit my-spec --description "New description" --dry-run
+```
+
+Editable fields: `model`, `fallback-model`, `description`, `permission`, `timeout`, `tags`
+
+### specialists run
+
+Run a specialist directly from the terminal — no MCP required:
+
+```bash
+# Inline prompt
+specialists run init-session --prompt "What changed recently?"
+
+# Pipe from stdin
+echo "Analyse the architecture" | specialists run codebase-explorer
+
+# Override model, skip beads
+specialists run overthinker --prompt "Refactor strategy?" --model anthropic/claude-sonnet-4-6 --no-beads
+```
+
+Output streams to stdout in real time. Model, duration, and bead ID appear on stderr.
+
+### specialists status
+
+```
+specialists status
+
+── Specialists ───────────────────────────
+  ✓ 9 found  (9 project)
+
+── pi  (coding agent runtime) ────────────
+  ✓ v0.57.1  —  4 providers active  (anthropic, google-gemini-cli, qwen, zai)
+
+── beads  (issue tracker) ────────────────
+  ✓ bd installed  v0.59.0
+  ✓ .beads/ present in project
+
+── MCP ───────────────────────────────────
+  ✓ specialists binary installed  /usr/local/bin/specialists
+  verify registration: claude mcp get specialists
+```
+
 ---
 
 ## Development

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,187 +110,29 @@ 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 }],
+  hooks: [{ type: 'command', command: BEADS_EDIT_GATE_FILE, timeout: 10000 }],
 };
 const BEADS_COMMIT_GATE_ENTRY = {
   matcher: 'Bash',
-  hooks: [{ type: 'command', command: BEADS_COMMIT_GATE_FILE, timeout: 10 }],
+  hooks: [{ type: 'command', command: BEADS_COMMIT_GATE_FILE, timeout: 10000 }],
 };
 const BEADS_STOP_GATE_ENTRY = {
-  hooks: [{ type: 'command', command: BEADS_STOP_GATE_FILE, timeout: 10 }],
+  hooks: [{ type: 'command', command: BEADS_STOP_GATE_FILE, timeout: 10000 }],
 };
 
 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/dist/index.js

@@ -18149,7 +18149,7 @@ import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { dirname as dirname2, join as join4 } from "node:path";
 async function run() {
-  const installerPath = join4(dirname2(fileURLToPath(import.meta.url)), "..", "..", "bin", "install.js");
+  const installerPath = join4(dirname2(fileURLToPath(import.meta.url)), "..", "bin", "install.js");
   execFileSync(process.execPath, [installerPath], { stdio: "inherit" });
 }
 var init_install = () => {};

package/hooks/beads-commit-gate.mjs

@@ -0,0 +1,55 @@
+#!/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);

package/hooks/beads-edit-gate.mjs

@@ -0,0 +1,47 @@
+#!/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);

package/hooks/beads-stop-gate.mjs

@@ -0,0 +1,50 @@
+#!/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);

package/hooks/specialists-main-guard.mjs

@@ -0,0 +1,63 @@
+#!/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 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.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(
+        `⛔ 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`
+      );
+      process.exit(2);
+    }
+  }
+}
+
+process.exit(0);

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "2.1.13",
+  "version": "2.1.15",
   "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",