@jaggerxtrm/specialists 2.1.4 → 2.1.6

package/README.md

@@ -19,8 +19,8 @@ Specialists are `.specialist.yaml` files that define an autonomous agent: its mo
 | Scope | Location | Purpose |
 |-------|----------|---------|
 | **project** | `./specialists/` | Per-project specialists |
-| **user** | `~/.agents/specialists/` | Personal specialists |
-| **system** | bundled with the package | Built-in defaults |
+| **user** | `~/.agents/specialists/` | Built-in defaults (copied on install) + your own |
+| **system** | bundled with the package | Fallback if user scope is empty |
 
 When a specialist runs, the server spawns a `pi` subprocess with the right model, tools, and system prompt injected. Output streams back in real time via cursor-based polling.
 
@@ -93,7 +93,7 @@ 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/`.
+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.
 
 After running, **restart Claude Code** to load the MCP. Re-run `specialists install` at any time to update or repair the installation.
 
@@ -170,8 +170,19 @@ specialist:
 
   communication:
     publishes: [result]
+
+  # Optional: run scripts before/after the specialist
+  skills:
+    scripts:
+      - path: ./scripts/health-check.sh
+        phase: pre            # runs before the task prompt
+        inject_output: true   # output injected as $pre_script_output
+      - path: ./scripts/cleanup.sh
+        phase: post           # runs after the specialist completes
 ```
 
+Pre-script output is formatted as `<pre_flight_context>` XML and available in `task_template` via `$pre_script_output`. Scripts run locally via the host shell — not inside the pi agent. Failed scripts include their exit code so the specialist can reason about failures.
+
 **Model IDs** use the full provider/model format: `anthropic/claude-sonnet-4-6`, `google-gemini-cli/gemini-3-flash-preview`, `anthropic/claude-haiku-4-5`.
 
 ---
@@ -187,7 +198,7 @@ bun test
 ```
 
 - **Build**: `bun build src/index.ts --target=node --outfile=dist/index.js`
-- **Test**: `bun --bun vitest run` (67 unit tests)
+- **Test**: `bun --bun vitest run` (68 unit tests)
 - **Lint**: `tsc --noEmit`
 
 See [CLAUDE.md](CLAUDE.md) for the full architecture guide and [ROADMAP.md](ROADMAP.md) for planned features.

package/bin/install.js

@@ -3,7 +3,7 @@
 // Usage: npx --package=@jaggerxtrm/specialists install
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, readdirSync, chmodSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
@@ -16,6 +16,9 @@ const HOOK_FILE       = join(HOOKS_DIR, 'specialists-main-guard.mjs');
 const MCP_NAME        = 'specialists';
 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;
+
 // ── ANSI helpers ──────────────────────────────────────────────────────────────
 const dim    = (s) => `\x1b[2m${s}\x1b[0m`;
 const green  = (s) => `\x1b[32m${s}\x1b[0m`;
@@ -136,15 +139,13 @@ const HOOK_ENTRY = {
 };
 
 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 */ }
+    try { settings = JSON.parse(readFileSync(SETTINGS_FILE, 'utf8')); } catch {}
   }
 
   if (!Array.isArray(settings.hooks?.PreToolUse)) {
@@ -152,7 +153,6 @@ function installHook() {
     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);
@@ -199,23 +199,39 @@ registered
   ? ok(`MCP '${MCP_NAME}' registered at user scope`)
   : skip(`MCP '${MCP_NAME}' already registered`);
 
-// 5. Scaffold user specialists directory
-section('Scaffold');
-if (!existsSync(SPECIALISTS_DIR)) {
-  mkdirSync(SPECIALISTS_DIR, { recursive: true });
-  ok('~/.agents/specialists/ created');
-} else {
-  skip('~/.agents/specialists/ already exists');
+// 5. Scaffold + copy built-in specialists
+section('Specialists');
+mkdirSync(SPECIALISTS_DIR, { recursive: true });
+
+const yamlFiles = existsSync(BUNDLED_SPECIALISTS_DIR)
+  ? readdirSync(BUNDLED_SPECIALISTS_DIR).filter(f => f.endsWith('.specialist.yaml'))
+  : [];
+
+let installed = 0;
+let skipped = 0;
+for (const file of yamlFiles) {
+  const dest = join(SPECIALISTS_DIR, file);
+  if (existsSync(dest)) {
+    skipped++;
+  } else {
+    copyFileSync(join(BUNDLED_SPECIALISTS_DIR, file), dest);
+    installed++;
+  }
 }
 
+if (installed > 0) ok(`${installed} specialist(s) installed → ~/.agents/specialists/`);
+if (skipped  > 0) skip(`${skipped} specialist(s) already exist (user-modified, keeping)`);
+if (installed === 0 && skipped === 0) skip('No built-in specialists found');
+info('Edit any .specialist.yaml in ~/.agents/specialists/ to customise models, prompts, permissions');
+
 // 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 (JS, no jq needed)');
+  : ok('main-guard hook installed → ~/.claude/hooks/specialists-main-guard.mjs');
+info('Blocks Edit/Write/git commit/push on main or master branch');
 
 // 7. Health check
 section('Health check');
@@ -231,4 +247,5 @@ 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 and hooks`);
-console.log(`  3. ${bold('Update later:')} re-run this installer\n`);
+console.log(`  3. ${bold('Customise specialists:')} edit files in ${yellow('~/.agents/specialists/')}`);
+console.log(`  4. ${bold('Update later:')} re-run this installer (existing specialists preserved)\n`);

package/dist/index.js

@@ -24916,15 +24916,15 @@ class PiAgentSession {
   _doneReject;
   _agentEndReceived = false;
   _killed = false;
+  _lineBuffer = "";
   meta;
   constructor(options, meta) {
     this.options = options;
     this.meta = meta;
   }
   static async create(options) {
-    const provider = mapSpecialistBackend(options.model);
     const meta = {
-      backend: provider,
+      backend: options.model.includes("/") ? options.model.split("/")[0] : mapSpecialistBackend(options.model),
       model: options.model,
       sessionId: crypto.randomUUID(),
       startedAt: new Date
@@ -24940,7 +24940,6 @@ class PiAgentSession {
       "rpc",
       ...providerArgs,
       "--no-session",
-      "--print",
       ...extraArgs
     ];
     const toolsFlag = mapPermissionToTools(this.options.permissionLevel);
@@ -24958,9 +24957,19 @@ class PiAgentSession {
     });
     this._donePromise = donePromise;
     this.proc.stdout?.on("data", (chunk) => {
-      for (const line of chunk.toString().split(`
-`).filter(Boolean)) {
-        this._handleEvent(line);
+      this._lineBuffer += chunk.toString();
+      const lines = this._lineBuffer.split(`
+`);
+      this._lineBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line.trim())
+          this._handleEvent(line);
+      }
+    });
+    this.proc.stdout?.on("end", () => {
+      if (this._lineBuffer.trim()) {
+        this._handleEvent(this._lineBuffer);
+        this._lineBuffer = "";
       }
     });
     this.proc.on("close", (code) => {
@@ -25049,6 +25058,7 @@ class PiAgentSession {
     const msg = JSON.stringify({ type: "prompt", message: task }) + `
 `;
     this.proc?.stdin?.write(msg);
+    this.proc?.stdin?.end();
   }
   async waitForDone() {
     return this._donePromise;
@@ -25056,26 +25066,6 @@ class PiAgentSession {
   async getLastOutput() {
     return this._lastOutput;
   }
-  async executeBash(command) {
-    return new Promise((resolve) => {
-      const id = crypto.randomUUID();
-      const handler = (chunk) => {
-        for (const line of chunk.toString().split(`
-`).filter(Boolean)) {
-          try {
-            const ev = JSON.parse(line);
-            if (ev.id === id) {
-              this.proc?.stdout?.off("data", handler);
-              resolve(ev.output ?? ev.data?.output ?? "");
-            }
-          } catch {}
-        }
-      };
-      this.proc?.stdout?.on("data", handler);
-      this.proc?.stdin?.write(JSON.stringify({ type: "bash", command, id }) + `
-`);
-    });
-  }
   kill() {
     this._killed = true;
     this.proc?.kill();
@@ -25145,6 +25135,32 @@ function shouldCreateBead(beadsIntegration, permissionRequired) {
 }
 
 // src/specialist/runner.ts
+import { execSync } from "node:child_process";
+import { basename } from "node:path";
+function runScript(scriptPath) {
+  try {
+    const output = execSync(scriptPath, { encoding: "utf8", timeout: 30000 });
+    return { name: basename(scriptPath), output, exitCode: 0 };
+  } catch (e) {
+    return { name: basename(scriptPath), output: e.stdout ?? e.message ?? "", exitCode: e.status ?? 1 };
+  }
+}
+function formatScriptOutput(results) {
+  const withOutput = results.filter((r) => r.output.trim());
+  if (withOutput.length === 0)
+    return "";
+  const blocks = withOutput.map((r) => {
+    const status = r.exitCode === 0 ? "" : ` exit_code="${r.exitCode}"`;
+    return `<script name="${r.name}"${status}>
+${r.output.trim()}
+</script>`;
+  }).join(`
+`);
+  return `<pre_flight_context>
+${blocks}
+</pre_flight_context>`;
+}
+
 class SpecialistRunner {
   deps;
   sessionFactory;
@@ -25168,7 +25184,10 @@ class SpecialistRunner {
       circuit_breaker_state: circuitBreaker.getState(model),
       scope: "project"
     });
-    const variables = { prompt: options.prompt, ...options.variables };
+    const preScripts = spec.specialist.skills?.scripts?.filter((s) => s.phase === "pre") ?? [];
+    const preResults = preScripts.map((s) => runScript(s.path)).filter((_, i) => preScripts[i].inject_output);
+    const preScriptOutput = formatScriptOutput(preResults);
+    const variables = { prompt: options.prompt, pre_script_output: preScriptOutput, ...options.variables };
     const renderedTask = renderTemplate(prompt.task_template, variables);
     const promptHash = createHash("sha256").update(renderedTask).digest("hex").slice(0, 16);
     await hooks.emit("post_render", invocationId, metadata.name, metadata.version, {
@@ -25233,22 +25252,12 @@ You have access via Bash:
       });
       await session.start();
       onKillRegistered?.(session.kill.bind(session));
-      const preScripts = spec.specialist.skills?.scripts?.filter((s) => s.phase === "pre") ?? [];
-      let preScriptOutput = "";
-      for (const script of preScripts) {
-        const out = await session.executeBash(script.path);
-        if (script.inject_output)
-          preScriptOutput += out + `
-`;
-      }
-      const finalTask = preScriptOutput ? renderTemplate(renderedTask, { pre_script_output: preScriptOutput.trim() }) : renderedTask;
-      await session.prompt(finalTask);
+      await session.prompt(renderedTask);
       await session.waitForDone();
       output = await session.getLastOutput();
       const postScripts = spec.specialist.skills?.scripts?.filter((s) => s.phase === "post") ?? [];
-      for (const script of postScripts) {
-        await session.executeBash(script.path);
-      }
+      for (const script of postScripts)
+        runScript(script.path);
       circuitBreaker.recordSuccess(model);
     } catch (err) {
       circuitBreaker.recordFailure(model);

package/package.json

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