@jaggerxtrm/specialists 3.5.0 → 3.6.0

package/README.md

@@ -40,6 +40,13 @@ specialists feed -f
 bd close <id> --reason "Done"
 ```
 
+Merge worktree branches:
+
+```bash
+specialists merge <bead-id>           # single chain or epic (topological)
+specialists merge <bead-id> --rebuild # rebuild after merge
+```
+
 `specialists run` prints `[job started: <id>]` early and also writes the id to `.specialists/jobs/latest`.
 
 Ad-hoc work:
@@ -81,6 +88,7 @@ specialists doctor
 | xtrm / worktree integration | [docs/worktree.md](docs/worktree.md) |
 | RPC mode notes | [docs/pi-rpc.md](docs/pi-rpc.md) |
 | Pi subprocess isolation and extensions | [docs/pi-session.md](docs/pi-session.md) |
+| NodeSupervisor architecture, node lifecycle, and `sp node` CLI | [docs/nodes.md](docs/nodes.md) |
 
 ## Project structure
 
@@ -125,11 +133,14 @@ Use `specialists init` instead.
 
 ```bash
 bun run build
-bun test
+bun test           # bun vitest run (default)
+bun run test:node  # node vitest run (subprocess-safe alternative)
 specialists help
 specialists quickstart
 ```
 
+`test:node` uses plain `node vitest run` as an alternative to `bun --bun vitest`. Useful for executor/codex subprocess chains that may trigger stall detection during vitest's tinypool worker initialization silence.
+
 ## License
 
 MIT

package/config/hooks/specialists-session-start.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// specialists-session-start — Claude Code SessionStart hook
+// Injects specialists context at the start of every session:
+//   • Active background jobs (if any)
+//   • Available specialists list
+//   • Key CLI commands reminder
+//
+// Installed by: specialists init
+// Hook type: SessionStart
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const cwd     = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+const HOME    = homedir();
+const jobsDir = join(cwd, '.specialists', 'jobs');
+const lines   = [];
+
+// ── 1. Active background jobs ──────────────────────────────────────────────
+if (existsSync(jobsDir)) {
+  let entries = [];
+  try { entries = readdirSync(jobsDir); } catch { /* ignore */ }
+
+  const activeJobs = [];
+  for (const jobId of entries) {
+    const statusPath = join(jobsDir, jobId, 'status.json');
+    if (!existsSync(statusPath)) continue;
+    try {
+      const s = JSON.parse(readFileSync(statusPath, 'utf-8'));
+      if (s.status === 'running' || s.status === 'starting') {
+        const elapsed = s.elapsed_s !== undefined ? ` (${s.elapsed_s}s)` : '';
+        activeJobs.push(
+          `  • ${s.specialist ?? jobId}  [${s.status}]${elapsed}  →  specialists result ${jobId}`
+        );
+      }
+    } catch { /* malformed status.json */ }
+  }
+
+  if (activeJobs.length > 0) {
+    lines.push('## Specialists — Active Background Jobs');
+    lines.push('');
+    lines.push(...activeJobs);
+    lines.push('');
+    lines.push('Use `specialists feed <job-id> --follow` to stream events, or `specialists result <job-id>` when done.');
+    lines.push('');
+  }
+}
+
+// ── 2. Available specialists (read YAML dirs directly) ────────────────────
+function readSpecialistNames(dir) {
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir)
+      .filter(f => f.endsWith('.specialist.yaml'))
+      .map(f => f.replace('.specialist.yaml', ''));
+  } catch {
+    return [];
+  }
+}
+
+const projectNames = readSpecialistNames(join(cwd, 'specialists'));
+const userNames    = readSpecialistNames(join(HOME, '.agents', 'specialists'));
+
+// Merge, deduplicate, sort
+const allNames = [...new Set([...projectNames, ...userNames])].sort();
+
+if (allNames.length > 0) {
+  lines.push('## Specialists — Available');
+  lines.push('');
+  if (projectNames.length > 0) {
+    lines.push(`project (${projectNames.length}): ${projectNames.join(', ')}`);
+  }
+  if (userNames.length > 0) {
+    // Only show user-scope names not already in project
+    const extraUser = userNames.filter(n => !projectNames.includes(n));
+    if (extraUser.length > 0) {
+      lines.push(`user    (${extraUser.length}): ${extraUser.join(', ')}`);
+    }
+  }
+  lines.push('');
+}
+
+// ── 3. Key commands reminder ───────────────────────────────────────────────
+lines.push('## Specialists — Session Quick Reference');
+lines.push('');
+lines.push('```');
+lines.push('specialists list                                   # discover available specialists');
+lines.push('specialists run <name> --prompt "..."              # run foreground (streams output)');
+lines.push('specialists run <name> --prompt "..."              # run; job ID prints on stderr');
+lines.push('specialists feed <job-id> --follow                 # tail live events');
+lines.push('specialists result <job-id>                        # read final output');
+lines.push('specialists status                                 # system health');
+lines.push('specialists doctor                                 # troubleshoot issues');
+lines.push('```');
+lines.push('');
+lines.push('MCP tools: use_specialist (foreground only)');
+
+// ── Output ─────────────────────────────────────────────────────────────────
+if (lines.length === 0) process.exit(0);
+
+process.stdout.write(JSON.stringify({
+  type: 'inject',
+  content: lines.join('\n'),
+}) + '\n');

package/config/nodes/research-multi.node.json

@@ -0,0 +1,11 @@
+{
+  "name": "research-multi",
+  "coordinator": "node-coordinator",
+  "members": [],
+  "initialPrompt": "You are coordinating a multi-researcher discovery node. There are NO pre-spawned members — you must spawn all members yourself via sp node spawn-member.\n\nYour mission: gather deep, wide research across both the codebase and online sources, then synthesize.\n\nOrchestration plan:\n\nPhase 1 — parallel discovery (spawn all at once, then wait-phase):\n  - explorer-1: codebase explorer — map the current context injection pipeline (what gets injected at specialist spawn, where bd prime runs, how runner.ts builds the prompt, what gitnexus cheatsheet injection looks like, token costs)\n  - researcher-1: search for agent/LLM context efficiency patterns — how do frontier agent frameworks (LangMem, MemGPT, AgentOS, CrewAI) handle memory retrieval and context injection? token budget strategies?\n  - researcher-2: search for bun:sqlite FTS5 and vector/embedding search capabilities — can bun:sqlite do semantic search? what scoring approaches work for memory retrieval without embeddings? SQLite FTS5 rank() function?\n  - researcher-3: search for specialist memory system patterns across GitHub — find real implementations of agent memory stores, typed retrieval, decay/scoring. Use ghgrep to find patterns.\n\nPhase 2 — synthesis (spawn after phase 1 evidence is in):\n  - overthinker-1: deep analysis of the research findings — design the optimal bd prime filtering strategy and the specialist memory SQLite schema. Critique assumptions. Synthesize across all phase 1 findings.\n\nExecution rules:\n  - Spawn all 4 phase-1 members simultaneously, then call wait-phase with all 4 member keys.\n  - After wait-phase completes, read ALL member results with sp node result before spawning overthinker.\n  - Do not advance to phase 2 until you have read every phase 1 result.\n  - After overthinker completes, read its result and synthesize final recommendations, then remain in waiting for operator closure.",
+  "memoryNamespace": "research-multi",
+  "completion_strategy": "manual",
+  "max_retries": 3,
+  "default_context_depth": 1,
+  "base_branch": "master"
+}

package/config/nodes/research.node.json

@@ -0,0 +1,27 @@
+{
+  "name": "research",
+  "coordinator": "node-coordinator",
+  "members": [
+    {
+      "memberId": "explorer",
+      "specialist": "explorer",
+      "role": "Codebase exploration and discovery. Read files, search code, map architecture. Report findings."
+    },
+    {
+      "memberId": "overthinker",
+      "specialist": "overthinker",
+      "role": "Deep multi-phase analysis. Reason about tradeoffs, critique assumptions, synthesize insights."
+    },
+    {
+      "memberId": "researcher",
+      "specialist": "researcher",
+      "role": "Documentation and code researcher. Targeted lookup via ctx7/deepwiki CLIs, or discovery mode via ghgrep to find real-world patterns across GitHub. Report findings with code examples."
+    }
+  ],
+  "initialPrompt": "You are coordinating a research node with an explorer, an overthinker, and a researcher. Plan an explicit explore phase first, then wait for the phase barrier, read every member result, synthesize the evidence, and decide whether a design or implementation phase is actually needed. On start, launch the explorer for codebase findings. Use the researcher only when external docs or ecosystem patterns are needed. Use the overthinker after evidence is gathered to analyze tradeoffs and synthesize insights. Maintain memory_patch entries (facts, questions, decisions) throughout.",
+  "memoryNamespace": "research",
+  "completion_strategy": "pr",
+  "max_retries": 3,
+  "default_context_depth": 1,
+  "base_branch": "master"
+}

package/config/presets.json

@@ -0,0 +1,26 @@
+{
+  "cheap": {
+    "description": "Low-cost, fast responses — best for exploration and simple tasks",
+    "fields": {
+      "specialist.execution.model": "dashscope/qwen3.5-plus",
+      "specialist.execution.thinking_level": "off",
+      "specialist.execution.stall_timeout_ms": 60000
+    }
+  },
+  "medium": {
+    "description": "Balanced cost/quality — good default for most tasks",
+    "fields": {
+      "specialist.execution.model": "anthropic/claude-sonnet-4-6",
+      "specialist.execution.thinking_level": "low",
+      "specialist.execution.stall_timeout_ms": 120000
+    }
+  },
+  "power": {
+    "description": "Maximum capability — complex implementation and reasoning",
+    "fields": {
+      "specialist.execution.model": "openai-codex/gpt-5.4",
+      "specialist.execution.thinking_level": "high",
+      "specialist.execution.stall_timeout_ms": 300000
+    }
+  }
+}