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

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.

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

@@ -0,0 +1,324 @@
+---
+description: Automatically updates project documentation by analyzing recent commits and detecting changes
+allowed-tools: AskUserQuestion, Bash, Edit, Glob, Grep, Read, TodoWrite, Write
+model: sonnet
+---
+
+## Context
+
+- Project root: !`git rev-parse --show-toplevel 2>/dev/null || pwd`
+- Current branch: !`git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "NO_BRANCH"`
+- Recent commits: !`git log --oneline -10 2>/dev/null || echo "NO_COMMITS"`
+- Documentation files: !`find . -maxdepth 3 -type f \( -name "README*" -o -name "ARCHITECTURE*" -o -name "CONTRIBUTING*" \) 2>/dev/null | head -10`
+- Last commit message: !`git log -1 --format="%s" 2>/dev/null || echo "NO_COMMITS"`
+
+# Update Project Documentation
+
+**Usage:**
+- `/update-docs` - Analyze recent commits and update all relevant documentation
+
+Automatically updates project documentation after code changes by intelligently analyzing recent commits, detecting what changed, and updating relevant documentation files while preserving existing style and structure.
+
+## Five-Phase Methodology
+
+### Phase 1: Change Analysis & Scope Detection
+
+**Explore recent commit history:**
+1. Review "Recent commits" from Context above
+2. Identify the most recent logical grouping of related changes
+
+**Commit Grouping Heuristics:**
+
+Use these indicators to determine which commits form a cohesive logical unit:
+
+**Related commits (include in same group):**
+- Commit messages with same feature prefix (e.g., "add auth flow", "fix auth bug", "test auth")
+- High file overlap (>50% of changed files appear in multiple commits)
+- Temporal proximity (commits within same day or few hours)
+- Sequential references to same feature, issue number, or component
+
+**Separate logical units (stop grouping):**
+- Different feature/component prefixes in messages
+- No file overlap between commits
+- Large time gaps (days or weeks apart)
+- Clearly distinct functional areas
+
+**Example decision:**
+```
+Commits:
+1. "add config set-default-profile command" (1h ago, modified: cli.py, config.py)
+2. "add config file persistence" (50min ago, modified: config.py, README.md)
+3. "add tests for default profile" (45min ago, modified: test_config.py)
+4. "fix typo in help text" (40min ago, modified: cli.py)
+5. "update dependencies" (2 days ago, modified: requirements.txt)
+
+→ Group commits 1-4 as "default profile feature"
+→ Exclude commit 5 (different feature, time gap)
+```
+
+**Analyze combined changes:**
+
+Once scope determined, get full diff for the commit group:
+```bash
+# For single commit
+git show <commit-hash>
+
+# For multiple commits (e.g., last 4)
+git log -4 --format="%h %s"
+git diff HEAD~4..HEAD
+```
+
+**Detect change patterns using this table:**
+
+| Pattern in Code | Feature Type | Documentation Impact |
+|-----------------|--------------|---------------------|
+| `@click.command()`, `@app.command()` | CLI command | CLI reference, examples |
+| `argparse.add_argument()`, `add_parser()` | CLI argument | CLI reference, usage |
+| `@app.route()`, `@router.get()` | API endpoint | API reference, integration guide |
+| `FastAPI()`, `APIRouter()` | API changes | API docs, OpenAPI spec |
+| Function signature changed | Breaking change | Migration guide, changelog |
+| New YAML/TOML/JSON keys in schema | Configuration | Config reference, examples |
+| `deprecated`, `@deprecated` | Deprecation | Deprecation notice, migration path |
+| New class in public API | New feature | API reference, examples |
+| Removed public function/class | Breaking change | Migration guide, what to use instead |
+
+**Parse commit messages for type:**
+- `feat:`, "add", "implement", "create" → New feature
+- `fix:`, "bug", "resolve", "patch" → Bug fix
+- `refactor:`, "restructure", "clean up" → Refactoring
+- `breaking:`, "BREAKING CHANGE:" → Breaking change
+- `docs:` → Documentation only (skip updating docs for docs changes)
+
+### Phase 2: Documentation Discovery
+
+**Auto-discover documentation files:**
+
+Search for documentation using these patterns (prioritized):
+
+1. **Root-level user docs** (highest priority):
+   - `README.md`, `README.rst`, `README.txt`
+   - `GETTING_STARTED.md`, `QUICKSTART.md`
+
+2. **Root-level developer docs**:
+   - `ARCHITECTURE.md`, `DESIGN.md`
+   - `CONTRIBUTING.md`, `DEVELOPMENT.md`
+   - `CHANGELOG.md`, `CHANGES.md`
+
+3. **Documentation directories**:
+   - `docs/*.md`, `doc/*.md`
+   - `docs/api/*.md`, `docs/cli/*.md`
+   - `.github/*.md`
+
+4. **Project-specific** (if they exist):
+   - `PLAN*.md` (but check if used for development planning)
+   - Any files mentioned in commit messages
+
+**Check Context above for "Documentation files"** - these are pre-discovered.
+
+**Prioritize by documentation type:**
+1. User-facing (README, getting started) - most critical
+2. CLI/API reference sections - document interfaces
+3. Developer docs (ARCHITECTURE, CONTRIBUTING) - technical details
+4. Examples and tutorials - illustrate usage
+
+### Phase 3: Impact Analysis
+
+**Map detected changes to documentation sections:**
+
+Use this decision table to determine what needs updating:
+
+| Change Type | README | ARCHITECTURE | CONTRIBUTING | docs/ | Priority |
+|-------------|--------|--------------|--------------|-------|----------|
+| New CLI command | CLI reference, Quick start | - | - | CLI guide | CRITICAL |
+| New CLI argument | CLI reference, Usage | - | - | CLI guide | CRITICAL |
+| New API endpoint | API overview | API architecture | - | API reference | CRITICAL |
+| Breaking change | Upgrade notes, Breaking changes section | System changes | - | Migration guide | CRITICAL |
+| New config option | Configuration section | Config system | - | Config reference | IMPORTANT |
+| Deprecated feature | Deprecation notice | - | - | Migration guide | IMPORTANT |
+| Performance improvement | Changelog, Performance section | Implementation | - | - | IMPORTANT |
+| Bug fix (behavior change) | Changelog | - | - | - | IMPORTANT |
+| Bug fix (no behavior change) | Changelog only | - | - | - | SKIP |
+| Internal refactor | - | - | - | - | SKIP |
+
+**Build update plan:**
+1. List all documentation files needing updates
+2. For each file, identify specific sections to modify
+3. Prioritize by CRITICAL → IMPORTANT → SKIP
+
+### Phase 4: Style-Preserving Documentation Updates
+
+**Before making any changes:**
+
+For each documentation file to update:
+
+1. **Analyze existing style** (read first 500 lines):
+   - Tone: Formal/technical vs casual/accessible
+   - Structure: Heading levels (# ## ###), section organization
+   - Formatting: Code block language tags, list style (-, *, 1.), table usage
+   - Example patterns: Inline examples vs separate files, comment style in code blocks
+
+2. **Identify update strategy**:
+   - **Insert**: Add new section for new feature (preserve structure)
+   - **Update**: Modify existing section (match formatting)
+   - **Append**: Add to list (match list style: -, *, or numbered)
+   - **Replace**: Outdated info (preserve tone and format)
+
+**Make minimal invasive edits:**
+
+For each update, use the Edit tool to:
+- Insert new content into existing sections (don't restructure)
+- Update examples to match new behavior (preserve example format)
+- Preserve cross-references and internal links
+- Match existing writing style, tone, and voice
+- Keep same heading hierarchy and conventions
+
+**Examples of style matching:**
+
+```markdown
+# Existing style (casual, emoji, short sentences)
+## Commands
+
+Use these commands:
+- 🚀 `app start` - Start the app
+- 🛑 `app stop` - Stop it
+
+# Match this style when adding:
+- ⚙️ `app config` - Configure settings
+```
+
+```markdown
+# Existing style (formal, technical, detailed)
+### Command Reference
+
+#### start
+Initializes the application server and begins listening for incoming requests on the configured port (default: 8080).
+
+# Match this style when adding:
+#### configure
+Modifies application configuration settings, persisting changes to the local configuration file (~/.app/config.toml). Accepts key-value pairs via command-line arguments.
+```
+
+**What NOT to do:**
+- Don't add features not requested or clearly necessary
+- Don't restructure existing documentation
+- Don't change the tone (formal → casual or vice versa)
+- Don't add verbose descriptions if existing docs are concise
+- Don't remove existing content unless it's deprecated/wrong
+
+### Phase 5: Verification & Summary
+
+**Verify completeness:**
+
+After all updates, check:
+- [ ] All significant changes from Phase 1 are documented
+- [ ] Deprecated features removed or marked as deprecated
+- [ ] All examples updated to match new behavior
+- [ ] Cross-references still valid (no broken links to removed sections)
+- [ ] Consistent style maintained throughout each file
+- [ ] No orphaned sections (sections referencing removed features)
+
+**Generate summary report:**
+
+Provide user with:
+```
+Documentation Updated - Summary
+
+Scope Analyzed:
+- Commits: <N> commits from <oldest> to <newest>
+- Feature: <brief description of logical grouping>
+- Changes detected: <list of key changes>
+
+Files Updated:
+- <file1>: <what was updated>
+- <file2>: <what was updated>
+
+Verification:
+✓ All new features documented
+✓ Examples updated
+✓ Style preserved
+✓ Cross-references valid
+
+Review changes: git diff
+```
+
+## Prioritization Framework
+
+Use this framework to decide what to document:
+
+**Critical (Must Document)**:
+- New user-facing features (CLI commands, API endpoints)
+- Breaking changes requiring migration
+- Security-related changes (authentication, authorization, data handling)
+- Changed behavior for existing features
+- New required configuration
+
+**Important (Should Document)**:
+- New optional configuration
+- Performance improvements with visible user impact
+- Behavior-changing bug fixes (even if fixing a bug)
+- New developer-facing features (build tools, dev commands)
+- Enhanced error messages that users will see
+
+**Skip (Don't Document)**:
+- Internal refactoring with no external impact
+- Test additions or modifications
+- Code style or formatting changes
+- Dependency updates (unless they cause breaking changes)
+- Trivial bug fixes (typos, off-by-one with no behavior change)
+- Documentation-only changes (don't update docs for docs commits)
+
+## Critical Requirements
+
+**Change Detection:**
+- Explore recent commits to identify logical grouping (not just HEAD)
+- Use commit message patterns, file overlap, and timestamps
+- Make autonomous decision about scope
+- Analyze combined diff for the identified group
+
+**Documentation Discovery:**
+- Auto-discover using intelligent patterns (README*, ARCHITECTURE*, docs/)
+- Check pre-executed Context for available files
+- Prioritize user-facing docs > API/CLI reference > developer docs
+
+**Style Preservation:**
+- **ALWAYS** analyze existing style before updating
+- **MUST** match tone (formal vs casual)
+- **MUST** preserve formatting (code blocks, lists, tables)
+- **MUST** maintain heading hierarchy
+- Make minimal invasive changes only
+
+**Update Strategy:**
+- Use Edit tool with exact string matching
+- Insert into existing sections (don't restructure)
+- Update examples in-place (preserve format)
+- Remove deprecated content explicitly
+
+**Accuracy:**
+- Base all updates on actual code changes (git diff)
+- Don't guess or fabricate features
+- Include concrete technical details (function names, command syntax)
+- Verify examples match actual implementation
+
+**Completeness:**
+- Document all CRITICAL changes (user-facing features, breaking changes)
+- Document IMPORTANT changes (config, behavior changes)
+- Skip internal changes with no external impact
+- Generate verification summary for user
+
+**DO:**
+- Analyze commit history to find logical groupings
+- Detect changes using pattern matching table
+- Preserve existing documentation style and tone
+- Make minimal edits (insert into existing structure)
+- Update all examples affected by changes
+- Report what was changed in final summary
+
+**DO NOT:**
+- Rigidly analyze only HEAD commit (explore recent history)
+- Restructure existing documentation
+- Change tone or writing style
+- Add features or improvements beyond what changed
+- Skip documenting breaking changes or new user features
+- Remove content without confirming it's deprecated
+
+Your goal is to keep documentation accurate and up-to-date with code changes while respecting project conventions and minimizing disruption to existing docs structure.

ai_rules/config/claude/hooks/subagentStop.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""SubagentStop Hook - Block premature exits and ensure task completion."""
+
+import json
+import sys
+
+from pathlib import Path
+
+
+def main() -> None:
+    try:
+        event_data = json.loads(sys.stdin.read())
+        transcript_path = event_data.get("transcript_path", "")
+    except Exception as e:
+        print(f"Error loading event data: {e}", file=sys.stderr)
+        print(json.dumps({"decision": "approve"}))
+        return
+
+    if not transcript_path:
+        print(json.dumps({"decision": "approve"}))
+        return
+
+    transcript_file = Path(transcript_path).expanduser()
+    if not transcript_file.exists():
+        print(json.dumps({"decision": "approve"}))
+        return
+
+    pending_todos = []
+    all_assistant_text = ""
+
+    with open(transcript_file) as f:
+        for line in f:
+            try:
+                msg = json.loads(line)
+
+                if "message" in msg:
+                    msg = msg["message"]
+
+                if msg.get("role") == "assistant":
+                    content = msg.get("content", [])
+                    if isinstance(content, list):
+                        for item in content:
+                            if (
+                                item.get("type") == "tool_use"
+                                and item.get("name") == "TodoWrite"
+                            ):
+                                todos = item.get("input", {}).get("todos", [])
+                                pending_todos = [
+                                    t["content"]
+                                    for t in todos
+                                    if t.get("status") == "pending"
+                                ]
+                            elif item.get("type") == "text":
+                                all_assistant_text += item.get("text", "") + " "
+            except Exception as e:
+                print(f"Error parsing message: {e}", file=sys.stderr)
+                continue
+
+    last_assistant_text = all_assistant_text[-2000:]
+
+    if pending_todos:
+        reason = f"INCOMPLETE: {len(pending_todos)} pending tasks:\n"
+        reason += "\n".join(f"- {todo}" for todo in pending_todos)
+        reason += "\n\nContinue working autonomously until ALL tasks complete."
+        print(json.dumps({"decision": "block", "reason": reason}), file=sys.stderr)
+        return
+
+    check_patterns = [
+        "would you like me to",
+        "should i continue",
+        "shall i proceed",
+        "let me check with",
+    ]
+
+    text_lower = last_assistant_text.lower()
+    if any(pattern in text_lower for pattern in check_patterns):
+        print(
+            json.dumps(
+                {
+                    "decision": "block",
+                    "reason": "INCOMPLETE: Do NOT ask for permission. Continue working autonomously.",
+                }
+            ),
+            file=sys.stderr,
+        )
+        return
+
+    print(json.dumps({"decision": "approve"}))
+
+
+if __name__ == "__main__":
+    main()

ai_rules/config/claude/mcps.json

@@ -0,0 +1 @@
+{}