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

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.

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

@@ -0,0 +1,244 @@
+---
+description: Audit and optimize test suite by removing trivial tests and consolidating valuable ones
+allowed-tools: AskUserQuestion, Bash, Edit, Glob, Grep, Read, TodoWrite, Write
+model: inherit
+---
+
+## Context
+
+- Project root: !`git rev-parse --show-toplevel 2>/dev/null || pwd`
+- Test framework: !`[ -f package.json ] && grep -E '"(test|jest|mocha|vitest)"' package.json | head -1 || [ -f pytest.ini ] && echo "pytest" || [ -f go.mod ] && echo "go test" || echo "unknown"`
+- Test file count: !`find . -type f \( -name "*test*" -o -name "*spec*" \) 2>/dev/null | wc -l`
+- Test execution time: !`[ -f package.json ] && npm test -- --listTests 2>/dev/null | wc -l || echo "N/A"`
+- Coverage config: !`[ -f .coveragerc ] && echo "Python coverage" || [ -f jest.config.js ] && echo "Jest coverage" || [ -f .nycrc ] && echo "NYC coverage" || echo "No coverage config"`
+- Recent test failures: !`git log --grep="test\|fix" --oneline -10 2>/dev/null | head -5`
+
+# Test Suite Optimization
+
+Perform comprehensive audit of all tests in the codebase to identify opportunities for consolidation, refactoring, or removal. Focus on maximizing test value while minimizing maintenance burden.
+
+## Test Value Framework
+
+Classify each test using this hierarchy:
+
+**1. Critical (MUST KEEP)**
+- Business logic with multiple code paths
+- Security boundaries (authentication, authorization, input validation)
+- Data integrity checks (transactions, constraints)
+- User-facing functionality that directly impacts users
+- Integration points with external systems
+- Financial calculations or regulatory compliance logic
+
+**2. Valuable (KEEP)**
+- Error handling for external dependencies
+- Edge cases with production impact history
+- State transitions in complex workflows
+- API contract validation
+- Performance regression detection
+- Cross-cutting concerns (logging, monitoring)
+
+**3. Questionable (EVALUATE)**
+- Simple getters/setters with no logic
+- Framework functionality already tested by framework
+- Tests with >80% mocking (testing mocks, not code)
+- Overly coupled to implementation details
+- Duplicate coverage of same behavior
+
+**4. Trivial (REMOVE)**
+- Testing language features (e.g., "JavaScript can add numbers")
+- Testing third-party libraries (e.g., "axios makes HTTP requests")
+- Tests that never fail (always pass regardless of implementation)
+- Generated tests with no assertions
+- Tests verifying constants or configuration values
+
+## Systematic Audit Process
+
+### Phase 1: Inventory
+
+**Review metrics from Context above:**
+- Test framework, file count, and coverage config are pre-loaded
+- Measure execution time using the detected test framework
+- Run coverage report if coverage config exists
+
+**Categorize tests:**
+- Unit tests (test individual functions/classes)
+- Integration tests (test multiple components together)
+- E2E tests (test full user workflows)
+- Performance tests
+- Contract/API tests
+
+### Phase 2: Analysis
+
+Apply decision framework to each test. For every test, ask:
+
+**1. What business rule does this validate?**
+- If answer is "none" or unclear → REMOVE
+
+**2. Has this test ever caught a real bug?**
+- Check git history for test failures in CI
+- If always passes → QUESTIONABLE
+
+**3. Does this test document important behavior?**
+- Would removing it make system behavior unclear? → KEEP
+- Is it redundant with other tests? → CONSOLIDATE
+
+**4. Would removing this test increase risk?**
+- High risk area (payments, auth, data loss) → KEEP
+- Low risk area (UI formatting, logs) → EVALUATE
+
+**Identify patterns:**
+- Repeated test setup → Consolidate into shared fixtures
+- Multiple tests for same behavior → Merge into single comprehensive test
+- Tests with zero assertions → Remove
+- Tests that mock everything → Reconsider if testing anything real
+
+### Phase 3: Optimization Actions
+
+**For REMOVE candidates:**
+1. Verify test provides no unique value
+2. Confirm other tests cover the behavior (if any)
+3. Delete test and unused fixtures/helpers
+4. Run full test suite to confirm no gaps
+
+**For CONSOLIDATE candidates:**
+1. Identify overlapping test coverage
+2. Create single comprehensive test covering all cases
+3. Remove individual redundant tests
+4. Verify consolidated test provides same coverage
+
+**For REFACTOR candidates:**
+1. Extract repeated setup to shared fixtures
+2. Replace implementation testing with behavior testing
+3. Reduce mocking to essential external dependencies only
+4. Simplify assertions to focus on outcomes, not internals
+
+**For KEEP candidates:**
+1. Verify test is maintainable and clear
+2. Ensure test runs quickly (flag slow tests >1s)
+3. Check test has clear failure messages
+4. Document why test is important if non-obvious
+
+### Phase 4: Execute Changes
+
+**Process systematically:**
+1. Start with obvious REMOVE candidates (fastest wins)
+2. Consolidate related tests (reduce duplication)
+3. Refactor questionable tests (improve quality)
+4. Run tests after each batch of changes
+5. Monitor coverage to ensure no gaps introduced
+
+**Track progress:**
+- Count tests before/after
+- Measure execution time improvement
+- Verify coverage maintained or improved
+- Document any intentional coverage gaps
+
+### Phase 5: Validation
+
+**Run comprehensive checks:**
+```bash
+# Full test suite
+npm test
+
+# Coverage report
+npm run coverage
+
+# Linter (might catch unused imports/fixtures)
+npm run lint
+
+# Type checking (if applicable)
+npm run type-check
+```
+
+**Verify metrics:**
+- Test count reduced by removing trivial tests
+- Execution time improved (target: 20-30% faster)
+- Coverage of critical paths maintained (≥80% for business logic)
+- No new test failures introduced
+
+## Decision Criteria Examples
+
+**Remove:**
+```python
+# Testing Python language feature
+def test_list_append():
+    lst = []
+    lst.append(1)
+    assert len(lst) == 1  # Python lists work!
+
+# Testing framework functionality
+def test_mock_called():
+    mock = Mock()
+    mock()
+    assert mock.called  # Mocks work!
+```
+
+**Keep:**
+```python
+# Testing business logic
+def test_discount_calculation_with_coupon():
+    cart = Cart(items=[Item(price=100)])
+    cart.apply_coupon("SAVE20")
+    assert cart.total() == 80  # Business rule: 20% discount
+
+# Testing security boundary
+def test_unauthorized_access_denied():
+    response = api.delete("/user/123", auth=None)
+    assert response.status == 403  # Security: require auth
+```
+
+**Consolidate:**
+```python
+# Before: 3 separate tests
+def test_user_creation_with_valid_email(): ...
+def test_user_creation_with_name(): ...
+def test_user_creation_stores_timestamp(): ...
+
+# After: 1 comprehensive test
+def test_user_creation_with_all_fields():
+    user = create_user(email="test@example.com", name="Test")
+    assert user.email == "test@example.com"
+    assert user.name == "Test"
+    assert user.created_at is not None
+```
+
+## Common Pitfalls to Avoid
+
+- **Don't remove tests that caught bugs in the past**: Check git history
+- **Don't reduce coverage of critical paths**: Maintain ≥80% for business logic
+- **Don't remove tests just because they're slow**: Optimize instead
+- **Don't delete edge case tests**: They often prevent regression
+- **Don't remove integration tests in favor of unit tests**: Both have value
+
+## Success Metrics
+
+After optimization, verify:
+✓ Test suite runs 20-30% faster
+✓ Zero trivial tests remain (language features, framework tests)
+✓ Critical path coverage maintained (≥80%)
+✓ All remaining tests have clear purpose
+✓ Test failures provide actionable error messages
+✓ Reduced maintenance burden (fewer brittle tests)
+
+## Reporting
+
+Provide summary after completion:
+```
+Test Optimization Complete
+
+Metrics:
+- Tests removed: X (Y% reduction)
+- Tests consolidated: Z groups
+- Execution time: Before Xs → After Ys (Z% improvement)
+- Coverage: Maintained at N%
+
+Categories removed:
+- Trivial tests: X
+- Framework tests: Y
+- Implementation-only tests: Z
+
+All tests passing: ✓
+Coverage maintained: ✓
+```
+
+Your goal is to create a lean, valuable test suite that focuses on critical business logic and system integration while removing tests that provide no real protection against bugs.