@jaggerxtrm/specialists 3.4.2 → 3.4.4

package/config/hooks/specialists-complete.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-// specialists-complete — Claude Code UserPromptSubmit hook
+// specialists-complete — Claude Code UserPromptSubmit/PostToolUse hook
 // Checks .specialists/ready/ for completed background job markers and injects
-// completion banners into Claude's context.
+// completion/failure banners into Claude's context.
 //
 // Installed by: specialists install
 
@@ -32,16 +32,26 @@ for (const jobId of markers) {
   try {
     let specialist = jobId;
     let elapsed = '';
+    let completionStatus = 'done';
+    let errorMessage = '';
 
     if (existsSync(statusPath)) {
       const status = JSON.parse(readFileSync(statusPath, 'utf-8'));
       specialist = status.specialist ?? jobId;
       elapsed = status.elapsed_s !== undefined ? `, ${status.elapsed_s}s` : '';
+      completionStatus = status.status ?? 'done';
+      errorMessage = status.error ? ` — ${status.error}` : '';
     }
 
-    banners.push(
-      `[Specialist '${specialist}' completed (job ${jobId}${elapsed}). Run: specialists result ${jobId}]`
-    );
+    if (completionStatus === 'error') {
+      banners.push(
+        `[Specialist '${specialist}' failed (job ${jobId}${elapsed}${errorMessage}). Run: specialists feed ${jobId} --follow]`
+      );
+    } else {
+      banners.push(
+        `[Specialist '${specialist}' completed (job ${jobId}${elapsed}). Run: specialists result ${jobId}]`
+      );
+    }
 
     // Delete marker so it only fires once
     unlinkSync(markerPath);
@@ -53,7 +63,7 @@ for (const jobId of markers) {
 
 if (banners.length === 0) process.exit(0);
 
-// UserPromptSubmit hooks inject content via JSON
+// UserPromptSubmit/PostToolUse hooks inject content via JSON
 process.stdout.write(JSON.stringify({
   type: 'inject',
   content: banners.join('\n'),

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

@@ -107,7 +107,7 @@ lines.push('specialists status                                 # system health')
 lines.push('specialists doctor                                 # troubleshoot issues');
 lines.push('```');
 lines.push('');
-lines.push('MCP tools: specialist_init · use_specialist · start_specialist · feed_specialist · run_parallel');
+lines.push('MCP tools: use_specialist (foreground only)');
 
 // ── Output ─────────────────────────────────────────────────────────────────
 if (lines.length === 0) process.exit(0);

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

@@ -5,7 +5,7 @@ description: >
   ask whether to delegate. Consult before any: code review, security audit, deep bug
   investigation, test generation, multi-file refactor, or architecture analysis. Also
   use for the mechanics of delegation: --bead workflow, --context-depth, background
-  jobs, MCP tools (use_specialist, start_specialist, feed_specialist), specialists init,
+  jobs, MCP tool (`use_specialist`), specialists init,
   or specialists doctor. Don't wait for the user to say "use a specialist" — proactively
   evaluate whether delegation makes sense.
 version: 3.6
@@ -132,7 +132,7 @@ Run `specialists list` to see what's available. Match by task type:
 - **debugger** is the most powerful investigation specialist. Uses GitNexus call-chain tracing (when available) for 5-phase root cause analysis with ranked hypotheses. Use for ANY "why is X broken" question — don't do the investigation yourself.
 - **sync-docs** is an interactive specialist — it audits first, then waits for approval before executing. This is correct behavior, not a bug.
 - **overthinker** and **reviewer** are also interactive.
-- Canonical pattern: use `start_specialist` / `specialists run` normally; interactive specialists now default to keep-alive via `execution.interactive: true`.
+- Canonical pattern: orchestration is CLI-first (`specialists run/feed/result/steer/resume/stop`); use MCP only for one-shot `use_specialist` runs.
 - Use `--no-keep-alive` only when you explicitly want a one-shot run.
 - **explorer** is fast and cheap (Haiku) but READ_ONLY — output auto-appends to the input bead's notes. Use for investigation, not implementation.
 - **executor** is the workhorse — HIGH permissions, writes code and docs, runs tests, closes beads. Best for any task that needs files written.
@@ -236,7 +236,7 @@ After each wave completes:
 ### Real wave example (from a 6-wave session)
 
 ```
-Wave 1: 2x executor → fixed --background flag + migrated start_specialist to Supervisor
+Wave 1: 2x executor → stabilized background job execution and supervisor lifecycle
 Wave 2: overthinker + 2x executor → output contract design + retry logic + footer fix
 Wave 3: 4x sync-docs + 3x explorer → docs audit (produced reports, not files)
 Wave 4: 5x executor + 2x explorer → output contract impl + READ_ONLY auto-append + 4 fixes
@@ -292,54 +292,14 @@ Available after `specialists init` and session restart.
 
 | Tool | Purpose |
 |------|---------|
-| `specialist_init` | Bootstrap once per session |
-| `use_specialist` | Foreground run; pass `bead_id` for tracked work |
-| `start_specialist` | Async: returns job ID immediately (Supervisor-backed) |
-| `feed_specialist` | Cursor-paginated run events (status + deltas) |
-| `resume_specialist` | Next-turn prompt for keep-alive jobs in `waiting` |
-| `steer_specialist` | Mid-run steering message for active jobs |
-| `stop_specialist` | Cancel (sends SIGTERM to job PID) |
-| `specialist_status` | Circuit breaker health + staleness |
-
-### CLI vs MCP equivalences
-
-| Action | CLI | MCP |
-|--------|-----|-----|
-| Run foreground (one-shot) | `specialists run <name> --bead <id>` | `use_specialist({name, bead_id})` |
-| Run background (interactive-capable) | `specialists run <name> --bead <id> --background` | `start_specialist({name, bead_id})` |
-| Monitor events | `specialists feed <job-id>` | `feed_specialist({job_id, cursor})` |
-| Read result | `specialists result <job-id>` | — (CLI only) |
-| Steer mid-run | `specialists steer <job-id> "msg"` | `steer_specialist({job_id, message})` |
-| Resume waiting | `specialists resume <job-id> "task"` | `resume_specialist({job_id, task})` |
-| Cancel | `specialists stop <job-id>` | `stop_specialist({job_id})` |
-
-**Canonical pattern:** `use_specialist` is one-shot. For interactive review/analysis flows,
-use `start_specialist` then `resume_specialist`.
-
-**Prefer CLI** for most orchestration work — it's simpler and output is easier to inspect.
-**Use MCP** (`use_specialist`) when you need a direct one-shot result in your conversation context.
+| `use_specialist` | Foreground run; pass `bead_id` for tracked work and get final output directly in conversation context |
 
----
-
-## feed_specialist Observation Pattern
-
-Use cursor-based polling for structured progress when monitoring long specialist runs:
+MCP is intentionally minimal. Use CLI commands for orchestration, monitoring, steering,
+resume, and cancellation.
+If you encounter legacy `start_specialist`, treat it as deprecated and migrate to
+`specialists run <name> --prompt "..." --background`.
 
-```bash
-# first read
-feed_specialist({job_id: "abc123"})
-# => {events:[...], next_cursor: 12, has_more: true, is_complete: false}
-
-# continue from cursor
-feed_specialist({job_id: "abc123", cursor: 12})
-# => {events:[...], next_cursor: 25, has_more: false, is_complete: true}
-```
-
-When `is_complete: true` and `has_more: false`, fetch final text with:
-
-```bash
-specialists result <job-id>
-```
+---
 
 ---