ai-agent-rules 0.15.2__py3-none-any.whl

ai_rules/config/claude/commands/comment-cleanup.md

@@ -0,0 +1,161 @@
+---
+description: Remove unnecessary code comments that explain WHAT instead of WHY
+allowed-tools: AskUserQuestion, Bash, Edit, Glob, Grep, Read, TodoWrite, Write
+model: sonnet
+---
+
+## Context
+
+- Project root: !`git rev-parse --show-toplevel 2>/dev/null || pwd`
+- Primary languages: !`find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.rb" -o -name "*.rs" \) 2>/dev/null | sed 's/.*\.//' | sort | uniq -c | sort -nr | head -5`
+- Test files count: !`find . -type f \( -name "*test*" -o -name "*spec*" \) 2>/dev/null | wc -l`
+- Total comment lines: !`grep -r "^\s*\(//\|#\|/\*\)" --include="*.js" --include="*.ts" --include="*.py" --include="*.go" 2>/dev/null | wc -l`
+- Build/Test command: !`[ -f package.json ] && echo "npm" || [ -f Makefile ] && echo "make" || [ -f pyproject.toml ] && echo "pytest" || echo "unknown"`
+
+# Comment Cleanup
+
+Perform comprehensive cleanup of unnecessary code comments across the codebase, removing comments that explain WHAT the code does (when self-evident) rather than WHY certain decisions were made.
+
+## Decision Framework
+
+For each comment encountered, apply this evaluation in order:
+
+1. **Is it a preserved type?** (Shebang, linter directive, TODO/FIXME, docstring) → **KEEP**
+2. **Does it explain WHY?** (Rationale, workaround, warning, performance note) → **KEEP**
+3. **Does it explain WHAT?** (Organizational, obvious, implementation detail) → **REMOVE**
+4. **Would removing make code harder to maintain?** → **KEEP**
+
+## What to Remove
+
+**Organizational comments**: Section dividers
+```python
+# --- User Management Functions ---
+# Database Operations
+```
+
+**Obvious comments**: Restating the code
+```javascript
+// Create config
+const config = createConfig();
+// Check if path exists
+if (!pathExists(path)) return false;
+```
+
+**Implementation detail comments**: Explaining how when it's clear
+```go
+// Try exact match first
+if val, ok := map[key]; ok { return val }
+```
+
+**Trivial test comments**: Stating the obvious
+```python
+# Should be parsed as integer
+assert isinstance(result, int)
+```
+
+## What to Preserve
+
+**WHY comments**: Explaining decisions, workarounds, warnings
+```javascript
+// Use deep copy to prevent mutation of shared state object
+const result = deepCopy(baseObject);
+
+// Workaround for IE11 - doesn't support fetch API
+if (!window.fetch) return xhrRequest(url);
+
+// PERF: Cache compiled regex to avoid recompilation on every call
+const cachedPattern = /^[a-z]+$/i;
+```
+
+**Documentation comments**: Function/class docs (docstrings, JSDoc, JavaDoc, etc.)
+
+**Directives**: Shebangs (`#!/usr/bin/env`), linter configs (`eslint-disable`, `noqa`, `@ts-ignore`, `#pragma`)
+
+**Action items**: TODO, FIXME, HACK, NOTE with context
+
+## Systematic Process
+
+### Step 1: Prioritized Search Strategy
+
+Use the language information from Context above to focus your search. Map comment patterns by language:
+- **JavaScript/TypeScript**: `//`, `/* */`, `/** */` (preserve JSDoc)
+- **Python**: `#`, `"""`, `'''` (preserve docstrings)
+- **Go**: `//`, `/* */`
+- **Shell/Bash**: `#` (preserve shebangs)
+- **Ruby**: `#`, `=begin`/`=end`
+- **Rust**: `//`, `/* */`, `///` (preserve doc comments)
+
+### Step 2: Execute Search
+
+**Start with highest-density areas** (most trivial comments):
+1. Test files (`*_test.*`, `test_*.py`, `*.spec.*`)
+2. Implementation files in `src/`, `lib/`, `pkg/`
+3. Configuration files
+
+**Search commands** by language:
+```bash
+# JavaScript/TypeScript
+rg "^\s*//" --type js --type ts src/ tests/
+
+# Python
+rg "^\s*#(?!\s*(?:!/|pragma|noqa|type:))" --type py
+
+# Multiple languages
+rg "^\s*(?://|#)" src/ tests/ --glob '!*.{md,txt}'
+```
+
+### Step 3: Review & Categorize
+
+For each file with comments:
+1. Apply decision framework to each comment
+2. Mark comments for removal vs preservation
+3. Look for patterns (e.g., all section dividers)
+4. Consider batch removal for repeated trivial patterns
+
+### Step 4: Execute Removals
+
+- Use Edit tool for targeted comment removal
+- Maintain code structure and intentional blank lines
+- Process files systematically (test files first)
+- Keep running count of removals
+
+### Step 5: Validation
+
+Run validation checks:
+```bash
+# Run tests
+npm test  # or pytest, go test, cargo test, etc.
+
+# Run linter/formatter
+npm run lint  # or ruff check, golangci-lint, etc.
+
+# Verify no trivial comments remain
+rg "^\s*(?://|#)\s*(?:Create|Check|Set|Get|Return|Loop)" src/
+```
+
+## Success Criteria
+
+✓ All trivial/obvious comments removed
+✓ Code remains self-documenting through clear naming
+✓ All tests pass without modification
+✓ Linter checks pass
+✓ Only WHY comments remain (if any)
+✓ Test execution time unchanged
+✓ Code coverage metrics maintained
+
+## Common Pitfalls to Avoid
+
+- **Don't remove error suppression**: `// @ts-ignore`, `// eslint-disable`, `# noqa`
+- **Don't remove type hints**: `# type: ignore`, `/** @type {string} */`
+- **Don't remove legal/license headers**: Usually at file top
+- **Don't remove API documentation**: JSDoc, docstrings, doc comments
+- **Do preserve context for workarounds**: Even if explaining WHAT, workarounds need WHY
+
+## Reporting
+
+After completion, provide summary:
+- Total comments removed: X
+- Files modified: Y
+- Comment types preserved: [list]
+- Test result: PASS/FAIL
+- Next steps if issues found

ai_rules/config/claude/commands/continue-crash.md

@@ -0,0 +1,38 @@
+---
+description: Continues after a session crash while working on a task
+model: inherit
+---
+
+## Context
+
+- Git status: !`git status --porcelain 2>/dev/null | head -20 || echo "NOT_IN_GIT"`
+- Recent commits: !`git log --oneline -5 2>/dev/null || echo "NO_COMMITS"`
+- Modified files: !`git diff --name-only 2>/dev/null | head -10 || echo "NONE"`
+- Current branch: !`git branch --show-current 2>/dev/null || echo "UNKNOWN"`
+- TODO files: !`ls -la PLAN__*.md TODO.md 2>/dev/null || echo "No TODO files found"`
+
+# Continue After Crash
+
+Our session crashed. Use the context above to recover and continue where we left off.
+
+## Recovery Process
+
+1. **Analyze context** from pre-executed commands above:
+   - Review git status to see uncommitted work
+   - Check recent commits to understand what was completed
+   - Look for TODO/PLAN files documenting the task
+
+2. **Reconstruct and resume**:
+   - Identify the task from the evidence
+   - Create or update TODO list based on actual progress
+   - Fix any test failures before continuing
+   - Continue from the interruption point
+
+## Important
+
+- Base reconstruction only on the evidence provided in Context
+- If context is unclear from the data above, ask for clarification
+- Don't duplicate completed work - verify what's done in git history
+- Maintain the original task direction and intent
+
+Resume work from where it was interrupted.

ai_rules/config/claude/commands/dev-docs.md

@@ -0,0 +1,169 @@
+---
+description: Creates or updates PLAN.md based on session - auto-detects create vs update mode
+allowed-tools: AskUserQuestion, Bash, Edit, Glob, Grep, Read, TodoWrite, Write
+model: sonnet
+---
+
+## Context
+
+- Project: !`git rev-parse --show-toplevel 2>/dev/null || echo "NOT_IN_GIT_REPO"`
+- PLAN files: !`sh -c 'PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null); if [ -z "$PROJECT_ROOT" ]; then echo "NOT_IN_GIT_REPO"; exit 0; fi; cd "$PROJECT_ROOT" && for f in PLAN__*.md; do [ -f "$f" ] && echo "$f" && found=1; done; if [ -z "$found" ]; then [ -f PLAN.md ] && echo "LEGACY_PLAN" || echo "NO_PLAN_FILES"; fi' 2>/dev/null | sed 's/PLAN__//;s/\.md$//' | paste -sd ',' -`
+- Directory: !`pwd`
+- Last commit: !`git log -1 --format="%h %ai %s" 2>/dev/null || echo "NO_COMMITS"`
+
+# Create or Update Development Documentation
+
+Automatically creates task-specific PLAN files (`PLAN__<TASK>.md`) or updates existing ones by analyzing session activity to track implementation progress. Multiple agents can work simultaneously, each with their own per-task plan file.
+
+## Task-Specific PLAN Files
+
+**Purpose:** Single source of truth for plans and progress across sessions, tracking multi-phase work with status indicators
+
+**Naming Convention:**
+- Format: `PLAN__<TASK>.md` (always `PLAN__` with two underscores)
+- Task identifier: 1-2 words, uppercase letters only, single underscores between words
+- Valid: ✓ `AUTH_FLOW`, ✓ `API_MIGRATION`, ✓ `SLACK_FORMATTING`
+- Invalid: ✗ `auth_flow` (lowercase), ✗ `AUTH__FLOW` (double underscore), ✗ `TOO_MANY_WORDS` (>2 words)
+
+## CRITICAL: File Location
+
+**ALWAYS write PLAN files to the git repository root, NEVER to ~/.claude/plans/**
+
+- Target path: `{git_root}/PLAN__<TASK>.md` (e.g., `/Users/user/project/PLAN__AUTH_FLOW.md`)
+- Claude Code has an internal plan mode that uses `~/.claude/plans/` - this is SEPARATE and UNRELATED
+- If you see a path containing `~/.claude/plans/`, you are using the WRONG location
+- The `/dev-docs` command manages repository-local documentation, not Claude Code internals
+
+## Phase 1: Determine Mode
+
+Use pre-executed context to determine mode:
+
+**Check "PLAN files" from Context:**
+- `NO_PLAN_FILES` → **Create mode**: Extract plan from ExitPlanMode, generate task name
+- `LEGACY_PLAN` → **Legacy migration**: Rename PLAN.md to PLAN__<TASK>.md, continue as update
+- Single task (e.g., `AUTH_FLOW`) → **Update mode**: Work with that specific file
+- Multiple tasks (e.g., `AUTH_FLOW,API_MIGRATION`) → **Disambiguate**: Determine which task or create new
+
+**Legacy Migration:**
+1. Read `PLAN.md`, extract main task theme
+2. Generate task name (1-2 uppercase words with underscores)
+3. Rename: `mv PLAN.md PLAN__<TASK>.md`
+4. Continue as update mode
+
+**Disambiguate (multiple PLAN files):**
+1. List available tasks
+2. Search recent ExitPlanMode/Write/Edit/TodoWrite for context clues
+3. If clear match → proceed with that task
+4. If ambiguous → ask user which task to update or create new
+
+## Phase 2: Extract Plan & Evidence
+
+### For Create Mode
+
+⚠️ **ANTI-RECENCY BIAS WARNING**: Recent work dominates attention. The FIRST ExitPlanMode typically has the complete vision. Later calls often refine/narrow focus. You MUST document ALL work (completed, current, AND future).
+
+**Extract plans:**
+1. Find ALL ExitPlanMode calls: `"name":"ExitPlanMode","input":{"plan":"..."}`
+2. Extract each in chronological order
+3. **CRITICAL**: Read FIRST call for complete vision
+4. **PRESERVE original structure** - if phases existed, use phases; if flat list, keep flat
+5. **DO NOT invent structure** not in original
+6. Synthesize complete plan ensuring ALL original items captured
+7. Generate task name from main theme (1-2 uppercase words)
+
+**Search for implementation evidence:**
+1. Review activity after last ExitPlanMode
+2. Find: Write/Edit/NotebookEdit/Bash/TodoWrite calls, completion phrases, confirmations
+3. Map tasks to evidence via file paths and keywords
+
+**Assign statuses:**
+- Strong evidence (multiple indicators) → [DONE]
+- Medium evidence (single indicator) → [IN PROGRESS]
+- Weak/no evidence → [TODO]
+
+### For Update Mode
+
+1. Read `PLAN__<TASK>.md`, parse task hierarchy with statuses
+2. Search recent activity for implementation evidence
+3. Match tasks to evidence, assign status updates
+4. Check for plan evolution: ExitPlanMode newer than PLAN file
+5. Present findings if any tasks have evidence (skip if all TODO)
+
+## Phase 3: Write or Update File
+
+### Create Mode - Generate File
+
+Structure (preserve original organization from ExitPlanMode):
+- **Overview**: 1-2 paragraph summary
+- **Scope**: Features, components, files, integrations
+- **Purpose**: Problem, value, requirements, context
+- **Implementation Details**: Hierarchical tasks with `[STATUS] description`
+  - Include file paths/names
+  - Nest with 3-space indentation
+  - Order: setup → implementation → testing
+  - Apply evidence-based statuses
+
+Write to `{git_root}/PLAN__<TASK>.md` (NOT ~/.claude/plans/) and **validate**:
+- Compare structure to FIRST ExitPlanMode call
+- If original had phases, ensure all phases documented
+- If original was flat list, ensure no invented phases
+- Count items: original N items should match generated
+- Future work documented as [TODO], not omitted
+- Task name format valid (1-2 uppercase words, single underscores)
+
+Report: file path, task count, structure type
+
+### Update Mode - Modify Existing
+
+Update `PLAN__<TASK>.md`:
+- For each status change, use Edit tool
+- Match exact old_string with indentation and status
+- Replace with new status
+- Preserve hierarchy and formatting
+
+Handle plan evolution if detected:
+- Add new areas to existing structure
+- Insert new tasks under relevant parents
+- Mark deprecated as `[CANCELLED - plan changed]`
+- Update Scope/Purpose if changed
+- Append to Plan Updates section with timestamp
+
+Report: file path, X tasks completed, Y in progress, Z changes made
+
+## Status Transitions & Evidence Strength
+
+**Evidence Strength:**
+- Strong: Multiple indicators → [DONE]
+- Medium: Single indicator → [IN PROGRESS]
+- Weak/None: Mention only → [TODO]
+
+**Valid Status Labels:**
+- [TODO] → Not started
+- [IN PROGRESS] → Started not finished
+- [DONE] → Completed
+- [BLOCKED] → Cannot proceed (include reason)
+- [CANCELLED - plan changed] → No longer relevant
+
+## Critical Requirements
+
+**All Modes:**
+- Analyze session activity for evidence (tool calls + completion phrases)
+- Match ALL tasks to evidence, assign statuses intelligently
+- Include evidence-free tasks as [TODO] - never skip planned work
+- Use 3-space indentation, preserve hierarchy
+- Inform user of mode and target file
+
+**Create Mode:**
+- **PREVENT RECENCY BIAS**: Prioritize FIRST ExitPlanMode for complete vision
+- **PRESERVE STRUCTURE**: Match original organization exactly
+- Document entire plan regardless of implementation progress
+- Support both complex multi-phase AND simple flat lists
+- Generate valid task name, create `PLAN__<TASK>.md` in git root (NEVER in ~/.claude/plans/)
+
+**Update Mode:**
+- Use Edit tool with exact matching
+- Handle evolution: add new, mark deprecated as cancelled
+
+**Legacy Migration:**
+- Detect `PLAN.md`, generate task name from content
+- Rename using Bash `mv`, inform user of migration

ai_rules/config/claude/commands/pr-creator.md

@@ -0,0 +1,247 @@
+---
+description: Creates GitHub pull requests with comprehensive descriptions by analyzing git history and code changes
+allowed-tools: AskUserQuestion, Bash, Glob, Grep, Read, TodoWrite
+model: sonnet
+---
+
+## Context
+
+- Project: !`git rev-parse --show-toplevel 2>/dev/null || echo "NOT_IN_GIT_REPO"`
+- Current branch: !`git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "NO_BRANCH"`
+- Base branch: !`git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main"`
+- Uncommitted changes: !`git status --porcelain 2>/dev/null | wc -l | xargs`
+- Remote status: !`git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "NOT_PUSHED"`
+- Commits ahead: !`git rev-list --count @{u}..HEAD 2>/dev/null || echo "0"`
+
+# Create GitHub Pull Request
+
+**Usage:**
+- `/pr-creator` - Create regular pull request
+- `/pr-creator draft` - Create draft pull request
+
+You are an expert software engineer creating high-quality PR descriptions that facilitate efficient code review. All feature changes are already committed to the local feature branch.
+
+## Pre-flight Checks
+
+**Validate environment:**
+1. Check "Project" - if "NOT_IN_GIT_REPO", stop and inform user
+2. Check "Current branch" - if "NO_BRANCH", stop and inform user
+3. Check "Uncommitted changes" - if > 0, warn user and ask to continue
+
+## Stage 1: Analyze & Generate Draft
+
+### Step 1: Determine PR Type & Detect Draft Mode
+
+**Check command argument:**
+- If `$1` equals "draft" → set flag to create draft PR
+- Default (empty or other value) → create regular PR
+
+**Analyze commits to classify PR type:**
+```bash
+git log origin/{base-branch}..HEAD --format="%s"
+```
+
+Match commit patterns to type:
+- **Feature**: "feat:", "add", "implement", "create", new functionality
+- **Fix**: "fix:", "bug", "resolve", "patch", corrects issues
+- **Refactor**: "refactor:", "restructure", "clean up", improves without behavior change
+- **Docs**: "docs:", changes primarily to *.md or documentation
+- **Test**: "test:", additions/improvements to test files
+- **Chore**: "chore:", maintenance, dependency updates, config changes
+
+### Step 2: Gather Comprehensive Information
+
+**Inspect changes:**
+```bash
+# All commits not in base branch
+git log origin/{base-branch}..HEAD
+
+# Complete scope of changes
+git diff origin/{base-branch}...HEAD --stat
+
+# Detailed code changes
+git diff origin/{base-branch}...HEAD
+```
+
+**Look for:**
+- GitHub issue references in commits or code comments
+- Breaking changes or API modifications
+- New dependencies or configuration changes
+- Security-relevant changes (auth, validation, data handling)
+- Performance implications (algorithms, database queries, caching)
+
+### Step 3: Assess Complexity
+
+**Calculate complexity indicators:**
+```bash
+# Lines changed
+git diff origin/{base-branch}...HEAD --shortstat
+
+# Files modified
+git diff origin/{base-branch}...HEAD --name-only | wc -l
+```
+
+**Complexity guidance:**
+- Lines >500 → Suggest splitting into smaller PRs
+- Files >10 → Add file navigation guide to description
+- Multiple unrelated concerns → Recommend separate PRs
+
+### Step 4: Generate Draft Description
+
+**Structure based on PR type:**
+
+**Opening paragraph** (1-2 sentences):
+- Start with "This PR [enables/adds/fixes/updates/refactors]..."
+- State what changed and the value/benefit delivered
+- Focus on user-facing or technical value
+
+**Context paragraph** (2-4 sentences):
+- Explain the problem or "before this change" state
+- Help reviewers understand WHY this change was needed
+- Provide relevant background informing implementation decisions
+
+**Implementation details** (3-5 bulleted items):
+- Use plain bullets (-)
+- Include concrete names: functions, classes, fields, patterns, files
+- Focus on HOW the solution was implemented
+- One line per bullet, specific and technical
+- Highlight key technical decisions or approaches
+
+**Review-friendly additions** (when applicable):
+- **Breaking Changes**: Clearly flag if API changes break compatibility
+- **Testing Instructions**: Steps to manually verify (for complex features)
+- **Security Notes**: Call out security-relevant changes
+- **Performance Impact**: Note if this affects performance significantly
+
+**Issue references** (if found):
+```
+Fixes #123
+Relates to #456
+```
+
+### Step 5: Present Draft & STOP
+
+Present the draft description to user and **STOP**. You must wait for explicit approval.
+
+When presenting:
+- Indicate if this will be draft PR or regular PR
+- Show complexity assessment if lines >300 or files >7
+- Ask if user wants to proceed or revise description
+
+## Stage 2: Create Pull Request
+
+**Only proceed after receiving explicit user approval.**
+
+### Verification Steps
+
+1. **Check for PLAN files** that shouldn't be pushed:
+```bash
+# Check if PLAN files in commits
+git log origin/{base}..HEAD --name-only --pretty=format: | grep -q "^PLAN"
+
+# Check if PLAN files currently tracked
+git ls-files | grep -q "^PLAN"
+```
+
+If PLAN files found:
+- STOP immediately with clear error
+- Explain these are development docs (from /dev-docs) that shouldn't be in PRs
+- Provide remediation:
+  - Option 1: Remove PLAN files and amend/rebase commits
+  - Option 2: Create clean branch without PLAN files
+  - Remind to exclude PLAN files before committing
+
+2. **Ensure branch pushed to remote:**
+```bash
+# Check "Remote status" from Context
+# If "NOT_PUSHED":
+git push -u origin HEAD
+```
+
+### Create PR
+
+**Extract title** from opening paragraph (concise, 50-70 chars)
+
+**Create PR** using appropriate command:
+
+Regular PR:
+```bash
+gh pr create --title "Brief PR title" --base {base-branch} --body "$(cat <<'EOF'
+[Full approved PR description]
+EOF
+)"
+```
+
+Draft PR:
+```bash
+gh pr create --title "Brief PR title" --base {base-branch} --draft --body "$(cat <<'EOF'
+[Full approved PR description]
+EOF
+)"
+```
+
+**Display PR URL** to user upon success
+
+## PR Description Guidelines
+
+**Formatting:**
+- Use plain prose (no bold/headers in body)
+- Use plain bullets (-) for implementation details
+- One line per bullet
+- Total length: 8-15 lines (complex PRs may be 15-20 with review sections)
+- Issue references at bottom, separated by blank line
+- Use GitHub autolink: `Fixes #123` or `Relates to #123`
+
+**Tone & Style:**
+- Professional but conversational
+- Focus on "why" and "how" over "what"
+- Use specific technical terms and names
+- Avoid marketing language or superlatives
+- Write for engineer reviewers needing context quickly
+
+**Content:**
+- Base all content on actual git history and code inspection
+- Never guess or fabricate information
+- Include concrete technical details (function/class names, patterns)
+- Explain reasoning behind implementation choices
+- Reference relevant issues when applicable
+
+**Review Optimization:**
+- Flag breaking changes prominently
+- Add testing instructions for complex features
+- Highlight security-relevant changes
+- Note performance implications
+- Suggest navigation for large PRs
+
+## Critical Requirements
+
+**Approval Gate:**
+- NEVER skip user approval of draft description
+- ALWAYS present draft and wait for explicit confirmation
+- Accept and incorporate revision requests
+- Only proceed to PR creation after clear approval
+
+**Accuracy:**
+- Inspect actual commits using git commands
+- Review real code changes via git diff
+- Do not rely solely on commit messages
+- Verify issue references exist in code or commits
+
+**Structure:**
+- Follow 3-section format (opening, context, implementation)
+- Maintain 8-15 line length guideline (up to 20 for complex PRs)
+- Use proper formatting for issue references
+- Add review-friendly sections when applicable
+
+**Branch Management:**
+- Verify branch pushed to remote before creating PR
+- Use `git push -u origin HEAD` if needed
+- Confirm base branch correct (from Context)
+- Block PRs containing PLAN files
+
+**Formatting:**
+- Always use HEREDOC in `gh pr create --body` to preserve formatting
+- Ensure proper line breaks and bullet formatting
+- Include blank line before issue references
+
+Your goal is to create PR descriptions that make code review efficient and thorough, providing reviewers with all context needed to understand and evaluate the changes quickly.