claude-dev-env 1.0.0

package/commands/implement.md

@@ -0,0 +1,102 @@
+---
+description: Provide full implementation context to right-sized engineer in XML format
+allowed-tools: Task, Read, Grep, Glob
+---
+
+**Implementation with Full Context - XML-Structured Guidance**
+
+Launch a clean-coder agent with COMPREHENSIVE implementation context provided in structured XML format.
+
+## Process:
+
+1. **Gather Complete Context** - Analyze the codebase to understand:
+   - Existing patterns and conventions
+   - Available dependencies and libraries
+   - Testing approaches and frameworks
+   - File organization and naming conventions
+
+2. **Structure the Implementation Request in XML**:
+   ```xml
+   <implementation-context>
+     <requirements>
+       <user-request>Exact user requirements</user-request>
+       <acceptance-criteria>What defines success</acceptance-criteria>
+       <constraints>Any limitations or must-haves</constraints>
+     </requirements>
+
+     <project-context>
+       <codebase-patterns>
+         <pattern>Existing patterns found in codebase</pattern>
+         <conventions>Naming and style conventions observed</conventions>
+         <architecture>Current architectural approach</architecture>
+       </codebase-patterns>
+       <dependencies>
+         <available>List of available libraries/frameworks</available>
+         <avoid>Libraries NOT to use</avoid>
+       </dependencies>
+       <testing-approach>
+         <framework>Testing framework in use</framework>
+         <patterns>Test file patterns and locations</patterns>
+       </testing-approach>
+     </project-context>
+
+     <implementation-plan>
+       <approach>High-level approach to implementation</approach>
+       <steps>
+         <step priority="1">First implementation step</step>
+         <step priority="2">Second implementation step</step>
+         <!-- Additional steps as needed -->
+       </steps>
+       <test-strategy>
+         <tdd-requirement>MANDATORY: Write failing tests first</tdd-requirement>
+         <coverage>Expected test coverage approach</coverage>
+       </test-strategy>
+     </implementation-plan>
+
+     <engineering-principles>
+       <must-follow>
+         <principle>TDD - No production code without failing test</principle>
+         <principle>Follow existing patterns exactly</principle>
+         <principle>Use available utilities - no reinventing</principle>
+         <principle>Small, focused functions</principle>
+         <principle>Proper error handling</principle>
+       </must-follow>
+       <avoid>
+         <anti-pattern>Over-engineering for current scale</anti-pattern>
+         <anti-pattern>Breaking existing conventions</anti-pattern>
+         <anti-pattern>Copy-paste programming</anti-pattern>
+         <anti-pattern>Magic numbers/strings</anti-pattern>
+       </avoid>
+     </engineering-principles>
+
+     <success-criteria>
+       <criterion>All tests pass</criterion>
+       <criterion>Follows existing patterns</criterion>
+       <criterion>No linting/type errors</criterion>
+       <criterion>Maintains backward compatibility</criterion>
+     </success-criteria>
+   </implementation-context>
+   ```
+
+3. **Provide to Agent with Clear Instructions**:
+   - "ULTRATHINK through this implementation"
+   - "Follow TDD strictly - write tests FIRST"
+   - "Match existing patterns EXACTLY"
+   - "Use the XML context to understand all requirements and constraints"
+
+4. **Agent Should**:
+   - Parse the XML context thoroughly
+   - Implement following TDD (Red-Green-Refactor)
+   - Match existing codebase patterns
+   - Use available utilities and libraries
+   - Apply right-sized engineering principles
+   - Validate against success criteria
+
+**CRITICAL REQUIREMENTS**:
+- Provide COMPLETE context - incomplete context leads to wrong implementations
+- Ensure XML is well-formed and comprehensive
+- Include concrete examples from existing code
+- Specify exact file locations and patterns
+- Make constraints and requirements crystal clear
+
+This ensures the implementation agent has everything needed to deliver a solution that integrates seamlessly with the existing codebase while following best practices.

package/commands/initialize.md

@@ -0,0 +1,91 @@
+# Initialize Session
+
+You are starting a new task. Before proceeding, you MUST read and internalize the critical protocols from CLAUDE.md.
+
+## MANDATORY PROTOCOL REVIEW
+
+Read CLAUDE.md now and focus on:
+
+### 1. AGENT-FIRST WORKFLOW (CRITICAL)
+
+**BEFORE RESPONDING TO ANY USER MESSAGE:**
+- ☐ What is the user asking for?
+- ☐ Does ANY agent match this request?
+- ☐ If yes → INVOKE THE AGENT via Task tool
+- ☐ If no agent matches → Proceed with skills/direct implementation
+
+**Agent Decision Tree:**
+- Automation work → check available agents for automation patterns
+- Web App Development → check available agents for framework-specific patterns
+- Configuration/Architecture → config-extraction-agent, parallel-workflow-coordinator
+
+**Never skip agent check to "save time" or because request "seems simple"**
+
+### 2. SKILLS WORKFLOW (CRITICAL)
+
+**Before ANY task:**
+- ☐ List available skills in your mind
+- ☐ Does ANY skill match this request?
+- ☐ If yes → Use Skill tool to read and run it
+- ☐ Announce which skill you're using
+- ☐ Follow the skill exactly
+
+**Mandatory skills to remember:**
+- `code-standards` - For ALL code generation, planning, implementation
+- `superpowers:test-driven-development` - For ANY feature/bugfix
+- `superpowers:brainstorming` - BEFORE coding on design tasks
+- `superpowers:systematic-debugging` - For bugs/failures
+- `superpowers:verification-before-completion` - Before claiming work is done
+
+### 3. TDD IS NON-NEGOTIABLE
+
+**Red-Green-Refactor:**
+1. **Red**: Write failing test FIRST. NO production code.
+2. **Green**: MINIMUM code to pass test only.
+3. **Refactor**: Assess improvements after green.
+
+**If writing production code without failing test, STOP immediately.**
+
+### 4. CODE STANDARDS (ENFORCED)
+
+- No `Any` types - Use Union/Optional/generics
+- No `# type: ignore` without justification
+- All imports at top
+- No files in project root
+- Immutable data (frozen dataclasses)
+- Small functions (5-15 lines, max 30)
+- Max 2 nesting levels
+- No comments (self-documenting code)
+- No Unicode in print/debug (Windows compatibility)
+
+### 5. RIGHT-SIZED ENGINEERING
+
+**Always Do:**
+- Extract constants and configuration
+- Create reusable functions
+- DRY from the start
+- Single responsibility
+
+**Never Do (Solo Scale):**
+- Abstract base classes for single implementations
+- Dependency injection frameworks
+- Complex patterns
+- Over-abstracted interfaces
+
+## Common Rationalizations That Mean Failure
+
+If you think:
+- "This is too simple" → WRONG. Check agents/skills.
+- "Let me just implement quickly" → WRONG. Check agents/skills first.
+- "I'll gather context first" → WRONG. Agents/skills tell you HOW.
+- "This doesn't need formal process" → WRONG. Process prevents mistakes.
+
+## NOW PROCEED
+
+You have reviewed the critical protocols. Apply them to the current task.
+
+**Remember:**
+1. Check agents FIRST
+2. Check skills SECOND
+3. Follow TDD ALWAYS
+4. Build it right, but build it simple

package/commands/plan.md

@@ -0,0 +1,63 @@
+Plan a feature with full validation workflow.
+
+> **MANDATORY:** Load `~/.claude/docs/CODE_RULES.md` for all code standards.
+
+## Workflow (MANDATORY - NO SKIPPING STEPS)
+
+### Phase 1: Design
+1. **Invoke `plan` skill** - Discover configs, design through dialogue
+
+### Phase 2: Plan
+2. **Invoke `write-plan` skill** - Create detailed TDD implementation plan (CODE_RULES.md compliant)
+3. **Invoke `review-plan` skill** - Validate plan against CODE_RULES.md standards
+4. **Fix violations** - If review-plan finds issues, fix before proceeding
+
+### Phase 3: Approval (NEW PRs only)
+5. **Invoke `plan-checkpoint` skill** - Generate summary gist for reviewer approval
+6. **Wait for approval** - Do not proceed until approved
+
+### Phase 4: Execute
+7. **Invoke `plan-executor` agent** - Execute with full standards enforcement
+8. **Invoke `readability-review` skill** - Validate written code against CODE_RULES.md
+
+### Phase 5: Commit & Review
+9. **Invoke `/commit`** - Create atomic commits
+10. **Invoke `pre-push-review` skill** - MANDATORY pre-push review
+11. **Push branch** - Push to GitHub (NO PR yet)
+12. **Wait for commit review** - User reviews on GitHub
+13. **Create PR** - Only after user approves commit
+
+## Key Rules
+
+- NEVER offer execution until review-plan passes with ZERO violations
+- For NEW PRs: wait for reviewer approval on checkpoint before implementing
+- For PR REVIEW FIXES: skip checkpoint, proceed directly to execution
+- NEVER push until pre-push-review passes
+- NEVER create PR until user explicitly approves pushed commit
+
+## Skills & Agents Reference
+
+| Step | Tool | Purpose |
+|------|------|---------|
+| Design | `plan` skill | Collaborative design with config discovery |
+| Write | `write-plan` skill | TDD plan with CODE_RULES.md compliance |
+| Review Plan | `review-plan` skill | Validate plan against standards |
+| Execute | `plan-executor` agent | Implement with standards enforcement |
+| Review Code | `readability-review` skill | Validate code before commit |
+
+## Standards Reference
+
+All code quality standards are in `~/.claude/docs/CODE_RULES.md`:
+- Self-documenting code (no comments)
+- Centralized configs (reuse existing)
+- No magic values
+- No abbreviations
+- Complete type hints
+- All imports shown
+
+## Usage
+
+```
+/plan add user authentication
+/plan refactor the payment system
+```

package/commands/pr-comments.md

@@ -0,0 +1,47 @@
+---
+description: Fetch and display all comments from a GitHub PR (fetches comments from the current repo)
+---
+
+You are an AI assistant integrated into a git-based version control system. Your task is to fetch and display comments from a GitHub pull request.
+
+**CRITICAL: Detect the repository from the current git remote (upstream preferred, then origin).**
+
+Follow these steps:
+
+1. Detect `{owner}/{repo}` from `gh repo view --json nameWithOwner -q .nameWithOwner`
+2. Extract PR number from the argument (e.g., "PR44" → 44, "44" → 44)
+3. Use `gh api repos/{owner}/{repo}/issues/{number}/comments` to get PR-level comments
+4. Use `gh api repos/{owner}/{repo}/pulls/{number}/comments` to get inline review comments
+5. Use `gh api repos/{owner}/{repo}/pulls/{number}/reviews` to get review summaries
+6. Parse and format all comments in chronological order
+7. Return ONLY the formatted comments, with no additional text
+
+Format the comments as:
+
+## Comments
+
+### PR-level Comments
+
+[For each issue comment:]
+- @author (timestamp):
+  > quoted comment text
+
+### Review: @reviewer [action] (timestamp)
+
+[Review summary if present]
+
+[For each inline code comment:]
+- @author file.ts#line:
+  ```diff
+  [diff_hunk from the API response]
+  ```
+  > quoted comment text
+
+If there are no comments, return "No comments found."
+
+Remember:
+1. Only show the actual comments, no explanatory text
+2. Include PR-level comments, review summaries, and inline code review comments
+3. Preserve chronological order
+4. Show the file and line number context for inline code review comments
+5. Detect {owner}/{repo} dynamically from the current git remote

package/commands/readability-review.md

@@ -0,0 +1,20 @@
+---
+description: "8-dimension readability review: scores and FIXES code to 160/160. Also handles paste-rewrite via arguments."
+allowed-tools: Task, Read, Edit, Grep, Glob
+---
+
+Launch the readability-review agent to review and fix code readability.
+
+## Steps
+
+1. Launch a `readability-review-agent` via the Task tool
+2. The agent will: load its rubric → discover target code → read it → score every function → FIX anything below 16/20 → report
+
+## User Arguments
+
+If the user provided arguments: $ARGUMENTS
+
+- If arguments contain **pasted code**: locate the code in the codebase (Grep for a unique line), read the full file, score it against all 8 dimensions, rewrite to 160/160, and apply via Edit tool
+- If arguments contain a **file path**: review only that file
+- If arguments contain **"score-only"**: skip the fix phase and just report scores
+- If **no arguments**: review all changed files in the session (via `git diff --name-only`)

package/commands/review-plan.md

@@ -0,0 +1,7 @@
+Review the current plan against code standards.
+
+MANDATORY: Spawn a `readability-review-agent` via Task tool to perform the review. NEVER review inline in the main conversation.
+
+1. Identify plan files in `.planning/phases/` or `docs/plans/`
+2. Spawn `readability-review-agent` with full review instructions from the `review-plan` skill
+3. Report the agent's verdict back to the user

package/commands/right-size.md

@@ -0,0 +1,15 @@
+---
+description: Prevent over/under-engineering
+allowed-tools: Task
+---
+
+Launch the clean-coder agent to review code for appropriate engineering practices.
+
+The agent will evaluate whether abstractions, patterns, and practices match the actual needs of the project, ensuring code is neither over-engineered nor under-engineered for its current scale and purpose.
+
+The review will identify:
+- **Over-engineering**: Abstract classes with single implementations, unnecessary interfaces, complex patterns where simple functions would suffice
+- **Under-engineering**: Hardcoded values, magic numbers/strings, copy-pasted code, missing error handling
+- **Good examples**: Appropriate constant extraction, well-scoped functions, clear error handling, simple maintainable solutions
+
+The goal is to build it right, but build it simple - applying good engineering principles at the appropriate scale for the project.

package/commands/stubcheck.md

@@ -0,0 +1,89 @@
+---
+description: Detect and fix stub implementations in code and plans with agent/skill recommendations
+allowed-tools: Read, Grep, Glob, Skill
+---
+
+Execute comprehensive stub detection using the stub-detector skill to identify incomplete implementations and recommend appropriate solutions.
+
+## Process
+
+1. **Invoke stub-detector skill** to scan current project
+2. Identify all stubs in:
+   - Python code (pass, NotImplementedError, TODO comments)
+   - Plan documents (incomplete steps, TBD markers)
+   - Configuration (placeholder values)
+3. Classify by severity (CRITICAL/HIGH/MEDIUM/LOW)
+4. Recommend specific agents or skills based on:
+   - Project type (Web Automation, Django, etc.)
+   - Stub category (config, automation, business logic)
+   - Available implementations (check for existing solutions first)
+5. Present actionable report with:
+   - file:line references for each stub
+   - Severity and impact assessment
+   - Specific recommendations with rationale
+   - Batch operation opportunities
+6. Offer immediate actions to fix CRITICAL stubs
+
+## Stub Detection Patterns
+
+**Code stubs to find:**
+```
+pass statements
+NotImplementedError
+TODO/FIXME/HACK comments
+Empty functions with only docstrings
+Placeholder returns (return None when type suggests otherwise)
+```
+
+**Documentation stubs to find:**
+```
+[TODO] or [TBD] markers
+"To be implemented" sections
+Incomplete step descriptions
+Placeholder text in plans
+Missing details in implementation guides
+```
+
+## Agent/Skill Recommendation Logic
+
+**Web Automation stubs →**
+- Automation: automation-agent or automation skill
+- Google Sheets: sheets orchestrator agent
+- Config issues: config-extraction-agent or config-extraction skill
+
+**Web framework stubs →**
+- Models/views/forms: domain-specific agent
+- Business logic: domain-specific agent
+- Domain features: domain-specific agent
+
+**General stubs →**
+- Follow TDD workflow from CLAUDE.md
+- Follow CODE_RULES.md standards (via clean-coder agent)
+- Check for existing shared utilities first
+
+## Output Format
+
+Provide a clear summary report showing:
+- Total stubs found with severity breakdown
+- Grouped by category for batch processing
+- Specific recommendations for each stub
+- Immediate action options for user
+
+Example:
+```
+Found 7 stubs (3 CRITICAL, 2 HIGH, 2 MEDIUM)
+
+[CRITICAL] services/file_processor.py:45
+Incomplete matching logic
+→ Recommendation: Use FileProcessor (already available)
+→ Action: Refactor to use shared utility
+
+[HIGH] tests/test_integration.py:234
+Missing integration test
+→ Recommendation: Follow TDD workflow
+→ Agent: tdd-test-writer
+
+Would you like me to fix CRITICAL stubs now?
+```
+
+**IMPORTANT:** Always check if solutions already exist (like we just implemented FileProcessor) before recommending new development.

package/commands/sum.md

@@ -0,0 +1,30 @@
+---
+name: sum
+description: Generate a formatted session summary for quick pickup in new sessions
+---
+
+Provide a nicely formatted summary of where we are leaving off in this session.
+
+Use this format with proper line breaks:
+
+```
+---
+
+**Session Summary: [Project/Task Name]**
+
+**Status:** [Current state - e.g., Complete, In Progress, Blocked]
+
+**Commits:** (if any)
+- `hash` - Description
+
+**What's Done:**
+- Item 1
+- Item 2
+
+**Next Step:**
+[Single clear next action]
+
+---
+```
+
+Keep it concise but readable. Focus on actionable context, not history.

package/docs/CODE_RULES.md

@@ -0,0 +1,186 @@
+# Code Rules Reference
+
+Compact reference for agents. Hook-enforced rules marked with ⚡.
+
+---
+
+## COMMENT PRESERVATION (ABSOLUTE RULE)
+
+**NEVER remove existing comments.** If you are not adding or removing code on a line, do not touch its comments.
+
+- Existing comments are SACRED — never delete, rewrite, or "clean up" existing comments
+- New inline comments are not needed — write self-documenting code instead
+- Docstrings for new files/methods/classes are allowed
+- The hook enforces BOTH directions: blocks new inline comments AND blocks deletion of existing comments
+
+**Scope:** Only evaluate comments on lines YOU are actively changing. If code is untouched, its comments are untouched.
+
+---
+
+## CORE PRINCIPLES
+
+### Self-Documenting Code
+New code explains itself through naming. Do not add new inline comments — use descriptive names instead. Docstrings on functions/methods/classes are allowed.
+
+> **Full readability standard:** `~/.claude/skills/readability-review/SKILL.md` — 8-dimension rubric (naming, SRP, abstraction, control flow, domain language, call sites, state clarity, visual rhythm). Run `/check` for parallel team review or `/readability-review` standalone.
+
+### Centralized Configuration
+One source of truth. Every constant lives in ONE place (`config/`).
+
+### Reuse Before Create
+Search first. Import second. Create last.
+
+### Encapsulation Enables Cleaner Naming
+Expose constants via helper functions: `isMaxLevel(level)` > `level >= MAXIMUM_LEVEL`
+
+---
+
+## ⚡ HOOK-ENFORCED RULES
+
+These rules are automatically enforced by `code-rules-enforcer.py`. Violations block Write/Edit.
+
+| Rule | What's Checked |
+|------|----------------|
+| No NEW comments | `#` / `//` in new code only (existing comments NEVER removed; shebangs, type:, noqa, eslint, docstrings exempt) |
+| Imports at top | No `import` inside function bodies |
+| Logging format args | No `log_*(f"...")` - use `log_*("...", arg)` |
+| File line count | Max 400 lines per file |
+| Magic values | No literals in function bodies (0, 1, -1 exempt). Includes string templates — if you strip the interpolations from an f-string and the remaining literal text is structural (paths, URLs, patterns), those fragments are magic values that belong in config |
+| Constants location | No `UPPER_SNAKE =` outside `config/` |
+
+---
+
+## 3. REUSE CONSTANTS (DRY CONFIG)
+
+**Before writing ANY constant:**
+
+```bash
+# Find config files
+# Search your project for existing config files before creating new ones
+
+# Search for value
+grep -r "VALUE" config/
+```
+
+**Decision tree:**
+1. Search exact value → Found? → IMPORT IT
+2. Search semantic match → Found? → USE EXISTING NAME
+3. Config file exists? → ADD TO EXISTING
+4. Create new (rare)
+
+---
+
+## 4. CONFIG LOCATIONS
+
+| Constant Type | Location |
+|---------------|----------|
+| Timeouts, delays, retries | `config/timing.py` |
+| Ports, URLs, thresholds | `config/constants.py` |
+| CSS selectors | `config/selectors.py` |
+
+---
+
+## 5. NO ABBREVIATIONS
+
+Full words only. No mental translation.
+
+| Bad | Good |
+|-----|------|
+| `ctx`, `cfg`, `msg` | `context`, `configuration`, `message` |
+| `btn`, `idx`, `cnt` | `button`, `index`, `count` |
+| `tmp`, `elem`, `val` | `temporary_value`, `element`, `value` |
+
+**Exception:** `i`, `j`, `k` in loops; `e` for exception.
+
+**Extended naming rules** (from readability-review rubric):
+- Loop vars: `each_order`, `each_user` (prefix `each_`)
+- Booleans: `is_valid`, `has_permission`, `should_retry` (prefix `is_`/`has_`/`should_`/`can_`)
+- Collections: `all_orders`, `all_users` (prefix `all_`)
+- Maps: `price_by_product`, `user_by_id` (pattern `X_by_Y`)
+- Preposition params: `from_path=`, `to=`, `into=`
+- **Banned names:** `result`, `data`, `output`, `response`, `value`, `item`, `temp`
+- **Banned prefixes:** `handle`, `process`, `manage`, `do`
+
+---
+
+## 6. COMPLETE TYPE HINTS
+
+```python
+def function_name(
+    parameter: str,
+    optional: Optional[str] = None,
+) -> ReturnType:
+```
+
+- ALL parameters typed
+- ALL returns typed
+- No `Any` type
+- No `# type: ignore`
+
+*(Also enforced by mypy_validator.py hook)*
+
+---
+
+## 7. RIGHT-SIZED ENGINEERING
+
+**Simple > Clever. Functions > Classes. Concrete > Abstract.**
+
+Never: ABC for single impl, DI frameworks, factory for single type
+Always: Functions when no state, concrete classes, simple imports
+
+---
+
+## 8. TDD PROCESS
+
+1. **RED** - Failing test first
+2. **GREEN** - Minimum code to pass
+3. **REFACTOR** - Only if valuable
+
+---
+
+## 9. SELF-CONTAINED COMPONENTS
+
+Components own their complete feature. Parents just render `<Child />`.
+
+Child handles: state, modals, overlays, toasts
+Parent knows: nothing about child's internals
+
+---
+
+## 10. NO REDUNDANT DATA FETCHES
+
+If you already have data, don't fetch again.
+
+```typescript
+// BAD
+const profile = await getProfile();
+const localProfile = await db.profile.first(); // same data!
+
+// GOOD
+const profile = await db.profile.first();
+// ... use profile throughout ...
+```
+
+---
+
+## QUICK CHECKLIST
+
+```
+Before ANY code:
+[ ] Searched existing configs?
+[ ] Importing from centralized config?
+
+Hook will enforce:
+[⚡] No NEW comments (existing comments NEVER removed)
+[⚡] No magic values
+[⚡] Imports at top
+[⚡] Logging format args
+[⚡] File under 400 lines
+[⚡] Constants in config/
+
+Manual check:
+[ ] No abbreviations?
+[ ] Complete type hints?
+[ ] Self-contained components?
+[ ] Readability: /check or /readability-review
+```