@jaggerxtrm/specialists 2.0.0

package/README.md

@@ -0,0 +1,144 @@
+# OmniSpecialist
+
+**One MCP Server. Many Specialists. Real AI Agents.**
+
+[![npm version](https://img.shields.io/npm/v/@jaggerxtrm/specialists.svg)](https://www.npmjs.com/package/@jaggerxtrm/specialists)
+[![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.
+
+**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.
+
+---
+
+## 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:
+
+| Scope | Location | Purpose |
+|-------|----------|---------|
+| **project** | `./specialists/` | Per-project specialists |
+| **user** | `~/.agents/specialists/` | Personal specialists |
+| **system** | bundled with OmniSpecialist | 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.
+
+---
+
+## MCP Tools (7)
+
+| Tool | Description |
+|------|-------------|
+| `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 |
+| `stop_specialist` | Cancel a running job |
+| `run_parallel` | Run multiple specialists concurrently or as a pipeline |
+| `specialist_status` | Circuit breaker health + job status |
+
+---
+
+## Built-in Specialists
+
+| Specialist | Model | Purpose |
+|-----------|-------|---------|
+| `init-session` | Haiku | Analyze git state, recent commits, surface relevant context |
+| `codebase-explorer` | Gemini Flash | Architecture analysis, directory structure, patterns |
+| `overthinker` | Sonnet | 4-phase deep reasoning: analysis → critique → synthesis → output |
+| `parallel-review` | Sonnet | Concurrent code review across multiple focus areas |
+| `bug-hunt` | Sonnet | Autonomous bug investigation from symptoms to root cause |
+| `feature-design` | Sonnet | Turn feature requests into structured implementation plans |
+| `auto-remediation` | Gemini Flash | Apply fixes to identified issues automatically |
+| `report-generator` | Haiku | Synthesize data/analysis results into structured markdown |
+| `test-runner` | Haiku | Run tests, parse results, surface failures |
+
+---
+
+## Permission Tiers
+
+Specialists declare their required permission level. OmniSpecialist enforces this at spawn time via `pi --tools`:
+
+| Tier | Allowed tools | Use case |
+|------|--------------|----------|
+| `READ_ONLY` | read, bash (read-only), grep, find, ls | Analysis, exploration |
+| `LOW` | + edit, write | Code modifications |
+| `MEDIUM` | + git operations | Commits, branching |
+| `HIGH` | Full autonomy | External API calls, push |
+
+---
+
+## Installation
+
+```bash
+node <(curl -fsSL https://raw.githubusercontent.com/Jaggerxtrm/unit.ai-specialists/master/bin/install.js)
+```
+
+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.
+
+Then **restart Claude Code**.
+
+---
+
+## Writing a Specialist
+
+Create a `.yaml` file in `./specialists/` (project scope) or `~/.agents/specialists/` (user scope):
+
+```yaml
+specialist:
+  metadata:
+    name: my-specialist
+    version: 1.0.0
+    description: "What this specialist does."
+    category: analysis
+    tags: [analysis, example]
+    updated: "2026-03-07"
+
+  execution:
+    mode: tool
+    model: anthropic/claude-haiku-4-5
+    fallback_model: google-gemini-cli/gemini-3-flash-preview
+    timeout_ms: 120000
+    response_format: markdown
+    permission_required: READ_ONLY
+
+  prompt:
+    system: |
+      You are a specialist that does X.
+      Produce a structured markdown report.
+
+    task_template: |
+      $prompt
+
+      Working directory: $cwd
+
+  communication:
+    publishes: [result]
+```
+
+**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`.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Jaggerxtrm/specialists.git
+cd specialists
+bun install
+bun run build
+bun test
+```
+
+- **Build**: `bun build src/index.ts --target=node --outfile=dist/index.js`
+- **Test**: `bun --bun vitest run` (40 unit tests)
+- **Lint**: `tsc --noEmit`
+
+See [CLAUDE.md](CLAUDE.md) for the full architecture guide and [ROADMAP.md](ROADMAP.md) for planned features.
+
+---
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// OmniSpecialist Installer
+// Usage: npx --package=github:Jaggerxtrm/specialists install
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const HOME            = homedir();
+const SPECIALISTS_DIR = join(HOME, '.agents', 'specialists');
+const MCP_NAME        = 'specialists';
+const GITHUB_PKG      = '@jaggerxtrm/specialists';
+
+// ── ANSI helpers ──────────────────────────────────────────────────────────────
+const dim    = (s) => `\x1b[2m${s}\x1b[0m`;
+const green  = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const bold   = (s) => `\x1b[1m${s}\x1b[0m`;
+const red    = (s) => `\x1b[31m${s}\x1b[0m`;
+
+function section(label) {
+  const line = '─'.repeat(Math.max(0, 40 - label.length));
+  console.log(`\n${bold(`── ${label} ${line}`)}`);
+}
+
+function ok(label)   { console.log(`  ${green('✓')} ${label}`); }
+function skip(label) { console.log(`  ${yellow('○')} ${label}`); }
+function info(label) { console.log(`  ${dim(label)}`); }
+function fail(label) { console.log(`  ${red('✗')} ${label}`); }
+
+function isInstalled(cmd) {
+  const r = spawnSync('which', [cmd], { encoding: 'utf8' });
+  return r.status === 0 && r.stdout.trim().length > 0;
+}
+
+function npmInstallGlobal(pkg) {
+  const r = spawnSync('npm', ['install', '-g', pkg], { stdio: 'inherit', encoding: 'utf8' });
+  if (r.status !== 0) throw new Error(`npm install -g ${pkg} failed`);
+}
+
+function installDolt() {
+  if (process.platform === 'darwin') {
+    info('Installing dolt via brew...');
+    const r = spawnSync('brew', ['install', 'dolt'], { stdio: 'inherit', encoding: 'utf8' });
+    r.status === 0 ? ok('dolt installed') : fail('brew install dolt failed — install manually: brew install dolt');
+  } else {
+    info('Installing dolt (requires sudo)...');
+    const r = spawnSync(
+      'sudo', ['bash', '-c', 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash'],
+      { stdio: 'inherit', encoding: 'utf8' }
+    );
+    if (r.status === 0) {
+      ok('dolt installed');
+    } else {
+      fail('dolt install failed — install manually:');
+      info("  sudo bash -c 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash'");
+    }
+  }
+}
+
+function registerMCP() {
+  const check = spawnSync('claude', ['mcp', 'get', MCP_NAME], { encoding: 'utf8' });
+  if (check.status === 0) return false;
+
+  npmInstallGlobal(GITHUB_PKG);
+
+  const r = spawnSync('claude', [
+    'mcp', 'add', '--scope', 'user', MCP_NAME, '--', MCP_NAME,
+  ], { stdio: 'inherit', encoding: 'utf8' });
+  if (r.status !== 0) throw new Error('claude mcp add failed');
+  return true;
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+console.log('\n' + bold('  OmniSpecialist — full-stack installer'));
+
+// 1. pi
+section('pi  (coding agent runtime)');
+if (isInstalled('pi')) {
+  skip('pi already installed');
+} else {
+  info('Installing @mariozechner/pi-coding-agent...');
+  npmInstallGlobal('@mariozechner/pi-coding-agent');
+  ok('pi installed');
+}
+
+// 2. beads
+section('beads  (issue tracker)');
+if (isInstalled('bd')) {
+  skip('bd already installed');
+} else {
+  info('Installing @beads/bd...');
+  npmInstallGlobal('@beads/bd');
+  ok('bd installed');
+}
+
+// 3. dolt
+section('dolt  (beads sync backend)');
+if (isInstalled('dolt')) {
+  skip('dolt already installed');
+} else {
+  installDolt();
+}
+
+// 4. Specialists MCP
+section('Specialists MCP');
+const registered = registerMCP();
+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');
+}
+
+// 6. Health check
+section('Health check');
+if (isInstalled('pi')) {
+  const r = spawnSync('pi', ['--list-models'], { encoding: 'utf8' });
+  r.status === 0
+    ? ok('pi has at least one active provider')
+    : skip('No active provider — run pi config to set one up');
+}
+
+// 7. 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(`  3. ${bold('Update later:')} re-run this installer\n`);