claude-dev-env 1.2.1 → 1.7.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

@@ -5,6 +5,7 @@ import { join, dirname, resolve, relative } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 
 const CLAUDE_HOME = join(homedir(), '.claude');
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -12,6 +13,7 @@ const MANIFEST_FILE = join(CLAUDE_HOME, '.claude-dev-env-manifest.json');
 const PACKAGE_NAME = 'claude-dev-env';
 
 const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'agents'];
+const WORKSPACE_SIBLINGS = ['claude-journal', 'claude-deep-research', 'claude-prompt-tools'];
 
 function detectPython() {
     const candidates = [
@@ -114,6 +116,67 @@ function mergeHooks(pythonCommand) {
     return groupCount;
 }
 
+function findSiblingPackage(packageName) {
+    const workspaceRoot = resolve(PACKAGE_ROOT, '..', '..');
+    const workspacePath = join(workspaceRoot, 'packages', packageName);
+    if (existsSync(join(workspacePath, 'package.json'))) {
+        return workspacePath;
+    }
+    const require = createRequire(import.meta.url);
+    try {
+        const packageJsonPath = require.resolve(join(packageName, 'package.json'));
+        return dirname(packageJsonPath);
+    } catch { /* not found */ }
+    return null;
+}
+
+function installSiblingContent(siblingRoot, allInstalledFiles) {
+    const siblingName = JSON.parse(readFileSync(join(siblingRoot, 'package.json'), 'utf8')).name;
+    console.log(`  Installing sibling: ${siblingName}`);
+    let totalFiles = 0;
+    const skillsSource = join(siblingRoot, 'skills');
+    if (existsSync(skillsSource)) {
+        const skillDirs = readdirSync(skillsSource, { withFileTypes: true }).filter(entry => entry.isDirectory());
+        for (const skillDir of skillDirs) {
+            const stats = copyTree(join(skillsSource, skillDir.name), join(CLAUDE_HOME, 'skills', skillDir.name));
+            allInstalledFiles.push(...stats.paths);
+            totalFiles += stats.created + stats.updated;
+        }
+    }
+    const agentsSource = join(siblingRoot, 'agents');
+    if (existsSync(agentsSource)) {
+        const stats = copyTree(agentsSource, join(CLAUDE_HOME, 'agents'));
+        allInstalledFiles.push(...stats.paths);
+        totalFiles += stats.created + stats.updated;
+    }
+    const rulesSource = join(siblingRoot, 'rules');
+    if (existsSync(rulesSource)) {
+        const stats = copyTree(rulesSource, join(CLAUDE_HOME, 'rules'));
+        allInstalledFiles.push(...stats.paths);
+        totalFiles += stats.created + stats.updated;
+    }
+    const hooksSource = join(siblingRoot, 'hooks');
+    if (existsSync(hooksSource)) {
+        const filesToCopy = collectFiles(hooksSource).filter(file => !file.endsWith('hooks.json'));
+        const hooksDestination = join(CLAUDE_HOME, 'hooks');
+        for (const sourceFile of filesToCopy) {
+            const relativePath = relative(hooksSource, sourceFile);
+            const destFile = join(hooksDestination, relativePath);
+            mkdirSync(dirname(destFile), { recursive: true });
+            const existed = existsSync(destFile);
+            copyFileSync(sourceFile, destFile);
+            allInstalledFiles.push(destFile);
+            totalFiles++;
+            if (existed) {
+                console.log(`  ↻ ${join('hooks', relativePath)} (updated)`);
+            } else {
+                console.log(`  ✓ ${join('hooks', relativePath)} (new)`);
+            }
+        }
+    }
+    return totalFiles;
+}
+
 function writeManifest(installedFiles) {
     const manifest = { package: PACKAGE_NAME, version: '1.0.0', installedAt: new Date().toISOString(), files: installedFiles };
     writeFileSync(MANIFEST_FILE, JSON.stringify(manifest, null, 2) + '\n');
@@ -153,6 +216,16 @@ function install() {
         summary.skills = { created: skillsCreated, updated: skillsUpdated, paths: skillPaths };
         allInstalledFiles.push(...skillPaths);
     }
+    let siblingCount = 0;
+    for (const siblingName of WORKSPACE_SIBLINGS) {
+        const siblingRoot = findSiblingPackage(siblingName);
+        if (siblingRoot) {
+            siblingCount += installSiblingContent(siblingRoot, allInstalledFiles);
+        }
+    }
+    if (siblingCount > 0) {
+        summary.siblings = siblingCount;
+    }
     const hooksSource = join(PACKAGE_ROOT, 'hooks');
     if (existsSync(hooksSource)) {
         const hooksDestination = join(CLAUDE_HOME, 'hooks');
@@ -186,6 +259,9 @@ function install() {
         const { created, updated } = summary.skills;
         console.log(`  skills: ${created + updated} files (${created} new, ${updated} updated)`);
     }
+    if (summary.siblings) {
+        console.log(`  workspace siblings: ${summary.siblings} files`);
+    }
     if (summary.hookFiles) {
         console.log(`  hooks: ${summary.hookFiles.created + summary.hookFiles.updated} files, ${summary.hookGroups} groups in settings.json`);
     }

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/hooks.json

@@ -44,11 +44,6 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/validation/code-style-validator.py",
             "timeout": 15
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/docker-settings-guard.py",
-            "timeout": 15
           }
         ]
       },
@@ -117,11 +112,6 @@
       {
         "matcher": "",
         "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/hook-structure-context.py",
-            "timeout": 10
-          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/bulk-edit-reminder.py",
@@ -136,16 +126,6 @@
       }
     ],
     "SessionStart": [
-      {
-        "matcher": "compact",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/compact-context-reinject.py",
-            "timeout": 10
-          }
-        ]
-      },
       {
         "matcher": "",
         "hooks": [

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.1",
+    "version": "1.7.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -15,6 +15,11 @@
         "skills/",
         "hooks/"
     ],
+    "dependencies": {
+        "claude-journal": "^1.3.0",
+        "claude-deep-research": "^1.0.0",
+        "claude-prompt-tools": "^1.0.0"
+    },
     "keywords": [
         "claude-code",
         "plugin",
@@ -25,6 +30,7 @@
     "license": "MIT",
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/jl-cmd/claude-code-config.git"
+        "url": "git+https://github.com/jl-cmd/claude-code-config.git",
+        "directory": "packages/claude-dev-env"
     }
 }

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