| name | update-specialists |
| description | Reconcile specialists runtime drift and xtrm-managed asset drift across one repo or many. Use this skill when user says "update specialists", "specialists is out of date", "xtrm drift", "skills not updating", "assets out of date", or when operator needs guided refresh of specialists/xtrm state.
|
| version | 2.1 |
| synced_at | 2026-05-05T00:00:00.000Z |
| disable-model-invocation | true |
update-specialists
Interactive operator workflow for the two distribution tracks:
- Category A — specialists runtime / npm-live assets
- specialist definitions
- mandatory rules
- tool catalogs
- node configs
- resolved by
sp from the installed @jaggerxtrm/specialists package unless a repo intentionally overrides them
- Category B — xtrm-managed filesystem assets
- skills under
.xtrm/skills/default/
- hooks under
.xtrm/hooks/default/
- active
.claude/skills, .pi/skills, hook settings, and related registry-managed files
- refreshed by
xt update
Do not collapse these flows. Category A is specialists-owned and uses sp commands. Category B is xtrm-owned and uses xt commands.
No automatic destructive execution. Always summarize first and ask before applying refresh/prune actions.
Quick Decision Tree
- User says specialist configs/rules/catalog/node behavior is stale → run Category A flow.
- User says skills/hooks/Claude/Pi active files are stale → run Category B flow.
- User says update specialists with no detail → run both diagnostics, then present a combined plan.
- User is in many repos → use root discovery and group results by repo.
xt missing → Category A can still run; Category B falls back to install/update guidance.sp missing → tell user to install/upgrade @jaggerxtrm/specialists; do not claim runtime drift is fixed.
Category A — Specialists Runtime / npm-live Flow
A1) Verify package and command surface
Run in the target repo:
sp --version
sp doctor
sp doctor --check-drift
Use specialists instead of sp if the alias is unavailable.
Category A canonical source is the installed @jaggerxtrm/specialists npm package. To update it, upgrade/pin the package version:
npm install -g @jaggerxtrm/specialists@latest
npm install -D @jaggerxtrm/specialists@<version>
Report the installed version and whether the repo is intentionally pinned.
A2) Interpret sp doctor --check-drift
This checks stale .specialists/default/ snapshots against package-canonical assets.
Typical statuses:
| Finding | Meaning | Action |
|---|
| redundant / byte-identical default | Local default snapshot duplicates package canonical | Safe to prune after review |
| diverged default | Local default differs from package canonical | Treat as intentional until operator confirms migration |
| missing package canonical | Installed package or registry is incomplete/stale | Upgrade/reinstall specialists package |
| user overlay | .specialists/user/ custom asset | Preserve; never overwrite automatically |
A3) Prune redundant Category A snapshots
Dry-run first:
sp prune-stale-defaults --dry-run
sp prune-stale-defaults --root <repo>
Only after operator confirmation, prune redundant defaults:
sp prune-stale-defaults --root <repo>
Rules:
- Never prune
.specialists/user/.
- Never overwrite or delete diverged defaults without explicit operator approval.
- If a diverged default should become a customization, move/keep it as user-owned policy and document why.
- If the repo deliberately pins old behavior, leave
.specialists/default/ in place and record the pinned specialists version.
A4) Validate runtime resolution
For specialist definitions and tool policy:
sp list --full
sp config show <specialist> --resolved
For mandatory rules/skills references in custom specialists, verify resolution from package canonical or project override:
sp config show <specialist> --resolved --from-source
Use --from-source only in a specialists source/worktree context where installed dist may lag local source.
Category B — xtrm-managed Filesystem Asset Flow
B1) Discover projects root
Ask for root if user did not name one.
Default order:
- explicit user root,
~/dev,- git-discovered repo root / workspace root,
- current directory as last fallback.
If multiple candidate roots exist, ask which one to use.
B2) Run xtrm doctor
Use:
xt doctor --cwd <root> --json
If xt is unavailable, stop Category B and use fallback guidance below. Do not invent xtrm bulk commands.
B3) Summarize Category B drift
Render a clean table grouped by repo:
| repo | status | drift | missing | mismatched | suggested action |
|---|
Keep focus on operator action, not internal diagnostics.
B4) Ask for confirmation
Offer three paths:
- dry-run only,
- refresh specific repos,
- refresh all repos.
If user names one repo, keep flow narrow and confirm only that repo.
B5) Apply xtrm refresh
Dry-run:
xt update --root <root>
xt update --repo <repo>
Apply:
xt update --apply --root <root>
xt update --apply --repo <repo>
B6) Re-run doctor
Run the same doctor command again after update:
xt doctor --cwd <root> --json
Confirm clean state or reduced-to-intentional drift.
Combined Multi-repo Flow
When the operator asks broadly to "update specialists" across repos:
- Choose projects root.
- For each repo with specialists state:
- run/record Category A status:
sp --version, sp doctor --check-drift if available.
- For each repo with
.xtrm/registry.json:
- run/record Category B status:
xt doctor --cwd <repo> --json.
- Present one combined table:
| repo | specialists pkg | Category A status | Category B status | recommended action |
|---|
Recommended action examples:
- upgrade
@jaggerxtrm/specialists, then re-run sp doctor --check-drift,
- prune redundant
.specialists/default/ snapshots,
- preserve
.specialists/user/ customization,
- run
xt update --repo <repo> --apply,
- no action.
Fallbacks
sp missing
Say Category A cannot be verified until specialists is installed:
npm install -g @jaggerxtrm/specialists@latest
If project policy uses local dev dependency, recommend the project-local package manager command instead.
xt missing
Category A can still be checked with sp. For Category B, tell user:
npm install -g xtrm-tools@latest
xt install
xt doctor --cwd <repo> --json
Do not claim skills/hooks are synced without xt or a valid .xtrm/registry.json.
.xtrm/registry.json missing
Report that xtrm-managed assets cannot be drift-checked in that repo until registry scaffold exists. Suggested action:
xt install
or pull a repo revision that tracks .xtrm/registry.json.
Safety Rules
- Preserve
.specialists/user/ and any user-authored skill/hook layer.
- Treat
.specialists/default/ as compatibility/pinning surface, not normal fresh-repo state.
- Treat
.xtrm/skills/default/ and .xtrm/hooks/default/ as managed output; do not hand-edit as the repair path.
- Prefer dry-run first when more than one repo will change.
- Keep Category A and Category B results separate in the final report.
Output Shape
Use this order:
- root/repo chosen,
- specialists package version and Category A summary,
- xtrm Category B summary,
- combined drift table,
- proposed actions,
- explicit confirmation request,
- commands run,
- post-action verification,
- residual manual work.
Example Operator Loop
Root: ~/dev
repo sp version Category A Category B action
repo-a 3.13.0 redundant defaults: 4 skills drift: 2 prune A + xt update
repo-b 3.12.0 package behind latest in-sync upgrade sp only
repo-c 3.13.0 user overlay only hooks drift: 1 preserve user + xt update
Apply which actions? dry-run / selected repos / all
Verification Checklist
After work:
sp doctor --check-drift clean or reduced to intentional pins/overrides,sp prune-stale-defaults --dry-run shows no redundant defaults unless intentionally retained,sp list --full and selected sp config show <name> --resolved reflect package-live runtime,xt doctor --cwd <root> --json clean or reduced to intentional custom drift,- single-repo case stays single-repo,
- missing-tool paths fall back cleanly.
