@jaggerxtrm/specialists 3.17.0 → 3.18.0

package/docs/hooks.md

@@ -0,0 +1,81 @@
+---
+title: Hooks Reference
+scope: hooks
+category: reference
+version: 1.2.0
+updated: 2026-03-23
+description: Bundled Specialists hooks and their runtime behavior.
+source_of_truth_for:
+  - "hooks/specialists-complete.mjs"
+  - "hooks/specialists-session-start.mjs"
+domain:
+  - hooks
+---
+
+<!-- INDEX: auto-generated by validate_doc.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+| [Hook inventory](#hook-inventory) | | Hook | Event | Purpose | |
+| [`specialists-complete.mjs`](#specialists-completemjs) | Behavior: |
+| [`specialists-session-start.mjs`](#specialists-session-startmjs) | Behavior: |
+| [Installation notes](#installation-notes) | The current canonical bootstrap is `specialists init` |
+| [Beads hooks](#beads-hooks) | Beads workflow enforcement hooks are owned outside this package |
+| [See also](#see-also) | - [workflow |
+<!-- END INDEX -->
+
+# Hooks Reference
+
+This package bundles hook scripts used by Specialists-aware environments.
+
+Specialists works alongside **[xtrm-tools](https://github.com/Jaggerxtrm/xtrm-tools)**. Specialists owns only its specialist-specific hooks; xtrm-tools owns the broader beads/workflow enforcement hook layer.
+
+## Hook inventory
+
+| Hook | Event | Purpose |
+|---|---|---|
+| `specialists-complete.mjs` | `UserPromptSubmit` | inject background completion banners |
+| `specialists-session-start.mjs` | `SessionStart` | inject active jobs, available specialists, and workflow reminders |
+
+## `specialists-complete.mjs`
+
+Behavior:
+
+- scans `.specialists/ready/` for completion markers
+- reads job metadata from `status.json`
+- injects a completion banner for finished jobs
+- removes the marker after injection
+
+## `specialists-session-start.mjs`
+
+Behavior:
+
+- lists active background jobs
+- lists available project specialists
+- injects a concise bead-first workflow reminder:
+  - `--bead` for tracked work
+  - `--prompt` for ad-hoc work
+  - `--context-depth` default
+  - `--no-beads` semantics
+
+## Installation notes
+
+Hook distribution is Category B: hook files and `.claude/settings.json` wiring must exist on disk, so xtrm-tools owns the managed mirror under `.xtrm/hooks/default/` and refreshes it with `xt update`.
+
+Use:
+
+```bash
+xt doctor --cwd <repo> --json
+xt update --repo <repo> --apply
+```
+
+`specialists init` still manages specialists-specific runtime dirs, MCP registration, and specialists hook wiring. Use `specialists doctor` for runtime health; use `xt doctor` / `xt update` for xtrm-managed hook drift.
+
+## Beads hooks
+
+Beads workflow enforcement hooks are owned outside this package. Specialists focuses on specialist execution and workflow guidance.
+
+## See also
+
+- [workflow.md](workflow.md)
+- [background-jobs.md](background-jobs.md)
+- [bootstrap.md](bootstrap.md)

package/docs/installation.md

@@ -0,0 +1,142 @@
+---
+title: Installation and Distribution
+scope: installation
+category: guide
+version: 1.0.2
+updated: 2026-06-24
+synced_at: 833bc435
+description: Canonical-from-package install model, global user config, user overlays, and managed xtrm assets.
+source_of_truth_for:
+  - package.json
+  - src/specialist/canonical-asset-resolver.ts
+  - src/cli/init.ts
+  - docs/skills.md
+  - docs/hooks.md
+domain:
+  - installation
+  - distribution
+---
+
+# Installation and Distribution
+
+## Runtime requirement: Bun
+
+Specialists is Bun-only. Require Bun >= 1.0.0 before installing or running the package.
+
+Verify:
+
+```bash
+bun --version
+```
+
+Install Bun if missing:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+
+Specialists now uses a two-category distribution model. Install or upgrade the npm package to choose the canonical Specialist runtime version; do not copy default files into every repository as the normal path.
+
+## Prerequisites and install order
+
+Specialists uses xtrm-tools as a runtime prerequisite, not a normal npm dependency. Keep it installed separately so `specialists init` can verify `xt` and manage `.xtrm/`.
+
+Ordered install flow:
+
+1. Install Bun.
+2. Install xtrm-tools globally: `npm install -g xtrm-tools`
+3. Run `xt install`
+4. Run `xt init` in this repo
+5. Install Specialists: `npm install -g @jaggerxtrm/specialists`
+6. Run `sp init --global` if you want machine-level user config
+7. Run `sp init`
+
+Category A and bootstrap note:
+- `sp list`, `sp doctor --check-drift`, and `sp prune-stale-defaults` are Category A commands.
+- They do not require `xt` or `.xtrm/`.
+
+### Naming and prerequisite policy
+
+- Specialists ships as the scoped package `@jaggerxtrm/specialists`. Binaries: `specialists` and `sp` (alias).
+- xtrm-tools is a separate published package; the canonical name is `xtrm-tools` and its CLI is `xt`.
+- Specialists does NOT declare xtrm-tools as a normal dependency, devDependency, or peerDependency. It is recorded as a runtime prerequisite in the underscore-prefixed `_runtime_prerequisites` field in `package.json` (npm ignores underscore-prefixed top-level fields), and enforced at runtime by `sp init` via `assertXtrmPrerequisites` in `src/cli/init.ts`.
+- `sp init --global` sets up machine-level user config. Use it once per operator account when you want shared personal defaults; plain `sp init` stays repo-local.
+- Rationale: a normal/peer dependency on xtrm-tools would couple specialists publishes to xtrm-tools version cuts and risk transitive-bin ambiguity. Operators install both packages globally; `xt --version` is the source of truth for xtrm CLI presence.
+- Migration: legacy installs that depended on `xtrm-tools` transitively should switch to explicit global install per the ordered flow above.
+
+GitHub CI now includes a package-payload smoke gate that packs the tarball, asserts required runtime assets are present, installs into an isolated prefix, and runs `sp --version`, `sp doctor --check-drift`, `sp prune-stale-defaults --dry-run`, `sp clean --dry-run`, and `sp list --compact` to catch payload regressions before publish.
+
+## Category A: runtime-resolved package assets
+
+Category A assets are read by the `sp` runtime itself:
+
+- specialist definitions from `config/specialists/`
+- mandatory rules from `config/mandatory-rules/`
+- tool catalog files from `config/catalog/` / `.specialists/catalog/` override
+- node configs
+
+The loader resolves them live from the installed package when a repo has no intentional override. Precedence is:
+
+```text
+.specialists/user/ > .specialists/default/ > config/<kind>/ > package canonical > legacy
+```
+
+For new repositories this means no default snapshot is required. Pin the canonical runtime version with `package.json` / lockfile by depending on the desired `@jaggerxtrm/specialists` version; global installs only choose which package version is active on the machine. Put custom project definitions in `.specialists/user/`; they intentionally outrank package canonical assets.
+
+`sp init --sync-defaults` is deprecated. It still works as a compatibility alias, but it prints a loud warning because it creates drift debt.
+
+`.specialists/default/` stays empty by default. Populate it only when you intentionally pin a specialist, mandatory rule, or node config for repo-local override.
+
+Use `sp pin <id>` for intentional pins when available; otherwise copy the specific asset into `.specialists/default/` only for an operator-approved override.
+
+## Category B: filesystem-bound xtrm-managed assets
+
+Category B assets must exist on disk because external tools read them directly:
+
+- skills under `.xtrm/skills/default/` and the active `.claude/skills` / `.pi/skills` surfaces
+- hooks under `.xtrm/hooks/default/` and `.claude/settings.json` hook wiring
+
+xtrm-tools owns these snapshots. Check drift with:
+
+```bash
+xt doctor --cwd <repo-or-root> --json
+```
+
+Refresh one repo or many with:
+
+```bash
+xt update --repo <repo> --apply
+xt update --root <projects-root> --apply
+```
+
+Omit `--apply` for a dry run. See [skills.md](skills.md), [hooks.md](hooks.md), and the `update-specialists` skill for the operator-facing flow.
+
+## Pin a specialist version
+
+If you need to keep one specialist pinned in a repo, copy it into the user layer before pruning defaults:
+
+```bash
+cp .specialists/default/<name>.specialist.json .specialists/user/
+sp prune-stale-defaults
+```
+
+User overlays stay untouched by prune.
+
+## Migrating existing repositories
+
+1. Upgrade the `@jaggerxtrm/specialists` package version you want to run.
+2. Run `sp doctor --check-drift` to find stale Category A snapshots in `.specialists/default/`.
+3. Run `sp prune-stale-defaults` to remove stale default mirrors. Add `--keep-diverged` if you want to preserve intentional pins.
+4. Run `xt doctor --cwd <repo> --json` for Category B drift.
+5. Run `xt update --repo <repo> --apply` or `xt update --root <projects-root> --apply` after operator confirmation.
+
+Do not move user-authored specialists, skills, or hooks into default mirrors. User-owned layers are custom policy, not drift.
+
+## See also
+
+- [authoring.md](authoring.md)
+- [manifest.md](manifest.md)
+- [skills.md](skills.md) — xtrm-managed skill install and update flow
+- [hooks.md](hooks.md)
+- [cli-reference.md](cli-reference.md)

package/docs/manifest.md

@@ -0,0 +1,184 @@
+---
+title: Tool Manifest and Permissions
+scope: manifest
+category: reference
+version: 1.0.1
+updated: 2026-05-15
+synced_at: b92a11ba
+description: Manifest-driven tool catalog, permission tiers, and per-specialist permissions[TIER] override blocks.
+source_of_truth_for:
+  - "config/catalog/*.json"
+  - ".specialists/catalog/*.json"
+  - "src/specialist/manifest-resolver.ts"
+  - "src/specialist/resolution-diagnostics.ts"
+  - "src/pi/session.ts:resolvePermissionTools"
+domain:
+  - manifest
+  - permissions
+  - tools
+---
+
+# Tool Manifest and Permissions
+
+This document is the user-facing reference for the tool resolver: how each specialist's effective `--tools` list is computed, how to declare a per-specialist override, and how the deny modes interact with extension health.
+
+> History: this system replaces the legacy hardcoded tier→tool arrays in `src/pi/session.ts` (removed in unitAI-qujxo.2). Design lives in `docs/design/gzrx-tool-catalog.md`. Critique of the parity-window cleanup in `docs/design/gzrx-completion-critique.md`.
+
+## What runs at session start
+
+When a specialist is dispatched, `PiAgentSession.start()` produces a comma-joined `--tools` argument for the underlying `pi` subprocess by calling `resolvePermissionTools` with three inputs:
+
+1. The specialist's coarse tier from `execution.permission_required` (`READ_ONLY` | `LOW` | `MEDIUM` | `HIGH`).
+2. The specialist's optional `permissions[<TIER>]` override block.
+3. The catalog index resolved from `.specialists/catalog/index.json` when a local override exists, otherwise package-canonical `config/catalog/index.json`, plus the live health probe of the `pi-gitnexus` and `pi-serena-tools` npm extensions.
+
+The resolver is the only path. There is no env-flag fallback. There are no hardcoded tool arrays in source.
+
+
+Catalog files are Category A assets in the distribution model: the runtime resolves them from the installed package when the repo has no intentional local catalog override. New repos do not need a copied `.specialists/catalog/` snapshot just to get current policy. Pin policy by pinning the specialists package version; override locally only when the project deliberately diverges. See [installation.md](installation.md).
+
+## Catalog architecture
+
+The resolved catalog `index.json` declares the precedence order and inlines per-catalog tier policies. Package installs read `config/catalog/index.json`; `.specialists/catalog/index.json` is an intentional local override when present:
+
+```json
+{
+  "precedence_order": ["native", "gitnexus", "serena"],
+  "catalogs": [
+    {
+      "catalog": "native",
+      "package": "specialists",
+      "version": "3.11.0",
+      "precedence": 0,
+      "source_tiers": {
+        "READ_ONLY": ["read", "grep", "find", "ls"],
+        "LOW":       ["read", "grep", "find", "ls", "bash"],
+        "MEDIUM":    ["read", "grep", "find", "ls", "bash", "edit"],
+        "HIGH":      ["read", "grep", "find", "ls", "bash", "edit", "write"]
+      }
+    },
+    { "catalog": "gitnexus", "package": "pi-gitnexus", "...": "..." },
+    { "catalog": "serena",   "package": "pi-serena-tools", "...": "..." }
+  ]
+}
+```
+
+Three catalog files (`native.json`, `gitnexus.json`, `serena.json`) sit alongside the index and contain richer per-tool metadata. The index is the canonical input the resolver reads at session start.
+
+The flat tool list emitted to `pi --tools` is the union of each catalog's `source_tiers[<TIER>]` for the active tier, gated by extension health (see below).
+
+## The four tiers
+
+| Tier | Native | GitNexus | Serena |
+|------|--------|----------|--------|
+| `READ_ONLY` | read, grep, find, ls | read tools (query/context/impact/detect_changes/list_repos) | read tools (find_symbol, search_for_pattern, list_dir, find_file, …) |
+| `LOW` | + bash | (same as READ_ONLY) | + execute_shell_command |
+| `MEDIUM` | + edit | + rename, cypher | + write tools (replace_symbol_body, create_text_file, …) |
+| `HIGH` | + write | (same as MEDIUM) | (same as MEDIUM) |
+
+Inspect the actual resolved set for any specialist with `sp config show <name> --resolved` (see `docs/cli-reference.md`).
+
+## Extension health gating
+
+Three states per extension affect resolution:
+
+| Probe state | Effect on resolved tools |
+|-------------|--------------------------|
+| `loaded_healthy` | Catalog tools included normally; hard-deny of natives is allowed. |
+| `loaded_unhealthy` / `not_installed` / `disabled` / `unknown` | Catalog's tools are dropped from the resolved set; if a hard-deny is configured against natives, those natives are *restored* automatically and a downgrade reason is recorded. |
+
+Restoration is the safety net: an explorer that hard-denies `grep`/`find`/`ls` will get them back as a fallback if `pi-serena-tools` becomes unhealthy mid-run. You see this in `sp config show --resolved` as `restored native fallback: ...` in `downgrade reasons`.
+
+Probes inspect `pi-gitnexus` and `pi-serena-tools` in the global npm modules directory.
+
+## Per-specialist override block
+
+Most specialists need nothing special — catalog `default_overrides` define runtime-native deny defaults, and tier-local `permissions[<TIER>]` blocks only appear when a specialist must diverge from that baseline. Put specialist overrides at top level of specialist JSON (sibling to `execution`, not nested inside it).
+
+### Schema
+
+```jsonc
+{
+  "specialist": {
+    "execution": { "permission_required": "READ_ONLY", "...": "..." },
+    "permissions": {
+      "READ_ONLY": {
+        "denied_natives_when_extension": ["grep", "find", "ls"],
+        "denied_natives_mode": "hard"
+      }
+    }
+  }
+}
+```
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `denied_natives_when_extension` | `string[]` | `[]` | Native tools to deny **only when a replacement extension is healthy**. Order doesn't matter. Catalog defaults apply first, specialist overrides replace them when present. |
+| `denied_natives_mode` | `"soft"` \| `"hard"` | `"soft"` | Whether the denial actually removes the tool (`hard`) or only emits a preference signal (`soft`). |
+
+Only the tier matching the specialist's `execution.permission_required` is consulted. Unused tiers in the block are silently ignored.
+
+### Soft vs hard deny
+
+| Mode | Effect on `--tools` | When to use |
+|------|---------------------|-------------|
+| `soft` | Final tool list is **unchanged**; resolver emits a `preference signals` line in the resolved report. The model still receives the native tool, with a hint to prefer the extension. | Gentle nudges; rollouts you want to observe before tightening; cases where the replacement might not always cover the native's edge cases. |
+| `hard` | Native tool is removed from `--tools` entirely (when the replacement extension is healthy). Falls back to native automatically if the replacement degrades. | Strong opinions where the native tool is genuinely worse and the replacement is reliable. |
+
+Soft is the default — bias toward observability before enforcement.
+
+### Canonical example: explorer
+
+`config/specialists/explorer.specialist.json` is currently the only specialist with an override block:
+
+```json
+{
+  "specialist": {
+    "execution": { "permission_required": "READ_ONLY" },
+    "permissions": {
+      "READ_ONLY": {
+        "denied_natives_when_extension": ["grep", "find", "ls"],
+        "denied_natives_mode": "hard"
+      }
+    }
+  }
+}
+```
+
+Why: explorer is meant to discover code through the symbol/process graph — `gitnexus_query` and serena's `search_for_pattern` / `find_symbol` / `find_file` give richer, ranked, structured results than native `grep`/`find`/`ls`. Hard-denying the natives forces explorer to use the better tools when they're available, while the health-gated restore guarantees it still works if the extensions go offline.
+
+`read` stays soft (not in the deny list) because no extension currently provides large-file or non-code reading equivalents.
+
+## When NOT to declare an override
+
+- **Tier defaults are correct.** Most specialists are in this bucket.
+- You're tempted to copy explorer's block into another specialist "just in case." Don't — drift is a real cost, and the file then has to track catalog changes by hand.
+- You want to *add* tools beyond the tier default. The override block can only deny natives, not extend the catalog. Adjust the catalog file or change the specialist's tier instead.
+
+## Inspecting the resolution
+
+```bash
+sp config show <name> --resolved
+```
+
+The output shows, in order:
+
+- The full resolved JSON for the specialist
+- `layer attribution`: which layer (catalog / specialist_override / runtime_health) contributed which tools
+- `extension availability`: live health probe per extension
+- `catalog compatibility`: schema-version check
+- `denied natives`: tools removed by override
+- `deny mode`: `soft` or `hard`
+- `preference signals`: present when soft-deny is configured
+- `downgrade reasons`: present when hard-deny had to restore natives due to unhealthy extensions
+- `--tools`: the literal comma-joined string passed to `pi`
+
+Use this command after editing a specialist's tier or override block to confirm the resolved output is what you expect — *before* dispatching a real run.
+
+## See also
+
+- [authoring.md](authoring.md) — full specialist JSON schema
+- [cli-reference.md](cli-reference.md#specialists-config) — `sp config show --resolved` flag reference
+- [specialists-catalog.md](specialists-catalog.md) — current specialist roster and their tier assignments
+- [design/gzrx-tool-catalog.md](design/gzrx-tool-catalog.md) — original design document
+- [design/gzrx-completion-critique.md](design/gzrx-completion-critique.md) — gap analysis that drove the qujxo.2 cleanup

package/docs/mcp-servers.md

@@ -0,0 +1,73 @@
+---
+title: MCP Servers Configuration
+scope: mcp-servers
+category: reference
+version: 1.3.1
+updated: 2026-05-15
+synced_at: bf6baf7a
+description: Project-scoped MCP registration for Specialists.
+source_of_truth_for:
+  - ".mcp.json"
+  - "src/cli/init.ts"
+domain:
+  - mcp
+---
+
+<!-- INDEX: auto-generated by validate_doc.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+| [MCP tools](#mcp-tools) | | Tool | Description | |
+| [Registration](#registration) | The MCP server is registered at **project scope** by `specialists init` |
+| [Verification](#verification) | You should see Specialists registered at **Project config** scope |
+| [See also](#see-also) | - [bootstrap |
+<!-- END INDEX -->
+
+# MCP Servers Configuration
+
+Specialists exposes an MCP server for Claude Code integration.
+
+## MCP tools
+
+The server exposes a single tool. For full tool contract, see [mcp-tools.md](mcp-tools.md).
+
+| Tool | Description |
+|---|---|
+| `use_specialist` | run a specialist synchronously |
+
+Orchestration, monitoring, steering, resume, and cancellation are CLI-only. See [cli-reference.md](cli-reference.md).
+
+## Registration
+
+The MCP server is registered at **project scope** by `specialists init`.
+
+Init writes `.mcp.json` directly (no `claude mcp add` shell-out).
+
+Typical entry:
+
+```json
+{
+  "mcpServers": {
+    "specialists": {
+      "type": "stdio",
+      "command": "specialists",
+      "args": [],
+      "env": {}
+    }
+  }
+}
+```
+
+## Verification
+
+```bash
+# `sp init` is human-only and writes project `.mcp.json` during bootstrap.
+claude mcp get specialists
+sp doctor
+```
+
+You should see Specialists registered at **Project config** scope.
+
+## See also
+
+- [bootstrap.md](bootstrap.md)
+- [workflow.md](workflow.md)

package/docs/mcp-tools.md

@@ -0,0 +1,71 @@
+---
+title: MCP Tools Reference
+scope: mcp-tools
+category: reference
+version: 2.1.1
+updated: 2026-05-15
+synced_at: bf6baf7a
+description: MCP tool contract for the Specialists server.
+source_of_truth_for:
+  - "src/server.ts"
+  - "src/tools/specialist/use_specialist.tool.ts"
+domain:
+  - mcp
+  - tools
+---
+
+# MCP Tools Reference
+
+This server now exposes a single MCP tool.
+
+## Active tool inventory
+
+| Tool | Purpose |
+|---|---|
+| `use_specialist` | synchronous specialist run with result returned directly in MCP response |
+
+## `use_specialist`
+
+### Input schema
+
+```ts
+z.object({
+  name: z.string().describe('Specialist identifier (e.g. explorer, debugger, reviewer)'),
+  prompt: z.string().optional().describe('The task or question for the specialist'),
+  bead_id: z.string().optional().describe('Use an existing bead as the specialist prompt'),
+  variables: z.record(z.string()).optional().describe('Additional $variable substitutions'),
+  backend_override: z.string().optional().describe('Force a specific backend/model provider when supported by the runtime'),
+  autonomy_level: z.enum(['READ_ONLY', 'LOW', 'MEDIUM', 'HIGH']).optional().describe('Override permission level for this invocation'),
+  context_depth: z.number().min(0).max(10).optional().describe('Depth of blocker context injection (0 = none, 1 = immediate blockers, etc.)'),
+}).refine((input) => Boolean(input.prompt?.trim() || input.bead_id), {
+  message: 'Either prompt or bead_id is required',
+  path: ['prompt'],
+})
+```
+
+### Behavior highlights
+
+- `bead_id` links execution to an existing bead and uses it as task context.
+- The tool runs in foreground and returns final output directly in the MCP result.
+- For orchestration, monitoring, steering, resume, and cancellation, use the CLI (`specialists run/feed/result/steer/resume/stop`).
+
+## Removed MCP tools
+
+The following tools were intentionally removed from MCP surface and are CLI-only workflows now:
+
+- `start_specialist` *(legacy compatibility implementations may still emit a deprecation warning; migrate to `specialists run <name> --prompt "..." --background` now — full removal in next major)*
+- `feed_specialist`
+- `stop_specialist`
+- `steer_specialist`
+- `resume_specialist`
+- `specialist_status`
+- `run_parallel`
+- `follow_up_specialist`
+- `specialist_init`
+- `list_specialists`
+
+## See also
+
+- [cli-reference.md](cli-reference.md)
+- [workflow.md](workflow.md)
+- [background-jobs.md](background-jobs.md)