claude-dev-kit 2.1.0 → 2.1.2

package/.claude/commands/init.md

@@ -246,7 +246,54 @@ Files to update:
 - Dev commands table (extracted from `package.json` `scripts` or language conventions)
 - Validation gate commands
 
-### 5c. Update .claude/settings.json
+### 5c. Generate CLAUDE.local.md.example
+
+If `CLAUDE.local.md.example` does not already exist in the project root, copy `.claude/templates/CLAUDE.local.md.example` (or generate the standard template) so developers know they can create a personal `CLAUDE.local.md`.
+
+Also ensure `.gitignore` (or `.git/info/exclude` for projects without a shared `.gitignore`) contains `CLAUDE.local.md`.
+
+### 5d. Scaffold stack-specific rules overrides
+
+Check if `.claude/rules/` already exists. If not present, note to the user that the generic rules installed with CDK cover universal patterns. If a stack-specific rules file would add value (e.g., a `db-conventions.md` for Prisma schema practices, or a `components.md` for Next.js component hierarchy), generate it now:
+
+**Next.js + Prisma projects** — create `.claude/rules/db-conventions.md`:
+```markdown
+---
+globs: "prisma/**,app/generated/**,lib/db*"
+---
+
+# Database Conventions (Prisma)
+
+- Schema lives at `prisma/schema.prisma` — all model changes start here
+- Run `bun prisma migrate dev` to generate migrations from schema changes
+- Never edit generated migration files — re-generate if incorrect
+- Use `prisma.model.findFirst` for conflict checks — not `findUnique` on non-unique fields
+- Always call `db.refresh(obj)` / re-query after mutations to return updated state
+- Prisma client is a singleton — import from `lib/db`, never instantiate directly
+- Use `select` / `include` to fetch only the fields the caller needs
+```
+
+**FastAPI + SQLAlchemy projects** — create `.claude/rules/db-conventions.md`:
+```markdown
+---
+globs: "app/models/**,app/schemas/**,alembic/**"
+---
+
+# Database Conventions (SQLAlchemy 2.x)
+
+- Models at `app/models/<domain>.py` — use `mapped_column` and `Mapped[T]` for all columns
+- Schemas at `app/schemas/<domain>.py` — separate `Create`, `Update`, `Out` Pydantic models
+- Migrations via Alembic — never edit the DB schema directly in production
+- Use `AsyncSession` throughout — never use synchronous session in async endpoints
+- Always `await db.refresh(obj)` after commit to return accurate data to the caller
+- Use SQLAlchemy 2.x `select()` / `insert()` — no raw SQL unless absolutely necessary
+```
+
+**Express.js projects** — create `.claude/rules/db-conventions.md` if an ORM is detected, following the same pattern.
+
+Skip this step if stack is `generic` or no database layer was detected.
+
+### 5e. Update .claude/settings.json
 
 Read existing settings.json. Preserve the `hooks` section verbatim. Replace only the `permissions.allow` array with:
 
@@ -294,12 +341,20 @@ Read existing settings.json. Preserve the `hooks` section verbatim. Replace only
 - `.claude/agents/dev-e2e.md` — Playwright patterns
 - `CLAUDE.md` — project guide created/updated
 - `.claude/settings.json` — permissions updated
+- `.claude/rules/code-style.md` — universal code quality rules (all files)
+- `.claude/rules/security.md` — universal security practices (all files)
+- `.claude/rules/api-conventions.md` — HTTP/REST conventions (api/** files, path-scoped)
+- `.claude/rules/testing.md` — test structure and coverage rules (test files, path-scoped)
+- `.claude/rules/db-conventions.md` — database/ORM conventions (stack-specific, if applicable)
+- `CLAUDE.local.md.example` — personal override template (copy to `CLAUDE.local.md`)
 
 ### Next Steps
-1. **Review** `CLAUDE.md` and add any project-specific conventions
-2. **Run** `/primer` to verify Claude understands the project
-3. **Plan** your backlog: `/pm:groom` → `/pm:size` → `/pm:plan-epic`
-4. **Build**: `/dev <issue-number>` to implement your first feature
+1. **Personal setup**: Copy `CLAUDE.local.md.example` → `CLAUDE.local.md` and fill in your preferences (it's gitignored)
+2. **Review** `CLAUDE.md` and add any project-specific notes in the Project Notes section
+3. **Customize rules**: Edit `.claude/rules/*.md` files for project-specific conventions
+4. **Run** `/primer` to verify Claude understands the project
+5. **Plan** your backlog: `/pm:groom` → `/pm:size` → `/pm:plan-epic`
+6. **Build**: `/dev <issue-number>` to implement your first feature
 ```
 
 ---

package/.claude/rules/api-conventions.md

@@ -0,0 +1,39 @@
+---
+globs: "src/api/**,app/api/**,src/routes/**,src/controllers/**,app/**/route.ts,app/**/route.tsx"
+---
+
+# API Layer Conventions
+
+Routes are thin. They validate input, delegate to services, and return responses. Business logic lives in services.
+
+## Structure
+
+- Validate all input at the route boundary (Zod / Pydantic) **before** calling any service function
+- Services raise domain exceptions — routes catch them and translate to HTTP responses
+- Never import DB clients directly in route handlers — use service functions
+- Auth middleware runs before every protected route — never check auth inside services
+
+## Response Shape
+
+Always return consistent JSON:
+- **Success**: the resource or `{ "data": ... }` wrapper
+- **Error**: `{ "error": "human-readable message" }` or `{ "error": { "field": "message" } }` for validation
+
+## HTTP Status Codes
+
+| Status | When to use |
+|--------|-------------|
+| `200` | Successful GET / PUT / PATCH |
+| `201` | Resource created (POST) |
+| `204` | Success with no body (DELETE) |
+| `400` | Bad input / validation failure |
+| `401` | Not authenticated |
+| `403` | Authenticated but not authorized |
+| `404` | Resource not found |
+| `409` | Conflict (duplicate, slot already taken) |
+| `422` | Valid schema but fails business rules |
+| `500` | Unexpected server error — never expose details |
+
+## Pagination
+
+For list endpoints returning potentially large sets: use cursor-based pagination. Return `{ data: [], nextCursor: string | null }`.

package/.claude/rules/code-style.md

@@ -0,0 +1,14 @@
+# Code Style
+
+Keep code readable, explicit, and maintainable. These rules apply to all files in this project.
+
+- Files stay under 500 lines — split into smaller modules when exceeded
+- Functions do one thing and are named for what they do, not how they do it
+- Prefer explicit over implicit — avoid magic strings, side-effect-heavy imports, or clever tricks
+- No commented-out code in commits
+- No `any` types in TypeScript — use `z.infer<typeof Schema>`, Prisma/Drizzle generated types, or `unknown`
+- Environment variables must go through a typed config module — never use `process.env.X` inline across the codebase
+- Hard-code nothing that belongs in config: URLs, timeouts, limits, feature flags
+- Separate concerns: keep route/handler, service/use-case, and data-access layers distinct
+- External dependencies (DB, API clients, queues) must be injectable for testability
+- Handle all error paths explicitly — no silent failures or swallowed exceptions

package/.claude/rules/security.md

@@ -0,0 +1,14 @@
+# Security
+
+These rules apply to all files. When in doubt, err on the side of caution.
+
+- Never commit secrets, API keys, tokens, or credentials — use environment variables and `.gitignore`
+- Validate **all** input at system boundaries (API routes, CLI args, file uploads, webhooks) before processing
+- Never expose internal error messages, stack traces, or DB query details to API clients
+- Use parameterized queries or an ORM — never concatenate user input into raw SQL strings
+- Sanitize user-supplied content before rendering in HTML to prevent XSS
+- Authentication checks must happen before any business logic — never after
+- Reject unexpected fields in API payloads using strict schema validation (Zod `strict()`, Pydantic `model_config = ConfigDict(extra="forbid")`)
+- Log security events (failed auth, rate-limit hits, permission denials) but never log sensitive values (passwords, tokens, PII)
+- Use `httpOnly` + `Secure` + `SameSite=Strict` cookie attributes for session tokens
+- Apply the principle of least privilege: request only the permissions/scopes your code actually needs

package/.claude/rules/testing.md

@@ -0,0 +1,16 @@
+---
+globs: "**/*.test.ts,**/*.test.tsx,**/*.spec.ts,**/*.spec.tsx,**/*.test.py,**/tests/**,**/__tests__/**"
+---
+
+# Testing Conventions
+
+- **AAA pattern**: Arrange → Act → Assert — one clear block per concern
+- Test behavior, not implementation: test what a function *does*, not how it does it internally
+- Test names describe the scenario in plain language: `"returns 409 when slot is already booked"`
+- Cover: happy path, each distinct error path, and boundary conditions
+- **Dependency injection for mocking** — avoid module-level patching when the code supports DI
+- 90%+ branch coverage on all new and modified files
+- No arbitrary `sleep()` or `setTimeout()` in tests — use proper async waiting mechanisms
+- Never test private methods or internal state directly — test through the public interface
+- One `describe` block per unit/feature — keep test files focused
+- Mock at the seam closest to the external dependency (DB, HTTP, filesystem)

package/.claude/settings.json.example

@@ -0,0 +1,81 @@
+{
+  "_comment": "Copy this file to settings.json. It is gitignored — each developer configures their own.",
+  "_hooks_note": "The hooks block below is the CDK default. If you have an existing settings.json, merge this hooks section into it.",
+  "permissions": {
+    "allow": [
+      "Read",
+      "Write",
+      "Edit",
+      "Bash(git:*)",
+      "Bash(gh:*)",
+      "Bash(grep:*)",
+      "Bash(ls:*)",
+      "Bash(tree:*)",
+      "Bash(find:*)",
+      "Bash(cat:*)",
+      "Bash(echo:*)",
+      "Bash(gemini:*)",
+      "Bash(gemini -p:*)",
+      "Bash(opencode:*)",
+      "Bash(which:*)",
+      "Bash(python:*)",
+      "Bash(python3:*)",
+      "Bash(mkdir:*)",
+      "Bash(touch:*)",
+      "Bash(ollama:*)"
+    ],
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(chmod 777:*)",
+      "Read(.env)",
+      "Read(.env.*)",
+      "Edit(.claude/settings.json)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo \"For context, today's date is $(date). Please keep this in mind.\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/pre-tool-use/block-dangerous-commands.js"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .claude/hooks/stop/context_monitor.py"
+          },
+          {
+            "type": "command",
+            "command": "python .claude/hooks/stop/learning_logger.py"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd .claude/hooks/skill-activation-prompt && node_modules/.bin/tsx skill-activation-prompt.ts"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/templates/claude-md-template.md

@@ -35,6 +35,16 @@
 ## Key Conventions
 <!-- KEY_CONVENTIONS -->
 
+> Detailed rules live in `.claude/rules/` — Claude loads them automatically:
+> - `code-style.md` — code quality and structure rules (all files)
+> - `security.md` — security practices (all files)
+> - `api-conventions.md` — HTTP status codes, response shapes, route structure (api/** files)
+> - `testing.md` — AAA pattern, coverage targets, mock strategy (test files)
+
+## Personal Overrides
+
+Copy `CLAUDE.local.md.example` → `CLAUDE.local.md` to set personal preferences (gitignored).
+
 ## Agent System (Claude Dev Kit)
 This project uses the claude-dev-kit autonomous development pipeline:
 

package/CLAUDE.local.md.example

@@ -0,0 +1,36 @@
+# CLAUDE.local.md — Personal Overrides
+
+> This file is personal to you. Copy it to `CLAUDE.local.md` (which is gitignored).
+> It loads alongside `CLAUDE.md` but never affects your teammates.
+
+---
+
+## My Experience Level
+
+<!-- Tell Claude how to calibrate explanations for you. -->
+<!-- Examples: -->
+<!-- "I'm a senior TypeScript engineer — skip basics, focus on tradeoffs." -->
+<!-- "I'm new to Prisma; explain ORM concepts when they come up." -->
+
+## My Local Setup
+
+<!-- Override project defaults for your machine. -->
+<!-- Examples: -->
+<!-- Local DB: postgresql://localhost:5432/myapp_dev -->
+<!-- Dev server port: 4000 -->
+<!-- I run migrations with: bun prisma migrate dev -->
+
+## My Workflow Preferences
+
+<!-- Personal habits Claude should respect. -->
+<!-- Examples: -->
+<!-- "Always show me the full file diff before writing, so I can approve." -->
+<!-- "I prefer smaller, focused PRs over large bundled ones." -->
+<!-- "Skip test output summaries — I'll read the raw output myself." -->
+
+## Editor / Terminal
+
+<!-- Context that helps Claude format output usefully for your environment. -->
+<!-- Examples: -->
+<!-- Terminal: Ghostty (supports 256 colors, Unicode) -->
+<!-- "When showing multi-file changes, use unified diff format." -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-dev-kit",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Transform Claude Code into a fully autonomous development team — orchestrated sub-agents for planning, implementation, testing, and review.",
   "bin": {
     "claude-dev-kit": "./bin/claude-dev-kit.js"
@@ -10,8 +10,11 @@
     ".claude/agents/",
     ".claude/commands/",
     ".claude/hooks/",
+    ".claude/rules/",
+    ".claude/settings.json.example",
     ".claude/skills/",
     ".claude/templates/",
+    "CLAUDE.local.md.example",
     "scripts/install.sh"
   ],
   "keywords": [
@@ -22,7 +25,9 @@
     "developer-tools",
     "autonomous-development"
   ],
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/scripts/install.sh

@@ -126,27 +126,19 @@ if [[ "$MCP_ONLY" == "false" ]]; then
     ask_yn "Install .claude/ into $TARGET?" || { echo "Aborted."; exit 0; }
   fi
 
-  # Backup existing .claude
-  if [[ -d "$TARGET/.claude" ]]; then
-    BACKUP="$TARGET/.claude.bak.$(date +%Y%m%d_%H%M%S)"
-    warn "Existing .claude/ found — backing up to $(basename "$BACKUP")"
-    mv "$TARGET/.claude" "$BACKUP"
-  fi
-
-  # Copy files
-  info "Copying .claude/ ..."
-  if command -v rsync &>/dev/null; then
-    rsync -a --exclude='node_modules' --exclude='*.jsonl' \
-      "$KIT_ROOT/.claude/" "$TARGET/.claude/"
+  # ── Delegate all .claude/ file management to the migration tool ──────────────
+  # migrate.sh handles: categorization, conflict resolution, settings.json merge,
+  # CLAUDE.md merge, and manifest maintenance. It is safe to run standalone.
+  if bash "$SCRIPT_DIR/migrate.sh" "$KIT_ROOT" "$TARGET"; then
+    : # migrate.sh prints its own success messages
   else
-    cp -r "$KIT_ROOT/.claude" "$TARGET/.claude"
-    rm -rf "$TARGET/.claude/hooks/skill-activation-prompt/node_modules"
+    error "Migration failed — check output above"
+    exit 1
   fi
-  success ".claude/ installed"
 
-  # Ensure log directory exists now that .claude/ is present
+  # Ensure log directory + file exist now that .claude/ is present
   mkdir -p "$TARGET/.claude"
-  : > "$LOG_FILE"  # create/truncate log
+  : > "$LOG_FILE"
 
   # ── Inject .gitignore entries into target project ────────────────────────────
   TARGET_GITIGNORE="$TARGET/.gitignore"
@@ -154,20 +146,31 @@ if [[ "$MCP_ONLY" == "false" ]]; then
   if [[ -f "$TARGET_GITIGNORE" ]] && grep -qF "$GITIGNORE_MARKER" "$TARGET_GITIGNORE" 2>/dev/null; then
     info ".gitignore already contains CDK entries — skipping"
   else
-    info "Adding .gitignore entries to protect secrets..."
+    info "Adding .gitignore entries..."
     cat >> "$TARGET_GITIGNORE" <<'EOF'
 
 # Claude Dev Kit — managed entries
 # settings.json may contain MCP API tokens written by install.sh — never commit it.
 .claude/settings.json
-# Audit log and install log contain local paths — no need to track.
+# Audit log, install log, and migration manifest contain local paths — no need to track.
 .claude/audit.log
 .claude/install.log
+.claude/.cdk-manifest
+# Personal Claude overrides — machine-local, never shared with teammates.
+CLAUDE.local.md
 EOF
-    success ".gitignore updated (settings.json, audit.log, install.log excluded)"
+    success ".gitignore updated"
   fi
 
-  # Install hook dependencies
+  # ── Copy CLAUDE.local.md.example if not present ──────────────────────────────
+  EXAMPLE_SRC="$KIT_ROOT/CLAUDE.local.md.example"
+  EXAMPLE_DEST="$TARGET/CLAUDE.local.md.example"
+  if [[ -f "$EXAMPLE_SRC" && ! -f "$EXAMPLE_DEST" ]]; then
+    cp "$EXAMPLE_SRC" "$EXAMPLE_DEST"
+    info "CLAUDE.local.md.example added — copy to CLAUDE.local.md for personal preferences"
+  fi
+
+  # ── Install hook dependencies ─────────────────────────────────────────────
   HOOK_DIR="$TARGET/.claude/hooks/skill-activation-prompt"
   if [[ -f "$HOOK_DIR/package.json" ]]; then
     info "Installing skill-activation-prompt hook dependencies..."
@@ -186,6 +189,7 @@ EOF
     popd > /dev/null
     success "Hook dependencies installed"
   fi
+
 fi
 
 # ─── Phase 2: MCP Wizard ──────────────────────────────────────────────────────
@@ -415,9 +419,10 @@ header "Installation Complete 🎉"
 echo ""
 
 if [[ "$MCP_ONLY" == "false" ]]; then
-  echo -e "  ${GREEN}✓${NC} .claude/ installed at $TARGET/.claude"
+  echo -e "  ${GREEN}✓${NC} .claude/ merged into $TARGET/.claude"
   echo -e "  ${GREEN}✓${NC} Hook dependencies installed"
   echo -e "  ${GREEN}✓${NC} .gitignore updated (settings.json excluded)"
+  echo -e "  ${DIM}  settings.json and CLAUDE.md were preserved if they existed${NC}"
 fi
 
 echo ""