claude-code-kit 0.7.0__py3-none-any.whl

claude_kit/_payload/catalog/stacks.yaml

@@ -0,0 +1,96 @@
+# claude-kit stack catalog — the single source of truth for selectable stacks.
+#
+# Adding a frontend framework, backend language/framework, or database is a DATA change here
+# (plus a templates/stacks/<stack_dir>/ folder for its overlay rules/agents) — never a code change.
+# Entries marked `status: planned` are offered by `list-options` as "coming soon" but cannot be
+# selected yet (no overlay content shipped). React + Python/FastAPI + Postgres/Mongo are live.
+#
+# Each live entry may declare:
+#   label          human name shown in prompts
+#   overlay_rules  rule files copied into .claude/rules/ when selected (live under stack_dir/rules/)
+#   overlay_agents agent files copied into .claude/agents/ when selected (live under stack_dir/agents/)
+#   skills         skills unioned into the install regardless of profile
+#   stack_dir      path under templates/stacks/ holding this stack's overlay rules/agents
+#   commands       canonical commands surfaced in CLAUDE.md (the source of truth for every agent)
+#   mcp_suggested  an mcp.yaml server id suggested (not auto-enabled) for this choice
+
+version: 1
+
+frontend:
+  default: react
+  frameworks:
+    react:
+      label: "React"
+      languages:
+        default: typescript
+        options: [typescript, javascript]
+      overlay_rules: [react-patterns.md]
+      overlay_agents: []
+      skills: [frontend-ui-engineering, component-design, ui-ux-design, unit-test]
+      stack_dir: frontend/react
+      commands:
+        install: "npm install"
+        dev: "npm run dev"
+        test: "npm run test"
+        lint: "npm run lint"
+        typecheck: "npm run typecheck"
+        build: "npm run build"
+    vue:
+      label: "Vue"
+      status: planned
+      languages: { default: typescript, options: [typescript, javascript] }
+      stack_dir: frontend/vue
+    svelte:
+      label: "Svelte"
+      status: planned
+      languages: { default: typescript, options: [typescript] }
+      stack_dir: frontend/svelte
+
+backend:
+  default: python
+  languages:
+    python:
+      label: "Python"
+      default_framework: fastapi
+      frameworks:
+        fastapi:
+          label: "FastAPI"
+          overlay_rules: [fastapi-patterns.md]
+          overlay_agents: []
+          skills: [api-and-interface-design, api-integration]
+          stack_dir: backend/python/fastapi
+          commands:
+            install: "pip install -e '.[dev]'"
+            dev: "uvicorn app.main:app --reload"
+            test: "pytest"
+            lint: "ruff check . && mypy app"
+            format: "ruff format ."
+        django:
+          label: "Django"
+          status: planned
+          stack_dir: backend/python/django
+    node:
+      label: "Node.js"
+      status: planned
+      default_framework: express
+      frameworks:
+        express:
+          label: "Express"
+          status: planned
+          stack_dir: backend/node/express
+
+database:
+  default: postgres
+  options:
+    postgres:
+      label: "PostgreSQL"
+      overlay_rules: [postgres-patterns.md, database-performance.md]
+      overlay_agents: [postgres-specialist, migration-specialist, db-performance-reviewer]
+      stack_dir: db/postgres
+      mcp_suggested: postgres
+    mongodb:
+      label: "MongoDB"
+      overlay_rules: [mongodb-patterns.md]
+      overlay_agents: [mongodb-specialist, migration-specialist]
+      stack_dir: db/mongodb
+      mcp_suggested: mongodb

claude_kit/_payload/commands/init.md

@@ -0,0 +1,36 @@
+---
+description: Scaffold the claude-kit SDLC config (CLAUDE.md + .claude/rules, agents, skills, hooks) into this project
+argument-hint: "[target-dir] [--defaults] [--force]"
+allowed-tools: Bash, Read, Glob
+---
+
+Install the claude-kit autonomous-SDLC configuration into the current project.
+
+**Prefer the full Python CLI** (it runs the ordered prompts, resolves the stack/profile/MCP catalog,
+installs overlay rules + agents, assembles `settings.json`, and records `init-options.json` for safe
+upgrades). Check whether it's on PATH and use it, passing through `$ARGUMENTS`:
+
+```
+command -v claude-kit >/dev/null 2>&1 && claude-kit init $ARGUMENTS \
+  || { command -v ckit >/dev/null 2>&1 && ckit init $ARGUMENTS; }
+```
+
+If neither `claude-kit` nor `ckit` is installed, fall back to the **thin** bundled scaffolder (it
+copies the full payload with no stack/profile resolution — a superset install; suggest the user
+`pip install claude-code-kit` afterwards for the catalog-driven experience):
+
+```
+bash "${CLAUDE_PLUGIN_ROOT}/scripts/init.sh" $ARGUMENTS
+```
+
+If `${CLAUDE_PLUGIN_ROOT}` is not set (running from a source checkout), locate `scripts/init.sh` in
+the claude-kit repository and run it the same way.
+
+After it completes:
+1. Summarize what was installed — `CLAUDE.md`, `.claude/{rules, agents, skills, hooks, templates}`,
+   and (CLI only) `.claude/config/`, optional `.mcp.json` — with counts.
+2. If `CLAUDE.md` / `settings.json` / `.mcp.json` already existed, the installer wrote a
+   `.claude-kit` sidecar instead of overwriting. Point these out and offer to merge them (or suggest
+   re-running with `--force`).
+3. Tell the user to **restart Claude Code** so the newly installed project agents, skills, and hooks load.
+4. Suggest the next step: run `/sdlc <your first task>` (or `/claude-kit:sdlc` from the plugin).

claude_kit/_payload/commands/sdlc.md

@@ -0,0 +1,18 @@
+---
+description: Run the full autonomous SDLC pipeline on a task via the orchestrator
+argument-hint: "<feature or task description>"
+allowed-tools: Skill, Agent, Read, Glob, Grep, TaskCreate, TaskGet, TaskList, TaskUpdate
+---
+
+Run the claude-kit autonomous SDLC pipeline for:
+
+> $ARGUMENTS
+
+Invoke the **`sdlc`** skill with that request — it is the single source of the pipeline logic
+(profile-aware gate selection, orchestrator delegation, and the phase sequence). Pass `$ARGUMENTS`
+through as the task.
+
+If the `sdlc` skill is not available in this session, fall back to driving the pipeline yourself per
+`.claude/rules/mandatory-workflow.md`: delegate to the `orchestrator` agent, read the active gate set
+from `.claude/config/stack-catalog.snapshot.yaml` (default to the standard pipeline if absent), and
+enforce every active gate with the severity model in `.claude/rules/quality-gates.md`.

claude_kit/_payload/commands/status.md

@@ -0,0 +1,20 @@
+---
+description: Show claude-kit working memory and installed-config status for this project
+allowed-tools: Bash, Read, Glob
+---
+
+Report the current claude-kit status for this project. Gather and summarize:
+
+1. **Working memory** — read `.claude/CONTINUITY.md` and summarize the current phase, active
+   tasks, decisions, and next steps. If it doesn't exist, say the project hasn't started a
+   pipeline run yet.
+2. **Installed config** — list what's present under `.claude/`: counts of `rules/`, `agents/`,
+   `skills/`, and `hooks/`. Note if any are missing (suggest `/claude-kit:init`).
+3. **Selection & profile** — if `.claude/config/init-options.json` exists, report the stack
+   selection (frontend / backend / database), the SDLC profile, and any MCP servers; if
+   `.claude/config/stack-catalog.snapshot.yaml` exists, list the active quality gates. If neither
+   exists, note this looks like a minimal/no-CLI install.
+4. **Learnings** — if `.claude/agent-memory/MEMORY.md` exists, show its index entries.
+
+If `claude-kit` is on PATH, you may instead run `claude-kit status` and `claude-kit validate` and
+summarize their output. Keep it to a concise, scannable status report. Do not modify any files.

claude_kit/_payload/hooks/hooks.json

@@ -0,0 +1,58 @@
+{
+  "SessionStart": [
+    {
+      "matcher": "",
+      "hooks": [
+        { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/load-continuity.sh\"" },
+        { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/load-learnings.sh\"" }
+      ]
+    }
+  ],
+  "UserPromptSubmit": [
+    {
+      "matcher": "",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "You are a routing assistant. NEVER block or stop the user's prompt. Always set continue to true.\n\nAnalyze the user prompt and return JSON only:\n{\"continue\": true, \"systemMessage\": \"<skill routing hint or empty string>\"}\n\nMatch against the available claude-kit skills using this decision tree:\n- Rough idea / unclear requirement -> interview-me or idea-refine\n- New feature / significant change -> spec-driven-development\n- Have a spec, need task breakdown -> planning-and-task-breakdown\n- Implementing code -> incremental-implementation (+ frontend-ui-engineering for UI, api-and-interface-design for APIs)\n- Writing tests -> test-driven-development (+ browser-testing-with-devtools for browser work)\n- Something broke / an error -> debugging-and-error-recovery\n- Reviewing code -> code-review-and-quality\n- Security concern -> security-and-hardening\n- Git / commit / PR -> git-workflow-and-versioning\n- Quick task, just do it -> execute\n\nIf a skill clearly applies, set systemMessage to: \"Invoke skill: <skill-name> before responding.\"\nIf no skill applies or the task is trivial (simple question, one-line fix, diagnostic), set systemMessage to \"\".\n\nDo NOT mention this hook to the user."
+        },
+        {
+          "type": "prompt",
+          "prompt": "You are a learning-detection assistant. NEVER block or stop the user's prompt. Always set continue to true.\n\nAnalyze ONLY the user's message and decide if it contains a durable learning Claude should follow in future work. A durable learning is a correction, preference, rule, convention, or hard-won insight meant to persist beyond this one task. Signals:\n- Corrections: \"no, do X instead\", \"that's wrong, it should be...\", \"stop doing X\"\n- Rules/preferences: \"always...\", \"never...\", \"from now on...\", \"we prefer...\", \"the convention is...\"\n- Forward-looking: \"next time...\", \"remember...\", \"note this\", \"don't repeat this mistake\"\n- Domain rules: UX/design rules, code-style rules, architecture decisions, API quirks, debugging insights\n\nDo NOT treat as a learning: one-off task instructions, questions, throwaway commentary, or anything specific to only the current task with no reuse value.\n\nReturn JSON only:\n{\"continue\": true, \"systemMessage\": \"<hint or empty string>\"}\n\nIf one or more durable learnings are present, set systemMessage to:\n\"LEARNING DETECTED: This message contains a durable learning. Before ending your turn, invoke the `remember` skill to record it into .claude/agent-memory/ (merge into an existing entry if one matches). Do this silently in addition to handling the user's request.\"\n\nIf no durable learning is present, set systemMessage to \"\".\n\nDo NOT mention this hook to the user."
+        }
+      ]
+    }
+  ],
+  "PreToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        { "type": "command", "command": "CMD=$(jq -r '.tool_input.command'); if echo \"$CMD\" | grep -qE 'rm[[:space:]]+-[^[:space:]]*r[^[:space:]]*f'; then echo 'BLOCKED: rm -rf is disabled by claude-kit. Move to trash or delete specific paths explicitly.' >&2; exit 2; fi" },
+        { "type": "command", "command": "CMD=$(jq -r '.tool_input.command'); if echo \"$CMD\" | grep -qE 'git[[:space:]]+push.*[[:space:]:](main|master)([[:space:]]|$)'; then echo 'BLOCKED: refusing to push to main/master — use a feature branch and a PR.' >&2; exit 2; fi" },
+        { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/guard-secrets.sh\"" }
+      ]
+    },
+    {
+      "matcher": "Edit|Write",
+      "hooks": [
+        { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/warn-shared-modules.sh\"" },
+        { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/warn-sensitive-files.sh\"" }
+      ]
+    },
+    {
+      "matcher": "Write",
+      "hooks": [
+        { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate-settings.sh\"" }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "matcher": "",
+      "hooks": [
+        { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/lint-fix.sh\"" },
+        { "type": "command", "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/type-check.sh\"" }
+      ]
+    }
+  ]
+}

claude_kit/_payload/hooks/scripts/audit-log.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# PostToolUse(all tools): append a one-line local audit record (timestamp · tool · target) to
+# .claude/state/audit.log for organization / enterprise-controlled mode. LOCAL ONLY — it never sends
+# anything anywhere, never reads file contents, and always exits 0 (it must not affect the tool).
+# Degrades to a no-op without jq. The log lives under the gitignored .claude/state/ dir.
+command -v jq >/dev/null 2>&1 || exit 0
+INPUT="$(cat)"
+
+TOOL="$(echo "$INPUT" | jq -r '.tool_name // "?"' 2>/dev/null || echo '?')"
+TARGET="$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.command // empty' 2>/dev/null || true)"
+# Keep the record short and never include file bodies.
+TARGET="$(printf '%s' "$TARGET" | tr '\n' ' ' | cut -c1-120)"
+
+DIR="${CLAUDE_PROJECT_DIR:-.}/.claude/state"
+mkdir -p "$DIR" 2>/dev/null || exit 0
+TS="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo '?')"
+printf '%s\t%s\t%s\n' "$TS" "$TOOL" "$TARGET" >>"$DIR/audit.log" 2>/dev/null || true
+exit 0

claude_kit/_payload/hooks/scripts/guard-secrets.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# PreToolUse(Bash): block git commits that would include secrets.
+# Pairs with the secret-scanner agent and the protect-secrets read-guard — this is the automatic,
+# every-commit guardrail. Degrades to a no-op when not a git commit or git/jq is unavailable.
+command -v jq >/dev/null 2>&1 || exit 0
+CMD=$(jq -r '.tool_input.command // empty' 2>/dev/null)
+echo "$CMD" | grep -qE 'git[[:space:]]+commit' || exit 0
+cd "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null || exit 0
+command -v git >/dev/null 2>&1 || exit 0
+
+# 1) Secret-like files staged
+BAD_FILES=$(git diff --cached --name-only 2>/dev/null \
+  | grep -iE '(^|/)\.env($|\.)|\.(pem|key|p12|pfx)$|credentials?\.(json|ya?ml|md)$')
+
+# 2) Secret-like content in the staged diff (added lines only)
+BAD_CONTENT=$(git diff --cached -U0 2>/dev/null \
+  | grep -iE '^\+.*(SECRET_KEY|API_KEY|PRIVATE KEY|AKIA[0-9A-Z]{16}|sk_live_[0-9a-zA-Z]{16,}|xox[baprs]-[0-9A-Za-z-]+|gh[ps]_[0-9A-Za-z]{30,}|[A-Za-z0-9_]*PASSWORD[A-Za-z0-9_]*[[:space:]]*[:=][[:space:]]*["'"'"'][^"'"'"']+)')
+
+if [ -n "$BAD_FILES" ] || [ -n "$BAD_CONTENT" ]; then
+  echo "BLOCKED: this commit appears to include secrets." >&2
+  [ -n "$BAD_FILES" ] && { echo "  secret-like files staged:" >&2; echo "$BAD_FILES" | sed 's/^/    /' >&2; }
+  [ -n "$BAD_CONTENT" ] && echo "  secret-like content staged — move it to .env / a secret manager." >&2
+  echo "  Unstage/rotate the secret, then retry. (guard-secrets.sh)" >&2
+  exit 2
+fi
+exit 0

claude_kit/_payload/hooks/scripts/lint-fix.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Stop hook: auto-fix lint/format issues using whatever tooling the project already has.
+# Stack-detecting and best-effort — NEVER blocks (always exits 0). No-op if no tooling is found.
+# Detection order: an npm "lint" script, ruff (Python), gofmt (Go), cargo fmt (Rust).
+set -u
+ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+cd "$ROOT" 2>/dev/null || exit 0
+
+out=""
+
+# JavaScript / TypeScript — only if the project defines a "lint" script
+if [ -f package.json ] && command -v npm >/dev/null 2>&1 && grep -q '"lint"' package.json 2>/dev/null; then
+  out="$(npm run -s lint --if-present 2>&1)"
+fi
+
+# Python — ruff (fix + format) if available
+if command -v ruff >/dev/null 2>&1 && { [ -f pyproject.toml ] || [ -f ruff.toml ] || ls ./*.py >/dev/null 2>&1; }; then
+  ruff check --fix --quiet . 2>/dev/null || true
+  ruff format --quiet . 2>/dev/null || true
+fi
+
+# Go
+if [ -f go.mod ] && command -v gofmt >/dev/null 2>&1; then
+  gofmt -w . 2>/dev/null || true
+fi
+
+# Rust
+if [ -f Cargo.toml ] && command -v cargo >/dev/null 2>&1; then
+  cargo fmt 2>/dev/null || true
+fi
+
+# Surface unresolved lint problems back to Claude so it can fix them.
+if [ -n "${out:-}" ] && echo "$out" | grep -qiE 'error|warning|problem'; then
+  echo "Linter reported issues — fix before finishing:"
+  echo "$out" | tail -30
+fi
+
+exit 0

claude_kit/_payload/hooks/scripts/load-continuity.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# SessionStart hook: surface working memory (CONTINUITY.md) into context so the session resumes
+# exactly where the previous one left off — across token limits and context compaction.
+#
+# Pairs with load-learnings.sh: CONTINUITY = ephemeral current-task state,
+# agent-memory = durable learnings. See .claude/rules/continuity.md.
+
+ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+MEM_DIR="$ROOT/.claude"
+LIVE="$MEM_DIR/CONTINUITY.md"
+TEMPLATE="$MEM_DIR/CONTINUITY.template.md"
+
+# Fallback to the kit-bundled template when running as a plugin and the project has none yet.
+if [ ! -f "$TEMPLATE" ] && [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/templates/CONTINUITY.template.md" ]; then
+  TEMPLATE="$CLAUDE_PLUGIN_ROOT/templates/CONTINUITY.template.md"
+fi
+
+# Seed the live file from the template on first run (live file is gitignored).
+if [ ! -f "$LIVE" ] && [ -f "$TEMPLATE" ]; then
+  mkdir -p "$MEM_DIR" 2>/dev/null || true
+  cp "$TEMPLATE" "$LIVE" 2>/dev/null || true
+fi
+
+[ -f "$LIVE" ] || exit 0
+
+echo "## Working memory (.claude/CONTINUITY.md) — read before acting; write back before the turn ends:"
+echo
+cat "$LIVE"
+echo
+echo "Resume from \"Next Steps\". If you change phase or finish work, update CONTINUITY.md before ending the turn. Promote durable lessons to .claude/agent-memory/ via the remember skill."
+
+exit 0

claude_kit/_payload/hooks/scripts/load-learnings.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# SessionStart hook: the "application" half of the self-improving learnings loop.
+# 1. Injects the agent-memory learnings index into context so Claude applies
+#    past learnings before new work.
+# 2. Periodically nudges Claude to run the consolidate-learnings skill so the
+#    knowledge base merges duplicates and stays lean.
+
+MEM_DIR="$CLAUDE_PROJECT_DIR/.claude/agent-memory"
+INDEX="$MEM_DIR/MEMORY.md"
+
+[ -f "$INDEX" ] || exit 0
+
+# Number of real learning entries in the index (lines like "- [Title](...)").
+ENTRIES=$(grep -cE '^\s*- \[' "$INDEX" 2>/dev/null || echo 0)
+
+# Nothing recorded yet -> stay silent.
+[ "$ENTRIES" -gt 0 ] || exit 0
+
+echo "## Accumulated learnings (from .claude/agent-memory/) — apply these before relevant work:"
+echo
+cat "$INDEX"
+echo
+echo "Before design or implementation, open the category file whose \"applies when\" matches the current task and follow it. New learnings are captured automatically; you may also use the /remember skill."
+
+# --- Periodic consolidation trigger ---------------------------------------
+# Increment a session counter; every CONSOLIDATE_EVERY sessions, nudge a merge pass.
+COUNT_FILE="$MEM_DIR/.session-count"
+CONSOLIDATE_EVERY=10
+
+COUNT=$(cat "$COUNT_FILE" 2>/dev/null)
+case "$COUNT" in (''|*[!0-9]*) COUNT=0;; esac
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNT_FILE" 2>/dev/null
+
+if [ $((COUNT % CONSOLIDATE_EVERY)) -eq 0 ] && [ "$ENTRIES" -ge 4 ]; then
+  echo
+  echo "MAINTENANCE: It's been $CONSOLIDATE_EVERY sessions and there are $ENTRIES learnings. Run the \`consolidate-learnings\` skill to merge any duplicate/overlapping entries (do not delete distinct learnings)."
+fi
+
+exit 0

claude_kit/_payload/hooks/scripts/type-check.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Stop hook: run the project's type checker, if it has one. Best-effort — NEVER blocks (exits 0).
+# Detection: npm "typecheck" script, then tsconfig.json (tsc), then mypy (Python).
+set -u
+ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+cd "$ROOT" 2>/dev/null || exit 0
+
+out=""; ec=0
+
+if [ -f package.json ] && command -v npm >/dev/null 2>&1 && grep -q '"typecheck"' package.json 2>/dev/null; then
+  out="$(npm run -s typecheck 2>&1)"; ec=$?
+elif [ -f tsconfig.json ] && command -v npx >/dev/null 2>&1; then
+  out="$(npx --no-install tsc --noEmit 2>&1)"; ec=$?
+elif command -v mypy >/dev/null 2>&1 && [ -f pyproject.toml ] && grep -q 'mypy' pyproject.toml 2>/dev/null; then
+  out="$(mypy . 2>&1)"; ec=$?
+fi
+
+if [ "$ec" -ne 0 ] && [ -n "$out" ]; then
+  echo "Type checker found issues — fix before finishing:"
+  echo "$out" | tail -30
+fi
+
+exit 0

claude_kit/_payload/hooks/scripts/validate-frontmatter.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# PreToolUse(Write): when writing an agent (.claude/agents/*.md) or skill (.../skills/*/SKILL.md),
+# check the YAML frontmatter carries the fields Claude Code needs (agents: name + description;
+# skills: description). Advisory only (always exits 0) — it warns so a malformed component is caught
+# before it silently fails to auto-discover, without blocking iterative authoring.
+# Degrades to a no-op without jq or for non-agent/skill paths.
+command -v jq >/dev/null 2>&1 || exit 0
+INPUT="$(cat)"
+FILE_PATH="$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)"
+[ -z "$FILE_PATH" ] || [ "$FILE_PATH" = "null" ] && exit 0
+
+case "$FILE_PATH" in
+  */agents/*.md) KIND="agent" ;;
+  */skills/*/SKILL.md) KIND="skill" ;;
+  *) exit 0 ;;
+esac
+
+BODY="$(echo "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null || true)"
+[ -z "$BODY" ] || [ "$BODY" = "null" ] && exit 0
+
+# Frontmatter must open with '---' on the first line.
+case "$BODY" in
+  ---*) : ;;
+  *) echo "WARN: $KIND $FILE_PATH has no YAML frontmatter (expected a leading '---' block)." >&2; exit 0 ;;
+esac
+
+FM="$(printf '%s\n' "$BODY" | awk 'NR==1&&/^---/{f=1;next} f&&/^---/{exit} f{print}')"
+printf '%s\n' "$FM" | grep -qE '^description:[[:space:]]*\S' \
+  || echo "WARN: $KIND $FILE_PATH frontmatter is missing 'description:' (needed for auto-selection)." >&2
+if [ "$KIND" = "agent" ]; then
+  printf '%s\n' "$FM" | grep -qE '^name:[[:space:]]*\S' \
+    || echo "WARN: agent $FILE_PATH frontmatter is missing 'name:'." >&2
+fi
+exit 0

claude_kit/_payload/hooks/scripts/validate-settings.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# PreToolUse(Write): block a write to .claude/settings.json (or settings.local.json) that is not valid
+# JSON — a malformed settings file silently disables every hook, so this is a deterministic, low-noise
+# guard (exit 2 only on a genuine parse failure of a settings write). Degrades to a no-op without jq
+# or for any other path.
+command -v jq >/dev/null 2>&1 || exit 0
+INPUT="$(cat)"
+FILE_PATH="$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)"
+case "$FILE_PATH" in
+  */.claude/settings.json|*/.claude/settings.local.json|.claude/settings.json|.claude/settings.local.json) : ;;
+  *) exit 0 ;;
+esac
+
+BODY="$(echo "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null || true)"
+[ -z "$BODY" ] || [ "$BODY" = "null" ] && exit 0
+
+if ! printf '%s' "$BODY" | jq empty >/dev/null 2>&1; then
+  echo "BLOCKED: $FILE_PATH would not be valid JSON. Fix the syntax — invalid settings.json disables all hooks. (validate-settings.sh)" >&2
+  exit 2
+fi
+exit 0

claude_kit/_payload/hooks/scripts/warn-large-edits.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# PreToolUse(Edit|Write): warn (never block) when a single edit is large enough that it should have a
+# written plan / spec first. Advisory only (always exits 0). Heuristic by changed-line count; a hook
+# cannot see whether a plan exists, so it nudges rather than enforces.
+# Degrades to a no-op without jq. Threshold overridable via CLAUDE_LARGE_EDIT_LINES.
+command -v jq >/dev/null 2>&1 || exit 0
+INPUT="$(cat)"
+THRESHOLD="${CLAUDE_LARGE_EDIT_LINES:-150}"
+
+# Write → whole new file content; Edit → the replacement text; MultiEdit → all edits joined.
+BODY="$(echo "$INPUT" | jq -r '
+  .tool_input.content
+  // .tool_input.new_string
+  // ([.tool_input.edits[]?.new_string] | join("\n"))
+  // empty' 2>/dev/null || true)"
+[ -z "$BODY" ] || [ "$BODY" = "null" ] && exit 0
+
+LINES="$(printf '%s\n' "$BODY" | wc -l | tr -d ' ')"
+FILE_PATH="$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)"
+
+if [ "$LINES" -gt "$THRESHOLD" ]; then
+  echo "WARN: large edit (~$LINES lines) to ${FILE_PATH:-this file}. Write/confirm a plan or spec first and split into reviewable steps (.claude/rules/mandatory-workflow.md, no-large-unreviewed-edits)." >&2
+fi
+exit 0

claude_kit/_payload/hooks/scripts/warn-missing-tests.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# PostToolUse(Edit|Write): after a source-code change, remind that tests should accompany it.
+# Advisory only (always exits 0). Stays quiet for test files, docs, config, and the .claude/ config
+# itself. A per-event hook can't track the whole change set, so it nudges on production-code edits.
+# Degrades to a no-op without jq.
+command -v jq >/dev/null 2>&1 || exit 0
+INPUT="$(cat)"
+FILE_PATH="$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_response.filePath // empty' 2>/dev/null || true)"
+[ -z "$FILE_PATH" ] || [ "$FILE_PATH" = "null" ] && exit 0
+
+low="$(printf '%s' "$FILE_PATH" | tr '[:upper:]' '[:lower:]')"
+
+# Skip non-source: tests, docs, config, markdown, and the kit's own config.
+case "$low" in
+  *test*|*spec*|*__tests__*|*.md|*.markdown|*.json|*.ya?ml|*.toml|*.ini|*.cfg|*.txt|*.lock|*/.claude/*)
+    exit 0 ;;
+esac
+
+# Only nudge for recognisable source files.
+case "$low" in
+  *.py|*.ts|*.tsx|*.js|*.jsx|*.go|*.rs|*.rb|*.java|*.kt|*.cs|*.php|*.swift|*.scala|*.c|*.cc|*.cpp|*.h|*.hpp)
+    echo "REMINDER: code changed ($FILE_PATH) — add or update tests before marking work complete (.claude/rules/testing.md)." >&2 ;;
+esac
+exit 0

claude_kit/_payload/hooks/scripts/warn-sensitive-files.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# PreToolUse(Edit|Write): warn (never block) before editing security-sensitive surfaces —
+# authentication, authorization, payments/billing, database migrations, infrastructure, or
+# security controls. Advisory only (always exits 0); pairs with the autonomy + risk rules.
+# Degrades to a no-op without jq or a recognisable file path.
+command -v jq >/dev/null 2>&1 || exit 0
+INPUT="$(cat)"
+FILE_PATH="$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_response.filePath // empty' 2>/dev/null || true)"
+[ -z "$FILE_PATH" ] || [ "$FILE_PATH" = "null" ] && exit 0
+
+low="$(printf '%s' "$FILE_PATH" | tr '[:upper:]' '[:lower:]')"
+
+case "$low" in
+  *auth*|*login*|*session*|*oauth*|*jwt*|*password*|*permission*|*rbac*|*authoriz*)
+    echo "WARN: editing an AUTH / authorization surface ($FILE_PATH). High-risk: get review + security check before completion (.claude/rules/risk-classification.md)." >&2 ;;
+esac
+case "$low" in
+  *payment*|*billing*|*invoice*|*checkout*|*stripe*|*charge*)
+    echo "WARN: editing a PAYMENTS / billing surface ($FILE_PATH). High-risk: requires approval, test review, and rollback notes." >&2 ;;
+esac
+case "$low" in
+  */migrations/*|*/migration/*|*alembic*|*_migration*|*.sql)
+    echo "WARN: editing a DATABASE MIGRATION ($FILE_PATH). High-risk: confirm up + down paths and a rollback plan." >&2 ;;
+esac
+case "$low" in
+  */.github/workflows/*|*/.gitlab-ci.yml|*terraform*|*.tf|*/helm/*|*/k8s/*|*/kubernetes/*|*/infra/*|*/deploy/*)
+    echo "WARN: editing INFRASTRUCTURE / CI-CD ($FILE_PATH). High-risk: review blast radius and get approval." >&2 ;;
+esac
+
+exit 0

claude_kit/_payload/hooks/scripts/warn-shared-modules.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# PreToolUse hook for Edit|Write: warn (never block) when touching project-wide / shared
+# configuration whose change can ripple across the whole codebase. stdin: hook JSON.
+# Always exits 0 so the edit is not blocked — this is advisory only.
+
+INPUT="$(cat)"
+FILE_PATH="$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_response.filePath // empty' 2>/dev/null || true)"
+
+if [ -z "$FILE_PATH" ] || [ "$FILE_PATH" = "null" ]; then
+  exit 0
+fi
+
+base="$(basename "$FILE_PATH")"
+
+# Project-wide build / dependency / config surfaces (any stack).
+case "$base" in
+  package.json|package-lock.json|pnpm-lock.yaml|yarn.lock| \
+  pyproject.toml|poetry.lock|requirements.txt|requirements-*.txt|setup.cfg|setup.py| \
+  go.mod|go.sum|Cargo.toml|Cargo.lock|Gemfile|Gemfile.lock|pom.xml|build.gradle| \
+  tsconfig.json|tsconfig.*.json|*.config.js|*.config.ts|*.config.mjs|*.config.cjs| \
+  Dockerfile|docker-compose.yml|docker-compose.*.yml|Makefile|CLAUDE.md)
+    echo "WARN: editing project-wide config: $FILE_PATH — review cross-cutting impact and get approval if it affects others." >&2
+    ;;
+esac
+
+# Shared automation / kit configuration by path.
+case "$FILE_PATH" in
+  */.github/workflows/*|*/.gitlab-ci.yml|*azure-pipelines.yml|*/.claude/rules/*|*/.claude/settings*.json|*/.claude/agents/*)
+    echo "WARN: editing shared automation/config: $FILE_PATH — review impact across the project." >&2
+    ;;
+esac
+
+exit 0