xtrm-tools 0.7.10 → 0.7.12

package/.xtrm/skills/default/update-specialists/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: update-specialists
+description: >
+  Reconcile a project with current canonical specialists install state.
+  Use this skill when a user says "update specialists", "specialists is broken",
+  "sp is out of date", "hooks not firing", "skills not loading after update",
+  or when drift is detected in installed specialists config, hooks, jobs, DB,
+  extensions, or worktree cleanup.
+version: 1.0
+synced_at: 00000000
+---
+
+# update-specialists
+
+Bring specialists install back to canonical state. Detect drift, apply targeted
+fixes, then verify with `sp doctor`.
+
+## Canonical State
+
+Check each item explicitly. This is what a healthy specialists-initialized project
+looks like.
+
+### Specialists configs
+
+| Check | Expected value |
+|-------|----------------|
+| `.specialists/default/*.specialist.json` | JSON-first specialist configs present |
+| `metadata.name` | Matches filename stem |
+| `metadata.version` | Valid semver string |
+| `metadata.description` | Present |
+| `metadata.category` | Present |
+| `execution.model` | Present and pingable |
+| `execution.fallback_model` | Present, different provider from primary |
+| `execution.permission_required` | Valid enum |
+| `execution.extensions.serena` | Present when skill needs opt-out or default true |
+| `execution.extensions.gitnexus` | Present when skill needs opt-out or default true |
+| `execution.interactive` | Matches intended keep-alive behavior |
+
+### Hooks wiring
+
+| Check | Expected value |
+|-------|----------------|
+| `.claude/settings.json` | Has hook entries for active events |
+| Hook events | At minimum: `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop` |
+| Hook paths | Point at specialists runtime hook scripts, not stale xtrm-only paths |
+| Hook format | Matches project's installed settings format and loads cleanly |
+
+### CLI reachability
+
+| Check | Expected value |
+|-------|----------------|
+| `sp` command | On PATH and runs |
+| `specialists` command | On PATH and runs |
+| Version compatibility | `sp doctor` reports matching runtime / install state |
+| Command surface | `sp doctor`, `sp init`, `sp clean`, `sp status` available |
+
+### Jobs and runtime dirs
+
+| Check | Expected value |
+|-------|----------------|
+| `.specialists/jobs/` | Exists |
+| `.specialists/ready/` | Exists if used by runtime |
+| `.specialists/default/` | Canonical install copy present |
+| Orphaned worktrees | None under `.worktrees/` |
+| Worktree ownership | No stale entries for deleted jobs |
+
+### SQLite / observability
+
+| Check | Expected value |
+|-------|----------------|
+| specialists DB | Opens cleanly |
+| Schema version | Matches runtime expectation |
+| WAL / busy timeout settings | Present when runtime uses SQLite |
+| Corruption / lock errors | None in `sp doctor` |
+
+### Pi extensions
+
+| Check | Expected value |
+|-------|----------------|
+| `quality-gates` | Registered if project uses quality gates |
+| `pi-gitnexus` | Registered when GitNexus integration is expected |
+| `pi-serena-tools` | Registered when Serena integration is expected |
+| Extension paths | Resolve from installed project, not stale workspace copies |
+
+## Detection
+
+Run these in order. Report which checks pass and which drift.
+
+```bash
+# 1. Primary health check
+sp doctor
+
+# 2. Runtime status
+sp status
+
+# 3. Config shape
+find .specialists/default -maxdepth 1 -name '*.specialist.json' -print
+
+# 4. Validate specialist JSON files
+node -e "const fs=require('fs'); const path=require('path'); const dir='.specialists/default'; for (const file of fs.readdirSync(dir)) { if (!file.endsWith('.specialist.json')) continue; const data=JSON.parse(fs.readFileSync(path.join(dir,file),'utf8')); const s=data.specialist||data; const m=s.metadata||{}; const e=s.execution||{}; const missing=[]; for (const key of ['name','version','description','category']) if (!m[key]) missing.push('metadata.'+key); for (const key of ['model','fallback_model','permission_required']) if (!e[key]) missing.push('execution.'+key); if (missing.length) console.log(file+': MISSING '+missing.join(', ')); if (m.name && m.name !== file.replace(/\.specialist\.json$/, '')) console.log(file+': NAME MISMATCH '+m.name); }"
+
+# 5. Hooks wiring
+node -e "const fs=require('fs'); const p='.claude/settings.json'; if (fs.existsSync(p)) { const s=JSON.parse(fs.readFileSync(p,'utf8')); console.log(JSON.stringify(s.hooks ?? s, null, 2)); } else { console.log('MISSING .claude/settings.json'); }"
+
+# 6. Command availability
+command -v sp
+command -v specialists
+sp doctor --json 2>/dev/null || true
+
+# 7. Jobs and worktrees
+ls -1 .specialists/jobs 2>/dev/null || true
+find .worktrees -maxdepth 2 -mindepth 1 -type d 2>/dev/null || true
+
+# 8. Extension registration
+node -e "const fs=require('fs'); const p='.pi/settings.json'; if (fs.existsSync(p)) console.log(JSON.stringify(JSON.parse(fs.readFileSync(p,'utf8')).skills ?? JSON.parse(fs.readFileSync(p,'utf8')).extensions ?? {}, null, 2)); else console.log('MISSING .pi/settings.json')"
+```
+
+## Drift -> Fix Mapping
+
+Use targeted fixes first. Escalate to full sync only if needed.
+
+| Drift | Fix |
+|-------|-----|
+| Specialist JSON missing required fields | `sp edit <name> ...` or regenerate via `sp init --sync-skills` |
+| Specialist JSON schema mismatch | `sp init --sync-skills` |
+| Hooks missing or stale | `sp init --sync-hooks` if available, otherwise `sp init --sync-skills` or `sp init -y` |
+| `sp` / `specialists` missing from PATH | Reinstall / re-bootstrap specialists runtime |
+| Job dir missing | `sp init -y` |
+| Orphaned `.worktrees/` entries | `specialists clean` |
+| SQLite schema/version mismatch | `sp doctor` first, then `sp init --sync-skills` or runtime migration command |
+| Pi extensions missing | `sp init --sync-skills` or reinstall extension registration |
+| Hook config format stale | `sp init -y` |
+| Unknown manual drift | Stop, inspect, then apply user-approved fix |
+
+## Remediation
+
+### Fix: Specialist configs drifted
+
+If `sp doctor` or JSON validation shows missing fields, wrong names, or schema
+mismatch:
+
+```bash
+sp init --sync-skills
+```
+
+If one specialist needs a small repair and `sp edit` supports it, prefer that over
+full sync.
+
+### Fix: Hooks not firing
+
+If hooks are missing, wrong events, or stale script paths:
+
+```bash
+sp init -y
+```
+
+If runtime exposes a narrower hook sync command, prefer it. Use full init only
+when hook-only sync is not enough.
+
+### Fix: CLI not reachable
+
+If `sp` or `specialists` is missing or incompatible:
+
+```bash
+sp doctor
+```
+
+If doctor confirms install drift, reinstall or re-bootstrap specialists runtime.
+Do not guess at file edits when command surface itself is broken.
+
+### Fix: Job dirs or worktree GC drift
+
+If jobs exist without owners, worktrees are orphaned, or cleanup state is stale:
+
+```bash
+specialists clean
+```
+
+Then re-run `sp doctor`.
+
+### Fix: SQLite schema drift
+
+If doctor reports DB version mismatch or recovery issue:
+
+1. Run `sp doctor` and capture exact schema error.
+2. Apply runtime migration command if available.
+3. If no automated migration exists, flag manual intervention.
+
+### Fix: Pi extensions not registered
+
+If `quality-gates`, `pi-gitnexus`, or `pi-serena-tools` are missing:
+
+```bash
+sp init --sync-skills
+```
+
+If project uses different extension packaging, re-run install step that writes
+`.pi/settings.json`.
+
+## Verification
+
+After fixes, confirm canonical state restored.
+
+```bash
+sp doctor
+sp status
+
+command -v sp
+command -v specialists
+
+node -e "const fs=require('fs'); const p='.claude/settings.json'; const s=JSON.parse(fs.readFileSync(p,'utf8')); console.log(Boolean(s.hooks || Object.keys(s).length))"
+```
+
+Expected outcome:
+- `sp doctor` clean
+- `sp status` no drift / no repair hints
+- `sp` and `specialists` reachable
+- specialist JSON files valid
+- hooks present on required events
+- no orphaned worktrees
+- SQLite state healthy
+
+## Manual Intervention
+
+Flag these when automatic fix is unsafe or impossible:
+
+- `sp doctor` reports corrupt DB / unreadable SQLite file
+- command surface missing because install itself is broken
+- hook scripts absent from repo and cannot be regenerated
+- schema mismatch with no available migration path
+- worktree cleanup would remove user changes
+- extensions required by project are not installed at package level
+
+When manual intervention needed, report:
+1. exact drift
+2. exact command tried
+3. why auto-fix stopped
+4. next safe operator action
+
+## User Summary Format
+
+After detection + remediation, answer with compact status:
+
+```text
+## specialists update complete
+
+✓ sp doctor clean
+✓ specialist configs valid
+✓ hooks wired
+✓ CLI reachable
+✓ jobs/worktrees clean
+✓ SQLite healthy
+✓ extensions registered
+
+[manual items, if any]
+```

package/.xtrm/skills/default/update-xt/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: update-xt
+description: >
+  Update an xtrm-initialized project to match the current canonical install state.
+  Use this skill whenever the user asks to update, upgrade, repair, or re-sync xtrm
+  in a project — or when they say something like "xt is out of date", "skills aren't
+  loading", "hooks aren't firing", "the install looks wrong", or "I just pulled new
+  xtrm changes". Also triggers when the agent detects stale paths like
+  .claude/skills → active/claude (old structure) or .pi/settings.json pointing to
+  active/pi (old structure). Proactively suggest running this skill after any
+  xtrm-tools upgrade.
+---
+
+# update-xt
+
+Reconcile a project's xtrm installation against the current canonical state. Detect
+drift, apply targeted fixes, verify everything is wired correctly.
+
+## Canonical State (current)
+
+This is what a correctly installed project looks like. Check each item.
+
+### Skills wiring
+
+| Check | Expected value |
+|-------|----------------|
+| `.claude/skills` symlink target | `../.xtrm/skills/active` |
+| `.xtrm/skills/active/` | Flat directory of symlinks to `../default/<skill>` |
+| `active/pi/` subdirectory | Must NOT exist (stale — old runtime split) |
+| `active/claude/` subdirectory | Must NOT exist (stale — old runtime split) |
+| `.pi/settings.json` `.skills` array | Must include `"../.xtrm/skills/active"` |
+| `.pi/settings.json` `.skills` array | Must NOT include `"../.xtrm/skills/active/pi"` (old path) |
+
+### Hooks wiring
+
+| Check | Expected value |
+|-------|----------------|
+| `.claude/settings.json` or `~/.claude/settings.json` | Has `hooks` block with commands containing `/.xtrm/hooks/` paths |
+| Hooks events covered | At minimum: `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop` |
+
+### Project bootstrap
+
+| Check | Expected value |
+|-------|----------------|
+| `.beads/` exists | Yes |
+| `CLAUDE.md` or `AGENTS.md` exists | Yes |
+
+## Detection
+
+Run these in order. Report what passes and what drifts.
+
+```bash
+# 1. High-level status — shows pending syncs
+xt status
+
+# 2. Claude hook wiring
+xt claude status
+
+# 3. Skills symlink
+readlink .claude/skills
+# Expected: ../.xtrm/skills/active
+# Stale: ../.xtrm/skills/active/claude
+
+# 4. Stale runtime subdirs (should return nothing)
+ls .xtrm/skills/active/pi 2>/dev/null && echo "STALE: active/pi exists"
+ls .xtrm/skills/active/claude 2>/dev/null && echo "STALE: active/claude exists"
+
+# 5. Pi settings skills entry
+node -e "const s=require('./.pi/settings.json'); console.log(s.skills)" 2>/dev/null
+# Expected to include: ../.xtrm/skills/active
+# Stale if includes: ../.xtrm/skills/active/pi
+
+# 6. Active view integrity (all entries must be valid symlinks)
+for f in .xtrm/skills/active/*; do [ -L "$f" ] || echo "NOT A SYMLINK: $f"; done
+```
+
+## Remediation
+
+Two commands cover almost all drift. Know which fixes what:
+
+| Command | Fixes |
+|---------|-------|
+| `xt claude install` | Hooks wiring only (settings.json hooks block) |
+| `xt init -y` | Skills symlink, active/ view rebuild, Pi settings, all phases |
+
+### Fix: Skills symlink stale or active/ view wrong
+
+`xt claude install` does NOT rebuild skills. Only `xt init` does (Phase 6b).
+
+```bash
+xt init -y
+```
+
+### Fix: Stale active/pi or active/claude subdirs
+
+`xt init` rebuilds `active/` atomically — it does NOT remove old subdirs left over
+from a previous layout. After `xt init -y` confirms the flat view is working, remove
+the stale dirs manually:
+
+```bash
+rm -rf .xtrm/skills/active/pi
+rm -rf .xtrm/skills/active/claude
+```
+
+Verify flat active/ is intact:
+```bash
+ls .xtrm/skills/active/
+# Should show skill dirs directly (clean-code, deepwiki, ...) — NOT pi/ or claude/ subdirs
+```
+
+### Fix: Hooks not wired
+
+```bash
+xt claude install
+```
+
+Rewires from `.xtrm/config/hooks.json` into `.claude/settings.json`.
+
+### Fix: Pi settings stale path
+
+Covered by `xt init -y`. If you need to target it alone:
+```bash
+xt pi install
+```
+
+### Fix: beads not initialized
+
+```bash
+bd init
+```
+
+## If updating xtrm-tools itself (not a consumer project)
+
+After merging changes to `cli/src/`, the dist must be rebuilt before `xt` picks up
+the new logic. Skipping this causes verification to report stale errors even after
+`xt init` runs.
+
+```bash
+cd cli && npm run build
+xt init -y   # now runs with updated code
+```
+
+## Verification
+
+After all fixes, confirm canonical state is restored:
+
+```bash
+xt claude status
+# Should show: ✓ Claude hooks wired
+# Should show: ✓ claude CLI available
+
+xt status
+# Should show no pending changes (or only optional ones)
+
+readlink .claude/skills
+# Must output: ../.xtrm/skills/active
+
+node -e "const s=require('./.pi/settings.json'); console.log(s.skills.includes('../.xtrm/skills/active'))" 2>/dev/null
+# Must output: true
+```
+
+If `xt status` still shows drift after targeted fixes, run the full sync:
+```bash
+xt init
+```
+
+## Reporting to the user
+
+After completing detection + remediation + verification, give the user a concise
+summary:
+
+```
+## xtrm update complete
+
+✓ .claude/skills → ../.xtrm/skills/active
+✓ active/ view: N skills (flat, all valid symlinks)
+✓ active/pi and active/claude stale dirs: removed
+✓ Hooks wired (X events, Y commands)
+✓ .pi/settings.json skills entry: current
+
+[Any items that could not be auto-fixed, with manual instructions]
+```
+
+If anything could not be fixed automatically (e.g. missing `.pi/settings.json`,
+no beads config), explain the manual step clearly — don't just report failure.