@jaggerxtrm/specialists 3.3.1 → 3.3.2

package/config/skills/specialists-usage-workspace/iteration-2/eval-code-review/without_skill/outputs/result.md

@@ -0,0 +1,146 @@
+# Code Review: src/specialist/runner.ts
+
+## Approach
+
+I read the following files to build full context before reviewing:
+
+- `/home/dawid/projects/specialists/src/specialist/runner.ts` — the target file (303 lines)
+- `/home/dawid/projects/specialists/src/specialist/beads.ts` — BeadsClient interface
+- `/home/dawid/projects/specialists/src/specialist/jobRegistry.ts` — async job state management
+- `/home/dawid/projects/specialists/src/specialist/hooks.ts` — HookEmitter
+- `/home/dawid/projects/specialists/src/specialist/loader.ts` — SpecialistLoader
+- `/home/dawid/projects/specialists/src/specialist/schema.ts` — Zod schema / types
+- `/home/dawid/projects/specialists/src/specialist/templateEngine.ts` — renderTemplate
+- `/home/dawid/projects/specialists/src/pi/session.ts` — PiAgentSession, SessionKilledError
+- `/home/dawid/projects/specialists/src/utils/circuitBreaker.ts` — CircuitBreaker
+- `/home/dawid/projects/specialists/tests/unit/specialist/runner.test.ts`
+- `/home/dawid/projects/specialists/tests/unit/specialist/runner-scripts.test.ts`
+
+---
+
+## Findings
+
+### Bug: Duplicate `sessionBackend` assignment (lines 208 and 210)
+
+```typescript
+sessionBackend = session.meta.backend;
+output = await session.getLastOutput();
+sessionBackend = session.meta.backend; // capture before finally calls kill()
+```
+
+`sessionBackend` is assigned on line 208, then again identically on line 210. The comment on line 210 says "capture before finally calls kill()" — but that is what line 208 does. The second assignment is dead code. The problem is that `getLastOutput()` (line 209) is async and could theoretically throw before line 210 is reached, which is exactly why the first capture on line 208 matters. However the second assignment is still redundant and misleading. If `getLastOutput()` throws, control jumps to the catch block before either assignment after it is reached — so the defensive intent of line 210 is already served by line 208.
+
+This is not a functional bug in practice (the value is the same both times), but it creates misleading intent and maintenance risk.
+
+### Bug: `runScript` does not sanitise or validate the script path
+
+```typescript
+function runScript(scriptPath: string): ScriptResult {
+  try {
+    const output = execSync(scriptPath, { encoding: 'utf8', timeout: 30_000 });
+```
+
+`execSync` is called with a raw string from the specialist YAML (`s.path`). This passes the string directly to a shell. If a specialist YAML is written with a path containing shell metacharacters or if it is loaded from an untrusted source, this enables shell injection. A safer approach is to use `spawnSync` with an args array (the same pattern already used in `beads.ts`), or at minimum validate that the path refers to an actual file before executing. The same risk applies to path values that start with `~/` or `./` that are interpolated without being resolved first.
+
+### Edge case: Pre-script filter logic is subtle and fragile (lines 119–121)
+
+```typescript
+const preResults = preScripts
+  .map(s => runScript(s.path))
+  .filter((_, i) => preScripts[i].inject_output);
+```
+
+All pre-scripts run unconditionally (`.map`), but only the ones with `inject_output: true` are collected in `preResults`. This means all scripts execute as side effects, while only some contribute output to the prompt. This behaviour is intentional per the test in `runner-scripts.test.ts` ("Script still runs (for side effects)"), but it is not documented at the call site. The coupling between the mapped index and `preScripts[i]` is fragile: if a future refactor introduces a flatMap or reorders the chain, the index-based correlation silently breaks. Extracting this into a named function or a `reduce` would make it safer.
+
+### Edge case: `post_execute` hook is emitted twice on success — once implicitly never on failure path
+
+On success, `post_execute` is emitted at line 250 with `status: 'COMPLETE'`. On failure, it is emitted at line 233 inside the catch block with `status: 'ERROR'` or `'CANCELLED'`. This is correct.
+
+However, there is no `post_execute` emission in the `finally` block. This means if the `finally` block itself somehow throws (unlikely since `session?.kill()` is a no-op after `close()`), no hook is emitted. This is a very low risk edge case but worth noting for observability completeness.
+
+### Edge case: Circuit breaker records success against `model`, not `sessionBackend`
+
+```typescript
+circuitBreaker.recordSuccess(model);
+```
+
+`model` is the resolved model string (possibly a fallback). `sessionBackend` is the actual backend string returned from the pi session meta (e.g. `"google-gemini-cli"`). These may differ in format. The circuit breaker is keyed by whatever string is passed — so `recordSuccess("gemini")` and `recordFailure("gemini")` must use the same key. Currently both use `model`, which is consistent. But `onMeta` can update `sessionBackend` to a different string (`provider` from pi's message_start event). If a caller were ever to rely on `sessionBackend` as a circuit-breaker key, mismatches would occur silently. The inconsistency in semantics (model string vs. backend/provider string) is worth documenting.
+
+### Edge case: `sessionPath` option is declared but never used
+
+```typescript
+export interface RunOptions {
+  /** Path to an existing pi session file for continuation (Phase 2+) */
+  sessionPath?: string;
+}
+```
+
+`sessionPath` is accepted in `RunOptions` but never read or passed to the session factory. The comment says "Phase 2+" implying it is intentionally deferred, but there is no guard, warning, or error when it is provided. A caller passing `sessionPath` expecting continuation behaviour would get silent no-op behaviour instead.
+
+### Edge case: `backendOverride` initialises registry `backend` field with `'starting'` string
+
+```typescript
+registry.register(jobId, {
+  backend: options.backendOverride ?? 'starting',
+  model: '?',
+  specialistVersion,
+});
+```
+
+When `backendOverride` is not set, the registry records `backend: 'starting'`. This is a sentinel, not an actual backend name. If a polling client reads the snapshot before `onMeta` fires, it sees `backend: 'starting'` — which is fine for display. However if the caller passes `backendOverride`, it is used as the initial `backend` value even though the actual backend used by the pi session may differ (since `backendOverride` goes through circuit breaker fallback logic). This means an async job snapshot may show an incorrect backend name until `onMeta` fires and `setMeta` is called.
+
+### Code quality: Duplicated JSDoc comment (lines 274–277)
+
+```typescript
+/** Fire-and-forget: registers job in registry, returns job_id immediately. */
+/** Fire-and-forget: registers job in registry, returns job_id immediately. */
+/** Fire-and-forget: registers job in registry, returns job_id immediately. */
+/** Fire-and-forget: registers job in registry, returns job_id immediately. */
+async startAsync(...)
+```
+
+The same JSDoc comment is repeated four times. This is a copy-paste artifact with no functional impact, but it is noise that should be cleaned up.
+
+### Code quality: Dynamic import inside hot path (line 145)
+
+```typescript
+const { readFile } = await import('node:fs/promises');
+```
+
+`readFile` is dynamically imported inside the `run()` method. The static import of `writeFile` from the same module already exists at line 3. This is redundant — `readFile` should be added to the existing static import at the top of the file. Dynamic imports inside hot-path async functions add minor per-call overhead (though Node.js caches them) and make the dependency surface less obvious at a glance.
+
+### Code quality: `sessionFactory` type parameter bound is unnecessarily wide
+
+```typescript
+export type SessionFactory = (opts: PiSessionOptions) => Promise<Pick<PiAgentSession, 'start' | 'prompt' | 'waitForDone' | 'getLastOutput' | 'getState' | 'close' | 'kill' | 'meta'>>;
+```
+
+`getState` is listed in the `Pick` but is never called on the session inside `runner.ts`. The test mock includes it too. Removing unused methods from the `Pick` would tighten the contract and make mocking simpler, though this is a low-priority style concern.
+
+### Code quality: `beadVariables` uses `options.prompt` for `bead_context` (line 125)
+
+```typescript
+const beadVariables = options.inputBeadId
+  ? { bead_context: options.prompt, bead_id: options.inputBeadId }
+  : {};
+```
+
+When `inputBeadId` is set, `bead_context` is set to `options.prompt`. The intention appears to be: if the task was sourced from a bead, expose the bead's content as `$bead_context`. But the caller already provides the bead content as `options.prompt` — so this is effectively duplicating the prompt. The test confirms this is deliberate ("Bead=# Task: Refactor auth" equals the prompt value). The variable naming is slightly misleading: `bead_context` sounds like extra context added to the prompt, but it is actually the same as `$prompt`. A comment clarifying this equivalence would help future readers.
+
+---
+
+## Summary Table
+
+| Severity | Issue | Location |
+|----------|-------|----------|
+| Low (bug, cosmetic) | Duplicate `sessionBackend` assignment | Lines 208, 210 |
+| Medium (security) | `execSync` with unsanitised shell string | Lines 59, `runScript` function |
+| Low (fragility) | Index-coupled filter for pre-script inject logic | Lines 119–121 |
+| Low (silent no-op) | `sessionPath` option accepted but never used | `RunOptions`, `run()` |
+| Low (misleading state) | `backendOverride` used as initial registry backend before `onMeta` fires | `startAsync`, lines 287–290 |
+| Trivial | Quadruplicated JSDoc comment on `startAsync` | Lines 274–277 |
+| Low (style) | Dynamic import of `readFile` inside hot path | Line 145 |
+| Low (style) | `getState` in `SessionFactory` Pick but never called | Line 32 |
+| Informational | `bead_context` === `prompt` when `inputBeadId` set — naming could mislead | Lines 125–126 |
+
+The most impactful issue is the shell injection risk in `runScript`. Everything else is low severity or cosmetic.

package/config/skills/specialists-usage-workspace/iteration-2/eval-code-review/without_skill/timing.json

@@ -0,0 +1,5 @@
+{
+  "total_tokens": 48186,
+  "duration_ms": 109896,
+  "total_duration_seconds": 109.9
+}

package/config/skills/specialists-usage-workspace/iteration-2/eval-test-coverage/with_skill/outputs/result.md

@@ -0,0 +1,89 @@
+# Test Coverage Task — With Skill
+
+## Task
+
+Identify and fill coverage gaps in `tests/unit/specialist/loader.test.ts` for `src/specialist/loader.ts`.
+
+## Skill Guidance Applied
+
+Read `/home/dawid/projects/specialists/skills/specialists-usage/SKILL.md` before starting.
+
+The skill says to delegate when a task:
+- Would take >5 minutes of focused work
+- Spans multiple files or modules
+- Benefits from a fresh, focused run
+
+This task involved analyzing a source file, cross-referencing against an existing test file, identifying untested behaviors, writing new tests across two describe blocks, and running the suite to verify. It spans 2 source files + schema context, and would take >5 minutes to do carefully. Decision: delegate.
+
+## What Was Done
+
+### Step 1: Read the skill
+
+Read `/home/dawid/projects/specialists/skills/specialists-usage/SKILL.md`. Confirmed delegation is appropriate.
+
+### Step 2: Gathered context (both files read in parallel)
+
+- `/home/dawid/projects/specialists/src/specialist/loader.ts` — source under test
+- `/home/dawid/projects/specialists/tests/unit/specialist/loader.test.ts` — existing tests
+- `/home/dawid/projects/specialists/src/specialist/schema.ts` — schema used by loader
+
+### Step 3: Listed available specialists
+
+Ran `specialists list`. Found `test-runner` (anthropic/claude-haiku-4-5) — focused on running tests, interpreting failures, and writing fixes.
+
+### Step 4: Delegated via start_specialist
+
+Used `mcp__specialists__start_specialist` with specialist `test-runner` and a detailed prompt containing:
+- Full source of `loader.ts`
+- Full source of existing `loader.test.ts`
+- Explicit list of all coverage gaps identified during pre-analysis
+- Instructions to write tests, run the suite, and fix failures
+
+Job ID: `c28f2b8f-39cf-4903-8d88-c815c1716c0c`
+Bead: `unitAI-laiv`
+
+### Step 5: Polled for results
+
+Used `mcp__specialists__poll_specialist` to wait for completion. Job completed in ~53 seconds with status `done`.
+
+### Step 6: Verified
+
+Read the updated test file and ran `bun --bun vitest run tests/unit/specialist/loader.test.ts` locally. Result: **27 tests passed, 0 failed**.
+
+## Coverage Gaps Filled
+
+### checkStaleness (entire function — zero prior coverage)
+
+Added `describe('checkStaleness', ...)` block with 10 tests:
+- Returns `OK` when `filestoWatch` is absent
+- Returns `OK` when `filestoWatch` is empty
+- Returns `OK` when `updated` is absent
+- Returns `OK` when `updated` is an invalid date string
+- Returns `OK` when watched files have NOT changed since `updated`
+- Returns `OK` when watched file does not exist (stat fails gracefully)
+- Returns `STALE` when a watched file was modified after `updated`
+- Returns `AGED` when stale AND `daysSinceUpdate > staleThresholdDays`
+- Returns `STALE` (not `AGED`) when stale but within threshold
+- Returns `STALE` when stale and no `staleThresholdDays` set
+
+### SpecialistLoader — additional it() blocks
+
+- Discovers specialists in `.claude/specialists/` with `scope='project'`
+- Discovers specialists in `.agent-forge/specialists/` with `scope='project'`
+- Discovers specialists in user dir with `scope='user'`
+- `list(category)` filters by category
+- `list(category)` returns empty when no matches
+- Ignores non-`.specialist.yaml` files
+- `invalidateCache(name)` clears only the named entry
+- `invalidateCache()` with no args clears all entries
+- `get()` resolves `~/` prefixed skill paths to homedir-relative absolute paths
+- `get()` resolves `./` prefixed skill paths relative to specialist file directory
+- `get()` leaves absolute skill paths unchanged
+
+## Files Modified
+
+- `/home/dawid/projects/specialists/tests/unit/specialist/loader.test.ts` — 6 original tests, 21 new tests added (27 total)
+
+## Why Delegate vs Do Myself
+
+The skill explicitly says "when in doubt, delegate" and that delegation produces higher quality results because the specialist has no competing context. Even though I had read both files before delegating, the analysis + careful test writing across multiple describe blocks, plus the test run + verification loop, justified delegation. The specialist completed in 53 seconds with all tests passing on first attempt — no iteration needed.

package/config/skills/specialists-usage-workspace/iteration-2/eval-test-coverage/with_skill/timing.json

@@ -0,0 +1,5 @@
+{
+  "total_tokens": 38715,
+  "duration_ms": 205928,
+  "total_duration_seconds": 205.9
+}

package/config/skills/specialists-usage-workspace/iteration-2/eval-test-coverage/without_skill/outputs/result.md

@@ -0,0 +1,96 @@
+# Test Coverage Gap Analysis and Additions: loader.ts
+
+## Files Read
+
+- `/home/dawid/projects/specialists/src/specialist/loader.ts` — source under test
+- `/home/dawid/projects/specialists/src/specialist/schema.ts` — Zod schema for Specialist type
+- `/home/dawid/projects/specialists/tests/unit/specialist/loader.test.ts` — existing tests (read before and after edits)
+
+## Existing Coverage (6 tests)
+
+| Test | What it covers |
+|------|----------------|
+| discovers specialists in project specialists/ dir | `list()` finds `specialists/` dir, returns scope=project |
+| returns empty list when no specialists | `list()` on empty dirs |
+| loads and caches a specialist by name | `get()` basic load + cache hit (same reference) |
+| throws when specialist not found | `get()` error path |
+| warns to stderr and skips invalid YAML | `list()` error handling, stderr output |
+| project-level overrides user-level (same name) | deduplication, first-wins logic |
+
+## Coverage Gaps Identified
+
+### 1. `checkStaleness()` — entirely untested (0 coverage)
+
+This is an exported async function with 6 distinct return paths:
+- Returns `'OK'` when `filestoWatch` is absent or empty
+- Returns `'OK'` when `updated` is absent
+- Returns `'OK'` when `updated` is an invalid date string (NaN guard)
+- Returns `'OK'` when watched file does not exist on disk (`.catch(() => null)`)
+- Returns `'OK'` when all watched files have mtimes older than `updated`
+- Returns `'STALE'` when a watched file was modified after `updated`
+- Returns `'AGED'` when stale AND `daysSinceUpdate > staleThresholdDays`
+- Returns `'STALE'` (not `'AGED'`) when stale but within threshold, or no threshold set
+
+### 2. Alternate project-scope discovery dirs — untested
+
+`getScanDirs()` scans three project directories: `specialists/`, `.claude/specialists/`, `.agent-forge/specialists/`. Only the first was tested.
+
+### 3. User-scope listing — untested
+
+No test verified that a specialist found in `userDir` gets `scope: 'user'`.
+
+### 4. `list()` category filter — untested
+
+The `category` parameter to `list()` was never exercised, including the case where it matches nothing.
+
+### 5. Non-.specialist.yaml files are ignored — untested
+
+The `.filter(f => f.endsWith('.specialist.yaml'))` guard had no explicit test.
+
+### 6. `get()` skills path resolution — untested (3 branches)
+
+`get()` resolves `~/`, `./`, and absolute paths differently. None of the three branches were tested.
+
+### 7. `invalidateCache()` — untested (2 branches)
+
+- `invalidateCache(name)` — removes one entry, leaves others intact
+- `invalidateCache()` — clears the entire cache
+
+## Tests Added (21 new tests)
+
+### SpecialistLoader describe block (new tests)
+
+1. **discovers specialists in .claude/specialists/ dir with project scope** — covers second scan dir
+2. **discovers specialists in .agent-forge/specialists/ dir with project scope** — covers third scan dir
+3. **discovers specialists in user dir with user scope** — covers user scope
+4. **filters list() by category** — category filter returns only matching specialists
+5. **list() returns all specialists when category filter matches none** — empty result from filter
+6. **ignores files that do not end with .specialist.yaml** — extension filter guard
+7. **invalidateCache() by name removes only that entry** — partial cache invalidation
+8. **invalidateCache() without name clears all cached entries** — full cache clear
+9. **get() resolves ~/ prefixed skill paths to absolute home-relative paths** — tilde expansion
+10. **get() resolves ./ prefixed skill paths relative to specialist file directory** — relative expansion
+11. **get() leaves absolute skill paths unchanged** — absolute passthrough
+
+### checkStaleness describe block (10 new tests)
+
+1. **returns OK when filestoWatch is absent** — no watch config
+2. **returns OK when filestoWatch is empty** — empty array guard
+3. **returns OK when updated is absent** — missing updated field
+4. **returns OK when updated is an invalid date string** — NaN guard
+5. **returns OK when all watched files have not changed since updated** — files older than updated
+6. **returns OK when watched file does not exist** — stat failure catch
+7. **returns STALE when a watched file was modified after updated** — core STALE path
+8. **returns AGED when file is stale and daysSinceUpdate exceeds staleThresholdDays** — AGED path
+9. **returns STALE (not AGED) when stale but daysSinceUpdate is within staleThresholdDays** — threshold not exceeded
+10. **returns STALE when stale and no staleThresholdDays is set** — stale without threshold
+
+## Results
+
+```
+Tests: 27 passed (6 original + 21 new)
+Test Files: 1 passed
+Duration: ~67ms
+```
+
+All tests pass. No source files were modified.

package/config/skills/specialists-usage-workspace/iteration-2/eval-test-coverage/without_skill/timing.json

@@ -0,0 +1,5 @@
+{
+  "total_tokens": 30589,
+  "duration_ms": 124787,
+  "total_duration_seconds": 124.8
+}

package/config/skills/specialists-usage-workspace/skill-snapshot/SKILL.md.old

@@ -0,0 +1,237 @@
+---
+name: specialists-usage
+description: >
+  How to use the specialists MCP server and CLI to delegate work to specialist AI agents.
+  Use this skill whenever you need to run a specialist, decide whether to delegate a task,
+  track work with --bead, monitor background jobs, read results, or understand the
+  bead-first workflow. Also use it when the user asks about specialists run, feed, result,
+  stop, list, init, doctor, or any MCP tool like use_specialist or start_specialist.
+  Consult this skill proactively when planning any task that might benefit from delegation —
+  don't wait for the user to explicitly say "use a specialist".
+version: 2.0
+---
+
+# Specialists Usage
+
+> Specialists are autonomous AI agents optimised for heavy tasks. Use them instead of doing
+> the work yourself when the task benefits from a dedicated expert, a second opinion, or a
+> model tuned for the workload.
+
+## When to Use a Specialist
+
+| Use a specialist | Do it yourself |
+|-----------------|---------------|
+| Code review / security audit | Single-file edit |
+| Deep bug investigation | Quick config change |
+| Architecture analysis | Short read-only query |
+| Test generation for a module | Obvious one-liner |
+| Refactoring across many files | Simple documentation update |
+| Long-running analysis (>5 min) | Trivial formatting fix |
+
+**Rule of thumb**: if the task would take you >5 minutes or benefit from a second opinion, delegate it.
+
+---
+
+## Primary Workflow: Bead-First (Tracked Work)
+
+The canonical pattern for any real work. Always use `--bead` for tracked tasks.
+
+```bash
+# 1. Create a bead to track the work
+bd create --title "Review auth module for security issues" --type task --priority 2
+
+# 2. Run the specialist, passing the bead ID
+specialists run code-review --bead unitAI-abc [--context-depth 1] [--background]
+
+# 3. Monitor progress
+specialists feed -f                          # follow all active jobs
+
+# 4. Close the bead when done
+bd close unitAI-abc --reason "Review complete, 3 issues found"
+```
+
+**`--context-depth N`** — controls how much bead context is injected into the specialist's
+system prompt. Defaults to `1` (immediate bead only). Increase for deeper dependency context.
+
+**`--no-beads`** — skips creating a new tracking bead for this run. Does **not** disable
+reading the input bead passed via `--bead`. Use when you don't want an auto-created sub-issue.
+
+---
+
+## Secondary Workflow: Ad-Hoc (Untracked Work)
+
+For quick, exploratory, or one-off tasks with no issue to track.
+
+```bash
+specialists run codebase-explorer --prompt "Map the CLI architecture"
+```
+
+Use `--prompt` only when there's no bead. For anything worth tracking, use `--bead`.
+
+---
+
+## Discovery
+
+```bash
+specialists list                       # all specialists in this project
+specialists list --category analysis   # filter by category
+specialists list --json                # machine-readable
+```
+
+Specialists are **project-scoped only** — loaded from `./specialists/*.specialist.yaml`.
+User-scope (`~/.specialists/`) is deprecated.
+
+---
+
+## Running a Specialist
+
+### Foreground (streams output in real time)
+
+```bash
+specialists run <name> --bead <id>
+specialists run <name> --prompt "..."          # ad-hoc only
+```
+
+- Output streams to stdout as tokens arrive
+- Ctrl+C sends SIGTERM (clean stop)
+- Exit code 0 = success
+
+### Background (returns immediately, job runs async)
+
+```bash
+specialists run <name> --bead <id> --background
+# → Job started: job_a1b2c3d4
+```
+
+Use background mode for tasks that will take >30 seconds, or when you want to keep working
+while the specialist runs.
+
+### Other run flags
+
+| Flag | Purpose |
+|------|---------|
+| `--model <model>` | Override model for this run only |
+| `--no-beads` | Skip creating auto-tracking bead (still reads `--bead` input) |
+| `--context-depth N` | Bead context depth, default 1 |
+| stdin | Pipe a prompt: `cat brief.md \| specialists run code-review --bead <id>` |
+
+---
+
+## Background Job Lifecycle
+
+```
+specialists run --background
+      │
+      ▼
+  job_a1b2c3d4  [starting]
+      │
+      ▼
+  job_a1b2c3d4  [running]   ← specialists feed -f
+      │
+      ├─► done   → specialists result <id>
+      └─► error  → specialists feed <id>  (see error event)
+```
+
+### Monitor with feed
+
+```bash
+specialists feed                              # snapshot of all jobs
+specialists feed -f                           # follow all active jobs (live)
+specialists feed job_a1b2c3d4 --follow        # follow a specific job
+```
+
+Event types in the feed:
+- `text` — streamed output token
+- `thinking` — model reasoning token
+- `tool` — specialist calling a tool (phase: start/end)
+- `run_complete` — specialist finished
+
+### Read the result
+
+```bash
+specialists result job_a1b2c3d4              # prints output, exits 1 if still running
+specialists result job_a1b2c3d4 > out.md     # capture to file
+```
+
+### Cancel
+
+```bash
+specialists stop job_a1b2c3d4                # sends SIGTERM
+```
+
+### Completion Banner
+
+When a background job completes, the next prompt you submit will show:
+
+```
+[Specialist 'code-review' completed (job job_a1b2c3d4, 42s). Run: specialists result job_a1b2c3d4]
+```
+
+This is injected by the `specialists-complete` hook. Retrieve the result with the shown command.
+
+---
+
+## MCP Tools (Claude Code)
+
+Available after `specialists init` has been run and Claude Code restarted.
+
+| Tool | When to use |
+|------|-------------|
+| `specialist_init` | **Start of every session** — bootstraps context, lists specialists |
+| `list_specialists` | Discover specialists programmatically |
+| `use_specialist` | **Preferred for foreground runs** — full lifecycle, pass `bead_id` for tracked work |
+| `start_specialist` | Start async job, returns job ID immediately |
+| `poll_specialist` | Check job status and read delta output |
+| `stop_specialist` | Cancel a running job |
+| `run_parallel` | Run multiple specialists concurrently or as a pipeline |
+| `specialist_status` | Circuit breaker health + staleness info |
+
+**Recommended pattern for tracked work:**
+
+```
+1. specialist_init                              ← bootstrap once per session
+2. use_specialist(name, prompt, bead_id=id)    ← foreground, bead context injected
+   OR
+2. start_specialist(name, prompt, bead_id=id)  ← async for long tasks
+3. poll_specialist(job_id)                     ← repeat until status=done
+```
+
+---
+
+## Project Setup
+
+```bash
+specialists init           # creates specialists/, .specialists/, injects AGENTS.md workflow
+specialists list           # verify specialists are discovered
+```
+
+Run `specialists init` once per project root. `specialists install` and `specialists setup`
+are **deprecated** — they redirect to `init`.
+
+---
+
+## Editing Specialists
+
+```bash
+specialists edit code-review --model anthropic/claude-sonnet-4-6
+specialists edit code-review --timeout 180000
+specialists edit code-review --permission HIGH
+specialists edit code-review --description "Updated description"
+specialists edit code-review --dry-run                             # preview without writing
+```
+
+---
+
+## Troubleshooting
+
+```bash
+specialists doctor         # detailed checks with fix hints (hooks, MCP, zombie jobs, pi)
+specialists status         # system health overview
+```
+
+Common issues:
+- **"specialist not found"** → run `specialists list`; only project-scope is searched
+- **Job hangs** → check `specialists feed <id>` for stall; use `specialists stop`
+- **MCP tools missing** → run `specialists init` then restart Claude Code
+- **Hook not firing** → run `specialists doctor` to verify hook wiring
+- **Invalid YAML skipped** → warnings now print to stderr with filename and reason