claude-dev-env 1.2.0 → 1.4.0

package/agents/project-context-loader.md

@@ -175,7 +175,7 @@ Displays updated context
 
 ### With Hooks
 
-**SessionStart Hook** (~/.claude/hooks/hooks.json):
+**SessionStart Hook** (~/.claude/settings.json):
 ```json
 {
   "name": "auto-load-project-context",

package/bin/install.mjs

@@ -81,13 +81,14 @@ function mergeHooks(pythonCommand) {
     }
     if (!settings.hooks) settings.hooks = {};
     const installedHooksDir = join(CLAUDE_HOME, 'hooks');
+    const pluginRootDir = CLAUDE_HOME;
     let groupCount = 0;
     for (const [eventType, matcherGroups] of Object.entries(hooksConfig.hooks)) {
         if (!settings.hooks[eventType]) settings.hooks[eventType] = [];
         for (const sourceGroup of matcherGroups) {
             const rewrittenHooks = sourceGroup.hooks.map(hook => {
                 let command = hook.command;
-                command = command.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, installedHooksDir.replace(/\\/g, '/'));
+                command = command.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginRootDir.replace(/\\/g, '/'));
                 command = command.replace(/^python3\b/, pythonCommand);
                 return { ...hook, command };
             });

package/docs/PR_DESCRIPTION_GUIDE.md

@@ -0,0 +1,95 @@
+# GitHub PR Summary Writing Guide for AI
+
+Use this guide when writing pull request descriptions. Follow these best practices to create clear, professional, and reviewable PR summaries.
+
+## Required Sections
+
+### What (Changes)
+
+- Concise statement of what was changed
+- What files or systems were modified
+- What functionality was added, removed, or improved
+- Keep to 2-3 sentences maximum
+
+### Why (Problem/Context)
+
+- Explain the problem this PR solves
+- Provide business or technical context
+- Reference related issue numbers using `#123` or `Fixes #123`, `Closes #456`
+- If no issue exists, briefly explain the motivation
+
+### How (Approach/Solution)
+
+- Describe your implementation approach
+- Explain any design decisions or trade-offs
+- Include architectural changes if applicable
+- Note any breaking changes prominently
+
+## Supporting Details
+
+### Testing and Quality
+
+- What tests were added/modified
+- How to manually verify the changes (if applicable)
+- Any areas of concern or limitations
+- Performance impact (if relevant)
+
+### Dependencies and Risk
+
+- New dependencies introduced (if any)
+- Backward compatibility status
+- Potential side effects
+- Migration steps (if needed)
+
+## Optional but Valuable
+
+### Related Issues/PRs
+
+- Link to dependent PRs or issues
+- Note any follow-up work needed
+
+### Screenshots/Examples (for UI changes)
+
+- Before/after comparisons when visual changes are involved
+
+### Reviewer Guidance
+
+- Specific areas to focus on
+- Questions for reviewers
+- Deployment considerations
+
+## Tone and Style Guidelines
+
+- Be clear and concise -- reviewers scan quickly
+- Use second person sparingly -- focus on what the code does, not what the reviewer should do
+- Avoid jargon -- explain technical terms if non-obvious
+- Use markdown formatting -- bullets, code blocks, headers for readability
+- Be honest about limitations -- acknowledge trade-offs and known issues
+- Assume reviewers are unfamiliar -- provide sufficient context
+
+## What to Avoid
+
+- Vague statements like "fix bug" or "update code"
+- AI-generated summaries without human verification
+- Large walls of text -- break into sections
+- Repeating information from commit messages
+- References to temporary branch names or internal jargon without context
+
+## Example Structure
+
+```markdown
+## Description
+Brief 1-2 sentence overview of the change.
+
+## Why
+Problem/context and reference to related issue (#123).
+
+## How
+Implementation approach and design decisions.
+
+## Testing
+How this was tested and verified.
+
+## Risk Assessment
+Any breaking changes, dependencies, or concerns.
+```

package/hooks/blocking/block-main-commit.py

@@ -123,9 +123,21 @@ def parse_bash_command_from_stdin() -> str:
     return hook_event.get("tool_input", {}).get("command", "")
 
 
+DRAFT_PR_INSTRUCTION = (
+    " Instead: (1) create a feature branch with `git checkout -b <descriptive-branch-name>`, "
+    "(2) commit your changes there, "
+    "(3) push with `git push -u origin <branch-name>`, "
+    "(4) create a draft PR with `gh pr create --draft`. "
+    "If you must commit to main, the user needs to approve explicitly."
+)
+
+
 def build_denial_response(branch_name: str, repo_dir: str | None) -> dict:
     location = f" in {repo_dir}" if repo_dir else ""
-    denial_reason = f"BLOCKED: Direct commit to '{branch_name}' is not allowed. Create a feature branch first: git checkout -b feature/your-branch-name. If you must commit to main, the user needs to approve explicitly."
+    denial_reason = (
+        f"BLOCKED: Direct commit to '{branch_name}'{location} is not allowed."
+        + DRAFT_PR_INSTRUCTION
+    )
 
     return {
         "hookSpecificOutput": {

package/hooks/blocking/pr-description-enforcer.py

@@ -1,9 +1,67 @@
 import json
+import os
 import re
 import sys
 
+PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+PR_GUIDE_PATH = os.path.join(PLUGIN_ROOT, "docs", "PR_DESCRIPTION_GUIDE.md")
 
-def main():
+REQUIRED_PR_SECTION_HEADERS = [
+    "description",
+    "why",
+    "how",
+]
+
+MINIMUM_PR_BODY_LENGTH = 50
+
+VAGUE_LANGUAGE_PATTERN = re.compile(
+    r'\b(fix(?:ed)? (?:bug|issue|it)|update(?:d)? code|minor changes|various (?:fixes|updates|improvements))\b',
+    re.IGNORECASE,
+)
+
+
+def extract_body_from_command(command: str) -> str:
+    heredoc_match = re.search(r'--body\s+"\$\(cat <<', command)
+    if heredoc_match:
+        return command[heredoc_match.start():]
+
+    body_match = re.search(r'--body\s+"([^"]*)"', command) or re.search(r"--body\s+'([^']*)'", command)
+    if body_match:
+        return body_match.group(1)
+
+    short_flag_match = re.search(r'-b\s+"([^"]*)"', command) or re.search(r"-b\s+'([^']*)'", command)
+    if short_flag_match:
+        return short_flag_match.group(1)
+
+    return ""
+
+
+def validate_pr_body(body: str) -> list[str]:
+    violations = []
+    body_lower = body.lower()
+
+    missing_required_sections = [
+        header for header in REQUIRED_PR_SECTION_HEADERS
+        if f"## {header}" not in body_lower and f"**{header}" not in body_lower
+    ]
+
+    if missing_required_sections:
+        formatted_sections = ", ".join(f"'{each_section.title()}'" for each_section in missing_required_sections)
+        violations.append(f"Missing required section(s): {formatted_sections}")
+
+    stripped_body = re.sub(r'#.*', '', body).strip()
+    stripped_body = re.sub(r'\*\*.*?\*\*', '', stripped_body).strip()
+    if len(stripped_body) < MINIMUM_PR_BODY_LENGTH:
+        violations.append("PR body too short -- provide meaningful context for reviewers")
+
+    vague_matches = VAGUE_LANGUAGE_PATTERN.findall(body)
+    if vague_matches:
+        violations.append(f"Vague language detected: {', '.join(vague_matches)} -- be specific about what changed and why")
+
+    return violations
+
+
+def main() -> None:
     try:
         input_data = json.load(sys.stdin)
     except json.JSONDecodeError:
@@ -19,62 +77,29 @@ def main():
 
     is_pr_create = "gh pr create" in command and ("--body" in command or "-b " in command)
     is_pr_edit = "gh pr edit" in command and "--body" in command
-    is_commit = re.search(r'git commit\b', command) and ("-m " in command or "-m\"" in command or "-m'" in command)
 
-    if not (is_pr_create or is_pr_edit or is_commit):
+    if not (is_pr_create or is_pr_edit):
         sys.exit(0)
 
-    body = ""
-    if is_pr_create or is_pr_edit:
-        body_match = re.search(r'--body\s+"([^"]*)"', command) or re.search(r"--body\s+'([^']*)'", command)
-        if body_match:
-            body = body_match.group(1)
-        heredoc_match = re.search(r'--body\s+"\$\(cat <<', command)
-        if heredoc_match:
-            body = command[heredoc_match.start():]
-
-    if is_commit:
-        msg_match = re.search(r'-m\s+"([^"]*)"', command) or re.search(r"-m\s+'([^']*)'", command)
-        if msg_match:
-            body = msg_match.group(1)
-        heredoc_match = re.search(r'-m\s+"\$\(cat <<', command)
-        if heredoc_match:
-            body = command[heredoc_match.start():]
+    body = extract_body_from_command(command)
 
     if not body:
         sys.exit(0)
 
-    violations = []
-
-    if is_pr_create or is_pr_edit:
-        if "## Summary" not in body and "## summary" not in body.lower():
-            violations.append("Missing '## Summary' section")
-
-        has_file_bold = bool(re.search(r'\*\*\w+\.\w+\*\*', body))
-        has_bullet_section = bool(re.search(r'###.*(?:test|config|fix)', body, re.IGNORECASE))
-
-        if not has_file_bold and not has_bullet_section:
-            violations.append("Production changes must be grouped by file with **filename** bold headers explaining WHY")
-
-        jargon_patterns = [
-            (r'\bDexie\b', "Dexie (say 'database' or 'local database')"),
-            (r'\bReact Query\b', "React Query (say 'cache' or 'data cache')"),
-            (r'\bsyncStatus\b', "syncStatus (describe the behavior, not the field)"),
-            (r'\blocalUpdatedAt\b', "localUpdatedAt (describe the behavior, not the field)"),
-            (r'\bpullStartedAt\b', "pullStartedAt (describe the behavior, not the field)"),
-            (r'\buseMutation\b', "useMutation (describe what it does for the user)"),
-        ]
-        for pattern, name in jargon_patterns:
-            if re.search(pattern, body):
-                violations.append(f"Jargon detected: {name}")
+    violations = validate_pr_body(body)
 
     if violations:
         violation_list = "; ".join(violations)
+        pr_guide_reference = f" @{PR_GUIDE_PATH}" if os.path.exists(PR_GUIDE_PATH) else ""
+        denial_reason = (
+            f"BLOCKED: [PR_DESCRIPTION] {violation_list}. "
+            f"Follow the PR description guide:{pr_guide_reference}"
+        )
         result = {
             "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
                 "permissionDecision": "deny",
-                "permissionDecisionReason": f"BLOCKED: [PR_DESCRIPTION_STYLE] {violation_list}. Use the pr-description-writer custom agent: Agent(subagent_type=\"pr-description-writer\", team_name=\"your-team\", prompt=\"Write PR description for the current branch\").",
+                "permissionDecisionReason": denial_reason,
             }
         }
         print(json.dumps(result))

package/hooks/notification/attention-needed-notify.py

@@ -40,6 +40,7 @@ def get_question_from_stdin() -> str:
 
 def main() -> None:
     system = platform.system()
+    wsl_mode = is_wsl()
 
     project_name = get_project_name()
     question_text = get_question_from_stdin()
@@ -49,7 +50,7 @@ def main() -> None:
     if system == "Windows":
         sound_windows()
         notify_windows(project_name, question_text)
-    elif is_wsl():
+    elif wsl_mode:
         sound_wsl()
         notify_wsl(project_name, question_text)
     elif system == "Linux":

package/hooks/notification/notification_utils.py

@@ -156,15 +156,18 @@ def notify_ntfy(title: str, message: str, priority: str = "high") -> None:
 
 
 def notify_linux() -> None:
-    subprocess.Popen(
-        [
-            "notify-send", "-t", LINUX_NOTIFICATION_TIMEOUT_MS,
-            "-u", "normal", "-i", "dialog-warning",
-            DEFAULT_LINUX_TOAST_TITLE, DEFAULT_LINUX_TOAST_MESSAGE,
-        ],
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL
-    )
+    try:
+        subprocess.Popen(
+            [
+                "notify-send", "-t", LINUX_NOTIFICATION_TIMEOUT_MS,
+                "-u", "normal", "-i", "dialog-warning",
+                DEFAULT_LINUX_TOAST_TITLE, DEFAULT_LINUX_TOAST_MESSAGE,
+            ],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL
+        )
+    except FileNotFoundError:
+        return
 
 
 def sound_windows() -> None:

package/hooks/validation/mypy_validator.py

@@ -11,12 +11,27 @@ This catches:
 Works in both WSL and Windows for any Python project with a git root.
 Project root is discovered via CLAUDE_PROJECT_ROOT env var or git rev-parse.
 """
+import importlib
 import json
 import os
 import platform
 import subprocess
 import sys
 from pathlib import Path
+from types import ModuleType
+
+NOTIFICATION_UTILS_DIRECTORY = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "notification"
+)
+sys.path.insert(0, NOTIFICATION_UTILS_DIRECTORY)
+
+
+def load_notification_utils() -> ModuleType | None:
+    try:
+        return importlib.import_module("notification_utils")
+    except ImportError:
+        return None
+
 
 IS_WINDOWS = platform.system() == "Windows"
 
@@ -104,6 +119,25 @@ def format_error_summary(all_error_lines: list[str]) -> str:
     return error_summary
 
 
+def send_block_notification(error_summary: str) -> None:
+    notification_module = load_notification_utils()
+    if notification_module is None:
+        return
+
+    notification_title = "Mypy Type Errors"
+    notification_body = f"Write blocked: {error_summary[:200]}"
+
+    try:
+        if notification_module.is_wsl():
+            notification_module.notify_wsl(notification_title, notification_body)
+        elif platform.system() == "Linux":
+            notification_module.notify_linux()
+        elif platform.system() == "Windows":
+            notification_module.notify_windows(notification_title, notification_body)
+    except (AttributeError, OSError):
+        pass
+
+
 def build_block_response(error_summary: str) -> dict[str, str | dict[str, str]]:
     return {
         "decision": "block",
@@ -171,6 +205,7 @@ def main() -> None:
         sys.exit(0)
 
     error_summary = format_error_summary(all_error_lines)
+    send_block_notification(error_summary)
     block_response = build_block_response(error_summary)
     print(json.dumps(block_response))
     sys.exit(0)

package/hooks/workflow/auto-formatter.py

@@ -1,10 +1,45 @@
 #!/usr/bin/env python3
 
+import importlib
 import json
 import os
+import platform
 import subprocess
 import sys
 from pathlib import Path
+from types import ModuleType
+
+NOTIFICATION_UTILS_DIRECTORY = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "notification"
+)
+sys.path.insert(0, NOTIFICATION_UTILS_DIRECTORY)
+
+
+def load_notification_utils() -> ModuleType | None:
+    try:
+        return importlib.import_module("notification_utils")
+    except ImportError:
+        return None
+
+
+def send_format_notification(file_path: str, formatter_name: str) -> None:
+    notification_module = load_notification_utils()
+    if notification_module is None:
+        return
+
+    notification_title = "Auto-Formatter"
+    notification_body = f"{formatter_name} formatted: {Path(file_path).name}"
+
+    try:
+        if notification_module.is_wsl():
+            notification_module.notify_wsl(notification_title, notification_body)
+        elif platform.system() == "Linux":
+            notification_module.notify_linux()
+        elif platform.system() == "Windows":
+            notification_module.notify_windows(notification_title, notification_body)
+    except (AttributeError, OSError):
+        pass
+
 
 PYTHON_EXTENSIONS = {".py"}
 JS_EXTENSIONS = {".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs"}
@@ -89,6 +124,8 @@ def main() -> None:
             try:
                 format_run = subprocess.run(each_formatter_command, capture_output=True, text=True, timeout=PYTHON_FORMAT_TIMEOUT_SECONDS)
                 if format_run.returncode == 0:
+                    formatter_name = each_formatter_command[0] if each_formatter_command[0] != sys.executable else each_formatter_command[2]
+                    send_format_notification(file_path, formatter_name)
                     break
             except FileNotFoundError:
                 continue
@@ -98,12 +135,14 @@ def main() -> None:
         if not has_prettier_config(file_path):
             sys.exit(0)
         try:
-            subprocess.run(
+            prettier_run = subprocess.run(
                 ["npx", "--yes", "prettier", "--write", file_path],
                 capture_output=True,
                 text=True,
                 timeout=JS_FORMAT_TIMEOUT_SECONDS,
             )
+            if prettier_run.returncode == 0:
+                send_format_notification(file_path, "prettier")
         except (FileNotFoundError, subprocess.TimeoutExpired):
             pass
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.2.0",
+    "version": "1.4.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/npm-creator/SKILL.md

@@ -29,7 +29,7 @@ Scan the current repo root for these directories:
 | `commands/` | Slash commands (.md) | `~/.claude/commands/` |
 | `agents/` | Agent definitions (.md) | `~/.claude/agents/` |
 | `skills/` | Skill packages (subdirs) | `~/.claude/skills/` |
-| `hooks/` | Hook scripts + hooks.json | Merge into `~/.claude/settings.json` |
+| `hooks/` | Hook scripts (+ optional hooks.json manifest) | Merge into `~/.claude/settings.json` |
 
 Use Glob to find which directories exist and count files in each. Report findings to the user.
 
@@ -97,6 +97,10 @@ If hooks/hooks.json exists:
   - Append new groups
 - Write settings.json with `JSON.stringify(data, null, 4)`
 
+Important runtime note:
+- `~/.claude/settings.json` is the runtime source of truth for hooks.
+- `hooks/hooks.json` is a packaging/install manifest input for merge workflows, not a runtime file Claude reads directly.
+
 Print summary:
 ```
 Installed <package-name>:
@@ -176,8 +180,8 @@ When ready to publish: `npm publish`
 ## Remember
 
 - Zero external dependencies — only Node.js built-ins
-- hooks.json in the repo stays canonical (python3 + ${CLAUDE_PLUGIN_ROOT})
-- Rewriting happens only in the destination settings.json
+- If present, hooks.json in the repo stays canonical (python3 + ${CLAUDE_PLUGIN_ROOT})
+- Rewriting happens only in the destination settings.json (runtime source of truth)
 - path.join() everywhere — never concatenate paths with `/` or `\`
 - Idempotent: running twice produces the same result
 - Log every file action so the user sees what changed

package/hooks/blocking/docker-settings-guard.py

@@ -1,44 +0,0 @@
-#!/usr/bin/env python3
-"""
-PreToolUse hook: blocks direct edits to Docker settings files.
-Hooks must be added to the Windows settings.json instead.
-"""
-
-import json
-import sys
-
-BLOCKED_PATHS = [
-    "settings-docker.json",
-    "settings-docker",
-    "docker/settings-docker.json",
-    ".claude/docker/settings-docker.json",
-]
-
-
-def main() -> None:
-    try:
-        stdin_data = sys.stdin.read()
-        hook_input = json.loads(stdin_data)
-        tool_input = hook_input.get("tool_input", {})
-        file_path = tool_input.get("file_path", "")
-
-        for blocked in BLOCKED_PATHS:
-            if file_path.endswith(blocked):
-                message = "BLOCKED: Docker settings edit denied. Edit your user settings.json instead."
-                result = {
-                    "hookSpecificOutput": {
-                        "hookEventName": "PreToolUse",
-                        "permissionDecision": "deny",
-                        "permissionDecisionReason": message
-                    }
-                }
-                print(json.dumps(result))
-                sys.exit(0)
-    except SystemExit:
-        raise
-    except Exception:
-        pass
-
-
-if __name__ == "__main__":
-    main()

package/hooks/blocking/parallel-task-blocker.py

@@ -1,69 +0,0 @@
-#!/usr/bin/env python3
-"""PreToolUse:Task hook — suggests team orchestration for parallel Task spawning.
-
-Detects parallel Task/Agent calls without team_name and injects a suggestion
-into the conversation context. Does NOT block — the tool call proceeds.
-
-Uses atomic file creation (O_CREAT | O_EXCL) to detect concurrent calls.
-Lock auto-expires after 3 seconds to avoid false positives on sequential calls.
-"""
-
-import json
-import os
-import sys
-import tempfile
-import time
-
-LOCK_FILE = os.path.join(tempfile.gettempdir(), "claude-parallel-task-guard.lock")
-LOCK_MAX_AGE_SECONDS = 3
-
-SUGGESTION_MESSAGE = (
-    "SUGGESTION: Multiple parallel agents detected without team orchestration. "
-    "Consider using TeamCreate + team_name for better coordination, "
-    "progress tracking, and file ownership management. "
-    "This is optional — parallel agents will proceed without it."
-)
-
-
-def main() -> None:
-    try:
-        input_data = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
-
-    tool_name = input_data.get("tool_name", "")
-    tool_input = input_data.get("tool_input", {})
-
-    if tool_name not in ("Task", "Agent"):
-        sys.exit(0)
-
-    # Team-orchestrated tasks — no suggestion needed
-    if tool_input.get("team_name"):
-        sys.exit(0)
-
-    # Clean stale locks (previous turn's lock that wasn't cleaned up)
-    try:
-        if os.path.exists(LOCK_FILE):
-            lock_age = time.time() - os.path.getmtime(LOCK_FILE)
-            if lock_age > LOCK_MAX_AGE_SECONDS:
-                os.unlink(LOCK_FILE)
-    except OSError:
-        pass  # Race with another process cleaning — fine
-
-    # Atomic create: only one concurrent caller wins
-    try:
-        fd = os.open(LOCK_FILE, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
-        os.write(fd, str(time.time()).encode())
-        os.close(fd)
-        # First Task in this turn — no suggestion
-        sys.exit(0)
-    except FileExistsError:
-        pass  # Another Task already holds the lock
-
-    # Second+ parallel Task without team → suggest (not block)
-    print(SUGGESTION_MESSAGE, file=sys.stderr)
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

package/hooks/blocking/pyautogui-scroll-blocker.py

@@ -1,74 +0,0 @@
-#!/usr/bin/env python3
-"""
-Block pyautogui mousewheel scroll usage - guide Claude to use pynput instead.
-
-pyautogui's scroll implementation uses incorrect delta values with SendInput API.
-pynput uses the same SendInput API but sends correct delta values.
-"""
-import json
-import re
-import sys
-
-PYAUTOGUI_SCROLL_PATTERNS = [
-    r'pyautogui\.scroll\s*\(',
-    r'pyautogui\.hscroll\s*\(',
-    r'pyautogui\.vscroll\s*\(',
-]
-
-COMPILED_PATTERNS = [re.compile(pattern) for pattern in PYAUTOGUI_SCROLL_PATTERNS]
-
-
-def check_for_pyautogui_scroll(content: str) -> list[str]:
-    """Check for pyautogui scroll function usage."""
-    violations = []
-    lines = content.split('\n')
-
-    for line_num, line in enumerate(lines, 1):
-        for pattern in COMPILED_PATTERNS:
-            if pattern.search(line):
-                violations.append(f"Line {line_num}: {line.strip()}")
-                break
-
-    return violations
-
-
-def main() -> None:
-    try:
-        input_data = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
-
-    tool_input = input_data.get("tool_input", {})
-    file_path = tool_input.get("file_path", "")
-
-    if not file_path:
-        sys.exit(0)
-
-    # Only check Python files
-    if not file_path.endswith('.py'):
-        sys.exit(0)
-
-    content = tool_input.get("content", "") or tool_input.get("new_string", "")
-
-    if not content:
-        sys.exit(0)
-
-    violations = check_for_pyautogui_scroll(content)
-
-    if violations:
-        violation_list = "\n".join(f"  • {v}" for v in violations[:5])
-        result = {
-            "hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "permissionDecision": "deny",
-                "permissionDecisionReason": f"BLOCKED: pyautogui scroll() is broken on Windows (incorrect delta values). Use pynput instead: from pynput.mouse import Controller; mouse = Controller(); mouse.scroll(0, -3) for scrolling down 3 clicks."
-            }
-        }
-        print(json.dumps(result))
-        sys.stdout.flush()
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

package/hooks/session/bulk-edit-reminder.py

@@ -1,30 +0,0 @@
-#!/usr/bin/env python3
-import json
-import sys
-
-BULK_UPDATE_KEYWORDS = ["update all", "replace all", "change all", "fix all", "rename all"]
-
-BULK_UPDATE_REMINDER = "BULK UPDATE DETECTED: Use a Python script with --preview/--apply instead of line-by-line edits."
-
-
-def main() -> None:
-    try:
-        input_data = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
-
-    prompt = input_data.get("prompt", "")
-
-    if not prompt:
-        sys.exit(0)
-
-    message_lower = prompt.lower()
-
-    if any(keyword in message_lower for keyword in BULK_UPDATE_KEYWORDS):
-        print(BULK_UPDATE_REMINDER)
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

package/hooks/session/code-rules-reminder.py

@@ -1,97 +0,0 @@
-#!/usr/bin/env python3
-"""
-UserPromptSubmit hook that detects code-related requests and injects CODE_RULES.md reminder.
-Triggers on keywords indicating code writing, planning, or implementation.
-"""
-
-import json
-import re
-import sys
-
-CODE_KEYWORDS = [
-    # Creation verbs
-    r'\b(write|create|implement|add|build|make|generate|develop|setup|scaffold|bootstrap|initialize|init|compose|construct|define|declare|register|wire|connect|integrate|introduce)\b',
-    # Code nouns
-    r'\b(code|function|class|method|script|module|component|hook|test|spec|api|endpoint|route|handler|service|util|helper|factory|interface|type|enum|constant|variable|parameter|argument|logic|algorithm|feature|library|package|dependency|plugin|extension|widget|element|node|token|parser|serializer|validator|formatter|linter|compiler|transpiler|bundler|loader|resolver|provider|consumer|producer|subscriber|publisher|emitter|dispatcher|reducer|selector|adapter|wrapper|decorator|mixin|trait|protocol|abstract|generic|iterator|generator|coroutine|fiber|thread|process|worker|job|task|queue|stack|buffer|stream|pipe|socket|channel|signal|slot|observer|mediator|strategy|command|visitor|singleton|repository|gateway|mapper|transformer|converter|encoder|decoder|interceptor|guard|filter|middleware|pipeline|chain|proxy|facade|bridge|flyweight|memento|prototype)\b',
-    # Modification verbs
-    r'\b(fix|update|refactor|modify|change|edit|rewrite|improve|enhance|optimize|debug|patch|correct|adjust|tweak|rework|revise|extend|expand|rename|move|extract|inline|split|merge|combine|consolidate|simplify|clean|cleanup|reorganize|restructure|decouple|encapsulate|abstract|generalize|specialize|upgrade|downgrade|migrate|convert|transform|adapt|port|backport)\b',
-    # Deletion/removal verbs
-    r'\b(delete|remove|drop|deprecate|disable|deactivate|unregister|detach|disconnect|unbind|unsubscribe|uninstall|prune|trim|strip|purge|clear|reset|destroy|dispose|release|free|deallocate)\b',
-    # Planning verbs
-    r'\b(plan|design|structure|architect|outline|draft|sketch|propose|suggest|approach|strategy|solution|how would|how should|how do|how can|how to|what if|where should|when should|why does|why is|could we|should we|can we|let.s|need to|want to|going to)\b',
-    # Review/analysis verbs
-    r'\b(review|check|analyze|audit|inspect|examine|validate|verify|assess|evaluate|trace|profile|benchmark|measure|monitor|diagnose|troubleshoot|investigate|identify|detect|discover|locate|find the bug|root cause)\b',
-    # Testing verbs
-    r'\b(test|run tests|unit test|integration test|e2e test|end.to.end|assert|expect|mock|stub|spy|fake|fixture|setup|teardown|arrange|act|coverage|regression|smoke test|snapshot|parameterize)\b',
-    # File types
-    r'\.(py|js|ts|tsx|jsx|css|scss|less|html|json|yaml|yml|toml|ini|cfg|sql|sh|bash|zsh|vue|svelte|go|rs|java|kt|swift|rb|php|c|cpp|h|hpp|cs|fs|ex|exs|erl|hs|ml|clj|scala|groovy|dart|lua|r|jl|nim|zig|wasm|graphql|proto|tf|hcl)\b',
-    # Programming concepts
-    r'\b(loop|condition|if statement|switch|try|catch|exception|error handling|async|await|promise|callback|event|listener|state|props|render|return|import|export|inherit|extend|override|decorator|middleware|migration|schema|model|view|controller|template|query|mutation|subscription|context|scope|closure|binding|reference|pointer|memory|allocation|garbage collection|concurrency|parallelism|synchronization|deadlock|race condition|mutex|semaphore|lock|atomic|transaction|rollback|commit|index|constraint|foreign key|primary key|join|aggregate|subquery|cursor|trigger|stored procedure|materialized view)\b',
-    # DevOps/infrastructure
-    r'\b(deploy|release|publish|ship|rollout|rollback|ci|cd|pipeline|docker|container|kubernetes|k8s|terraform|ansible|nginx|apache|server|cluster|replica|shard|partition|load balancer|proxy|cdn|ssl|tls|certificate|dns|domain|cors|csp|firewall|vpc|subnet|security group|iam|role|policy|secret|vault|env var|environment variable|configuration|config file|dotenv)\b',
-    # Database/data
-    r'\b(database|db|sql|nosql|mongo|postgres|mysql|sqlite|redis|elasticsearch|dynamodb|cassandra|orm|queryset|recordset|dataset|dataframe|csv|parquet|avro|protobuf|graphql|rest|grpc|websocket|sse|webhook|polling|pagination|cursor|offset|limit|batch|bulk|upsert|crud)\b',
-    # Sample/example requests
-    r'\b(example|sample|snippet|demo|prototype|proof of concept|poc|skeleton|boilerplate|starter|template|scaffold|seed|initial|baseline|reference implementation|minimal|basic|simple|quick|small)\b',
-    # Common tool/framework references
-    r'\b(django|flask|fastapi|express|next|react|vue|angular|svelte|tailwind|bootstrap|jest|pytest|mocha|cypress|playwright|selenium|webpack|vite|rollup|esbuild|npm|yarn|pnpm|pip|poetry|cargo|gradle|maven|cmake|bazel|make|dockerfile|compose|github|gitlab|bitbucket|jira|confluence)\b',
-]
-
-CONDENSED_RULES = """
-<code-rules-reminder>
-## MANDATORY CODE RULES - APPLY TO ALL CODE (samples, plans, implementations)
-
-1. **NO COMMENTS** - Self-documenting names only
-   - BAD: `d = 0.5  # delay` -> GOOD: `delay_between_retries_seconds = 0.5`
-
-2. **NO MAGIC VALUES** - Everything named and in config
-   - BAD: `if score > 0.8:` -> GOOD: `if score > MINIMUM_CONFIDENCE_THRESHOLD:`
-
-3. **NO ABBREVIATIONS** - Full words always
-   - BAD: `ctx`, `cfg`, `msg`, `btn` -> GOOD: `context`, `configuration`, `message`, `button`
-
-4. **COMPLETE TYPE HINTS** - All parameters and returns typed, no `Any`
-
-5. **CENTRALIZED CONFIG** - Constants in config/, imported everywhere
-
-6. **SEARCH BEFORE CREATE** - Use everything-search skill before defining constants
-
-7. **ALL IMPORTS SHOWN** - Every code block includes its imports
-
-8. **SELF-CONTAINED COMPONENTS** - Components own their modals/toasts/state
-
-CHECKLIST before writing ANY code:
-[ ] No comments (names explain everything)
-[ ] No magic values (all named constants)
-[ ] No abbreviations (full words)
-[ ] Complete types (all params + returns)
-[ ] Imports shown
-
-SCOPE: These rules apply to code you WRITE or MODIFY. Do NOT fix violations in untouched code unless explicitly instructed.
-</code-rules-reminder>
-"""
-
-
-def main() -> None:
-    try:
-        hook_input = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
-
-    prompt = hook_input.get("prompt", "")
-
-    if not prompt:
-        sys.exit(0)
-
-    message_lower = prompt.lower()
-
-    for pattern in CODE_KEYWORDS:
-        if re.search(pattern, message_lower, re.IGNORECASE):
-            print(CONDENSED_RULES)
-            sys.exit(0)
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

package/hooks/session/compact-context-reinject.py

@@ -1,39 +0,0 @@
-#!/usr/bin/env python3
-import json
-import os
-import sys
-
-PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-CODE_RULES_PATH = os.path.join(PLUGIN_ROOT, "docs", "CODE_RULES.md")
-
-
-def load_code_rules() -> str:
-    try:
-        with open(CODE_RULES_PATH, encoding="utf-8") as code_rules_file:
-            return code_rules_file.read()
-    except (FileNotFoundError, OSError):
-        return ""
-
-
-def main() -> None:
-    try:
-        json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
-
-    code_rules_content = load_code_rules()
-    if not code_rules_content:
-        sys.exit(0)
-
-    reinject_payload = {
-        "hookSpecificOutput": {
-            "hookEventName": "SessionStart",
-            "additionalContext": code_rules_content,
-        }
-    }
-    print(json.dumps(reinject_payload))
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

package/hooks/session/hook-structure-context.py

@@ -1,140 +0,0 @@
-#!/usr/bin/env python3
-"""
-UserPromptSubmit hook that detects "hook" mentions and injects
-context about our current hook structure and how to add new hooks.
-"""
-
-import json
-import sys
-
-
-TRIGGER_PHRASES = [
-    "hook",
-]
-
-EXCLUDE_PHRASES = [
-    "react hook",
-    "usehook",
-    "usestate",
-    "useeffect",
-    "custom hook",
-    "git hook",
-    "pre-commit hook",
-    "webhook",
-]
-
-CONTEXT = """
-<hook-structure-context>
-## Claude Code Hook System
-
-### Architecture
-- **Runner pattern**: `run-hook-wrapper.js` (Node.js) -> `run-hook.py` (Python) -> individual hook
-- **Hook directory**: `hooks/`
-
-### Hook Organization (subfolder structure)
-```
-hooks/
-|-- rewrite-plugin-paths.py
-|-- session/
-|   |-- compact-context-reinject.py
-|   |-- plugin-data-dir-cleanup.py
-|   +-- hook-structure-context.py
-|-- notification/
-|   |-- attention-needed-notify.py
-|   |-- claude-notification-handler.py
-|   +-- notification_utils.py
-|-- advisory/
-|   |-- refactor-guard.py
-|   +-- migration-safety-advisor.py
-|-- validation/
-|   |-- code-style-validator.py
-|   |-- hook-format-validator.py
-|   |-- mypy_validator.py
-|   +-- e2e-test-validator.py
-|-- lifecycle/
-|   |-- config-change-guard.py
-|   +-- session-end-cleanup.py
-|-- blocking/
-|   |-- pyautogui-scroll-blocker.py
-|   |-- sensitive-file-protector.py
-|   |-- write-existing-file-blocker.py
-|   +-- destructive-command-blocker.py
-|-- git-hooks/
-|   +-- post-commit.py
-|-- github-action/
-|   +-- test_workflow.py
-+-- validators/
-    |-- (validation check modules)
-    +-- test_files/
-```
-
-### Event Types
-| Event | When | Input (stdin JSON) | Can Block? |
-|-------|------|-------------------|------------|
-| SessionStart | Session begins | `{}` | No |
-| UserPromptSubmit | User sends message | `{"prompt": "..."}` | No (advisory) |
-| PreToolUse | Before tool execution | `{"tool_name": "...", "tool_input": {...}}` | YES (exit 2) |
-| PostToolUse | After tool execution | `{"tool_name": "...", "tool_input": {...}, "tool_output": "..."}` | No |
-| SubagentStop | Agent completes | `{"agent_type": "...", ...}` | No |
-| Stop | Session ends | `{}` | No |
-
-### How to Add a New Hook
-
-1. **Create the hook file** in the appropriate subfolder:
-   ```python
-   #!/usr/bin/env python3
-   import json
-   import sys
-
-   hook_input = json.load(sys.stdin)
-   print("Context to inject")
-   sys.exit(0)
-   ```
-
-2. **Register in settings.json** under the correct event type:
-   ```json
-   {
-     "type": "command",
-     "command": "node -e \\"process.argv.splice(1,0,'_');require(require('os').homedir()+'/.claude/hooks/run-hook-wrapper.js')\\" \\"session/your-hook.py\\"",
-     "timeout": 15000
-   }
-   ```
-
-3. **Key rules**:
-   - Always use the `run-hook-wrapper.js` pattern (cross-platform)
-   - Set explicit timeouts (10000-30000ms)
-   - PreToolUse hooks use `matcher` to scope which tools they fire on
-   - UserPromptSubmit hooks match on `prompt` content
-   - Print output = context injected into Claude's conversation
-   - Advisory hooks exit 0; blocking hooks exit 2 with `hookSpecificOutput.permissionDecision`
-</hook-structure-context>
-"""
-
-
-def main() -> None:
-    try:
-        hook_input = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
-
-    prompt = hook_input.get("prompt", "")
-
-    if not prompt:
-        sys.exit(0)
-
-    message_lower = prompt.lower()
-
-    for exclude in EXCLUDE_PHRASES:
-        if exclude in message_lower:
-            sys.exit(0)
-
-    for phrase in TRIGGER_PHRASES:
-        if phrase in message_lower:
-            print(CONTEXT)
-            sys.exit(0)
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

package/hooks/validation/code-style-validator.py

@@ -1,145 +0,0 @@
-#!/usr/bin/env python3
-"""
-Code style validator - checks for common style issues.
-
-- 4-space indentation (not tabs, not 2 spaces)
-- Single newlines between functions (not double)
-- Single newlines between class methods
-"""
-import json
-import re
-import sys
-
-
-def check_indentation(content: str) -> list[str]:
-    """Check for non-4-space indentation."""
-    issues = []
-    lines = content.split('\n')
-
-    for line_num, line in enumerate(lines, 1):
-        if not line or not line[0].isspace():
-            continue
-
-        # Check for tabs
-        if '\t' in line:
-            issues.append(f"Line {line_num}: Tab indentation - use 4 spaces")
-            continue
-
-        # Get leading spaces
-        stripped = line.lstrip(' ')
-        indent = len(line) - len(stripped)
-
-        # Check if indent is multiple of 4
-        if indent > 0 and indent % 4 != 0:
-            issues.append(f"Line {line_num}: {indent}-space indent - use 4 spaces")
-
-    return issues[:5]  # Limit to first 5
-
-
-def check_function_spacing(content: str) -> list[str]:
-    """Check for excessive blank lines between code blocks.
-
-    Detects 2+ consecutive blank lines anywhere in the file, plus validates
-    correct spacing before function/method/class definitions.
-    """
-    issues = []
-    lines = content.split('\n')
-
-    func_pattern = re.compile(r'^(\s*)(async\s+)?def\s+\w+')
-    class_pattern = re.compile(r'^class\s+\w+')
-
-    consecutive_blank_count = 0
-    blank_run_start_line = 0
-    prev_was_code = False
-
-    for line_num, line in enumerate(lines, 1):
-        stripped = line.strip()
-
-        if not stripped:
-            if consecutive_blank_count == 0:
-                blank_run_start_line = line_num
-            consecutive_blank_count += 1
-            continue
-
-        if consecutive_blank_count >= 3:
-            issues.append(f"Line {blank_run_start_line}: {consecutive_blank_count} consecutive blank lines - max 2 allowed")
-
-        func_match = func_pattern.match(line)
-        class_match = class_pattern.match(line)
-
-        if func_match and prev_was_code:
-            indent = len(func_match.group(1)) if func_match.group(1) else 0
-
-            if indent == 0:
-                if consecutive_blank_count != 2:
-                    issues.append(f"Line {line_num}: Top-level function needs 2 blank lines above (has {consecutive_blank_count})")
-            else:
-                if consecutive_blank_count != 1:
-                    issues.append(f"Line {line_num}: Method needs 1 blank line above (has {consecutive_blank_count})")
-
-        elif class_match and prev_was_code:
-            if consecutive_blank_count != 2:
-                issues.append(f"Line {line_num}: Class needs 2 blank lines above (has {consecutive_blank_count})")
-
-        consecutive_blank_count = 0
-        prev_was_code = not stripped.startswith('#') and not stripped.startswith('@')
-
-    return issues[:5]
-
-
-def main() -> None:
-    try:
-        input_data = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
-
-    tool_input = input_data.get("tool_input", {})
-    file_path = tool_input.get("file_path", "")
-
-    if not file_path:
-        sys.exit(0)
-
-    # Only check Python files
-    if not file_path.endswith('.py'):
-        sys.exit(0)
-
-    # Skip test files (more lenient)
-    if 'test' in file_path.lower() or 'conftest' in file_path.lower():
-        sys.exit(0)
-
-    tool_name = input_data.get("tool_name", "")
-    content = tool_input.get("content", "") or tool_input.get("new_string", "")
-
-    if not content:
-        sys.exit(0)
-
-    if tool_name == "Write":
-        try:
-            with open(file_path, "r", encoding="utf-8") as existing_file:
-                existing_content = existing_file.read()
-            if existing_content:
-                sys.exit(0)
-        except (FileNotFoundError, OSError, UnicodeDecodeError):
-            pass
-
-    issues = []
-    issues.extend(check_indentation(content))
-    issues.extend(check_function_spacing(content))
-
-    if issues:
-        issue_list = "; ".join(issues)
-        result = {
-            "hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "permissionDecision": "ask",
-                "permissionDecisionReason": f"[Code Style] {len(issues)} issue(s): {issue_list}. Fix or proceed?"
-            }
-        }
-        print(json.dumps(result))
-        sys.stdout.flush()
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

package/hooks/validation/e2e-test-validator.py

@@ -1,142 +0,0 @@
-#!/usr/bin/env python3
-"""
-Validate E2E test consistency between online/offline specs.
-
-Two checks:
-1. Naming: offline tests must mirror online test names with " offline" suffix.
-2. Coverage: when a new online e2e test file is written, a corresponding
-   offline equivalent must exist. Blocks if missing.
-
-Triggered as PostToolUse hook when editing spec files.
-"""
-
-import json
-import os
-import re
-import sys
-from pathlib import Path
-
-
-E2E_TEST_DIRECTORY = "frontend/tests/e2e"
-
-
-def extract_test_names(file_path: Path) -> set[str]:
-    """Extract test names from spec file."""
-    content = file_path.read_text()
-    pattern = r"test\(['\"]([^'\"]+)['\"]"
-    return set(re.findall(pattern, content))
-
-
-def validate_e2e_naming(project_root: Path) -> list[str]:
-    """Return list of naming violations.
-
-    Only validates tests that follow the naming convention (end with " offline").
-    Legacy tests without the suffix are ignored - they may intentionally differ.
-    """
-    online = project_root / E2E_TEST_DIRECTORY / "online.spec.ts"
-    offline = project_root / E2E_TEST_DIRECTORY / "offline.spec.ts"
-
-    if not online.exists() or not offline.exists():
-        return []
-
-    online_tests = extract_test_names(online)
-    offline_tests = extract_test_names(offline)
-
-    violations = []
-
-    for test in offline_tests:
-        if not test.endswith(" offline"):
-            continue
-
-        online_name = test.removesuffix(" offline")
-        if online_name not in online_tests:
-            violations.append(f"No online pair for: '{test}'")
-
-    return violations
-
-
-def validate_offline_coverage(file_path: str, project_root: Path) -> list[str]:
-    """Check that online e2e test files have a corresponding offline file.
-
-    When a new online spec file is written, the offline equivalent must exist.
-    Returns blocking violations if offline file is missing.
-    """
-    e2e_directory = project_root / E2E_TEST_DIRECTORY
-    file_name = Path(file_path).name
-
-    if "offline" in file_name:
-        return []
-
-    if not file_name.endswith(".spec.ts"):
-        return []
-
-    offline_name = file_name.replace(".spec.ts", ".offline.spec.ts")
-    if file_name == "online.spec.ts":
-        offline_name = "offline.spec.ts"
-
-    offline_path = e2e_directory / offline_name
-    if not offline_path.exists():
-        return [f"Missing offline equivalent: {offline_name} required for {file_name}"]
-
-    return []
-
-
-def main() -> None:
-    """Hook entry point - reads tool input from stdin."""
-    try:
-        input_data = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
-
-    tool_input = input_data.get("tool_input", {})
-    file_path = tool_input.get("file_path", "")
-
-    if not file_path:
-        sys.exit(0)
-
-    if ".spec.ts" not in file_path:
-        sys.exit(0)
-
-    path_object = Path(file_path)
-    project_root = path_object.parent
-    while project_root != project_root.parent:
-        if (project_root / E2E_TEST_DIRECTORY).exists():
-            break
-        project_root = project_root.parent
-    else:
-        sys.exit(0)
-
-    if not (project_root / E2E_TEST_DIRECTORY).exists():
-        sys.exit(0)
-
-    naming_violations = validate_e2e_naming(project_root)
-    coverage_violations = validate_offline_coverage(file_path, project_root)
-
-    if coverage_violations:
-        violation_list = "; ".join(coverage_violations)
-        result = {
-            "hookSpecificOutput": {
-                "hookEventName": "PostToolUse",
-                "additionalContext": f"[E2E COVERAGE] Offline test required: {violation_list}"
-            }
-        }
-        print(json.dumps(result))
-        sys.stdout.flush()
-        sys.exit(0)
-
-    if naming_violations:
-        violation_list = "; ".join(naming_violations)
-        result = {
-            "hookSpecificOutput": {
-                "hookEventName": "PostToolUse",
-                "additionalContext": f"[E2E NAMING] {violation_list}. Offline tests must mirror online names with ' offline' suffix."
-            }
-        }
-        print(json.dumps(result))
-        sys.stdout.flush()
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()