claude-dev-env 1.0.0

package/hooks/validators/type_safety_checks.py

@@ -0,0 +1,101 @@
+"""Type safety checks validator.
+
+Implements:
+- Check 39: Missing type hints on functions
+- Check 40: Any type usage
+"""
+
+import ast
+import sys
+from pathlib import Path
+from typing import List
+
+from validator_base import Violation
+
+
+def check_missing_type_hints(tree: ast.AST, filename: str) -> List[Violation]:
+    violations: List[Violation] = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if node.name.startswith("_") and node.name != "__init__":
+                continue
+
+            if node.returns is None:
+                violations.append(
+                    Violation(
+                        filename,
+                        node.lineno,
+                        f"Function '{node.name}' missing return type annotation",
+                    )
+                )
+
+            for arg in node.args.args:
+                if arg.arg == "self" or arg.arg == "cls":
+                    continue
+                if arg.annotation is None:
+                    violations.append(
+                        Violation(
+                            filename,
+                            node.lineno,
+                            f"Parameter '{arg.arg}' in '{node.name}' missing type annotation",
+                        )
+                    )
+
+    return violations
+
+
+def check_any_type(tree: ast.AST, filename: str) -> List[Violation]:
+    violations: List[Violation] = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name) and node.id == "Any":
+            violations.append(
+                Violation(
+                    filename,
+                    node.lineno,
+                    "Any type used - use specific type or generic",
+                )
+            )
+
+    return violations
+
+
+def validate_file(file_path: Path) -> List[Violation]:
+    violations: List[Violation] = []
+    filename = str(file_path)
+
+    try:
+        source = file_path.read_text(encoding="utf-8")
+        tree = ast.parse(source)
+    except Exception as error:
+        return [Violation(filename, 0, f"Error: {error}")]
+
+    violations.extend(check_missing_type_hints(tree, filename))
+    violations.extend(check_any_type(tree, filename))
+
+    return violations
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("Usage: type_safety_checks.py <file1.py> [file2.py ...]", file=sys.stderr)
+        return 1
+
+    all_violations: List[Violation] = []
+
+    for file_arg in sys.argv[1:]:
+        file_path = Path(file_arg)
+        if not file_path.exists():
+            print(f"Error: File not found: {file_path}", file=sys.stderr)
+            return 1
+        all_violations.extend(validate_file(file_path))
+
+    for violation in all_violations:
+        print(violation)
+
+    return 1 if all_violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/validators/useless_test_checks.py

@@ -0,0 +1,92 @@
+"""Useless test detection validator.
+
+Implements check 12: No useless tests.
+Tests must verify behavior, not existence or constant values.
+"""
+
+import ast
+import sys
+from pathlib import Path
+from typing import List
+
+from validator_base import Violation
+
+
+def check_useless_tests(tree: ast.AST, filename: str) -> List[Violation]:
+    violations: List[Violation] = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef) and node.name.startswith("test_"):
+            for child in ast.walk(node):
+                if isinstance(child, ast.Assert):
+                    if _is_callable_check(child):
+                        violations.append(
+                            Violation(filename, child.lineno, "Useless test: callable() check doesn't verify behavior")
+                        )
+                    elif _is_hasattr_check(child):
+                        violations.append(
+                            Violation(filename, child.lineno, "Useless test: hasattr() check doesn't verify behavior")
+                        )
+                    elif _is_constant_value_check(child):
+                        violations.append(
+                            Violation(filename, child.lineno, "Useless test: testing constant value doesn't verify behavior")
+                        )
+
+    return violations
+
+
+def _is_callable_check(node: ast.Assert) -> bool:
+    if isinstance(node.test, ast.Call):
+        if isinstance(node.test.func, ast.Name) and node.test.func.id == "callable":
+            return True
+    return False
+
+
+def _is_hasattr_check(node: ast.Assert) -> bool:
+    if isinstance(node.test, ast.Call):
+        if isinstance(node.test.func, ast.Name) and node.test.func.id == "hasattr":
+            return True
+    return False
+
+
+def _is_constant_value_check(node: ast.Assert) -> bool:
+    if isinstance(node.test, ast.Compare):
+        if len(node.test.ops) == 1 and isinstance(node.test.ops[0], ast.Eq):
+            left = node.test.left
+            right = node.test.comparators[0] if node.test.comparators else None
+            if isinstance(left, ast.Name) and left.id.isupper():
+                if isinstance(right, ast.Constant) and isinstance(right.value, str):
+                    return True
+    return False
+
+
+def validate_file(file_path: Path) -> List[Violation]:
+    filename = str(file_path)
+    if "test" not in filename.lower():
+        return []
+
+    try:
+        source = file_path.read_text(encoding="utf-8")
+        tree = ast.parse(source)
+    except Exception as error:
+        return [Violation(filename, 0, f"Error: {error}")]
+
+    return check_useless_tests(tree, filename)
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        return 1
+
+    all_violations: List[Violation] = []
+    for file_arg in sys.argv[1:]:
+        all_violations.extend(validate_file(Path(file_arg)))
+
+    for violation in all_violations:
+        print(violation)
+
+    return 1 if all_violations else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/validators/validator_base.py

@@ -0,0 +1,19 @@
+"""Base classes for validators.
+
+Provides shared dataclasses used across all validator modules.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Violation:
+    """Represents a validation violation."""
+
+    file: str
+    line: int
+    message: str
+
+    def __str__(self) -> str:
+        """Format as file:line: message."""
+        return f"{self.file}:{self.line}: {self.message}"

package/hooks/validators/verify_paths.py

@@ -0,0 +1,57 @@
+"""Verify all validator paths referenced in SKILL.md exist."""
+
+import re
+import sys
+from pathlib import Path
+
+
+SKILL_MD_PATH = Path(__file__).parent.parent.parent / "skills" / "pr-review-responder" / "SKILL.md"
+VALIDATORS_DIR = Path(__file__).parent
+
+
+def extract_validator_paths(content: str) -> list[str]:
+    """Extract validator file paths from SKILL.md content."""
+    pattern = r"validators[/\\](\w+\.py)"
+    matches = re.findall(pattern, content)
+    return list(set(matches))
+
+
+def verify_validators() -> int:
+    """Verify all referenced validators exist.
+
+    Returns:
+        Exit code: 0 if all exist, 1 if any missing
+    """
+    if not SKILL_MD_PATH.exists():
+        print(f"ERROR: SKILL.md not found at {SKILL_MD_PATH}")
+        return 1
+
+    content = SKILL_MD_PATH.read_text(encoding="utf-8")
+    referenced_validators = extract_validator_paths(content)
+
+    print(f"Found {len(referenced_validators)} validator references in SKILL.md")
+    print()
+
+    missing = []
+    for validator_file in sorted(referenced_validators):
+        validator_path = VALIDATORS_DIR / validator_file
+        if validator_path.exists():
+            print(f"  [OK] {validator_file}")
+        else:
+            print(f"  [MISSING] {validator_file}")
+            missing.append(validator_file)
+
+    print()
+
+    if missing:
+        print(f"ERROR: {len(missing)} validator(s) missing:")
+        for validator_file in missing:
+            print(f"  - {validator_file}")
+        return 1
+
+    print("All referenced validators exist.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(verify_validators())

package/hooks/workflow/auto-formatter.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+PYTHON_EXTENSIONS = {".py"}
+JS_EXTENSIONS = {".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs"}
+JSON_EXTENSIONS = {".json"}
+PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+HOOKS_DIR = os.path.join(PLUGIN_ROOT, "hooks") + os.sep
+PYTHON_FORMAT_TIMEOUT_SECONDS = 15
+JS_FORMAT_TIMEOUT_SECONDS = 30
+PRETTIER_CONFIG_NAMES = {
+    ".prettierrc",
+    ".prettierrc.json",
+    ".prettierrc.yml",
+    ".prettierrc.yaml",
+    ".prettierrc.js",
+    ".prettierrc.cjs",
+    ".prettierrc.mjs",
+    ".prettierrc.toml",
+    "prettier.config.js",
+    "prettier.config.cjs",
+    "prettier.config.mjs",
+}
+
+
+def has_prettier_config(file_path: str) -> bool:
+    each_ancestor = Path(file_path).resolve().parent
+    while True:
+        for config_name in PRETTIER_CONFIG_NAMES:
+            if (each_ancestor / config_name).exists():
+                return True
+        parent = each_ancestor.parent
+        if parent == each_ancestor:
+            break
+        each_ancestor = parent
+    return False
+
+
+def is_untracked_in_git(file_path: str) -> bool:
+    """Check if file is untracked (brand new) by git."""
+    containing_directory = str(Path(file_path).parent)
+    try:
+        git_check = subprocess.run(
+            ["git", "ls-files", "--error-unmatch", file_path],
+            capture_output=True,
+            text=True,
+            cwd=containing_directory,
+            timeout=5,
+        )
+        return git_check.returncode != 0
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    tool_name = hook_input.get("tool_name", "")
+    file_path = hook_input.get("tool_input", {}).get("file_path", "")
+    if not file_path:
+        sys.exit(0)
+
+    if tool_name == "Edit":
+        sys.exit(0)
+
+    if tool_name == "Write" and not is_untracked_in_git(file_path):
+        sys.exit(0)
+
+    if file_path.startswith(HOOKS_DIR):
+        sys.exit(0)
+
+    suffix = Path(file_path).suffix.lower()
+
+    if suffix in PYTHON_EXTENSIONS:
+        for each_formatter_command in [
+            ["ruff", "format", file_path],
+            [sys.executable, "-m", "ruff", "format", file_path],
+            ["black", file_path],
+            [sys.executable, "-m", "black", file_path],
+        ]:
+            try:
+                format_run = subprocess.run(each_formatter_command, capture_output=True, text=True, timeout=PYTHON_FORMAT_TIMEOUT_SECONDS)
+                if format_run.returncode == 0:
+                    break
+            except FileNotFoundError:
+                continue
+            except subprocess.TimeoutExpired:
+                break
+    elif suffix in JS_EXTENSIONS or suffix in JSON_EXTENSIONS:
+        if not has_prettier_config(file_path):
+            sys.exit(0)
+        try:
+            subprocess.run(
+                ["npx", "--yes", "prettier", "--write", file_path],
+                capture_output=True,
+                text=True,
+                timeout=JS_FORMAT_TIMEOUT_SECONDS,
+            )
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            pass
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/workflow/investigation-tracker-reset.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""PostToolUse hook — resets the serial investigation tracker when delegation occurs.
+
+Clears the investigation timestamp tracker when the lead session delegates work
+via Agent, Task, or TeamCreate tools. This allows the lead to resume limited
+diagnostic calls after properly delegating.
+
+Companion: blocking/serial-investigation-blocker.py (PreToolUse on Read|Bash|Grep)
+"""
+
+import json
+import os
+import sys
+
+TRACKER_STATE_PATH = os.path.join(
+    os.path.expanduser("~"), ".claude", "runtime", "investigation-tracker.json"
+)
+
+DELEGATION_TOOLS = frozenset({"Agent", "Task", "TeamCreate"})
+
+
+def clear_investigation_tracker() -> None:
+    try:
+        os.remove(TRACKER_STATE_PATH)
+    except FileNotFoundError:
+        pass
+    except OSError:
+        pass
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = hook_input.get("tool_name", "")
+    if tool_name not in DELEGATION_TOOLS:
+        sys.exit(0)
+
+    clear_investigation_tracker()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -0,0 +1,30 @@
+{
+    "name": "claude-dev-env",
+    "version": "1.0.0",
+    "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
+    "type": "module",
+    "bin": {
+        "claude-dev-env": "bin/install.mjs"
+    },
+    "files": [
+        "bin/",
+        "rules/",
+        "docs/",
+        "commands/",
+        "agents/",
+        "skills/",
+        "hooks/"
+    ],
+    "keywords": [
+        "claude-code",
+        "plugin",
+        "cli",
+        "tdd",
+        "code-quality"
+    ],
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/jl-cmd/claude-code-config.git"
+    }
+}

package/rules/agent-spawn-protocol.md

@@ -0,0 +1,47 @@
+# Agent Spawn Protocol (Mandatory)
+
+**When this applies:** Before any Agent or Task tool invocation (Explore, implementation, research, or team subagents).
+
+<agent_spawn_protocol>
+
+## Before spawning ANY agent — no exceptions
+
+Every Agent and Task tool call must follow this protocol. This includes Explore agents, research agents, execution agents, and team members.
+
+### Step 1: Context sufficiency check
+
+Before writing any agent prompt, verify you can answer all of these:
+- [ ] What specific files, directories, or areas of the codebase are involved?
+- [ ] What constraints apply? (patterns to follow, things NOT to change, boundaries)
+- [ ] What does success look like? (expected output, acceptance criteria)
+- [ ] Is the task unambiguous enough to delegate?
+
+If ANY answer is "I don't know" -- investigate first (read files, search code) or ask the user. Do NOT spawn with incomplete context.
+
+### Step 2: Craft the prompt with /prompt-generator
+
+Run the `/prompt-generator` skill to produce a structured prompt. Feed it:
+- The task description and goal
+- Target files/directories discovered in Step 1
+- Constraints and boundaries
+- Expected output format
+- Acceptance criteria
+
+The skill will ask 1-3 clarifying questions if information is missing -- this is the built-in context verification.
+
+Use the skill's output as the agent's `prompt` parameter.
+
+### Step 3: Spawn the agent
+
+Pass the structured prompt from Step 2 to the Agent/Task tool.
+
+</agent_spawn_protocol>
+
+## Why
+
+Agents receiving vague prompts waste tokens exploring in circles, produce code that misses constraints, and require expensive rework. A 30-second investment in prompt quality via /prompt-generator saves 5-minute agent failures. This applies equally to Explore agents (which waste context on unfocused searches) and execution agents (which write wrong code).
+
+## Relationship to other rules
+
+- **conservative-action.md** gates acting when ambiguous. This extends that: do not delegate when the task is ambiguous—investigate or ask the user first.
+- Project-specific rules or `~/.claude/CLAUDE.md` may define *whether* to use subagents or teams; this rule governs *how* to craft prompts when you do delegate.

package/rules/cleanup-temp-files.md

@@ -0,0 +1,27 @@
+# Clean Up Temporary Files
+
+**When this applies:** After tasks that created scratch files, debug dumps, or one-off scripts the user did not ask to keep.
+
+Source: [Anthropic — Reduce file creation in agentic coding](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#reduce-file-creation-in-agentic-coding)
+
+## During a task
+
+- Prefer working in memory over creating scratchpad files. Use variables and tool results instead of writing intermediate data to disk.
+- When a temporary file is genuinely needed (e.g., a helper script, a test fixture, a debug output), track it mentally for cleanup.
+
+## When a task is complete
+
+- Remove every temporary file, script, or helper file you created during the task.
+- Leave the working directory cleaner than you found it.
+- If a file was created at the user's explicit request (not as a byproduct of your process), leave it in place.
+
+## What counts as temporary
+
+- Scripts written to test a hypothesis or run a one-off check
+- Debug output files, log dumps, or intermediate data exports
+- Helper files created to work around tool limitations
+- Any file the user did not ask for and would not expect to find after the task
+
+## Why
+
+Temporary files accumulate across sessions and clutter the project root. Latest models sometimes use files as scratchpads during iteration, and these leftovers confuse both the user and future sessions if not cleaned up.

package/rules/code-reviews.md

@@ -0,0 +1,11 @@
+# Responding to Code Reviews
+
+**When this applies:** GitHub PR review feedback on a branch you are fixing.
+
+**MANDATORY PROTOCOL (use pr-review-responder skill):**
+
+1. Fetch ALL reviewer comments BEFORE any fixes
+2. Create TodoWrite checklist - One item per comment
+3. Fix systematically - Mark each todo complete
+4. Reply to EACH comment inline
+5. Create ONE review fix commit - DO NOT squash with original

package/rules/code-standards.md

@@ -0,0 +1,43 @@
+# Code Standards
+
+> **MANDATORY REFERENCE:** CODE_RULES.md - Load for ALL code generation.
+> This is the single source of truth for code standards. Non-negotiable.
+
+@${CLAUDE_PLUGIN_ROOT}/docs/CODE_RULES.md
+
+**Key principles (see CODE_RULES.md for complete reference):**
+- Self-documenting code (no comments)
+- Centralized configuration (one source of truth)
+- Reuse constants (search before creating)
+- No magic values (everything named)
+- No abbreviations (full words)
+- Complete type hints
+- TDD (test first)
+
+## Function Parameters - Required vs Optional
+
+**Use required parameters when no valid use case exists for optional.**
+**Remove unused parameters.**
+
+## Encapsulation - Logic Belongs in Models
+
+**NEVER scatter construction logic in calling code.**
+
+Path/URL building, formatting, transformations -> Put in model methods.
+If you find yourself building the same string pattern in multiple places, it belongs in the model.
+
+## Document Temporary Code
+
+**Scaffolding/placeholder code MUST have TODO comments.**
+
+When code exists only to enable testing before full implementation:
+- Add `// TODO: Replace with...` explaining what will replace it
+- Explain WHY it's temporary, not just WHAT it does
+
+## Naming Reflects Behavior
+
+**Name components after what they ARE, not abstract concepts.**
+
+If it overlays the viewport -> "Overlay" not "Screen"
+If it validates input -> "Validator" not "Handler"
+Names should describe observable behavior or visual appearance.

package/rules/conservative-action.md

@@ -0,0 +1,20 @@
+# Conservative Action
+
+Source: [Anthropic - Tool Usage](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#tool-usage)
+
+<do_not_act_before_instructions>
+When the user's intent is ambiguous, default to research and recommendations rather than taking action. Provide information, explain options, and surface tradeoffs — then let the user decide before making changes.
+
+Proceed with edits, file modifications, or implementations only when the user explicitly requests them.
+</do_not_act_before_instructions>
+
+## Deciding whether to act
+
+- If the user asks a question, answer the question. Do not also fix the thing they asked about.
+- If the user describes a problem, investigate and recommend. Do not jump to implementation.
+- If the user says "do it", "go ahead", "make the change", or similarly explicit language, proceed with action.
+- When in doubt, ask: "Would you like me to make this change, or just show you the approach?"
+
+## Why
+
+Acting prematurely wastes effort and round-trips when the user wanted a different approach. Exploring first produces better outcomes than committing early. This is especially important with models that have a strong action bias.

package/rules/context7.md

@@ -0,0 +1,12 @@
+---
+alwaysApply: true
+---
+
+When working with libraries, frameworks, or APIs — use Context7 MCP to fetch current documentation instead of relying on training data. This includes setup questions, code generation, API references, and anything involving specific packages.
+
+## Steps
+
+1. Call `resolve-library-id` with the library name and the user's question
+2. Pick the best match — prefer exact names and version-specific IDs when a version is mentioned
+3. Call `query-docs` with the selected library ID and the user's question
+4. Answer using the fetched docs — include code examples and cite the version

package/rules/explore-thoroughly.md

@@ -0,0 +1,27 @@
+# Explore Thoroughly
+
+Source: [Anthropic - Overthinking and Excessive Thoroughness](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#overthinking-and-excessive-thoroughness)
+
+Note: This deliberately chooses exploration depth over the "commit and execute quickly" pattern from the same source. Thorough upfront exploration is preferred for the intended workflow.
+
+## Before committing to an approach
+
+- Read the relevant files. Understand what exists before proposing what to change.
+- Map the existing patterns: naming conventions, file organization, architectural decisions.
+- Identify constraints that could invalidate an approach before investing effort in it.
+- For unfamiliar codebases or high-stakes changes, invest more time exploring than feels necessary.
+
+## Exploration scales with risk
+
+- Small change to a familiar file: a quick read of the file and its immediate neighbors is sufficient.
+- New feature or cross-cutting change: read broadly across the codebase to understand how similar things are done.
+- Architectural decision: explore the full landscape before recommending a direction.
+
+## Relationship to other rules
+
+- **conservative-action.md** gates *whether* to act. This rule governs *how deeply* to investigate.
+- **research-mode.md** ensures factual claims are grounded. This rule ensures implementation plans are grounded in the actual codebase.
+
+## Why
+
+Premature commitment leads to wasted effort when the chosen approach conflicts with existing patterns or misses important context. Thorough exploration surfaces constraints early and produces better-informed solutions.