@jaggerxtrm/specialists 3.15.3 → 3.16.0

package/README.md

@@ -121,6 +121,18 @@ Specialists uses two distribution tracks:
 
 `.specialists/user/` is your customization layer. `.specialists/default/` is now only for intentional pins or compatibility snapshots; stale default files are drift debt and `sp prune-stale-defaults` removes them by default. `sp init --sync-defaults` remains as a compatibility path, but it is deprecated because it creates repo-local snapshots that can drift from the package-canonical source.
 
+For an interactive, agent-guided update flow that runs both tracks, diagnoses drift, and asks before applying destructive changes, invoke the `/update-specialists` skill in Claude Code instead of running the raw commands manually.
+
+## Operator skills
+
+These skills load into your Claude Code session on demand and guide the most common operator workflows:
+
+| Skill | Invoke | When to use |
+|---|---|---|
+| `using-specialists-v3` | `/using-specialists-v3` | **Canonical orchestration guide.** Use for any substantial delegated work: implementation, debugging, review, planning, security audit, doc sync, multi-chain epics. Covers bead contracts, role selection, chain lifecycle, merge path, and escalation. |
+| `using-specialists-auto` | `/using-specialists-auto` | **Autonomous / offline mode.** Activates when you hand over a multi-item list and step away ("auto mode", "run the list"). Layers pacing discipline and escalation triggers on top of `using-specialists-v3`. |
+| `update-specialists` | `/update-specialists` | **Guided drift repair.** Runs both Category A and Category B diagnostics, presents a combined plan, and asks before applying anything. Prefer this over running raw `sp`/`xt` commands directly. |
+
 ## Core tracked workflow
 
 ```bash
@@ -132,6 +144,9 @@ sp ps
 sp feed <job-id> --follow
 sp result <job-id>
 
+# Human-in-the-loop alternative: launch with a live TUI
+sp chat debugger --bead <id>          # feed-style timeline + status + final result + input
+
 # After implementation and reviewer PASS
 sp merge <chain-root-bead>          # standalone chain
 sp epic status <epic-id>            # multi-chain publication check
@@ -157,6 +172,7 @@ sp ps                         # actionable dashboard
 sp ps -f                      # TTY dashboard follow; pipes emit ANSI-free snapshots
 sp feed <job-id>              # full DB-backed event replay
 sp feed -f                    # follow all active jobs
+sp chat explorer --bead <id>    # launch interactive TUI; input auto-steers/resumes
 sp result <job-id> --wait
 sp steer <job-id> "focus only on X"
 sp resume <job-id> "continue with these findings"
@@ -165,6 +181,8 @@ sp clean --reap-orphans --dry-run
 sp clean --ps                 # hide terminal dashboard history without deleting DB audit rows
 ```
 
+`sp chat` is for launching a new interactive specialist session. It renders the same normalized feed style as `sp feed -f`, shows startup/payload context and the final result, and maps typed input to `steer` while running or `resume` while waiting. `/quit` and Ctrl+C detach the TUI without stopping the job; use `/stop` when you intend to stop it. Current `sp attach <job-id>` remains the legacy tmux attach path; chat-style attach to an existing job is tracked separately.
+
 ## Script and service specialists
 
 Use `sp run` for interactive agent orchestration. Use the script/service surfaces when you need a synchronous, READ_ONLY, one-shot generation path:
@@ -193,7 +211,10 @@ curl -sS http://localhost:8000/v1/generate \
 | Tool catalog and permission resolver | [docs/manifest.md](docs/manifest.md) |
 | MCP registration and tool surface | [docs/mcp-servers.md](docs/mcp-servers.md), [docs/mcp-tools.md](docs/mcp-tools.md) |
 | Hooks | [docs/hooks.md](docs/hooks.md) |
-| Skills | [docs/skills.md](docs/skills.md) |
+| Skills and operator skill reference | [docs/skills.md](docs/skills.md) |
+| Orchestration skill (`using-specialists-v3`) | [docs/skills.md#using-specialists-v3](docs/skills.md#using-specialists-v3) |
+| Auto mode skill (`using-specialists-auto`) | [docs/skills.md#using-specialists-auto](docs/skills.md#using-specialists-auto) |
+| Update / drift repair skill (`update-specialists`) | [docs/skills.md#update-specialists](docs/skills.md#update-specialists) |
 | Worktrees and session close | [docs/worktrees.md](docs/worktrees.md), [docs/worktree.md](docs/worktree.md) |
 | Runtime architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
 | Pi subprocess isolation / RPC boundary | [docs/pi-session.md](docs/pi-session.md), [docs/pi-rpc-boundary.md](docs/pi-rpc-boundary.md) |

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

@@ -5,8 +5,8 @@ description: >
   agent through writing a valid `.specialist.json`, choosing supported models,
   validating against the schema, and avoiding common specialist authoring
   mistakes.
-version: 1.2
-synced_at: 236ca5e6
+version: 1.3
+synced_at: 78a7883e
 ---
 
 # Specialist Author Guide
@@ -358,16 +358,35 @@ Typical use cases:
 - `gitnexus: false` for specialists that should not receive GitNexus graph tooling
 - set both `false` for constrained runs that need clean extension surface
 
+### Bare specialists
+
+Use `execution.bare: true` for non-coding LLM transforms that need a fresh canvas: research synthesis, document analysis, summarization, extraction, translation, or other tasks where specialist runtime framing adds noise instead of help.
+
+Bare mode disables all package-runner prompt injection beyond rendered `prompt.system` and `prompt.task_template`: Specialist Run Context, Output Style, GitNexus mandate, `STATIC_WORKFLOW_RULES_BLOCK`, memory injection, GitNexus pre-query snapshot, reviewer patch retrieval, output contract, and task-side mandatory rules / reviewer diff context.
+
+`execution.bare` is orthogonal to `prompt.system_prompt_mode`. Set `bare: true` without `system_prompt_mode: "replace"` when you want to keep pi's coding-agent base prompt but skip specialist runtime injections.
+
+Copy bare template from installed npm package, not repo clone:
+
+```bash
+cp "$(node -p \"require.resolve('@jaggerxtrm/specialists/package.json').replace(/package\\.json$/, '')\")config/specialists/bare.specialist.json" ".specialists/user/<your-name>.specialist.json"
+```
+
+Warning: bare mode bypasses `mandatory_rules` completely — template sets, inline rules, and global disables all skip runtime injection in bare runs.
+
 ### `specialist.prompt` (required)
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
 | `task_template` | string | yes | Template string with `$variable` substitution |
 | `system` | string | no | System prompt / agents.md content |
+| `system_prompt_mode` | enum | no | `append` \| `replace` — see [System Prompt Mode](#system-prompt-mode) |
 | `skill_inherit` | string | no | Single skill folder/file injected via `pi --skill` (Agent Forge compat) |
 | `output_schema` | object | no | JSON schema for structured output — injected into system prompt by runner; post-run validation is warn-only |
 | `examples` | array | no | Few-shot examples |
 
+> **Replace mode warning:** `replace` removes pi's coding-agent base prompt. Teach every command, tool, convention, output format, and behavior explicitly in `prompt.system`; nothing implicit remains.
+
 **Output contract precedence (runner-injected):** `response_format` → `output_type` → `output_schema`.
 
 **`response_format` behavior**
@@ -397,6 +416,24 @@ Typical use cases:
 
 **Mandatory markdown+schema rule:** if `response_format: markdown` and `output_schema` is present, the output must include `## Machine-readable block` containing exactly one JSON object in a single ` ```json ` fenced block. That JSON object is canonical and must match the schema.
 
+### System Prompt Mode
+
+`prompt.system_prompt_mode` controls whether `prompt.system` replaces or appends to pi's base prompt.
+
+| Runner | Default when field absent | `append` sees | `replace` sees |
+|--------|---------------------------|---------------|----------------|
+| Package-class (`sp run` → `runner.ts` → `session.ts`) | `append` | pi coding-agent base prompt + specialist `agentsMd` | only specialist `agentsMd` |
+| Script-class (`sp script` / `sp serve` → `script-runner.ts`) | `replace` | only specialist `prompt.system` | only specialist `prompt.system` |
+
+| Combination | Agent sees |
+|-------------|------------|
+| Package × append | pi coding-agent base prompt + specialist `agentsMd` |
+| Package × replace | only specialist `agentsMd` |
+| Script × append | pi coding-agent base prompt + specialist `prompt.system` |
+| Script × replace | only specialist `prompt.system` |
+
+> **Replace mode warning:** use `replace` only when you intend to author full prompt surface yourself. No coding-agent defaults survive; teach commands, tools, conventions, output contract, and behavior explicitly. Best fit: non-coding transforms where base prompt adds noise.
+
 Standard schemas by specialist type (shown as the `output_schema` object value):
 
 executor — change manifest:
@@ -441,6 +478,48 @@ planner — epic result:
 }
 ```
 
+### `specialist.mandatory_rules` (optional)
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `template_sets` | string[] | `[]` | Adds rule-set ids from `config/mandatory-rules/index.json` and local overlays |
+| `disable_default_globals` | boolean | `false` | Suppresses only inline `STATIC_WORKFLOW_RULES_BLOCK` (`Beads Workflow Quick Rules`) |
+| `inline_rules` | `MandatoryRule[]` | `[]` | Inline rules appended without file lookup |
+
+Runtime layering:
+
+1. `config/mandatory-rules/index.json.required_template_sets` — always loaded
+2. `config/mandatory-rules/index.json.default_template_sets` — also always loaded today; current quirk, not suppressed by `disable_default_globals`
+3. `specialist.mandatory_rules.template_sets`
+4. `specialist.mandatory_rules.inline_rules`
+
+`disable_default_globals` only removes the inline `STATIC_WORKFLOW_RULES_BLOCK`. It does **not** suppress index-driven sets. True user-rules-only runs need both `disable_default_globals: true` and a user overlay index in `.specialists/user/mandatory-rules/index.json` that clears required/default sets.
+
+Canonical set ids in `config/mandatory-rules/*.md`:
+`bead-id-verbatim`, `changelog-conventions`, `changelog-keeper-scope`, `code-quality-defaults`, `core-session-boundary`, `diagnose-loop`, `executor-delivery`, `explorer-readonly`, `git-workflow-safe`, `gitnexus-required`, `overthinker-4phase`, `per-turn-handoff-schema`, `research-tool-routing`, `researcher-source-discipline`, `reviewer-verdict-format`, `security-review-defaults`, `serena-cheatsheet`, `sync-docs-scope-discipline`, `test-runner-execution-scope`.
+
+Minimal user-rules-only spec:
+
+```json
+{
+  "specialist": {
+    "mandatory_rules": {
+      "disable_default_globals": true,
+      "inline_rules": [
+        { "id": "user-rule-1", "level": "error", "text": "Use local policy only." },
+        { "id": "user-rule-2", "level": "warn", "text": "Prefer repo overlay index.", "when": "overlay exists" }
+      ]
+    }
+  }
+}
+```
+
+Inline rule shape:
+
+```json
+{ "id": "rule-id", "level": "error", "text": "Rule text", "when": "optional condition" }
+```
+
 ### `specialist.skills` (optional)
 
 ```json
@@ -794,3 +873,41 @@ specialists run my-specialist --prompt "ping" --no-beads
 ```
 
 If you need the underlying implementation, read `config/skills/specialists-creator/scripts/validate-specialist.ts`. It is a thin Bun/TypeScript wrapper over `parseSpecialist()` from `src/specialist/schema.ts`, which keeps the helper cross-platform for Windows, macOS, and Linux.
+
+---
+
+## Script-Class vs Package-Class Runtime
+
+Two runtime classes exist:
+
+- **Package-class**: `sp run` → `runner.ts` → `session.ts`
+- **Script-class**: `sp script` / `sp serve` → `script-runner.ts`
+
+| Runner | Injected into system prompt |
+|--------|----------------------------|
+| Package-class | `prompt.system` + Specialist Run Context + caveman output style + GitNexus mandate (if `.gitnexus` exists) + `STATIC_WORKFLOW_RULES_BLOCK` + memory injection + mandatory rules + skills inheritance + output contract + reviewer patch retrieval (reviewer reuse only) |
+| Script-class | `prompt.system` only |
+
+Pi flags:
+
+| Runner | Pi flags |
+|--------|----------|
+| Package-class | `--no-extensions`, then re-enable quality-gates/service-skills/caveman/gitnexus/serena |
+| Script-class | `--no-extensions --no-tools --offline --no-context-files --no-prompt-templates --no-themes` and `--no-skills` when `skills.paths` is empty |
+
+Settings that silently do nothing on script-class:
+
+- `mandatory_rules` (all fields)
+- beads injection
+- GitNexus mandate
+- memory injection
+- output contract auto-generation
+
+Per-runner default for `prompt.system_prompt_mode`:
+
+- Package-class: `append`
+- Script-class: `replace`
+
+> **Script-class warning:** `mandatory_rules` never reaches script-class. If spec must rely on rule sets, it must run package-class.
+
+---

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

@@ -292,7 +292,7 @@ Core commands:
 - `bd create --parent <epic-id>`: epic-child edge; auto-names child `.1`, `.2`, … and adds parent ownership. Use for chain members that must live under an epic. [source: bd create --help]
 - `bd create --deps discovered-from:<id>` or `bd dep add <new> <source> --type discovered-from`: follow-up work discovered from a source bead.
 - `bd duplicate <new> --of <canonical>`: close duplicate issue and point at canonical. Use when two beads describe the same required work.
-- `bd duplicates` / `bd find-duplicates --status open --method ai --json`: find exact or semantic duplicates before dispatching parallel chains.
+- `bd duplicates` / `bd find-duplicates --status open --method mechanical --json`: cheap duplicate prefilter before dispatching parallel chains. For semantic clustering, use the `issue-triage` skill path (mechanical prefilter + bv graph signals + explorer/GitNexus overlap + overthinker recommendations), not `bd --method ai`.
 - `bd supersede <old> --with <new>` or `bd dep add <new> <old> --type supersedes`: mark a replacement when a better-scoped fix bead replaces an obsolete/abandoned one.
 - `bd dep cycles`, `bd dep tree <id>`, and `bd graph <id>`: sanity-check the execution graph before merge/publication.
 
@@ -345,10 +345,49 @@ Use each form for a different reason:
 - `parent-child` / `--parent` for epic ownership and child naming.
 - `supersedes` / `bd supersede` for replacement work; `duplicate` for same-work issues.
 
-Cross-repo consistency: keep this vocabulary aligned with the xtrm-tools triaging skill and sibling triage bead `xtrm-drkk`; both should use the same relationship names when rewiring issue graphs.
+Cross-repo consistency: keep this vocabulary aligned with the xtrm-tools `issue-triage` and `planning` skills; all three should use the same relationship names when creating or rewiring issue graphs.
 
 What differs: orchestrator chooses edge type deliberately, so graph stays correct for chain execution, epic publish, duplicate cleanup, root-cause navigation, verification evidence, and follow-up traceability.
 
+## Swarm Validation For Epic Readiness
+
+Use `bd swarm` as graph-level readiness instrumentation for multi-chain epics. It does **not** replace specialists jobs, `sp epic status`, or `sp epic merge`; it validates and summarizes the bead DAG so you know whether the epic is shaped for parallel execution before spending specialist tokens.
+
+Command surface:
+
+```bash
+bd swarm validate <epic-id> [--verbose] [--json]
+bd swarm status <epic-or-swarm-id> [--json]
+bd swarm list [--json]
+bd swarm create <epic-id> [--coordinator=<addr>] [--force]
+```
+
+What each command is for:
+
+| Command | Use it when | Output / decision |
+| --- | --- | --- |
+| `bd swarm validate <epic>` | Before launching a multi-chain epic, after graph rewrites, and before `sp epic merge` | Finds dependency-direction mistakes, orphan/disconnected children, cycles, ready fronts, estimated worker sessions, and max parallelism |
+| `bd swarm status <epic-or-swarm>` | During orchestration | Shows computed completed / active / ready / blocked groups from live bead state |
+| `bd swarm list` | Operator wants all active swarm molecules | Inventory of swarm molecules with epic/progress summary |
+| `bd swarm create <epic>` | Operator explicitly wants a swarm molecule/coordinator handoff | Mutates board state; confirm first. If passed a task, bd may auto-wrap it in an epic. |
+
+Where it fits in orchestration:
+
+1. **After planning / before dispatch**: run `bd swarm validate <epic-id> --json` for epics with 3+ children or intended parallel execution. Treat warnings as graph-shaping feedback; fix relationship types or split/merge beads before launching specialists.
+2. **During execution**: use `bd swarm status <epic-id> --json` alongside `sp ps`. `sp ps` tells you job/runtime state; swarm status tells you issue-graph state (ready vs blocked fronts).
+3. **Before publication**: run `bd swarm validate <epic-id>` plus `bd dep cycles` and `sp epic status <epic-id>`. Do not `sp epic merge` if swarm validation reports cycles, disconnected graph, or suspicious dependency direction.
+4. **Optional coordinator handoff**: run `bd swarm create <epic-id> --coordinator=<addr>` only after operator confirmation. Creating a swarm molecule is a tracked mutation, not a default read-only check.
+
+Example gate before parallel dispatch:
+
+```bash
+bd dep cycles
+bd swarm validate <epic-id> --json > .triage/swarm-<epic-id>.json
+sp epic status <epic-id>
+```
+
+If validation says max parallelism is 1, do not pretend the epic is parallel; dispatch serially or fix the graph. If it reports multiple ready fronts, use that as the wave plan for specialist launches.
+
 ## Bead Contract By Bead Type
 
 Use shape that fits specialist.
@@ -606,7 +645,7 @@ bd supersede <old-chain-a> --with <unified-chain>
 bd supersede <old-chain-b> --with <unified-chain>
 ```
 
-Default heuristic: if 3+ chains touch the same file, **serial-dispatch them**. Conflict-resolution time at integration usually exceeds the time saved by parallel dispatch. Run `bd find-duplicates --status open --method ai --json` before launching a large wave; merge or supersede duplicate work before specialists spend tokens on it.
+Default heuristic: if 3+ chains touch the same file, **serial-dispatch them**. Conflict-resolution time at integration usually exceeds the time saved by parallel dispatch. Before launching a large wave, run mechanical duplicate prefiltering and semantic clustering through `issue-triage` (or its core path: `bd find-duplicates --method mechanical` + `bv --robot-triage/alerts` + explorer/GitNexus overlap + overthinker recommendations); merge or supersede duplicate work before specialists spend tokens on it.
 
 ## Pre-Epic: Test-Failure-Map Pattern
 

package/config/specialists/bare.specialist.json

@@ -0,0 +1,56 @@
+{
+  "specialist": {
+    "metadata": {
+      "name": "bare",
+      "version": "1.0.0",
+      "description": "TEMPLATE — do not dispatch. Copy from the installed @jaggerxtrm/specialists package to .specialists/user/<your-name>.specialist.json and customize for your own task. Fresh-canvas specialist template for non-coding transforms that need zero runtime prompt injection.",
+      "category": "template",
+      "tags": [
+        "template",
+        "bare-mode",
+        "copy-me"
+      ]
+    },
+    "execution": {
+      "bare": true,
+      "mode": "tool",
+      "model": "openai/codex-5",
+      "fallback_model": "google-gemini-cli/gemini-3.1-pro-preview",
+      "timeout_ms": 120000,
+      "max_retries": 0,
+      "interactive": false,
+      "response_format": "markdown",
+      "output_type": "synthesis",
+      "permission_required": "READ_ONLY",
+      "extensions": {
+        "serena": false,
+        "gitnexus": false
+      }
+    },
+    "prompt": {
+      "system": "You are a fresh-canvas specialist for one narrow transform. No hidden rules assumed.\n\nYour job: read the supplied input carefully, decide what transformation is needed, and produce only the requested result. Use no commands unless the task explicitly authorizes them. If commands are allowed, list each command before running it, explain why it is needed, and stop if the command output does not match the task.\n\nAvailable tools in this run are only those granted by the specialist configuration. Treat them as the complete tool list. If you need a tool that is not present, state the limitation and continue with a best-effort answer instead of inventing capabilities.\n\nOutput format: return a short heading, then the transformed result, then a brief note listing assumptions or blockers. If the task requires structured output, emit exactly that structure and nothing extra.\n\nTermination condition: finish once the requested transform is complete and self-consistent. Do not add policy reminders, runtime framing, or extra commentary. If the input is ambiguous, ask one precise clarification question and stop.",
+      "system_prompt_mode": "replace",
+      "task_template": "Transform the following input using the brief above. Preserve meaning, keep only requested content, and return the final answer in the format you chose.\n\n$prompt"
+    },
+    "skills": {
+      "paths": [],
+      "scripts": []
+    },
+    "capabilities": {
+      "required_tools": [],
+      "external_commands": []
+    },
+    "validation": {
+      "files_to_watch": [
+        "config/specialists/bare.specialist.json"
+      ],
+      "stale_threshold_days": 30
+    },
+    "stall_detection": {},
+    "mandatory_rules": {
+      "template_sets": []
+    },
+    "beads_integration": "auto",
+    "beads_write_notes": true
+  }
+}

package/config/specialists/changelog-drafter.specialist.json

@@ -26,7 +26,10 @@
       "interactive": false,
       "max_retries": 0,
       "mode": "auto",
-      "requires_worktree": false
+      "requires_worktree": false,
+      "extensions": {
+        "serena": false
+      }
     },
     "mandatory_rules": {
       "template_sets": [

package/config/specialists/code-sanity.specialist.json

@@ -26,14 +26,16 @@
       "permission_required": "READ_ONLY",
       "interactive": true,
       "thinking_level": "low",
-      "max_retries": 0
+      "max_retries": 0,
+      "extensions": {
+        "serena": false
+      }
     },
     "mandatory_rules": {
       "template_sets": [
         "explorer-readonly",
         "gitnexus-required",
         "code-quality-defaults",
-        "serena-cheatsheet",
         "per-turn-handoff-schema",
         "bead-id-verbatim"
       ]

package/config/specialists/explorer.specialist.json

@@ -23,13 +23,15 @@
       "output_type": "analysis",
       "permission_required": "READ_ONLY",
       "max_retries": 0,
-      "interactive": true
+      "interactive": true,
+      "extensions": {
+        "serena": false
+      }
     },
     "mandatory_rules": {
       "template_sets": [
         "explorer-readonly",
         "gitnexus-required",
-        "serena-cheatsheet",
         "per-turn-handoff-schema",
         "bead-id-verbatim"
       ]

package/config/specialists/overthinker.specialist.json

@@ -24,13 +24,15 @@
       "output_type": "synthesis",
       "permission_required": "READ_ONLY",
       "interactive": true,
-      "max_retries": 0
+      "max_retries": 0,
+      "extensions": {
+        "serena": false
+      }
     },
     "mandatory_rules": {
       "template_sets": [
         "overthinker-4phase",
         "research-tool-routing",
-        "serena-cheatsheet",
         "per-turn-handoff-schema",
         "bead-id-verbatim"
       ]

package/config/specialists/specialists-creator.specialist.json

@@ -2,10 +2,10 @@
   "specialist": {
     "metadata": {
       "name": "specialists-creator",
-      "version": "1.3.0",
+      "version": "1.4.0",
       "description": "Specialist-definition author. Use for creating or fixing .specialist.json files, choosing valid models, schema fields, permissions, rules, and config validation. HIGH; not for ordinary app code.",
       "category": "authoring",
-      "updated": "2026-05-04",
+      "updated": "2026-05-23",
       "tags": [
         "authoring",
         "json",
@@ -27,7 +27,7 @@
       "interactive": false
     },
     "prompt": {
-      "system": "You are a specialist authoring assistant. Your job is to help agents and developers\nwrite valid .specialist.json files that pass schema validation on the first attempt.\n\nYou have deep knowledge of the SpecialistSchema (Zod) and the runtime behavior of\nSpecialistRunner. You know every required field, every valid enum value, and every\ncommon pitfall.\n\nMANDATORY — model selection protocol (enforced every run):\nThe available models are injected into $pre_script_output by the pre-script.\nYou MUST:\n  1. Read $pre_script_output to see the real available models.\n  2. Select a primary and fallback from DIFFERENT providers.\n  3. Ping both before writing any JSON:\n       pi --model <primary>  --print \"ping\"   # must return \"pong\"\n       pi --model <fallback> --print \"ping\"   # must return \"pong\"\n  4. If a ping fails, pick the next best in that tier and ping again.\n  5. Only write the JSON after both return \"pong\".\n\nNever hardcode a model string from memory. Never skip pinging.\n\nABSOLUTE RULES — violation terminates the task:\n  - DO NOT delete, move, or rename any existing file or directory.\n  - DO NOT modify any file that was not explicitly requested by the user.\n  - You may only CREATE new files and WRITE to files you have been asked to create.\n\nCONTEXT WINDOW AWARENESS — apply to every specialist you create:\n  - Context rot degrades quality before the hard limit is hit. Design for bounded runs.\n  - Always set stall_timeout_ms for interactive/keep-alive specialists.\n  - Use thinking_level: low for orchestration specialists that emit structured JSON.\n  - If the specialist is multi-turn or a Node member: add handoff_summary to output_schema.\n  - Never inject large static context blobs in task_template that could be fetched on demand.\n  - context_pct = cumulative_input_tokens / model_context_window * 100\n    Windows: anthropic claude-* = 200k, gemini-3.1-pro = 1M, qwen3.5/glm-5 = 128k\n\nWhen asked to create a specialist, you:\n1. Run the model selection protocol above (steps 1-5).\n2. Run scaffold-specialist.ts first to materialize all schema fields.\n3. Use `sp edit <name> <dot.path> <value>` as the primary mutation tool.\n4. Use `sp edit <name> --preset <preset>` for common model/thinking baselines.\n5. Use raw file-based writes (`--file`) only for multiline `specialist.prompt.system` and `specialist.prompt.task_template`.\n6. When extension surface matters, set `specialist.execution.extensions.serena` and/or `specialist.execution.extensions.gitnexus` to `false` instead of inventing ad-hoc flags.\n7. After setting `permission_required`, run `sp config show <name> --resolved` and inspect the `--tools` line. The catalog tier defaults are correct for nearly every specialist — do NOT add a `specialist.permissions[<TIER>]` override block unless the policy genuinely diverges. Today only explorer declares one (hard-deny on native grep/find/ls). See docs/manifest.md for full semantics.\n8. When user wants canonical mandatory rules or canonical skills, reference them by name (for example mandatory_rules.template_sets=[\"serena-cheatsheet\"] or skills.paths=[\"releasing\"]) — runtime resolves package-canonical assets when no project-local override exists.\n9. Write specialist.metadata.description as a routing summary for `specialists list`: choose-when, do-not-choose-when, distinctive capability, and permission/workflow note.\n10. Run `sp view <name>`, `specialists list`, and schema validation to confirm final output and list readability.\n11. Highlight any fields the user should customize.\n\nWhen asked to fix a specialist, you:\n1. Identify the exact Zod error and map it to the fix table in the skill.\n2. Apply focused fixes via `sp edit` (or `--file` for prompt.system/task_template only).\n3. Explain why the original was invalid.\n",
+      "system": "You are a specialist authoring assistant. Your job is to help agents and developers\nwrite valid .specialist.json files that pass schema validation on the first attempt.\n\nYou have deep knowledge of the SpecialistSchema (Zod) and the runtime behavior of\nSpecialistRunner. You know every required field, every valid enum value, and every\ncommon pitfall.\n\nMANDATORY — model selection protocol (enforced every run):\nThe available models are injected into $pre_script_output by the pre-script.\nYou MUST:\n  1. Read $pre_script_output to see the real available models.\n  2. Select a primary and fallback from DIFFERENT providers.\n  3. Ping both before writing any JSON:\n       pi --model <primary>  --print \"ping\"   # must return \"pong\"\n       pi --model <fallback> --print \"ping\"   # must return \"pong\"\n  4. If a ping fails, pick the next best in that tier and ping again.\n  5. Only write the JSON after both return \"pong\".\n\nNever hardcode a model string from memory. Never skip pinging.\n\nABSOLUTE RULES — violation terminates the task:\n  - DO NOT delete, move, or rename any existing file or directory.\n  - DO NOT modify any file that was not explicitly requested by the user.\n  - You may only CREATE new files and WRITE to files you have been asked to create.\n\nCONTEXT WINDOW AWARENESS — apply to every specialist you create:\n  - Context rot degrades quality before the hard limit is hit. Design for bounded runs.\n  - Always set stall_timeout_ms for interactive/keep-alive specialists.\n  - Use thinking_level: low for orchestration specialists that emit structured JSON.\n  - If the specialist is multi-turn or a Node member: add handoff_summary to output_schema.\n  - Never inject large static context blobs in task_template that could be fetched on demand.\n  - context_pct = cumulative_input_tokens / model_context_window * 100\n    Windows: anthropic claude-* = 200k, gemini-3.1-pro = 1M, qwen3.5/glm-5 = 128k\n\nWhen asked to create a specialist, you:\n1. Run the model selection protocol above (steps 1-5).\n2. Run scaffold-specialist.ts first to materialize all schema fields.\n3. Use `sp edit <name> <dot.path> <value>` as the primary mutation tool.\n4. Use `sp edit <name> --preset <preset>` for common model/thinking baselines.\n5. Use raw file-based writes (`--file`) only for multiline `specialist.prompt.system` and `specialist.prompt.task_template`.\n6. When extension surface matters, set `specialist.execution.extensions.serena` and/or `specialist.execution.extensions.gitnexus` to `false` instead of inventing ad-hoc flags.\n7. After setting `permission_required`, run `sp config show <name> --resolved` and inspect the `--tools` line. The catalog tier defaults are correct for nearly every specialist — do NOT add a `specialist.permissions[<TIER>]` override block unless the policy genuinely diverges. Today only explorer declares one (hard-deny on native grep/find/ls). See docs/manifest.md for full semantics.\n8. When user wants canonical mandatory rules or canonical skills, reference them by name (for example mandatory_rules.template_sets=[\"serena-cheatsheet\"] or skills.paths=[\"releasing\"]) — runtime resolves package-canonical assets when no project-local override exists.\n9. Write specialist.metadata.description as a routing summary for `specialists list`: choose-when, do-not-choose-when, distinctive capability, and permission/workflow note.\n10. Run `sp view <name>`, `specialists list`, and schema validation to confirm final output and list readability.\n11. Highlight any fields the user should customize.\n\nWhen asked to create a specialist, also decide whether `prompt.system_prompt_mode` should stay `append` or switch to `replace`. Use `replace` only when the specialist must own every command, tool, and output convention explicitly; once replaced, nothing implicit remains.\n\nSet `execution.bare: true` for fresh-canvas non-coding specialists like research, summarization, extraction, document analysis, or translation. Bare mode skips mandatory_rules entirely, so use inline rules in `prompt.system` when you still need constraints.\n\nIf you do use `mandatory_rules`, keep the opt-in pattern explicit: `template_sets`, `disable_default_globals`, and `inline_rules` are separate controls. `disable_default_globals` only removes the inline `STATIC_WORKFLOW_RULES_BLOCK`; it does not disable index-driven template sets.\n\nFor bare specs, use `config/specialists/bare.specialist.json` as the copy-and-edit starter template.\n\nWhen asked to fix a specialist, you:\n1. Identify the exact Zod error and map it to the fix table in the skill.\n2. Apply focused fixes via `sp edit` (or `--file` for prompt.system/task_template only).\n3. Explain why the original was invalid.\n",
       "task_template": "$prompt\n\nWorking directory: $cwd\n\nAvailable models (from pi --list-models — use this, do not guess):\n$pre_script_output\n\nInstructions:\n  1. Read the model list above. Select primary + fallback from different providers.\n  2. Ping both: pi --model <primary> --print \"ping\" and pi --model <fallback> --print \"ping\"\n  3. Only proceed after both return \"pong\".\n  4. Run scaffold-specialist.ts first, then mutate fields with `sp edit` (dot.path + preset).\n  5. Use `--file` only for prompt.system and prompt.task_template.\n  6. If user asks to disable Serena or GitNexus for specialist, set `specialist.execution.extensions.serena false` and/or `specialist.execution.extensions.gitnexus false`.\n  7. After tier is set, run `sp config show <name> --resolved` and verify the `--tools` line matches expectations. Only add a top-level `specialist.permissions[<TIER>]` override (sibling to `execution`) if policy genuinely diverges from the catalog tier default — see docs/manifest.md.\n  7a. For canonical shared guidance, reference package assets by name instead of copying files: `mandatory_rules.template_sets` for rules and `skills.paths` for canonical skills.\n  8. Write metadata.description for `specialists list` routing: choose-when, do-not-choose-when, distinctive capability, permission/workflow note.\n  9. Run `sp view <name>`, `specialists list`, and schema validation before outputting the final result.\n"
     },
     "skills": {
@@ -55,10 +55,12 @@
     },
     "validation": {
       "files_to_watch": [
-        "src/specialist/schema.ts",
-        "src/specialist/runner.ts",
+        ".xtrm/skills/default/specialists-creator/SKILL.md",
+        "config/specialists/bare.specialist.json",
+        "src/specialist/mandatory-rules.ts",
         "src/specialist/manifest-resolver.ts",
-        ".xtrm/skills/default/specialists-creator/SKILL.md"
+        "src/specialist/runner.ts",
+        "src/specialist/schema.ts"
       ],
       "stale_threshold_days": 30
     },

package/dist/asset-contract.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0.0",
-  "package_version": "3.15.3",
+  "package_version": "3.16.0",
   "shipped_skills": [
     {
       "path": "config/skills/memory-audit-transaction/SKILL.md",
@@ -12,7 +12,7 @@
     },
     {
       "path": "config/skills/specialists-creator/SKILL.md",
-      "sha256": "250cd9376b818142d1ccca71b48198086723ab2453ebac1eb69c3ba6293e9721"
+      "sha256": "f8951e41b20d03a1a5cb71cd79fc7a17f525aba7005cce893d2a4524fc5a169e"
     },
     {
       "path": "config/skills/update-specialists/SKILL.md",
@@ -40,7 +40,7 @@
     },
     {
       "path": "config/skills/using-specialists-v3/SKILL.md",
-      "sha256": "643264862dfa758f85cff41a150be13d6a0c2c8ed42ded6186a3b9b16a87852b"
+      "sha256": "034692ee7ce97984a587a9ac4a612c3b71e37e03fea6a4d23bf37e388ace6cca"
     },
     {
       "path": "config/skills/using-specialists/SKILL.md",
@@ -48,6 +48,9 @@
     }
   ],
   "shipped_specialists": [
+    {
+      "path": "config/specialists/bare.specialist.json"
+    },
     {
       "path": "config/specialists/changelog-drafter.specialist.json"
     },