@jaggerxtrm/specialists 2.0.1 → 2.1.0

package/README.md

@@ -1,4 +1,4 @@
-# OmniSpecialist
+# Specialists
 
 **One MCP Server. Many Specialists. Real AI Agents.**
 
@@ -6,7 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
 
-OmniSpecialist is a **Model Context Protocol (MCP) server** that lets Claude (and other AI agents) discover and run specialist agents — each a full autonomous coding agent powered by [pi](https://github.com/mariozechner/pi), scoped to a specific task.
+**Specialists** is a **Model Context Protocol (MCP) server** that lets Claude (and other AI agents) discover and run specialist agents — each a full autonomous coding agent powered by [pi](https://github.com/mariozechner/pi), scoped to a specific task.
 
 **Designed for agents, not just users.** Claude can autonomously route heavy tasks (code review, bug hunting, deep reasoning, session init) to the right specialist without user intervention. Specialists run in the background while Claude continues working.
 
@@ -14,26 +14,27 @@ OmniSpecialist is a **Model Context Protocol (MCP) server** that lets Claude (an
 
 ## How it works
 
-Specialists are `.specialist.yaml` files that define an autonomous agent: its model, system prompt, task template, and permission tier. OmniSpecialist 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 three scopes:
 
 | Scope | Location | Purpose |
 |-------|----------|---------|
 | **project** | `./specialists/` | Per-project specialists |
 | **user** | `~/.agents/specialists/` | Personal specialists |
-| **system** | bundled with OmniSpecialist | Built-in defaults |
+| **system** | bundled with the package | Built-in defaults |
 
-When a specialist runs, OmniSpecialist spawns a `pi` subprocess with the right model, tools, and system prompt injected. Output streams back in real time via cursor-based polling.
+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.
 
 ---
 
-## MCP Tools (7)
+## MCP Tools (8)
 
 | Tool | Description |
 |------|-------------|
+| `specialist_init` | Session bootstrap: init beads if needed, return available specialists |
 | `list_specialists` | Discover all available specialists across scopes |
 | `use_specialist` | Run a specialist synchronously and return the result |
 | `start_specialist` | Fire-and-forget: start a specialist job, returns `job_id` |
-| `poll_specialist` | Poll a running job; returns delta since last cursor |
+| `poll_specialist` | Poll a running job; returns delta since last cursor + `beadId` |
 | `stop_specialist` | Cancel a running job |
 | `run_parallel` | Run multiple specialists concurrently or as a pipeline |
 | `specialist_status` | Circuit breaker health + job status |
@@ -58,7 +59,7 @@ When a specialist runs, OmniSpecialist spawns a `pi` subprocess with the right m
 
 ## Permission Tiers
 
-Specialists declare their required permission level. OmniSpecialist enforces this at spawn time via `pi --tools`:
+Specialists declare their required permission level, enforced at spawn time via `pi --tools`:
 
 | Tier | Allowed tools | Use case |
 |------|--------------|----------|
@@ -69,13 +70,60 @@ Specialists declare their required permission level. OmniSpecialist enforces thi
 
 ---
 
+## Beads Integration
+
+Specialists with write permissions (`LOW`/`MEDIUM`/`HIGH`) automatically create a [beads](https://github.com/beads/bd) issue when they run and close it on completion. Control this per-specialist with `beads_integration`:
+
+```yaml
+beads_integration: auto    # default — create for LOW/MEDIUM/HIGH, skip for READ_ONLY
+beads_integration: always  # always create, regardless of permission tier
+beads_integration: never   # never create
+```
+
+The orchestrating agent can retrieve the `beadId` from `poll_specialist` output to link the issue for follow-up (`bd remember`, `bd update --notes`, etc.).
+
+---
+
 ## Installation
 
+### One-line installer (recommended)
+
 ```bash
-node <(curl -fsSL https://raw.githubusercontent.com/Jaggerxtrm/unit.ai-specialists/master/bin/install.js)
+npx --package=@jaggerxtrm/specialists install
 ```
 
-Clones the repo to `~/.agents/omnispecialist/`, installs dependencies (bun if available, else npm), registers the MCP as a direct `node` call — no npx overhead on every startup. Also installs **pi** and **beads** if missing.
+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.
+
+---
+
+### Manual installation
+
+**1. pi** — coding agent runtime:
+```bash
+npm install -g @mariozechner/pi-coding-agent
+```
+Run `pi` once, then `pi config` to enable your model providers (Anthropic, Google, etc.).
+
+**2. beads** — issue tracker:
+```bash
+npm install -g @beads/bd
+```
+
+**3. dolt** — beads sync backend:
+```bash
+# Linux
+sudo bash -c 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash'
+# macOS
+brew install dolt
+```
+
+**4. specialists + MCP:**
+```bash
+npm install -g @jaggerxtrm/specialists
+claude mcp add --scope user specialists -- specialists
+```
 
 Then **restart Claude Code**.
 
@@ -93,7 +141,7 @@ specialist:
     description: "What this specialist does."
     category: analysis
     tags: [analysis, example]
-    updated: "2026-03-07"
+    updated: "2026-03-09"
 
   execution:
     mode: tool
@@ -132,7 +180,7 @@ bun test
 ```
 
 - **Build**: `bun build src/index.ts --target=node --outfile=dist/index.js`
-- **Test**: `bun --bun vitest run` (40 unit tests)
+- **Test**: `bun --bun vitest run` (67 unit tests)
 - **Lint**: `tsc --noEmit`
 
 See [CLAUDE.md](CLAUDE.md) for the full architecture guide and [ROADMAP.md](ROADMAP.md) for planned features.

package/dist/index.js

@@ -24568,12 +24568,12 @@ class StdioServerTransport {
 }
 
 // src/server.ts
-import { join as join2 } from "node:path";
+import { join as join3 } from "node:path";
 
 // src/constants.ts
-var LOG_PREFIX = "[UAI-MCP]";
+var LOG_PREFIX = "[specialists]";
 var MCP_CONFIG = {
-  SERVER_NAME: "unitAI",
+  SERVER_NAME: "specialists",
   VERSION: "1.0.0",
   CAPABILITIES: {
     tools: {},
@@ -24748,6 +24748,7 @@ var SpecialistSchema = objectType({
     capabilities: CapabilitiesSchema,
     communication: CommunicationSchema,
     validation: ValidationSchema,
+    beads_integration: enumType(["auto", "always", "never"]).default("auto"),
     heartbeat: unknownType().optional()
   })
 });
@@ -25078,6 +25079,15 @@ class PiAgentSession {
   }
 }
 
+// src/specialist/beads.ts
+function shouldCreateBead(beadsIntegration, permissionRequired) {
+  if (beadsIntegration === "never")
+    return false;
+  if (beadsIntegration === "always")
+    return true;
+  return permissionRequired !== "READ_ONLY";
+}
+
 // src/specialist/runner.ts
 class SpecialistRunner {
   deps;
@@ -25087,7 +25097,7 @@ class SpecialistRunner {
     this.sessionFactory = deps.sessionFactory ?? PiAgentSession.create.bind(PiAgentSession);
   }
   async run(options, onProgress, onEvent, onMeta, onKillRegistered) {
-    const { loader, hooks, circuitBreaker } = this.deps;
+    const { loader, hooks, circuitBreaker, beadsClient } = this.deps;
     const invocationId = crypto.randomUUID();
     const start = Date.now();
     const spec = await loader.get(options.name);
@@ -25142,6 +25152,11 @@ You have access via Bash:
       timeout_ms: execution.timeout_ms,
       permission_level: permissionLevel
     });
+    const beadsIntegration = spec.specialist.beads_integration ?? "auto";
+    let beadId;
+    if (beadsClient && shouldCreateBead(beadsIntegration, execution.permission_required)) {
+      beadId = beadsClient.createBead(metadata.name) ?? undefined;
+    }
     let output;
     let session;
     try {
@@ -25179,6 +25194,8 @@ You have access via Bash:
       circuitBreaker.recordSuccess(model);
     } catch (err) {
       circuitBreaker.recordFailure(model);
+      if (beadId)
+        beadsClient?.closeBead(beadId, "ERROR", Date.now() - start, model);
       await hooks.emit("post_execute", invocationId, metadata.name, metadata.version, {
         status: "ERROR",
         duration_ms: Date.now() - start,
@@ -25198,12 +25215,17 @@ You have access via Bash:
       duration_ms: durationMs,
       output_valid: true
     });
+    if (beadId) {
+      beadsClient?.closeBead(beadId, "COMPLETE", durationMs, model);
+      beadsClient?.auditBead(beadId, metadata.name, model, 0);
+    }
     return {
       output,
       backend: session.meta.backend,
       model,
       durationMs,
-      specialistVersion: metadata.version
+      specialistVersion: metadata.version,
+      beadId
     };
   }
   async startAsync(options, registry2) {
@@ -25478,6 +25500,12 @@ class JobRegistry {
     if (meta.model)
       job.model = meta.model;
   }
+  setBeadId(id, beadId) {
+    const job = this.jobs.get(id);
+    if (!job)
+      return;
+    job.beadId = beadId;
+  }
   setKillFn(id, killFn) {
     const job = this.jobs.get(id);
     if (!job)
@@ -25499,6 +25527,8 @@ class JobRegistry {
     job.model = result.model;
     job.specialistVersion = result.specialistVersion;
     job.endedAtMs = Date.now();
+    if (result.beadId)
+      job.beadId = result.beadId;
   }
   fail(id, err) {
     const job = this.jobs.get(id);
@@ -25535,7 +25565,8 @@ class JobRegistry {
       model: job.model,
       specialist_version: job.specialistVersion,
       duration_ms: (job.endedAtMs ?? Date.now()) - job.startedAtMs,
-      error: job.error
+      error: job.error,
+      beadId: job.beadId
     };
   }
   delete(id) {
@@ -25606,15 +25637,50 @@ function createStopSpecialistTool(registry2) {
   };
 }
 
+// src/tools/specialist/specialist_init.tool.ts
+import { spawnSync } from "node:child_process";
+import { existsSync as existsSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+var specialistInitSchema = exports_external.object({});
+function createSpecialistInitTool(loader, deps) {
+  const resolved = deps ?? {
+    bdAvailable: () => spawnSync("bd", ["--version"], { stdio: "ignore" }).status === 0,
+    beadsExists: () => existsSync2(join2(process.cwd(), ".beads")),
+    bdInit: () => spawnSync("bd", ["init"], { stdio: "ignore" })
+  };
+  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.",
+    inputSchema: specialistInitSchema,
+    async execute(_input) {
+      const available = resolved.bdAvailable();
+      let initialized = false;
+      if (available) {
+        if (resolved.beadsExists()) {
+          initialized = true;
+        } else {
+          const result = resolved.bdInit();
+          initialized = result.status === 0;
+        }
+      }
+      const specialists = await loader.list();
+      return {
+        specialists,
+        beads: { available, initialized }
+      };
+    }
+  };
+}
+
 // src/server.ts
-class UnitAIServer {
+class SpecialistsServer {
   server;
   tools;
   constructor() {
     const circuitBreaker = new CircuitBreaker;
     const loader = new SpecialistLoader;
     const hooks = new HookEmitter({
-      tracePath: join2(process.cwd(), ".unitai", "trace.jsonl")
+      tracePath: join3(process.cwd(), ".specialists", "trace.jsonl")
     });
     const runner = new SpecialistRunner({ loader, hooks, circuitBreaker });
     const registry2 = new JobRegistry;
@@ -25625,7 +25691,8 @@ class UnitAIServer {
       createSpecialistStatusTool(loader, circuitBreaker),
       createStartSpecialistTool(runner, registry2),
       createPollSpecialistTool(registry2),
-      createStopSpecialistTool(registry2)
+      createStopSpecialistTool(registry2),
+      createSpecialistInitTool(loader)
     ];
     this.server = new Server({ name: MCP_CONFIG.SERVER_NAME, version: MCP_CONFIG.VERSION }, { capabilities: MCP_CONFIG.CAPABILITIES });
     this.setupHandlers();
@@ -25639,7 +25706,8 @@ class UnitAIServer {
       specialist_status: exports_external.object({}),
       start_specialist: startSpecialistSchema,
       poll_specialist: pollSpecialistSchema,
-      stop_specialist: stopSpecialistSchema
+      stop_specialist: stopSpecialistSchema,
+      specialist_init: specialistInitSchema
     };
     this.toolSchemas = schemaMap;
     this.server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -25665,7 +25733,7 @@ class UnitAIServer {
       const onProgress = (msg) => {
         this.server.notification({
           method: "notifications/message",
-          params: { level: "info", logger: "unitai", data: msg }
+          params: { level: "info", logger: "specialists", data: msg }
         }).catch(() => {});
       };
       try {
@@ -25689,7 +25757,7 @@ class UnitAIServer {
     try {
       const transport = new StdioServerTransport;
       await this.server.connect(transport);
-      logger.info(`UnitAI MCP Server v2 started — ${this.tools.length} tools registered`);
+      logger.info(`Specialists MCP Server v2 started — ${this.tools.length} tools registered`);
     } catch (error2) {
       logger.error("Failed to start server", error2);
       process.exit(1);
@@ -25702,8 +25770,8 @@ class UnitAIServer {
 
 // src/index.ts
 async function main() {
-  logger.info("Starting Unified AI MCP Tool server...");
-  const server = new UnitAIServer;
+  logger.info("Starting Specialists MCP Server...");
+  const server = new SpecialistsServer;
   await server.start();
 }
 main().catch((error2) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "2.0.1",
-  "description": "OmniSpecialist \u2014 7-tool MCP orchestration layer powered by the Specialist System. Discover and execute .specialist.yaml files across project/user/system scopes via pi.",
+  "version": "2.1.0",
+  "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": [