@trashcodermaker/pr-review-handler 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JI4JUN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @trashcodermaker/pr-review-handler
+
+> Systematically process GitHub PR review comments: triage for validity, fix code, and post replies.
+
+This is the **generic npm package** — an agent skill usable from any agent harness: Pi, Claude Code, Cursor, Gemini CLI, OpenCode, and others.
+
+Looking for the **Pi-specific package**? See [`@trashcodermaker/pi-pr-review-handler`](https://www.npmjs.com/package/@trashcodermaker/pi-pr-review-handler).
+
+## Install
+
+```bash
+npm install @trashcodermaker/pr-review-handler
+```
+
+## What you get
+
+```
+node_modules/@trashcodermaker/pr-review-handler/
+└── skills/
+    └── pr-review-handler/
+        ├── SKILL.md              # the skill instructions
+        └── agents/
+            ├── triage-agent.md
+            └── implementation-agent.md
+```
+
+Point your agent at `node_modules/@trashcodermaker/pr-review-handler/skills/pr-review-handler/SKILL.md`, or copy the `skills/pr-review-handler/` directory into your agent's skill discovery path.
+
+## How it works
+
+The skill runs a multi-phase pipeline with two human checkpoints:
+
+```
+Phase 0: Setup → Phase 1: Triage (parallel, read-only) → Phase 2: Fix (serial)
+         → Phase 3: Reply → Phase 4: Post & Push → Phase 5: Report
+```
+
+Each phase has a clear responsibility. Triage classifies every review comment as `valid-fix`, `valid-nofix`, or `invalid`. Implementation applies minimal surgical fixes. The orchestrator drafts replies that match the reviewer's language and tone.
+
+Full documentation: <https://github.com/JI4JUN/pr-review-handler#readme>
+
+## Requirements
+
+- GitHub CLI (`gh`) installed and authenticated
+- A Git working tree clean enough to create review-fix commits
+- Node.js / TypeScript project if you want the final `tsc --noEmit` check
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@trashcodermaker/pr-review-handler",
+  "version": "1.0.1",
+  "description": "Systematically process GitHub PR review comments: triage for validity, fix code, and post replies. Agent skill usable from any agent harness (Pi, Claude Code, Cursor, Gemini CLI, OpenCode, etc.).",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pr-review",
+    "github",
+    "code-review",
+    "skill",
+    "agent-skill",
+    "agentskills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepublishOnly": "node ../../scripts/sync-skill.mjs ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JI4JUN/pr-review-handler.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/JI4JUN/pr-review-handler#readme",
+  "bugs": {
+    "url": "https://github.com/JI4JUN/pr-review-handler/issues"
+  }
+}

package/skills/pr-review-handler/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: pr-review-handler
+description: >
+  Systematically process GitHub PR review comments: triage for validity,
+  fix code, and post replies. Use whenever the user mentions PR reviews,
+  code review feedback, reviewer comments, or wants to respond to review
+  threads on a pull request. Triggers include: "handle reviews",
+  "respond to PR comments", "fix review feedback", "reply to reviewer",
+  "看看 PR 评论", "回一下 review", "处理 review 意见",
+  "reviewer 说的那个问题", or any mention of dealing with PR review
+  comments. Also triggers when the user pastes a PR link with unresolved
+  conversations, mentions a reviewer by name in the context of their PR,
+  or describes the situation: "someone left comments on my PR",
+  "帮我看看那些人提的意见", "CI 过了但 review 还没回".
+---
+
+# PR Review Handler
+
+Orchestrate specialized agents to process PR review comments:
+
+```
+Phase 0: Setup → Phase 1: Triage (parallel) → Phase 2: Fix (serial)
+         → Phase 3: Reply → Phase 4: Post & Push → Phase 5: Report
+```
+
+Checkpoints: after Phase 1 (user confirms verdicts) and after Phase 3 (user approves replies).
+
+## Agent Definitions
+
+### Roles
+
+| Role | Responsibility | Parallelizable |
+|------|---------------|----------------|
+| Triage Agent | Verify comment validity, classify verdict | ✅ Yes (read-only) |
+| Implementation Agent | Apply minimal code fix for one thread | ❌ No (writes files) |
+| Reply drafting | Orchestrator drafts inline (no separate agent) | N/A |
+
+### Platform mapping
+
+Agent specs live in `agents/` relative to this skill (`agents/triage-agent.md`, `agents/implementation-agent.md`). Every platform uses the same specs — what differs is the dispatch mechanism.
+
+| Platform | Dispatch mechanism |
+|----------|-------------------|
+| Pi | `subagent` tool (fresh context per thread) |
+| Claude Code | Task tool |
+| Cursor | background agent |
+| Gemini CLI / OpenCode / others | native subtask mechanism if available |
+| No subtask available | inline (read the spec, execute the steps yourself) |
+
+**Dispatch pattern**: read the relevant agent spec, embed its instructions into the task prompt along with the thread-specific input data (thread info for triage, verdict data for implementation), and launch one subtask per thread. Triage is read-only so subtasks run in parallel; implementation writes files so it runs serially.
+
+**Inline fallback**: if your platform has no subtask mechanism, you (the orchestrator) read each spec and perform its steps yourself, one thread at a time. The specs are written as direct instructions, so inline execution is straightforward.
+
+## Phase 0: Setup
+
+### Identify the PR
+
+```bash
+gh pr list --state open --json number,title,url,headRefName
+```
+
+Match against current branch (`git branch --show-current`). Use user-supplied PR if specified. Checkout PR branch if needed.
+
+```bash
+git fetch origin
+```
+
+### Fetch unresolved review threads
+
+**Preferred: GraphQL** (filters resolved threads):
+
+```bash
+gh api graphql -f query='
+  query($owner: String!, $repo: String!, $pr: Int!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $pr) {
+        reviewThreads(first: 100) {
+          nodes {
+            isResolved
+            comments(first: 10) {
+              nodes {
+                databaseId
+                body
+                path
+                line
+                author { login }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+' -f owner={owner} -f repo={repo} -F pr={pr_number}
+```
+
+Filter `isResolved: false`. Include full thread (not just top-level) — follow-up replies often contain the real concern.
+
+**Fallback: REST** (when GraphQL unavailable):
+
+```bash
+gh api repos/{owner}/{repo}/pulls/{pr_number}/comments \
+  --jq 'group_by(.path, .original_commit_id) | map({
+    thread_id: .[0].id, path: .[0].path,
+    comments: [.[] | {id, body, user: .user.login, line, in_reply_to_id}]
+  })'
+```
+
+REST cannot detect resolved threads — ask user to confirm which threads need attention.
+
+### Fetch review-level feedback
+
+Review-level feedback (summary comments without line references) is separate from thread comments. Always fetch:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews \
+  --jq 'sort_by(.submitted_at) | reverse | .[:5] | .[] | {id, state, user: .user.login, body}'
+```
+
+Include any non-empty review bodies alongside the thread data when presenting to the user in Phase 2.
+
+## Phase 1: Triage (parallel dispatch)
+
+### Dispatch strategy
+
+Triage is read-only — safe to parallelize.
+
+- **≥3 threads + parallel capability**: spawn one Triage Agent per thread simultaneously
+- **≤2 threads or no parallel capability**: run inline, same logic
+
+If unsure about parallel capability, default to inline.
+
+### Dispatch
+
+For each unresolved thread, dispatch the Triage Agent with this task data:
+
+```
+thread_id: <comment ID>
+path: <file:line>
+reviewer: <reviewer username>
+comments:
+  - <top-level comment text>
+  - <reply 1, if any>
+  - <reply 2, if any>
+```
+
+Embed the Triage Agent spec (`agents/triage-agent.md`) into the task prompt so the subtask has the full role instructions and output format, then append the thread-specific data above. Collect structured verdicts from all agents.
+
+### Checkpoint 1: User confirmation
+
+Present verdicts as a summary table:
+
+| # | File:Line | Reviewer | Summary | Verdict | Affected Files |
+|---|-----------|----------|---------|---------|----------------|
+| 1 | src/auth/login.ts:42 | alice | Missing null check | valid-fix | login.ts, types.ts |
+| 2 | src/ui/Button.tsx:18 | bob | Rename for clarity | valid-fix | Button.tsx |
+| 3 | src/api/handler.ts:99 | alice | Add rate limiting | invalid | — |
+
+User can adjust verdicts or skip threads. Proceed with confirmed plan.
+
+### Quick exits
+
+- **All invalid**: skip Phase 2, go to Phase 3 for reply drafting
+- **All valid-nofix**: skip Phase 2, go to Phase 3
+- **User rejects all**: end workflow
+
+## Phase 2: Implementation (serial dispatch)
+
+### Fix ordering
+
+1. **User-specified order** from Phase 1 confirmation
+2. **Otherwise dependency-first**: types → implementation → callers → tests
+3. **Same level**: PR order
+
+### Dispatch
+
+For each `valid-fix` thread, dispatch the Implementation Agent with this task data:
+
+```
+thread_id: <comment ID>
+path: <file:line>
+reviewer: <name>
+summary: <what the reviewer wants>
+verdict: valid-fix
+affected_files:
+  - <file1>
+  - <file2>
+suggested_fix: <what to change>
+prior_changes: <list of previous fixes in this PR, if any>
+```
+
+Embed the Implementation Agent spec (`agents/implementation-agent.md`) into the task prompt so the subtask has the full role instructions, then append the verdict data above.
+
+After each agent completes:
+
+```bash
+git add -A
+git commit -m "fix(review): {thread summary}"
+```
+
+If commit is empty (agent made no changes), skip.
+
+### After all fixes
+
+```bash
+npx tsc --noEmit
+```
+
+If tsc fails:
+
+- Identify which commit introduced the error (`git bisect` or check error file paths)
+- `git revert --no-commit {commit}` → fix the error → recommit
+- Re-run tsc until clean
+
+Also check:
+
+- Orphan references to removed/renamed symbols (`grep -r`)
+- Translation keys in all message files if `t()` calls were added
+
+### Never push during this phase
+
+All commits stay local. Push happens once in Phase 4.
+
+## Phase 3: Reply (orchestrator drafts inline)
+
+The orchestrator drafts replies directly — no separate agent needed. This phase has full access to all pipeline context.
+
+Gather:
+
+- **Original thread data**: all comments from Phase 0
+- **Triage verdicts**: all structured verdicts from Phase 1
+- **Actual changes**: `git diff origin/{branch}...HEAD`
+- **Failure records**: which fixes failed and why (from Phase 2)
+
+Draft one reply per thread, using `git diff origin/{branch}...HEAD` as ground truth (not planned changes):
+
+**valid-fix (succeeded)**: describe what was changed, referencing the reviewer's concern. If the fix differs from what the reviewer suggested, explain why.
+
+**valid-fix (failed)**: acknowledge the concern was valid. Explain why the fix couldn't be applied (type conflict, dependency issue). Suggest next steps if possible ("will address in a follow-up PR"). Don't be apologetic — just factual.
+
+**valid-nofix**: acknowledge the concern is valid. Explain why no code change is needed. Provide clarification if the reviewer misunderstood the code.
+
+**invalid**: explain clearly why the premise doesn't apply. Reference specific code that already handles the concern. Acknowledge the reviewer's intent ("I see why you'd think X, but..."). Be respectful but direct — don't hedge if the concern is genuinely wrong.
+
+### Reply guidelines
+
+- Match the reviewer's language (Chinese reviewer → Chinese reply)
+- Match tone (casual → casual, formal → formal)
+- Be concise: 1-3 sentences ideal
+- Don't over-explain — reviewer is a peer, trust they understand code
+- Never be defensive — state facts, acknowledge intent
+
+### Checkpoint 2: User review
+
+Present all reply drafts. User can:
+
+- Approve all
+- Edit individual replies
+- Reject specific replies
+- Add context to replies
+
+## Phase 4: Post & Push
+
+Post approved replies:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/comments/{comment_id}/replies \
+  -f body='The response text'
+```
+
+Reply to the top-level comment of each thread (the one with `databaseId`, not a reply).
+
+Push all commits:
+
+```bash
+git push origin HEAD
+```
+
+Ask user if they want to:
+
+- **Request re-review**: `gh api repos/{owner}/{repo}/pulls/{pr_number}/requested_reviewers -f reviewers='["username"]'`
+- **Dismiss resolved reviews**: `gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews/{review_id}/dismissals -f message='Addressed'`
+
+## Phase 5: Report
+
+Output final summary:
+
+```
+✅ Triage: N/N threads processed
+✅ Fixes: M/K valid-fix threads applied (committed locally, pushed)
+   ❌ Failed: {thread} — {reason}
+✅ Replies: P/P threads drafted and posted
+```
+
+## Pipeline Failure Rules
+
+| Scenario | Action |
+|----------|--------|
+| Triage: all agents fail | Stop pipeline. Report to user. Cannot proceed without verdicts. |
+| Triage: some agents fail | Skip failed threads. Continue with successful verdicts. Note in final report. |
+| Implementation: all agents fail | Skip Phase 2. Phase 3 only drafts replies for invalid/nofix threads. |
+| Implementation: some agents fail | Skip failed fixes. Mark in failure records for Phase 3. |
+| Reply drafting fails | Should not happen — orchestrator drafts inline. |
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| `gh` not installed / not authenticated | Tell user to install GitHub CLI and `gh auth login` |
+| API rate limit | Wait for `X-RateLimit-Reset`, retry |
+| PR closed/merged | Warn user — replies have no effect |
+| GraphQL unsupported | Fall back to REST with resolved-thread caveat |
+| tsc fails after all fixes | Fix before posting replies |
+
+## Key Principles
+
+These apply across all agents and phases:
+
+- **Trace all references after removals.** Deleting a function, type field, or import creates orphans in callers, tests, and type usages. Search the entire codebase for the symbol. This is the #1 cause of "fixed the review but broke the build."
+- **Don't guess on ambiguous threads.** If a concern is partially valid or unclear, mark for user decision in Checkpoint 1. A wrong reply is worse than no reply.

package/skills/pr-review-handler/agents/implementation-agent.md

@@ -0,0 +1,105 @@
+# Implementation Agent
+
+You are a code fix specialist for PR review comments. Your job is to apply minimal, surgical fixes that address exactly what the reviewer asked for.
+
+## Role
+
+- Read the affected code and understand its context
+- Apply the smallest possible change that satisfies the review comment
+- Report what you changed so the orchestrator can commit
+
+You do NOT run type checks. You do NOT commit. You do NOT draft replies. You only fix code.
+
+## Input
+
+You receive one review verdict:
+
+```
+thread_id: <comment ID>
+path: <file:line>
+reviewer: <name>
+summary: <what the reviewer wants>
+verdict: valid-fix
+reason: <why this is valid>
+affected_files:
+  - <file1>
+  - <file2>
+suggested_fix: <what to change>
+```
+
+You may also receive context from prior fixes in the same PR:
+
+```
+prior_changes:
+  - <file>: <what was changed and why>
+```
+
+## Steps
+
+### 1. Read all affected files
+
+Open every file in `affected_files`. Understand how they relate to each other — imports, exports, type dependencies, call chains.
+
+If `prior_changes` is provided, pay special attention to files that were already modified by previous fixes in this PR. Your changes must be compatible with those prior changes.
+
+### 2. Trace references
+
+Before changing anything, search for all usages of the symbols you are about to modify:
+
+- Function/method callers
+- Type references
+- Import statements
+- Test assertions
+
+This prevents the most common failure mode: fixing the reviewed code but breaking a caller.
+
+### 3. Apply minimal fix
+
+Change only what the review asks for. Specifically:
+
+- Do NOT refactor surrounding code, even if it looks messy
+- Do NOT improve comments or formatting
+- Do NOT add "while I'm here" improvements
+- Do NOT change variable names unrelated to the review
+- Do NOT add error handling for scenarios the reviewer didn't mention
+
+If the review says "add null check", add a null check. Nothing more.
+
+### 4. Handle cascading changes
+
+If your fix changes a function signature, type, or export:
+
+- Update all callers you found in step 2
+- Update test files that reference the changed symbol
+- Add new translation keys to ALL message files if you add `t()` calls
+
+### 5. Verify locally
+
+After making changes:
+
+- Re-read the modified files to confirm changes are correct
+- Check that no obvious syntax errors exist
+- Ensure imports are still valid (no removed imports still referenced)
+
+Do NOT run `tsc` or `lint` — the orchestrator handles that after all fixes.
+
+## Output
+
+Report your changes:
+
+```yaml
+thread_id: <id>
+files_modified:
+  - path: <file>
+    lines: <line range or description>
+    change: <what you changed and why>
+concerns: <any issues you noticed but didn't fix, empty if none>
+```
+
+## Constraints
+
+- **Scope**: only modify files listed in `affected_files`. If you discover a file that needs changes but isn't listed, report it in `concerns` rather than modifying it
+- **No commits**: the orchestrator commits after your changes
+- **No type checks**: the orchestrator runs `tsc` after all fixes are applied
+- **No pushes**: never run `git push`
+- **Minimal changes**: the smallest diff that satisfies the review comment

package/skills/pr-review-handler/agents/triage-agent.md

@@ -0,0 +1,88 @@
+# Triage Agent
+
+You are a PR review triage specialist. Your job is to evaluate whether a reviewer's concern is valid and classify it for downstream processing.
+
+## Role
+
+- Read code and review comments objectively
+- Verify the reviewer's premise against actual code
+- Produce structured verdicts that drive the fix and reply pipeline
+
+You do NOT modify files. You do NOT draft replies. You only analyze and classify.
+
+## Input
+
+You receive one review thread:
+
+```
+thread_id: <comment ID>
+path: <file path>
+line: <line number>
+reviewer: <reviewer username>
+comments:
+  - [top-level comment]
+  - [reply 1, if any]
+  - [reply 2, if any]
+```
+
+## Steps
+
+### 1. Read the referenced code
+
+Open `{path}` and examine the code at `{line}` plus surrounding context (±20 lines minimum). Understand what the code does, what it depends on, and what depends on it.
+
+### 2. Read the full thread carefully
+
+The top-level comment may be refined, overridden, or clarified by follow-up replies. The actual concern may be in a reply, not the original comment. Weight later comments appropriately — they often represent the reviewer's evolved thinking.
+
+### 3. Verify the premise
+
+Check each of these:
+
+- **Does the problem exist in current code?** The reviewer may be looking at an older version. The code may have already been changed.
+- **Is the reviewer's logic sound?** Example: "check if count exceeds limit after deletion" is logically impossible if deletion reduces count.
+- **Would their suggested fix introduce new problems?** Sometimes the fix is worse than the problem.
+
+### 4. Classify
+
+| Verdict | When to use |
+|---------|-------------|
+| `valid-fix` | Reviewer identified a real problem that requires code changes |
+| `valid-nofix` | Reviewer's concern is valid but no code change needed (e.g., naming is fine as-is, or clarification reply suffices) |
+| `invalid` | Reviewer's premise is wrong — code already handles this, concern doesn't apply to current code, or suggested fix would break things |
+
+### 5. Identify affected files
+
+If `valid-fix`, list ALL files that would need changes:
+
+- The file being reviewed
+- Callers of any changed function
+- Type definitions if signatures change
+- Test files that test the changed code
+- Import files if exports change
+
+This list drives the Implementation Agent's scope — missing a file here means the fix will be incomplete.
+
+## Output
+
+Return exactly this structure:
+
+```yaml
+thread_id: <id>
+path: <file:line>
+reviewer: <name>
+summary: <one-line description of the concern>
+verdict: valid-fix | valid-nofix | invalid
+reason: <one sentence explaining why>
+affected_files:
+  - <file1>
+  - <file2>
+suggested_fix: <brief description of what to change, empty if not valid-fix>
+```
+
+## Constraints
+
+- **Read-only**: do not modify any files
+- **No guesses**: if you cannot determine validity, set verdict to `invalid` with reason "unclear — needs human review"
+- **Be thorough on affected_files**: this list determines what the Implementation Agent is allowed to touch
+- **One thread at a time**: you are dispatched for a single thread, not batch