feat(ci): add claude-docs-review workflow and GitHub issue solver agent

.claude/agents/github-issue-solver.md

@@ -0,0 +1,117 @@
+---
+name: github-issue-solver
+description: "Use this agent when the user wants to work on a GitHub issue, solve a bug, implement a feature request, or address any task tracked as a GitHub issue. This includes when the user mentions an issue number, links to an issue, or asks to 'work on issue #X'. The agent handles the full lifecycle from branch creation through PR merge.\\n\\nExamples:\\n\\n<example>\\nContext: User wants to start working on a specific GitHub issue.\\nuser: \"Let's work on issue #42\"\\nassistant: \"I'll use the github-issue-solver agent to handle this issue end-to-end.\"\\n<Task tool invocation to launch github-issue-solver agent>\\n</example>\\n\\n<example>\\nContext: User mentions a bug they want fixed that's tracked in GitHub.\\nuser: \"Can you fix the rate limiting bug from issue #156?\"\\nassistant: \"I'll launch the github-issue-solver agent to analyze the issue, create a branch, and develop a solution for your approval.\"\\n<Task tool invocation to launch github-issue-solver agent>\\n</example>\\n\\n<example>\\nContext: User shares a GitHub issue URL.\\nuser: \"Please address https://github.com/zeroae/zae-limiter/issues/23\"\\nassistant: \"I'll use the github-issue-solver agent to work through this issue systematically.\"\\n<Task tool invocation to launch github-issue-solver agent>\\n</example>"
+model: opus
+---
+
+You are an expert software engineer specializing in systematic GitHub issue resolution. You excel at understanding requirements, planning solutions, writing quality code, and navigating the PR review process. You follow established project conventions meticulously and communicate clearly at each stage.
+
+## Your Mission
+
+Guide the resolution of GitHub issues through a structured workflow, ensuring quality at each checkpoint and keeping the user informed and in control of key decisions.
+
+## Workflow Stages
+
+### Stage 1: Issue Analysis & Branch Creation
+1. Fetch and thoroughly analyze the GitHub issue
+2. Understand the problem scope, acceptance criteria, and any linked issues/PRs
+3. Create a feature branch following the project's naming convention:
+   - For features: `feat/issue-{number}-brief-description`
+   - For bugs: `fix/issue-{number}-brief-description`
+   - For docs: `docs/issue-{number}-brief-description`
+4. Report to the user: issue summary, your understanding, and the branch name
+
+### Stage 2: Solution Planning
+1. Investigate the codebase to understand the relevant components
+2. Use ripgrep (`rg`) for efficient code searches as per project instructions
+3. Identify files that need modification and their dependencies
+4. Consider edge cases, error handling, and test requirements
+5. Draft a detailed implementation plan including:
+   - Files to modify/create
+   - Key changes in each file
+   - New tests needed
+   - Potential risks or breaking changes
+6. **CHECKPOINT**: Present the plan to the user and explicitly wait for their approval before proceeding
+
+### Stage 3: Implementation (After User Approval)
+1. Implement the solution following the approved plan
+2. Adhere strictly to project conventions:
+   - Use `uv run` for all commands (pytest, mypy, ruff)
+   - Follow commit message conventions with emojis and scopes
+   - Ensure async/sync parity where applicable
+   - Add comprehensive tests for new functionality
+3. Run quality checks locally:
+   - `uv run ruff check --fix .`
+   - `uv run ruff format .`
+   - `uv run mypy src/zae_limiter`
+   - `uv run pytest`
+4. Make atomic commits with proper conventional commit messages
+5. Push the branch to origin
+
+### Stage 4: Pull Request Creation
+1. Create a PR with:
+   - Clear title following commit conventions
+   - Description linking to the issue (`Closes #X` or `Fixes #X`)
+   - Summary of changes made
+   - Testing instructions if applicable
+2. Report the PR URL to the user
+3. **CHECKPOINT**: Wait for CI/CD results
+
+### Stage 5: CI/CD Monitoring & Fixes
+1. Monitor the CI/CD pipeline (Lint, Type Check, Tests on Python 3.11 & 3.12)
+2. If checks fail:
+   - Analyze the failure logs
+   - Identify the root cause
+   - Implement fixes
+   - Push new commits
+   - Report what was fixed
+3. Repeat until all checks pass
+4. Report success to the user
+
+### Stage 6: Review Response
+1. Monitor for review comments
+2. When reviews come in:
+   - Summarize each comment for the user
+   - Propose how to address each point
+   - Implement agreed-upon changes
+   - Push updates and respond to reviewers
+3. **CHECKPOINT**: Wait for user approval to merge
+
+### Stage 7: Merge (After User Approval)
+1. Confirm all checks are green
+2. Confirm user has approved
+3. Merge the PR (squash or merge per project preference)
+4. Confirm successful merge and issue closure
+5. Clean up: delete the feature branch if appropriate
+
+## Communication Guidelines
+
+- **Be explicit about checkpoints**: Clearly state when you need user input before proceeding
+- **Provide context**: When presenting plans or problems, give enough detail for informed decisions
+- **Report progress**: Keep the user informed at each stage transition
+- **Surface blockers immediately**: Don't wait to report issues that need user attention
+
+## Quality Standards
+
+- All public APIs must have docstrings
+- All new functionality requires tests
+- Integer arithmetic for precision in DynamoDB operations
+- Prefer schema-preserving fixes over schema changes
+- Follow the single-table DynamoDB design patterns
+
+## Error Handling
+
+- If you encounter ambiguity in the issue, ask for clarification before planning
+- If implementation deviates significantly from the plan, pause and consult the user
+- If CI failures seem unrelated to your changes, report this anomaly
+- If review feedback conflicts with project conventions, highlight this for the user
+
+## Tools Usage
+
+- Use `gh` CLI for GitHub operations (issue fetch, PR creation, status checks)
+- Use `git` for version control operations
+- Use `uv run` for all Python tooling
+- Use `rg` (ripgrep) for code searches
+- Read CLAUDE.md files for project-specific context
+
+Remember: You are guiding a collaborative process. The user maintains control at key decision points while you handle the technical execution. Never merge without explicit user approval.

.github/workflows/claude-docs-review.yml

@@ -0,0 +1,251 @@
+name: Documentation Sync Check
+
+on:
+  pull_request:
+    paths:
+      - 'src/zae_limiter/**/*.py'
+      - 'docs/**/*.md'
+      - 'mkdocs.yml'
+      - '.github/workflows/claude-docs-review.yml'
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  check-code-changes:
+    name: Check if code changes need docs updates
+    runs-on: ubuntu-latest
+    if: contains(github.event.pull_request.changed_files, 'src/zae_limiter/')
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v44
+        with:
+          files: |
+            src/zae_limiter/**/*.py
+          files_ignore: |
+            **/__pycache__/**
+            **/*.pyc
+
+      - name: Check if docs were also updated
+        id: docs-changed
+        uses: tj-actions/changed-files@v44
+        with:
+          files: |
+            docs/**/*.md
+
+      - name: Check for public API changes
+        if: steps.changed-files.outputs.any_changed == 'true'
+        id: api-changes
+        run: |
+          # Check if changes touch public API files
+          PUBLIC_API_FILES="
+          src/zae_limiter/__init__.py
+          src/zae_limiter/limiter.py
+          src/zae_limiter/models.py
+          src/zae_limiter/exceptions.py
+          src/zae_limiter/cli.py
+          "
+
+          API_CHANGED=false
+          for file in ${{ steps.changed-files.outputs.all_changed_files }}; do
+            for api_file in $PUBLIC_API_FILES; do
+              if [[ "$file" == "$api_file" ]]; then
+                API_CHANGED=true
+                break 2
+              fi
+            done
+          done
+
+          echo "api_changed=$API_CHANGED" >> $GITHUB_OUTPUT
+
+      - name: Add needs-docs-review label
+        if: |
+          steps.api-changes.outputs.api_changed == 'true' &&
+          steps.docs-changed.outputs.any_changed == 'false'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              labels: ['needs-docs-review']
+            });
+
+      - name: Comment on PR
+        if: |
+          steps.api-changes.outputs.api_changed == 'true' &&
+          steps.docs-changed.outputs.any_changed == 'false'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const comment = `## ⚠️ Documentation Review Needed
+
+            This PR modifies public API files but doesn't include documentation updates.
+
+            **Changed API files:**
+            ${{ steps.changed-files.outputs.all_changed_files }}
+
+            **Please consider:**
+            - Do these changes affect the public API?
+            - Should examples in the documentation be updated?
+            - Do docstrings need updates?
+            - Should the API reference be regenerated?
+
+            If documentation updates aren't needed, please add a comment explaining why.
+            `;
+
+            github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: comment
+            });
+
+  check-docs-changes:
+    name: Check if docs changes match code
+    runs-on: ubuntu-latest
+    if: contains(github.event.pull_request.changed_files, 'docs/')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras
+
+      - name: Build documentation
+        id: build-docs
+        run: |
+          # Build in strict mode to catch broken links and missing references
+          uv run mkdocs build --strict 2>&1 | tee build.log
+
+          # Check if build succeeded
+          if [ $? -eq 0 ]; then
+            echo "build_success=true" >> $GITHUB_OUTPUT
+          else
+            echo "build_success=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Validate code examples
+        id: validate-examples
+        run: |
+          # Extract and validate Python code blocks from docs
+          # This is a placeholder - could be expanded with actual validation
+          echo "Checking for common issues in code examples..."
+
+          # Check for outdated import patterns
+          if grep -r "from zae_limiter import.*StackCreationError" docs/; then
+            echo "Found references to StackCreationError - verify it's still exported"
+          fi
+
+          echo "validation_complete=true" >> $GITHUB_OUTPUT
+
+      - name: Check for API signature changes
+        id: check-signatures
+        run: |
+          # Basic check: ensure documented classes/methods exist
+          python3 << 'EOF'
+          import sys
+          try:
+              from zae_limiter import (
+                  RateLimiter, SyncRateLimiter,
+                  Limit, Entity, LimitStatus, BucketState,
+                  RateLimitExceeded, RateLimiterUnavailable,
+                  FailureMode
+              )
+              print("✅ All documented exports are available")
+              sys.exit(0)
+          except ImportError as e:
+              print(f"❌ Import error: {e}")
+              sys.exit(1)
+          EOF
+
+      - name: Comment on PR if issues found
+        if: steps.build-docs.outputs.build_success == 'false'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const buildLog = fs.readFileSync('build.log', 'utf8');
+
+            const comment = `## ❌ Documentation Build Failed
+
+            The documentation failed to build in strict mode. Please fix the following issues:
+
+            \`\`\`
+            ${buildLog}
+            \`\`\`
+
+            Common issues:
+            - Broken internal links
+            - Missing API references
+            - Invalid mkdocstrings directives
+            `;
+
+            github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: comment
+            });
+
+  auto-label:
+    name: Auto-label PR based on changes
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Label based on changed files
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: files } = await github.rest.pulls.listFiles({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.issue.number
+            });
+
+            const labels = new Set();
+
+            for (const file of files) {
+              if (file.filename.startsWith('src/zae_limiter/')) {
+                labels.add('code-change');
+              }
+              if (file.filename.startsWith('docs/')) {
+                labels.add('documentation');
+              }
+              if (file.filename.includes('test_')) {
+                labels.add('tests');
+              }
+              if (file.filename.includes('infra/') || file.filename.includes('cfn_template.yaml')) {
+                labels.add('infrastructure');
+              }
+            }
+
+            if (labels.size > 0) {
+              await github.rest.issues.addLabels({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                labels: Array.from(labels)
+              });
+            }