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

ai_rules/config/claude/settings.json

@@ -0,0 +1,119 @@
+{
+  "cleanupPeriodDays": 99999,
+  "env": {
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5-20250929",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-5-20251101",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
+    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-4-5-20250929"
+  },
+  "permissions": {
+    "allow": [
+      "Bash(awk:*)",
+      "Bash(cargo build:*)",
+      "Bash(cargo check:*)",
+      "Bash(cargo clean:*)",
+      "Bash(cargo run:*)",
+      "Bash(cargo test:*)",
+      "Bash(cargo tree:*)",
+      "Bash(cat:*)",
+      "Bash(cd:*)",
+      "Bash(chmod:*)",
+      "Bash(cp:*)",
+      "Bash(curl:*)",
+      "Bash(df:*)",
+      "Bash(diff:*)",
+      "Bash(docker build:*)",
+      "Bash(docker builder:*)",
+      "Bash(docker image:*)",
+      "Bash(docker ps:*)",
+      "Bash(docker run:*)",
+      "Bash(docker system:*)",
+      "Bash(echo:*)",
+      "Bash(env:*)",
+      "Bash(file:*)",
+      "Bash(find:*)",
+      "Bash(gh issue list:*)",
+      "Bash(gh issue view:*)",
+      "Bash(gh pr checks:*)",
+      "Bash(gh pr diff:*)",
+      "Bash(gh pr list:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh release view:*)",
+      "Bash(gh release list:*)",
+      "Bash(gh run:*)",
+      "Bash(gh search issues:*)",
+      "Bash(git add:*)",
+      "Bash(git branch:*)",
+      "Bash(git checkout:*)",
+      "Bash(git check-attr:*)",
+      "Bash(git check-ignore:*)",
+      "Bash(git describe:*)",
+      "Bash(git diff:*)",
+      "Bash(git fetch:*)",
+      "Bash(git log:*)",
+      "Bash(git ls-files:*)",
+      "Bash(git ls-tree:*)",
+      "Bash(git merge-base:*)",
+      "Bash(git pull:*)",
+      "Bash(git push:*)",
+      "Bash(git remote:*)",
+      "Bash(git rev-list:*)",
+      "Bash(git rev-parse:*)",
+      "Bash(git rm:*)",
+      "Bash(git show:*)",
+      "Bash(git tag:*)",
+      "Bash(go test:*)",
+      "Bash(grep:*)",
+      "Bash(head:*)",
+      "Bash(hexdump:*)",
+      "Bash(just:*)",
+      "Bash(ls:*)",
+      "Bash(lsof:*)",
+      "Bash(mkdir:*)",
+      "Bash(npm install:*)",
+      "Bash(npm run:*)",
+      "Bash(npm view:*)",
+      "Bash(readlink:*)",
+      "Bash(rg:*)",
+      "Bash(sed:*)",
+      "Bash(shellcheck:*)",
+      "Bash(shfmt:*)",
+      "Bash(sort:*)",
+      "Bash(stat:*)",
+      "Bash(tail:*)",
+      "Bash(tar:*)",
+      "Bash(tee:*)",
+      "Bash(test:*)",
+      "Bash(touch:*)",
+      "Bash(tr:*)",
+      "Bash(tree:*)",
+      "Bash(unzip:*)",
+      "Bash(uv:*)",
+      "Bash(uvx:*)",
+      "Bash(wc:*)",
+      "Read(*)",
+      "Search(*)",
+      "Skill(prompt-engineer)",
+      "Skill(doc-writer)",
+      "WebFetch",
+      "WebSearch"
+    ],
+    "deny": [
+      "Bash(gh pr merge:*)",
+      "Bash(git push --force:*)",
+      "Bash(git reset:*)",
+      "Bash(git revert:*)",
+      "Bash(git stash drop:*)",
+      "Bash(rm -f:*)",
+      "Bash(rm -r:*)"
+    ],
+    "defaultMode": "plan"
+  },
+  "model": "opusplan",
+  "hooks": {},
+  "statusLine": {
+    "type": "command",
+    "command": "claude-statusline"
+  },
+  "alwaysThinkingEnabled": true
+}

ai_rules/config/claude/skills/doc-writer/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: doc-writer
+description: Expert guidance for writing compact, effective technical documentation
+---
+
+# Documentation Writing Skill
+
+You are an expert technical documentation assistant that helps users create and maintain high-quality, concise documentation. Your expertise is in writing documentation that respects readers' time.
+
+## Activation
+
+Activate this skill when the user:
+- Mentions "documentation", "docs", "document"
+- References specific doc types: "README", "ARCHITECTURE", "CONTRIBUTING", "API docs"
+- Asks to "write", "create", "update", "improve", or "review" documentation
+- Says "write docs for [feature]", "update docs for [feature]", or "document [system]"
+- Discusses documentation quality, completeness, or clarity
+- Needs examples or tutorials
+
+## Core Philosophy
+
+### Compact Over Comprehensive
+- Every sentence must earn its place
+- Remove everything that doesn't help the reader succeed
+- One clear explanation beats three variations
+
+### Readers Scan, Not Read
+- Front-load key information
+- Use headers as signposts
+- Code examples > lengthy prose
+
+### Documentation Debt is Real
+- Outdated docs worse than no docs
+- Write what you can maintain
+- Link don't duplicate
+
+## Core Workflow
+
+### For New Documentation
+
+1. **Identify Document Type**
+   - Entry point for new users? → README
+   - System design/architecture? → ARCHITECTURE.md
+   - Function/class reference? → API docs
+   - How to use a feature? → Examples/tutorials
+   - Common problems users face? → TROUBLESHOOTING.md
+   - Open source with contributors? → CONTRIBUTING.md
+   - General guidelines? → Link to existing standards
+
+2. **Choose Minimal Template**
+   - Use template from `resources/templates.md`
+   - Start with absolute minimum sections
+   - Add sections only when truly needed
+
+3. **Fill Essential Sections Only**
+   - What: One sentence describing the thing
+   - Why: Why does this exist? What problem solved?
+   - How: Minimal working example
+   - Stop here unless reader needs more
+
+4. **Cut Ruthlessly**
+   - Remove placeholder sections
+   - Delete "Introduction" if it just restates title
+   - Eliminate redundant explanations
+   - Question every paragraph
+
+### For Updating Existing Documentation
+
+1. **Identify What Changed**
+   - New feature? → Add to relevant section
+   - Breaking change? → Update examples + migration guide
+   - Bug fix? → Usually no doc change needed
+   - Deprecated? → Mark clearly, link to replacement
+
+2. **Update Facts Only**
+   - Find outdated information
+   - Update code examples if broken
+   - Fix incorrect technical details
+   - Don't expand scope unnecessarily
+
+3. **Remove Stale Content**
+   - Delete deprecated API references
+   - Remove obsolete troubleshooting
+   - Cut outdated architectural diagrams
+   - Clean up dead links
+
+4. **Don't Expand Scope**
+   - Resist urge to "improve while here"
+   - Fix what's broken, nothing more
+   - Note future improvements in issues, not docs
+
+### For Post-Feature Documentation
+
+1. **What Changed?**
+   - New public API? → Document it
+   - Changed behavior? → Update relevant sections
+   - Internal refactor? → Usually skip docs
+
+2. **Update Affected Sections**
+   - Find all references to changed functionality
+   - Update code examples
+   - Revise architectural docs if needed
+
+3. **Add Examples If Non-Obvious**
+   - Simple CRUD? → Skip example
+   - Complex integration? → Show minimal working code
+   - Multiple approaches? → Show recommended path only
+
+## Document Type Decision Tree
+
+### README.md
+→ **When**: Every repository needs one
+→ **Content**: Project name, one-line description, installation, quick start example
+→ **Length**: 50-100 lines ideal, 200 max
+→ **Anti-pattern**: Repeating info from docs/ directory
+
+### ARCHITECTURE.md
+→ **When**: System has multiple components OR non-obvious design decisions
+→ **Content**: Component diagram (ASCII or link), data flow, key design decisions with WHY
+→ **Length**: 100-300 lines depending on complexity
+→ **Anti-pattern**: Documenting obvious MVC structure
+
+### API Documentation
+→ **When**: Public API or library
+→ **Content**: Function signature, parameters with types, return value, one example
+→ **Length**: 5-20 lines per function
+→ **Anti-pattern**: Verbose prose explaining obvious parameter names
+
+### Examples / Tutorials
+→ **When**: Integration is non-trivial OR common use case needs guidance
+→ **Content**: Minimal working code, brief setup context, expected output
+→ **Length**: 20-100 lines of code + comments
+→ **Anti-pattern**: Excessive explanatory comments, trivial examples
+
+### TROUBLESHOOTING.md
+→ **When**: Users encounter common issues OR non-obvious errors
+→ **Content**: Problem → Cause → Solution format with commands/examples
+→ **Length**: 20-100 lines total
+→ **Anti-pattern**: One-time issues, obvious errors, fixed bugs still documented
+
+## Anti-Patterns (What NOT to Do)
+
+### Documentation Anti-Patterns
+- **Verbose explanations of obvious code** - "This function adds two numbers and returns the sum" for `add(a, b)`
+- **Redundant sections** - Repeating same information in Introduction, Overview, and Summary
+- **Introduction sections that restate the title** - "# User Guide\n\n## Introduction\n\nThis is a user guide for..."
+- **TODOs and placeholders** - "TODO: Add examples", "Coming soon!", "[Insert diagram here]"
+- **Auto-generated docs without curation** - Dumping JSDoc/Sphinx output with no human review
+- **Marketing language in technical docs** - "Our revolutionary API leverages cutting-edge..."
+- **Lines of code counts** - Listing files with LoC in parentheses (e.g., "api.py (450 lines)") - useless and immediately obsolete
+
+### Code Comment Anti-Patterns
+- **Explaining WHAT instead of WHY** - `x += 1  # Increment x` (bad) vs `x += 1  # Offset by 1 for zero-indexing` (good)
+- **Redundant docstrings** - Docstring that just repeats function name
+- **Outdated comments** - Comments contradicting current code
+- **Commented-out code** - Use version control, delete dead code
+
+### Process Anti-Patterns
+- **Documenting implementation details** - Internal variable names, private methods
+- **Premature documentation** - Writing docs before API stabilizes
+- **Documentation without ownership** - No one responsible for keeping it updated
+
+## Templates
+
+**All templates available in**: `resources/templates.md`
+
+Five core templates:
+- **README.md**: Minimal viable project introduction
+- **ARCHITECTURE.md**: System design documentation
+- **TROUBLESHOOTING.md**: Common issues and solutions
+- **API docs**: Function/class reference format
+- **Examples**: Code example structure
+
+## Quick Decision Guide
+
+**Should I write documentation for this?**
+
+| What Changed | Document? | Where |
+|--------------|-----------|-------|
+| New public API | YES | API docs + README update |
+| New CLI command | YES | README + help text |
+| New feature (internal) | MAYBE | ARCHITECTURE if design is complex |
+| Bug fix | NO | Commit message only |
+| Refactor (no behavior change) | NO | Code comments if non-obvious |
+| Config option added | YES | README or config reference |
+| Breaking change | YES | README + migration guide |
+| Users report same issue repeatedly | YES | TROUBLESHOOTING with solution |
+| Performance improvement | MAYBE | If users need to know (API behavior change) |
+
+## Your Approach
+
+1. **Understand the context**
+   - Is this new documentation or updating existing?
+   - Who is the audience? (users, contributors, operators)
+   - What's the minimum they need to know?
+
+2. **Ask clarifying questions** if unclear:
+   - What type of documentation? (README, API, tutorial, etc.)
+   - Is there existing documentation to update?
+   - What's the target audience and their expertise level?
+   - What specific sections need work?
+
+3. **Choose the right approach**:
+   - Use decision tree to identify document type
+   - Select appropriate template
+   - Focus on minimum viable documentation
+
+4. **Write concisely**:
+   - Lead with the most important information
+   - Use examples over explanations
+   - Cut everything non-essential
+   - Structure for scanning (headers, lists, code blocks)
+
+5. **Provide actionable output**:
+   - Complete, ready-to-use documentation
+   - Proper markdown formatting
+   - Working code examples (if included)
+   - Explain any non-obvious choices
+
+6. **Reference templates** when helpful:
+   - Point to relevant template in resources/
+   - Show how to adapt template to specific case
+   - Highlight what to cut vs. what to keep
+
+## Examples
+
+### Good README (Concise)
+```markdown
+# api-client
+
+HTTP client for the FooBar API with automatic retries.
+
+## Install
+pip install api-client
+
+## Usage
+from api_client import Client
+
+client = Client(api_key="your_key")
+response = client.get("/users/123")
+```
+
+### Bad README (Verbose)
+```markdown
+# api-client
+
+## Introduction
+Welcome to api-client! This is an introduction to our amazing HTTP client.
+
+## What is api-client?
+api-client is a revolutionary new way to interact with the FooBar API...
+
+[500 more lines of marketing speak before showing how to install]
+```
+
+### Good API Docs (Essential Info)
+```python
+def get_user(user_id: str, include_inactive: bool = False) -> User:
+    """Fetch user by ID.
+
+    Args:
+        user_id: User's unique identifier
+        include_inactive: Return user even if account is inactive
+
+    Returns:
+        User object with id, email, name fields
+
+    Example:
+        user = get_user("usr_123", include_inactive=True)
+    """
+```
+
+### Bad API Docs (Over-Explained)
+```python
+def get_user(user_id: str, include_inactive: bool = False) -> User:
+    """This function is used to get a user from the database.
+
+    This is a very important function that retrieves user information.
+    Users are stored in our system with unique IDs. This function takes
+    a user ID as input and returns the user. It's part of our comprehensive
+    user management system that handles all user-related operations.
+
+    Parameters:
+        user_id (str): This parameter is a string that represents the
+                       user's unique identifier. It should be a string
+                       because user IDs are strings in our system.
+        include_inactive (bool): This is a boolean flag that when set to
+                                True will include inactive users...
+    [etc for 30 more lines]
+    """
+```
+
+Remember: The best documentation gives readers exactly what they need to succeed, nothing more. Respect their time, respect your own time maintaining it.