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

ai_rules/config/claude/commands/agents-md.md

@@ -0,0 +1,422 @@
+---
+description: Creates or updates AGENTS.md with comprehensive repo documentation for LLM coding agents
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob, TodoWrite
+model: sonnet
+---
+
+## Context
+
+- Mode: !`[ -f "$(git rev-parse --show-toplevel 2>/dev/null)/AGENTS.md" ] && echo "UPDATE_MODE" || echo "CREATE_MODE"`
+- Git root: !`git rev-parse --show-toplevel 2>/dev/null || echo "NOT_IN_GIT_REPO"`
+- Project name: !`sh -c 'ROOT=$(git rev-parse --show-toplevel 2>/dev/null); [ -z "$ROOT" ] && echo "UNKNOWN" || (cd "$ROOT" && (grep -m1 "name" package.json 2>/dev/null | sed -E "s/.*\"name\"[[:space:]]*:[[:space:]]*\"([^\"]+)\".*/\\1/" || grep -m1 "^name = " pyproject.toml 2>/dev/null | sed -E "s/name = \"([^\"]+)\"/\\1/" || grep -m1 "^name = " Cargo.toml 2>/dev/null | sed -E "s/name = \"([^\"]+)\"/\\1/" || basename "$ROOT"))'`
+- Tooling: !`sh -c 'ROOT=$(git rev-parse --show-toplevel 2>/dev/null); [ -z "$ROOT" ] && echo "NONE" || (cd "$ROOT" && tools=""; [ -f Makefile ] && tools="${tools}make,"; [ -f Justfile ] && tools="${tools}just,"; [ -f package.json ] && tools="${tools}npm,"; [ -f pyproject.toml ] && tools="${tools}python,"; [ -f Cargo.toml ] && tools="${tools}rust,"; [ -f go.mod ] && tools="${tools}go,"; echo "${tools%,}" | sed "s/^$/NONE/")'`
+- Primary language: !`sh -c 'ROOT=$(git rev-parse --show-toplevel 2>/dev/null); [ -z "$ROOT" ] && echo "UNKNOWN" || (cd "$ROOT" && (find . -type f -name "*.py" 2>/dev/null | head -1 | grep -q . && echo "Python") || (find . -type f -name "*.js" -o -name "*.ts" 2>/dev/null | head -1 | grep -q . && echo "JavaScript/TypeScript") || (find . -type f -name "*.rs" 2>/dev/null | head -1 | grep -q . && echo "Rust") || (find . -type f -name "*.go" 2>/dev/null | head -1 | grep -q . && echo "Go") || echo "UNKNOWN")'`
+- Directory: !`pwd`
+
+# Create or Update AGENTS.md
+
+You are creating comprehensive documentation to help LLM coding agents (Claude Code, Cursor, Goose, etc.) work effectively in this repository. Your goal is to discover and document everything an agent needs to understand the project quickly: commands, structure, patterns, gotchas, and conventions.
+
+**Target audience:** LLM coding agents starting fresh on this codebase
+**Output:** AGENTS.md file at repository root with actionable, concise guidance
+
+## Phase 1: Determine Mode
+
+Check the "Mode" field from Context section:
+
+### CREATE_MODE
+AGENTS.md does not exist. You will create a new file from scratch by exploring the repository comprehensively.
+
+**Action:**
+1. Inform user you're creating AGENTS.md for `{Project name}`
+2. Proceed to Phase 2: Deep Exploration
+
+### UPDATE_MODE
+AGENTS.md already exists. You will read the existing file, explore for new information, and merge updates while preserving user customizations.
+
+**Action:**
+1. Inform user you're updating existing AGENTS.md
+2. Read current AGENTS.md file
+3. Proceed to Phase 2: Deep Exploration (focusing on changes/additions)
+
+## Phase 2: Deep Exploration
+
+Explore the repository systematically across all key areas. Use the findings to populate AGENTS.md sections.
+
+### Area 1: Project Identity & Overview
+
+**Goal:** Understand what this project is and what it does
+
+**Explore:**
+1. Read README.md for project description and purpose
+2. Check package files (package.json, pyproject.toml, Cargo.toml, go.mod) for:
+   - Official project name
+   - Version
+   - Description field
+   - Main entry points
+3. Identify if this is a library, CLI tool, web app, service, or other
+
+**Document in:** Opening paragraph (1-2 sentences)
+
+### Area 2: Quick Commands (PRIORITY: Document First)
+
+**Goal:** Find all essential build/test/run commands
+
+**Explore (in priority order):**
+
+1. **Makefile** (if exists):
+   ```bash
+   make help  # Try first
+   grep "^[a-zA-Z]" Makefile | head -20  # List targets
+   ```
+
+2. **Justfile** (if exists):
+   ```bash
+   just --list
+   ```
+
+3. **package.json** (if exists):
+   ```bash
+   cat package.json | grep -A 50 '"scripts"'
+   ```
+
+4. **pyproject.toml** (if exists):
+   - Check for tool commands
+   - Look for `[tool.pytest]`, `[tool.ruff]`, etc.
+   - Common: `pytest`, `ruff check`, `ruff format`, `mypy`
+
+5. **README.md**:
+   - Search for "Getting Started", "Installation", "Development"
+   - Extract command examples
+
+6. **CI/CD config** (.github/workflows/, .gitlab-ci.yml):
+   - Commands used in CI are canonical
+
+**Critical:** Document the ACTUAL commands agents should run:
+- Setup/installation
+- Build/compile
+- Run locally
+- Test (full suite AND file-scoped if different)
+- Lint
+- Format
+- Type check
+
+**Document in:** `## Quick Commands` section (put at top, most important)
+
+### Area 3: Project Structure
+
+**Goal:** Map the directory layout and key modules
+
+**Explore:**
+1. Run `tree -d -L 3` or `ls -R` to see directory structure
+2. Identify key directories:
+   - Source code location (src/, lib/, app/, pkg/)
+   - Test location (tests/, test/, __tests__)
+   - Config location (config/, .config/)
+   - Documentation location (docs/, documentation/)
+3. For each major directory, understand its purpose
+4. Note any monorepo structure (packages/, apps/)
+
+**Document in:** `## Project Structure` section (tree view or annotated list)
+
+### Area 4: Tech Stack
+
+**Goal:** Document specific technologies with versions
+
+**Explore:**
+1. Language and version (from package files or README)
+2. Framework (React, Django, Express, etc.) with major version
+3. Key libraries/dependencies (check package files)
+4. Database (if any - check docker-compose.yml, env examples)
+5. Build tools (Webpack, Vite, esbuild, etc.)
+6. Package manager (npm, yarn, pnpm, uv, cargo, etc.)
+
+**Be specific:** "React 18 with TypeScript" not just "React"
+
+**Document in:** `## Tech Stack` section (bulleted list)
+
+### Area 5: Key Patterns & Conventions
+
+**Goal:** Discover architectural patterns and coding conventions agents must follow
+
+**Explore:**
+1. **Architecture patterns:**
+   - Read 2-3 example source files
+   - Look for: MVC, component patterns, service layers, repository patterns
+   - Check for dependency injection, factories, builders
+
+2. **Code organization conventions:**
+   - Naming patterns (camelCase, snake_case, PascalCase for what?)
+   - File naming (index.js patterns, _private.py, test_*.py)
+   - Import/export patterns
+
+3. **Abstractions to use:**
+   - Base classes (check for `Base*`, `Abstract*`)
+   - Utilities (lib/, utils/, helpers/)
+   - Shared components/modules
+
+4. **Framework-specific patterns:**
+   - React: Hook patterns, component structure
+   - Python: Class decorators, context managers
+   - Go: Interface patterns
+
+**Look at real code examples** to understand conventions
+
+**Document in:** `## Key Patterns` section with brief explanations
+
+### Area 6: Code Style
+
+**Goal:** Document style guidelines NOT covered by linters
+
+**Explore:**
+1. Check for style guide docs (CONTRIBUTING.md, docs/style.md)
+2. Read linter configs (.eslintrc, .ruff.toml, etc.) for what's enforced
+3. Look for patterns in existing code:
+   - Comment style (docstrings, JSDoc, inline)
+   - Function/method length norms
+   - Prefer composition or inheritance?
+
+**Important:**
+- Only document what linters DON'T catch
+- Use code examples over prose when possible
+- Keep brief (linters handle most style)
+
+**Document in:** `## Code Style` section (brief, example-focused)
+
+### Area 7: Testing
+
+**Goal:** How to run tests and where they live
+
+**Explore:**
+1. Test framework (pytest, vitest, jest, go test, cargo test)
+2. Test file locations and naming
+3. Test commands:
+   - Full suite
+   - Single file
+   - Watch mode
+   - Coverage
+4. CI test commands (check .github/workflows/)
+5. Test patterns/conventions (fixtures, mocks, factories)
+
+**Document in:** `## Testing` section
+
+### Area 8: Common Gotchas (HIGH VALUE)
+
+**Goal:** Capture edge cases and traps that cause bugs
+
+**Explore:**
+1. Check comments with "NOTE:", "WARNING:", "FIXME:", "HACK:"
+2. Read existing AGENTS.md, CLAUDE.md, or similar files for gotchas
+3. Look for complex setup (environment vars, secrets, external services)
+4. Check for version-specific issues (e.g., "Must use Python 3.11+")
+5. Review git hooks (.git/hooks/) or pre-commit config
+6. Look for common failure modes in issues/PRs if public repo
+
+**Examples of good gotchas:**
+- "Array path notation: Use `hooks.SubagentStop[0].command` for setting arrays"
+- "Mocking HOME in tests requires patching both environ and Path.home"
+- "Must run migrations before tests: `make migrate-test`"
+
+**Document in:** `## Common Gotchas` section (numbered list)
+
+### Area 9: Key Files by Task
+
+**Goal:** Map tasks to relevant files for faster navigation
+
+**Explore:**
+1. Identify common tasks based on project type:
+   - Add CLI command → which files?
+   - Add API endpoint → which files?
+   - Add new component → which files?
+   - Change config behavior → which files?
+   - Add new agent/plugin → which files?
+
+2. Document the mapping as a table
+
+**Document in:** `## Key Files by Task` section (table format)
+
+## Phase 3: Synthesize Findings
+
+Organize your exploration findings into a well-structured AGENTS.md file.
+
+### Structure Requirements
+
+Use this exact structure (based on research of 2,500+ repositories):
+
+```markdown
+# AGENTS.md
+
+[1-2 sentence project description from Area 1]
+
+## Quick Commands
+
+```bash
+[Commands from Area 2 - setup, build, test, lint, format]
+```
+
+## Project Structure
+
+```
+[Directory tree from Area 3 with annotations]
+```
+
+## Tech Stack
+
+- [Language + version]
+- [Framework + version]
+- [Key libraries]
+- [Build tools]
+- [Database if applicable]
+
+## Key Patterns
+
+[Findings from Area 5 - conventions, abstractions, architectural patterns]
+
+## Code Style
+
+[Findings from Area 6 - brief, with code examples if helpful]
+
+## Testing
+
+```bash
+[Test commands from Area 7]
+```
+
+[Test structure notes]
+
+## Common Gotchas
+
+1. [Gotcha from Area 8]
+2. [Another gotcha]
+...
+
+## Key Files by Task
+
+| Task | Files |
+|------|-------|
+[Mapping from Area 9]
+```
+
+### Quality Standards
+
+**Conciseness:**
+- Target: Under 60 lines total (up to 100 for complex projects)
+- Be specific and actionable, avoid prose
+- One line per item where possible
+- Put commands early (they're used most)
+
+**Specificity:**
+- Include version numbers ("React 18" not "React")
+- Use exact commands with flags (`pytest -v` not "run tests")
+- Reference actual file paths (`src/cli.py` not "CLI file")
+
+**Examples over explanation:**
+```markdown
+# Bad
+"Use meaningful variable names"
+
+# Good
+user_email = get_email()  # Not: e = get_email()
+```
+
+**Boundaries (Optional but valuable):**
+Consider adding a boundaries section if there are critical constraints:
+```markdown
+## Boundaries
+
+**Always:**
+- Run tests before committing
+- Use existing components from src/components/
+
+**Ask first:**
+- Adding new dependencies
+- Database schema changes
+
+**Never:**
+- Commit secrets or credentials
+- Delete existing tests without replacement
+```
+
+## Phase 4: Write or Update File
+
+### For CREATE_MODE
+
+1. **Generate complete AGENTS.md** using structure from Phase 3
+2. Write to: `{Git root}/AGENTS.md`
+3. **Validate:**
+   - File under 100 lines
+   - Commands section is first (after overview)
+   - Specific versions included
+   - All sections have content (no empty placeholders)
+   - No sensitive information included
+
+4. **Report to user:**
+   - File path
+   - Line count
+   - Key sections included
+
+### For UPDATE_MODE
+
+1. **Read existing AGENTS.md** (already done in Phase 1)
+2. **Compare** existing content vs. new findings:
+   - Identify new commands not documented
+   - Identify new gotchas discovered
+   - Check if versions are outdated
+   - Look for structural improvements
+
+3. **Merge strategy:**
+   - **Preserve** user customizations and manual additions
+   - **Add** new findings to appropriate sections
+   - **Update** outdated information (versions, commands)
+   - **Don't remove** user content unless clearly obsolete
+
+4. **Apply updates** using Edit tool:
+   - Match exact old_string with proper formatting
+   - Add new items to lists/sections
+   - Update version numbers where stale
+
+5. **Report to user:**
+   - File path
+   - What was added/updated
+   - Summary of changes (X commands added, Y gotchas updated, etc.)
+
+## Critical Requirements
+
+**File Location:**
+- ALWAYS write to `{Git root}/AGENTS.md`
+- NEVER write to subdirectories (root-level only)
+- Confirm git root from Context section
+
+**Exploration Depth:**
+- READ actual files, don't guess content
+- Run commands to see real output (make --help, just --list, etc.)
+- Check multiple sources for same information
+- Prefer CI config for canonical commands
+
+**Content Quality:**
+- Specific over vague ("pytest -v" not "run tests")
+- Actionable over descriptive
+- Examples over explanations
+- Brief over comprehensive
+- Accurate over complete
+
+**Avoid:**
+- Sensitive information (API keys, credentials, tokens)
+- Duplicating linter rules in Code Style
+- Generic advice ("write good code", "test your changes")
+- Personal opinions not grounded in codebase
+- Unnecessary prose
+
+**Update Mode:**
+- Preserve user customizations
+- Don't remove manual additions
+- Only update what changed
+- Maintain user's organizational preferences
+
+**Documentation:**
+- This is for LLM agents, not humans
+- Focus on information NOT in README
+- Commands are most important (put first)
+- Gotchas are high-value (include prominent section)
+
+Your AGENTS.md should enable any LLM coding agent to start contributing effectively within minutes of reading it.

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.