From 1977fd02cfe13d45725faa11b9b2314a10a923fd Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:39:22 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 ++ README.md | 3 + commands/pr-create.md | 75 ++++++++ commands/pr-review.md | 347 +++++++++++++++++++++++++++++++++++++ plugin.lock.json | 49 ++++++ 5 files changed, 486 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/pr-create.md create mode 100644 commands/pr-review.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..6cd64c9 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "pr-review-toolkit", + "description": "Comprehensive PR review toolkit for working with GitHub repositories like creating pull requests, commits, and more", + "version": "1.0.0", + "author": { + "name": "Martin Gonzalez", + "email": "gonzalez.martin90@gmail.com" + }, + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..294299a --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# pr-review-toolkit + +Comprehensive PR review toolkit for working with GitHub repositories like creating pull requests, commits, and more diff --git a/commands/pr-create.md b/commands/pr-create.md new file mode 100644 index 0000000..b9a0ca3 --- /dev/null +++ b/commands/pr-create.md @@ -0,0 +1,75 @@ +--- +description: "Create a pull request following the strict workflow" +allowed-tools: ["Bash", "Glob", "Grep", "Read", "Task"] +--- + +You are helping the user create a pull request following their strict workflow. + +## MANDATORY STEPS (DO NOT SKIP): + +1. **Branch Analysis** (run in parallel) + - `git status` - See untracked files + - `git diff` - See staged and unstaged changes + - `git branch --show-current` - Get current branch name + - `git log origin/main..HEAD --oneline` - See all commits in this branch + - `git diff origin/main...HEAD` - See full diff from main + +2. **PR Content Analysis** + - Review ALL commits (not just the latest) to understand full scope + - Analyze all code changes from when branch diverged from main + - Draft comprehensive PR summary covering all changes + +3. **Push to Remote** + - Check if branch tracks remote: `git rev-parse --abbrev-ref --symbolic-full-name @{u}` + - If no remote tracking or not up to date: `git push -u origin ` + +4. **Create PR with gh** + - Use semantic prefix in title: `feat:`, `fix:`, `docs:`, `chore:` + - Use HEREDOC for body to ensure proper formatting + - Follow this template: + ```bash + gh pr create --title "type: brief description" --body "$(cat <<'EOF' + #### Description + [1-3 bullet points summarizing ALL changes] + [It can be a 3-5 sentences description explaining why the changes are needed] + + #### Ticket(s) + [ticket/issue url or "N/A"] + + #### Action points + [bullets of actions needed, or "None"] + EOF + )" + ``` + +5. **Return PR URL** + - Show the created PR URL to the user + +## IMPORTANT RULES: +- NEVER use TodoWrite tool +- DO NOT run additional code exploration beyond git commands +- Focus on ALL commits in the branch, not just the latest one +- Be thorough in analyzing the full diff from main +- Ask about ticket association if not obvious from commits +- Keep title under 50 characters +- Use present tense in description ("Add" not "Added") + +## Example: +```bash +gh pr create --title "feat: add user authentication" --body "$(cat <<'EOF' +#### Description +- Implement JWT-based authentication service +- Add login/logout endpoints with validation +- Create user session management with secure tokens + +#### Ticket(s) +https://github.com/org/repo/issues/123 + +#### Action points +- Update environment variables with JWT_SECRET +- Run database migrations for user tables +EOF +)" +``` + +Now proceed with the PR creation workflow. \ No newline at end of file diff --git a/commands/pr-review.md b/commands/pr-review.md new file mode 100644 index 0000000..1f6336f --- /dev/null +++ b/commands/pr-review.md @@ -0,0 +1,347 @@ +--- +description: "Comprehensive PR review using specialized agents" +argument-hint: "[review-aspects]" +allowed-tools: ["Bash", "Glob", "Grep", "Read", "Task"] +--- + +# Comprehensive PR Review + +Run a comprehensive pull request review using multiple specialized agents, each focusing on a different aspect of code quality. + +**Review Aspects (optional):** "$ARGUMENTS" + +## Review Workflow: + +1. **Determine Review Scope** + - Check if argument contains the keyword `local` + - If `local` argument detected: + * **Pre-review mode** - Review local changes before creating/updating PR + * Verify current directory is a git repository: `git rev-parse --is-inside-work-tree` + * If not a git repo: Exit with error message + * Get current branch: `git branch --show-current` + * Get default branch: `git remote show origin | grep 'HEAD branch'` or assume `main`/`master` + * Check for uncommitted changes: `git status --porcelain` + * If uncommitted changes exist: Ask user "You have uncommitted changes. Review staged changes only, or commit all changes first? (staged/commit/cancel)" + * Generate diff against default branch: `git diff ...HEAD` + * If no changes found: Exit with message "No changes detected between current branch and " + * Continue with review using the local diff + * Skip PR metadata extraction (no PR exists yet) + * Use branch name and local changes for context + - Check if argument is a PR URL (matches pattern: `https://github.com/*/pull/*`) + - If PR URL detected: + * Use `gh pr view $URL --json headRefName,headRepository,headRepositoryOwner` to extract metadata + * Extract repo name and branch from JSON response + * **Check for existing repository:** + - If current directory is NOT a git repo: Check if any child folder matches repo name and contains `.git` + - If matching child folder found: Use that instead of cloning + - If no matching folder exists: Clone via `git clone git@github.com:owner/repo.git` + * **Navigate to repository directory** + * **Branch state management:** + 1. Check current branch: `git branch --show-current` + 2. Check if on HEAD of PR branch: `git fetch origin && git rev-parse HEAD` vs `git rev-parse origin/` + 3. Check for uncommitted changes: `git status --porcelain` + 4. Apply appropriate action: + - **On PR branch, at HEAD, no changes:** Continue with review + - **On PR branch, behind HEAD, no changes:** Pull latest: `git pull origin ` + - **On PR branch, behind HEAD, with changes:** Ask user: "Branch has uncommitted changes. Reset hard and pull HEAD? (y/n)" + - **On different branch, no changes:** Switch to PR branch: `git checkout ` + - **On different branch, with changes:** Ask user: "You are on branch X with uncommitted changes. Reset and switch to PR branch? (y/n)" + * Continue with review in this context + - If no URL provided: + * Run `git rev-parse --is-inside-work-tree` to check if current directory is a git project + * If NOT a git project: **Exit early** with message: "Not in a git repository and no PR URL provided. Please either navigate to a git project or provide a PR URL." + * If git project exists: proceed with current repository + - Check git status to identify changed files + - If no specific review aspects provided in arguments: **Ask user interactively** which aspects to review + - Present numbered list of available aspects and wait for user selection + +2. **Interactive Review Aspect Selection (if not provided in arguments)** + + Present this numbered menu to user: + ``` + Select review aspects (comma-separated numbers, or 0 for all): + + 0. All applicable reviews (comprehensive) + 1. Comments - Analyze code comment accuracy and maintainability + 2. Tests - Review test coverage quality and completeness + 3. Errors - Check error handling for silent failures + 4. Types - Analyze type design and invariants + 5. Code - General code review for project guidelines + 6. Simplify - Simplify code for clarity and maintainability + + Example: "1,2,3" or "0" or "2" + ``` + + - Wait for user input + - Parse their selection (e.g., "1,3,5" → comments, errors, code) + - If user enters "0" or "all": run all applicable reviews + - Proceed to next step with selected aspects + +3. **Available Review Aspects Reference:** + + - **comments** - Analyze code comment accuracy and maintainability + - **tests** - Review test coverage quality and completeness + - **errors** - Check error handling for silent failures + - **types** - Analyze type design and invariants (if new types added) + - **code** - General code review for project guidelines + - **simplify** - Simplify code for clarity and maintainability + - **all** - Run all applicable reviews (default) + +4. **Identify Changed Files** + - Run `git diff --name-only` to see modified files + - Check if PR already exists: `gh pr view` + - Identify file types and what reviews apply + +5. **Determine Applicable Reviews** + + Based on changes: + - **Always applicable**: code-reviewer (general quality) + - **If test files changed**: pr-test-analyzer + - **If comments/docs added**: comment-analyzer + - **If error handling changed**: silent-failure-hunter + - **If types added/modified**: type-design-analyzer + - **After passing review**: code-simplifier (polish and refine) + +6. **Launch Review Agents** + + **Sequential approach** (one at a time): + - Easier to understand and act on + - Each report is complete before next + - Good for interactive review + + **Parallel approach** (user can request): + - Launch all agents simultaneously + - Faster for comprehensive review + - Results come back together + +7. **Aggregate Results** + + After agents complete, summarize: + - **Critical Issues** (must fix before merge) + - **Important Issues** (should fix) + - **Suggestions** (nice to have) + - **Positive Observations** (what's good) + +8. **Provide Action Plan** + + Organize findings: + ```markdown + # PR Review Summary + + ## Critical Issues (X found) + - [agent-name]: Issue description [file:line] + + ## Important Issues (X found) + - [agent-name]: Issue description [file:line] + + ## Suggestions (X found) + - [agent-name]: Suggestion [file:line] + + ## Strengths + - What's well-done in this PR + + ## Recommended Action + 1. Fix critical issues first + 2. Address important issues + 3. Consider suggestions + 4. Re-run review after fixes + ``` + +9. **Generate Review Document** + + After completing the review, write a markdown file with appropriate naming convention. + + **For PR URL reviews:** + - Filename: `pr_.md` + - Fetch PR details: `gh pr view --json number,title,author,headRefName,baseRefName,body,additions,deletions,changedFiles` + - Extract ticket URL from PR body (look for patterns like Jira, GitHub issues, etc.) + + **For local reviews:** + - Filename: `pr_local__.md` (e.g., `pr_local_feature-auth_20251010-143022.md`) + - Use timestamp format: `YYYYMMDD-HHMMSS` + - Generate metadata from git: author (git config user.name), branch names, file statistics + + **File location:** + - Create `.pr-reviews/` directory in repository root if it doesn't exist + - Save review file as `.pr-reviews/.md` + - Ensure `.pr-reviews/` is added to `.gitignore` so reviews are not committed + + **Gitignore management:** + - Check if `.gitignore` exists in repository root + - If exists: Check if `.pr-reviews/` is already ignored + - If not ignored: Append `.pr-reviews/` to `.gitignore` + - If `.gitignore` doesn't exist: Create it with `.pr-reviews/` entry + + **Document structure for PR reviews:** + ```markdown + pr_title: + pr_link: + author: + branch: <- + ticket: (if there is any, otherwise "N/A") + files_changed: (+ -) + + ## PR Description + + + ## Summary + + + [Rest of the review content: Critical Issues, Important Issues, Suggestions, etc.] + ``` + + **Document structure for local reviews:** + ```markdown + review_type: Local Pre-Review + branch: <- + author: + date: + files_changed: (+ -) + ticket: (if detectable, otherwise "N/A") + + ## Changes Summary + + + ## Summary + + + [Rest of the review content: Critical Issues, Important Issues, Suggestions, etc.] + ``` + + **Notes:** + - Use underscores for spaces in filename (e.g., `pr_123.md`) + - Preserve exact PR description formatting + - Executive summary should be 2-3 sentences highlighting key findings and risk level + - Reviews are kept local and not tracked in git + +10. **Provide Review File Location** + + After successfully writing the review document: + - Display the absolute path to the review file + - Format: "Review saved to: `/absolute/path/to/repo/.pr-reviews/pr_.md`" + - This allows users to easily locate and open the review file + +## Usage Examples: + +**Local pre-review (before creating PR):** +``` +/github-toolkit:pr-review local +# Reviews local changes against default branch (comprehensive) + +/github-toolkit:pr-review local tests errors +# Reviews only test coverage and error handling of local changes + +/github-toolkit:pr-review local code +# Quick code quality check before committing +``` + +**Review PR from URL:** +``` +/github-toolkit:pr-review https://github.com/owner/repo/pull/123 +# Clones repo (if needed), checks out PR branch, runs full review + +/github-toolkit:pr-review https://github.com/owner/repo/pull/123 tests errors +# Reviews specific aspects of external PR +``` + +**Full review (current repo with existing PR):** +``` +/github-toolkit:pr-review +``` + +**Specific aspects:** +``` +/github-toolkit:pr-review tests errors +# Reviews only test coverage and error handling + +/github-toolkit:pr-review comments +# Reviews only code comments + +/github-toolkit:pr-review simplify +# Simplifies code after passing review +``` + +**Parallel review:** +``` +/github-toolkit:pr-review all parallel +# Launches all agents in parallel + +/github-toolkit:pr-review local all parallel +# Fast pre-review of local changes +``` + +## Agent Descriptions: + +**comment-analyzer**: +- Verifies comment accuracy vs code +- Identifies comment rot +- Checks documentation completeness + +**pr-test-analyzer**: +- Reviews behavioral test coverage +- Identifies critical gaps +- Evaluates test quality + +**silent-failure-hunter**: +- Finds silent failures +- Reviews catch blocks +- Checks error logging + +**type-design-analyzer**: +- Analyzes type encapsulation +- Reviews invariant expression +- Rates type design quality + +**code-reviewer**: +- Checks CLAUDE.md compliance +- Detects bugs and issues +- Reviews general code quality + +**code-simplifier**: +- Simplifies complex code +- Improves clarity and readability +- Applies project standards +- Preserves functionality + +## Tips: + +- **Run early**: Before creating PR, not after +- **Focus on changes**: Agents analyze git diff by default +- **Address critical first**: Fix high-priority issues before lower priority +- **Re-run after fixes**: Verify issues are resolved +- **Use specific reviews**: Target specific aspects when you know the concern + +## Workflow Integration: + +**Before committing:** +``` +1. Write code +2. Run: /github-toolkit:pr-review code errors +3. Fix any critical issues +4. Commit +``` + +**Before creating PR:** +``` +1. Stage all changes +2. Run: /github-toolkit:pr-review all +3. Address all critical and important issues +4. Run specific reviews again to verify +5. Create PR +``` + +**After PR feedback:** +``` +1. Make requested changes +2. Run targeted reviews based on feedback +3. Verify issues are resolved +4. Push updates +``` + +## Notes: + +- Agents run autonomously and return detailed reports +- Each agent focuses on its specialty for deep analysis +- Results are actionable with specific file:line references +- Agents use appropriate models for their complexity +- All agents available in `/agents` list \ No newline at end of file diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..7073278 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,49 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:MartinGonzalez/claude-plugins:plugins/pr-review", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "68b116c474508f5482d3a51fdb56b1074969f65d", + "treeHash": "78e2abcbd852b48ea1130157b680f99fb82dc1be8d7e22a61554096611cf67c6", + "generatedAt": "2025-11-28T10:12:06.329519Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "pr-review-toolkit", + "description": "Comprehensive PR review toolkit for working with GitHub repositories like creating pull requests, commits, and more", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "4ec980a8e83037d29d8f9c90eebf1bee3ccb9c6f2a5605af9e72f6ca0a805508" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "109a6cdc0a31b39ded688fee012e868febaa51eee196d81a113404f99ebfed1a" + }, + { + "path": "commands/pr-create.md", + "sha256": "bb54d861269c6c9c40917b469cbfbf4f9ffffed72892971fd818be30e12f211c" + }, + { + "path": "commands/pr-review.md", + "sha256": "f31fc6dd87b4eabc659d161b01a7fc6ab64fab56a24faa1633d5bca83402334a" + } + ], + "dirSha256": "78e2abcbd852b48ea1130157b680f99fb82dc1be8d7e22a61554096611cf67c6" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file