feat: add gemini and review-pr slash commands (#138)

2026-03-25 09:25:50 +00:00 · 2025-06-29 22:53:33 +02:00 · 2025-06-29 22:53:33 +02:00 · b2a395fcd8
commit b2a395fcd8
parent 13b98308c9
3 changed files with 571 additions and 0 deletions
--- a/.claude/commands/gemini.md
+++ b/.claude/commands/gemini.md
@ -0,0 +1,58 @@
+# /gemini
+
+Execute Gemini CLI with the context from docs/gemini.md for large codebase analysis.
+
+## Usage
+
+```
+/gemini {prompt}
+```
+
+## Description
+
+This command reads the `docs/gemini.md` file which contains best practices for using the Gemini CLI with large codebases, then executes the appropriate gemini command based on your prompt.
+
+## Examples
+
+### Analyze a single file
+```
+/gemini @web/src/server/server.ts Explain this file's purpose and structure
+```
+
+### Check feature implementation
+```
+/gemini @web/src/ Has dark mode been implemented in this codebase?
+```
+
+### Analyze entire project
+```
+/gemini @./ Give me an overview of this entire project
+```
+
+### Verify security measures
+```
+/gemini @web/src/ @web/src/api/ Are SQL injection protections implemented?
+```
+
+## Implementation
+
+When you use this command, I will:
+1. Check if Gemini CLI is installed and accessible
+2. Read the contents of `docs/gemini.md` to understand Gemini CLI usage patterns (provide helpful error if missing)
+3. Analyze your prompt to determine the appropriate Gemini command structure
+4. Execute the gemini command with the proper flags and file inclusions
+5. Return the results to help with your codebase analysis
+
+## Error Handling
+
+- If Gemini CLI is not installed, provide installation instructions
+- If `docs/gemini.md` is missing, use built-in knowledge of Gemini CLI best practices
+- Handle command execution errors gracefully with helpful messages
+
+## Note
+
+The Gemini CLI is particularly useful when:
+- Analyzing entire codebases or large directories
+- Context window limits are a concern
+- You need to verify implementation of specific features across many files
+- Working with files totaling more than 100KB
--- a/.claude/commands/review-pr.md
+++ b/.claude/commands/review-pr.md
@ -0,0 +1,314 @@
+# /review-pr
+
+Perform a comprehensive code review of the current pull request using parallel sub-agents powered by Claude and Gemini, with results intelligently merged.
+
+## Usage
+
+```
+/review-pr [options]
+```
+
+Options:
+- `--focus <area>` - Focus on specific areas. Valid values: `security`, `performance`, `tests`, `architecture`, `documentation`, `all`
+- `--gemini-only` - Perform the review only with gemini CLI
+
+## Description
+
+This command performs a thorough code review of the current branch's changes compared to the main branch. It runs two parallel sub-agents - one using Claude and another using Gemini - to perform independent comprehensive reviews. The results from both AI models are then intelligently merged to provide a complete multi-perspective analysis.
+
+## Examples
+
+### Standard PR review
+```
+/review-pr
+```
+
+### Security-focused review
+```
+/review-pr --focus security
+```
+
+### Performance and scalability review
+```
+/review-pr --focus performance
+```
+
+## Implementation
+
+When you use this command, I will:
+
+1. **Initial PR Context Gathering**
+   - Check if required tools are available: `gh`, `git`, and `gemini`
+   - Run `gh pr view` to check PR description and any existing comments (handle errors gracefully)
+   - Run `git log "main..HEAD" --oneline` to see all commits in this PR (with proper shell escaping)
+   - Run `git diff "main...HEAD" --stat` to get an overview of changed files (with proper shell escaping)
+   - Generate comprehensive diff with secure temporary file handling:
+     ```bash
+     touch .pr_review_diff.tmp && chmod 600 .pr_review_diff.tmp
+     git diff "main...HEAD" > .pr_review_diff.tmp
+     ```
+   - If any git commands fail, provide helpful error messages and guidance
+
+2. **Launch Two Parallel Sub-Agents**
+
+   **Sub-Agent 1: Claude Review**
+   - WARNING: This step must be skipped when `--gemini-only` has been passed
+   - Performs complete multi-aspect code review using Claude
+   - Analyzes all aspects below independently
+   
+   **Sub-Agent 2: Gemini Review**
+   - Runs Gemini CLI following instructions from `docs/gemini.md`
+   - Performs complete multi-aspect code review using Gemini
+   - Form the prompt to the Gemini CLI in a way that it only returns the final output of its findings, to save tokens
+   - Analyzes all aspects below independently
+   - Use a timeout of 10 minutes for the gemini CLI command (configurable via environment variable `GEMINI_TIMEOUT_SECONDS`, default: 600)
+   - **IMPORTANT**: Gemini CLI can only access files within the project directory
+     - Create temporary diff file in project root (e.g., `.pr_review_diff.tmp`)
+     - Use `@.pr_review_diff.tmp` syntax to include the diff in Gemini prompt
+     - Clean up temporary file after review completes
+
+   **Both sub-agents analyze:**
+
+   **Correctness & Logic**
+   - Verify the code solves the intended problem
+   - Check for edge cases, off-by-one errors, null/undefined handling
+   - Validate business logic and algorithm correctness
+   
+   **Code Quality & Architecture**
+   - Check adherence to DRY and SOLID principles
+   - Assess function/class complexity and cohesion
+   - Verify consistent naming conventions and code style
+   - Ensure changes align with existing architecture patterns
+   
+   **Performance & Scalability**
+   - Identify O(n²) algorithms that could be O(n)
+   - Check for N+1 database queries
+   - Look for memory leaks or excessive allocations
+   - Identify missed caching opportunities
+   
+   **Security**
+   - Check for SQL injection vulnerabilities
+   - Identify XSS vulnerabilities
+   - Verify authentication/authorization checks
+   - Ensure no sensitive data in logs or commits
+   - Validate all user inputs are sanitized
+   
+   **Testing**
+   - Verify test coverage for new/modified code
+   - Check if tests actually test the right behavior
+   - Ensure edge cases are covered
+   - Assess test maintainability and brittleness
+   
+   **Error Handling**
+   - Verify errors are properly caught and handled
+   - Check error messages are helpful for debugging
+   - Ensure appropriate logging levels
+   - Validate graceful failure modes
+   
+   **Documentation**
+   - Check if complex logic is explained
+   - Verify API documentation is updated
+   - Look for outdated or misleading comments
+   - Ensure README/docs are updated if needed
+
+   **Automated Checks**
+   - Execute `pnpm run check` (for web/) if available
+   - Run `./scripts/lint.sh` (for mac/) if the script exists
+   - Run `./lint.sh` (for tauri/) if the script exists
+   - Check if tests pass with appropriate test commands
+   - Verify build succeeds
+   - If any checks fail, continue with review but note the failures
+
+3. **Merge Results**
+   - Intelligently combine findings from both Claude and Gemini
+   - Identify common issues found by both models (high confidence)
+   - Highlight unique insights from each model
+   - Resolve any conflicting assessments
+   - Generate unified severity ratings
+
+4. **Generate Final Review Report**
+   - Provide a structured review with:
+     - **Summary**: High-level overview of changes
+     - **Strengths**: What's done well
+     - **Critical Issues**: Must-fix problems with exact line numbers
+     - **Suggestions**: Nice-to-have improvements with exact line numbers
+     - **Questions**: Clarifications needed with exact line numbers
+   - Use accountability mindset - I'm as responsible as the author
+   - Provide constructive, mentoring-oriented feedback
+   - **CRITICAL**: Always include exact line numbers for every issue found
+   - Use format: `filename:line_number` (e.g., `src/server.ts:142`)
+   - For multi-line issues, use ranges: `filename:start_line-end_line`
+
+5. **Cleanup**
+   - Remove temporary diff file `.pr_review_diff.tmp` from project root
+   - Ensure no sensitive data remains in temporary files
+
+## Review Checklist
+
+### ✅ Shared Accountability
+- [ ] I understand I share responsibility for this code once approved
+- [ ] I've reviewed with the same care as if I wrote it
+
+### 🎯 Functionality
+- [ ] Code implements intended functionality
+- [ ] Edge cases and error scenarios handled
+- [ ] No regressions introduced
+
+### 🏗️ Architecture & Design
+- [ ] Changes align with system architecture
+- [ ] Scalability and maintainability considered
+- [ ] Design patterns appropriately used
+
+### 🔒 Security
+- [ ] Input validation present
+- [ ] Authentication/authorization correct
+- [ ] No sensitive data exposed
+- [ ] Dependencies are secure
+
+### ⚡ Performance
+- [ ] No unnecessary database queries
+- [ ] Efficient algorithms used
+- [ ] Resource usage is reasonable
+- [ ] Caching utilized where appropriate
+
+### 🧪 Testing
+- [ ] Adequate test coverage
+- [ ] Tests are meaningful, not just coverage
+- [ ] Edge cases tested
+- [ ] Tests are maintainable
+
+### 📝 Code Quality
+- [ ] Code is DRY
+- [ ] SOLID principles followed
+- [ ] Clear naming and structure
+- [ ] Appropriate comments/documentation
+
+### 🔄 Backwards Compatibility
+- [ ] API changes are backwards compatible
+- [ ] Database migrations handled properly
+- [ ] No breaking changes without discussion
+
+## Note
+
+This command emphasizes:
+- **Parallel Sub-Agent Architecture**: Two independent sub-agents perform complete reviews - one using Claude, another using Gemini CLI
+- **Intelligent Merging**: Final step combines findings from both AI models by identifying common issues (high confidence), highlighting unique insights, and resolving conflicting assessments
+- **Accountability**: Approving means you own the outcome
+- **Mentorship**: Every comment is a teaching opportunity
+- **Thoroughness**: Multiple passes from different angles by both AI models
+- **Actionability**: Specific, clear feedback with examples
+- **Precision**: Every issue must include exact line numbers
+
+**Line Number Format Examples:**
+- Single line issue: `src/server/auth.ts:234`
+- Multi-line issue: `src/client/app.ts:45-52`
+- Context reference: `src/utils/helpers.ts:78 (similar pattern at lines 95, 112)`
+
+**Sub-Agent Execution:**
+- Claude sub-agent performs the review using Claude's capabilities
+- Gemini sub-agent runs the Gemini CLI following instructions from `docs/gemini.md`
+- Both sub-agents work in parallel for efficiency
+
+For large PRs, consider reviewing incrementally and suggesting the author break it into smaller PRs for more effective review.
+
+## Prerequisites
+
+- Git and GitHub CLI (`gh`) must be installed
+- For full functionality: Gemini CLI must be installed (see Gemini documentation)
+- For `--gemini-only` mode: Only Gemini CLI is required
+
+## Security Considerations
+
+**Input Sanitization:**
+- All user-provided parameters (e.g., `--focus` values) are validated against a whitelist
+- Git commands use proper shell escaping with quotes around branch names
+- Temporary files are created with secure permissions (mode 600)
+- File paths are validated to prevent directory traversal attacks
+- The `--focus` parameter only accepts predefined values: security, performance, tests, architecture, documentation, all
+
+**Safe Command Execution:**
+```bash
+# Always quote branch names and file paths
+git diff "main...HEAD" --stat  # Correct
+git diff main...HEAD --stat     # Vulnerable to injection
+
+# Set restrictive permissions on temporary files
+touch .pr_review_diff.tmp && chmod 600 .pr_review_diff.tmp
+git diff "main...HEAD" > .pr_review_diff.tmp
+```
+
+## Error Handling
+
+- If required tools are missing, the command will provide installation instructions
+- Git command failures are handled gracefully with helpful error messages
+- If automated checks fail, the review continues but notes the failures
+- Timeout protection: Gemini sub-agent has a 10-minute timeout (configurable via `GEMINI_TIMEOUT_SECONDS` environment variable)
+
+## Implementation Notes
+
+**Gemini CLI File Access:**
+- Gemini CLI can only access files within the project directory
+- Always save temporary files in the project root with `.tmp` extension
+- Use `.gitignore` patterns for temporary files (e.g., `.pr_review_*.tmp`)
+- Example workflow:
+  ```bash
+  # Create file with secure permissions
+  touch .pr_review_diff.tmp && chmod 600 .pr_review_diff.tmp
+  
+  # Save diff to project-accessible location
+  git diff "main...HEAD" > .pr_review_diff.tmp
+  
+  # Use with Gemini
+  gemini -p "@.pr_review_diff.tmp Your review prompt here"
+  
+  # Clean up
+  rm -f .pr_review_diff.tmp
+  ```
+
+**Handling Large Diffs:**
+- For very large PRs, consider splitting the diff by file type or directory
+- Use Gemini's 2M token context window advantage for comprehensive analysis
+- If diff exceeds reasonable size, suggest breaking PR into smaller chunks
+
+**Chunking Strategy for Diffs Exceeding 1.5M Tokens:**
+
+1. **Automatic splitting by file type:**
+   ```bash
+   # JavaScript/TypeScript files
+   git diff "main...HEAD" -- "*.js" "*.ts" "*.jsx" "*.tsx" > .pr_review_js.tmp
+   
+   # Python files
+   git diff "main...HEAD" -- "*.py" > .pr_review_py.tmp
+   
+   # Documentation
+   git diff "main...HEAD" -- "*.md" "*.rst" "*.txt" > .pr_review_docs.tmp
+   ```
+
+2. **Split by directory structure:**
+   ```bash
+   # Frontend changes
+   git diff "main...HEAD" -- "web/src/client/" > .pr_review_frontend.tmp
+   
+   # Backend changes
+   git diff "main...HEAD" -- "web/src/server/" > .pr_review_backend.tmp
+   
+   # Test changes
+   git diff "main...HEAD" -- "**/test/" "**/tests/" > .pr_review_tests.tmp
+   ```
+
+3. **Prioritize by change type:**
+   ```bash
+   # New files (highest priority)
+   git diff "main...HEAD" --name-status | grep "^A" | cut -f2 | xargs git diff "main...HEAD" -- > .pr_review_new.tmp
+   
+   # Modified files
+   git diff "main...HEAD" --name-status | grep "^M" | cut -f2 | xargs git diff "main...HEAD" -- > .pr_review_modified.tmp
+   
+   # Deleted files (lowest priority for review)
+   git diff "main...HEAD" --name-status | grep "^D" | cut -f2 > .pr_review_deleted_list.tmp
+   ```
+
+4. **Token estimation:**
+   - Rough estimate: 1 token ≈ 4 characters
+   - Check file size: `wc -c .pr_review_diff.tmp`
+   - If > 6MB (≈1.5M tokens), implement chunking strategy
--- a/docs/gemini.md
+++ b/docs/gemini.md
@ -0,0 +1,199 @@
+# Using Gemini CLI for Large Codebase Analysis
+
+When analyzing large codebases or multiple files that might exceed context limits, use the Gemini CLI with its massive context window (up to 2 million tokens). Use `gemini -p` to leverage Google Gemini's large context capacity.
+
+## Prerequisites
+
+Ensure Gemini CLI is installed before using these commands. Installation instructions: https://github.com/google/gemini-cli#installation
+
+## File and Directory Inclusion Syntax
+
+Use the `@` syntax to include files and directories in your Gemini prompts. The paths should be relative to WHERE you run the gemini command:
+
+### Examples:
+
+**Single file analysis:**
+```bash
+gemini -p "@web/src/server/server.ts Explain this file's purpose and structure"
+```
+
+**Multiple files:**
+```bash
+gemini -p "@package.json @web/src/client/app.ts Analyze the dependencies used in the code"
+```
+
+**Entire directory:**
+```bash
+gemini -p "@src/ Summarize the architecture of this codebase"
+```
+
+**Multiple directories:**
+```bash
+gemini -p "@src/ @tests/ Analyze test coverage for the source code"
+```
+
+**Current directory and subdirectories:**
+```bash
+gemini -p "@./ Give me an overview of this entire project"
+# Or use --all_files flag:
+gemini --all_files -p "Analyze the project structure and dependencies"
+```
+
+**⚠️ Security Warning:** Using `@./` may include sensitive files like `.env`, `.git/`, or API keys. Consider using specific directories or exclusion patterns.
+
+## Implementation Verification Examples
+
+**Check if a feature is implemented:**
+```bash
+gemini -p "@src/ @lib/ Has dark mode been implemented in this codebase? Show me the relevant files and functions"
+```
+
+**Verify authentication implementation:**
+```bash
+gemini -p "@src/ @middleware/ Is JWT authentication implemented? List all auth-related endpoints and middleware"
+```
+
+**Check for specific patterns:**
+```bash
+gemini -p "@src/ Are there any React hooks that handle WebSocket connections? List them with file paths"
+```
+
+**Verify error handling:**
+```bash
+gemini -p "@src/ @api/ Is proper error handling implemented for all API endpoints? Show examples of try-catch blocks"
+```
+
+**Check for rate limiting:**
+```bash
+gemini -p "@backend/ @middleware/ Is rate limiting implemented for the API? Show the implementation details"
+```
+
+**Verify caching strategy:**
+```bash
+gemini -p "@src/ @lib/ @services/ Is Redis caching implemented? List all cache-related functions and their usage"
+```
+
+**Check for specific security measures:**
+```bash
+gemini -p "@src/ @api/ Are SQL injection protections implemented? Show how user inputs are sanitized"
+```
+
+**Verify test coverage for features:**
+```bash
+gemini -p "@src/payment/ @tests/ Is the payment processing module fully tested? List all test cases"
+```
+
+## Error Scenarios and Handling
+
+**Gemini CLI not installed:**
+```bash
+# Error: command not found: gemini
+# Solution: Install Gemini CLI following instructions at https://github.com/google/gemini-cli#installation
+```
+
+**Invalid file paths:**
+```bash
+gemini -p "@nonexistent/path/ Analyze this code"
+# Gemini will report: "Error: Path 'nonexistent/path/' does not exist"
+# The command continues with any valid paths provided
+```
+
+**Network connectivity issues:**
+```bash
+# If API calls fail, you'll see:
+# "Error: Failed to connect to Gemini API"
+# Solution: Check your internet connection and API key configuration
+```
+
+**File encoding problems:**
+```bash
+# Non-UTF8 files are automatically skipped with a warning:
+# "Warning: Skipping binary or non-UTF8 file: path/to/file"
+```
+
+**Context limit exceeded:**
+```bash
+# For extremely large codebases:
+# "Error: Context limit exceeded (2M tokens)"
+# Solution: Use more specific paths or directories instead of @./
+```
+
+**Timeout during analysis:**
+```bash
+# Default timeout is 30 seconds for API calls
+# For longer operations, use the --timeout flag:
+gemini --timeout 120 -p "@large-codebase/ Analyze architecture"
+```
+
+## When to Use Gemini CLI
+
+Use `gemini -p` when:
+- Analyzing entire codebases or large directories
+- Comparing multiple large files
+- Need to understand project-wide patterns or architecture
+- Current context window is insufficient for the task
+- Working with files totaling more than 100KB
+- Verifying if specific features, patterns, or security measures are implemented
+- Checking for the presence of certain coding patterns across the entire codebase
+
+## Important Notes
+
+- Paths in @ syntax are relative to your current working directory when invoking gemini
+- The CLI will include file contents directly in the context
+- The --yolo flag bypasses confirmation prompts (use cautiously)
+- Gemini's context window can handle entire codebases that would overflow Claude's context
+- When checking implementations, be specific about what you're looking for to get accurate results
+- Symlinks are followed by default - be cautious with circular references
+- Binary files are automatically excluded from analysis
+- Use `.geminiignore` file to exclude specific patterns (similar to `.gitignore`)
+
+## Using .geminiignore
+
+Create a `.geminiignore` file in your project root to exclude files and directories from Gemini analysis. The syntax follows `.gitignore` patterns:
+
+```
+# Environment and secrets
+.env*
+*.key
+*.pem
+secrets/
+credentials/
+
+# Build artifacts
+dist/
+build/
+*.min.js
+*.bundle.js
+
+# Dependencies
+node_modules/
+vendor/
+venv/
+
+# Large generated files
+package-lock.json
+yarn.lock
+*.generated.ts
+
+# Test fixtures
+test/fixtures/large-data/
+**/*.snapshot.js
+
+# IDE and OS files
+.idea/
+.vscode/
+.DS_Store
+```
+
+**Pattern Examples:**
+- `*.log` - Exclude all log files
+- `temp/` - Exclude temp directory
+- `!important.log` - Include important.log even if *.log is excluded
+- `src/**/test.js` - Exclude test.js in any subdirectory of src
+- `/config.json` - Exclude config.json only in root directory
+
+## Error Handling
+
+- If paths don't exist, Gemini will report an error and continue with valid paths
+- File encoding issues are handled gracefully (non-UTF8 files are skipped)
+- For large repositories, consider using specific subdirectories to avoid timeouts