@nolrm/contextkit 0.15.1 → 0.17.0

package/README.md

@@ -62,8 +62,8 @@ Perfect for teams where members use different AI tools:
 contextkit install claude   # or: contextkit install (interactive picker)
 
 # Each additional team member adds their platform
-ck claude      # creates CLAUDE.md + .claude/rules/
-ck cursor      # creates .cursor/rules/ (scoped .mdc files)
+ck claude      # creates CLAUDE.md + .claude/rules/ — skips if already up to date
+ck cursor      # creates .cursor/rules/ (scoped .mdc files) — skips if already up to date
 ck copilot     # creates .github/copilot-instructions.md
 ck codex       # creates AGENTS.md
 ck opencode    # creates AGENTS.md
@@ -114,7 +114,7 @@ Each platform generates bridge files that the AI tool auto-reads. If a bridge fi
 /fix        # diagnose and fix bugs
 ```
 
-**Claude Code** — `CLAUDE.md` uses `@` imports to auto-load all standards into context every session (no manual reads needed, saves tokens). Skills in `.claude/skills/`.
+**Claude Code** — `CLAUDE.md` uses `@` imports to auto-load all standards into context every session (no manual reads needed, saves tokens). Skills in `.claude/skills/`. Also writes a PostToolUse hook to `.claude/settings.json` that runs format+lint after every file edit — auto-detected for Node.js (npm/pnpm/yarn/bun), Go, and Python.
 
 ```bash
 /analyze    # scan codebase and generate standards
@@ -154,7 +154,7 @@ ContextKit installs reusable slash commands for supported platforms:
 | `/refactor`            | Refactor code with safety checks                                                                                                |
 | `/test`                | Generate comprehensive tests                                                                                                    |
 | `/doc`                 | Add documentation                                                                                                               |
-| `/doc-arch`            | Generate architecture docs (`docs/architecture.md`) — stack-aware (Level 1)                                                     |
+| `/doc-arch`            | Generate architecture docs — stack-aware (Level 1). Output: `docs/<topic>.md`, or `docs/architecture.md` if no topic given. Pass a topic name, PR number, or leave blank to infer from branch. |
 | `/doc-feature`         | Generate feature-level docs (`docs/features/<name>.md`) — stack-aware (Level 2)                                                 |
 | `/doc-component`       | Generate component-level docs colocated with the target file — stack-aware (Level 3)                                            |
 | `/spec`                | Write a component spec (MD-first) before any code is created                                                                    |
@@ -182,6 +182,8 @@ Both platforms delegate to the universal command files in `.contextkit/commands/
 
 The squad workflow turns a single AI session into a structured multi-role pipeline. Each role has its own slash command that reads and writes to a shared handoff file (`.contextkit/squad/handoff.md`), simulating a team of specialists.
 
+> **Squad works standalone.** If `.contextkit/` isn't set up, `/squad` will offer to create just `.contextkit/squad/` so you can use the pipeline without a full `ck install`.
+
 ### Pipeline Roles
 
 | Step | Role          | Command            | What it does                                                                                                                                                                                                   |
@@ -256,10 +258,14 @@ If you have a screenshot, mockup, or design image relevant to the task, paste or
 
 ---
 
-## Git Hooks & Quality Gates
+## Hooks & Quality Gates
+
+ContextKit installs two kinds of hooks. **Git hooks** (pre-push, commit-msg) enforce quality at push time for the whole team. For **Claude Code** installs, a **PostToolUse hook** is also written to `.claude/settings.json` — it runs format+lint after every file edit in a Claude Code session, catching failures immediately rather than at push time.
 
 ContextKit can optionally install Git hooks during `ck install`. Uses `git config core.hooksPath` to point Git at `.contextkit/hooks/` — no external dependencies like Husky required. Works in any git repo, not just Node.js projects.
 
+If an existing hooks manager is detected (Husky, Lefthook, simple-git-hooks, an existing `core.hooksPath`, or scripts in `.git/hooks/`), `ck install` will suggest how to integrate rather than overriding your setup.
+
 For **Node.js projects**, a `prepare` script is automatically added to `package.json` so hooks activate for all developers after `npm install` — no need for everyone to run `ck install`.
 
 If you enable the pre-push hook on a Node.js project that has no `format` or `lint` scripts, `ck install` will offer to scaffold a minimal **prettier + eslint** setup for you (adds scripts, `.prettierrc`, `.prettierignore`, `eslint.config.js`, and installs the devDependencies). Answer No to skip and set it up manually later.
@@ -368,8 +374,9 @@ Then add your Anthropic API key as a repository secret:
 # Installation & Setup
 ck install            # set up .contextkit + pick AI tool interactively
 ck install claude     # set up .contextkit + Claude, or add Claude to an existing install
-ck claude      # add Claude Code integration (CLAUDE.md + rules)
-ck cursor      # add Cursor integration (scoped .mdc rules)
+ck install --force    # regenerate all files, including user-customized standards
+ck claude      # add or refresh Claude integration — skips if already up to date
+ck cursor      # add or refresh Cursor integration — skips if already up to date
 ck copilot     # add GitHub Copilot integration
 ck codex       # add Codex CLI integration (AGENTS.md)
 ck opencode    # add OpenCode integration (AGENTS.md)
@@ -381,8 +388,9 @@ ck vscode      # alias for copilot
 
 # Analysis & Updates
 /analyze       # customize standards to your project (slash command in your AI tool)
-ck update      # pull latest commands/hooks — preserves your analyzed standards
-               # updates are also flagged automatically after each ck command (24h cache)
+ck update             # pull latest commands/hooks — never overwrites your standards or glossary
+ck update --force     # also regenerate user-owned files (standards, glossary)
+                      # updates are also flagged automatically after each ck command (24h cache)
 ck status      # check install & integrations
 
 # Validation & Compliance

package/bin/contextkit.js

@@ -27,6 +27,7 @@ program
   )
   .option('--no-hooks', 'Skip Git hooks installation')
   .option('--non-interactive', 'Skip interactive prompts')
+  .option('--force', 'Regenerate user-owned standards files even if they already exist')
   .action(async (platform, options) => {
     try {
       await install({ ...options, ...(platform ? { platform } : { fullInstall: true }) });
@@ -53,7 +54,7 @@ program
 program
   .command('update')
   .description('Update to latest version')
-  .option('--force', 'Force update even if no changes')
+  .option('--force', 'Force update even if no changes; also regenerates user-owned standards files')
   .action(async (options) => {
     try {
       await update(options);

package/lib/commands/analyze.js

@@ -167,9 +167,12 @@ class AnalyzeCommand {
         pathContext.tsconfig = await fs.readJson('tsconfig.json');
       }
 
-      // Detect frameworks and build tools for this path
-      pathContext.frameworks = await this.detectFrameworks();
-      pathContext.buildTools = await this.detectBuildTools();
+      // Detect primary language and frameworks/build tools for this path
+      const ProjectDetector = require('../utils/project-detector');
+      const primaryLanguage = new ProjectDetector().detectProjectType();
+      pathContext.primaryLanguage = primaryLanguage;
+      pathContext.frameworks = await this.detectFrameworks(primaryLanguage);
+      pathContext.buildTools = await this.detectBuildTools(primaryLanguage);
     } catch {
       // Continue even if one path fails
     } finally {
@@ -457,13 +460,17 @@ class AnalyzeCommand {
   }
 
   async detectProjectStructure() {
+    const ProjectDetector = require('../utils/project-detector');
+    const primaryLanguage = new ProjectDetector().detectProjectType();
+
     const structure = {
       hasSrc: await fs.pathExists('src'),
       hasApp: await fs.pathExists('src/app'),
       hasComponents: await fs.pathExists('src/components'),
       isMonorepo: (await fs.pathExists('packages')) || (await fs.pathExists('apps')),
-      frameworks: await this.detectFrameworks(),
-      buildTools: await this.detectBuildTools(),
+      primaryLanguage,
+      frameworks: await this.detectFrameworks(primaryLanguage),
+      buildTools: await this.detectBuildTools(primaryLanguage),
     };
 
     structure.type = structure.isMonorepo ? 'monorepo' : 'single-package';
@@ -471,26 +478,138 @@ class AnalyzeCommand {
     return structure;
   }
 
-  async detectFrameworks() {
+  // ── JS language types ───────────────────────────────────────────────────────
+  _isJsLanguage(primaryLanguage) {
+    return [
+      'node', 'react', 'react-vite', 'react-webpack', 'react-rollup',
+      'nextjs', 'vue', 'vue-vite', 'vue-webpack', 'nuxt', 'angular', 'svelte',
+    ].includes(primaryLanguage);
+  }
+
+  async detectFrameworks(primaryLanguage) {
+    // Non-JS projects: return language-appropriate framework info
+    if (!this._isJsLanguage(primaryLanguage)) {
+      return await this._detectNonJsFrameworks(primaryLanguage);
+    }
+
+    // JS projects: filesystem heuristics are appropriate
     const frameworks = [];
 
-    if (await fs.pathExists('src/components')) {
+    // Require both a dependency signal AND directory structure to avoid false positives
+    const hasPackageJson = await fs.pathExists('package.json');
+    let deps = {};
+    if (hasPackageJson) {
+      try {
+        const pkg = await fs.readJson('package.json');
+        deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      } catch {
+        // ignore
+      }
+    }
+
+    if ((deps.react || deps['@types/react']) && (await fs.pathExists('src/components'))) {
       frameworks.push('React');
     }
-    if (await fs.pathExists('src/pages')) {
+    if (deps.next && (await fs.pathExists('src/pages'))) {
       frameworks.push('Next.js');
     }
-    if (await fs.pathExists('src/views')) {
+    if ((deps.vue || deps['@vue/core']) && (await fs.pathExists('src/views'))) {
       frameworks.push('Vue');
     }
-    if (await fs.pathExists('angular.json')) {
+    if (deps['@angular/core'] && (await fs.pathExists('angular.json'))) {
       frameworks.push('Angular');
     }
 
+    // Fallback for cases where dependency exists but directories differ (still JS)
+    if (frameworks.length === 0 && (deps.react || deps['@types/react'])) {
+      frameworks.push('React');
+    }
+    if (frameworks.length === 0 && deps.next) {
+      frameworks.push('Next.js');
+    }
+    if (frameworks.length === 0 && (deps.vue || deps['@vue/core'])) {
+      frameworks.push('Vue');
+    }
+
+    return frameworks;
+  }
+
+  async _detectNonJsFrameworks(primaryLanguage) {
+    const frameworks = [];
+
+    if (primaryLanguage === 'go') {
+      frameworks.push('Go');
+      if (await fs.pathExists('go.mod')) {
+        try {
+          const goMod = await fs.readFile('go.mod', 'utf-8');
+          const moduleLine = goMod.split('\n').find((l) => l.startsWith('module '));
+          if (moduleLine) {
+            frameworks.push(`module:${moduleLine.replace('module ', '').trim()}`);
+          }
+        } catch {
+          // ignore
+        }
+      }
+      return frameworks;
+    }
+
+    if (primaryLanguage === 'python') {
+      frameworks.push('Python');
+      const depSources = ['requirements.txt', 'pyproject.toml'];
+      for (const src of depSources) {
+        if (await fs.pathExists(src)) {
+          try {
+            const content = await fs.readFile(src, 'utf-8');
+            if (/django/i.test(content)) frameworks.push('Django');
+            if (/flask/i.test(content)) frameworks.push('Flask');
+            if (/fastapi/i.test(content)) frameworks.push('FastAPI');
+          } catch {
+            // ignore
+          }
+          break;
+        }
+      }
+      return frameworks;
+    }
+
+    if (primaryLanguage === 'rust') {
+      frameworks.push('Rust');
+      return frameworks;
+    }
+
+    if (primaryLanguage === 'java') {
+      frameworks.push('Java');
+      return frameworks;
+    }
+
+    if (primaryLanguage === 'ruby') {
+      frameworks.push('Ruby');
+      if (await fs.pathExists('Gemfile')) {
+        try {
+          const gemfile = await fs.readFile('Gemfile', 'utf-8');
+          if (/rails/i.test(gemfile)) frameworks.push('Rails');
+        } catch {
+          // ignore
+        }
+      }
+      return frameworks;
+    }
+
+    if (primaryLanguage === 'php') {
+      frameworks.push('PHP');
+      return frameworks;
+    }
+
     return frameworks;
   }
 
-  async detectBuildTools() {
+  async detectBuildTools(primaryLanguage) {
+    // Non-JS projects: skip JS build tool checks, return relevant tools
+    if (!this._isJsLanguage(primaryLanguage)) {
+      return await this._detectNonJsBuildTools(primaryLanguage);
+    }
+
+    // JS projects: check JS build tool config files
     const tools = [];
 
     if ((await fs.pathExists('vite.config.js')) || (await fs.pathExists('vite.config.ts'))) {
@@ -506,6 +625,46 @@ class AnalyzeCommand {
     return tools;
   }
 
+  async _detectNonJsBuildTools(primaryLanguage) {
+    const tools = [];
+
+    if (primaryLanguage === 'go') {
+      if (await fs.pathExists('Makefile')) tools.push('Make');
+      if (
+        (await fs.pathExists('.goreleaser.yml')) ||
+        (await fs.pathExists('.goreleaser.yaml'))
+      ) {
+        tools.push('GoReleaser');
+      }
+      return tools;
+    }
+
+    if (primaryLanguage === 'python') {
+      if (await fs.pathExists('Makefile')) tools.push('Make');
+      if (await fs.pathExists('pyproject.toml')) tools.push('pyproject');
+      if (await fs.pathExists('setup.py')) tools.push('setuptools');
+      return tools;
+    }
+
+    if (primaryLanguage === 'rust') {
+      tools.push('Cargo');
+      if (await fs.pathExists('Makefile')) tools.push('Make');
+      return tools;
+    }
+
+    if (primaryLanguage === 'java') {
+      if (await fs.pathExists('pom.xml')) tools.push('Maven');
+      if (await fs.pathExists('build.gradle') || await fs.pathExists('build.gradle.kts')) {
+        tools.push('Gradle');
+      }
+      return tools;
+    }
+
+    if (await fs.pathExists('Makefile')) tools.push('Make');
+
+    return tools;
+  }
+
   async detectAITools() {
     const ToolDetector = require('../utils/tool-detector');
     const detector = new ToolDetector();

package/lib/commands/install.js

@@ -191,23 +191,69 @@ class InstallCommand {
   async addContextKitGitignoreEntries() {
     if (!(await fs.pathExists('.gitignore'))) return;
 
+    // Only runtime/ephemeral state belongs in .gitignore.
+    // Standards, commands, hooks, and platform integrations should be committed.
     const entries = [
       '.contextkit/status.json',
       '.contextkit/status.yml',
       '.contextkit/context.md',
       '.contextkit/squad/',
       '.contextkit/squad-done-*/',
+      '.contextkit/backup-*/',
     ];
 
+    const HEADER = '# ContextKit — runtime state (do not commit)';
+    const HEADER_LEGACY = '# ContextKit';
+
     try {
       const content = await fs.readFile('.gitignore', 'utf-8');
+
+      // Detect pre-existing ignore-all pattern (.contextkit/* or .contextkit/)
+      const hasIgnoreAll =
+        content.includes('.contextkit/*') || /^\.contextkit\/\s*$/m.test(content);
+
+      if (hasIgnoreAll) {
+        // Don't modify — add a helpful note as a comment so the user knows what to do
+        const hasNote = content.includes('# Note: the above ignores all of .contextkit/');
+        if (!hasNote) {
+          const separator = content.endsWith('\n') ? '' : '\n';
+          await fs.appendFile(
+            '.gitignore',
+            `${separator}# Note: the above ignores all of .contextkit/ — consider replacing it with:\n` +
+              `#   ${entries.join('\n#   ')}\n` +
+              `# This lets you commit standards/, commands/, hooks/, and product/ while ignoring runtime state.\n`
+          );
+          console.log(
+            chalk.yellow(
+              '⚠️  .gitignore already has .contextkit/* (ignore-all). Added guidance comment.'
+            )
+          );
+        }
+        return;
+      }
+
       const missing = entries.filter((e) => !content.includes(e));
       if (missing.length === 0) return;
 
-      const hasHeader = content.includes('# ContextKit');
-      const header = hasHeader ? '' : '\n# ContextKit\n';
-      const separator = content.endsWith('\n') ? '' : '\n';
+      // Update legacy header to new descriptive header if present
+      let updatedContent = content;
+      if (content.includes(HEADER_LEGACY) && !content.includes(HEADER)) {
+        updatedContent = content.replace(HEADER_LEGACY, HEADER);
+        await fs.writeFile('.gitignore', updatedContent);
+      }
+
+      const hasHeader =
+        updatedContent.includes(HEADER) || updatedContent.includes(HEADER_LEGACY);
+      const header = hasHeader ? '' : `\n${HEADER}\n`;
+      const separator = updatedContent.endsWith('\n') ? '' : '\n';
       await fs.appendFile('.gitignore', `${separator}${header}${missing.join('\n')}\n`);
+
+      console.log(chalk.green('✅ .gitignore updated — runtime state excluded'));
+      console.log(
+        chalk.dim(
+          '💡 Commit .contextkit/standards/ and .contextkit/commands/ — your team needs them'
+        )
+      );
     } catch (error) {
       console.log(chalk.yellow('⚠️  Could not update .gitignore:'), error.message);
     }
@@ -383,6 +429,18 @@ class InstallCommand {
     return { prePush, commitMsg };
   }
 
+  // ── User-owned file helper ──────────────────────────────────────────────────
+  // Writes a user-owned skeleton file only if it does not already exist.
+  // With force=true, overwrites existing content (warns before doing so).
+  async _writeUserOwnedFile(relativePath, content, force = false) {
+    const fullPath = `.contextkit/${relativePath}`;
+    if (!force && (await fs.pathExists(fullPath))) {
+      console.log(chalk.dim(`  ⏭  ${relativePath} already exists — skipping (use --force to regenerate)`));
+      return;
+    }
+    await fs.writeFile(fullPath, content);
+  }
+
   async createDirectoryStructure() {
     console.log(chalk.blue('📁 Creating structure...'));
 
@@ -679,11 +737,11 @@ This file is loaded when HTML-related tasks are detected:
     };
 
     for (const [relativePath, content] of Object.entries(skeletonFiles)) {
-      await fs.writeFile(`.contextkit/${relativePath}`, content);
+      await this._writeUserOwnedFile(relativePath, content, this._force);
     }
 
     for (const [relativePath, content] of Object.entries(granularCodeStyleFiles)) {
-      await fs.writeFile(`.contextkit/${relativePath}`, content);
+      await this._writeUserOwnedFile(relativePath, content, this._force);
     }
   }
 
@@ -805,11 +863,12 @@ Any design decisions, trade-offs, or open questions to resolve before coding.
     };
 
     for (const [relativePath, content] of Object.entries(skeletonFiles)) {
-      await fs.writeFile(`.contextkit/${relativePath}`, content);
+      await this._writeUserOwnedFile(relativePath, content, this._force);
     }
   }
 
-  async downloadFiles(projectType, _options = {}) {
+  async downloadFiles(projectType, options = {}) {
+    this._force = options.force || false;
     try {
       // Create skeleton standards files (will be customized by analyze)
       console.log(chalk.blue('📝 Creating skeleton standards files...'));

package/lib/commands/update.js

@@ -40,6 +40,9 @@ class UpdateCommand {
       );
     }
 
+    // Store force flag for use in downloadFiles
+    this._force = options.force || false;
+
     // Create backup
     const backupPath = await this.createBackup();
 
@@ -222,20 +225,33 @@ class UpdateCommand {
     return config;
   }
 
+  // ── User-owned file download helper ────────────────────────────────────────
+  // Downloads a file only if it does not already exist on disk.
+  // With force=true, always downloads (overwrites).
+  async _downloadUserOwnedFile(url, dest, force = false) {
+    if (!force && (await require('fs-extra').pathExists(dest))) {
+      console.log(chalk.dim(`  ⏭  ${dest} preserved (user-owned)`));
+      return;
+    }
+    await this.downloadManager.downloadFile(url, dest);
+  }
+
   async downloadFiles(projectType, config = {}) {
     const spinner = ora('Downloading latest files...').start();
 
     try {
       // Download only the real files (not skeleton files - those come from install)
+      // standards/README.md is CK-owned (attribution) — always update
       await this.downloadManager.downloadFile(
         `${this.repoUrl}/standards/README.md`,
         '.contextkit/standards/README.md'
       );
 
-      // Keep glossary updated (universal file)
-      await this.downloadManager.downloadFile(
+      // glossary.md is user-owned — only write if missing, never overwrite existing
+      await this._downloadUserOwnedFile(
         `${this.repoUrl}/standards/glossary.md`,
-        '.contextkit/standards/glossary.md'
+        '.contextkit/standards/glossary.md',
+        this._force
       );
 
       // Download commands

package/lib/integrations/base-integration.js

@@ -21,7 +21,46 @@ class BaseIntegration {
     this.platformDir = '';
   }
 
-  async install() {
+  // Returns true when all generated files exist AND the version in the bridge
+  // file matches the current package version. Returns false if anything is
+  // missing or outdated — triggering a full regeneration.
+  async isUpToDate() {
+    // All CK-generated files must be present
+    for (const file of this.generatedFiles) {
+      if (!(await fs.pathExists(file))) return false;
+    }
+
+    // If this integration has a bridge file, check the version embedded in it
+    if (this.bridgeFiles.length > 0) {
+      const bridgeFile = this.bridgeFiles[0];
+      if (!(await fs.pathExists(bridgeFile))) return false;
+
+      try {
+        const pkg = require('../../package.json');
+        const content = await fs.readFile(bridgeFile, 'utf-8');
+        const match = content.match(/Version:\s*([0-9]+\.[0-9]+\.[0-9]+)/);
+        if (!match || match[1] !== pkg.version) return false;
+      } catch {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  async install(force = false) {
+    if (!force && (await this.isUpToDate())) {
+      try {
+        const pkg = require('../../package.json');
+        console.log(
+          chalk.green(`  ✓ ${this.displayName} integration is up to date (v${pkg.version})`)
+        );
+      } catch {
+        console.log(chalk.green(`  ✓ ${this.displayName} integration is up to date`));
+      }
+      return;
+    }
+
     if (this.platformDir) {
       await fs.ensureDir(this.platformDir);
     }

package/lib/integrations/claude-integration.js

@@ -38,12 +38,31 @@ class ClaudeIntegration extends BaseIntegration {
     this.platformDir = '.claude/rules';
   }
 
-  async install() {
-    await super.install();
+  async install(force = false) {
+    await super.install(force);
     const fs = require('fs-extra');
     await fs.ensureDir('.claude/skills');
     await this.addToGitignore('.claude/settings.local.json');
     await this.removeLegacyFiles();
+    await this._installHook();
+  }
+
+  async _installHook() {
+    try {
+      const HookDetector = require('../utils/hook-detector');
+      const ClaudeSettings = require('../utils/claude-settings');
+      const command = await new HookDetector().detect();
+      if (command) {
+        await new ClaudeSettings().addPostToolUseHook(command);
+        console.log(chalk.green(`  ✓ PostToolUse hook: ${command}`));
+      } else {
+        console.log(
+          chalk.dim(chalk.yellow('  ⚠  No format/lint tooling detected — PostToolUse hook skipped'))
+        );
+      }
+    } catch (err) {
+      console.log(chalk.yellow(`  ⚠  Could not install PostToolUse hook: ${err.message}`));
+    }
   }
 
   async addToGitignore(entry) {

package/lib/integrations/claude-integration.md

@@ -0,0 +1,39 @@
+# claude-integration.js
+
+The Claude Code platform integration. Installs `CLAUDE.md`, `.claude/rules/`, `.claude/skills/`, and a PostToolUse hook in `.claude/settings.json`.
+
+## Extends
+
+`BaseIntegration`
+
+## install(force = false)
+
+Runs the full Claude Code setup:
+1. Writes bridge file (`CLAUDE.md`) and generated files (rules, skills) via `super.install()`
+2. Ensures `.claude/skills/` directory exists
+3. Adds `.claude/settings.local.json` to `.gitignore`
+4. Removes legacy `.claude/commands/` files
+5. Detects project tooling and installs a PostToolUse hook in `.claude/settings.json`
+
+### Hook Installation (step 5)
+
+Uses `HookDetector` to detect the right format+lint command for the project (Node.js, Go, or Python). If a command is found, `ClaudeSettings.addPostToolUseHook()` writes it to `.claude/settings.json` with a `_contextkit: true` marker.
+
+- On success: logs `✓ PostToolUse hook: <command>`
+- No tooling detected: logs a dim yellow skip message
+- Any error: logs a yellow warning and continues (graceful degradation)
+
+Re-running `install()` (e.g. via `ck update → refreshIntegrations()`) replaces the existing ContextKit hook rather than duplicating it.
+
+## generatedFiles
+
+Listed in the constructor. Does **not** include `.claude/settings.json` — that file is a merge target, not overwritten.
+
+## Key Files Written
+
+| File | Type | Purpose |
+|---|---|---|
+| `CLAUDE.md` | Bridge (merged) | Auto-loaded every Claude Code session |
+| `.claude/rules/contextkit-*.md` | Generated | Scoped rules for standards, testing, code style |
+| `.claude/skills/*/SKILL.md` | Generated | All slash commands |
+| `.claude/settings.json` | Merged | PostToolUse hook entry (`_contextkit: true`) |

package/lib/integrations/continue-integration.js

@@ -12,8 +12,8 @@ class ContinueIntegration extends BaseIntegration {
     this.platformDir = '.continue/rules';
   }
 
-  async install() {
-    await super.install();
+  async install(force = false) {
+    await super.install(force);
     // Remove old vibe-kit-named files
     const legacyFile = '.continue/rules/vibe-kit-standards.md';
     if (await fs.pathExists(legacyFile)) {

package/lib/integrations/cursor-integration.js

@@ -30,8 +30,8 @@ class CursorIntegration extends BaseIntegration {
     this.platformDir = '.cursor/rules';
   }
 
-  async install() {
-    await super.install();
+  async install(force = false) {
+    await super.install(force);
     await fs.ensureDir('.cursor/prompts');
     // Remove old monolithic rule file if present
     await this.removeLegacyFiles();

package/lib/integrations/windsurf-integration.js

@@ -11,8 +11,8 @@ class WindsurfIntegration extends BaseIntegration {
     this.platformDir = '.windsurf/rules';
   }
 
-  async install() {
-    await super.install();
+  async install(force = false) {
+    await super.install(force);
     // Remove old vibe-kit-named files
     const fs = require('fs-extra');
     const legacyFile = '.windsurf/rules/vibe-kit-standards.md';

package/lib/utils/claude-settings.js

@@ -0,0 +1,67 @@
+const fs = require('fs-extra');
+const chalk = require('chalk');
+
+const SETTINGS_PATH = '.claude/settings.json';
+
+class ClaudeSettings {
+  async read() {
+    if (!(await fs.pathExists(SETTINGS_PATH))) return {};
+    try {
+      const raw = await fs.readFile(SETTINGS_PATH, 'utf8');
+      return JSON.parse(raw);
+    } catch {
+      console.warn(
+        chalk.yellow(`  ⚠  .claude/settings.json contains invalid JSON — skipping hook merge`)
+      );
+      return {};
+    }
+  }
+
+  async write(settings) {
+    await fs.ensureDir('.claude');
+    await fs.writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+  }
+
+  async addPostToolUseHook(command) {
+    if (!command) throw new Error('hook command is required');
+
+    const settings = await this.read();
+    settings.hooks = settings.hooks || {};
+
+    if (!Array.isArray(settings.hooks.PostToolUse)) {
+      if (settings.hooks.PostToolUse !== undefined) {
+        settings.hooks._contextkit_original_invalid = settings.hooks.PostToolUse;
+      }
+      settings.hooks.PostToolUse = [];
+    }
+
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((entry) => !entry._contextkit);
+
+    settings.hooks.PostToolUse.push({
+      matcher: 'Edit|Write',
+      hooks: [{ type: 'command', command }],
+      _contextkit: true,
+    });
+
+    await this.write(settings);
+  }
+
+  async removeContextKitHooks() {
+    const settings = await this.read();
+    if (!Array.isArray(settings.hooks?.PostToolUse)) return;
+
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((entry) => !entry._contextkit);
+
+    if (settings.hooks.PostToolUse.length === 0) {
+      delete settings.hooks.PostToolUse;
+    }
+
+    if (Object.keys(settings.hooks).length === 0) {
+      delete settings.hooks;
+    }
+
+    await this.write(settings);
+  }
+}
+
+module.exports = ClaudeSettings;

package/lib/utils/claude-settings.md

@@ -0,0 +1,52 @@
+# claude-settings.js
+
+Reads, merges, and writes `.claude/settings.json` safely — adding or removing ContextKit-owned entries without clobbering user content.
+
+## Exports
+
+`ClaudeSettings` — class
+
+## Public API
+
+### `read() → Promise<object>`
+
+Returns the parsed contents of `.claude/settings.json`, or `{}` if the file does not exist. On invalid JSON, logs a yellow warning and returns `{}` (does not throw).
+
+### `write(settings) → Promise<void>`
+
+Writes the settings object to `.claude/settings.json` with 2-space indentation and a trailing newline. Creates `.claude/` if it does not exist.
+
+### `addPostToolUseHook(command) → Promise<void>`
+
+Adds a ContextKit-owned PostToolUse hook entry. Replaces any existing `_contextkit: true` entry rather than duplicating. Merges into existing file content — other keys (permissions, other hooks) are preserved.
+
+Throws `Error('hook command is required')` if `command` is falsy.
+
+Hook entry written:
+```json
+{
+  "matcher": "Edit|Write",
+  "hooks": [{ "type": "command", "command": "<command>" }],
+  "_contextkit": true
+}
+```
+
+### `removeContextKitHooks() → Promise<void>`
+
+Removes all `PostToolUse` entries where `_contextkit: true`. If the array becomes empty, deletes the `PostToolUse` key. If `hooks` becomes empty, deletes the `hooks` key. No-op if the file is absent.
+
+## Usage Example
+
+```javascript
+const ClaudeSettings = require('./claude-settings');
+
+const cs = new ClaudeSettings();
+await cs.addPostToolUseHook('pnpm run format && pnpm run lint --fix 2>&1 | tail -20');
+// → writes .claude/settings.json, merging into existing content
+```
+
+## Edge Cases & Notes
+
+- `PostToolUse` that is not an array: the original value is preserved under `_contextkit_original_invalid`, and a fresh array is started for ContextKit's entry
+- Invalid JSON in existing file: returns `{}` with a warning — the file is NOT overwritten (protects corrupted user files)
+- Thread safety: no file locking; not a concern for a CLI tool

package/lib/utils/git-hooks.js

@@ -17,12 +17,31 @@ class GitHooksManager {
     }
 
     try {
-      // Clean up legacy Husky directory if present
+      // Clean up legacy Husky directory if present (only removes CK-owned husky hooks)
       await this.cleanupLegacyHusky();
 
       // Clean up legacy .git/hooks/ files from previous ContextKit versions
       await this.cleanupLegacyGitHooks();
 
+      // Detect conflicting hooks manager — suggest integration instead of forcing override
+      const conflict = await this.detectExistingHooksManager();
+      if (conflict.detected) {
+        console.log(chalk.yellow(`\n⚠️  Existing hooks manager detected: ${conflict.type}`));
+        console.log(chalk.yellow(`   ${conflict.details}`));
+        console.log(chalk.blue('\n💡 To use ContextKit quality gates with your existing setup:'));
+        const lines = conflict.suggestion.split('\n');
+        for (const line of lines) {
+          console.log(chalk.dim(`   ${line}`));
+        }
+        console.log(chalk.dim('\n   Skipping automatic hooks setup to avoid conflicts.'));
+        console.log(
+          chalk.dim(
+            `   To force ContextKit hooks, run: git config core.hooksPath ${this.hooksPath}`
+          )
+        );
+        return;
+      }
+
       // Remove hooks the user didn't select
       await this.removeUnselectedHooks(hookChoices);
 
@@ -46,6 +65,119 @@ class GitHooksManager {
     }
   }
 
+  async detectExistingHooksManager() {
+    // 1. Check if core.hooksPath already points somewhere other than .contextkit/hooks
+    try {
+      const currentHooksPath = execSync('git config core.hooksPath', {
+        encoding: 'utf8',
+        stdio: 'pipe',
+      }).trim();
+      if (currentHooksPath && currentHooksPath !== this.hooksPath) {
+        return {
+          detected: true,
+          type: 'core.hooksPath',
+          details: `core.hooksPath is already set to "${currentHooksPath}"`,
+          suggestion: `Run your existing hooks via that path, or update it manually:\n  git config core.hooksPath ${this.hooksPath}`,
+        };
+      }
+    } catch {
+      // core.hooksPath not set — no conflict
+    }
+
+    // 2. Check for Husky (.husky/ still present after legacy cleanup = user-owned)
+    if (fs.existsSync('.husky')) {
+      return {
+        detected: true,
+        type: 'husky',
+        details: 'Found .husky/ directory with project hooks',
+        suggestion:
+          'Call ContextKit hooks from your existing Husky hooks:\n' +
+          '  echo "sh .contextkit/hooks/pre-push" >> .husky/pre-push\n' +
+          '  echo "sh .contextkit/hooks/commit-msg" >> .husky/commit-msg',
+      };
+    }
+
+    // 3. Check for Lefthook
+    if (
+      fs.existsSync('.lefthook.yml') ||
+      fs.existsSync('lefthook.yml') ||
+      fs.existsSync('.lefthook')
+    ) {
+      return {
+        detected: true,
+        type: 'lefthook',
+        details: 'Found Lefthook configuration',
+        suggestion:
+          'Add ContextKit quality gates to your lefthook.yml:\n' +
+          '  pre-push:\n' +
+          '    commands:\n' +
+          '      ck-quality:\n' +
+          '        run: sh .contextkit/hooks/pre-push\n' +
+          '  commit-msg:\n' +
+          '    commands:\n' +
+          '      ck-commit:\n' +
+          '        run: sh .contextkit/hooks/commit-msg {1}',
+      };
+    }
+
+    // 4. Check for simple-git-hooks or husky.hooks in package.json
+    if (fs.existsSync('package.json')) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
+        if (pkg['simple-git-hooks']) {
+          return {
+            detected: true,
+            type: 'simple-git-hooks',
+            details: 'Found simple-git-hooks configuration in package.json',
+            suggestion:
+              'Add ContextKit hooks to your simple-git-hooks config in package.json:\n' +
+              '  "simple-git-hooks": {\n' +
+              '    "pre-push": "sh .contextkit/hooks/pre-push",\n' +
+              '    "commit-msg": "sh .contextkit/hooks/commit-msg $1"\n' +
+              '  }',
+          };
+        }
+        if (pkg.husky && pkg.husky.hooks) {
+          return {
+            detected: true,
+            type: 'husky-config',
+            details: 'Found husky.hooks configuration in package.json',
+            suggestion:
+              'Add ContextKit hooks to your husky.hooks config in package.json:\n' +
+              '  "husky": { "hooks": { "pre-push": "sh .contextkit/hooks/pre-push" } }',
+          };
+        }
+      } catch {
+        // Invalid package.json — skip
+      }
+    }
+
+    // 5. Check for non-CK files in .git/hooks/
+    const hooksToCheck = ['pre-push', 'commit-msg', 'pre-commit'];
+    for (const hook of hooksToCheck) {
+      const hookPath = `.git/hooks/${hook}`;
+      if (fs.existsSync(hookPath)) {
+        try {
+          const content = fs.readFileSync(hookPath, 'utf-8');
+          if (!content.includes('ContextKit managed hook') && !content.includes('.contextkit/')) {
+            return {
+              detected: true,
+              type: 'git-hooks',
+              details: `Found existing ${hook} hook in .git/hooks/`,
+              suggestion:
+                `Add ContextKit quality gates to your existing .git/hooks/${hook}:\n` +
+                `  sh .contextkit/hooks/${hook}`,
+            };
+          }
+        } catch {
+          // Unreadable hook file — skip
+        }
+      }
+    }
+
+    return { detected: false, type: null, details: null, suggestion: null };
+  }
+
   async removeUnselectedHooks(hookChoices) {
     // If user didn't select a hook, remove it from .contextkit/hooks/
     // so core.hooksPath doesn't run hooks they didn't want

package/lib/utils/hook-detector.js

@@ -0,0 +1,138 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { execSync } = require('child_process');
+
+class HookDetector {
+  _commandExists(name) {
+    try {
+      execSync(`which ${name}`, { stdio: 'ignore' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  _pmPrefix(pm) {
+    switch (pm) {
+      case 'pnpm':
+        return 'pnpm run';
+      case 'yarn':
+        return 'yarn';
+      case 'bun':
+        return 'bun run';
+      default:
+        return 'npm run';
+    }
+  }
+
+  _lintFixCmd(pm, hasLintFix, hasLint) {
+    if (hasLintFix) {
+      switch (pm) {
+        case 'yarn':
+          return 'yarn lint:fix';
+        default:
+          return `${this._pmPrefix(pm)} lint:fix`;
+      }
+    }
+    if (hasLint) {
+      switch (pm) {
+        case 'pnpm':
+          return 'pnpm run lint --fix';
+        case 'yarn':
+          return 'yarn lint --fix';
+        case 'bun':
+          return 'bun run lint --fix';
+        default:
+          return 'npm run lint -- --fix';
+      }
+    }
+    return null;
+  }
+
+  async _detectNode(projectDir) {
+    const pkgPath = path.join(projectDir, 'package.json');
+    if (!(await fs.pathExists(pkgPath))) return null;
+
+    let packageJson;
+    try {
+      const raw = await fs.readFile(pkgPath, 'utf8');
+      packageJson = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+
+    const scripts = packageJson.scripts || {};
+
+    let pm = 'npm';
+    if (await fs.pathExists(path.join(projectDir, 'bun.lockb'))) {
+      pm = 'bun';
+    } else if (await fs.pathExists(path.join(projectDir, 'pnpm-lock.yaml'))) {
+      pm = 'pnpm';
+    } else if (await fs.pathExists(path.join(projectDir, 'yarn.lock'))) {
+      pm = 'yarn';
+    }
+
+    const hasFormat = Boolean(scripts.format);
+    const hasLintFix = Boolean(scripts['lint:fix']);
+    const hasLint = Boolean(scripts.lint);
+
+    const parts = [];
+
+    if (hasFormat) {
+      const prefix = this._pmPrefix(pm);
+      parts.push(pm === 'yarn' ? `yarn format` : `${prefix} format`);
+    }
+
+    const lintCmd = this._lintFixCmd(pm, hasLintFix, hasLint);
+    if (lintCmd) {
+      parts.push(lintCmd);
+    }
+
+    if (parts.length === 0) return null;
+
+    return parts.join(' && ') + ' 2>&1 | tail -20';
+  }
+
+  async _detectGo(projectDir) {
+    if (!(await fs.pathExists(path.join(projectDir, 'go.mod')))) return null;
+
+    const parts = [];
+    if (this._commandExists('gofmt')) parts.push('gofmt -w .');
+    if (this._commandExists('golangci-lint')) parts.push('golangci-lint run 2>&1 | tail -20');
+
+    if (parts.length === 0) return null;
+
+    const cmd = parts.join(' && ');
+    // If only gofmt, add tail ourselves; if golangci-lint is present, it already has tail
+    return parts.length === 1 && parts[0] === 'gofmt -w .' ? cmd : cmd;
+  }
+
+  async _detectPython(projectDir) {
+    const hasPyproject = await fs.pathExists(path.join(projectDir, 'pyproject.toml'));
+    const hasRequirements = await fs.pathExists(path.join(projectDir, 'requirements.txt'));
+    if (!hasPyproject && !hasRequirements) return null;
+
+    const parts = [];
+    if (this._commandExists('black')) parts.push('black .');
+    if (this._commandExists('ruff')) parts.push('ruff check --fix . 2>&1 | tail -20');
+
+    if (parts.length === 0) return null;
+
+    return parts.join(' && ');
+  }
+
+  async detect(projectDir = process.cwd()) {
+    const node = await this._detectNode(projectDir);
+    if (node) return node;
+
+    const go = await this._detectGo(projectDir);
+    if (go) return go;
+
+    const python = await this._detectPython(projectDir);
+    if (python) return python;
+
+    return null;
+  }
+}
+
+module.exports = HookDetector;

package/lib/utils/hook-detector.md

@@ -0,0 +1,42 @@
+# hook-detector.js
+
+Detects the right PostToolUse hook command for a project based on its language, package manager, and available scripts.
+
+## Exports
+
+`HookDetector` — class
+
+## Public API
+
+### `detect(projectDir = process.cwd()) → Promise<string | null>`
+
+Returns a shell command string suitable for use as a Claude Code PostToolUse hook, or `null` if no format/lint tooling is detected.
+
+Tries three detectors in order: Node.js → Go → Python.
+
+## Usage Example
+
+```javascript
+const HookDetector = require('./hook-detector');
+
+const command = await new HookDetector().detect('/path/to/project');
+// → "pnpm run format && pnpm run lint --fix 2>&1 | tail -20"
+// → null (if no tooling found)
+```
+
+## Detection Logic
+
+| Stack | Trigger | PM detection | Command built from |
+|---|---|---|---|
+| Node.js | `package.json` exists | lockfile (`bun.lockb` > `pnpm-lock.yaml` > `yarn.lock` > `npm`) | `scripts.format`, `scripts['lint:fix']`, `scripts.lint` |
+| Go | `go.mod` exists | n/a | `gofmt` and/or `golangci-lint` (via `which`) |
+| Python | `pyproject.toml` or `requirements.txt` | n/a | `black` and/or `ruff` (via `which`) |
+
+For Node.js: `lint:fix` takes priority over `lint`. If only `lint` is present, `--fix` is appended (npm uses `-- --fix` separator; pnpm/yarn/bun pass args directly).
+
+## Edge Cases & Notes
+
+- Malformed `package.json` → returns `null`, does not throw
+- No scripts in `package.json` → returns `null`
+- Go/Python tools not on PATH → returns `null`
+- Node.js takes priority when multiple stack markers coexist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolrm/contextkit",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "ContextKit - Context Engineering for AI Development. Provide rich context to AI through structured MD files with standards, code guides, and documentation. Works with Cursor, Claude, Aider, VS Code Copilot, and more.",
   "main": "lib/index.js",
   "bin": {