@jaggerxtrm/specialists 3.18.1 → 3.18.3

package/docs/design/roadmap/specialists-roadmap.md

@@ -445,7 +445,7 @@ Both verbs surface counts (`stopped 7 waiting, skipped 3 terminal, refused 1 run
 
 **Opportunity 14 [shipped 2026-05-31] — Canonical-pipeline completion: `test-engineer` step + `test-runner` upgrade + chain_template wiring.** *(Beads: epic `unitAI-sfwe1`, design canon `docs/design/chain-templates.md` §2, formula integration `unitAI-f9kku`.)*
 
-**Problem today.** The current canonical pipeline (already in production via `using-specialists-v3`) runs `executor → code-sanity → obligations-scanner → reviewer` for production diffs. But there is a precise gap between the writer and `code-sanity`: nobody turns a production diff into the right behavioral tests, smoke/E2E checks, and telemetry assertions before the reviewer sees it. The executor is busy implementing; `test-runner` only executes. As a result, autonomous chains repeatedly ship code whose test/log/telemetry contract was never validated against the actual diff — the reviewer either gives a false PASS (no evidence to gate on) or a noisy PARTIAL (asking the operator to fill the gap manually).
+**Problem today.** The current canonical pipeline (already in production via `using-specialists`) runs `executor → code-sanity → obligations-scanner → reviewer` for production diffs. But there is a precise gap between the writer and `code-sanity`: nobody turns a production diff into the right behavioral tests, smoke/E2E checks, and telemetry assertions before the reviewer sees it. The executor is busy implementing; `test-runner` only executes. As a result, autonomous chains repeatedly ship code whose test/log/telemetry contract was never validated against the actual diff — the reviewer either gives a false PASS (no evidence to gate on) or a noisy PARTIAL (asking the operator to fill the gap manually).
 
 **Patch.** Two specialist additions/upgrades plus a chain_template formula pass that completes the canonical pipeline:
 
@@ -503,7 +503,7 @@ The fusion is architecturally clean: `reviewer.specialist.json` already declared
 **Companion enforcement.**
 
 - **Reviewer Release Checklist** (canon §2.6 already updated): three seconder lines (`scope_verdict`, `quality_verdict`, `overall_verdict`). Reviewer cannot PASS without an established `seconder.overall_verdict: PASS` at medium+.
-- **`using-specialists-v3` + `v4` SKILL docs**: teach the canonical pipeline including `seconder` step; document dual-verdict semantics + failure routing per dimension; cross-reference canon §2.3.
+- **`using-specialists` + `v4` SKILL docs**: teach the canonical pipeline including `seconder` step; document dual-verdict semantics + failure routing per dimension; cross-reference canon §2.3.
 - **Smoke/eval** (`unitAI-o7j1a` adapted): empirically prove that an off-scope writer dispatch produces `seconder.scope_verdict: FAIL` and blocks `test-engineer` from firing.
 
 **Cost: ~3 E-D-E (~half-day wall-clock auto-mode), parallelizable.** seconder spec authoring (inherit + extend code-sanity, 1 E-D-E) + reviewer prompt refactor (0.5 E-D-E) + formula integration (folds into f9kku, ~0 marginal since code-sanity → seconder is a string swap) + skill doc update (0.5 E-D-E) + eval (0.5 E-D-E) + optional mandatory rule (0.5 E-D-E).
@@ -720,7 +720,7 @@ PASS → `next: sp merge forge-eorh.48 — chain ready`. PARTIAL → `next: sp r
 
 **[adjusted: R5 dedup]** The last check IS the reviewer-specific R5 — it lives here, once. §7's R5 references this row rather than restating it. This is the data-loss class, hence hard-refuse not warn.
 
-**[2026-07-03 addition — draft-bead promotion gate, shipped as a doc-only bridge.]** The `contract:draft`/`contract:ready` HARD-REFUSE row above is **not yet implemented as an `sp run` check** — it exists today only as orchestrator discipline, taught in `using-specialists-v3` (rule #15 + "Draft Beads And The Promotion Gate"), `planning` ("Draft capture mode"), `using-xtrm` (two Trigger Patterns rows), and CLAUDE.md/AGENTS.md (new Dispatch gate row, marked explicitly "bridge — discipline only, not yet hook-enforced"). It reuses the existing `bd state`/`bd set-state` primitive (see the "Existing bd surface inventory" table above — the same row already flagged this primitive as under-used) rather than inventing a new schema field, per this document's own discipline. **What roadmap implementation must still build:** the real `run.ts` pre-dispatch check — `bd state <id> contract`, hard-refuse when `draft` or unset, same code path as the C1 cwd-mismatch check on the row above it. Until that lands, a session that skips the doc-taught discipline has no structural backstop; track this explicitly as unfinished work when Phase 3 (Naming, conventions, environment) or §5.3's implementation lands, not as something already closed by the doc changes.
+**[2026-07-03 addition — draft-bead promotion gate, shipped as a doc-only bridge.]** The `contract:draft`/`contract:ready` HARD-REFUSE row above is **not yet implemented as an `sp run` check** — it exists today only as orchestrator discipline, taught in `using-specialists` (rule #15 + "Draft Beads And The Promotion Gate"), `planning` ("Draft capture mode"), `using-xtrm` (two Trigger Patterns rows), and CLAUDE.md/AGENTS.md (new Dispatch gate row, marked explicitly "bridge — discipline only, not yet hook-enforced"). It reuses the existing `bd state`/`bd set-state` primitive (see the "Existing bd surface inventory" table above — the same row already flagged this primitive as under-used) rather than inventing a new schema field, per this document's own discipline. **What roadmap implementation must still build:** the real `run.ts` pre-dispatch check — `bd state <id> contract`, hard-refuse when `draft` or unset, same code path as the C1 cwd-mismatch check on the row above it. Until that lands, a session that skips the doc-taught discipline has no structural backstop; track this explicitly as unfinished work when Phase 3 (Naming, conventions, environment) or §5.3's implementation lands, not as something already closed by the doc changes.
 
 ### 5.4 `sp chain <bead>` CLI dashboard view
 
@@ -893,7 +893,7 @@ Everything below this phase assumes Phase 0 has shipped. Without it, Phase 2 Pas
 | 0.b | Edit `config/specialists/planner.specialist.json` — extend `output_schema` with `recommended_template: enum(<15 formula names> \| 'on-the-run')`; validated at runtime against `bd formula list` (D26 a) | 0.3d | `jq` shows new enum; `sp validate planner` passes |
 | 0.c.1 | **Create canonical `config/skills/planning/SKILL.md` (does not exist today — only `.xtrm/skills/default/planning/SKILL.md` deployed mirror, 531 lines, Phases 1-6).** Add the **7 missing sections** identified by 2026-05-31 audit: (1) Pass-2 `recommended_template` annotation (D26 b core deliverable); (2) chain-template catalog enum with when-to-use briefs (15 templates, refs `chain-templates.md` §3.1-§3.15); (3) contract-creation discipline (D29 — CoT prefill in `<thinking>` tags, 2 worked + 1 anti-example per contract type, critique-before-commit premortem-style); (4) XML semantic structure (D30/Opp 12 — `<change-contract>` for root, `<step-contract>` for step; concrete shape with `<problem>`/`<scope>/<path>`/`<non-goals>`/`<validation>/<criterion>`/`<acceptance>`); (5) memory-recall integration (D27/Opp 11 — `bd memories <keyword>` BEFORE planning, `bd recall <key>` for payloads); (6) SCRUTINY-aware composition (Opp 16 — planner picks tier per scope/risk surface; canon §2.2 auto-escalation table; planner sets floor, reviewer can only escalate); (7) bd dep typed-edges navigation (D28 absorbed — full `--type` vocabulary: validates / informs / discovered-from / parent-child / related / supersedes; worked-template tables). | 1.0d | All 7 sections present + `sp validate planner` reads the new file via `skills.paths` |
 | 0.c.2 | **Cross-repo mirror to `~/dev/xtrm-tools`** — propagate canonical to xtrm-tools update pipeline so `xt update --apply` ships the new content to consumer projects. Requires `npm link` symlink + revendor + 2-pass `xt update --apply` per memory `xtrm-tools-skill-propagation-requires-npm-link-2026-05-23`. Verify identical SHA in ≥2 consumer repos. | 0.5d | `diff -q ~/projects/<repo>/.xtrm/skills/default/planning/SKILL.md ~/dev/specialists/config/skills/planning/SKILL.md` returns identical |
-| 0.d | Verify `/using-specialists-v3` still teaches the manual-chain-discipline + Iron pipeline + manual git per CLAUDE.md rule #9 that holds Phase 1 execution until Opp 4+10 land | 0.1d | Skim §"Orchestration Discipline" + §"Chain Management" sections |
+| 0.d | Verify `/using-specialists` still teaches the manual-chain-discipline + Iron pipeline + manual git per CLAUDE.md rule #9 that holds Phase 1 execution until Opp 4+10 land | 0.1d | Skim §"Orchestration Discipline" + §"Chain Management" sections |
 | 0.e | Smoke: dispatch planner on a vacuum bead (just a title) → confirm `recommended_template` field appears in output_schema-validated output | 0.2d | `sp run planner --bead <test> --json` shows the field; resolved chain pour respects template-declared scrutiny floor |
 
 **Why Phase 0 is bootstrap, not Phase 3:** D26 was originally Phase 3 row 11b because the operator could in principle hand-edit it any time. But Phase 2 Pass-2 (planner annotation of `recommended_template`) **cannot run without D26 shipped**. Putting D26 inside Phase 3 created a circular dependency: planning Phase 2 produces the bd board that includes Phase 3 work that planning Phase 2 needs. The fix is sequencing, not redesign.
@@ -943,18 +943,18 @@ After Phase 0: the operator has the chain templates installed, the planner knows
 |---|---|---|---|
 | 17 | bd auto-stage + hooksPath cases + dep/migration verify | §6 / §0 #6 | **`xtrm-h9hqg`** ✓ done (CLOSED 2026-05-27 per D25) |
 | 18 | Orphan worktree cleanup (B-A4), test excludes (B-A5), osv wrapper (B-A6) | §6 | friction-audit-side (~1d) |
-| 19 | `sp merge` / `sp epic merge` / `sp finalize` rework | §5.5 | **NEW epic `unitAI-lyh1b` filed 2026-05-31 as kj651 child** — supersedes the original "dirty-index diagnostic" scope (D18 runway recalibration) with a fuller rework: structured failure envelopes, conflict-recovery paths, auto-rebase suggestion, soak across 3 repos to remove the `using-specialists-v3` rule #9 prohibition. Decomposition into child beads by planner Pass-1. |
+| 19 | `sp merge` / `sp epic merge` / `sp finalize` rework | §5.5 | **NEW epic `unitAI-lyh1b` filed 2026-05-31 as kj651 child** — supersedes the original "dirty-index diagnostic" scope (D18 runway recalibration) with a fuller rework: structured failure envelopes, conflict-recovery paths, auto-rebase suggestion, soak across 3 repos to remove the `using-specialists` rule #9 prohibition. Decomposition into child beads by planner Pass-1. |
 | 20 | `xt init` auto-runs the bootstrap skill on new repos (per D19) | §6 | xtrm-tools (~0.5d) |
 
 ### Phase 6 — Skills revamp: `using-specialists-v4` as new canonical (~2 days)
 
-The operator-facing skills (`using-specialists-v3`, `using-specialists-auto`) currently teach the pre-roadmap discipline: `--bead` + `--worktree` / `--job` dispatch, manual chain stitching, Iron pipeline as convention, manual git per rule #9. After Phases 1–5 ship, the discipline has fundamentally changed — `--chain <molecule-id>` is the single dispatch verb, `sp chain review/approve/insert` is the composition gate, step-bead conventions are atomic with `kind:step` as truth, R-checks fire at dispatch, the new mandatory rule replaces auto-injection, the chain-template catalog is live. **This is a revamp, not a patch.** v3 was built for the pre-roadmap world; trying to patch it in-place produces contradictory text where every section disagrees with the next. v4 is the clean canonical successor.
+The operator-facing skills (`using-specialists`, `using-specialists-auto`) currently teach the pre-roadmap discipline: `--bead` + `--worktree` / `--job` dispatch, manual chain stitching, Iron pipeline as convention, manual git per rule #9. After Phases 1–5 ship, the discipline has fundamentally changed — `--chain <molecule-id>` is the single dispatch verb, `sp chain review/approve/insert` is the composition gate, step-bead conventions are atomic with `kind:step` as truth, R-checks fire at dispatch, the new mandatory rule replaces auto-injection, the chain-template catalog is live. **This is a revamp, not a patch.** v3 was built for the pre-roadmap world; trying to patch it in-place produces contradictory text where every section disagrees with the next. v4 is the clean canonical successor.
 
 | # | Item | Source | Cost |
 |---|---|---|---|
 | 21 | **Create `config/skills/using-specialists-v4/SKILL.md`** as the new canonical operator-facing skill, taught from scratch around the shipped surfaces: `--chain <molecule-id>` as the only dispatch verb (Opp 10); `sp chain review/approve/insert` as composition gate (Opp 4); `bd mol pour` + 13 chain templates as the resolved-shape source (§13); `kind:step` label-as-truth for step beads (Opp 5/D20); atomic role→edge wiring via `sp chain wire-edges` post-pour helper; R-check behavior per §7 (R3/R6/R7 hard-refuse; R1/R2/R5 retired with `--job`); pull-not-push memory recall via the new mandatory rule (Opp 11/D27) — no more bd-prime / .xtrm/memory.md auto-dump; `sp epic` as decorated reader-only surface (§12); manual git per CLAUDE.md rule #9 remains canonical (sp merge / sp epic merge dropped). Mark frontmatter `status: canonical (post-roadmap)`. | §11.1 D28 | 1d |
 | 22 | **Refresh `config/skills/using-specialists-auto/SKILL.md`** to mirror v4 in the auto-orchestration mode; explicitly call out the new smoke-checkpoint cadence (each phase's checkpoint set is the auto-mode validation gate); teach the "eat-your-own-dogfood as it ships" discipline. | §11.1 D28 | 0.5d |
-| 23 | **Freeze `config/skills/using-specialists-v3/SKILL.md`** as legacy reference. Prepend a frontmatter banner: `status: legacy — superseded by using-specialists-v4 as of <commit>; preserved for historical reference and for any cold-start sessions that haven't migrated`. Do NOT rewrite v3 in place — patching v3 produces contradictory text where new and old surfaces collide. v3 stays as the pre-roadmap snapshot. Inside-v4 forward-looking section ("Future surfaces") notes channels v0 + substrate concepts as *coming, not active* — so operators know what to expect when those land, without v4 itself being gated on them. | §11.1 D28 | 0.5d |
+| 23 | **Freeze `config/skills/using-specialists/SKILL.md`** as legacy reference. Prepend a frontmatter banner: `status: legacy — superseded by using-specialists-v4 as of <commit>; preserved for historical reference and for any cold-start sessions that haven't migrated`. Do NOT rewrite v3 in place — patching v3 produces contradictory text where new and old surfaces collide. v3 stays as the pre-roadmap snapshot. Inside-v4 forward-looking section ("Future surfaces") notes channels v0 + substrate concepts as *coming, not active* — so operators know what to expect when those land, without v4 itself being gated on them. | §11.1 D28 | 0.5d |
 
 **Why v4 is canonical-now, not channels-gated:** the 11 opportunities ship in ~16 days (Phases 0–5); channels v0 and substrate landing are months out and outside this roadmap. Gating v4 on channels would leave the operator with a stale v3 teaching dead surfaces (`--worktree`/`--job`/raw `--bead`) for months. v4 = canonical for what shipped. Channels/substrate-aware surfaces live as a clearly-marked "Future surfaces" section inside v4 (or as a future `using-specialists-v5` when channels v0 ships) — they do not block v4's release.
 

package/docs/design/xt-pi-role-pi-flag-passthrough.md

@@ -0,0 +1,174 @@
+# `xt pi --role` ↔ `pi` runtime flag passthrough
+
+**Context:** `xt pi --role <name>` (xtrm-tools/core PR #362, branch
+`feature/xtrm-yd1p1-pi-role-launcher`) launches a `pi` interactive session in
+a worktree. The current implementation forwards **zero flags** to the pi
+subprocess (`cli/src/utils/worktree-session.ts:373`):
+
+```ts
+const runtimeCmd = runtime === 'claude' ? 'claude' : 'pi';
+const runtimeArgs = runtime === 'claude' ? ['--dangerously-skip-permissions'] : [];
+const launchResult = spawnSync(runtimeCmd, runtimeArgs, { cwd: worktreePath, stdio: 'inherit' });
+```
+
+xt pi's own flags today: `[name]`, `--role <name>`, `--bead <id>`, `--no-attach`.
+Everything `pi` accepts (`pi --help`) is currently unreachable through xt.
+
+This doc rules pi's ~30 CLI flags **passthrough / xt-owned / skip** for `xt pi --role`.
+
+Coordinated with xt-design.3, epic `xtmux-2i5`.
+
+## Recommended shape
+
+**Adopt the `--` passthrough convention.** Anything after `--` on the `xt pi`
+command line is forwarded verbatim as pi argv:
+
+```bash
+xt pi --role chain-coordinator --bead unitAI-2i5 -- --thinking high --no-extensions -e ./local-ext.js
+```
+
+Rationale: pi's flag surface is large, changes independently, and includes
+extension-registered flags xt can't enumerate ahead of time (`--gitnexus-cmd`,
+`--mcp-config`, `--plan`, …). Enumerating each is a maintenance treadmill.
+The `--` convention gives full parity with one code change, zero drift.
+
+Individual xt flags (below) are reserved for pi flags xt itself needs to
+*read or override* — e.g. session naming, which xt derives from the branch.
+
+## Passthrough table
+
+Legend:
+- **passthrough** — forward as-is after `--` (no xt interpretation)
+- **xt-owned** — xt sets or overrides these; user cannot pass them
+- **surface** — worth a first-class xt flag (short-form convenience or
+  interpretation needed before pi launches)
+- **skip** — not meaningful under `xt pi --role`
+
+### Runtime shape
+
+| pi flag | Verdict | Rationale |
+|---|---|---|
+| `--provider <name>` | passthrough | Runtime shape. `pi --model provider/id` also handles this, but explicit form works. |
+| `--model <pattern>` | **surface** as `--model` | High-value parity flag. Also match `sp run --model`. Support `:thinking` shorthand pi already parses. |
+| `--api-key <key>` | passthrough | Rare; env vars usually suffice. Don't surface (secret on cmdline). |
+| `--thinking <level>` | **surface** as `--thinking` | Runtime shape and highest-frequency override. Match pi's levels: off/minimal/low/medium/high/xhigh. |
+| `--models <patterns>` | passthrough | Ctrl+P cycling config. Not critical to surface. |
+
+### Session lifecycle
+
+| pi flag | Verdict | Rationale |
+|---|---|---|
+| `--continue, -c` | passthrough | Meaningful when re-entering an existing xt worktree; user knows the intent. |
+| `--resume, -r` | passthrough | Same. |
+| `--session <path\|id>` | passthrough | Advanced use. Passthrough sufficient. |
+| `--session-id <id>` | passthrough | Same. |
+| `--fork <path\|id>` | passthrough | Same. |
+| `--session-dir <dir>` | **xt-owned** | xt sets `PI_CODING_AGENT_SESSION_DIR` (or equivalent) to a worktree-scoped path if desired. Don't let users override — breaks session locality. |
+| `--no-session` | passthrough | Ephemeral run inside a persistent worktree is a valid user choice. |
+| `--name, -n <name>` | **xt-owned** | xt derives the display name from `[name]` positional / branch slug. Overriding here fragments observability. |
+
+### Tools / extensions / skills
+
+| pi flag | Verdict | Rationale |
+|---|---|---|
+| `--no-tools, -nt` | passthrough | Read-only mode; user choice. |
+| `--no-builtin-tools, -nbt` | passthrough | Same. |
+| `--tools, -t <list>` | passthrough | Allowlist. Same. |
+| `--exclude-tools, -xt <list>` | passthrough | Denylist. Same. |
+| `--extension, -e <path>` | passthrough | Load explicit extension file. Multi-use. Passthrough. |
+| `--no-extensions, -ne` | passthrough | Disable discovery. Passthrough. |
+| `--skill <path>` | passthrough | Same as `-e` for skills. |
+| `--no-skills, -ns` | passthrough | Same. |
+| `--prompt-template <path>` | passthrough | Same. |
+| `--no-prompt-templates, -np` | passthrough | Same. |
+| `--theme <path>` | passthrough | Cosmetic. |
+| `--no-themes` | passthrough | Same. |
+| `--no-context-files, -nc` | passthrough | Disable AGENTS.md/CLAUDE.md load. Legitimate override. |
+
+### System prompt
+
+| pi flag | Verdict | Rationale |
+|---|---|---|
+| `--system-prompt <text>` | **xt-owned when `--role` set** | The role's `specialist.prompt.system` is already the system prompt (see `resolveRole` in worktree-session.ts). Passing this again would clobber the role. Reject with an error when `--role` is present; passthrough when it isn't. |
+| `--append-system-prompt <text>` | passthrough | Additive, not clobbering. Safe alongside `--role`. Multi-use. |
+
+### Startup / mode
+
+| pi flag | Verdict | Rationale |
+|---|---|---|
+| `--mode <mode>` | passthrough | text/json/rpc — user knows intent. |
+| `--print, -p` | **skip / warn** | Non-interactive mode contradicts `xt pi`'s interactive-tmux design. Warn and refuse (use `sp run` for one-shot). |
+| `--approve, -a` | passthrough | Trust project files this run. |
+| `--no-approve, -na` | passthrough | Same. |
+| `--offline` | passthrough | `PI_OFFLINE=1` alternative. |
+| `--verbose` | passthrough | Debug aid. |
+
+### Introspection / one-shot commands
+
+| pi flag | Verdict | Rationale |
+|---|---|---|
+| `--list-models [search]` | **skip** | Not a session — no worktree needed. User runs `pi --list-models` directly. |
+| `--export <file>` | **skip** | One-shot session-to-HTML. Not an xt workflow. |
+| `--help, -h` | **skip** | xt owns its own `--help`. |
+| `--version, -v` | **skip** | Use `xt pi status` (already exists per pi.ts). |
+
+### Subcommands (`pi install`, `pi update`, `pi list`, `pi config`)
+
+| Subcommand | Verdict | Rationale |
+|---|---|---|
+| `pi install / remove / uninstall / update / list / config` | **skip** | Not launch flows. User runs `pi <cmd>` directly outside a worktree. |
+
+### Extension-registered flags
+
+| Flag | Verdict | Rationale |
+|---|---|---|
+| `--gitnexus-cmd <value>` | passthrough | Registered by extension. Cannot enumerate ahead of time. |
+| `--mcp-config <value>` | passthrough | Same. |
+| Any future extension flag | passthrough | Same. Justifies the `--` convention as primary path. |
+
+## Summary
+
+**Primary path — do this first:**
+Implement `--` passthrough in `launchWorktreeSession`. Every flag pi supports
+(current or future, first-party or extension-registered) becomes reachable
+with zero per-flag maintenance.
+
+**Surface as first-class xt flags** (short-form convenience for the two most
+common overrides):
+- `--model <pattern>` — passes to pi as `--model`
+- `--thinking <level>` — passes to pi as `--thinking`
+
+**xt-owned (reject or override user attempts):**
+- `--session-dir` — xt controls session locality
+- `--name` — xt derives from branch slug
+- `--system-prompt` — clobbers `--role`'s specialist prompt when both set (error)
+
+**Skip / warn:**
+- `--print, -p` — non-interactive contradicts xt pi's design
+- `--list-models`, `--export`, `--help`, `--version`, subcommands — not launch flows
+
+**Everything else** — passthrough via `--`.
+
+## Implementation sketch (~10 lines)
+
+```ts
+// worktree-session.ts, near line 373
+const passthroughIdx = process.argv.indexOf('--');
+const passthroughArgs = passthroughIdx >= 0 ? process.argv.slice(passthroughIdx + 1) : [];
+
+// commander already strips xt-owned flags; combine with surfaced overrides
+const piArgs: string[] = [];
+if (opts.model) piArgs.push('--model', opts.model);
+if (opts.thinking) piArgs.push('--thinking', opts.thinking);
+piArgs.push(...passthroughArgs);
+
+// Guard: reject conflicts before spawn
+if (roleName && passthroughArgs.includes('--system-prompt')) {
+    console.error(kleur.red('\n  ✗ --system-prompt conflicts with --role (role owns the system prompt). Use --append-system-prompt instead.\n'));
+    process.exit(1);
+}
+
+const runtimeArgs = runtime === 'claude' ? ['--dangerously-skip-permissions'] : piArgs;
+```
+
+Decision doc only — no implementation in this PR.

package/docs/skills.md

@@ -36,26 +36,17 @@ User-authored skills belong in the user/active layer used by the local agent set
 
 The package ships the source copies under `config/skills/`. The active `.xtrm/skills/...` files in a project may be refreshed by xtrm-tools.
 
-### `using-specialists-v3`
+### `using-specialists`
 
-Location: `config/skills/using-specialists-v3/SKILL.md`
+Location: `config/skills/using-specialists/SKILL.md`
 
-Canonical orchestration doctrine for substantial tracked work. It covers bead contracts, dependency graph shape, conflict-cluster mapping, advisory passes, reviewer rebuttal, debugger-restitch, E2E smoke phases, monitoring cadence, `sp merge` / `sp epic merge`, and session-end handoff. Use this for multi-step implementation, debugging, reviews, docs sync planning, and specialist orchestration.
+Canonical orchestration doctrine for substantial tracked work. It covers bead contracts, dependency graph shape, conflict-cluster mapping, advisory passes, reviewer rebuttal, debugger-restitch, E2E smoke phases, monitoring cadence, manual publication, and session-end handoff. Use this for multi-step implementation, debugging, reviews, docs sync planning, and specialist orchestration.
 
 ### `using-specialists-auto`
 
 Location: `config/skills/using-specialists-auto/SKILL.md`
 
-Autonomous/offline orchestration overlay. It delegates shared mechanics to `using-specialists-v3` and adds auto-mode pacing, per-item loop shape, escalation triggers, and unattended-run discipline.
-
-### `using-specialists-v2` / `using-specialists`
-
-Locations:
-
-- `config/skills/using-specialists-v2/SKILL.md`
-- `config/skills/using-specialists/SKILL.md`
-
-Older orchestration references retained for compatibility and migration context. Prefer `using-specialists-v3` for current guidance.
+Autonomous/offline orchestration overlay. It delegates shared mechanics to `using-specialists` and adds auto-mode pacing, per-item loop shape, escalation triggers, and unattended-run discipline.
 
 ### `sync-docs`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "3.18.1",
+  "version": "3.18.3",
   "description": "OmniSpecialist — 7-tool MCP orchestration layer powered by the Specialist System. Discover and execute .specialist.yaml files across project/user/system scopes via pi.",
   "main": "dist/index.js",
   "types": "dist/types/lib.d.ts",