@jaggerxtrm/specialists 2.1.5 → 2.1.7

package/README.md

@@ -14,13 +14,12 @@
 
 ## How it works
 
-Specialists are `.specialist.yaml` files that define an autonomous agent: its model, system prompt, task template, and permission tier. The server discovers them across three scopes:
+Specialists are `.specialist.yaml` files that define an autonomous agent: its model, system prompt, task template, and permission tier. The server discovers them across two scopes:
 
 | 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 |
 
 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.
 
@@ -170,8 +169,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 +197,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

@@ -24786,19 +24786,16 @@ class SpecialistLoader {
   cache = new Map;
   projectDir;
   userDir;
-  systemDir;
   constructor(options = {}) {
     this.projectDir = options.projectDir ?? process.cwd();
     this.userDir = options.userDir ?? join(homedir(), ".agents", "specialists");
-    this.systemDir = options.systemDir ?? join(new URL(import.meta.url).pathname, "..", "..", "specialists");
   }
   getScanDirs() {
     return [
       { path: join(this.projectDir, "specialists"), scope: "project" },
       { path: join(this.projectDir, ".claude", "specialists"), scope: "project" },
       { path: join(this.projectDir, ".agent-forge", "specialists"), scope: "project" },
-      { path: this.userDir, scope: "user" },
-      { path: this.systemDir, scope: "system" }
+      { path: this.userDir, scope: "user" }
     ].filter((d) => existsSync(d.path));
   }
   async list(category) {

package/package.json

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