@jaggerxtrm/specialists 3.2.0 → 3.3.0

package/README.md

@@ -1,304 +1,133 @@
 # Specialists
 
-**One MCP Server. Many Specialists. Real AI Agents.**
+**One MCP server. Many specialists. Bead-first orchestration.**
 
 [![npm version](https://img.shields.io/npm/v/@jaggerxtrm/specialists.svg)](https://www.npmjs.com/package/@jaggerxtrm/specialists)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
 
-**Specialists** is a **Model Context Protocol (MCP) server** that lets Claude discover and delegate to specialist agents — each a full autonomous coding agent powered by [pi](https://github.com/mariozechner/pi), scoped to a specific task.
+**Specialists is a universal framework for defining and running specialist agents.** You can invoke the same specialist from the terminal, through MCP inside coding agents, inside autonomous multi-agent runtimes, or from scripts and CI/CD pipelines. Each run can explicitly define the model, tool access, system prompt, task input, permission level, timeout, output format, tracking behavior, memory sources, and dependency context.
 
-**Designed for agents, not users.** Claude autonomously routes heavy tasks (code review, bug hunting, deep reasoning, session init) to the right specialist. In v3, specialists run as **background CLI processes** — zero polling overhead, notifications on completion.
+Specialists is built on top of the **[pi coding agent](https://github.com/Jaggerxtrm/pi-coding-agent)** as its base execution technology. That gives Specialists access to a broad provider surface across many OAuth and API-backed models, a richer lifecycle event stream for tracking session progress and tool execution, and a usable RPC protocol for orchestrating specialist runs as a stable subprocess boundary.
 
----
-
-## How it works
-
-```
-┌──────────────────────────────────────────────┐
-│                 Claude Code                  │
-│                                              │
-│  MCP (control plane)   CLI (execution plane) │
-│  ─────────────────────  ──────────────────── │
-│  specialist_init        specialists run \    │
-│  list_specialists         <name> --background│
-│  use_specialist         specialists result \ │
-│  specialist_status        <id>               │
-└──────────────────────────────────────────────┘
-              ↓ file-based job state
-     .specialists/jobs/<id>/
-       status.json   result.txt   events.jsonl
-```
-
-Specialists are `.specialist.yaml` files discovered across two scopes:
+Specialists is intended to run inside the **xt/xtrm architecture** provided by **[xtrm-tools](https://github.com/Jaggerxtrm/xtrm-tools)**. xtrm-tools provides the worktree isolation, execution boundaries, session model, and surrounding workflow environment that Specialists expects. Specialists handles specialist execution; xtrm-tools owns the broader operator workflow and beads enforcement hooks. For tracking and coordination Specialists uses **beads** by **Steven Yegge** as the issue, dependency, and communication layer. I built a similar issue system for Mercury AACS and Terminal back in November, but Beads is already widely used and actively maintained, so xt/Specialists is built around Beads instead of carrying a separate workflow stack. When a specialist run originates from a bead, its output is written back to that same bead, so the task spec, dependency context, coordination state, and result stay inside one tight, controlled loop.
 
-| Scope | Location | Purpose |
-|-------|----------|---------|
-| **project** | `./specialists/` | Per-project specialists |
-| **user** | `~/.agents/specialists/` | Built-in defaults (copied on install) + your own |
-
-When a specialist runs, the server spawns a `pi` subprocess with the right model, tools, and system prompt injected. For background jobs, a **Supervisor** writes job state to disk — status, events, and final output — so Claude gets a one-shot notification on completion instead of polling.
+A specialist is a reusable execution spec: model, allowed tools, skills, system prompt, task prompt, timeout, permission level, output format, and background-job behavior. It can run from a plain prompt, from a system+task prompt pair, or directly from an **issue/bead ID as the task source**. Dependency chains can be injected as context, centralized memory can be reused across runs, and jobs can execute in the foreground or as background processes with status, events, and results exposed through the CLI and MCP surfaces.
 
 ---
 
-## Background Jobs (v3)
-
-The primary workflow for long-running specialists:
+## Quick start
 
 ```bash
-# Start in background — returns immediately
-specialists run overthinker --prompt "Refactor strategy?" --background
-# → Job started: a1b2c3
-
-# Check progress
-specialists status
-# → Active Jobs
-#   a1b2c3  overthinker  running  1m12s  tool: bash
-
-# Stream events live
-specialists feed --job a1b2c3 --follow
-
-# Get result when done
-specialists result a1b2c3
-
-# Cancel
-specialists stop a1b2c3
-```
-
-When a background job completes, Claude's next prompt automatically receives a banner:
-
-```
-[Specialist 'overthinker' completed (job a1b2c3, 87s). Run: specialists result a1b2c3]
-```
-
-Job files live in `.specialists/jobs/<id>/` (gitignored by `specialists init`):
-
-| File | Contents |
-|------|---------|
-| `status.json` | id, specialist, status, model, backend, pid, elapsed_s, bead_id, error |
-| `events.jsonl` | thinking\_start, toolcall\_start, tool\_execution\_end, agent\_end |
-| `result.txt` | Final assistant output |
-
----
-
-## MCP Tools (8)
-
-| Tool | Description |
-|------|-------------|
-| `specialist_init` | Session bootstrap: init beads if needed, return available specialists |
-| `list_specialists` | Discover all available specialists across scopes |
-| `use_specialist` | Run a specialist synchronously and return the result |
-| `specialist_status` | Circuit breaker health + background job summary |
-| `start_specialist` | *(deprecated v3)* Async job via in-memory registry — use CLI instead |
-| `poll_specialist` | *(deprecated v3)* Poll in-memory job — use CLI instead |
-| `stop_specialist` | *(deprecated v3)* Kill in-memory job — use `specialists stop <id>` |
-| `run_parallel` | *(deprecated v3)* Concurrent in-memory jobs — use CLI `--background` |
-
-For production use: `use_specialist` for short synchronous tasks, CLI `--background` for anything that takes more than a few seconds.
-
----
-
-## Built-in Specialists
-
-| Specialist | Model | Purpose |
-|-----------|-------|---------|
-| `init-session` | Haiku | Analyse git state, recent commits, surface relevant context |
-| `codebase-explorer` | Gemini Flash | Architecture analysis, directory structure, patterns |
-| `overthinker` | Sonnet | 4-phase deep reasoning: analysis → critique → synthesis → output |
-| `parallel-review` | Sonnet | Concurrent code review across multiple focus areas |
-| `bug-hunt` | Sonnet | Autonomous bug investigation from symptoms to root cause |
-| `feature-design` | Sonnet | Turn feature requests into structured implementation plans |
-| `auto-remediation` | Gemini Flash | Apply fixes to identified issues automatically |
-| `report-generator` | Haiku | Synthesise data/analysis results into structured markdown |
-| `test-runner` | Haiku | Run tests, parse results, surface failures |
-
----
-
-## Permission Tiers
-
-| Tier | pi tools | Use case |
-|------|---------|----------|
-| `READ_ONLY` | read, bash, grep, find, ls | Analysis, exploration |
-| `LOW` | read, bash, edit, write, grep, find, ls | Code modifications |
-| `MEDIUM` | read, bash, edit, write, grep, find, ls | Code modifications + git |
-| `HIGH` | read, bash, edit, write, grep, find, ls | Full autonomy |
-
-Permission is enforced at spawn time via `pi --tools`, not just in the system prompt.
-
----
-
-## Beads Integration
-
-Specialists with write permissions automatically create a [beads](https://github.com/beads/bd) issue and close it on completion. Control this per-specialist:
-
-```yaml
-beads_integration: auto    # default — create for LOW/MEDIUM/HIGH
-beads_integration: always  # always create
-beads_integration: never   # never create
+npm install -g @jaggerxtrm/specialists
+specialists init
+specialists list
 ```
 
-The `bead_id` is written to `status.json` so you can link issues for follow-up.
-
----
-
-## Installation
-
-### Recommended
+`sp` is a shorter alias for `specialists` — both commands are identical:
 
 ```bash
-npm install -g @jaggerxtrm/specialists
-specialists install
+sp list
+sp run bug-hunt --bead <id> --background
 ```
 
-Installs: **pi** (`@mariozechner/pi-coding-agent`), **beads** (`@beads/bd`), **dolt**, registers the `specialists` MCP at user scope, scaffolds `~/.agents/specialists/`, copies built-in specialists, and installs five Claude Code hooks:
-
-| Hook | Event | Enforces |
-|------|-------|---------|
-| `specialists-main-guard.mjs` | `PreToolUse` | No direct edits/commits on `main`/`master` |
-| `beads-edit-gate.mjs` | `PreToolUse` | No file edits without an `in_progress` beads issue |
-| `beads-commit-gate.mjs` | `PreToolUse` | No `git commit` while issues are `in_progress` |
-| `beads-stop-gate.mjs` | `Stop` | Agent cannot stop with unresolved issues |
-| `specialists-complete.mjs` | `UserPromptSubmit` | Injects background job completion banners |
-
-After running, **restart Claude Code** to load the MCP. Re-run `specialists install` at any time to update or repair.
-
-### One-time (no global install)
+Tracked work:
 
 ```bash
-npx --package=@jaggerxtrm/specialists install
+bd create "Investigate auth bug" -t bug -p 1 --json
+specialists run bug-hunt --bead <id> --background
+specialists feed -f
+bd close <id> --reason "Done"
 ```
 
----
+Ad-hoc work:
 
-## Writing a Specialist
-
-Create a `.yaml` file in `./specialists/` (project scope) or `~/.agents/specialists/` (user scope):
-
-```yaml
-specialist:
-  metadata:
-    name: my-specialist
-    version: 1.0.0
-    description: "What this specialist does."
-    category: analysis
-    tags: [analysis, example]
-    updated: "2026-03-11"
-
-  execution:
-    mode: tool
-    model: anthropic/claude-haiku-4-5
-    fallback_model: google-gemini-cli/gemini-3-flash-preview
-    timeout_ms: 120000
-    response_format: markdown
-    permission_required: READ_ONLY
-
-  prompt:
-    system: |
-      You are a specialist that does X.
-      Produce a structured markdown report.
-
-    task_template: |
-      $prompt
-
-    # Inject a single skill file into the system prompt
-    skill_inherit: ~/.agents/skills/my-domain-knowledge.md
-
-  communication:
-    output_to: .specialists/my-specialist-result.md   # optional file sink
-
-  skills:
-    # Run scripts before/after the specialist
-    scripts:
-      - path: ./scripts/health-check.sh
-        phase: pre            # runs before the task prompt
-        inject_output: true   # output available as $pre_script_output
-      - path: ./scripts/cleanup.sh
-        phase: post
-
-    # Inject multiple skill/context files into the system prompt (v3)
-    paths:
-      - ~/skills/domain-context.md
-      - ./specialists/shared/conventions.md
+```bash
+specialists run codebase-explorer --prompt "Map the CLI architecture"
 ```
 
-**Model IDs** use the full provider/model format: `anthropic/claude-sonnet-4-6`, `google-gemini-cli/gemini-3-flash-preview`, `anthropic/claude-haiku-4-5`.
+## What `specialists init` does
 
----
+- creates `specialists/`
+- creates `.specialists/` runtime dirs (`jobs/`, `ready/`)
+- adds `.specialists/` to `.gitignore`
+- injects the canonical Specialists Workflow block into `AGENTS.md` and `CLAUDE.md`
+- registers the Specialists MCP server at project scope
 
-## CLI
-
-| Command | Description |
-|---------|-------------|
-| `specialists install` | Full-stack installer: pi, beads, dolt, MCP, hooks |
-| `specialists init` | Scaffold `./specialists/`, `.specialists/`, update `.gitignore`, inject `AGENTS.md` block |
-| `specialists list` | List discovered specialists with model, description, scope |
-| `specialists models` | List models available on pi with capability flags |
-| `specialists edit <name> --<field> <value>` | Edit a specialist field in-place |
-| `specialists run <name>` | Run a specialist (foreground by default) |
-| `specialists run <name> --background` | Start as background job, print job ID |
-| `specialists result <id>` | Print result of a completed background job |
-| `specialists feed --job <id> [--follow]` | Tail events.jsonl; `--follow` streams live |
-| `specialists stop <id>` | Send SIGTERM to a running background job |
-| `specialists status` | System health + active background jobs |
-| `specialists version` | Print installed version |
-| `specialists help` | Show command reference |
-
-### specialists run
+Verify bootstrap state:
 
 ```bash
-# Foreground — streams output to stdout
-specialists run init-session --prompt "What changed recently?"
-
-# Background — returns job ID immediately
-specialists run overthinker --prompt "Refactor?" --background
-
-# Background with model override, no beads
-specialists run bug-hunt --prompt "TypeError in auth" --background \
-  --model anthropic/claude-sonnet-4-6 --no-beads
-
-# Pipe from stdin
-echo "Analyse the architecture" | specialists run codebase-explorer
+specialists status
+specialists doctor
 ```
 
-### specialists status
-
+## Documentation map
+
+`docs/` is the source of truth for detailed documentation. Start with the page that matches your task:
+
+| Need | Doc |
+|---|---|
+| Install and bootstrap a project | [docs/bootstrap.md](docs/bootstrap.md) |
+| Bead-first workflow and semantics | [docs/workflow.md](docs/workflow.md) |
+| CLI commands and flags | [docs/cli-reference.md](docs/cli-reference.md) |
+| Background jobs, feed, result, stop | [docs/background-jobs.md](docs/background-jobs.md) |
+| Write or edit a `.specialist.yaml` | [docs/authoring.md](docs/authoring.md) |
+| Current built-in specialists | [docs/specialists-catalog.md](docs/specialists-catalog.md) |
+| MCP registration details | [docs/mcp-servers.md](docs/mcp-servers.md) |
+| Hook behavior | [docs/hooks.md](docs/hooks.md) |
+| Skills shipped in this repo | [docs/skills.md](docs/skills.md) |
+| xtrm / worktree integration | [docs/worktree.md](docs/worktree.md) |
+| RPC mode notes | [docs/pi-rpc.md](docs/pi-rpc.md) |
+| Pi subprocess isolation and extensions | [docs/pi-session.md](docs/pi-session.md) |
+
+## Project structure
+
+```text
+config/
+├── specialists/    canonical specialist definitions (.specialist.yaml)
+├── hooks/          bundled hook scripts
+├── skills/         repo-local skills used by specialists
+└── extensions/     pi extensions (future)
+.specialists/
+├── default/        canonical assets (from init)
+│   ├── specialists/
+│   ├── hooks/
+│   └── skills/
+├── user/           custom additions
+│   ├── specialists/
+│   ├── hooks/
+│   └── skills/
+├── jobs/           runtime — gitignored
+└── ready/          runtime — gitignored
+src/                CLI, server, loader, runner, tools
 ```
-specialists status
 
-── Specialists ───────────────────────────
-  ✓ 9 found  (9 project)
+## Core workflow rules
 
-── pi  (coding agent runtime) ────────────
-  ✓ v0.57.1  —  4 providers active  (anthropic, google-gemini-cli, qwen, zai)
+- **Use `--bead` for tracked work.** The bead is the prompt source.
+- **Use `--prompt` for ad-hoc work only.**
+- `--context-depth` controls how many completed blocker levels are injected.
+- `--no-beads` does **not** disable bead reading.
+- specialists are **project-only**. User-scope specialist discovery is deprecated.
 
-── beads  (issue tracker) ────────────────
-  ✓ bd installed  v0.59.0
-  ✓ .beads/ present in project
+## Deprecated commands
 
-── MCP ───────────────────────────────────
-  ✓ specialists binary installed  /usr/local/bin/specialists
+These commands are still recognized for migration guidance but are no longer onboarding paths:
 
-── Active Jobs ───────────────────────────
-  a1b2c3  overthinker           running   1m12s  tool: bash
-  g7h8i9  init-session          done      0m08s
-```
+- `specialists setup`
+- `specialists install`
 
----
+Use `specialists init` instead.
 
 ## Development
 
 ```bash
-git clone https://github.com/Jaggerxtrm/specialists.git
-cd specialists
-bun install
-bun run build    # bun build src/index.ts --target=node --outfile=dist/index.js
-bun test         # bun --bun vitest run
+bun run build
+bun test
+specialists help
+specialists quickstart
 ```
 
-See [CLAUDE.md](CLAUDE.md) for the full architecture guide.
-
----
-
 ## License
 
 MIT