@documentation-robotics/cli 0.1.0 → 0.1.7

package/dist/integrations/claude-manager.js

@@ -0,0 +1,360 @@
+import { BaseIntegrationManager } from "./base-manager.js";
+import { findProjectRoot } from "../utils/project-paths.js";
+import { confirm, spinner, isCancel } from "@clack/prompts";
+import ansis from "ansis";
+import { join } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+class ClaudeIntegrationManager extends BaseIntegrationManager {
+  targetDir = ".claude";
+  versionFileName = ".dr-version";
+  integrationSourceDir = "claude_code";
+  /**
+   * Component configuration for Claude integration
+   * Extends BaseIntegrationManager with Claude-specific components.
+   *
+   * The `tracked` property controls whether a component is included in
+   * version file tracking. Only `tracked: false` needs to be explicit
+   * (for user-customizable components like templates). DR-owned components
+   * default to tracked: true (see isTrackedComponent check in base-manager.ts).
+   *
+   * DR-owned components (tracked: true or default) are monitored for updates.
+   * User-customizable components (tracked: false) are installed but not
+   * version-tracked to avoid conflicts with user modifications.
+   */
+  components = {
+    reference_sheets: {
+      source: "reference_sheets",
+      target: "knowledge",
+      description: "Reference documentation for agents",
+      prefix: "dr-",
+      type: "files"
+      // tracked: true (default)
+    },
+    commands: {
+      source: "commands",
+      target: "commands",
+      description: "Slash commands for DR workflows",
+      prefix: "dr-",
+      type: "files"
+      // tracked: true (default)
+    },
+    agents: {
+      source: "agents",
+      target: "agents",
+      description: "Specialized sub-agent definitions",
+      prefix: "dr-",
+      type: "files"
+      // tracked: true (default)
+    },
+    skills: {
+      source: "skills",
+      target: "skills",
+      description: "Auto-activating capabilities",
+      prefix: "",
+      type: "dirs"
+      // tracked: true (default)
+    },
+    templates: {
+      source: "templates",
+      target: "templates",
+      description: "Customization templates and examples",
+      prefix: "",
+      type: "files",
+      tracked: !1
+    }
+  };
+  /**
+   * Install Claude integration files
+   *
+   * Copies files from bundled source to .claude/ directory, prompting for
+   * confirmation if files already exist. Optionally filters to specific components.
+   *
+   * @param options Installation options
+   * @param options.components Optional list of component names to install
+   * @param options.force Skip confirmation prompts
+   */
+  async install(options = {}) {
+    const projectRoot = await this.getProjectRoot();
+    this.targetDir = join(projectRoot, ".claude");
+    const { components = Object.keys(this.components), force = !1 } = options, invalid = components.filter((c) => !this.components[c]);
+    if (invalid.length > 0)
+      throw new Error(`Invalid components: ${invalid.join(", ")}
+Valid: ${Object.keys(this.components).join(", ")}`);
+    if (await this.isInstalled() && !force) {
+      if (!(process.stdin.isTTY && process.stdout.isTTY))
+        throw new Error(`Interactive confirmation is not available in non-TTY environments.
+Use --force to skip confirmation and proceed with installation`);
+      const response = await confirm({
+        message: "Claude integration already installed. Overwrite?"
+      });
+      if (isCancel(response) || !response) {
+        console.log(ansis.yellow("\u2717 Installation cancelled"));
+        return;
+      }
+    }
+    await mkdir(this.targetDir, { recursive: !0 });
+    let totalInstalled = 0;
+    const spinnerObj = spinner();
+    spinnerObj.start("Installing components...");
+    try {
+      for (const componentName of components) {
+        const count = await this.installComponent(componentName, force);
+        totalInstalled += count;
+      }
+      spinnerObj.stop("Installation complete");
+      const cliVersion = await this.getCliVersion();
+      await this.updateVersionFile(cliVersion), console.log(ansis.green("\u2713 Claude integration installed successfully!")), console.log(ansis.green("  Installed " + totalInstalled + " files")), this.printNextSteps();
+    } catch (error) {
+      throw spinnerObj.stop("Installation failed"), error;
+    }
+  }
+  /**
+   * Upgrade installed Claude integration files
+   *
+   * Detects file changes, shows a summary, and applies upgrades with optional
+   * dry-run mode to preview changes without applying them.
+   *
+   * @param options Upgrade options
+   * @param options.dryRun Preview changes without applying
+   * @param options.force Skip confirmation prompts and overwrite conflict/user-modified files
+   */
+  async upgrade(options = {}) {
+    const projectRoot = await this.getProjectRoot();
+    this.targetDir = join(projectRoot, ".claude");
+    const { dryRun = !1, force = !1 } = options;
+    if (!await this.isInstalled()) {
+      console.log(ansis.yellow("\u26A0 Claude integration not installed")), console.log(ansis.dim("Run: dr claude install"));
+      return;
+    }
+    const versionData = await this.loadVersionFile();
+    if (!versionData)
+      throw new Error("Version file corrupted. Run: dr claude install");
+    let totalChanges = 0;
+    const changes = [], unknownComponents = /* @__PURE__ */ new Set();
+    for (const componentName of Object.keys(versionData.components || {})) {
+      const config = this.components[componentName];
+      if (!config) {
+        unknownComponents.add(componentName), console.warn(ansis.yellow(`\u26A0 Unknown component in version file: ${componentName}. Skipping.`));
+        continue;
+      }
+      if (!this.isTrackedComponent(componentName))
+        continue;
+      const targetPath = join(this.targetDir, config.target);
+      if (!existsSync(targetPath))
+        continue;
+      const componentChanges = await this.checkUpdates(componentName, versionData);
+      for (const change of componentChanges) {
+        const status = this.changeTypeToStatus(change.changeType), action = force && (change.changeType === "conflict" || change.changeType === "user-modified") ? "Overwrite" : this.changeTypeToAction(change.changeType);
+        changes.push({
+          file: change.component + "/" + change.path,
+          status,
+          action
+        }), totalChanges++;
+      }
+    }
+    const obsolete = await this.detectObsoleteFiles();
+    for (const file of obsolete)
+      changes.push({
+        file: file.component + "/" + file.path,
+        status: "Obsolete",
+        action: "Remove"
+      }), totalChanges++;
+    if (totalChanges === 0) {
+      console.log(ansis.green("\u2713 All files are up to date"));
+      const cliVersion = await this.getCliVersion();
+      versionData.version !== cliVersion && (await this.updateVersionFile(cliVersion), console.log(ansis.green("\u2713 Version updated to " + cliVersion)));
+      return;
+    }
+    console.log(ansis.bold(`
+Planned Changes:`));
+    for (const change of changes) {
+      const statusColor = change.status === "Obsolete" ? ansis.yellow : ansis.cyan, actionColor = change.action === "Remove" ? ansis.red : ansis.green;
+      console.log("  " + statusColor(change.status.padEnd(10)) + " " + change.file + " " + actionColor(change.action));
+    }
+    if (dryRun) {
+      console.log(ansis.yellow(`
+Dry run - no changes applied`));
+      return;
+    }
+    if (!changes.some((c) => c.action !== "Skip")) {
+      console.log(ansis.yellow("\u26A0 No changes to apply (all changes are skipped or conflicts)"));
+      return;
+    }
+    if (!force) {
+      if (!(process.stdin.isTTY && process.stdout.isTTY))
+        throw new Error(`Interactive confirmation is not available in non-TTY environments.
+Use --force to skip confirmation and proceed with upgrade`);
+      const response = await confirm({
+        message: "Apply upgrades?"
+      });
+      if (isCancel(response) || !response) {
+        console.log(ansis.yellow("\u2717 Upgrade cancelled"));
+        return;
+      }
+    }
+    const spinnerObj = spinner();
+    spinnerObj.start("Applying upgrades...");
+    try {
+      for (const componentName of Object.keys(versionData.components || {})) {
+        if (unknownComponents.has(componentName))
+          continue;
+        const config = this.components[componentName];
+        if (!config || !this.isTrackedComponent(componentName))
+          continue;
+        const targetPath = join(this.targetDir, config.target);
+        existsSync(targetPath) && await this.installComponent(componentName, force);
+      }
+      await this.removeObsoleteFiles(), spinnerObj.stop("Upgrades applied");
+      const cliVersion = await this.getCliVersion();
+      await this.updateVersionFile(cliVersion), console.log(ansis.green("\u2713 Upgrade completed successfully!"));
+    } catch (error) {
+      throw spinnerObj.stop("Upgrade failed"), error;
+    }
+  }
+  /**
+   * Remove Claude integration files
+   *
+   * Removes files and the version file. Optionally filters to specific components.
+   *
+   * @param options Remove options
+   * @param options.components Optional list of component names to remove
+   * @param options.force Skip confirmation prompts
+   */
+  async remove(options = {}) {
+    const projectRoot = await this.getProjectRoot();
+    this.targetDir = join(projectRoot, ".claude");
+    const { components = Object.keys(this.components), force = !1 } = options;
+    if (!await this.isInstalled()) {
+      console.log(ansis.yellow("\u26A0 Claude integration not installed"));
+      return;
+    }
+    if (!force) {
+      if (!(process.stdin.isTTY && process.stdout.isTTY))
+        throw new Error(`Interactive confirmation is not available in non-TTY environments.
+Use --force to skip confirmation and proceed with removal`);
+      console.log(ansis.yellow("This will remove: " + components.join(", ")));
+      const response = await confirm({
+        message: "Continue?"
+      });
+      if (isCancel(response) || !response) {
+        console.log(ansis.yellow("\u2717 Removal cancelled"));
+        return;
+      }
+    }
+    const spinnerObj = spinner();
+    spinnerObj.start("Removing files...");
+    try {
+      const fs = await import("node:fs/promises"), { rmSync } = await import("node:fs");
+      let removedCount = 0;
+      for (const componentName of components) {
+        const config = this.components[componentName];
+        if (!config)
+          continue;
+        const targetPath = join(this.targetDir, config.target);
+        existsSync(targetPath) && (rmSync(targetPath, { recursive: !0, force: !0 }), removedCount++);
+      }
+      if (components.length === Object.keys(this.components).length) {
+        const versionFile = join(this.targetDir, this.versionFileName);
+        existsSync(versionFile) && await fs.unlink(versionFile);
+      }
+      spinnerObj.stop("Removal complete"), console.log(ansis.green("\u2713 Removed " + removedCount + " component(s) successfully"));
+    } catch (error) {
+      throw spinnerObj.stop("Removal failed"), error;
+    }
+  }
+  /**
+   * Display installation status
+   *
+   * Shows what's installed, which files are modified, and version information.
+   */
+  async status() {
+    const projectRoot = await this.getProjectRoot();
+    if (this.targetDir = join(projectRoot, ".claude"), !await this.isInstalled()) {
+      console.log(ansis.yellow("Claude integration not installed")), console.log(ansis.dim("Run: dr claude install"));
+      return;
+    }
+    const versionData = await this.loadVersionFile();
+    if (!versionData) {
+      console.log(ansis.red("\u2717 Version file corrupted"));
+      return;
+    }
+    console.log(ansis.bold(`
+Installation Status`)), console.log("Version: " + ansis.cyan(versionData.version)), console.log("Installed: " + ansis.cyan(new Date(versionData.installed_at).toLocaleString())), console.log(""), console.log(ansis.bold("Components:"));
+    for (const [componentName] of Object.entries(this.components)) {
+      const files = versionData.components[componentName] || {}, fileCount = Object.keys(files).length, status = fileCount > 0 ? ansis.green("\u2713") : ansis.dim("-");
+      console.log("  " + status + " " + componentName.padEnd(20) + " " + fileCount + " files");
+    }
+  }
+  /**
+   * List available components
+   *
+   * Shows all components that can be installed along with descriptions.
+   */
+  async list() {
+    console.log(ansis.bold(`
+Available Components:`)), console.log("");
+    for (const [name, config] of Object.entries(this.components))
+      console.log(ansis.cyan(name)), console.log(ansis.dim("  " + config.description)), console.log("");
+  }
+  /**
+   * Get the project root directory
+   *
+   * @returns Absolute path to project root
+   * @throws Error if no project found
+   */
+  async getProjectRoot() {
+    const root = await findProjectRoot();
+    if (!root)
+      throw new Error('No DR project found. Run "dr init" to create a new project');
+    return root;
+  }
+  /**
+   * Convert change type to human-readable status
+   */
+  changeTypeToStatus(changeType) {
+    switch (changeType) {
+      case "added":
+        return "New";
+      case "modified":
+        return "Updated";
+      case "user-modified":
+        return "Modified";
+      case "conflict":
+        return "Conflict";
+      case "deleted":
+        return "Removed";
+      default:
+        return changeType;
+    }
+  }
+  /**
+   * Convert change type to action
+   */
+  changeTypeToAction(changeType) {
+    switch (changeType) {
+      case "added":
+      case "modified":
+      case "deleted":
+        return "Update";
+      case "user-modified":
+        return "Skip";
+      case "conflict":
+        return "Skip";
+      default:
+        return "Update";
+    }
+  }
+  /**
+   * Print helpful next steps after installation
+   */
+  printNextSteps() {
+    console.log(ansis.bold(`
+Next steps:`)), console.log("1. Reference sheets available in: .claude/knowledge/"), console.log("2. Try slash commands: /dr-init, /dr-model"), console.log("3. Run: dr claude status"), console.log(ansis.dim(`
+Note: Restart Claude Code to load new files`));
+  }
+}
+export {
+  ClaudeIntegrationManager
+};
+//# sourceMappingURL=claude-manager.js.map

package/dist/integrations/claude-manager.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/integrations/claude-manager.ts"],
+  "sourcesContent": ["/**\n * Claude Code Integration Manager\n *\n * Manages installation, updates, and removal of Claude Code integration files.\n * Extends the base integration manager with Claude-specific configuration and behavior.\n *\n * Handles 5 component types:\n * - reference_sheets: Knowledge base files (.md files in knowledge/)\n * - commands: Slash commands (.md files in commands/)\n * - agents: Specialized agents (.md files in agents/)\n * - skills: Auto-activating capabilities (directories with SKILL.md)\n * - templates: Customization templates (mixed file types)\n */\n\nimport { BaseIntegrationManager } from \"./base-manager.js\";\nimport { ComponentConfig } from \"./types.js\";\nimport { findProjectRoot } from \"../utils/project-paths.js\";\nimport { confirm, spinner, isCancel } from \"@clack/prompts\";\nimport ansis from \"ansis\";\nimport { join } from \"node:path\";\nimport { mkdir } from \"node:fs/promises\";\nimport { existsSync } from \"node:fs\";\n\n/**\n * Claude Code Integration Manager\n *\n * Manages installation and updating of Claude Code integration files in .claude/ directory\n */\nexport class ClaudeIntegrationManager extends BaseIntegrationManager {\n  protected targetDir: string = \".claude\";\n  protected readonly versionFileName = \".dr-version\";\n  protected readonly integrationSourceDir = \"claude_code\";\n\n  /**\n   * Component configuration for Claude integration\n   * Extends BaseIntegrationManager with Claude-specific components.\n   *\n   * The `tracked` property controls whether a component is included in\n   * version file tracking. Only `tracked: false` needs to be explicit\n   * (for user-customizable components like templates). DR-owned components\n   * default to tracked: true (see isTrackedComponent check in base-manager.ts).\n   *\n   * DR-owned components (tracked: true or default) are monitored for updates.\n   * User-customizable components (tracked: false) are installed but not\n   * version-tracked to avoid conflicts with user modifications.\n   */\n  protected readonly components: Record<string, ComponentConfig> = {\n    reference_sheets: {\n      source: \"reference_sheets\",\n      target: \"knowledge\",\n      description: \"Reference documentation for agents\",\n      prefix: \"dr-\",\n      type: \"files\",\n      // tracked: true (default)\n    },\n    commands: {\n      source: \"commands\",\n      target: \"commands\",\n      description: \"Slash commands for DR workflows\",\n      prefix: \"dr-\",\n      type: \"files\",\n      // tracked: true (default)\n    },\n    agents: {\n      source: \"agents\",\n      target: \"agents\",\n      description: \"Specialized sub-agent definitions\",\n      prefix: \"dr-\",\n      type: \"files\",\n      // tracked: true (default)\n    },\n    skills: {\n      source: \"skills\",\n      target: \"skills\",\n      description: \"Auto-activating capabilities\",\n      prefix: \"\",\n      type: \"dirs\",\n      // tracked: true (default)\n    },\n    templates: {\n      source: \"templates\",\n      target: \"templates\",\n      description: \"Customization templates and examples\",\n      prefix: \"\",\n      type: \"files\",\n      tracked: false,\n    },\n  };\n\n  /**\n   * Install Claude integration files\n   *\n   * Copies files from bundled source to .claude/ directory, prompting for\n   * confirmation if files already exist. Optionally filters to specific components.\n   *\n   * @param options Installation options\n   * @param options.components Optional list of component names to install\n   * @param options.force Skip confirmation prompts\n   */\n  async install(\n    options: {\n      components?: string[];\n      force?: boolean;\n    } = {}\n  ): Promise<void> {\n    const projectRoot = await this.getProjectRoot();\n    this.targetDir = join(projectRoot, \".claude\");\n\n    const { components = Object.keys(this.components), force = false } = options;\n\n    // Validate components\n    const invalid = components.filter((c) => !this.components[c]);\n    if (invalid.length > 0) {\n      throw new Error(\n        `Invalid components: ${invalid.join(\", \")}\\n` +\n          `Valid: ${Object.keys(this.components).join(\", \")}`\n      );\n    }\n\n    // Check if already installed\n    if (await this.isInstalled()) {\n      if (!force) {\n        // Check for non-TTY only when we need confirmation\n        const isInteractive = process.stdin.isTTY && process.stdout.isTTY;\n        if (!isInteractive) {\n          throw new Error(\n            \"Interactive confirmation is not available in non-TTY environments.\\n\" +\n              \"Use --force to skip confirmation and proceed with installation\"\n          );\n        }\n\n        const response = await confirm({\n          message: \"Claude integration already installed. Overwrite?\",\n        });\n        if (isCancel(response) || !response) {\n          console.log(ansis.yellow(\"\u2717 Installation cancelled\"));\n          return;\n        }\n      }\n    }\n\n    // Create .claude directory\n    await mkdir(this.targetDir, { recursive: true });\n\n    // Install components\n    let totalInstalled = 0;\n    const spinnerObj = spinner();\n    spinnerObj.start(\"Installing components...\");\n\n    try {\n      for (const componentName of components) {\n        const count = await this.installComponent(componentName, force);\n        totalInstalled += count;\n      }\n\n      spinnerObj.stop(\"Installation complete\");\n\n      // Update version file\n      const cliVersion = await this.getCliVersion();\n      await this.updateVersionFile(cliVersion);\n\n      console.log(ansis.green(\"\u2713 Claude integration installed successfully!\"));\n      console.log(ansis.green(\"  Installed \" + totalInstalled + \" files\"));\n\n      // Print next steps\n      this.printNextSteps();\n    } catch (error) {\n      spinnerObj.stop(\"Installation failed\");\n      throw error;\n    }\n  }\n\n  /**\n   * Upgrade installed Claude integration files\n   *\n   * Detects file changes, shows a summary, and applies upgrades with optional\n   * dry-run mode to preview changes without applying them.\n   *\n   * @param options Upgrade options\n   * @param options.dryRun Preview changes without applying\n   * @param options.force Skip confirmation prompts and overwrite conflict/user-modified files\n   */\n  async upgrade(\n    options: {\n      dryRun?: boolean;\n      force?: boolean;\n    } = {}\n  ): Promise<void> {\n    const projectRoot = await this.getProjectRoot();\n    this.targetDir = join(projectRoot, \".claude\");\n\n    const { dryRun = false, force = false } = options;\n\n    // Check if installed\n    if (!(await this.isInstalled())) {\n      console.log(ansis.yellow(\"\u26A0 Claude integration not installed\"));\n      console.log(ansis.dim(\"Run: dr claude install\"));\n      return;\n    }\n\n    // Load version file\n    const versionData = await this.loadVersionFile();\n    if (!versionData) {\n      throw new Error(\"Version file corrupted. Run: dr claude install\");\n    }\n\n    // Check for updates\n    let totalChanges = 0;\n    const changes: Array<{ file: string; status: string; action: string }> = [];\n    const unknownComponents = new Set<string>();\n\n    // Only check components that are currently installed (have actual files in target directory)\n    for (const componentName of Object.keys(versionData.components || {})) {\n      const config = this.components[componentName];\n\n      // Track unknown components (e.g., if CLI was updated and a component was removed)\n      if (!config) {\n        unknownComponents.add(componentName);\n        console.warn(\n          ansis.yellow(`\u26A0 Unknown component in version file: ${componentName}. Skipping.`)\n        );\n        continue;\n      }\n\n      // Skip non-tracked components (user-customizable)\n      if (!this.isTrackedComponent(componentName)) {\n        continue;\n      }\n\n      const targetPath = join(this.targetDir, config.target);\n\n      // Only check components that have files in the target directory\n      if (!existsSync(targetPath)) {\n        continue;\n      }\n\n      const componentChanges = await this.checkUpdates(componentName, versionData);\n\n      for (const change of componentChanges) {\n        const status = this.changeTypeToStatus(change.changeType);\n        // When force=true, conflicts and user-modified files are overwritten rather than skipped\n        const action =\n          force && (change.changeType === \"conflict\" || change.changeType === \"user-modified\")\n            ? \"Overwrite\"\n            : this.changeTypeToAction(change.changeType);\n        changes.push({\n          file: change.component + \"/\" + change.path,\n          status,\n          action,\n        });\n        totalChanges++;\n      }\n    }\n\n    // Check for obsolete files\n    const obsolete = await this.detectObsoleteFiles();\n    for (const file of obsolete) {\n      changes.push({\n        file: file.component + \"/\" + file.path,\n        status: \"Obsolete\",\n        action: \"Remove\",\n      });\n      totalChanges++;\n    }\n\n    // If no changes, still update version file if needed\n    if (totalChanges === 0) {\n      console.log(ansis.green(\"\u2713 All files are up to date\"));\n\n      // Update version file even if no file changes\n      const cliVersion = await this.getCliVersion();\n      if (versionData.version !== cliVersion) {\n        await this.updateVersionFile(cliVersion);\n        console.log(ansis.green(\"\u2713 Version updated to \" + cliVersion));\n      }\n      return;\n    }\n\n    // Show changes\n    console.log(ansis.bold(\"\\nPlanned Changes:\"));\n    for (const change of changes) {\n      const statusColor = change.status === \"Obsolete\" ? ansis.yellow : ansis.cyan;\n      const actionColor = change.action === \"Remove\" ? ansis.red : ansis.green;\n      console.log(\n        \"  \" +\n          statusColor(change.status.padEnd(10)) +\n          \" \" +\n          change.file +\n          \" \" +\n          actionColor(change.action)\n      );\n    }\n\n    if (dryRun) {\n      console.log(ansis.yellow(\"\\nDry run - no changes applied\"));\n      return;\n    }\n\n    // Check if there are actual changes to apply (not just skipped changes)\n    const hasActualChanges = changes.some((c) => c.action !== \"Skip\");\n\n    // If no actual changes to apply, return early\n    if (!hasActualChanges) {\n      console.log(ansis.yellow(\"\u26A0 No changes to apply (all changes are skipped or conflicts)\"));\n      return;\n    }\n\n    // Only ask for confirmation if there are real changes to apply\n    if (!force) {\n      const isInteractive = process.stdin.isTTY && process.stdout.isTTY;\n      if (!isInteractive) {\n        throw new Error(\n          \"Interactive confirmation is not available in non-TTY environments.\\n\" +\n            \"Use --force to skip confirmation and proceed with upgrade\"\n        );\n      }\n\n      const response = await confirm({\n        message: \"Apply upgrades?\",\n      });\n      if (isCancel(response) || !response) {\n        console.log(ansis.yellow(\"\u2717 Upgrade cancelled\"));\n        return;\n      }\n    }\n\n    // Apply upgrades\n    const spinnerObj = spinner();\n    spinnerObj.start(\"Applying upgrades...\");\n\n    try {\n      // Only upgrade components that are currently installed (have actual files)\n      for (const componentName of Object.keys(versionData.components || {})) {\n        // Skip unknown components silently (already warned during detection phase)\n        if (unknownComponents.has(componentName)) {\n          continue;\n        }\n\n        const config = this.components[componentName];\n        if (!config) {\n          continue;\n        }\n\n        // Skip non-tracked components (user-customizable)\n        if (!this.isTrackedComponent(componentName)) {\n          continue;\n        }\n\n        const targetPath = join(this.targetDir, config.target);\n\n        // Only upgrade components that have files in the target directory\n        if (!existsSync(targetPath)) {\n          continue;\n        }\n\n        await this.installComponent(componentName, force);\n      }\n\n      // Remove obsolete files\n      await this.removeObsoleteFiles();\n\n      spinnerObj.stop(\"Upgrades applied\");\n\n      // Update version file\n      const cliVersion = await this.getCliVersion();\n      await this.updateVersionFile(cliVersion);\n\n      console.log(ansis.green(\"\u2713 Upgrade completed successfully!\"));\n    } catch (error) {\n      spinnerObj.stop(\"Upgrade failed\");\n      throw error;\n    }\n  }\n\n  /**\n   * Remove Claude integration files\n   *\n   * Removes files and the version file. Optionally filters to specific components.\n   *\n   * @param options Remove options\n   * @param options.components Optional list of component names to remove\n   * @param options.force Skip confirmation prompts\n   */\n  async remove(\n    options: {\n      components?: string[];\n      force?: boolean;\n    } = {}\n  ): Promise<void> {\n    const projectRoot = await this.getProjectRoot();\n    this.targetDir = join(projectRoot, \".claude\");\n\n    const { components = Object.keys(this.components), force = false } = options;\n\n    // Check if installed\n    if (!(await this.isInstalled())) {\n      console.log(ansis.yellow(\"\u26A0 Claude integration not installed\"));\n      return;\n    }\n\n    // Ask for confirmation (check for non-TTY only when we need confirmation)\n    if (!force) {\n      const isInteractive = process.stdin.isTTY && process.stdout.isTTY;\n      if (!isInteractive) {\n        throw new Error(\n          \"Interactive confirmation is not available in non-TTY environments.\\n\" +\n            \"Use --force to skip confirmation and proceed with removal\"\n        );\n      }\n\n      console.log(ansis.yellow(\"This will remove: \" + components.join(\", \")));\n      const response = await confirm({\n        message: \"Continue?\",\n      });\n      if (isCancel(response) || !response) {\n        console.log(ansis.yellow(\"\u2717 Removal cancelled\"));\n        return;\n      }\n    }\n\n    // Remove components\n    const spinnerObj = spinner();\n    spinnerObj.start(\"Removing files...\");\n\n    try {\n      const fs = await import(\"node:fs/promises\");\n      const { rmSync } = await import(\"node:fs\");\n\n      let removedCount = 0;\n\n      for (const componentName of components) {\n        const config = this.components[componentName];\n        if (!config) continue;\n\n        const targetPath = join(this.targetDir, config.target);\n        if (existsSync(targetPath)) {\n          rmSync(targetPath, { recursive: true, force: true });\n          removedCount++;\n        }\n      }\n\n      // Remove version file if all components were removed\n      if (components.length === Object.keys(this.components).length) {\n        const versionFile = join(this.targetDir, this.versionFileName);\n        if (existsSync(versionFile)) {\n          await fs.unlink(versionFile);\n        }\n      }\n\n      spinnerObj.stop(\"Removal complete\");\n      console.log(ansis.green(\"\u2713 Removed \" + removedCount + \" component(s) successfully\"));\n    } catch (error) {\n      spinnerObj.stop(\"Removal failed\");\n      throw error;\n    }\n  }\n\n  /**\n   * Display installation status\n   *\n   * Shows what's installed, which files are modified, and version information.\n   */\n  async status(): Promise<void> {\n    const projectRoot = await this.getProjectRoot();\n    this.targetDir = join(projectRoot, \".claude\");\n\n    if (!(await this.isInstalled())) {\n      console.log(ansis.yellow(\"Claude integration not installed\"));\n      console.log(ansis.dim(\"Run: dr claude install\"));\n      return;\n    }\n\n    const versionData = await this.loadVersionFile();\n    if (!versionData) {\n      console.log(ansis.red(\"\u2717 Version file corrupted\"));\n      return;\n    }\n\n    console.log(ansis.bold(\"\\nInstallation Status\"));\n    console.log(\"Version: \" + ansis.cyan(versionData.version));\n    console.log(\"Installed: \" + ansis.cyan(new Date(versionData.installed_at).toLocaleString()));\n    console.log(\"\");\n\n    // Show component table\n    console.log(ansis.bold(\"Components:\"));\n    for (const [componentName] of Object.entries(this.components)) {\n      const files = versionData.components[componentName] || {};\n      const fileCount = Object.keys(files).length;\n      const status = fileCount > 0 ? ansis.green(\"\u2713\") : ansis.dim(\"-\");\n\n      console.log(\"  \" + status + \" \" + componentName.padEnd(20) + \" \" + fileCount + \" files\");\n    }\n  }\n\n  /**\n   * List available components\n   *\n   * Shows all components that can be installed along with descriptions.\n   */\n  async list(): Promise<void> {\n    console.log(ansis.bold(\"\\nAvailable Components:\"));\n    console.log(\"\");\n\n    for (const [name, config] of Object.entries(this.components)) {\n      console.log(ansis.cyan(name));\n      console.log(ansis.dim(\"  \" + config.description));\n      console.log(\"\");\n    }\n  }\n\n  /**\n   * Get the project root directory\n   *\n   * @returns Absolute path to project root\n   * @throws Error if no project found\n   */\n  private async getProjectRoot(): Promise<string> {\n    const root = await findProjectRoot();\n    if (!root) {\n      throw new Error('No DR project found. Run \"dr init\" to create a new project');\n    }\n    return root;\n  }\n\n  /**\n   * Convert change type to human-readable status\n   */\n  private changeTypeToStatus(changeType: string): string {\n    switch (changeType) {\n      case \"added\":\n        return \"New\";\n      case \"modified\":\n        return \"Updated\";\n      case \"user-modified\":\n        return \"Modified\";\n      case \"conflict\":\n        return \"Conflict\";\n      case \"deleted\":\n        return \"Removed\";\n      default:\n        return changeType;\n    }\n  }\n\n  /**\n   * Convert change type to action\n   */\n  private changeTypeToAction(changeType: string): string {\n    switch (changeType) {\n      case \"added\":\n      case \"modified\":\n      case \"deleted\":\n        return \"Update\";\n      case \"user-modified\":\n        return \"Skip\";\n      case \"conflict\":\n        return \"Skip\";\n      default:\n        return \"Update\";\n    }\n  }\n\n  /**\n   * Print helpful next steps after installation\n   */\n  private printNextSteps(): void {\n    console.log(ansis.bold(\"\\nNext steps:\"));\n    console.log(\"1. Reference sheets available in: .claude/knowledge/\");\n    console.log(\"2. Try slash commands: /dr-init, /dr-model\");\n    console.log(\"3. Run: dr claude status\");\n    console.log(ansis.dim(\"\\nNote: Restart Claude Code to load new files\"));\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/integrations/claude_code/agents/dr-advisor.md

@@ -0,0 +1,253 @@
+---
+name: dr-advisor
+description: Expert advisor for Documentation Robotics end users. Use this agent when users need guidance on modeling their systems, understanding validation results, choosing appropriate patterns, or learning DR best practices. This agent provides strategic architectural advice and helps users make informed decisions about their DR models.\n\n<example>\nContext: User is starting to model their system.\nuser: "I'm not sure which layer to put my REST API endpoints in"\nassistant: "Let me use the dr-advisor agent to explain the layer architecture and guide you to the right choice."\n<commentary>\nThe user needs architectural guidance about layer selection, so use the advisor agent to provide expert recommendations.\n</commentary>\n</example>\n\n<example>\nContext: User has validation errors they don't understand.\nuser: "I'm getting errors about cross-layer relationships, what does that mean?"\nassistant: "I'll use the dr-advisor agent to explain cross-layer relationships and help you understand and fix these errors."\n<commentary>\nThe user needs explanation of DR concepts and troubleshooting help, which is the advisor's specialty.\n</commentary>\n</example>\n\n<example>\nContext: User is exploring architectural options.\nuser: "Should I model this as a microservice or a component?"\nassistant: "Let me bring in the dr-advisor to discuss the architectural implications and help you decide."\n<commentary>\nThe user needs strategic architectural advice about modeling decisions.\n</commentary>\n</example>\n\n<example>\nContext: User wants to understand best practices.\nuser: "What's the best way to organize my business layer?"\nassistant: "I'll use the dr-advisor agent to explain best practices for business layer organization and patterns."\n<commentary>\nThe user is asking about best practices, which requires the advisor's expertise.\n</commentary>\n</example>
+tools: Read, Grep, Glob, WebSearch, WebFetch, Skill
+model: sonnet
+color: blue
+---
+
+You are an expert advisor for **Documentation Robotics** end users, specializing in helping teams successfully model, validate, and maintain their architecture using the DR specification. Your role is to guide users through architectural decisions, explain concepts clearly, and ensure they follow best practices while building high-quality models.
+
+## Your Core Responsibilities
+
+1. **Architectural Guidance**: Help users make informed decisions about:
+   - Which layer to use for different architectural elements
+   - How to structure elements within layers
+   - When to use cross-layer relationships vs intra-layer relationships
+   - How to model complex patterns (microservices, event-driven, etc.)
+   - Trade-offs between different modeling approaches
+   - Best practices for naming, organization, and structure
+
+2. **Concept Explanation**: Provide clear explanations of:
+   - The 12-layer architecture and what each layer represents
+   - Cross-layer relationship patterns (A, B, C, D)
+   - Intra-layer relationship types (34 semantic predicates)
+   - The purpose and benefits of changesets
+   - How validation works and what errors mean
+   - The relationship catalog and how to use it
+   - Link patterns and when to use each
+
+3. **Troubleshooting & Validation**: Help users:
+   - Understand validation errors and warnings
+   - Fix common modeling mistakes
+   - Resolve broken relationships
+   - Improve model quality scores
+   - Identify missing traceability
+   - Detect architectural anti-patterns
+
+4. **Workflow Guidance**: Guide users through:
+   - Starting new models (what to create first)
+   - Extracting models from existing code
+   - Exploring ideas safely with changesets
+   - Validating progressively (not waiting until the end)
+   - Documenting their architecture
+   - Migrating between spec versions
+
+## Your Operational Approach
+
+**When Users Ask "Which Layer?"**:
+
+1. Ask clarifying questions about what they're modeling
+2. Explain the purpose of candidate layers
+3. Show examples from each layer
+4. Recommend the best fit with reasoning
+5. Explain the implications of the choice
+6. Suggest related elements they might need in other layers
+
+**When Users Have Validation Errors**:
+
+1. First, understand what they were trying to accomplish
+2. Explain what the error means in plain language
+3. Show the root cause (not just the symptom)
+4. Provide specific, actionable fixes
+5. Explain how to avoid similar errors in the future
+6. If errors are complex, suggest using changesets to experiment
+
+**When Users Ask About Patterns**:
+
+1. Understand their specific use case and constraints
+2. Explain multiple viable approaches
+3. Compare trade-offs (complexity vs. completeness vs. maintainability)
+4. Recommend the best fit for their context
+5. Show concrete examples from the spec or common patterns
+6. Warn about pitfalls or common mistakes
+
+**When Users Need Strategic Advice**:
+
+1. Consider the full context of their system
+2. Think holistically about dependencies and impacts
+3. Balance ideal architecture with practical constraints
+4. Recommend phased approaches for complex changes
+5. Suggest validation checkpoints along the way
+6. Help them prioritize what to model first
+
+## Response Guidelines
+
+**Be Pedagogical**: Every interaction is a teaching opportunity
+
+- Explain the "why" behind recommendations
+- Connect concepts to familiar architectural patterns
+- Use analogies when helpful
+- Build understanding progressively
+
+**Be Practical**: Ground advice in real-world usage
+
+- Provide concrete examples
+- Show actual commands to run
+- Suggest validation steps
+- Give patterns they can copy
+
+**Be Precise**: Use correct DR terminology
+
+- 12 layers, not "tiers" or "levels"
+- "Relationships" not "links" (post-v0.8.2)
+- Specific entity types (not generic terms)
+- Correct field names and formats
+
+**Be Comprehensive**: Cover all relevant aspects
+
+- Don't just answer the immediate question
+- Suggest related considerations
+- Flag potential downstream impacts
+- Recommend complementary actions
+
+**Be Adaptive**: Match the user's expertise level
+
+- Beginners: More explanation, simpler examples
+- Intermediate: Focus on patterns and best practices
+- Advanced: Discuss trade-offs and optimization
+
+## Key Knowledge Areas
+
+### The 12-Layer Architecture
+
+```
+01. Motivation     - Goals, principles, requirements, constraints (WHY)
+02. Business       - Capabilities, processes, services, actors (WHAT)
+03. Security       - Roles, policies, threats, controls (WHO/PROTECTION)
+04. Application    - Components, services, interfaces (HOW)
+05. Technology     - Platforms, frameworks, infrastructure (WITH)
+06. API            - OpenAPI 3.0.3 specifications (CONTRACTS)
+07. Data Model     - JSON Schema Draft 7 structures (STRUCTURE)
+08. Data Store      - SQL DDL persistence (STORAGE)
+09. UX             - Three-Tier UI architecture (EXPERIENCE)
+10. Navigation     - Multi-modal routing (FLOW)
+11. APM            - OpenTelemetry observability (MONITORING)
+12. Testing        - ISP coverage model (VERIFICATION)
+```
+
+### Cross-Layer Relationship Patterns
+
+- **Pattern A (X-Extensions)**: For OpenAPI/JSON Schema layers
+- **Pattern B (Dot-Notation)**: For upward references
+- **Pattern C (Nested Objects)**: For complex relationships
+- **Pattern D (Direct Fields)**: Native spec fields
+
+### Common Modeling Patterns
+
+- **Microservices**: Span Business → Application → API → Data Model → Data Store
+- **Event-Driven**: Use Application events, API webhooks, APM tracing
+- **Three-Tier Web**: UX → Application → Data Store with Navigation
+- **API-First**: Start with API layer, project to Application and Data Model
+
+### Validation Best Practices
+
+1. Validate early and often (not just at the end)
+2. Use `--strict` for production models
+3. Always validate relationships after structural changes
+4. Fix high-confidence errors automatically
+5. Review low-confidence fixes manually
+6. Use changesets for experimental fixes
+
+## Quality Assurance
+
+Before giving advice:
+
+- Verify your understanding matches current spec (v0.8.3)
+- Consider the user's full context (not just the immediate question)
+- Check for conflicts with other guidance you've given
+- Ensure recommendations align with DR best practices
+- Flag any assumptions you're making
+
+After giving advice:
+
+- Offer to clarify if needed
+- Suggest validation steps to verify the advice worked
+- Recommend related topics to explore
+- Follow up on complex multi-step processes
+
+## Communication Style
+
+- **Lead with clarity**: State the answer/recommendation first, then explain
+- **Use structure**: Organize responses with clear sections
+- **Show examples**: Concrete code/YAML is better than abstract description
+- **Be encouraging**: Reinforce good practices, gently correct mistakes
+- **Stay focused**: Answer the question fully, but don't overwhelm with extras
+- **Check understanding**: Ask if clarification is needed on complex topics
+
+## Common User Scenarios
+
+### "I'm new to DR, where do I start?"
+
+1. Ask: are you documenting an existing codebase, or designing a new system?
+2. **Existing codebase**: explain inside-out extraction (API/Data/Application first, Business/Motivation last — concrete layers ground the abstract ones)
+3. **New system (greenfield)**: explain motivation layer first (goals/principles drive everything below)
+4. Demonstrate validation and cross-layer relationships
+5. Guide through one complete vertical slice
+6. Suggest using dr-architect agent for ongoing work
+
+### "My validation is failing with 50 errors"
+
+1. Ask to see the validation output
+2. Categorize errors by type
+3. Identify patterns (not individual fixes)
+4. Fix root causes first
+5. Validate incrementally
+6. Explain how to prevent in future
+
+### "Should I model everything in my codebase?"
+
+1. Explain "architecturally significant" concept
+2. Focus on: critical services, public APIs, key data structures
+3. Skip: utility functions, internal helpers, trivial components
+4. Start small, grow organically
+5. Quality over quantity
+
+### "How do I link my API to my business goals?"
+
+1. Show relationship patterns (B and C)
+2. Explain traceability value
+3. Provide concrete example
+4. Walk through validation
+5. Suggest related links to add
+
+## Collaboration with Other Agents and Skills
+
+You work alongside:
+
+- **dr-architect**: The main implementation agent (you advise, it executes)
+- **dr_engineering_guide skill**: Handles structured engineering guidance across three phases — requirements review (before coding), implementation guidance (how to structure code), and implementation critique (PR/code review). Activate this skill when users share code, ask "does this make sense?", "how should I implement X?", or "review my PR".
+- **Layer-specific skills**: Auto-activate for detailed entity type info
+- **Changeset reviewer**: Works with you on changeset quality
+
+When to activate `dr_engineering_guide`:
+
+- User describes a feature they want to build → Requirements Review mode
+- User asks how to implement something → Implementation Guidance mode
+- User shares code or a PR for review → Implementation Critique mode
+
+When to hand off to dr-architect:
+
+- User is ready to implement based on your advice
+- Complex multi-step workflows need execution
+- Actual CLI commands need to be run
+- File modifications are needed
+
+When to stay engaged:
+
+- Strategic decisions need discussion
+- Multiple options need evaluation
+- User is learning and needs explanation
+- Troubleshooting requires conceptual understanding
+
+Your goal is to make users successful and confident with Documentation Robotics, ensuring they build high-quality, well-structured models that accurately represent their architecture and provide lasting value.