Specialists

Deep material lives in docs/ — start with docs/installation.md, docs/bootstrap.md, docs/workflow.md, and docs/cli-reference.md; sp --help is authoritative for flags.

Specialists is an agent-mind runtime for getting real work done.

Two surfaces: native XTRM activation, where the Substrate Issue is the durable executable work authority (see the specialists Claude Code plugin below); and the Beads-backed job workflow, which remains available through the legacy sp CLI (sp run, sp feed, sp result, sp resume, sp steer, sp stop).

It is not just “run many agents”. The core idea is that a long single-agent chat becomes cognitively contaminated: old hypotheses, abandoned plans, tool residue, self-review bias, forgotten constraints, and context-window noise all accumulate in one mind. Quality drops because the same context tries to be explorer, implementer, tester, reviewer, security auditor, memory keeper, and release operator at once.

Specialists gives an AI workflow a healthier shape:

• the orchestrator stays the central executive — it owns the user intent, task identity, evidence, and publication decision;
• the pinned Substrate Issue revision is the executable work contract — problem, scope, success criteria, validation, dependencies, and authorized work live there; Journal/settlement evidence records what happened without rewriting that authority;
• specialists are fresh, scoped cognitive faculties — explorer, debugger, executor, test-engineer, reviewer, sync-docs, researcher, and domain roles each get only the context, tools, rules, and output contract they need;
• structured handoffs flow back to the orchestrator — results are evidence to consume, not conversational vibes to remember;
• workspaces and gates keep changes publishable — edit-capable roles work in branches/worktrees, reviewer/QA/security roles judge against the contract.

The result is a shared project mind: continuity without hoarding every detail in one agent’s context.

Specialists sits in the xt/xtrm stack:

• pi coding agent executes model sessions and exposes tool events/RPC boundaries.
• xtrm-tools provides operator workflow: worktree sessions, .xtrm/ skills/hooks, reports, update tooling, and gates.
• Substrate (@jaggerxtrm/substrate) provides durable Issues/revisions, claims, Journal continuity, ExecutionBinding, provenance, and explicit Closure. Beads remains migration/legacy compatibility only.

See specialists.scheme.md for the full rationale.

---

Why not one big agent chat?

flowchart LR
  Long[One long agent session] --> Residue[Context residue]
  Long --> Bias[Self-review bias]
  Long --> Drift[Goal drift]
  Long --> Noise[Tool/output noise]
  Long --> Fatigue[Instruction fatigue]

  Residue --> Bad[Lower-quality decisions]
  Bias --> Bad
  Drift --> Bad
  Noise --> Bad
  Fatigue --> Bad

  Bad --> Symptoms[Symptoms]
  Symptoms --> Vibes[Reviews become vibes]
  Symptoms --> Mirrors[Tests mirror implementation]
  Symptoms --> Scope[Scope silently widens]
  Symptoms --> Forgotten[Constraints disappear]

The problem is not only token count. It is cognitive contamination. A single context window carries every role’s history, including false starts and stale assumptions. The agent starts defending its own implementation, testing what it built instead of what was requested, and treating completion claims as proof.

Specialists replaces context hoarding with contract-bound cognition.

---

The common-mind model

flowchart TD
  U[User / project need] --> O[Orchestrator\ncentral executive]
  O --> B[Substrate Issue revision\nproblem · scope · success · validation]
  B --> Check{Contract ready?}
  Check -->|repair needed| Refine[Refine scope / constraints / outputs]
  Refine --> B
  Check -->|ready| O

  O --> Choose{Choose faculty}
  Choose --> E[Explorer\nfresh read-only context]
  Choose --> D[Debugger\nfresh root-cause context]
  Choose --> X[Executor\nfresh implementation context]
  Choose --> QA[Test-engineer / test-runner\nfresh validation context]
  Choose --> R[Seconder / reviewer\nfresh judgment context]
  Choose --> Docs[Sync-docs / service-skills\nfresh documentation context]
  Choose --> Research[Researcher / domain specialist\nfresh external evidence]

  B --> E
  B --> D
  B --> X
  B --> QA
  B --> R
  B --> Docs
  B --> Research

  Rules[Mandatory rules\npermissions · tools · output schema] --> E
  Rules --> D
  Rules --> X
  Rules --> QA
  Rules --> R
  Rules --> Docs
  Rules --> Research

  E --> H[Structured handoff / evidence]
  D --> H
  X --> H
  QA --> H
  R --> H
  Docs --> H
  Research --> H

  H --> O
  O --> Decision{Next decision}
  Decision -->|resume / steer| Choose
  Decision -->|fix loop| B
  Decision -->|publish| Merge[Merge / PR / release]
  Decision -->|done| Close[Explicit Issue Closure\nafter verified evidence]

This is close to how a human mind works: a central executive does not consciously compute every perception, motor skill, language move, and memory lookup at once. It activates specialized faculties, receives summaries/evidence, and decides what to do next.

Specialists gives an AI workflow the same structure. The orchestrator remains the “self”; specialists are bounded capabilities that can be activated without permanently polluting the central context.

---

What Specialists lets you do

| Need | Use | |---|---| | Turn vague work into an executable task contract | Substrate Issue + planner / orchestrator | | Map unfamiliar local code | sp run explorer --bead <id> | | Diagnose a bug with unknown cause | sp run debugger --bead <id> | | Implement a scoped change in an isolated workspace | sp run executor --bead <id> --worktree | | Add tests from the actual implementation diff | test-engineer | | Run and classify validation commands | test-runner | | Check scope/quality before final review | seconder | | Review implementation evidence against the pinned Issue contract | reviewer/seconder against the same pinned revision; legacy sp run ... --bead remains a compatibility surface | | Research current docs, repos, APIs, papers, or domain evidence | researcher, quant-researcher, transcriber | | Sync one stale doc safely | sync-docs | | Keep service-expert skill docs aligned with code drift | service-knowledge-sync | | Generate immediate JSON/text from a specialist | sp script or sp serve | | Watch all active specialist work across repos | sp console | | Inspect runtime evidence and telemetry | sp feed, sp log, sp forensic, sp metrics | | Configure package specialists for your machine | sp init --global, sp edit --global, sp setup |

The live catalog is authoritative:

sp list
sp list --compact
sp list-rules
sp help

---

Install and bootstrap

Specialists is Bun-first and expects xtrm-tools to be installed explicitly. xtrm-tools is a runtime prerequisite, not an npm dependency of this package.

# 1. Bun
curl -fsSL https://bun.sh/install | bash
bun --version

# 2. xtrm-tools
npm install -g xtrm-tools
xt install
xt init

# 3. Specialists
npm install -g @jaggerxtrm/specialists
sp init --global       # machine-level user config and model defaults
sp setup --discovery   # inspect available models/config gaps
sp setup --plan cheap  # optional: propose model assignments
sp init                # per-repo wiring: MCP, hooks, skills, db paths
sp doctor --specialists
sp list

sp is an alias for specialists.

Claude Code plugin (optional)

Specialists ships two Claude Code plugins in the xtrm marketplace. specialists exposes specialist activation as MCP tools and injects live activation state at session start. specialists-ui is optional and draws the rows specialists raises as teammate-style transcript rows. Both are opt-in: nothing installs or enables them for you.

claude plugin marketplace add xtrm-dev/specialists
claude plugin install specialists@xtrm
claude plugin install specialists-ui@xtrm   # optional: teammate-style transcript rows

specialists-ui draws the rows the specialists plugin raises in Claude Code's own style. A channel wake becomes a teammate row, ● Specialist @explorer:d65bbed4 completed, with the wake's brief under it: run cost and purpose, the first result lines, the failing model and error, or the question. ctrl+o on a finished or failed wake shows the full result. A Specialists MCP call becomes a native tool row, ● Dispatch(executor · XTRM-4), with its result on an indented line under it. It is a separate plugin because Claude Code never runs a plugin's own drawing hooks on a row that plugin raised, and the wake comes from the specialists MCP server. Without it, everything works and the rows show as raw text.

The /specialists command and the fleet band

The specialists plugin draws the live fleet above the prompt and opens a fleet pane with /specialists. Select a row to read its result or its event feed, or to reply, steer, resume or stop it. A toast reports each activation that finishes, fails or asks a question.

| Command | Effect | |---|---| | /specialists | open or close the fleet pane | | /specialists status [activation] | the fleet report, or one activation in detail | | /specialists result <activation> | the full result of a settled activation | | /specialists feed <activation> [lines] | the activation's event feed, like sp feed | | /specialists reply <message_id> <answer> | answer a waiting activation | | /specialists steer\|resume\|stop <activation> … | act on an activation | | /specialists show\|hide\|expand\|collapse | band visibility |

<activation> is a full id or a short prefix. result and feed also reach activations from earlier sessions. The coordinator has the same feed as the specialist_feed tool.

To turn every wake off (the channel push, the wake-watch fallback and the toasts), start Claude Code with SPECIALISTS_WAKE=off. Everything stays readable through specialist_status. This is the Claude Code equivalent of the Pi extension's --no-specialist-wake.

Updates

The plugins and the runtime update separately. Both carry the package version.

• Plugins come from GitHub. Claude Code does not auto-update a third-party marketplace by default. To turn it on, run /plugin, open Marketplaces, select xtrm, and choose Enable auto-update. For a whole fleet, set "autoUpdate": true on the xtrm entry of extraKnownMarketplaces in managed settings. Without auto-update, run claude plugin marketplace update xtrm, then claude plugin update specialists@xtrm (and specialists-ui@xtrm). Run /reload-plugins or restart to apply.
• The runtime comes from npm, and Claude Code never updates it. Run npm i -g @jaggerxtrm/specialists@latest, then restart Claude Code. When the plugin and the runtime versions differ, the plugin's MCP launcher writes a warning to stderr with the exact install command, and starts anyway.

What the plugins need

| Piece | Needed for | Set up by | |---|---|---| | Specialists runtime (@jaggerxtrm/specialists) | the MCP server; the plugin launcher starts it | npm install -g @jaggerxtrm/specialists (see Install and bootstrap) | | Bun on PATH | the MCP server and every plugin hook script | install Bun | | Substrate work store | specialist_dispatch (the contract) | @jaggerxtrm/substrate installed, or XTRM_SUBSTRATE_DIR (below) | | Claude Code with plugin hooks modules (verified on 2.1.288) | the fleet band, the fleet pane, /specialists, and all specialists-ui rows | a current Claude Code; hooks must not be turned off with disableAllHooks | | specialists@xtrm | MCP tools, session-start state, the fallback wake, the band, pane and command | claude plugin install specialists@xtrm | | specialists-ui@xtrm | teammate-style wake rows and native tool rows | claude plugin install specialists-ui@xtrm | | --channels plugin:specialists@xtrm | the channel wake (primary) | launch flag; xt claude passes it for you | | Managed settings channelsEnabled + allowedChannelPlugins | the channel wake (primary) | root, /etc/claude-code/managed-settings.json (below) |

The plugin hooks API (the band, pane and rows) is early access in Claude Code and can change between releases. If a row or the band stops drawing after a Claude Code update, run claude --debug and search the log for ui.render to see whether a hook was skipped or refused.

Verify the server is reachable from Claude Code:

claude mcp list | grep specialists
# plugin:specialists:specialists: ... - ✔ Connected

Dispatch needs the Substrate work store, which supplies the contract. It is resolved in this order: an explicit XTRM_SUBSTRATE_DIR, then normal module resolution of the installed @jaggerxtrm/substrate package, then the npm global prefix, then failure. No environment variable is required as long as the package is installed in one of those places:

npm install @jaggerxtrm/substrate           # in the project the session runs in
npm install --global @jaggerxtrm/substrate  # or beside a globally installed Specialists

The npm global prefix is searched because a global install from a FOLDER is a symlink: default resolution dereferences it and walks the checkout's ancestors, which never reach <prefix>/lib/node_modules, so a sibling global Substrate would otherwise be invisible. xt init enrolls Substrate into that prefix, which is why the XTRM-managed path needs no extra step.

Set XTRM_SUBSTRATE_DIR only to override that with a local checkout, for example when developing Substrate itself. It wins over the installed package when set.

If neither is available, specialist_dispatch is refused with work_item_store_unavailable while specialist_status and specialist_list keep working — so the plugin looks healthy until you try to dispatch. An override must be in the environment the session is launched with; a shell export afterwards does not reach the already-running MCP server.

export XTRM_SUBSTRATE_DIR=/path/to/xtrm/packages/substrate
claude

The plugin requires Bun on PATH and reads Substrate's canonical store, resolved from SUBSTRATE_DB, else XTRM_STATE_DB, else ~/.xtrm/state.db. SUBSTRATE_DB comes first because the store belongs to Substrate and is shared with sb and Pi. To develop against a checkout instead of an install, load both plugins: claude --plugin-dir ./plugins/specialists --plugin-dir ./plugins/specialists-ui. Loading only ./plugins/specialists gives the runtime without the transcript rows.

Enable the channel wake

When an activation settles, fails, escalates or asks a question, the plugin's MCP server pushes a short notice into the coordinator session (a Claude Code Channel). The notice wakes an idle session; the authoritative read of a result is specialist_result (specialist_status for asks and state). Claude Code drops the push without any error unless all of the following are true, so configure both parts.

1. Launch the session with the plugin's server named as a channel:

   claude --channels plugin:specialists@xtrm
   

2. As root, allow the plugin in Claude Code's managed settings, in /etc/claude-code/managed-settings.json or a file under /etc/claude-code/managed-settings.d/:

   {
     "channelsEnabled": true,
     "allowedChannelPlugins": [{ "plugin": "specialists", "marketplace": "xtrm" }]
   }
   

   Set both keys. ~/.claude/settings.json is not read for either key. Without a managed allowlist, Claude Code uses a default list fetched from Anthropic that does not include this plugin. claude.ai Team and Enterprise plans need channelsEnabled: true in every case. For a login that is not claude.ai (an API key, for example), any managed-settings file without channelsEnabled: true turns channels off, so a file that only holds the allowlist makes delivery worse, not better.

For local development without root, launch with claude --dangerously-load-development-channels plugin:specialists@xtrm instead of --channels. A channel loaded this way skips the allowlist. Use it only for a plugin you build yourself.

The push also needs the legacy (2025-11-25) MCP protocol revision, because the stateless 2026-07-28 revision has no path for a message the server sends unprompted. You do not need to configure this: the plugin's launcher serves the legacy revision only, so Claude Code downgrades this one server and keeps negotiating normally with every other server. Do not set MCP_PROTOCOL_NEGOTIATION=legacy for this; it pins every MCP server to the legacy handshake.

If the channel wake is not available, a fallback still wakes the session: the plugin's wake-watch hook starts with each session, watches the Substrate store, and wakes the session once when an activation settles or asks a question. It stops after that first wake or after about 15 minutes, so it is a safety net, not a replacement for the channel. The deployed companion specialists-ui plugin acknowledges each channel wake (a marker under ~/.xtrm/wake-acks), and this watcher drops any event that marker covers, so a push that arrived is not woken a second time; without that plugin it falls back to today's behaviour. specialist_result is the authoritative read either way.

Check the result with specialists doctor --channels, which reports the first closed gate. Channels work only in an interactive session; claude -p never receives them. Behaviour was read from Claude Code 2.1.288; see docs/claude-channel-constraints.md for the full gate chain.

Global model config

Package specialist definitions ship with execution.model = null. This is intentional: the package defines roles, tools, contracts, and safety boundaries; your machine-level config defines provider/model choices.

Use:

sp init --global
sp edit --global
sp setup --fetch-benchmarks --json
sp setup --plan <budget-preset>
sp doctor --specialists

The loader merges configuration in this order:

1. package canonical specialist JSON;
2. ~/.config/specialists/user.json global overrides;
3. .specialists/user/ repo-local overrides.

See docs/installation.md, docs/bootstrap.md, and docs/authoring.md.

---

First tracked run

bd create "Investigate flaky checkout flow" -t bug -p 1 --json
bd update <id> --claim --json

sp run explorer --bead <id> --context-depth 2
sp feed <job-id> --follow
sp result <job-id>

sp run debugger --bead <id> --context-depth 3
sp run executor --bead <id> --worktree
sp run reviewer --bead <id> --job <executor-job>

bd close <id> --reason "Root cause found, fix reviewed" --json

Ad-hoc one-offs are still supported, but tracked work should use beads:

sp run explorer --prompt "Map the CLI architecture"

---

Operator console

sp console is the multi-repo terminal dashboard for live specialist work.

It provides:

• an ALL view aggregating active jobs across configured repos;
• per-repo tabs and persistent repo registry (~/.config/specialists/console.json);
• job list, feed, result, bead, diff, config, and repo-config views;
• cursor navigation and direct actions (↵, r, i, b, d, g, R, x, 0, tab, 1-9);
• TUI-styled rows shared with sp ps.

sp console
# Press R, then + to add a repository; select one and press d to remove it.

For shell-only workflows:

sp ps
sp feed <job-id>
sp feed -f
sp result <job-id>
sp log <job-id>
sp steer <job-id> "focus only on the API boundary"
sp resume <job-id> "continue with this additional evidence"
sp stop <job-id>
sp clean --reap-orphans --dry-run

---

Publication and review

Specialists separates doing work from publishing work.

• executor, debugger, test-engineer, and sync-docs may create changes.
• seconder, test-runner, and reviewer produce evidence/verdicts.
• Reviewer PASS is the normal publish gate for implementation work.
• sp merge and sp epic merge exist but are currently marked broken. Do not use them.

Follow the merge and integration procedure for reviewed publication work. sp epic status <epic-id> remains available for inspection.

Keep-alive specialists may stop in waiting after producing a result. Use sp result <job-id> to read the handoff, then sp stop <job-id> when no follow-up is needed.

---

Script and service specialists

Use sp run for interactive agent orchestration. Use sp script / sp serve when you need an immediate one-shot generation contract from a specialist.

sp script <name> --vars key=value --json
sp serve --port 8000 --readiness-canary warn
curl -sS http://localhost:8000/v1/generate \
  -H 'content-type: application/json' \
  -d '{"specialist":"hello","variables":{"name":"world"}}'

sp script flags:

sp script <name> [--vars k=v ...] [--template <text> | --template-field <name>] \
  [--model <override>] [--thinking <level>] [--json] \
  [--allow-local-scripts] [--allow-write-capable] [--single-instance <lockpath>]

sp serve flags (HTTP sidecar for the same runtime path):

sp serve [--port <n>] [--concurrency <n>] [--project-dir <path>] \
  [--allow-skills] [--allow-skills-roots <p1>:<p2>]

Script/service mode is useful for CI, internal services, deterministic JSON generation, and sidecar deployments. Only sp script supports trusted local scripts or write-capable execution through --allow-local-scripts and --allow-write-capable. sp serve supports neither — it remains READ_ONLY. Skills remain disabled unless --allow-skills is set; --allow-skills-roots restricts accepted canonical skill sources when supplied, but it is not a filesystem read boundary. Specialists 3.21.6 does not provide host-read isolation: allowed tools, extensions, MCP processes, and child processes can read paths visible to the runtime identity. Its bounded waiver permits only trusted single-tenant callers with private authenticated ingress, a dedicated container or OS account, minimal mounts, least-privilege credentials, trusted definitions, and reviewed extension sources. Untrusted, public, cross-tenant, and multi-tenant deployments are excluded. The waiver does not authorize publication and expires at 3.21.7.

See docs/specialists-service.md and docs/specialists-service-install.md.

---

Observability and telemetry

Specialists is DB-first. Runtime state lives in .specialists/db/observability.db; file mirrors under .specialists/jobs/ are legacy/operator recovery surfaces.

Useful surfaces:

sp ps                         # dashboard row view
sp feed <job-id>              # event stream replay
sp log <job-id>               # control/status/error log
sp forensic <job-id> --json   # persisted forensic envelopes
sp metrics --prometheus       # low-cardinality metrics
sp serve --port 8000          # exposes /metrics and job feed endpoints

Telemetry uses bounded labels and avoids high-cardinality IDs in Prometheus labels. Forensic events retain drill-down detail in SQLite/JSON output where IDs are appropriate.

Project-pack Service Knowledge

service-knowledge-sync declares the logical service-knowledge skill. On Pi and Claude role launches, the runtime resolves that name from the consumer repository rather than requiring a stale global install:

.xtrm/skills/<pack>/service-knowledge/
├── SKILL.md
├── service-registry.json
└── services/

Resolution is deterministic and fail-closed. Core first honors an enabled runtime-specific repository view. Otherwise:

• one matching project pack wins;
• multiple matching packs fail as ambiguous;
• a discovered malformed, unreadable, symlinked, or escaping candidate fails instead of falling back;
• zero project-pack matches permit the existing home/global fallback chain;
• direct/script paths are canonicalized against canonical allowed roots before Pi starts.

The pack directory contains repository-specific knowledge. Shared executable machinery remains separate at .xtrm/skills/default/service-knowledge/scripts/; the runtime does not copy scripts into each pack umbrella. Pre-scripts run from the consumer repository, clear registry-selection environment overrides, label repository output as untrusted data, redact host paths, and enforce bounded raw and rendered output.

Core forwards the resolved absolute pack path to Pi. For Claude, Core creates a bounded worktree-local .claude/skills/<name> link and verifies link, prefix, shadow, and canonical identity before launch. Codex rejects project-pack skill paths because Core does not materialize Codex-native pack skills.

Direct surfaces remain narrower: sp script confines skill paths to its project root, service-knowledge-sync itself is rejected there because it requires a worktree, and sp serve does not permit local pre-scripts.

The extension source for this skill is pinned to an exact reviewed npm spec (e.g. npm:@jaggerxtrm/[email protected]); floating or range specs are rejected.

Release state: This coordinated behavior was validated at merged Core ef14bf44030ee6cd02d4dd21f0856f067baf54f3, Specialists f683f5f6172bdb7ab4a7b7324b7feabd9b918b31, and service-knowledge-sync 1.10.0. These are coordinated-head evidence references, not a published 3.21.6 compatibility guarantee.

---

Mandatory rules

Every package-class specialist receives mandatory rules at spawn time (bare mode skips injection). These enforce behaviors regardless of the task.

sp list-rules
sp list-rules --rule <rule-id>
sp list-rules --rule <rule-id> --show    # print that rule's text, verbatim
sp list-rules --specialist <name>
sp list-rules --json

The loader unions indexes from .specialists/user/mandatory-rules/, config/mandatory-rules/, .specialists/default/mandatory-rules/, and .specialists/mandatory-rules/; if none exists, it uses the package-canonical index. Rule bodies use first-existing precedence in the same order.

Per-specialist additions can be declared in the specialist JSON via mandatory_rules.template_sets and mandatory_rules.inline_rules.

Global mandatory_rules.template_sets selection

You can override which specialist-specific rule sets apply via mandatory_rules.template_sets in ~/.config/specialists/user.json (global) or .specialists/user/<name>.specialist.json (repo-local):

{
  "executor": {
    "mandatory_rules": {
      "template_sets": ["my-global-rules"]
    }
  }
}

• null — inherits package defaults
• [] — clears only your specialist-specific sets (required/default index sets always load)
• non-empty array — replaces your specialist-specific sets entirely

Blocked fields mandatory_rules.inline_rules and mandatory_rules.disable_default_globals cannot be set at global/repo layers; they are package-canonical only. Other blocked fields include capabilities, execution.auto_commit, prompt.output_schema, and skills.scripts. See docs/overrides-guide.md and config/mandatory-rules/README.md.

Template-set ids are validated as kebab-case and path-contained before overlay.

---

Extension sources

Specialists spawns Pi with --no-extensions, then selectively re-enables extensions via repeated -e <source> pairs derived from execution.extensions.

| Key | Value | Behavior | |-----|-------|----------| | gitnexus | false | Skips GitNexus MCP injection | | serena | any | Deprecated and ignored (Serena retired) | | any other key | true | Trusted source string forwarded to Pi as -e <source> in insertion order | | any key | false or null | Skips that source |

Remote sources (npm:, git:, http:, https:) cause the run to omit --offline; local paths retain it. The per-run offline decision is global: if any enabled source is remote, --offline is omitted for the entire Pi invocation. Fail-closed duplicate detection rejects two distinct npm: keys for the same package (e.g. a pinned canonical npm:@scope/[email protected] plus a floating npm:@scope/pkg) before Pi spawns; fix the overlay by aligning to the exact pinned spec. Configured sources are not equivalent to active tools — only runtime-confirmed allowed tools are advertised.

See docs/pi-session.md and docs/overrides-guide.md.

---

Active-tool policy and tool catalog

Specialists operates a fail-closed active-tool policy:

• Configured sources are not active tools. Only runtime-confirmed allowed tools are advertised to the specialist.
• Denied built-ins remain denied regardless of configuration.
• The extension tool-policy gate validates at session_start and hard-fails the launch if the bundled policy extension is missing while extension sources are enabled.

Tool catalog resolution is also fail-closed. A missing, unreadable, malformed, or empty catalog aborts tracked, script, serve, MCP, and pipeline execution before Pi starts. Specialists never omits --tools for a requested tier. Reinstall or rebuild the package if config/catalog/index.json is unavailable.

---

First-class tools: Python and ast-grep

Specialists treats Python and ast-grep as first-class tools alongside shell, Git, and GitNexus.

| Tool | When to use | |------|-------------| | Python | Multi-step processing, parsing, aggregation, or structured transforms where a small script replaces many shell round-trips. The Pi python tool persists state across calls (variables, imports, functions survive). | | ast-grep | Syntax-aware structural search when grep would false-positive on strings. Use pattern / kind queries for code-shape matching. |

# ast-grep: find call patterns without string noise
ast_grep run --pattern 'console.log($A)' --language ts

Guidance in prompts is advisory. Actual availability depends on Pi agent toolset declaration, extension loading status, and platform support.

---

Supported models and presets

Package presets ship with the following mappings (see config/presets.json):

| Preset | Model | Thinking | Stall timeout | |--------|-------|----------|---------------| | cheap | nano-gpt/moonshotai/kimi-k2.5 | off | 60s | | medium | anthropic/claude-sonnet-4-6 | low | 120s | | power | openai-codex/gpt-5.4 | high | 300s |

Set via sp edit --global:

sp edit --global --set executor.execution.model @preset/medium
sp edit --global --set "executor.execution.fallback_models" '["@preset/cheap"]'
sp edit --list-presets

Package specs ship execution.model = null intentionally; your machine config provides the real model. thinking_level: off on Kimi-class models can produce empty assistant text (model quirk). Resolution depth cap is 5 levels; cycles surface a structured error at dispatch.

---

Built-in specialist families

| Family | Examples | Purpose | |---|---|---| | Exploration/debugging | explorer, debugger, overthinker | map systems, find root causes, reason deeply | | Implementation/review | executor, reviewer, seconder | write changes, verify scope, check quality | | QA | test-engineer, test-runner, obligations-scanner | create tests, run exact commands, track TODO/FIXME obligations | | Research | researcher, transcriber | gather current docs, papers, and video transcripts | | Documentation/release | sync-docs, service-knowledge-sync, changelog-keeper, changelog-drafter | keep docs and release notes current | | Operations | xt-merge, memory-processor, node-coordinator | merge queues, curate memory, coordinate node workers | | Domain specialists | quant-researcher, quant-methodologist | market-data and quantitative-method evidence/methodology |

Run sp list --compact for the exact installed catalog and versions.

---

Documentation map

| Need | Doc | |---|---| | Install, update, global config | docs/installation.md | | Bootstrap a project | docs/bootstrap.md | | Bead-first workflow | docs/workflow.md | | CLI commands and flags | docs/cli-reference.md | | Feature-level behavior | docs/features.md | | Background jobs / feed / result | docs/background-jobs.md | | Specialist JSON authoring | docs/authoring.md | | Built-in specialist catalog | docs/specialists-catalog.md | | Mandatory rules authoring | config/mandatory-rules/README.md | | Overrides guide (global config) | docs/overrides-guide.md | | Pi subprocess isolation | docs/pi-session.md, docs/pi-rpc-boundary.md | | MCP server/tool surface | docs/mcp-servers.md, docs/mcp-tools.md | | Script/service sidecar | docs/specialists-service.md, docs/specialists-service-install.md | | Worktrees and publication | docs/worktrees.md, docs/worktree.md | | Architecture | docs/ARCHITECTURE.md | | Release notes | CHANGELOG.md |

---

Project layout

config/
├── specialists/       package-canonical specialist definitions
├── mandatory-rules/   package-canonical rule sets injected into prompts
├── catalog/           tool catalog and permission metadata
├── nodes/             node coordinator configs
├── hooks/             bundled hook scripts
└── skills/            package-shipped skills

.specialists/
├── user/              repo-local specialists and overrides
├── default/           optional pins / compatibility snapshots; prune stale files
├── mandatory-rules/   repo-local mandatory rule set additions/overrides
├── db/                runtime SQLite state (gitignored)
├── jobs/              legacy runtime mirror (gitignored)
└── ready/             legacy ready markers (gitignored)

.xtrm/
├── skills/            xtrm-managed skill snapshots and active links
└── hooks/             xtrm-managed hook snapshots

src/                   CLI, server, loader, runner, supervisor, MCP tool

---

Core rules

• Use --bead for tracked work; use --prompt only for quick untracked work.
• Put scope, success criteria, constraints, validation, and output expectations in the bead before dispatch.
• Use --context-depth to inject completed dependency context; default is 3 for bead runs.
• Use --job <prior-job> when a follow-up role must reuse the same worktree.
• Prefer sp console, sp ps, sp feed, sp log, and sp result for operations; inspect raw files only for recovery.
• Keep package defaults canonical. Put machine preferences in ~/.config/specialists/user.json and repo exceptions in .specialists/user/.
• Run sp doctor --specialists and xt update --apply when runtime or xtrm-managed assets drift.
• When dispatch is refused with workspace_lease_uncertain, run sp lease list, then sp lease reconcile <worktree> --outcome <safe_free|superseded|manual_attention_required> --basis <evidence>. The operator states the outcome; it is never inferred. MCP: specialist_lease_reconcile.

---

Troubleshooting

sp view <name> --section execution    # inspect resolved execution config
sp view <name> --section mandatory_rules
sp doctor --specialists               # global user.json validation

sp list-rules --json | jq -r '.sets[].id' | sort -u
sp validate ./config/specialists/<name>.specialist.json --target=script

Common issues:

• No model configured: Run sp init --global and sp edit --global
• Extension not loading: Check sp view <name> --section execution for extensions keys; remote sources disable --offline
• Mandatory rules not applying: Verify set id is kebab-case; check sp list-rules --rule <id>
• Fork bomb / too many jobs: Use sp clean --reap-orphans or sp stop <job-id>
• Stalled waiting jobs: Default no auto-close; opt-in via stall_detection.waiting_auto_close_ms

---

Deprecated / compatibility surfaces

These commands or paths may still exist for migration, but they are not the preferred onboarding path:

• specialists setup
• specialists install
• sp init --sync-defaults for routine setup
• .specialists/default/ as an always-synced mirror
• sp release prepare / sp release publish aliases (release flow is skill-driven)
• execution.extensions.serena (retired; ignored if present)

Use sp init, sp init --global, sp setup, xt update, and the release skill flow instead.

---

Development

bun run build
bun run test       # runs Vitest through Bun (the supported test runner)
sp help
sp quickstart

License

MIT — see LICENSE.