xtrm-tools 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -7,13 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-## [0.7.1] - 2026-04-01
+## [0.7.1] - 2026-04-02
 
 ### Added
 - **`docs/skills-tier-architecture.md`**: New reference document covering three-tier skills model (default/optional/user), state.json schema, PACK.json schema, runtime active views, and xt skills CLI commands.
 - **`docs/xtrm-directory.md`**: New reference document for centralized `.xtrm/` directory layout — skills, hooks, extensions, worktrees, reports, registry.json.
+- **`docs/bash-tools.md`**: New reference for specialist bash CLIs (`ghgrep`, `ctx7`, `deepwiki`) including install source, usage examples, and CLI-vs-MCP guidance; README now links and surfaces `ghgrep` under capabilities.
 
 ### Changed
+- **Optional packs install behavior docs**: Updated README + skills docs to reflect that `xt install` now pre-populates `.xtrm/skills/optional/`; packs are activated with `xt skills enable <pack>`.
+- **Pi core resolution path docs**: Updated Pi architecture docs to reflect the new symlink location at `.xtrm/extensions/node_modules/@xtrm/pi-core` (replacing legacy `.pi/node_modules/@xtrm/pi-core`).
+- **Default skills catalog docs**: Added `deepwiki`, `specialists-creator`, and `using-specialists` to default-skill listings in README and skills documentation.
 - **`docs/skills.md`**: Rewritten to cover tier architecture, xt skills CLI, and updated skill catalog (v2.0.0).
 - **`docs/cli-architecture.md`**: Updated skills.ts section — enable/disable/create-pack now fully implemented, added runtime flags documentation (v1.5.0).
 - **`docs/skills-registry-exploration.md`**: Updated implementation status — Phase v0.9 pack lifecycle delivered, enable/disable/create-pack implemented (v1.2.0).

package/README.md

@@ -28,7 +28,7 @@ Native integration with the [specialists](https://github.com/Jaggerxtrm/speciali
 
 ---
 
-**Version 0.5.30** | [Complete Guide](XTRM-GUIDE.md) | [Changelog](CHANGELOG.md)
+**Version 0.7.1** | [Complete Guide](XTRM-GUIDE.md) | [Changelog](CHANGELOG.md)
 
 ---
 
@@ -43,6 +43,7 @@ Native integration with the [specialists](https://github.com/Jaggerxtrm/speciali
 | [docs/pi-extensions.md](docs/pi-extensions.md) | Pi extensions — managed sync, authoring, parity notes |
 | [docs/worktrees.md](docs/worktrees.md) | xt worktrees — `xt claude/pi`, `xt attach`, `xt end`, isolation model |
 | [docs/mcp-servers.md](docs/mcp-servers.md) | MCP servers — gitnexus, github-grep, deepwiki, official plugins |
+| [docs/bash-tools.md](docs/bash-tools.md) | Bash-native specialist CLIs — ghgrep, ctx7, deepwiki |
 | [docs/cli-architecture.md](docs/cli-architecture.md) | CLI internals — install flow, diff/sync engine, config merge |
 | [docs/docs-commands.md](docs/docs-commands.md) | Docs command suite — `show`, `list`, `cross-check`, output modes, drift checks |
 | [docs/project-skills.md](docs/project-skills.md) | Legacy project-skill migration notes and current asset location |
@@ -62,7 +63,7 @@ xtrm init
 
 # Verify
 claude plugin list
-# → xtrm-tools@xtrm-tools  Version: 0.5.30  Status: enabled
+# → xtrm-tools@xtrm-tools  Version: 0.7.1  Status: enabled
 ```
 
 **One-line run:**
@@ -103,7 +104,7 @@ xt merge
 
 ### Skills
 
-Skills are resolved through a three-tier registry in `.xtrm/skills/` (`default` + `optional` + `user`). Optional packs are installed on demand; today’s catalog additions are `research-methods`, `code-quality`, `security-ops`, `data-engineering`, and `architecture-design`.
+Skills are resolved through a three-tier registry in `.xtrm/skills/` (`default` + `optional` + `user`). Optional packs are installed by default during `xt install`; activate any pack with `xt skills enable <pack>`. Current optional pack catalog: `research-methods`, `code-quality`, `security-ops`, `data-engineering`, and `architecture-design`.
 
 Skills are organized into two categories: **xtrm workflow** skills built specifically for the xtrm stack, and **general-purpose** expert skills that work in any project.
 
@@ -123,10 +124,12 @@ These skills implement the xtrm-specific development workflow — session manage
 | `planning` | Structured issue board from any spec, with phases and deps |
 | `test-planning` | Test coverage planning alongside implementation work |
 | `delegating` | Cost-optimized task delegation to background agents |
+| `using-specialists` | Specialist routing and execution workflow (`specialists run/feed/result`) |
 | `orchestrating-agents` | Multi-model orchestration (Gemini, Qwen handshake) |
 | `documenting` | SSOT doc maintenance with drift detection |
 | `sync-docs` | Doc audit and structural sync across a sprint |
 | `skill-creator` | Create, improve, and evaluate skills |
+| `specialists-creator` | Create and validate `.specialist.yaml` definitions |
 | `find-skills` | Discover and install skills on demand |
 | `creating-service-skills` | Generate operational service skill packages |
 | `scoping-service-skills` | Task intake and service routing |
@@ -152,6 +155,7 @@ Domain expert skills that can be used in any project, independent of the xtrm wo
 | `gitnexus-debugging` | Trace bugs through call chains |
 | `gitnexus-refactoring` | Plan safe refactors via dependency mapping |
 | `obsidian-cli` | Interact with Obsidian vaults via CLI |
+| `deepwiki` | Query repository/library docs via DeepWiki |
 
 ---
 
@@ -225,6 +229,16 @@ Official Claude plugins installed by `xtrm init`: `serena`, `context7`, `github`
 
 See [docs/mcp-servers.md](docs/mcp-servers.md) for configuration details.
 
+## Specialist Bash Tools
+
+| Tool | Purpose | Install source |
+|------|---------|----------------|
+| `ghgrep` | GitHub code search CLI wrapper over `mcp.grep.app` | Ships as `bin` in `xtrm-tools` |
+| `ctx7` | Context7 docs + skills CLI | Installed by machine-bootstrap (`xt install` / `xt init`) |
+| `deepwiki` | Repo documentation Q&A CLI | Installed by machine-bootstrap (`xt install` / `xt init`) |
+
+See [docs/bash-tools.md](docs/bash-tools.md) for usage examples and when to use CLIs vs MCP equivalents.
+
 ---
 
 ## Issue Tracking (Beads)
@@ -243,6 +257,7 @@ See [XTRM-GUIDE.md](XTRM-GUIDE.md) for the full `bd` command reference.
 
 | Version | Date | Highlights |
 |---------|------|------------|
+| 0.7.1 | 2026-04-02 | Optional packs pre-populated on install; Pi core symlink path fix; new default skills (`deepwiki`, `specialists-creator`, `using-specialists`) |
 | 0.5.30 | 2026-03-22 | Fix statusline on fresh installs; `xt end --dry-run` |
 | 0.5.29 | 2026-03-22 | Statusline truecolor gradient; `--no-verify` autocommit; xt-merge skill |
 | 0.5.24 | 2026-03-21 | Hash-based docs drift detection; CLI docs cleanup |

package/cli/dist/index.cjs

@@ -43977,6 +43977,8 @@ function resolvePkgRoot() {
   return candidates[0];
 }
 var PI_AGENT_DIR = process.env.PI_AGENT_DIR || import_path3.default.join((0, import_node_os.homedir)(), ".pi", "agent");
+var PROJECT_EXTENSIONS_ENTRY = "../.xtrm/extensions";
+var PROJECT_SKILLS_ENTRY = "../.xtrm/skills/active/pi";
 var MANAGED_EXTENSIONS = [
   { id: "core", displayName: "@xtrm/pi-core", isLibrary: true, required: true },
   { id: "auto-session-name", displayName: "auto-session-name", required: false },
@@ -44138,7 +44140,8 @@ function renderPiRuntimePlan(plan) {
 }
 async function ensureCorePackageSymlink(coreSrcDir, projectRoot, dryRun, log) {
   if (!await import_fs_extra7.default.pathExists(coreSrcDir)) return;
-  const nodeModulesDir = import_path3.default.join(projectRoot, ".pi", "node_modules", "@xtrm");
+  const extensionsDir = import_path3.default.join(projectRoot, ".xtrm", "extensions");
+  const nodeModulesDir = import_path3.default.join(extensionsDir, "node_modules", "@xtrm");
   const symlinkPath = import_path3.default.join(nodeModulesDir, "pi-core");
   const existing = await import_fs_extra7.default.lstat(symlinkPath).catch(() => null);
   if (existing) return;
@@ -44149,7 +44152,46 @@ async function ensureCorePackageSymlink(coreSrcDir, projectRoot, dryRun, log) {
   await import_fs_extra7.default.ensureDir(nodeModulesDir);
   const relTarget = import_path3.default.relative(nodeModulesDir, coreSrcDir);
   await import_fs_extra7.default.symlink(relTarget, symlinkPath);
-  log?.(kleur_default.dim(`Created @xtrm/pi-core symlink for module resolution`));
+  log?.(kleur_default.dim(`Created @xtrm/pi-core symlink \u2192 .xtrm/extensions/node_modules/@xtrm/pi-core`));
+}
+function isXtrmExtensionsSetting(entry) {
+  const normalizedEntry = entry.replaceAll("\\", "/").replace(/\/$/, "");
+  return normalizedEntry === PROJECT_EXTENSIONS_ENTRY || normalizedEntry === ".xtrm/extensions";
+}
+async function cleanupLegacyProjectExtensionCopies(projectRoot, dryRun, log) {
+  const piSettingsPath = import_path3.default.join(projectRoot, ".pi", "settings.json");
+  let existingSettings = {};
+  try {
+    existingSettings = await import_fs_extra7.default.readJson(piSettingsPath);
+  } catch {
+    return { removed: [], failed: [] };
+  }
+  const pointsToXtrmExtensions = (existingSettings.extensions ?? []).some(isXtrmExtensionsSetting);
+  if (!pointsToXtrmExtensions) return { removed: [], failed: [] };
+  const legacyExtensionsDir = import_path3.default.join(projectRoot, ".pi", "extensions");
+  if (!await import_fs_extra7.default.pathExists(legacyExtensionsDir)) return { removed: [], failed: [] };
+  const removed = [];
+  const failed = [];
+  for (const ext of MANAGED_EXTENSIONS) {
+    const legacyExtPath = import_path3.default.join(legacyExtensionsDir, ext.id);
+    const legacyStat = await import_fs_extra7.default.lstat(legacyExtPath).catch(() => null);
+    if (!legacyStat || legacyStat.isSymbolicLink() || !legacyStat.isDirectory()) {
+      continue;
+    }
+    if (dryRun) {
+      log?.(kleur_default.dim(`[DRY RUN] - .pi/extensions/${ext.id} (legacy copy)`));
+      continue;
+    }
+    try {
+      await import_fs_extra7.default.remove(legacyExtPath);
+      removed.push(ext.id);
+      log?.(kleur_default.dim(`Removed legacy .pi/extensions/${ext.id}`));
+    } catch (err) {
+      failed.push(ext.id);
+      log?.(kleur_default.red(`\u2717 Failed to remove legacy .pi/extensions/${ext.id}: ${err}`));
+    }
+  }
+  return { removed, failed };
 }
 async function updatePiSettings(projectRoot, dryRun, log) {
   const piSettingsPath = import_path3.default.join(projectRoot, ".pi", "settings.json");
@@ -44162,16 +44204,14 @@ async function updatePiSettings(projectRoot, dryRun, log) {
     existingSettings = await import_fs_extra7.default.readJson(piSettingsPath);
   } catch {
   }
-  const extensionsEntry = "../.xtrm/extensions";
-  const skillsEntry = "../.xtrm/skills/active/pi";
   const existingPackages = (existingSettings.packages ?? []).filter(
     (p) => !p.startsWith("./extensions/")
   );
   await import_fs_extra7.default.ensureDir(import_path3.default.join(projectRoot, ".pi"));
   await import_fs_extra7.default.writeJson(piSettingsPath, {
     ...existingSettings,
-    extensions: [extensionsEntry],
-    skills: [skillsEntry],
+    extensions: [PROJECT_EXTENSIONS_ENTRY],
+    skills: [PROJECT_SKILLS_ENTRY],
     packages: existingPackages
   }, { spaces: 2 });
   log?.(kleur_default.dim(`Updated .pi/settings.json \u2192 .xtrm/extensions + .xtrm/skills/active/pi`));
@@ -44307,6 +44347,9 @@ async function runPiRuntimeSync(opts = {}) {
   }
   console.log(kleur_default.dim("  " + "-".repeat(50)));
   const result = { ...emptyResult };
+  const legacyCleanup = await cleanupLegacyProjectExtensionCopies(resolvedProjectRoot, dryRun, log);
+  result.extensionsRemoved.push(...legacyCleanup.removed);
+  result.failed.push(...legacyCleanup.failed);
   for (const status of missingPackages) {
     const { pkg } = status;
     if (dryRun) {
@@ -44541,9 +44584,9 @@ async function launchWorktreeSession(opts) {
       } catch {
       }
     }
-    const worktreeExtensionsDir = import_node_path5.default.join(worktreePiDir, "extensions");
+    const coreExtDir = import_node_path5.default.join(worktreePath, ".xtrm", "extensions", "core");
     try {
-      await ensureCorePackageSymlink(worktreeExtensionsDir, worktreePath, false);
+      await ensureCorePackageSymlink(coreExtDir, worktreePath, false);
     } catch (error48) {
       const message = error48 instanceof Error ? error48.message : String(error48);
       console.log(kleur_default.dim(`  warning: could not ensure @xtrm/pi-core symlink (${message})`));
@@ -44718,6 +44761,17 @@ var MANAGED_DEPS = [
     install: {
       default: [{ cmd: "npm", args: ["install", "-g", "@seflless/deepwiki"] }]
     }
+  },
+  {
+    id: "ctx7",
+    cli: "ctx7",
+    versionFlag: "--version",
+    displayName: "ctx7",
+    description: "Context7 CLI \u2014 library docs lookup for specialists",
+    required: false,
+    install: {
+      default: [{ cmd: "npm", args: ["install", "-g", "ctx7"] }]
+    }
   }
 ];
 function checkDep(dep) {
@@ -52462,6 +52516,7 @@ var ART = [
   " \u255A\u2550\u255D  \u255A\u2550\u255D   \u255A\u2550\u255D   \u255A\u2550\u255D  \u255A\u2550\u255D\u255A\u2550\u255D     \u255A\u2550\u255D       \u255A\u2550\u255D    \u255A\u2550\u2550\u2550\u2550\u2550\u255D  \u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D"
 ];
 var ART_WIDTH = 84;
+var TAGLINE = "agent infrastructure layer \u2014 runtimes, skills,\n  hooks, extensions, packages";
 function isTTY2() {
   return Boolean(process.stdout.isTTY);
 }
@@ -52508,12 +52563,14 @@ async function typewriterTagline(text) {
   const CHAR_DELAY = 42;
   const prefix = `  \x1B[2m\u2014\x1B[0m  \x1B[1m\x1B[37m`;
   const suffix = `\x1B[0m  \x1B[2m\u2014\x1B[0m`;
-  process.stdout.write(prefix);
-  for (const ch of text) {
-    process.stdout.write(ch);
-    await delay(CHAR_DELAY);
+  for (const line of text.split("\n")) {
+    process.stdout.write(prefix);
+    for (const ch of line) {
+      process.stdout.write(ch);
+      await delay(CHAR_DELAY);
+    }
+    process.stdout.write(suffix + "\n");
   }
-  process.stdout.write(suffix + "\n");
 }
 var HUE_START = 170;
 var HUE_END = 230;
@@ -52547,7 +52604,7 @@ async function renderTier0(version3) {
   }
   process.stdout.write(rule + "\n");
   process.stdout.write("  \x1B[2mv" + version3 + "\x1B[0m\n");
-  await typewriterTagline("Sync agent tools across AI environments");
+  await typewriterTagline(TAGLINE);
 }
 function renderTier1(version3) {
   console.log("");
@@ -52557,7 +52614,7 @@ function renderTier1(version3) {
   console.log(kleur_default.dim(" " + "\u2500".repeat(ART_WIDTH - 1)));
   console.log(kleur_default.dim("  v" + version3));
   console.log(
-    "  " + kleur_default.dim("\u2014") + "  " + kleur_default.bold().white("Sync agent tools across AI environments") + "  " + kleur_default.dim("\u2014")
+    "  " + kleur_default.dim("\u2014") + "  " + kleur_default.bold().white(TAGLINE) + "  " + kleur_default.dim("\u2014")
   );
   console.log("");
 }
@@ -52566,19 +52623,19 @@ function renderTier2(version3) {
   console.log(
     kleur_default.cyan("  \u25C8  ") + kleur_default.bold().white("xtrm-tools") + kleur_default.dim("  v" + version3)
   );
-  console.log(kleur_default.dim("     Sync agent tools across AI environments"));
+  console.log(kleur_default.dim(`     ${TAGLINE}`));
   console.log("");
 }
 function renderTier3(version3) {
   console.log("");
   console.log(kleur_default.bold("  xtrm-tools") + kleur_default.dim(" v" + version3));
-  console.log(kleur_default.dim("  Sync agent tools across AI environments"));
+  console.log(kleur_default.dim(`  ${TAGLINE}`));
   console.log("");
 }
 function renderTier4(version3) {
   console.log("");
   console.log("xtrm-tools v" + version3);
-  console.log("Sync agent tools across AI environments");
+  console.log(TAGLINE);
   console.log("");
 }
 async function printBanner(version3) {
@@ -52609,7 +52666,7 @@ try {
 } catch {
 }
 var program2 = new Command();
-program2.name("xtrm").description("Dual-runtime workflow system for Claude Code and Pi agents").version(version2);
+program2.name("xtrm").description("Agent infrastructure layer for runtimes, skills, hooks, extensions, and packages").version(version2);
 program2.exitOverride((err) => {
   if (err.code === "commander.unknownCommand") {
     console.error(kleur_default.red(`