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

ai_rules/config/claude/commands/annotate-changelog.md

@@ -0,0 +1,191 @@
+---
+description: Annotates auto-generated changelog entries with detailed descriptions
+allowed-tools: AskUserQuestion, Bash, Edit, Glob, Grep, Read, TodoWrite
+model: sonnet
+---
+
+## Context
+
+- Changelog file: !`find . -maxdepth 1 -name "CHANGELOG*" -type f | head -1`
+- Recent commits: !`git log --oneline -20 2>/dev/null || echo "NO_COMMITS"`
+- Git repo root: !`git rev-parse --show-toplevel 2>/dev/null || pwd`
+
+# Annotate Changelog
+
+**Usage:**
+- `/annotate-changelog` - Add detailed descriptions to terse auto-generated changelog entries
+
+Enhances auto-generated changelogs (from semantic-release, conventional commits, etc.) by adding user-facing descriptions beneath terse commit messages. Gathers context from git diffs, commit messages, and PR descriptions to explain what changed and why it matters.
+
+## Workflow
+
+### Phase 1: Parse Changelog
+
+1. **Read CHANGELOG.md** (from Context above)
+2. **Identify entries needing annotation:**
+   - Look for terse commit messages ("Cc perms", "Still flaky", "Llms are dumb")
+   - Short descriptions without explanation of impact
+   - Entries with just commit SHA links but no detail
+3. **Extract commit information:**
+   - Parse version sections (e.g., `## [0.10.3] - 2024-12-05`)
+   - Find commit SHAs in links (e.g., `[9dd366c]`)
+   - Note existing structure (bullets, sections like "### Added")
+
+### Phase 2: Gather Context
+
+For each entry needing annotation:
+
+1. **Get full commit message:**
+   ```bash
+   git log -1 --format="%B" <sha>
+   ```
+   The full body often has more detail than the subject line.
+
+2. **Get commit diff summary:**
+   ```bash
+   git show --stat <sha>
+   ```
+   Shows which files changed, gives technical context.
+
+3. **Search for related PR:**
+   ```bash
+   gh pr list --search "<sha>" --state merged --json number,title
+   ```
+   Find if this commit was part of a pull request.
+
+4. **If PR found, get description:**
+   ```bash
+   gh pr view <pr_number> --json body --jq .body
+   ```
+   PR descriptions often have better user-facing explanations.
+
+5. **If context is insufficient** (all sources are terse or unclear):
+   - Use AskUserQuestion tool
+   - Show the commit SHA and message
+   - Ask: "What was the user-facing change in this commit?"
+
+### Phase 3: Generate Annotations
+
+For each entry:
+
+1. **Analyze context gathered:**
+   - What files changed? (from diff)
+   - What's the user-facing impact?
+   - Why did this change happen? (bug fix, new feature, breaking change)
+
+2. **Write annotation:**
+   - Focus on user-facing impact, not implementation details
+   - Explain WHAT changed for users, not HOW it was implemented
+   - Keep it concise (1-2 sentences)
+   - Match existing changelog tone/style
+
+3. **Format:**
+   ```markdown
+   - Terse commit message ([commit_sha])
+     > Detailed annotation explaining user-facing impact
+   ```
+
+### Phase 4: Update Changelog
+
+1. **Preserve structure:**
+   - Keep version headers intact
+   - Maintain section organization (Added, Fixed, etc.)
+   - Keep commit SHA links as-is
+   - Don't remove or replace original entries
+
+2. **Add annotations:**
+   - Insert description as blockquote below entry
+   - Use `>` for blockquote formatting
+   - Maintain consistent indentation
+
+3. **Present changes:**
+   - Show diff before applying
+   - Explain how many entries were annotated
+   - Give user chance to review
+
+4. **Apply edits:**
+   - Use Edit tool to update CHANGELOG.md
+   - Make one edit per entry or batch similar entries
+
+## Example Transformation
+
+**Before:**
+```markdown
+## [0.10.3] - 2024-12-05
+
+### Bug Fixes
+
+- Cc perms ([9dd366c])
+```
+
+**After:**
+```markdown
+## [0.10.3] - 2024-12-05
+
+### Bug Fixes
+
+- Cc perms ([9dd366c])
+  > Fixed Claude Code permissions in settings.json to allow the doc-writer skill
+```
+
+**Before:**
+```markdown
+### Added
+
+- Doc-writer skill for claude code ([e293e4c])
+```
+
+**After:**
+```markdown
+### Added
+
+- Doc-writer skill for claude code ([e293e4c])
+  > Added new Claude Code skill that provides guidance for writing compact, effective technical documentation including README, ARCHITECTURE, and API docs
+```
+
+## Key Principles
+
+**Focus on user impact:**
+- "Added X feature that lets users do Y"
+- "Fixed bug where Z would fail"
+- NOT: "Updated function foo() to call bar()"
+
+**Be concise:**
+- 1-2 sentences max
+- Don't repeat obvious information from commit message
+- Add value, don't just restate
+
+**Preserve changelog structure:**
+- Don't change version numbers, dates, or commit links
+- Don't reorganize sections
+- Don't remove entries (even if trivial)
+
+**Match style:**
+- Use same tone as existing entries
+- Follow Keep a Changelog format if present
+- Consistent formatting (blockquotes for annotations)
+
+## Critical Requirements
+
+**Context gathering:**
+- MUST try git diffs first, then commit messages, then PR descriptions
+- MUST use AskUserQuestion if all sources are unclear
+- DON'T fabricate or guess at changes
+
+**Annotations:**
+- MUST focus on user-facing impact
+- MUST be concise (1-2 sentences)
+- MUST NOT repeat implementation details already in diff
+
+**Structure preservation:**
+- MUST keep all original entries intact
+- MUST preserve commit SHA links
+- MUST maintain version structure and dates
+- MUST use blockquote format (`>`) for annotations
+
+**Approval:**
+- MUST show diff before applying changes
+- MUST explain how many entries were annotated
+- DON'T apply changes without user seeing what will change
+
+Your goal is to make auto-generated changelogs more useful by adding context about what changed from a user's perspective, while preserving the automated structure and commit traceability.

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