xtrm-tools 2.3.0 → 2.4.1

package/README.md

@@ -1,171 +1,192 @@
 # XTRM-Tools
 
-**Claude Code tools installer** — skills, hooks, MCP servers, and project-specific extensions.
+> **Claude Code plugin** — workflow enforcement, code quality gates, issue tracking, and development automation.
 
-> **ARCHITECTURAL DECISION (v2.0.0+):** xtrm-tools supports **Claude Code exclusively**. Hook translation for Gemini CLI and Qwen CLI was removed.
+**Version 2.3.0** | [Complete Guide](XTRM-GUIDE.md) | [Changelog](CHANGELOG.md)
 
-> **MIGRATION NOTICE (v2.1.20+):** Core logic has moved to **Pi Extensions**. See the [Pi Extensions Migration Guide](docs/pi-extensions-migration.md).
-
-This repository contains production-ready extensions to enhance Claude's capabilities with prompt improvement, task delegation, development workflow automation, and quality gates. The `xtrm` CLI provides a robust, modular "Plug & Play" installation engine for project-specific tools.
+---
 
 ## Quick Start
 
 ```bash
 # Install globally (one-time)
-git clone https://github.com/Jaggerxtrm/xtrm-tools.git
-cd xtrm-tools/cli
-npm install && npm run build
-npm link
+npm install -g github:Jaggerxtrm/xtrm-tools@latest
 
-# Initialize a project and register gitnexus MCP
-xtrm project init
-```
+# Install the plugin
+xtrm install all
 
-## Table of Contents
+# Verify
+claude plugin list
+# → xtrm-tools@xtrm-tools  Version: 2.3.0  Status: ✔ enabled
+```
 
-- [Project Skills & Hooks](#project-skills--hooks)
-- [Global Skills](#global-skills)
-- [Installation](#installation)
-- [CLI User Guide](#cli-user-guide)
-- [Configuration](#configuration)
-- [Version History](#version-history)
-- [License](#license)
+**One-line run:**
+```bash
+npx -y github:Jaggerxtrm/xtrm-tools install all
+```
 
 ---
 
-## Project Skills & Hooks
+## What's Included
 
-Project skills are modular, plug-and-play tool packages extending Claude's capabilities for specific workflows. They install into your project's `.claude/` directory and include specific hooks enforcing local workflow rules and quality gates.
+### Core Enforcement
 
-### using-xtrm (Session Operating Manual)
-**The foundational operating manual for an xtrm-equipped session.**
-- **Invocation**: Activates automatically at session start via hook.
-- **Purpose**: Orients the agent on how to work within the xtrm stack: applying prompt improvement, using the beads issue-tracking gate, enforcing PR workflows, and combining the full toolset (gitnexus, Serena, quality gates, delegation).
-- **Core Workflow**: Provides the authoritative guide on feature-branch usage, requiring PRs for merges (with `--squash`), and stopping dangerous git commands on protected branches.
+| Component | Purpose |
+|-----------|---------|
+| **Main Guard** | PR-only workflow — blocks direct commits on `main`/`master` |
+| **Beads Gates** | Issue tracking — edit/commit/stop gates, memory prompts |
+| **Quality Gates** | Auto linting (ESLint, tsc, ruff, mypy) on file edits |
+| **GitNexus** | Knowledge graph context for code exploration |
 
-### Quality Gates (`using-quality-gates`)
-Code quality enforcement via the **Pi Extension** (`quality-gates.ts`), which fires on every mutating file tool result.
-- **TypeScript/JS**: delegates to project-local `.claude/hooks/quality-check.cjs` (ESLint + tsc)
-- **Python**: delegates to project-local `.claude/hooks/quality-check.py` (ruff + mypy)
-- Exit code 2 = blocking — Claude must fix before continuing.
-- No classic hook entry required; runs automatically when the Pi extension is loaded.
+### Skills
 
-> **Note:** `tdd-guard` is available as an installable project skill (`xtrm install project tdd-guard`) but is not enforced by default.
+| Skill | Type | Purpose |
+|-------|------|---------|
+| `using-xtrm` | Project | Session operating manual |
+| `documenting` | Global | SSOT documentation with drift detection |
+| `delegating` | Global | Task delegation to cost-optimized agents |
+| `orchestrating-agents` | Global | Multi-model collaboration |
 
-### Service Skills Set (Trinity)
-Task intake and service routing for Docker service projects.
-- **Invocation**: `/scope "task description"` or automatic via SessionStart hook.
-- **Purpose**: Gives Claude persistent, service-specific expertise without re-explaining architecture. Emits structured scope plans and detects codebase drift via PostToolUse hooks.
-
-### Core Project Hooks
+---
 
-**Main Guard (`main-guard.mjs`)**
-- **Trigger**: PreToolUse (Write|Edit|MultiEdit|Serena edit tools|Bash)
-- **Purpose**: Enforces PR-only merge workflow with full git protection. Blocks direct commits and dangerous `git checkout` / `git push` commands on protected branches (`main/master`).
-- **Post-Push (`main-guard-post-push.mjs`)**: After pushing a feature branch, reminds to use `gh pr merge --squash` and sync local via `git reset --hard origin/main`.
+## Plugin Structure
 
-**GitNexus Graph Context (`gitnexus-hook.cjs`)**
-- **Trigger**: PostToolUse (with Serena support and dedup cache)
-- **Purpose**: Enriches tool output with knowledge graph context via `gitnexus augment`.
-- *Note: `gitnexus-impact-reminder` was removed as impact analysis enforcement is now native.*
+```
+plugins/xtrm-tools/
+├── .claude-plugin/plugin.json   # Manifest
+├── hooks → ../../hooks           # All hook scripts + hooks.json
+├── skills → ../../skills         # Auto-discovered skills
+└── .mcp.json → ../../.mcp.json   # MCP servers
+```
 
-**Beads Issue Tracking Gates**
-- **Trigger**: PreToolUse (edit/commit), PostToolUse (claim sync), Stop (memory + stop gate), PreCompact, SessionStart
-- **Purpose**: Ensures all work is tracked to a `bd` issue. Blocks file edits without an active claim.
-- **Claim sync (`beads-claim-sync.mjs`)**: PostToolUse hook that syncs claim state after `bd update --claim` shell commands.
-- **Compaction**: `PreCompact` and `SessionStart` hooks preserve `in_progress` beads state across `/compact` events. Hook blocking messages are quieted and compacted to save tokens.
+All hook paths use `${CLAUDE_PLUGIN_ROOT}` — works from any installation location.
 
 ---
 
-## Global Skills
+## Policy System
 
-Global skills are reusable workflows installed to the user-level Claude environment (not tied to one repo). 
+Policies are the **single source of truth** for all enforcement rules. Located in `policies/`, they compile to both Claude hooks and Pi extensions.
 
-### documenting
-Maintains Single Source of Truth (SSOT) documentation system with drift detection.
-- **Invocation**: `/document [task]`
-- **Purpose**: Creates, updates, and validates SSOT documentation. Auto-generates INDEX blocks for rapid navigation. A Stop hook fires at session end to detect stale memories based on the `tracks:` frontmatter field.
+### Policy Files
 
-### delegating
-Proactively delegates tasks to cost-optimized agents before working in main session.
-- **Invocation**: `/delegate [task]` or `/delegating [task]`
-- **Purpose**: Routes simple deterministic tasks (tests, typos, formatting, docs) to GLM/Gemini/Qwen, and complex reasoning tasks to multi-agent orchestration. Interactive 2-step menu helps select the backend. Avoids main session token usage.
+| Policy | Runtime | Purpose |
+|--------|---------|---------|
+| `main-guard.json` | both | PR-only workflow |
+| `beads.json` | both | Issue tracking gates |
+| `quality-gates.json` | pi | Linting/typechecking |
+| `branch-state.json` | claude | Branch context injection |
+| `gitnexus.json` | claude | Knowledge graph enrichment |
 
-### orchestrating-agents
-Orchestrates task handoff and "handshaking" between Gemini and Qwen CLI agents.
-- **Invocation**: `/orchestrate [workflow-type] [task]`
-- **Purpose**: Facilitates multi-model collaboration, adversarial reviews, and deep cross-validation of complex logic. Workflows include collaborative design, adversarial security review, troubleshooting, and single handshakes.
+### Compiler
 
----
+```bash
+node scripts/compile-policies.mjs           # Generate hooks.json
+node scripts/compile-policies.mjs --check   # CI drift detection
+```
 
-## Installation
+---
 
-### 🚀 Quick One-Time Run
+## CLI Commands
 
-```bash
-npx -y github:Jaggerxtrm/xtrm-tools install all
+```
+xtrm <command> [options]
 ```
 
-### 🛠️ Global Installation (Recommended)
+| Command | Description |
+|---------|-------------|
+| `install all` | Full plugin + beads + gitnexus |
+| `install basic` | Plugin + skills (no beads) |
+| `install project <name>` | Install project skill |
+| `project init` | Initialize project (gitnexus + bd) |
+| `status` | Read-only diff view |
+| `clean` | Remove orphaned hooks |
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--yes`, `-y` | Non-interactive mode |
+| `--dry-run` | Preview only |
+| `--prune` | Force-replace hooks |
 
-```bash
-npm install -g github:Jaggerxtrm/xtrm-tools@latest
+---
 
-xtrm install all            # Install to all global targets
-xtrm project init           # Setup current project (runs gitnexus analyze + bd init)
-xtrm install project all    # Install all project-specific skills
-```
+## Hooks Reference
+
+### Event Types
+
+| Event | When |
+|-------|------|
+| `SessionStart` | Session begins |
+| `PreToolUse` | Before tool invocation |
+| `PostToolUse` | After tool completes |
+| `Stop` | Session ends |
+| `PreCompact` | Before compaction |
+
+### Main Guard
+
+- Blocks `git commit`/`push` on protected branches
+- Blocks direct file edits on `main`/`master`
+- Post-push reminder: `gh pr merge --squash`
+
+### Beads Gates
+
+| Hook | Behavior |
+|------|----------|
+| Edit Gate | Requires claimed issue to edit files |
+| Commit Gate | Prompts to close issue before commit |
+| Stop Gate | Blocks session end with unclosed issues |
+| Memory Gate | Prompts to persist insights when closing |
 
 ---
 
-## CLI User Guide
+## MCP Servers
 
-```
-xtrm <command> [options]
-```
+Configured in `.mcp.json` (xtrm-managed only):
 
-| Command | Description |
-|---|---|
-| `install all` | Non-interactive global install to all detected targets (installs `gitnexus` globally) |
-| `install basic` | Interactive global installation |
-| `install project <name>` | Install specific project skills (e.g., `tdd-guard`, `service-skills-set`) |
-| `project init` | Onboarding: runs `gitnexus analyze`, registers MCP, and runs `bd init` |
-| `status` | Read-only diff view showing what would change (with inline sync prompt) |
-| `clean` | Removes orphaned hooks, stale wrappers, and dead skills from your system |
-| `reset` | Clear saved CLI preferences |
+| Server | Purpose |
+|--------|---------|
+| `gitnexus` | Knowledge graph |
+| `github-grep` | Code search |
+| `deepwiki` | DeepWiki docs search |
+
+Official Claude plugins are installed during `xtrm install all`:
+- `serena@claude-plugins-official`
+- `context7@claude-plugins-official`
+- `github@claude-plugins-official`
+- `ralph-loop@claude-plugins-official`
 
 ---
 
-## Configuration
+## Issue Tracking (Beads)
 
-### MCP Servers
+```bash
+bd ready                    # Find unblocked work
+bd update <id> --claim      # Claim an issue
+bd close <id> --reason "Done"  # Close when done
+```
 
-Unified CLI sync configures core servers securely.
+---
 
-**Core Servers**:
-- **serena**: Code analysis (requires `uvx`)
-- **context7**: Documentation lookup (requires `CONTEXT7_API_KEY`)
-- **github-grep**: Code search
-- **deepwiki**: Technical documentation
-- **gitnexus**: Knowledge graph code intelligence (registered during `xtrm project init`)
+## Documentation
 
-Configured via `~/.config/xtrm-tools/.env`. Run `xtrm install basic` to sync interactively.
+- **[XTRM-GUIDE.md](XTRM-GUIDE.md)** — Complete reference guide
+- **[CHANGELOG.md](CHANGELOG.md)** — Full version history
+- **[ROADMAP.md](ROADMAP.md)** — Planned features
 
 ---
 
 ## Version History
 
 | Version | Date | Highlights |
-|---|---|---|
-| 2.2.0 | 2026-03-17 | Pi extension parity: quality-gates, beads, service-skills, main-guard; `beads-claim-sync.mjs`; `xtrm clean` canonical wiring validation |
-| 2.1.20 | 2026-03-16 | `xtrm clean` command, compact hook messages, `pruneStaleWrappers` fixes |
-| 2.1.18 | 2026-03-16 | `PreCompact` / `SessionStart` hooks to preserve `in_progress` beads state |
-| 2.1.16 | 2026-03-15 | Removed deprecated skill-suggestion, gitnexus-impact-reminder hooks |
-| 2.1.14 | 2026-03-15 | Rewrote gitnexus-hook as PostToolUse with Serena; added `using-xtrm` skill |
-| 2.1.9 | 2026-03-15 | `main-guard` enforced PR-only workflow, `--squash` requirement, npm publish |
+|---------|------|------------|
+| 2.3.0 | 2026-03-17 | Plugin structure, policy compiler, Pi extension parity |
+| 2.2.0 | 2026-03-17 | Pi extensions: quality-gates, beads, main-guard |
+| 2.0.0 | 2026-03-12 | CLI rebrand, project skills engine |
+| 1.7.0 | 2026-02-25 | GitNexus integration |
 
-See [CHANGELOG.md](CHANGELOG.md) for full history.
+---
 
 ## License
 
-MIT License - See LICENSE file for details.
+MIT License

package/cli/dist/index.cjs

@@ -37236,13 +37236,24 @@ async function calculateDiff(repoRoot, systemRoot, pruneMode = false) {
     "qwen-commands": { missing: [], outdated: [], drifted: [], total: 0 },
     "antigravity-workflows": { missing: [], outdated: [], drifted: [], total: 0 }
   };
+  const manifestPath = (0, import_path4.join)(systemRoot, ".jaggers-sync-manifest.json");
+  let installedHashes = null;
+  try {
+    if (await import_fs_extra3.default.pathExists(manifestPath)) {
+      const manifest = await import_fs_extra3.default.readJson(manifestPath);
+      if (manifest.fileHashes && typeof manifest.fileHashes === "object") {
+        installedHashes = manifest.fileHashes;
+      }
+    }
+  } catch {
+  }
   if (isAgentsSkills) {
     const repoPath = (0, import_path4.join)(repoRoot, "skills");
     if (!await import_fs_extra3.default.pathExists(repoPath)) return changeSet;
     const items = (await import_fs_extra3.default.readdir(repoPath)).filter((i) => !IGNORED_ITEMS.has(i));
     changeSet.skills.total = items.length;
     for (const item of items) {
-      await compareItem("skills", item, (0, import_path4.join)(repoPath, item), (0, import_path4.join)(systemRoot, item), changeSet, pruneMode);
+      await compareItem("skills", item, (0, import_path4.join)(repoPath, item), (0, import_path4.join)(systemRoot, item), changeSet, pruneMode, installedHashes);
     }
     return changeSet;
   }
@@ -37269,7 +37280,8 @@ async function calculateDiff(repoRoot, systemRoot, pruneMode = false) {
         (0, import_path4.join)(repoPath, item),
         (0, import_path4.join)(systemPath, item),
         changeSet,
-        pruneMode
+        pruneMode,
+        installedHashes
       );
     }
   }
@@ -37281,12 +37293,12 @@ async function calculateDiff(repoRoot, systemRoot, pruneMode = false) {
     const itemRepoPath = (0, import_path4.join)(repoRoot, paths.repo);
     const itemSystemPath = (0, import_path4.join)(systemRoot, paths.sys);
     if (await import_fs_extra3.default.pathExists(itemRepoPath)) {
-      await compareItem("config", name, itemRepoPath, itemSystemPath, changeSet);
+      await compareItem("config", name, itemRepoPath, itemSystemPath, changeSet, false, installedHashes);
     }
   }
   return changeSet;
 }
-async function compareItem(category, item, repoPath, systemPath, changeSet, pruneMode = false) {
+async function compareItem(category, item, repoPath, systemPath, changeSet, pruneMode = false, installedHashes = null) {
   const cat = changeSet[category];
   if (!await import_fs_extra3.default.pathExists(systemPath)) {
     cat.missing.push(item);
@@ -37304,12 +37316,22 @@ async function compareItem(category, item, repoPath, systemPath, changeSet, prun
     return;
   }
   if (repoHash !== systemHash) {
-    const repoMtime = await getNewestMtime(repoPath);
-    const systemMtime = await getNewestMtime(systemPath);
-    if (systemMtime > repoMtime + 2e3) {
-      cat.drifted.push(item);
+    const manifestKey = `${category}/${item}`;
+    const installedHash = installedHashes?.[manifestKey];
+    if (installedHash !== void 0) {
+      if (systemHash !== installedHash) {
+        cat.drifted.push(item);
+      } else {
+        cat.outdated.push(item);
+      }
     } else {
-      cat.outdated.push(item);
+      const repoMtime = await getNewestMtime(repoPath);
+      const systemMtime = await getNewestMtime(systemPath);
+      if (systemMtime > repoMtime + 2e3) {
+        cat.drifted.push(item);
+      } else {
+        cat.outdated.push(item);
+      }
     }
   }
 }
@@ -40508,7 +40530,32 @@ async function cleanupBackup(backup) {
 }
 
 // src/core/sync-executor.ts
-var syncedMcpAgents = /* @__PURE__ */ new Set();
+async function syncMcpForTargets(repoRoot, targets, isDryRun = false, selectedMcpServers) {
+  const synced = /* @__PURE__ */ new Set();
+  let count = 0;
+  for (const target of targets) {
+    const agent = detectAgent(target);
+    if (!agent || synced.has(agent)) continue;
+    const coreConfig = loadCanonicalMcpConfig(repoRoot);
+    const mcpToSync = { mcpServers: { ...coreConfig.mcpServers } };
+    if (selectedMcpServers && selectedMcpServers.length > 0) {
+      const optionalConfig = loadCanonicalMcpConfig(repoRoot, true);
+      for (const name of selectedMcpServers) {
+        if (optionalConfig.mcpServers[name]) {
+          mcpToSync.mcpServers[name] = optionalConfig.mcpServers[name];
+        }
+      }
+    }
+    if (!isDryRun) {
+      await syncMcpServersWithCli(agent, mcpToSync, isDryRun, false);
+    } else {
+      console.log(kleur_default.cyan(`  [DRY RUN] MCP sync for ${agent}`));
+    }
+    synced.add(agent);
+    count++;
+  }
+  return count;
+}
 function extractHookCommandPath(command) {
   const quoted = command.match(/"([^"]+)"/);
   if (quoted?.[1]) return quoted[1];
@@ -40544,7 +40591,7 @@ async function filterHooksByInstalledScripts(hooksConfig) {
   }
   return hooksConfig;
 }
-async function executeSync(repoRoot, systemRoot, changeSet, mode, actionType, isDryRun = false, selectedMcpServers, options) {
+async function executeSync(repoRoot, systemRoot, changeSet, mode, actionType, isDryRun = false, options) {
   const normalizedRoot = import_path8.default.normalize(systemRoot).replace(/\\/g, "/");
   const isAgentsSkills = normalizedRoot.includes(".agents/skills");
   const isClaude = systemRoot.includes(".claude") || systemRoot.includes("Claude");
@@ -40555,27 +40602,9 @@ async function executeSync(repoRoot, systemRoot, changeSet, mode, actionType, is
   let count = 0;
   const adapter = new ConfigAdapter(systemRoot);
   const backups = [];
+  const newHashes = {};
   try {
     const agent = detectAgent(systemRoot);
-    if (agent && actionType === "sync" && !syncedMcpAgents.has(agent) && !options?.skipMcp) {
-      const coreConfig = loadCanonicalMcpConfig(repoRoot);
-      const mcpToSync = { mcpServers: { ...coreConfig.mcpServers } };
-      if (selectedMcpServers && selectedMcpServers.length > 0) {
-        const optionalConfig = loadCanonicalMcpConfig(repoRoot, true);
-        for (const name of selectedMcpServers) {
-          if (optionalConfig.mcpServers[name]) {
-            mcpToSync.mcpServers[name] = optionalConfig.mcpServers[name];
-          }
-        }
-      }
-      if (!isDryRun) {
-        await syncMcpServersWithCli(agent, mcpToSync, isDryRun, false);
-      } else {
-        console.log(kleur_default.cyan(`  [DRY RUN] MCP sync for ${agent}`));
-      }
-      syncedMcpAgents.add(agent);
-      count++;
-    }
     for (const category of categories) {
       const itemsToProcess = [];
       if (actionType === "sync") {
@@ -40608,6 +40637,11 @@ async function executeSync(repoRoot, systemRoot, changeSet, mode, actionType, is
           src = import_path8.default.join(repoRoot, "config", "settings.json");
           dest = import_path8.default.join(systemRoot, "settings.json");
           const agent2 = detectAgent(systemRoot);
+          if (agent2 === "claude") {
+            if (!isDryRun) console.log(kleur_default.dim(`      (settings.json skipped \u2014 managed by xtrm-tools plugin)`));
+            count++;
+            continue;
+          }
           console.log(kleur_default.gray(`  --> config/settings.json`));
           if (!isDryRun && await import_fs_extra8.default.pathExists(dest)) {
             backups.push(await createBackup(dest));
@@ -40697,6 +40731,9 @@ async function executeSync(repoRoot, systemRoot, changeSet, mode, actionType, is
             await import_fs_extra8.default.copy(src, dest);
           }
         }
+        if (!isDryRun && actionType === "sync") {
+          newHashes[`${category}/${item}`] = await hashDirectory(src);
+        }
         count++;
       }
     }
@@ -40707,7 +40744,8 @@ async function executeSync(repoRoot, systemRoot, changeSet, mode, actionType, is
         ...existing,
         lastSync: (/* @__PURE__ */ new Date()).toISOString(),
         repoRoot,
-        items: count
+        items: count,
+        fileHashes: { ...existing.fileHashes ?? {}, ...newHashes }
       }, { spaces: 2 });
     }
     for (const backup of backups) {
@@ -41846,6 +41884,7 @@ function isGitnexusInstalled() {
 async function needsSettingsSync(repoRoot, target) {
   const normalizedTarget = target.replace(/\\/g, "/").toLowerCase();
   if (normalizedTarget.includes(".agents/skills")) return false;
+  if (detectAgent(target) === "claude") return false;
   const hooksTemplatePath = import_path13.default.join(repoRoot, "config", "hooks.json");
   if (!await import_fs_extra13.default.pathExists(hooksTemplatePath)) return false;
   const requiredEvents = Object.keys((await import_fs_extra13.default.readJson(hooksTemplatePath)).hooks ?? {});
@@ -41864,12 +41903,63 @@ async function needsSettingsSync(repoRoot, target) {
   }
   return requiredEvents.some((event) => !(event in targetHooks));
 }
+var OFFICIAL_CLAUDE_MARKETPLACE = "https://github.com/anthropics/claude-plugins-official";
+var OFFICIAL_CLAUDE_PLUGINS = [
+  "serena@claude-plugins-official",
+  "context7@claude-plugins-official",
+  "github@claude-plugins-official",
+  "ralph-loop@claude-plugins-official"
+];
+async function installOfficialClaudePlugins(dryRun) {
+  console.log(t.bold("\n  \u2699  official Claude plugins  (serena/context7/github/ralph-loop)"));
+  if (dryRun) {
+    console.log(t.accent("  [DRY RUN] Would register claude-plugins-official marketplace and install official plugins\n"));
+    return;
+  }
+  (0, import_child_process5.spawnSync)("claude", ["plugin", "marketplace", "add", OFFICIAL_CLAUDE_MARKETPLACE, "--scope", "user"], { stdio: "pipe" });
+  const listResult = (0, import_child_process5.spawnSync)("claude", ["plugin", "list"], { encoding: "utf8", stdio: "pipe" });
+  const installedOutput = listResult.stdout ?? "";
+  let installedCount = 0;
+  let alreadyInstalledCount = 0;
+  for (const pluginId of OFFICIAL_CLAUDE_PLUGINS) {
+    if (installedOutput.includes(pluginId)) {
+      alreadyInstalledCount += 1;
+      continue;
+    }
+    const result = (0, import_child_process5.spawnSync)("claude", ["plugin", "install", pluginId, "--scope", "user"], { stdio: "inherit" });
+    if (result.status === 0) {
+      installedCount += 1;
+    } else {
+      console.log(t.warning(`  ! Failed to install ${pluginId}. Install manually: claude plugin install ${pluginId} --scope user`));
+    }
+  }
+  console.log(t.success(`  \u2713 Official plugins ready (${installedCount} installed, ${alreadyInstalledCount} already present)
+`));
+}
+async function installPlugin(repoRoot, dryRun) {
+  console.log(t.bold("\n  \u2699  xtrm-tools  (Claude Code plugin)"));
+  if (dryRun) {
+    console.log(t.accent("  [DRY RUN] Would register xtrm-tools marketplace and install plugin\n"));
+    await installOfficialClaudePlugins(true);
+    return;
+  }
+  (0, import_child_process5.spawnSync)("claude", ["plugin", "marketplace", "add", repoRoot, "--scope", "user"], { stdio: "pipe" });
+  const listResult = (0, import_child_process5.spawnSync)("claude", ["plugin", "list"], { encoding: "utf8", stdio: "pipe" });
+  if (listResult.stdout?.includes("xtrm-tools@xtrm-tools")) {
+    (0, import_child_process5.spawnSync)("claude", ["plugin", "uninstall", "xtrm-tools@xtrm-tools"], { stdio: "inherit" });
+  }
+  (0, import_child_process5.spawnSync)("claude", ["plugin", "install", "xtrm-tools@xtrm-tools", "--scope", "user"], { stdio: "inherit" });
+  console.log(t.success("  \u2713 xtrm-tools plugin installed"));
+  await installOfficialClaudePlugins(false);
+}
 async function runGlobalInstall(flags, installOpts = {}) {
   const { dryRun, yes, noMcp, force } = flags;
   const effectiveYes = yes || process.argv.includes("--yes") || process.argv.includes("-y");
   const repoRoot = await findRepoRoot();
   const ctx = await getContext({ selector: "all", createMissingDirs: !dryRun });
   const { targets, syncMode } = ctx;
+  const claudeTargets = targets.filter((t2) => detectAgent(t2) === "claude");
+  const otherTargets = targets.filter((t2) => detectAgent(t2) !== "claude");
   let skipBeads = installOpts.excludeBeads ?? false;
   if (installOpts.checkBeads && !skipBeads) {
     console.log(t.bold("\n  \u2699  beads + dolt  (workflow enforcement backend)"));
@@ -41941,8 +42031,14 @@ async function runGlobalInstall(flags, installOpts = {}) {
       console.log(t.muted("  \u2139 Skipped. Install later with: npm install -g gitnexus\n"));
     }
   }
+  for (const _claudeTarget of claudeTargets) {
+    await installPlugin(repoRoot, dryRun);
+  }
+  if (otherTargets.length === 0) {
+    return;
+  }
   const diffTasks = new Listr(
-    targets.map((target) => ({
+    otherTargets.map((target) => ({
       title: formatTargetLabel(target),
       task: async (listCtx, task) => {
         try {
@@ -41950,10 +42046,6 @@ async function runGlobalInstall(flags, installOpts = {}) {
           if (skipBeads) {
             changeSet = filterBeadsFromChangeSet(changeSet);
           }
-          const hasSettingsDiff = changeSet.config.missing.includes("settings.json") || changeSet.config.outdated.includes("settings.json") || changeSet.config.drifted.includes("settings.json");
-          if (!hasSettingsDiff && await needsSettingsSync(repoRoot, target)) {
-            changeSet.config.outdated.push("settings.json");
-          }
           const totalChanges = Object.values(changeSet).reduce(
             (sum, c) => sum + c.missing.length + c.outdated.length + c.drifted.length,
             0
@@ -41998,11 +42090,13 @@ async function runGlobalInstall(flags, installOpts = {}) {
     }
   }
   let totalCount = 0;
+  if (!noMcp) {
+    await syncMcpForTargets(repoRoot, otherTargets, dryRun);
+  }
   for (const { target, changeSet, skippedDrifted } of allChanges) {
     console.log(t.bold(`
   ${sym.arrow} ${formatTargetLabel(target)}`));
-    const count = await executeSync(repoRoot, target, changeSet, syncMode, "sync", dryRun, void 0, {
-      skipMcp: noMcp,
+    const count = await executeSync(repoRoot, target, changeSet, syncMode, "sync", dryRun, {
       force
     });
     totalCount += count;
@@ -42045,6 +42139,8 @@ function createInstallCommand() {
       createMissingDirs: !dryRun
     });
     const { targets, syncMode } = ctx;
+    const claudeTargets = targets.filter((t2) => detectAgent(t2) === "claude");
+    const otherTargets = targets.filter((t2) => detectAgent(t2) !== "claude");
     let skipBeads = false;
     if (!backport) {
       console.log(t.bold("\n  \u2699  beads + dolt  (workflow enforcement backend)"));
@@ -42092,8 +42188,13 @@ function createInstallCommand() {
         }
       }
     }
+    if (!backport) {
+      for (const _claudeTarget of claudeTargets) {
+        await installPlugin(repoRoot, dryRun);
+      }
+    }
     const diffTasks = new Listr(
-      targets.map((target) => ({
+      otherTargets.map((target) => ({
         title: formatTargetLabel(target),
         task: async (listCtx, task) => {
           try {
@@ -42128,20 +42229,8 @@ function createInstallCommand() {
     );
     const diffCtx = await diffTasks.run({ allChanges: [] });
     const allChanges = diffCtx.allChanges;
-    if (!backport && !dryRun) {
-      const emptyChangeSet = {
-        skills: { missing: [], outdated: [], drifted: [], total: 0 },
-        hooks: { missing: [], outdated: [], drifted: [], total: 0 },
-        config: { missing: [], outdated: [], drifted: [], total: 0 },
-        commands: { missing: [], outdated: [], drifted: [], total: 0 },
-        "qwen-commands": { missing: [], outdated: [], drifted: [], total: 0 },
-        "antigravity-workflows": { missing: [], outdated: [], drifted: [], total: 0 }
-      };
-      for (const target of targets) {
-        console.log(t.bold(`
-  ${sym.arrow} ${formatTargetLabel(target)}`));
-        await executeSync(repoRoot, target, emptyChangeSet, syncMode, "sync", false);
-      }
+    if (!backport) {
+      await syncMcpForTargets(repoRoot, otherTargets, dryRun);
     }
     if (allChanges.length === 0) {
       console.log("\n" + t.boldGreen("\u2713 Files are up-to-date") + "\n");