@jaggerxtrm/specialists 3.3.4 → 3.4.0

package/README.md

@@ -28,18 +28,20 @@ specialists list
 
 ```bash
 sp list
-sp run bug-hunt --bead <id> --background
+sp run bug-hunt --bead <id>
 ```
 
 Tracked work:
 
 ```bash
 bd create "Investigate auth bug" -t bug -p 1 --json
-specialists run bug-hunt --bead <id> --background
+specialists run bug-hunt --bead <id>
 specialists feed -f
 bd close <id> --reason "Done"
 ```
 
+`specialists run` prints `[job started: <id>]` early and also writes the id to `.specialists/jobs/latest`.
+
 Ad-hoc work:
 
 ```bash

package/bin/install.js

@@ -1,209 +1,20 @@
 #!/usr/bin/env node
 
-import { spawnSync } from 'node:child_process';
-import {
-  chmodSync,
-  copyFileSync,
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  writeFileSync,
-} from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
+// DEPRECATED: This script is deprecated. Use `specialists init` instead.
 
-const CWD = process.cwd();
-const CLAUDE_DIR = join(CWD, '.claude');
-const HOOKS_DIR = join(CLAUDE_DIR, 'hooks');
-const SETTINGS_FILE = join(CLAUDE_DIR, 'settings.json');
-const MCP_FILE = join(CWD, '.mcp.json');
-const BUNDLED_HOOKS_DIR = new URL('../hooks', import.meta.url).pathname;
-const BUNDLED_SPECIALISTS_DIR = new URL('../specialists', import.meta.url).pathname;
-const USER_SPECIALISTS_DIR = join(homedir(), '.agents', 'specialists');
-
-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, 44 - 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 run(cmd, args, options = {}) {
-  return spawnSync(cmd, args, {
-    encoding: 'utf8',
-    stdio: 'pipe',
-    ...options,
-  });
-}
-
-function commandOk(cmd, args = ['--version']) {
-  const result = run(cmd, args);
-  return result.status === 0 && !result.error;
-}
-
-function loadJson(path, fallback) {
-  if (!existsSync(path)) return structuredClone(fallback);
-  try {
-    return JSON.parse(readFileSync(path, 'utf8'));
-  } catch {
-    return structuredClone(fallback);
-  }
-}
-
-function saveJson(path, value) {
-  writeFileSync(path, JSON.stringify(value, null, 2) + '\n', 'utf8');
-}
-
-function sameFileContent(a, b) {
-  if (!existsSync(a) || !existsSync(b)) return false;
-  return readFileSync(a, 'utf8') === readFileSync(b, 'utf8');
-}
-
-const HOOKS = [
-  {
-    event: 'UserPromptSubmit',
-    file: 'specialists-complete.mjs',
-    timeout: 5000,
-  },
-  {
-    event: 'SessionStart',
-    file: 'specialists-session-start.mjs',
-    timeout: 8000,
-  },
-];
-
-function findHookCommands(settings, event, fileName) {
-  const entries = settings?.hooks?.[event];
-  if (!Array.isArray(entries)) return [];
-  return entries.flatMap((entry) =>
-    (entry.hooks ?? [])
-      .map((hook) => hook.command)
-      .filter((command) => typeof command === 'string' && command.includes(fileName)),
-  );
-}
-
-function ensureHook(settings, hook) {
-  const dest = join(HOOKS_DIR, hook.file);
-  const source = join(BUNDLED_HOOKS_DIR, hook.file);
-  const existingCommands = findHookCommands(settings, hook.event, hook.file);
-  const externalOwner = existingCommands.find((command) => command !== dest);
-
-  if (externalOwner) {
-    skip(`${hook.file} already managed externally — deferring`);
-    info(`existing command: ${externalOwner}`);
-    return false;
-  }
-
-  mkdirSync(HOOKS_DIR, { recursive: true });
-  const changed = !sameFileContent(source, dest);
-  if (changed) {
-    copyFileSync(source, dest);
-    chmodSync(dest, 0o755);
-    ok(`${hook.file} installed in .claude/hooks/`);
-  } else {
-    skip(`${hook.file} already up to date`);
-  }
-
-  settings.hooks ??= {};
-  settings.hooks[hook.event] ??= [];
-  settings.hooks[hook.event] = settings.hooks[hook.event].filter(
-    (entry) => !(entry.hooks ?? []).some((h) => h.command === dest),
-  );
-  settings.hooks[hook.event].push({
-    hooks: [{ type: 'command', command: dest, timeout: hook.timeout }],
-  });
-  ok(`${hook.file} registered for ${hook.event}`);
-  return true;
-}
-
-function installBundledSpecialists() {
-  if (!existsSync(BUNDLED_SPECIALISTS_DIR)) {
-    skip('bundled specialists dir not found — skipping');
-    return;
-  }
-  mkdirSync(USER_SPECIALISTS_DIR, { recursive: true });
-  const files = readdirSync(BUNDLED_SPECIALISTS_DIR).filter(f => f.endsWith('.specialist.yaml'));
-  for (const file of files) {
-    const source = join(BUNDLED_SPECIALISTS_DIR, file);
-    const dest = join(USER_SPECIALISTS_DIR, file);
-    if (sameFileContent(source, dest)) {
-      skip(`${file} already up to date`);
-    } else {
-      copyFileSync(source, dest);
-      ok(`${file} installed in ~/.agents/specialists/`);
-    }
-  }
-}
-
-function ensureMcpRegistration() {
-  const mcp = loadJson(MCP_FILE, { mcpServers: {} });
-  mcp.mcpServers ??= {};
-  const existing = mcp.mcpServers.specialists;
-  const desired = { command: 'specialists', args: [] };
-
-  if (
-    existing &&
-    existing.command === desired.command &&
-    Array.isArray(existing.args) &&
-    existing.args.length === 0
-  ) {
-    skip('.mcp.json already registers specialists');
-    return;
-  }
-
-  mcp.mcpServers.specialists = desired;
-  saveJson(MCP_FILE, mcp);
-  ok('registered specialists in .mcp.json');
-}
-
-console.log(`\n${bold('Specialists installer')}`);
-console.log(dim('Project scope: prerequisite check, bundled specialists, hooks, MCP registration'));
-
-section('Prerequisite check');
-const prereqs = [
-  { name: 'pi', ok: commandOk('pi', ['--version']), required: true, help: 'Install pi first.' },
-  { name: 'bd', ok: commandOk('bd', ['--version']), required: true, help: 'Install beads (bd) first.' },
-  { name: 'xt', ok: commandOk('xt', ['--version']), required: true, help: 'xtrm-tools is required for hooks and workflow integration.' },
-];
-
-let prereqFailed = false;
-for (const prereq of prereqs) {
-  if (prereq.ok) {
-    ok(`${prereq.name} available`);
-  } else {
-    prereqFailed = prereqFailed || prereq.required;
-    fail(`${prereq.name} not found`);
-    info(prereq.help);
-  }
-}
-
-if (prereqFailed) {
-  console.log(`\n${red('Install aborted: required prerequisites are missing.')}`);
-  process.exit(1);
-}
-
-section('Specialists hooks');
-mkdirSync(CLAUDE_DIR, { recursive: true });
-const settings = loadJson(SETTINGS_FILE, {});
-for (const hook of HOOKS) ensureHook(settings, hook);
-saveJson(SETTINGS_FILE, settings);
-ok(`updated ${SETTINGS_FILE}`);
-
-section('Bundled specialists');
-installBundledSpecialists();
-
-section('MCP registration');
-ensureMcpRegistration();
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 
-console.log(`\n${bold(green('Done!'))}`);
-console.log(`  ${dim('Hooks are project-local in .claude/, and MCP is project-local in .mcp.json.')}`);
+console.log('');
+console.log(yellow('⚠ DEPRECATED: `bin/install.js` is deprecated'));
+console.log('');
+console.log(`  Use ${bold('specialists init')} instead.`);
+console.log('');
+console.log('  The init command handles all setup tasks:');
+console.log('    • creates specialists/ and .specialists/ directories');
+console.log('    • registers the MCP server in .mcp.json');
+console.log('    • injects workflow context into AGENTS.md/CLAUDE.md');
+console.log('');
+console.log(`  ${dim('Run: specialists init --help for full details')}`);
+console.log('');

package/config/skills/using-specialists/SKILL.md

@@ -73,7 +73,7 @@ Run `specialists list` to see what's available. Match by task type:
 
 | Task type | Look for |
 |-----------|----------|
-| Bug / regression investigation | `bug-hunt`, `overthinker` |
+| Bug / regression investigation | `debugger`, `overthinker` |
 | Code review | `parallel-review`, `codebase-explorer` |
 | Test generation | `test-runner` |
 | Architecture / exploration | `codebase-explorer`, `feature-design` |

package/config/specialists/debugger.specialist.yaml

@@ -0,0 +1,111 @@
+specialist:
+  metadata:
+    name: debugger
+    version: 1.2.0
+    description: >-
+      Autonomous debugger: given any symptom, error, or stack trace, systematically
+      traces call chains with GitNexus, identifies root cause at file:line precision,
+      ranks hypotheses, and delivers a prioritized, evidence-backed remediation plan.
+    category: debugging
+    tags:
+      - debugging
+      - root-cause
+      - investigation
+      - remediation
+      - gitnexus
+      - call-chain
+      - autonomous
+    updated: "2026-03-27"
+
+  execution:
+    mode: tool
+    model: anthropic/claude-sonnet-4-6
+    fallback_model: qwen-cli/qwen3-coder-plus
+    timeout_ms: 600000
+    response_format: markdown
+    permission_required: LOW
+    thinking_level: low
+
+  prompt:
+    system: |
+      You are an autonomous debugger specialist. Given a symptom, error message, or
+      stack trace, you conduct a disciplined, tool-driven investigation to identify
+      the root cause and deliver an actionable remediation plan.
+
+      ## Investigation Workflow
+
+      Work through these phases in order. Stop as soon as you have enough evidence.
+
+      ### Phase 0 — GitNexus Triage (preferred, skip if unavailable)
+
+      Use the knowledge graph to orient yourself before touching any source files.
+
+      1. `gitnexus_query({query: "<error text or symptom>"})`
+      2. `gitnexus_context({name: "<suspect symbol>"})`
+      3. Read `gitnexus://repo/{name}/process/{processName}` for execution trace details
+      4. Optional: `gitnexus_cypher({query: "MATCH path = ..."})` for custom traversal
+
+      Then read source files only for pinpointed suspects — never the whole codebase.
+
+      ### Phase 1 — File Discovery (fallback if GitNexus unavailable)
+
+      Parse the symptom for candidate locations:
+      - stack trace file paths + line numbers
+      - module/import names in errors
+      - error codes or exception types tied to subsystems
+
+      Use `grep` and `find` to locate code quickly; read only relevant sections.
+
+      ### Phase 2 — Root Cause Analysis
+
+      Determine:
+      - the exact line/expression causing failure
+      - causal explanation of observed symptom
+      - whether root cause or downstream effect
+      - likely side effects on related components
+
+      ### Phase 3 — Hypothesis Ranking
+
+      Produce 3–5 ranked hypotheses, each with:
+      - hypothesis statement
+      - supporting evidence
+      - quick confirmation experiment/command
+      - confidence (HIGH/MEDIUM/LOW)
+
+      ### Phase 4 — Remediation Plan
+
+      Produce up to 5 prioritized remediation steps with:
+      - file/line scope
+      - expected outcome
+      - verification command
+      - residual risks
+
+      ## Output Format
+
+      Always output a complete **Bug Investigation Report**:
+      - Symptoms
+      - Investigation path (GitNexus traces or files analyzed)
+      - Root cause (with file:line references)
+      - Ranked hypotheses
+      - Fix plan
+      - Concise summary
+
+      EFFICIENCY RULE: Stop using tools and write the final report after at most 15 tool calls.
+
+    task_template: |
+      Debug the following issue:
+
+      $prompt
+
+      Working directory: $cwd
+
+      Start with gitnexus_query for the symptom/error text if GitNexus is available.
+      Then trace call chains with gitnexus_context. Read source files for pinpointed suspects.
+      Fall back to grep/find if GitNexus is unavailable. Produce a full Bug Investigation Report.
+
+  capabilities:
+    required_tools: [bash, grep, find, read]
+    external_commands: [grep]
+
+  communication:
+    next_specialists: auto-remediation

package/config/specialists/explorer.specialist.yaml

@@ -1,6 +1,6 @@
 specialist:
   metadata:
-    name: codebase-explorer
+    name: explorer
     version: 1.1.0
     description: "Explores the codebase structure, identifies patterns, and answers architecture questions using GitNexus knowledge graph for deep call-chain and execution-flow awareness."
     category: analysis