claude-code-kit 0.22.0__tar.gz → 0.23.0__tar.gz

{claude_code_kit-0.22.0 → claude_code_kit-0.23.0}/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "claude-kit",
       "source": "./",
       "description": "Cookiecutter-style scaffolder for an autonomous Claude Code SDLC config (no app code, no Docker): install CLAUDE.md + .claude/ (rules, the profile's agents/skills, hooks, artifact templates) + optional .mcp.json, then run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates, working memory, and a self-improving learnings loop.",
-      "version": "0.22.0",
+      "version": "0.23.0",
       "license": "MIT",
       "keywords": ["sdlc", "agents", "orchestration", "quality-gates", "workflow", "scaffold", "cookiecutter"]
     }

{claude_code_kit-0.22.0 → claude_code_kit-0.23.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-kit",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Cookiecutter-style scaffolder for an autonomous Claude Code SDLC config (no app code, no Docker). `claude-kit init` asks ordered questions and installs CLAUDE.md + .claude/ (rules, the profile's agents/skills, hooks, artifact templates) + optional .mcp.json; run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates with working memory and a self-improving learnings loop.",
   "author": {
     "name": "Arjunsingh Yadav",

{claude_code_kit-0.22.0 → claude_code_kit-0.23.0}/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to claude-kit are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project uses
 [semantic versioning](https://semver.org/).
 
+## [0.23.0] — 2026-06-23
+
+**PR2 of the phased hardening review: structural single-source-of-truth for hooks, and plugin/CLI
+parity that fails loud instead of silently degrading.**
+
+### Changed
+
+- **Hooks are now generated from one registry.** The two previously hand-maintained static hook files —
+  the plugin's `hooks/hooks.json` and the no-pip starter `templates/settings.json` — are now generated
+  from `src/claude_kit/hooks.py` (`HOOK_REGISTRY` + per-channel membership data) via
+  `scripts/gen_hooks.py`. They had already drifted (the starter was missing `load-autonomy`, the PR1
+  `jq`-degradation prefix, and used a slightly different block message). A drift test
+  (`gen_hooks.py --check`, run in the suite) fails the build if either file is hand-edited.
+  - The installed per-profile `.claude/settings.json` (built by `build_settings`) is **byte-identical**
+    to before — pure refactor, verified against `origin/main`.
+  - `hooks/hooks.json` is **semantically identical** to before (reflowed to canonical 2-space JSON; no
+    hook added, removed, or reordered).
+  - `templates/settings.json` changes only by refreshing its two inline Bash guards to the registry
+    versions (gaining the `command -v jq … || exit 0` no-jq degradation + aligned message); same hook
+    membership.
+- **`guard-kubectl-delete` is now declared data.** It moves into a `PLUGIN_ONLY_HOOKS` map (with a
+  `reason`) — the single documented exception to "the registry is the source of truth" — instead of
+  being a silent hand-edit in `hooks.json`.
+
+### Fixed
+
+- **Plugin/CLI parity: `/claude-kit:init` requires the CLI and fails loud.** The command no longer
+  silently falls back to the thin `scripts/init.sh` scaffolder when neither `claude-kit` nor `ckit` is
+  on PATH — it stops and instructs `pipx install claude-code-kit` (or `pip install …`). The shell
+  fallback is now opt-in only (`CLAUDE_KIT_BASIC=1`) and prints a loud "degraded, no-resolution
+  install; upgrade/diff won't work" warning. README onboarding documents the CLI requirement.
+
 ## [0.22.0] — 2026-06-23
 
 **Critical-correctness hardening (PR1 of a phased review): a non-destructive `init` merge that no longer

{claude_code_kit-0.22.0 → claude_code_kit-0.23.0}/CONTRIBUTING.md

@@ -38,11 +38,15 @@ locally, and how to release.
   *when* to use it. Add it to the relevant profile(s) in `catalog/profiles.yaml`.
 - **Rule** → add `rules/<name>.md`; cross-reference siblings as `.claude/rules/<name>.md`.
 - **Hook** → add a script to `hooks/scripts/`, register it in the `HOOK_REGISTRY` in
-  `src/claude_kit/hooks.py`, wire it in `hooks/hooks.json` (plugin), and list its id in the relevant
-  profile's `hooks:`. (Exception: the agent-side capture hooks `capture-learnings[-catchup|-stop]` are
-  **not** profile-listed — they're installed by the init-time `capture_mode` choice via
-  `catalog/capture.yaml` + `catalog._apply_capture_mode`. One script, three triggers, dispatched by an
-  arg.)
+  `src/claude_kit/hooks.py`, and list its id in the relevant profile's `hooks:`. To surface it in the
+  plugin and/or the no-pip starter, add its id to `PLUGIN_HOOK_IDS` / `STARTER_HOOK_IDS` (same module),
+  then **run `python scripts/gen_hooks.py`** to regenerate `hooks/hooks.json` and
+  `templates/settings.json` — **never hand-edit those two files** (a drift test, `gen_hooks.py --check`,
+  fails the build if they diverge from the registry). A plugin-only hook (no CLI scaffold equivalent,
+  e.g. `guard-kubectl-delete`) goes in `PLUGIN_ONLY_HOOKS` with a `reason` instead of the registry.
+  (Exception: the agent-side capture hooks `capture-learnings[-catchup|-stop]` are **not** profile-listed
+  — they're installed by the init-time `capture_mode` choice via `catalog/capture.yaml` +
+  `catalog._apply_capture_mode`. One script, three triggers, dispatched by an arg.)
 - **Stack** (framework / database) → a **data change**: add an entry to `catalog/stacks.yaml`
   (`label`, `overlay_rules`, optional `overlay_agents`, `skills`, `stack_dir`, `commands`) and create
   `templates/stacks/<stack_dir>/rules/<name>.md` (+ `agents/` for a database). Mark not-yet-ready

{claude_code_kit-0.22.0 → claude_code_kit-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-kit
-Version: 0.22.0
+Version: 0.23.0
 Summary: Cookiecutter-style scaffolder for an autonomous Claude Code SDLC configuration (no app code, no Docker). Asks ordered questions and installs CLAUDE.md + .claude/ (rules, the chosen profile's agents/skills, hooks, artifact templates) + optional .mcp.json; run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates, working memory, and a self-improving learnings loop.
 Project-URL: Homepage, https://github.com/ajyadav013/claude-kit
 Project-URL: Repository, https://github.com/ajyadav013/claude-kit
@@ -110,6 +110,12 @@ Then, inside any project you want the pipeline to manage:
 /sdlc Add a CSV export button to the reports page
 ```
 
+> **`/claude-kit:init` requires the Python CLI** (`pipx install claude-code-kit`, or `pip install
+> claude-code-kit`) — it's what resolves your stack/profile/MCP catalog and records `init-options.json`
+> for safe `upgrade`/`diff`. If the CLI isn't on PATH the command stops and tells you to install it
+> rather than doing a partial install. (A degraded, no-resolution shell scaffolder is available only by
+> explicitly setting `CLAUDE_KIT_BASIC=1`; `upgrade`/`diff` won't work against it.)
+
 > `/sdlc` is a **project skill** installed by `init`, so it becomes available after the restart. The
 > plugin also exposes `/claude-kit:sdlc <task>`, which works immediately (no restart needed).
 

{claude_code_kit-0.22.0 → claude_code_kit-0.23.0}/README.md

@@ -83,6 +83,12 @@ Then, inside any project you want the pipeline to manage:
 /sdlc Add a CSV export button to the reports page
 ```
 
+> **`/claude-kit:init` requires the Python CLI** (`pipx install claude-code-kit`, or `pip install
+> claude-code-kit`) — it's what resolves your stack/profile/MCP catalog and records `init-options.json`
+> for safe `upgrade`/`diff`. If the CLI isn't on PATH the command stops and tells you to install it
+> rather than doing a partial install. (A degraded, no-resolution shell scaffolder is available only by
+> explicitly setting `CLAUDE_KIT_BASIC=1`; `upgrade`/`diff` won't work against it.)
+
 > `/sdlc` is a **project skill** installed by `init`, so it becomes available after the restart. The
 > plugin also exposes `/claude-kit:sdlc <task>`, which works immediately (no restart needed).
 

{claude_code_kit-0.22.0 → claude_code_kit-0.23.0}/commands/init.md

@@ -6,21 +6,35 @@ 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,
+**The Python CLI is required.** 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`:
+upgrades (`claude-kit upgrade` / `diff`). 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; }
+  || { command -v ckit >/dev/null 2>&1 && ckit init $ARGUMENTS \
+  || echo "CKIT_CLI_MISSING"; }
 ```
 
-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):
+**If the output is `CKIT_CLI_MISSING`, STOP — do not scaffold anything.** Neither `claude-kit` nor
+`ckit` is installed. Tell the user the CLI is required and how to install it, then have them re-run
+`/claude-kit:init`. Do **not** silently fall back to a partial install:
+
+- Recommended: `pipx install claude-code-kit`
+- Or: `pip install claude-code-kit`
+
+**Escape hatch (advanced, opt-in only).** A thin shell scaffolder exists for locked-down environments
+where installing the CLI is impossible. It copies the full payload as a **superset** with **no**
+stack/profile/MCP resolution, and `claude-kit upgrade` / `diff` will **not** work against it. Use it
+**only** if the user has explicitly opted in by setting `CLAUDE_KIT_BASIC=1`:
 
 ```
-bash "${CLAUDE_PLUGIN_ROOT}/scripts/init.sh" $ARGUMENTS
+if [ "${CLAUDE_KIT_BASIC:-0}" = "1" ]; then
+  bash "${CLAUDE_PLUGIN_ROOT}/scripts/init.sh" $ARGUMENTS
+else
+  echo "set CLAUDE_KIT_BASIC=1 to use the degraded no-CLI scaffolder (the CLI is the supported path)"
+fi
 ```
 
 If `${CLAUDE_PLUGIN_ROOT}` is not set (running from a source checkout), locate `scripts/init.sh` in

claude_code_kit-0.23.0/hooks/hooks.json

@@ -0,0 +1,106 @@
+{
+  "hooks": {
+    "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\""
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/load-autonomy.sh\""
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/capture-learnings.sh\" catchup"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "command -v jq >/dev/null 2>&1 || exit 0; 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": "command -v jq >/dev/null 2>&1 || exit 0; 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-destructive-git.sh\""
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/guard-secrets.sh\""
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/guard-kubectl-delete.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-llm-io.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\""
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/capture-learnings.sh\" end"
+          }
+        ]
+      }
+    ]
+  }
+}

{claude_code_kit-0.22.0 → claude_code_kit-0.23.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-code-kit"
-version = "0.22.0"
+version = "0.23.0"
 description = "Cookiecutter-style scaffolder for an autonomous Claude Code SDLC configuration (no app code, no Docker). Asks ordered questions and installs CLAUDE.md + .claude/ (rules, the chosen profile's agents/skills, hooks, artifact templates) + optional .mcp.json; run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates, working memory, and a self-improving learnings loop."
 readme = "README.md"
 requires-python = ">=3.9"

claude_code_kit-0.23.0/scripts/gen_hooks.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Generate (or --check) the two *static* hook files from the single ``hooks.py`` registry.
+
+claude-kit ships hooks through three channels, but only one should ever be hand-maintained:
+
+* the **installed** ``.claude/settings.json`` — built per-profile by ``hooks.build_settings`` at init;
+* the auto-discovered **plugin** ``hooks/hooks.json`` (``${CLAUDE_PLUGIN_ROOT}`` paths);
+* the thin no-pip **starter** ``templates/settings.json`` (``$CLAUDE_PROJECT_DIR`` paths).
+
+The latter two used to be edited by hand and silently drifted from the registry (and each other).
+This script regenerates both from ``claude_kit.hooks`` so the registry is the single source of truth.
+
+Usage::
+
+    python scripts/gen_hooks.py            # regenerate the two files in place
+    python scripts/gen_hooks.py --check    # exit 1 if either file is out of sync (CI / tests)
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(
+    0, str(ROOT / "src")
+)  # importable from a bare checkout (no editable install needed)
+
+from claude_kit import hooks  # noqa: E402
+
+#: (path on disk, generator) for each static file derived from the registry.
+TARGETS = [
+    (ROOT / "hooks" / "hooks.json", hooks.generate_plugin_hooks_json),
+    (ROOT / "templates" / "settings.json", hooks.generate_starter_settings),
+]
+
+
+def _render(doc: dict) -> str:
+    """Canonical JSON form (2-space indent, literal Unicode, trailing newline) for both files."""
+    return json.dumps(doc, indent=2, ensure_ascii=False) + "\n"
+
+
+def main(argv: list[str]) -> int:
+    check = "--check" in argv
+    drift: list[Path] = []
+    for path, generate in TARGETS:
+        want = _render(generate())
+        have = path.read_text(encoding="utf-8") if path.is_file() else ""
+        if check:
+            if want != have:
+                drift.append(path)
+        else:
+            path.write_text(want, encoding="utf-8")
+            print(f"wrote {path.relative_to(ROOT)}")
+    if check:
+        if drift:
+            print(
+                "hooks drift: FAIL — run `python scripts/gen_hooks.py` to regenerate:"
+            )
+            for path in drift:
+                print(f"  - {path.relative_to(ROOT)}")
+            return 1
+        print("hooks: in sync with the registry")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

{claude_code_kit-0.22.0 → claude_code_kit-0.23.0}/scripts/init.sh

@@ -40,6 +40,16 @@ done
 
 DEST="$TARGET/.claude"
 mkdir -p "$DEST"
+
+# Loud warning: this is the degraded, no-pip path. The full experience is the Python CLI.
+echo "================================================================" >&2
+echo "claude-kit BASIC scaffolder (no Python CLI)" >&2
+echo "  SUPERSET install: NO stack / profile / MCP resolution." >&2
+echo "  'claude-kit upgrade' and 'diff' will NOT work against it." >&2
+echo "  For the full catalog-driven experience + safe upgrades:" >&2
+echo "    pipx install claude-code-kit   (then re-run /claude-kit:init)" >&2
+echo "================================================================" >&2
+
 echo "claude-kit: scaffolding into $TARGET"
 
 copy_root_file() {  # src, dest, label

{claude_code_kit-0.22.0 → claude_code_kit-0.23.0}/src/claude_kit/__init__.py

@@ -7,4 +7,4 @@ Docker): ``claude-kit init`` asks ordered questions and lays down ``CLAUDE.md``
 as a plugin. Extensibility is data-driven via the ``catalog/`` (stacks, profiles, MCP).
 """
 
-__version__ = "0.22.0"
+__version__ = "0.23.0"

{claude_code_kit-0.22.0 → claude_code_kit-0.23.0}/src/claude_kit/hooks.py

@@ -60,6 +60,19 @@ def _script_entry(name: str, arg: str = "") -> dict[str, str]:
     return {"type": "command", "command": command}
 
 
+def _plugin_entry(name: str, arg: str = "") -> dict[str, str]:
+    """Build a settings.json command entry that runs a hook script from the plugin root.
+
+    The plugin variant of :func:`_script_entry` — Claude Code exposes the plugin's own directory via
+    ``${CLAUDE_PLUGIN_ROOT}``, so the auto-discovered ``hooks/hooks.json`` references scripts there
+    rather than in a scaffolded project's ``.claude/hooks/``.
+    """
+    command = f'bash "${{CLAUDE_PLUGIN_ROOT}}/hooks/scripts/{name}"'
+    if arg:
+        command += f" {arg}"
+    return {"type": "command", "command": command}
+
+
 #: The canonical registry. Order here is the order hooks appear in assembled settings.json.
 #: Each value: ``event``, ``matcher``, ``entry`` (settings.json hook object), and ``script``
 #: (basename under payload ``hooks/scripts/`` to copy, or ``None`` for inline/prompt hooks).
@@ -180,21 +193,97 @@ HOOK_REGISTRY: dict[str, dict[str, Any]] = {
         "matcher": "",
         "entry": _script_entry("capture-learnings.sh", "end"),
         "script": "capture-learnings.sh",
+        "arg": "end",
     },
     "capture-learnings-catchup": {
         "event": "SessionStart",
         "matcher": "",
         "entry": _script_entry("capture-learnings.sh", "catchup"),
         "script": "capture-learnings.sh",
+        "arg": "catchup",
     },
     "capture-learnings-stop": {
         "event": "Stop",
         "matcher": "",
         "entry": _script_entry("capture-learnings.sh", "stop"),
         "script": "capture-learnings.sh",
+        "arg": "stop",
     },
 }
 
+#: Hooks the plugin ships but the pip CLI does NOT — the single declared exception to "the registry
+#: is the source of truth". These run from the auto-discovered ``hooks/hooks.json`` only; they are
+#: deliberately absent from ``HOOK_REGISTRY`` / ``catalog/profiles.yaml`` so ``claude-kit init`` output
+#: is unchanged. Each entry carries a ``reason`` so the divergence is documented data, not an accident.
+PLUGIN_ONLY_HOOKS: dict[str, dict[str, Any]] = {
+    "guard-kubectl-delete": {
+        "event": "PreToolUse",
+        "matcher": "Bash",
+        "script": "guard-kubectl-delete.sh",
+        "arg": "",
+        "reason": (
+            "Blocks destructive `kubectl delete` from the agent's Bash tool. Plugin-only by design: "
+            "intentionally not added to the CLI scaffold registry / profiles, so `claude-kit init` "
+            "output is unchanged (see PR #25)."
+        ),
+    },
+}
+
+#: Which registry hooks each *static* generated file ships (the dynamic per-profile installed
+#: settings.json comes from the profile's hook list instead). Declaring channel membership as data —
+#: rather than hand-editing two JSON files — is what keeps the plugin file and the no-pip starter from
+#: silently drifting apart; ``scripts/gen_hooks.py`` regenerates both and a drift test enforces it.
+#:
+#: The plugin file (hooks/hooks.json, always-on for any project using the plugin) carries the broad
+#: recommended set plus the plugin-only guards above.
+PLUGIN_HOOK_IDS: frozenset[str] = frozenset(
+    {
+        "load-continuity",
+        "load-learnings",
+        "load-autonomy",
+        "guard-rm-rf",
+        "guard-push-main",
+        "guard-destructive-git",
+        "guard-commit-secrets",
+        "warn-shared-modules",
+        "warn-llm-io",
+        "warn-sensitive-files",
+        "validate-settings",
+        "lint-fix",
+        "type-check",
+        "capture-learnings",
+        "capture-learnings-catchup",
+    }
+)
+
+#: The thin no-pip starter (templates/settings.json, copied by scripts/init.sh) ships a smaller subset
+#: — the degraded fallback path keeps a minimal, broadly-safe set rather than the full plugin roster.
+STARTER_HOOK_IDS: frozenset[str] = frozenset(
+    {
+        "load-continuity",
+        "load-learnings",
+        "guard-rm-rf",
+        "guard-push-main",
+        "warn-shared-modules",
+        "lint-fix",
+        "type-check",
+        "capture-learnings",
+        "capture-learnings-catchup",
+    }
+)
+
+#: $comment headers for the two channels (kept here so generation is the single source).
+_INSTALLED_COMMENT = (
+    "Claude Code settings installed by claude-kit. Hooks wire the SDLC working-memory, "
+    "learnings, guardrails, and quality checks to scripts in .claude/hooks/. Personal "
+    "overrides belong in .claude/settings.local.json (gitignored)."
+)
+_STARTER_COMMENT = (
+    "Recommended Claude Code settings installed by claude-kit. Hooks wire the SDLC working-memory, "
+    "learnings, guardrails, and quality checks to the scripts in .claude/hooks/. Merge with your "
+    "existing settings.json as needed."
+)
+
 #: Event ordering for a stable, readable settings.json.
 _EVENT_ORDER = (
     "SessionStart",
@@ -221,42 +310,84 @@ def scripts_for(hook_ids: list[str]) -> list[str]:
     return sorted(set(out))
 
 
-def build_settings(hook_ids: list[str]) -> dict[str, Any]:
-    """Assemble a ``settings.json`` document from the selected hook ids.
+def _hooks_block(specs: list[tuple[str, str, dict[str, Any]]]) -> dict[str, Any]:
+    """Group ``(event, matcher, entry)`` specs into the ``{EVENT: [{matcher, hooks}]}`` schema.
+
+    Order is preserved from ``specs`` (callers pass them in registry order), with events sorted by
+    :data:`_EVENT_ORDER`. This is the one place the settings/hooks schema is assembled, shared by the
+    installed-settings, plugin, and starter generators so all three stay byte-identical in shape.
+    """
+    grouped: dict[str, dict[str, list[dict[str, Any]]]] = {}
+    for event, matcher, entry in specs:
+        grouped.setdefault(event, {}).setdefault(matcher, []).append(entry)
+    ordered_events = [e for e in _EVENT_ORDER if e in grouped] + [
+        e for e in grouped if e not in _EVENT_ORDER
+    ]
+    return {
+        event: [
+            {"matcher": matcher, "hooks": entries}
+            for matcher, entries in grouped[event].items()
+        ]
+        for event in ordered_events
+    }
+
+
+def build_settings(
+    hook_ids: list[str], *, comment: str | None = None
+) -> dict[str, Any]:
+    """Assemble an installed ``.claude/settings.json`` document from the selected hook ids.
 
     Groups the selected hooks by event and matcher, preserving registry order, into the schema
-    Claude Code expects (``{"hooks": {EVENT: [{"matcher": …, "hooks": [entry, …]}]}}``).
+    Claude Code expects (``{"hooks": {EVENT: [{"matcher": …, "hooks": [entry, …]}]}}``). Uses the
+    project-relative script paths (``$CLAUDE_PROJECT_DIR/.claude/hooks/…``).
 
     Args:
         hook_ids: Hook ids to enable.
+        comment: Optional ``$comment`` header (defaults to the installed-settings blurb).
 
     Returns:
         A JSON-serialisable settings mapping (always includes an explanatory ``$comment``).
     """
-    selected = [hid for hid in HOOK_REGISTRY if hid in set(hook_ids)]
-    # event -> matcher -> [entries]
-    grouped: dict[str, dict[str, list[dict[str, Any]]]] = {}
-    for hid in selected:
-        spec = HOOK_REGISTRY[hid]
-        grouped.setdefault(spec["event"], {}).setdefault(spec["matcher"], []).append(
-            spec["entry"]
+    specs = [
+        (
+            HOOK_REGISTRY[hid]["event"],
+            HOOK_REGISTRY[hid]["matcher"],
+            HOOK_REGISTRY[hid]["entry"],
         )
-
-    hooks_block: dict[str, list[dict[str, Any]]] = {}
-    ordered_events = [e for e in _EVENT_ORDER if e in grouped] + [
-        e for e in grouped if e not in _EVENT_ORDER
+        for hid in HOOK_REGISTRY
+        if hid in set(hook_ids)
     ]
-    for event in ordered_events:
-        hooks_block[event] = [
-            {"matcher": matcher, "hooks": entries}
-            for matcher, entries in grouped[event].items()
-        ]
-
     return {
-        "$comment": (
-            "Claude Code settings installed by claude-kit. Hooks wire the SDLC working-memory, "
-            "learnings, guardrails, and quality checks to scripts in .claude/hooks/. Personal "
-            "overrides belong in .claude/settings.local.json (gitignored)."
-        ),
-        "hooks": hooks_block,
+        "$comment": comment or _INSTALLED_COMMENT,
+        "hooks": _hooks_block(specs),
     }
+
+
+def generate_starter_settings() -> dict[str, Any]:
+    """Generate the thin no-pip starter ``templates/settings.json`` from :data:`STARTER_HOOK_IDS`."""
+    return build_settings(sorted(STARTER_HOOK_IDS), comment=_STARTER_COMMENT)
+
+
+def generate_plugin_hooks_json() -> dict[str, Any]:
+    """Generate the auto-discovered plugin ``hooks/hooks.json`` from the registry.
+
+    Ships :data:`PLUGIN_HOOK_IDS` (rebuilt with ``${CLAUDE_PLUGIN_ROOT}`` script paths; inline guard
+    commands are path-independent and reused verbatim) plus :data:`PLUGIN_ONLY_HOOKS`, which are
+    appended after the registry hooks within their event/matcher group. No ``$comment`` (the plugin
+    loader reads this as a hooks fragment).
+    """
+    specs: list[tuple[str, str, dict[str, Any]]] = []
+    for hid in HOOK_REGISTRY:
+        if hid not in PLUGIN_HOOK_IDS:
+            continue
+        spec = HOOK_REGISTRY[hid]
+        if spec["script"]:
+            entry = _plugin_entry(spec["script"], spec.get("arg", ""))
+        else:
+            entry = spec["entry"]  # inline command — no path to rewrite
+        specs.append((spec["event"], spec["matcher"], entry))
+    for po in PLUGIN_ONLY_HOOKS.values():
+        specs.append(
+            (po["event"], po["matcher"], _plugin_entry(po["script"], po.get("arg", "")))
+        )
+    return {"hooks": _hooks_block(specs)}