@trashcodermaker/pi-pr-review-handler 1.0.0

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,176 @@
+<!-- prettier-ignore -->
+<div align="center">
+
+<!-- No project-specific icon found; skip the header image. -->
+
+# PR Review Handler
+
+[![Build Status](https://img.shields.io/github/actions/workflow/status/JI4JUN/pr-review-handler/ci.yml?style=flat-square&label=Build)](https://github.com/JI4JUN/pr-review-handler/actions)
+[![npm version](https://img.shields.io/npm/v/@trashcodermaker/pi-pr-review-handler?style=flat-square)](https://www.npmjs.com/package/@trashcodermaker/pi-pr-review-handler)
+[![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
+
+> Systematically process GitHub PR review comments: triage for validity, fix code, and post replies.
+>
+> [中文版](./README.zh.md)
+
+⭐ If you like this project, star it on GitHub — it helps a lot!
+
+[Overview](#overview) • [Getting started](#getting-started) • [How it works](#how-it-works) • [Usage](#usage) • [Requirements](#requirements) • [Supported platforms](#supported-platforms)
+
+</div>
+
+## Overview
+
+Code review is part of every healthy PR workflow, but turning review threads into actual fixes and thoughtful replies can be tedious and error-prone.
+
+**PR Review Handler** automates that workflow. It fetches unresolved GitHub PR review threads, evaluates each comment for validity, applies minimal code fixes, drafts replies that match the reviewer's language and tone, and optionally pushes changes and requests re-review.
+
+It can be used as an npm package, a Pi package, a Pi skill, or embedded into other agent environments. The project ships agent specifications in `agents/` so each platform can run the pipeline with its own task/dispatch mechanism.
+
+## Getting started
+
+### Install as an npm package
+
+```bash
+npm install @trashcodermaker/pi-pr-review-handler
+```
+
+### Install as a Pi package
+
+```bash
+pi install @trashcodermaker/pi-pr-review-handler
+```
+
+### Install from skill.sh
+
+```bash
+npx skills add JI4JUN/pr-review-handler
+```
+
+### From source
+
+```bash
+git clone https://github.com/JI4JUN/pr-review-handler.git
+cd pr-review-handler
+npm install
+```
+
+> [!IMPORTANT]
+> Ensure GitHub CLI (`gh`) is installed and authenticated before using this skill or package. Most commands depend on it to read PR data and post replies.
+
+## How it works
+
+The handler runs a multi-phase pipeline. Each phase has a clear responsibility, and the flow stops at checkpoints where human confirmation is requested.
+
+```
+Phase 0: Setup
+Phase 1: Triage        ← parallel, read-only
+Phase 2: Fix           ← serial, minimal changes
+Phase 3: Reply         ← orchestrator drafts inline
+Phase 4: Post & Push
+Phase 5: Report
+```
+
+### Phase 0: Setup
+
+Identifies the target PR from the current branch or an explicit PR link, fetches unresolved review threads, and fetches review-level feedback. This phase prepares everything needed for triage without modifying code.
+
+### Phase 1: Triage
+
+Reads the referenced code and each review thread, then classifies every comment as:
+
+- `valid-fix` — a real issue that requires code changes
+- `valid-nofix` — the concern is valid, but no code change is needed
+- `invalid` — the premise doesn't apply to current code, or the suggested fix would be harmful
+
+If there are many threads and the platform supports parallel agents, triage runs in parallel for speed.
+
+> [!TIP]
+> Triage is intentionally conservative. If a comment is unclear, mark it `invalid` with the reason `unclear — needs human review`.
+
+### Phase 2: Fix
+
+For each `valid-fix` thread, a specialized implementation agent applies the smallest possible change that satisfies the review. The agent traces references first, updates callers and tests when signatures change, and avoids unrelated cleanup or refactors.
+
+All fixes are committed locally, but **never pushed** during this phase.
+
+After all fixes:
+
+```bash
+npx tsc --noEmit
+```
+
+If type checking fails, the pipeline identifies the offending commit, reverts it, fixes the issue, and recommits before continuing.
+
+### Phase 3: Reply
+
+The orchestrator drafts one reply per thread based on:
+
+- Original thread data
+- Triage verdicts
+- Actual diff: `git diff origin/{branch}...HEAD`
+- Failure records from Phase 2
+
+Replies are matched to the reviewer's language and tone, kept concise, and never defensive.
+
+### Phase 4: Post & Push
+
+Approved replies are posted to GitHub, and all local review-fix commits are pushed in one step.
+
+Optionally, the handler can also:
+
+- Request re-review from the original reviewers
+- Dismiss resolved review threads with an "Addressed" message
+
+### Phase 5: Report
+
+A concise summary is printed at the end:
+
+```
+✅ 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
+```
+
+## Usage
+
+### In an agent
+
+When installed as a skill, invoke it from your agent with natural language. Examples:
+
+- "帮我处理这个 PR 的 review：<https://github.com/owner/repo/pull/123>"
+- "回复 reviewer 的评论"
+- "看看 PR 里那些 unresolved threads"
+- "review 提的问题要修一下"
+- "CI 过了，但 review 还没回"
+- "someone left comments on my PR"
+- "帮我看看那些人提的意见"
+
+### From the command line
+
+If you want to drive the workflow manually, you can use the GitHub CLI commands directly. The skill and package primarily wrap these operations into an agent-friendly pipeline.
+
+## 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
+
+## Supported platforms
+
+| Platform | Support |
+| --- | --- |
+| npm / Node.js | ✅ Install as a published package |
+| Pi | ✅ Supported as a package and as a skill |
+| Claude Code | ✅ Task-based agent dispatch |
+| Cursor | ✅ Background agent dispatch |
+| Other agent clients | ✅ Inline fallback using the agent specs in `agents/` |
+
+## Notes
+
+- Agent specs are provided in `agents/` for reuse across platforms.
+- When a platform supports parallel agents, triage can run in parallel; otherwise it runs inline.
+- There are two checkpoints where execution pauses for confirmation: after triage verdicts, and before posting replies.
+- Pushes only happen once, after replies are approved.
+- The implementation phase is serial by default to avoid conflicting file changes.

package/README.zh.md

@@ -0,0 +1,176 @@
+<!-- prettier-ignore -->
+<div align="center">
+
+<!-- 项目中未发现专用图标，因此跳过顶部图片。 -->
+
+# PR Review Handler
+
+[![Build Status](https://img.shields.io/github/actions/workflow/status/JI4JUN/pr-review-handler/ci.yml?style=flat-square&label=Build)](https://github.com/JI4JUN/pr-review-handler/actions)
+[![npm version](https://img.shields.io/npm/v/@trashcodermaker/pi-pr-review-handler?style=flat-square)](https://www.npmjs.com/package/@trashcodermaker/pi-pr-review-handler)
+[![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
+
+> 系统地处理 GitHub PR review 评论：判断有效性、修复代码、发布回复。
+>
+> [English version](./README.md)
+
+⭐ 如果这个项目对你有帮助，欢迎在 GitHub 上点个 star！
+
+[项目简介](#项目简介) • [快速开始](#快速开始) • [工作原理](#工作原理) • [使用方法](#使用方法) • [环境要求](#环境要求) • [支持的平台](#支持的平台)
+
+</div>
+
+## 项目简介
+
+Code Review 是健康 PR 流程的一部分，但把 review 评论转化为实际修复和得体温回复往往既繁琐又容易出错。
+
+**PR Review Handler** 用自动化流程解决这个问题。它会抓取 GitHub PR 中未关闭的 review 线程，逐条判断评论是否成立，对有效问题做最小化代码修复，生成与评论者语言、语气一致的回复，并在确认后推送变更、请求 re-review。
+
+它可以作为 npm 包、Pi 包、Pi skill，或嵌入到其他 agent 环境使用。项目在 `agents/` 中提供 agent 规格，因此不同平台可以用自己的任务/调度机制运行同一套流水线。
+
+## 快速开始
+
+### 作为 npm 包安装
+
+```bash
+npm install @trashcodermaker/pi-pr-review-handler
+```
+
+### 作为 Pi 包安装
+
+```bash
+pi install @trashcodermaker/pi-pr-review-handler
+```
+
+### 通过 skill.sh 安装
+
+```bash
+npx skills add JI4JUN/pr-review-handler
+```
+
+### 从源码安装
+
+```bash
+git clone https://github.com/JI4JUN/pr-review-handler.git
+cd pr-review-handler
+npm install
+```
+
+> [!IMPORTANT]
+> 使用本 skill 或包之前，请确保已安装并登录 GitHub CLI（`gh`）。读取 PR 数据、发布回复等核心操作都依赖它。
+
+## 工作原理
+
+整个流程由多个阶段组成，每个阶段职责清晰；在需要人工确认的位置会设置 checkpoint 暂停执行。
+
+```
+Phase 0: Setup
+Phase 1: Triage        ← 并行，只读
+Phase 2: Fix           ← 串行，最小修改
+Phase 3: Reply         ← 由编排器直接起草
+Phase 4: Post & Push
+Phase 5: Report
+```
+
+### Phase 0: Setup
+
+根据当前分支或显式 PR 链接定位目标 PR，抓取未关闭的 review 线程，并补充抓取 review 级别的整体反馈。本阶段只做数据准备，不修改代码。
+
+### Phase 1: Triage
+
+读取评论所指代码和完整 review 线程后，逐条将评论分类为：
+
+- `valid-fix` — 存在真实问题，需要代码修改
+- `valid-nofix` — 问题成立，但不需要改代码
+- `invalid` — 前提不适用于当前代码，或建议的修复反而有害
+
+如果线程很多且平台支持并行 agent，Triage 会并行执行以提高速度。
+
+> [!TIP]
+> Triage 默认偏保守。如果某条评论含义不清，可直接标记为 `invalid`，原因写 `unclear — needs human review`。
+
+### Phase 2: Fix
+
+对每条 `valid-fix` 线程，由专门的 implementation agent 施加满足 review 要求的最小改动。修改前先追踪引用关系；如果改动影响函数签名、类型或导出，会同步更新调用方和测试；不顺手做无关的重构或清理。
+
+本阶段所有修复都会提交到本地，但 **不会推送**。
+
+全部修复完成后会执行：
+
+```bash
+npx tsc --noEmit
+```
+
+如果类型检查失败，流程会自动定位引入错误的提交，回滚、修复后重新提交，再继续后续阶段。
+
+### Phase 3: Reply
+
+编排器基于以下信息逐条起草回复：
+
+- 原始线程数据
+- Triage 结论
+- 实际变更：`git diff origin/{branch}...HEAD`
+- Phase 2 中的失败记录
+
+回复会尽量匹配评论者的语言和语气，保持简洁，避免防御性措辞。
+
+### Phase 4: Post & Push
+
+将用户确认后的回复发布到 GitHub，并把本地的 review-fix 提交统一推送。
+
+可选地，流程还可以：
+
+- 向原 reviewer 请求 re-review
+- 将已处理的 review 线程标记为“Addressed”并关闭
+
+### Phase 5: Report
+
+最后输出简要总结：
+
+```
+✅ Triage: N/N 条线程已处理
+✅ Fixes: M/K 条 valid-fix 已应用（本地提交并推送）
+   ❌ Failed: {thread} — {reason}
+✅ Replies: P/P 条回复已起草并发布
+```
+
+## 使用方法
+
+### 在 agent 中调用
+
+安装为 skill 后，直接用自然语言发起请求即可。常见触发方式包括：
+
+- "帮我处理这个 PR 的 review：<https://github.com/owner/repo/pull/123>"
+- "回复 reviewer 的评论"
+- "看看 PR 里那些 unresolved threads"
+- "review 提的问题要修一下"
+- "CI 过了，但 review 还没回"
+- "someone left comments on my PR"
+- "帮我看看那些人提的意见"
+
+### 命令行手动驱动
+
+如果你希望手动控制流程，也可以直接基于 GitHub CLI 命令执行。本 skill 和包的主要价值，是把这些命令封装成 agent 可理解、可执行的结构化流水线。
+
+## 环境要求
+
+- 已安装并登录 GitHub CLI（`gh`）
+- Git 工作区足够干净，可以创建 review-fix 提交
+- 若想执行最后的 `tsc --noEmit` 检查，项目应为 Node.js / TypeScript 项目
+
+## 支持的平台
+
+| 平台 | 支持情况 |
+| --- | --- |
+| npm / Node.js | ✅ 可作为已发布包安装 |
+| Pi | ✅ 支持作为 package 和 skill 使用 |
+| Claude Code | ✅ 通过 Task 机制分发 agent |
+| Cursor | ✅ 通过 background agent 分发 |
+| 其他 agent 客户端 | ✅ 使用 `agents/` 中的 agent 规格，以内联方式运行 |
+
+## 备注
+
+- 项目在 `agents/` 中提供可复用的 agent 规格。
+- 若平台支持并行 agent，Triage 可并行执行；否则以内联方式运行。
+- 流程中有两处会暂停等待确认：一次在 Triage 结论出来后，一次在发布回复前。
+- 推送仅在回复确认后执行一次。
+- Fix 阶段默认串行执行，以避免并发修改带来的冲突。

package/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
+
+Each role maps to a different agent depending on the platform. Agent specs for reference are in `agents/` relative to this skill.
+
+| Role | Pi | Claude Code | Cursor | No-agent fallback |
+|------|-----|-------------|--------|-------------------|
+| Triage | `pr-review.triage` | Task tool | background agent | inline (read spec, execute yourself) |
+| Implementation | `pr-review.implementation` | Task tool | background agent | inline (read spec, execute yourself) |
+| Reply | inline (orchestrator) | inline | inline | inline |
+
+**Pi users**: runtime agents are registered in `.agents/agents/pr-review/` at the project root. They include full system prompts, tool constraints, and output format — dispatch with task prompt containing only the input data (thread info, verdict data).
+
+**Other platforms**: read the agent specs in `agents/` relative to this skill (`agents/triage-agent.md`, `agents/implementation-agent.md`), embed the instructions into the task prompt, and dispatch using your available subtask mechanism. If no subtask mechanism exists, execute inline.
+
+## 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>
+```
+
+The agent already has its role instructions and output format built in. Do not embed role instructions in the task prompt — only pass 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>
+```
+
+The agent already has its role instructions and output format built in. Pass only 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/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/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

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@trashcodermaker/pi-pr-review-handler",
+  "version": "1.0.0",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-skill",
+    "pr-review",
+    "github",
+    "code-review"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "SKILL.md",
+    "agents",
+    "README.md",
+    "LICENSE"
+  ]
+}