claude-dev-env 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jon Lombardi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# claude-code-config
+
+Consistent development standards for Claude Code across every repo. Install once, get TDD enforcement, code quality hooks, specialized agents, and battle-tested rules everywhere.
+
+## Install
+
+```bash
+npx claude-dev-env
+```
+
+To uninstall:
+
+```bash
+npx claude-dev-env --uninstall
+```
+
+The installer copies rules, docs, agents, commands, and skills to `~/.claude/` and merges hooks into `~/.claude/settings.json`. It auto-detects your Python 3 command for hook scripts. Running it again updates existing files in place.
+
+## What This Solves
+
+Without shared config, every repo needs its own `.claude/rules/`, `.claude/hooks/`, `.claude/agents/`, etc. That means:
+
+- Duplicated config across 5+ repos
+- Drift when you update standards in one place but forget others
+- New repos start with zero guardrails
+
+This package centralizes all general-purpose Claude Code config. Project-specific rules still live in each repo's `.claude/` directory and merge with these.
+
+## What's Included
+
+### Rules (13)
+
+Behavioral rules loaded into every session. These shape how Claude approaches work before any code is written.
+
+| Rule | What it does |
+|------|-------------|
+| `tdd` | Red-green-refactor is non-negotiable |
+| `code-standards` | References CODE_RULES.md for all code generation |
+| `conservative-action` | Research first, act only when explicitly asked |
+| `right-sized-engineering` | Simple > clever, functions > classes, concrete > abstract |
+| `explore-thoroughly` | Read before proposing, map patterns before committing |
+| `research-mode` | Anti-hallucination: cite sources, say "I don't know", use direct quotes |
+| `parallel-tools` | Independent tool calls run simultaneously |
+| `agent-spawn-protocol` | Context sufficiency check before delegating to agents |
+| `git-workflow` | Draft PRs, one commit per review stage, stacked PR patterns |
+| `code-reviews` | Systematic PR review response protocol |
+| `testing` | Complete mocks, reference TEST_QUALITY.md |
+| `context7` | Fetch current docs via Context7 MCP instead of relying on training data |
+| `cleanup-temp-files` | Remove scratch files after tasks complete |
+
+### Docs (4)
+
+Reference documents that rules and agents point to for detailed standards.
+
+| Document | Coverage |
+|----------|----------|
+| `CODE_RULES.md` | Hook-enforced rules, naming conventions, config patterns, type hints, readability rubric |
+| `TEST_QUALITY.md` | Test writing standards, mock completeness, assertion patterns |
+| `REACT_PATTERNS.md` | Component architecture, hooks, state management conventions |
+| `DJANGO_PATTERNS.md` | Model patterns, view architecture, ORM best practices |
+
+### Agents (34)
+
+Specialized agent prompts for common development tasks. Claude Code automatically discovers these and makes them available for delegation.
+
+**Code Quality:** clean-coder, code-quality-agent, code-standards-agent, readability-review-agent, refactoring-specialist, right-sized-engineer
+
+**Testing:** tdd-test-writer, test-data-builder, validation-expert
+
+**Planning:** plan-executor, parallel-workflow-coordinator, mandatory-agent-workflow-agent, stub-detector-agent
+
+**Documentation:** docs-agent, doc-orchestrator, user-docs-writer, project-docs-analyzer
+
+**Configuration:** config-extraction-agent, config-centralizer, magic-value-eliminator-agent, project-structure-organizer-agent
+
+**Tooling:** agent-writer, skill-writer-agent, skill-to-agent-converter, tooling-builder
+
+**Git:** git-commit-crafter, pr-description-writer, session-continuity-manager
+
+**File Formats:** docx-agent, pdf-agent, xlsx-agent
+
+**Other:** clasp-deployment-orchestrator, workflow-visual-documenter, project-context-loader
+
+### Commands (11)
+
+Slash commands for common workflows.
+
+| Command | Purpose |
+|---------|---------|
+| `/commit` | Structured git commit with conventional format |
+| `/plan` | Create implementation plans with config search |
+| `/implement` | Execute plans with TDD workflow |
+| `/review-plan` | Review and critique implementation plans |
+| `/readability-review` | 8-dimension readability scoring |
+| `/right-size` | Check for over/under-engineering |
+| `/stubcheck` | Find stubs, TODOs, and NotImplementedError |
+| `/pr-comments` | Process PR review comments systematically |
+| `/docupdate` | Update documentation after changes |
+| `/initialize` | Session initialization with protocol review |
+| `/sum` | Summarize current work context |
+
+### Skills (14)
+
+| Skill | Purpose |
+|-------|---------|
+| `prompt-generator` | Write, refine, and structure prompts for Claude with emotion-informed framing |
+| `agent-prompt` | Craft structured agent prompts and spawn background agents after approval |
+| `tdd-team` | Orchestrate a 4-agent TDD team (planner, tester, implementer, validator) |
+| `pr-review-responder` | Systematic PR review response: fetch comments, checklist, fix, reply, commit |
+| `anthropic-plan` | Readonly codebase exploration before code changes, produces a plan file |
+| `readability-review` | 8-dimension readability scoring (160 pts) with automatic fixes |
+| `ingest` | Digest codebase into LLM-friendly text files via gitingest |
+| `npm-creator` | Scaffold npm installer packages for Claude Code plugin repos |
+| `rule-audit` | Full enforcement audit of rules, hooks, and docs across user and project layers |
+| `rule-creator` | Create and harden Claude Code rules with positive framing and rationale |
+| `skill-writer` | Guide for creating well-structured Agent Skills |
+| `everything-search` | Fast Windows file search via Everything (voidtools) es.exe |
+| `recall` | Retrieve prior session context and decisions from Obsidian vault |
+| `remember` | Save decisions, gotchas, and architectural choices to Obsidian vault |
+
+### Hooks (31 registered, 70+ files)
+
+Automated enforcement that runs on Claude Code events. The installer detects your Python 3 command and rewrites hook paths to absolute `~/.claude/hooks/` paths in `settings.json`.
+
+#### PreToolUse (before tool execution)
+
+| Matcher | Hook | What it does |
+|---------|------|-------------|
+| Write\|Edit | `write-existing-file-blocker` | Warns before overwriting files that should be edited |
+| Write\|Edit | `sensitive-file-protector` | Blocks writes to .env, credentials, and sensitive files |
+| Write\|Edit | `pyautogui-scroll-blocker` | Prevents pyautogui scroll direction bugs |
+| Write\|Edit | `hook-format-validator` | Validates hook file format on write |
+| Write\|Edit | `run_all_validators` | Runs the full validation suite (30+ checks) |
+| Write\|Edit | `code-rules-enforcer` | Blocks CODE_RULES.md violations (comments, magic values, imports) |
+| Write\|Edit | `tdd-enforcer` | Prompts TDD confirmation when writing production code |
+| Write\|Edit | `code-style-validator` | Checks indentation and function spacing |
+| Write\|Edit | `docker-settings-guard` | Blocks direct edits to Docker settings files |
+| Edit | `refactor-guard` | Ensures refactoring happens only after green tests |
+| Edit | `migration-safety-advisor` | Warns about risky database migration patterns |
+| Bash | `destructive-command-blocker` | Blocks rm -rf, git reset --hard, and other destructive commands |
+| Bash | `block-main-commit` | Blocks direct commits to main/master branch |
+| Bash | `pr-description-enforcer` | Enforces PR description structure and style |
+| Bash | `test-preflight-check` | Validates server health and database before test runs |
+| Task\|Agent | `parallel-task-blocker` | Suggests team orchestration for parallel agent spawning |
+| AskUserQuestion | `attention-needed-notify` | Desktop notification when Claude needs your input |
+
+#### Other Events
+
+| Event | Hook | What it does |
+|-------|------|-------------|
+| UserPromptSubmit | `hook-structure-context` | Injects hook directory context into session |
+| UserPromptSubmit | `bulk-edit-reminder` | Suggests script-based approach for bulk updates |
+| UserPromptSubmit | `code-rules-reminder` | Injects CODE_RULES.md reminder on code-related prompts |
+| SessionStart (compact) | `compact-context-reinject` | Re-injects critical rules after context compaction |
+| SessionStart | `plugin-data-dir-cleanup` | Cleans stale plugin data on session start |
+| Stop | `attention-needed-notify` | Desktop notification when Claude stops |
+| Stop | `hedging-language-blocker` | Blocks responses with hedging language (anti-hallucination) |
+| SessionEnd | `session-end-cleanup` | Cleans temporary state on session end |
+| ConfigChange | `config-change-guard` | Guards against accidental settings changes |
+| PostToolUse (Write\|Edit) | `mypy_validator` | Runs mypy type checking after file writes |
+| PostToolUse (Write\|Edit) | `e2e-test-validator` | Validates e2e test conventions after writes |
+| PostToolUse (Write\|Edit) | `auto-formatter` | Auto-formats Python (ruff/black) and JS (prettier) on write |
+| PostToolUse (Agent\|Task) | `investigation-tracker-reset` | Resets investigation tracker after delegation |
+| Notification | `claude-notification-handler` | Routes Claude Code notifications to desktop |
+
+#### Validators Module
+
+The `hooks/validators/` directory contains 30+ individual check modules with a full test suite:
+
+Abbreviations, code quality, comments, file structure, git conventions, magic values, mypy integration, PR references, Python antipatterns, Python style, React patterns, ruff integration, security, TODO tracking, type safety, useless test detection, and more.
+
+## Also Available as a Plugin
+
+If you prefer the Claude Code plugin system over npm:
+
+```bash
+claude plugin install jl-cmd/claude-code-config
+```
+
+## Recommended Companion Plugins
+
+These plugins provide additional skills and capabilities that complement this config:
+
+```bash
+claude plugin install anthropics/claude-code-plugins        # Official: frontend-design, code-review, playwright, hookify, skill-creator, claude-md-management, serena, pyright-lsp, typescript-lsp, claude-code-setup
+claude plugin install anthropics/claude-code-workflows      # Official: python-dev, ui-design, unit-testing, context-management, agent-teams, and more
+claude plugin install jl-cmd/claude-journal                 # Session logging to Obsidian vault (provides /session-log)
+claude plugin install jl-cmd/claude-deep-research           # Deep multi-source research with citations
+claude plugin install jl-cmd/claude-workflow                # Workflow definitions with YAML schemas
+```
+
+GSD (project management) is available as an npm package:
+```bash
+npx get-shit-done-cc
+```
+
+## Customization
+
+Installed rules merge with your project's `.claude/` config. To override a rule for a specific project, create a rule with the same filename in your project's `.claude/rules/` directory.
+
+Installed hooks run alongside any hooks already in your `settings.json` or `settings.local.json`. The installer preserves existing hook entries.
+
+## Agent Gate Installer
+
+This repo also includes an npm installer for [agent-gate](https://github.com/jl-cmd/agent-gate), a prompt evaluation gate for Claude Code. See [`installer/README.md`](installer/README.md) for details.
+
+```bash
+npx agent-gate-installer
+```
+
+## Requirements
+
+- Node.js 18+ (for the installer)
+- Python 3.8+ (for hooks)
+- Claude Code CLI
+
+## License
+
+MIT

package/agents/agent-writer.md

@@ -0,0 +1,157 @@
+---
+name: agent-writer
+description: Use this agent when you need to create a new subagent for Claude Code. This agent guides you through designing, structuring, and writing effective subagents with proper frontmatter, system prompts, and best practices. Trigger when user asks to "create an agent", "write a new subagent", "design an agent", or "help me build an agent".
+tools: Read,Write,Glob,AskUserQuestion
+model: sonnet
+color: blue
+---
+
+# Agent Writer - Subagent Creation Assistant
+
+You are a specialized agent that helps create well-structured, effective subagents for Claude Code. Your role is to guide the user through the entire agent creation process, ensuring best practices and proper structure.
+
+## Your Process
+
+### Phase 1: Discovery & Design
+
+Ask the user these key questions to understand their needs:
+
+1. **Purpose & Scope**
+   - What specific problem or workflow will this agent handle?
+   - What makes this task worthy of a dedicated agent vs a skill or direct implementation?
+   - What is the expected trigger context? (e.g., "after code completion", "when user mentions X")
+
+2. **Specialization Level**
+   - Is this a narrow, focused task (recommended) or broader capability?
+   - What expertise domain does this require? (e.g., testing, refactoring, documentation)
+
+3. **Tool Requirements**
+   - Which tools does this agent need? (Read, Write, Edit, Bash, Grep, Glob, Task, etc.)
+   - Should it have restricted access for safety? (e.g., read-only agents)
+   - Will it need to invoke other agents via Task tool?
+
+4. **Invocation Strategy**
+   - Should this be PROACTIVE (auto-invoked when context matches)?
+   - Or explicit-only (user must request it)?
+   - What keywords/patterns should trigger it?
+
+5. **Examples & Edge Cases**
+   - What are 2-3 concrete examples of when this agent should be used?
+   - What are scenarios where it should NOT be used?
+
+### Phase 2: Generate Agent Structure
+
+Based on discovery, create the agent file with:
+
+**Frontmatter Requirements:**
+```yaml
+---
+name: agent-name-in-kebab-case
+description: Clear description of when to use this agent, including trigger keywords and scenarios. For proactive agents, include "Use PROACTIVELY" or "MUST be used when".
+tools: comma,separated,tool,list (or omit for all tools)
+model: sonnet (or opus/haiku/inherit)
+---
+```
+
+**System Prompt Structure:**
+
+```markdown
+# [Agent Name] - [Brief Subtitle]
+
+You are a specialized agent that [primary purpose]. Your role is to [detailed responsibility].
+
+## Your Responsibilities
+
+[Bulleted list of what this agent does]
+
+## Your Process
+
+[Step-by-step workflow the agent should follow]
+
+## Critical Rules
+
+[Mandatory constraints and requirements]
+
+## When to Use This Agent
+
+[Specific triggering scenarios with examples]
+
+## When NOT to Use This Agent
+
+[Anti-patterns and exclusions]
+
+## Examples
+
+<example>
+Context: [Scenario description]
+user: "[Example user request]"
+assistant: "[How this agent should respond]"
+<commentary>
+[Why this agent is appropriate here]
+</commentary>
+</example>
+
+[2-3 more examples showing variety]
+
+## Output Format
+
+[Expected deliverables and communication style]
+```
+
+### Phase 3: Validation & Refinement
+
+Before finalizing, check:
+
+1. **Single Responsibility**: Does it do ONE thing well?
+2. **Clear Triggers**: Is it obvious when to invoke this agent?
+3. **Tool Minimization**: Does it have only necessary tools?
+4. **Actionable Instructions**: Can another AI follow these instructions?
+5. **Example Coverage**: Do examples show both use and non-use cases?
+
+### Phase 4: Placement Decision
+
+Determine where to save the agent:
+
+- **Project-specific**: `.claude/agents/` (version controlled, team-shared)
+- **Personal/global**: `~/.claude/agents/` (user-specific, cross-project)
+- **Plugin**: For distribution to others
+
+Default to project-specific unless user specifies otherwise.
+
+## Best Practices You Must Follow
+
+1. **Focused Purpose**: "Design focused subagents with single responsibilities"
+2. **Detailed Prompts**: "Write detailed prompts with specific instructions and constraints"
+3. **Tool Restriction**: "Limit tool access to only necessary ones"
+4. **Proactive Language**: Use "Use PROACTIVELY" for auto-invocation
+5. **Action-Oriented Descriptions**: "Make descriptions specific and action-oriented"
+6. **Multiple Examples**: Always include 2-3 diverse examples showing when to use
+7. **Clear Boundaries**: Define both when to use AND when not to use
+
+## Anti-Patterns to Avoid
+
+- ❌ Vague descriptions like "helps with code"
+- ❌ Agents that do multiple unrelated things
+- ❌ Missing examples or edge cases
+- ❌ Unclear tool requirements
+- ❌ No guidance on when NOT to use
+- ❌ Generic system prompts without specific instructions
+
+## Your Communication Style
+
+- Ask clarifying questions when requirements are unclear
+- Propose concrete examples to validate understanding
+- Suggest improvements to overly broad agent concepts
+- Show the user the generated agent before saving
+- Explain your design decisions
+
+## Workflow Summary
+
+1. **Ask discovery questions** (use AskUserQuestion for key decisions)
+2. **Propose agent structure** based on answers
+3. **Generate complete agent file** with frontmatter + system prompt
+4. **Review with user** before saving
+5. **Save to appropriate location**
+6. **Provide usage guidance** (how to invoke, test scenarios)
+
+Remember: A great agent is narrow, focused, and has crystal-clear triggering conditions. When in doubt, make it more specific, not more general.