claude-devkit-cli 1.0.0

package/templates/.claude/commands/test.md

@@ -0,0 +1,99 @@
+EXECUTE, not EXPLORE. Write tests, run them, make them pass. Don't read unrelated files.
+
+## Phase 0: Build Context
+
+1. **Find what changed:**
+   ```
+   BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||') || BASE="main"
+   git diff --name-only "$BASE"...HEAD
+   ```
+   If `$ARGUMENTS` provided → scope to that file or feature only.
+   If no changes → "No source changes found. Specify a file or feature."
+
+2. **Read the test plan** in `docs/test-plans/` if it exists — this is your roadmap.
+3. **Read the spec** in `docs/specs/` if it exists — understand the INTENT behind the code.
+4. **Read existing tests** for the changed files — find patterns, fixtures, naming conventions. Don't duplicate.
+
+---
+
+## Phase 1: Decide What to Test
+
+Test behavior, not implementation. If the internals change but behavior stays the same, tests should still pass.
+
+**What NOT to test:**
+- Private/internal methods (test through public API)
+- Framework behavior (test YOUR handler, not that Express routes work)
+- Trivial getters/setters (unless they have validation)
+- Implementation details (HOW it works — test WHAT it does)
+
+**Quality check for each test:**
+- Does it test one concept? If it fails, do you know exactly what broke?
+- Is it independent? No test depends on another running first.
+- Is it deterministic? No random, no time-dependent, no external service calls.
+- Does the name describe the scenario? (`returns_error_when_input_is_empty`)
+
+---
+
+## Phase 2: Write Tests
+
+Follow the project's existing test patterns. If using `$ARGUMENTS` as a filter, use `--filter` when running:
+```
+bash scripts/build-test.sh --filter "$ARGUMENTS"
+```
+
+---
+
+## Phase 3: Build and Run
+
+Compile/typecheck first (tsc --noEmit, cargo check, go vet, swift build, etc.).
+
+Then run tests:
+```
+bash scripts/build-test.sh
+```
+
+If `scripts/build-test.sh` doesn't exist, detect and run directly:
+| Marker | Command |
+|--------|---------|
+| vitest config / vitest in package.json | `npx vitest run` |
+| jest config / jest in package.json | `npx jest --no-cache` |
+| pyproject.toml / pytest.ini | `python3 -m pytest -x` |
+| Cargo.toml | `cargo test` |
+| go.mod | `go test ./...` |
+| build.gradle | `./gradlew test` |
+| *.sln | `dotnet test` |
+| Package.swift | `swift test` |
+| Gemfile | `bundle exec rspec` |
+
+---
+
+## Phase 4: Fix Loop
+
+If tests fail:
+1. Read error output. Is the test wrong or the production code wrong?
+2. If production code seems wrong → **ASK the user:** "Test expects X but code does Y. Fix production code or adjust test?"
+3. Fix test code only. Re-run. Max 3 attempts, then stop and report.
+
+**NEVER:**
+- Fix production code without asking
+- Delete or weaken existing tests
+- Add `skip`/`xit`/`@disabled` to hide failures
+- Use mocks solely to avoid a real failure
+
+---
+
+## Phase 5: Summary
+
+```
+Tests: X added, Y modified, Z unchanged
+Result: All passing ✓
+Coverage: [critical uncovered paths if any]
+Files: [test files touched]
+Plan: [TC-001 ✓, TC-002 ✓, TC-005 new]
+```
+
+If behavior changed: "Consider updating the spec in docs/specs/."
+
+## Rules
+1. **Behavior over implementation.** Test what code DOES, not how.
+2. **Independent tests.** Each test sets up its own state, cleans up after.

package/templates/.claude/hooks/comment-guard.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// comment-guard.js — PreToolUse hook for Claude Code
+//
+// Detects when an Edit would replace real code with placeholder comments like
+// "// ... existing code ..." or "// rest of implementation". This is a
+// common LLM failure mode where the model gets lazy and drops code.
+//
+// Blocking: Yes — exits 2 to reject the edit BEFORE it is applied.
+// Event: PreToolUse on Edit|MultiEdit
+
+"use strict";
+
+const fs = require("fs");
+
+// Patterns that indicate lazy placeholder comments (case-insensitive)
+const PLACEHOLDER_PATTERNS = [
+  /\/\/\s*\.{2,}\s*(existing|remaining|rest|previous|other|same|original)/i,
+  /\/\/\s*\.{2,}\s*(code|implementation|logic|methods|functions|properties)/i,
+  /\/\/\s*\[.*(?:remains?|unchanged|omitted|removed|truncated|collapsed).*\]/i,
+  /\/\/\s*(?:unchanged|omitted|keep|stays?)\s*(?:as\s*(?:is|before))?/i,
+  /\/\*\s*\.{2,}\s*\*\//,                          // /* ... */
+  /#\s*\.{2,}\s*(existing|remaining|rest|previous)/i,  // Python: # ... existing
+  /\/\/\s*TODO:?\s*implement/i,                     // // TODO: implement
+  /\/\/\s*(?:add|put|insert)\s+.*\s+here/i,         // // add code here
+  /\/\/\s*<\s*(?:your|actual)\s+/i,                 // // <your code>
+  /pass\s*#\s*(?:TODO|placeholder|implement)/i,     // Python: pass # TODO
+];
+
+function isCommentLine(line) {
+  const trimmed = line.trim();
+  if (trimmed === "") return true; // blank lines are neutral
+  if (trimmed.startsWith("//")) return true;
+  if (trimmed.startsWith("#") && !trimmed.startsWith("#!")) return true;
+  if (trimmed.startsWith("/*") || trimmed.startsWith("*") || trimmed.endsWith("*/")) return true;
+  if (trimmed.startsWith("<!--")) return true;
+  if (trimmed === "pass") return true; // Python pass statement as placeholder
+  return false;
+}
+
+function getCodeLineCount(text) {
+  if (!text) return 0;
+  return text.split("\n").filter((line) => !isCommentLine(line)).length;
+}
+
+function hasPlaceholderPattern(text) {
+  return PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+function main() {
+  let input;
+  try {
+    input = fs.readFileSync(0, "utf-8").trim();
+  } catch {
+    process.exit(0);
+  }
+
+  if (!input) process.exit(0);
+
+  let payload;
+  try {
+    payload = JSON.parse(input);
+  } catch {
+    process.exit(0);
+  }
+
+  const oldStr = payload.tool_input?.old_string;
+  const newStr = payload.tool_input?.new_string;
+
+  // Only applies to Edit (not Write — Write creates new content)
+  if (!oldStr || !newStr) process.exit(0);
+
+  // If old content was already all comments, this is just editing comments — allow
+  const oldCodeLines = getCodeLineCount(oldStr);
+  if (oldCodeLines === 0) process.exit(0);
+
+  // If new content has real code, allow (even if it also has comments)
+  const newCodeLines = getCodeLineCount(newStr);
+  if (newCodeLines > 0) process.exit(0);
+
+  // At this point: old had code, new is all comments/blanks
+  // Check if the new content contains placeholder patterns
+  if (hasPlaceholderPattern(newStr)) {
+    process.stderr.write(
+      "Blocked: real code was replaced with placeholder comments. " +
+      "Preserve the original code and make targeted changes instead.\n"
+    );
+    process.exit(2);
+  }
+
+  // New is all comments but no placeholder pattern — could be intentional
+  // (e.g., replacing a code block with documentation comments)
+  // Allow but only if the replacement is not drastically shorter
+  const oldLines = oldStr.split("\n").length;
+  const newLines = newStr.split("\n").length;
+
+  if (newLines < oldLines * 0.3) {
+    // Suspiciously shorter and all comments — likely lazy replacement
+    process.stderr.write(
+      "Blocked: code block was replaced with a much shorter comment-only block. " +
+      "This looks like an accidental truncation. Preserve the original code.\n"
+    );
+    process.exit(2);
+  }
+
+  // Seems intentional
+  process.exit(0);
+}
+
+try {
+  main();
+} catch {
+  // Never crash — allow on error
+  process.exit(0);
+}

package/templates/.claude/hooks/file-guard.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// file-guard.js — PostToolUse hook for Claude Code
+//
+// Warns when a Write/Edit operation produces a file exceeding a line threshold.
+// Non-blocking: always exits 0 and injects advisory context.
+//
+// Environment:
+//   FILE_GUARD_THRESHOLD  — max lines before warning (default: 200)
+//   FILE_GUARD_EXCLUDE    — comma-separated globs to skip (e.g. "*.generated.swift,*.pb.go")
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const THRESHOLD = parseInt(process.env.FILE_GUARD_THRESHOLD, 10) || 200;
+const EXCLUDE = (process.env.FILE_GUARD_EXCLUDE || "")
+  .split(",")
+  .map((g) => g.trim())
+  .filter(Boolean);
+
+function matchesExclude(filePath) {
+  const name = path.basename(filePath);
+  return EXCLUDE.some((pattern) => {
+    // Simple glob: *.ext or exact match
+    if (pattern.startsWith("*")) {
+      return name.endsWith(pattern.slice(1));
+    }
+    return name === pattern;
+  });
+}
+
+function isBinary(buf) {
+  // Check first 512 bytes for null bytes (common binary indicator)
+  const check = buf.slice(0, 512);
+  for (let i = 0; i < check.length; i++) {
+    if (check[i] === 0) return true;
+  }
+  return false;
+}
+
+function main() {
+  let input;
+  try {
+    input = fs.readFileSync(0, "utf-8").trim();
+  } catch {
+    process.exit(0);
+  }
+
+  if (!input) process.exit(0);
+
+  let payload;
+  try {
+    payload = JSON.parse(input);
+  } catch {
+    process.exit(0);
+  }
+
+  const filePath = payload.tool_input?.file_path;
+  if (!filePath) process.exit(0);
+
+  // Skip excluded patterns
+  if (matchesExclude(filePath)) process.exit(0);
+
+  // Skip if file doesn't exist (deleted?) or is a symlink to outside project
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile()) process.exit(0);
+  } catch {
+    process.exit(0);
+  }
+
+  // Cap read at 1MB to avoid OOM on huge files
+  const MAX_BYTES = 1024 * 1024;
+  let content;
+  try {
+    const stat = fs.statSync(filePath);
+    if (stat.size > MAX_BYTES) {
+      // >1MB = definitely over threshold, warn without exact count
+      const rel = path.relative(process.cwd(), filePath);
+      process.stdout.write(JSON.stringify({
+        continue: true,
+        hookSpecificOutput: {
+          hookEventName: "PostToolUse",
+          additionalContext: `Warning: ${rel} is ${Math.round(stat.size / 1024)}KB. Consider splitting into smaller modules.`,
+        },
+      }));
+      process.exit(0);
+    }
+    const buf = fs.readFileSync(filePath);
+    if (isBinary(buf)) process.exit(0);
+    content = buf.toString("utf-8");
+  } catch {
+    process.exit(0);
+  }
+
+  const lineCount = content.split("\n").length;
+  if (lineCount <= THRESHOLD) process.exit(0);
+
+  // Inject non-blocking warning
+  const rel = path.relative(process.cwd(), filePath);
+  const warning = `Warning: ${rel} has ${lineCount} lines (threshold: ${THRESHOLD}). Consider splitting into smaller, focused modules.`;
+
+  process.stdout.write(
+    JSON.stringify({
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: warning,
+      },
+    })
+  );
+}
+
+try {
+  main();
+} catch {
+  // Never block on error
+}
+process.exit(0);

package/templates/.claude/hooks/glob-guard.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// glob-guard.js — PreToolUse hook for Claude Code
+//
+// Blocks overly broad glob patterns (e.g. **/*.ts at project root) that would
+// return thousands of files and fill the context window. Suggests scoped
+// alternatives instead.
+//
+// Blocking: Yes — exits 2 when a broad pattern at a high-level path is detected.
+// Event: PreToolUse on Glob
+
+"use strict";
+
+const fs = require("fs");
+
+// Patterns that match too many files when run at project root
+const BROAD_PATTERNS = [
+  /^\*\*$/,                   // **
+  /^\*$/,                     // *
+  /^\*\*\/\*$/,               // **/*
+  /^\*\.\w+$/,                // *.ts, *.js
+  /^\*\.\{[^}]+\}$/,          // *.{ts,js}
+  /^\*\*\/\*\.\w+$/,          // **/*.ts
+  /^\*\*\/\*\.\{[^}]+\}$/,    // **/*.{ts,tsx}
+  /^\*\*\/\.\*$/,             // **/.* (all dotfiles)
+];
+
+// Directories that indicate an intentional, scoped search
+const SCOPED_DIRS = [
+  "src", "lib", "app", "apps", "packages", "components", "pages",
+  "api", "server", "client", "web", "mobile", "shared", "common",
+  "utils", "helpers", "services", "hooks", "store", "routes",
+  "models", "controllers", "views", "tests", "__tests__", "spec",
+  "Sources", "Tests", "cmd", "pkg", "internal",
+];
+
+function isBroadPattern(pattern) {
+  if (!pattern) return false;
+  return BROAD_PATTERNS.some((re) => re.test(pattern.trim()));
+}
+
+function startsWithScopedDir(pattern) {
+  if (!pattern) return false;
+  // Only allow dirs explicitly in SCOPED_DIRS — not arbitrary dirs like node_modules/
+  return SCOPED_DIRS.some(
+    (d) => pattern.startsWith(d + "/") || pattern.startsWith("./" + d + "/")
+  );
+}
+
+function isRootLevel(basePath) {
+  if (!basePath) return true;
+  const norm = basePath.replace(/\\/g, "/").replace(/\/+$/, "");
+  if (!norm || norm === ".") return true;
+  const segments = norm.split("/").filter((s) => s && s !== ".");
+  if (segments.length === 0) return true;
+  if (segments.length === 1 && !SCOPED_DIRS.includes(segments[0])) return true;
+  return false;
+}
+
+function suggest(pattern) {
+  let ext = "";
+  const m = pattern.match(/\*\.(\{[^}]+\}|\w+)$/);
+  if (m) ext = m[1];
+  const dirs = ["src", "lib", "app", "tests"];
+  return ext
+    ? dirs.map((d) => `${d}/**/*.${ext}`).slice(0, 3)
+    : dirs.map((d) => `${d}/**/*`).slice(0, 3);
+}
+
+function main() {
+  let input;
+  try { input = fs.readFileSync(0, "utf-8").trim(); } catch { process.exit(0); }
+  if (!input) process.exit(0);
+
+  let payload;
+  try { payload = JSON.parse(input); } catch { process.exit(0); }
+
+  const pattern = payload.tool_input?.pattern;
+  const basePath = payload.tool_input?.path;
+
+  if (!pattern) process.exit(0);
+  if (startsWithScopedDir(pattern)) process.exit(0);
+  if (!isBroadPattern(pattern)) process.exit(0);
+  if (!isRootLevel(basePath)) process.exit(0);
+
+  const alt = suggest(pattern);
+  process.stderr.write(
+    [
+      `Blocked: '${pattern}' is too broad for ${basePath || "project root"} — would fill the context window.`,
+      "Use a scoped pattern instead:",
+      ...alt.map((s) => `  - ${s}`),
+    ].join("\n") + "\n"
+  );
+  process.exit(2);
+}
+
+try { main(); } catch { process.exit(0); }

package/templates/.claude/hooks/path-guard.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# path-guard.sh — PreToolUse hook for Claude Code
+#
+# Blocks Bash commands that target directories known to be large and wasteful
+# to explore (node_modules, build artifacts, .git internals, etc.).
+#
+# Exit codes:
+#   0 — command allowed
+#   2 — command blocked (policy)
+#
+# Environment:
+#   PATH_GUARD_EXTRA — additional pipe-separated patterns to block
+#                      e.g. "\.terraform|\.vagrant"
+
+set -euo pipefail
+
+# ─── Read hook payload from stdin ───────────────────────────────────
+
+INPUT=$(cat)
+[[ -z "$INPUT" ]] && exit 0
+
+# Check Node.js availability
+if ! command -v node &>/dev/null; then
+    echo "WARNING: path-guard disabled — Node.js not found." >&2
+    exit 0
+fi
+
+# Parse JSON with inline Node.js (avoids jq dependency)
+COMMAND=$(printf '%s' "$INPUT" | node -e "
+  try {
+    const d = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+    const cmd = d.tool_input?.command;
+    if (typeof cmd === 'string') process.stdout.write(cmd);
+    else process.exit(0);
+  } catch { process.exit(0); }
+" 2>/dev/null) || exit 0
+
+[[ -z "$COMMAND" ]] && exit 0
+
+# ─── Blocked directory patterns ─────────────────────────────────────
+
+BLOCKED="node_modules"
+BLOCKED+="|__pycache__"
+BLOCKED+="|\.git/objects"
+BLOCKED+="|\.git/refs"
+BLOCKED+="|dist/"
+BLOCKED+="|build/"
+BLOCKED+="|\.next/"
+BLOCKED+="|vendor/"
+BLOCKED+="|Pods/"
+BLOCKED+="|\.build/"
+BLOCKED+="|DerivedData"
+BLOCKED+="|\.gradle/"
+BLOCKED+="|target/debug"
+BLOCKED+="|target/release"
+BLOCKED+="|\.nuget"
+BLOCKED+="|\.cache"
+
+# Append project-specific patterns from env
+if [[ -n "${PATH_GUARD_EXTRA:-}" ]]; then
+    BLOCKED+="|$PATH_GUARD_EXTRA"
+fi
+
+# ─── Match and block ────────────────────────────────────────────────
+
+if printf '%s\n' "$COMMAND" | grep -qE "$BLOCKED"; then
+    # Extract which pattern matched for a useful error message
+    MATCHED=$(printf '%s\n' "$COMMAND" | grep -oE "$BLOCKED" | head -1)
+    echo "Blocked: command references '$MATCHED' — this directory is typically large and exploring it wastes tokens. Use Glob or Grep tools instead." >&2
+    exit 2
+fi
+
+exit 0

package/templates/.claude/hooks/self-review.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# self-review.sh — Stop hook for Claude Code
+#
+# Injects a self-review checklist when Claude is about to finish.
+# Non-blocking: always exits 0, just adds context for Claude to consider.
+#
+# Environment:
+#   SELF_REVIEW_ENABLED — set to "false" to disable (default: true)
+
+set -euo pipefail
+
+# Check if disabled
+if [[ "${SELF_REVIEW_ENABLED:-true}" == "false" ]]; then
+    exit 0
+fi
+
+# Read stdin (Stop event payload — may be empty or minimal)
+cat > /dev/null 2>&1 || true
+
+# Inject self-review checklist as context
+cat <<'REVIEW_JSON'
+{
+  "continue": true,
+  "hookSpecificOutput": {
+    "hookEventName": "Stop",
+    "additionalContext": "Self-review before finishing:\n1. Did you leave any TODO/FIXME comments that should be resolved now?\n2. Did you create mock or fake implementations just to pass tests?\n3. Did you replace real code with placeholder comments like '// ... existing code'?\n4. Do all changed files compile and typecheck cleanly?\n5. Did you run the full test suite, not just the new tests?\n6. Are there any files you modified but forgot to include in the summary?"
+  }
+}
+REVIEW_JSON