@chris1807/claude-kit 2.1.16 → 2.1.18

package/bin/cli.js

@@ -11,6 +11,8 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const TEMPLATES_DIR = join(__dirname, '..', 'templates');
 const GLOBAL_CLAUDE_DIR = join(process.env.HOME || process.env.USERPROFILE, '.claude');
+const PKG = await fs.readJson(join(__dirname, '..', 'package.json'));
+const KIT_VERSION = PKG.version;
 
 // ============================================================================
 // CLI Arguments
@@ -110,6 +112,47 @@ async function installFile(src, dest, label) {
   return true;
 }
 
+// ============================================================================
+// Helper: additive merge for settings.json
+// ============================================================================
+// Top-level keys: keep user's value if present, add kit's only if missing.
+// `hooks`: union of matcher blocks; within each block, union of hook commands
+// (compared by `command` string). Never removes user-added entries.
+function mergeSettings(existing, template) {
+  const merged = { ...existing };
+  for (const [key, value] of Object.entries(template)) {
+    if (key === 'hooks') {
+      merged.hooks = mergeHooks(existing.hooks || {}, value);
+    } else if (!(key in merged)) {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+
+function mergeHooks(existing, template) {
+  const merged = { ...existing };
+  for (const [event, templateBlocks] of Object.entries(template)) {
+    const resultBlocks = [...(merged[event] || [])];
+    for (const tplBlock of templateBlocks) {
+      const idx = resultBlocks.findIndex(b => b.matcher === tplBlock.matcher);
+      if (idx === -1) {
+        resultBlocks.push(tplBlock);
+      } else {
+        const newHooks = [...(resultBlocks[idx].hooks || [])];
+        for (const tplHook of tplBlock.hooks || []) {
+          if (!newHooks.some(h => h.command === tplHook.command)) {
+            newHooks.push(tplHook);
+          }
+        }
+        resultBlocks[idx] = { ...resultBlocks[idx], hooks: newHooks };
+      }
+    }
+    merged[event] = resultBlocks;
+  }
+  return merged;
+}
+
 // ============================================================================
 // Step 1: Global Agents (always)
 // ============================================================================
@@ -243,6 +286,7 @@ async function main() {
   // ── MCP Servers (interactive selection) ───────────────────────────────
   let dbType = 'none';
   let selectedServers = [];
+  let adoOrgChoice = null;
   if (components.includes('mcp')) {
     console.log(chalk.yellow.bold('\n🔌 MCP Servers → .mcp.json\n'));
 
@@ -379,6 +423,7 @@ async function main() {
 
     dbType = mcpChoices.db;
     selectedServers = mcpChoices.servers;
+    adoOrgChoice = mcpChoices.adoOrg || null;
 
     const mcpPath = join(targetDir, '.mcp.json');
     if (await fs.pathExists(mcpPath)) {
@@ -388,15 +433,16 @@ async function main() {
       if (newContent.trim() === existingContent.trim()) {
         console.log(chalk.gray('  = .mcp.json (identical, skipped)'));
       } else {
+      // In --all mode, merge by default — preserves user-added MCP servers.
       const { action } = installAll
-        ? { action: 'overwrite' }
+        ? { action: 'merge' }
         : await inquirer.prompt([{
             type: 'list',
             name: 'action',
             message: '.mcp.json already exists:',
             choices: [
+              { name: 'Merge (add missing servers, keep yours)', value: 'merge' },
               { name: 'Overwrite with new config', value: 'overwrite' },
-              { name: 'Merge (add missing servers)', value: 'merge' },
               { name: 'Skip', value: 'skip' },
             ],
           }]);
@@ -422,11 +468,27 @@ async function main() {
   // ── Settings ──────────────────────────────────────────────────────────
   if (components.includes('settings')) {
     console.log(chalk.yellow.bold('\n⚙️  Settings → .claude/settings.json\n'));
-    await installFile(
-      join(TEMPLATES_DIR, 'infrastructure', 'settings.json'),
-      join(targetDir, '.claude', 'settings.json'),
-      'settings.json'
+    const templateSettings = await fs.readJson(
+      join(TEMPLATES_DIR, 'infrastructure', 'settings.json')
     );
+    const settingsPath = join(targetDir, '.claude', 'settings.json');
+    await fs.ensureDir(dirname(settingsPath));
+
+    if (!await fs.pathExists(settingsPath)) {
+      await fs.writeJson(settingsPath, templateSettings, { spaces: 2 });
+      console.log(chalk.green('  ✓ settings.json'));
+    } else {
+      const existing = await fs.readJson(settingsPath);
+      const merged = mergeSettings(existing, templateSettings);
+      const before = JSON.stringify(existing);
+      const after = JSON.stringify(merged);
+      if (before === after) {
+        console.log(chalk.gray('  = settings.json (no kit changes needed)'));
+      } else {
+        await fs.writeJson(settingsPath, merged, { spaces: 2 });
+        console.log(chalk.green('  ✓ settings.json (merged — kit hooks added, user customizations preserved)'));
+      }
+    }
   }
 
   // ── CLAUDE.md Workflow ────────────────────────────────────────────────
@@ -468,18 +530,27 @@ async function main() {
       existing = await fs.readFile(claudeMdPath, 'utf8');
 
       if (existing.includes('Claude Kit Workflow') || existing.includes('Care Solutions AI Workflow')) {
-        console.log(chalk.gray('  = Workflow section already exists'));
-        if (!installAll) {
+        // Check whether the existing workflow section matches the current template.
+        // If it does, nothing to do. If not, replace it (auto in --all, prompt otherwise).
+        const cleaned = existing.replace(/\n## (?:Claude Kit Workflow|Care Solutions AI Workflow)[\s\S]*$/, '').trimEnd();
+        const expected = `${cleaned}\n\n${workflowContent}`;
+        if (existing.trim() === expected.trim()) {
+          console.log(chalk.gray('  = Workflow section up to date'));
+        } else if (installAll) {
+          await fs.writeFile(claudeMdPath, expected);
+          console.log(chalk.green('  ✓ Workflow section re-synced to current template'));
+        } else {
           const { replace } = await inquirer.prompt([{
             type: 'confirm',
             name: 'replace',
-            message: 'Replace existing workflow section?',
-            default: false,
+            message: 'Workflow section differs from template — replace?',
+            default: true,
           }]);
           if (replace) {
-            const cleaned = existing.replace(/\n## (?:Claude Kit Workflow|Care Solutions AI Workflow)[\s\S]*$/, '').trimEnd();
-            await fs.writeFile(claudeMdPath, `${cleaned}\n\n${workflowContent}`);
+            await fs.writeFile(claudeMdPath, expected);
             console.log(chalk.green('  ✓ Workflow section replaced'));
+          } else {
+            console.log(chalk.gray('  ⊘ Workflow section left as-is'));
           }
         }
       } else {
@@ -518,6 +589,19 @@ async function main() {
     }
   }
 
+  // ── Install Manifest ──────────────────────────────────────────────────
+  // Records the kit version and the choices made (db, adoOrg) so the
+  // kit-update-check hook can re-run the installer non-interactively.
+  const manifestPath = join(targetDir, '.claude', '.kit-install.json');
+  await fs.ensureDir(dirname(manifestPath));
+  await fs.writeJson(manifestPath, {
+    version: KIT_VERSION,
+    choices: {
+      db: dbType,
+      adoOrg: selectedServers.includes('azuredevops') ? adoOrgChoice : null,
+    },
+  }, { spaces: 2 });
+
   // ── Summary ───────────────────────────────────────────────────────────
   const agentCount = (await fs.pathExists(join(targetDir, '.claude', 'agents')))
     ? (await fs.readdir(join(targetDir, '.claude', 'agents'))).filter(f => f.endsWith('.md')).length

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.16",
+  "version": "2.1.18",
   "description": "Claude Code starter kit for Azure DevOps teams — agents, hooks, MCP servers, slash commands, and end-to-end work item → PR → release → deploy workflow automation",
   "type": "module",
   "bin": {

package/templates/commands/implement.md

@@ -129,11 +129,37 @@ Run a build check **before** any other quality checks. Use the `build-validator`
 
 ## Step 7: Quality Checks
 
-1. **Review** code for quality, security, and Clean Architecture compliance
-2. **Run the full test suite** — every unit test in the repo, plus integration tests. Not just the tests added in this change. A failure in an unrelated test means this change broke something else; treat it as a regression, fix it, and re-run until the entire suite is green
-3. **Run lint** — ESLint and dotnet format
+1. **Run the full test suite** — every unit test in the repo, plus integration tests. Not just the tests added in this change. A failure in an unrelated test means this change broke something else; treat it as a regression, fix it, and re-run until the entire suite is green
+2. **Run lint** — ESLint and dotnet format
 
-## Step 8: UAT Gate
+## Step 8: Code Review
+
+Spawn the `reviewer` agent to review the diff for quality, security, Clean Architecture compliance, and CLAUDE.md adherence. The agent is read-only — it reports findings, you act on them.
+
+Present the findings to the user grouped by severity:
+
+```
+## Code Review Findings
+
+### Must-fix (blocking)
+- {file:line} — {issue + why it blocks}
+
+### Should-fix (recommended)
+- {file:line} — {issue + suggested change}
+
+### Nits (optional)
+- {file:line} — {minor note}
+
+Address must-fix items? (yes / select / skip)
+```
+
+- `yes` → fix every must-fix item, then re-run the reviewer agent on the updated diff
+- `select` → ask which items to address; fix only those, then re-run the reviewer agent
+- `skip` → proceed without fixes (only allowed if there are no must-fix items, or the user explicitly overrides)
+
+Loop until the reviewer reports no must-fix items, or the user explicitly accepts remaining findings. Do not proceed to UAT with unresolved must-fix items unless the user overrides.
+
+## Step 9: UAT Gate
 
 ### If Hot Fix:
 Skip manual UAT. Present an abbreviated confirmation:
@@ -165,7 +191,7 @@ Did manual testing pass?
 
 Wait for the user's response before proceeding. Do NOT create a PR until confirmed.
 
-## Step 9: Push, Create PR, and Update Work Item
+## Step 10: Push, Create PR, and Update Work Item
 
 1. Push the branch: `git push -u origin HEAD`
 2. Create a PR via Azure DevOps MCP:

package/templates/commands/rework.md

@@ -202,10 +202,9 @@ Run a build check **before** any other quality checks. Use the `build-validator`
 
 ## Step 9: Quality Checks
 
-1. **Review** code for quality, security, and Clean Architecture compliance
-2. **Run the full test suite** — every unit test in the repo, plus integration tests. Not just the tests added in this rework. A failure in an unrelated test means this rework broke something else; treat it as a regression, fix it, and re-run until the entire suite is green
-3. **Run lint** — ESLint and dotnet format
-4. **Acceptance Criteria check** — re-read the work item's full Acceptance Criteria (the same list captured in Step 3). For each AC, identify the test or piece of code that proves it's met. If any AC has no covering test or visible code path, flag it before moving to the UAT gate:
+1. **Run the full test suite** — every unit test in the repo, plus integration tests. Not just the tests added in this rework. A failure in an unrelated test means this rework broke something else; treat it as a regression, fix it, and re-run until the entire suite is green
+2. **Run lint** — ESLint and dotnet format
+3. **Acceptance Criteria check** — re-read the work item's full Acceptance Criteria (the same list captured in Step 3). For each AC, identify the test or piece of code that proves it's met. If any AC has no covering test or visible code path, flag it before moving on:
 
    ```
    ⚠ AC #{n} ({short form}) has no covering test or clear code path.
@@ -214,7 +213,34 @@ Run a build check **before** any other quality checks. Use the `build-validator`
 
    Do not advance to Step 10 with any AC unverified.
 
-## Step 10: UAT Gate
+## Step 10: Code Review
+
+Spawn the `reviewer` agent to review the rework diff for quality, security, Clean Architecture compliance, and CLAUDE.md adherence. Focus the review on the files changed since the last PR — call out any regression risk introduced by the rework. The agent is read-only — it reports findings, you act on them.
+
+Present the findings to the user grouped by severity:
+
+```
+## Code Review Findings
+
+### Must-fix (blocking)
+- {file:line} — {issue + why it blocks}
+
+### Should-fix (recommended)
+- {file:line} — {issue + suggested change}
+
+### Nits (optional)
+- {file:line} — {minor note}
+
+Address must-fix items? (yes / select / skip)
+```
+
+- `yes` → fix every must-fix item, then re-run the reviewer agent on the updated diff
+- `select` → ask which items to address; fix only those, then re-run the reviewer agent
+- `skip` → proceed without fixes (only allowed if there are no must-fix items, or the user explicitly overrides)
+
+Loop until the reviewer reports no must-fix items, or the user explicitly accepts remaining findings. Do not proceed to UAT with unresolved must-fix items unless the user overrides.
+
+## Step 11: UAT Gate
 
 ### If Hot Fix:
 Skip manual UAT. Present an abbreviated confirmation:
@@ -246,7 +272,7 @@ Did manual testing pass?
 
 Wait for the user's response before proceeding. Do NOT push until confirmed.
 
-## Step 11: Push and Update
+## Step 12: Push and Update
 
 1. Push the changes: `git push`
 2. Add a comment on the existing PR summarizing what was changed in the rework

package/templates/hooks/kit-update-check.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# kit-update-check.sh — SessionStart hook
+#
+# Checks npm for a newer @chris1807/claude-kit and re-runs the installer
+# non-interactively when one is available. Must never block claude startup —
+# every external call is timeout-bounded and every failure exits 0 silently.
+#
+# Throttled to once per 24h via a marker file. Reads .claude/.kit-install.json
+# for the installed version and the choices to pass to the re-install (db, adoOrg).
+
+set +e  # never propagate failures
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLAUDE_DIR="$(cd "$HOOK_DIR/.." && pwd)"
+PROJECT_DIR="$(cd "$CLAUDE_DIR/.." && pwd)"
+MANIFEST="$CLAUDE_DIR/.kit-install.json"
+MARKER="$CLAUDE_DIR/.kit-update-check"
+LOG="$CLAUDE_DIR/.kit-update.log"
+
+# No manifest = legacy install or global-only; nothing to do.
+[ -f "$MANIFEST" ] || exit 0
+
+# Throttle to one check per 24h. A failed check still touches the marker so
+# unreachable npm doesn't retry every session.
+if [ -f "$MARKER" ]; then
+  if command -v stat >/dev/null 2>&1; then
+    LAST=$(stat -f %m "$MARKER" 2>/dev/null || stat -c %Y "$MARKER" 2>/dev/null || echo 0)
+    NOW=$(date +%s)
+    if [ "$((NOW - LAST))" -lt 86400 ]; then
+      exit 0
+    fi
+  fi
+fi
+
+# Crude JSON extraction (avoids requiring jq).
+extract() {
+  grep -o "\"$1\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" "$MANIFEST" | head -1 | sed 's/.*"\([^"]*\)"$/\1/'
+}
+INSTALLED=$(extract version)
+DB=$(extract db)
+ADO_ORG=$(extract adoOrg)
+
+# Fetch latest with a 5s timeout — must never hang. `timeout` isn't on macOS
+# by default; perl's alarm() is the most portable fallback.
+if command -v timeout >/dev/null 2>&1; then
+  LATEST=$(timeout 5 npm view @chris1807/claude-kit version 2>/dev/null)
+elif command -v gtimeout >/dev/null 2>&1; then
+  LATEST=$(gtimeout 5 npm view @chris1807/claude-kit version 2>/dev/null)
+elif command -v perl >/dev/null 2>&1; then
+  LATEST=$(perl -e 'alarm 5; exec @ARGV or exit 1' npm view @chris1807/claude-kit version 2>/dev/null)
+else
+  # No timeout mechanism available — skip rather than risk a hang.
+  touch "$MARKER"
+  exit 0
+fi
+
+touch "$MARKER"
+
+[ -z "$LATEST" ] && exit 0
+[ -z "$INSTALLED" ] && exit 0
+[ "$LATEST" = "$INSTALLED" ] && exit 0
+
+# Only proceed if LATEST sorts strictly greater than INSTALLED.
+NEWER=$(printf '%s\n%s\n' "$INSTALLED" "$LATEST" | sort -V | tail -1)
+[ "$NEWER" = "$LATEST" ] || exit 0
+[ "$NEWER" = "$INSTALLED" ] && exit 0
+
+echo "claude-kit: updating $INSTALLED → $LATEST..." >&2
+
+ARGS=("@chris1807/claude-kit" "init" "$PROJECT_DIR" "--all")
+if [ -n "$DB" ] && [ "$DB" != "null" ]; then
+  ARGS+=("--db=$DB")
+fi
+if [ -n "$ADO_ORG" ] && [ "$ADO_ORG" != "null" ]; then
+  ARGS+=("--ado-org=$ADO_ORG")
+fi
+
+if npx -y "${ARGS[@]}" >"$LOG" 2>&1; then
+  echo "claude-kit: updated to $LATEST (log: $LOG)" >&2
+else
+  echo "claude-kit: update failed (see $LOG)" >&2
+fi
+
+exit 0

package/templates/infrastructure/settings.json

@@ -89,6 +89,16 @@
           }
         ]
       }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/kit-update-check.sh"
+          }
+        ]
+      }
     ]
   }
 }