npm - @trashcodermaker/pi-pr-review-handler - Versions diffs - 1.0.8 → 1.1.0 - Mend

@trashcodermaker/pi-pr-review-handler 1.0.8 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +22 -143
package/package.json +10 -7
package/{SKILL.md → skills/pr-review-handler/SKILL.md} +12 -12
package/README.zh.md +0 -169
/package/{agents → skills/pr-review-handler/agents}/implementation-agent.md +0 -0
/package/{agents → skills/pr-review-handler/agents}/triage-agent.md +0 -0

package/README.md CHANGED Viewed

@@ -1,169 +1,48 @@
-# PR Review Handler
+# @trashcodermaker/pi-pr-review-handler
-> Systematically process GitHub PR review comments: triage for validity, fix code, and post replies.
+> Pi package — systematically process GitHub PR review comments: triage, fix, reply.
-[![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)
-⭐ 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)
-[中文版](./README.zh.md)
-## 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
+Install with Pi:
 ```bash
-npm install @trashcodermaker/pi-pr-review-handler
+pi install npm:@trashcodermaker/pi-pr-review-handler
 ```
-### Install as a Pi package
-```bash
-pi install @trashcodermaker/pi-pr-review-handler
-```
+Pi auto-discovers the skill under `skills/pr-review-handler/`. Once installed, invoke it from your Pi session with natural language like "handle the reviews on my PR" or `/skill:pr-review-handler`.
-### Install from skill.sh
+## What it does
-```bash
-npx skills add JI4JUN/pr-review-handler
-```
+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.
-### From source
-```bash
-git clone https://github.com/JI4JUN/pr-review-handler.git
-cd pr-review-handler
-npm install
-```
+## Requirements
-> [!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.
+- 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
 ## 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 → Phase 1: Triage (parallel) → Phase 2: Fix (serial)
+         → Phase 3: Reply → 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`.
+Checkpoints pause for confirmation after triage verdicts and before posting replies.
-### Phase 2: Fix
+## Other platforms
-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:
+This is the Pi-scoped package. If you use Claude Code, Cursor, Gemini CLI, OpenCode, or another harness, install the generic package instead:
 ```bash
-npx tsc --noEmit
+npm install pr-review-handler
 ```
-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.
+Or grab the skill directly:
-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
+```bash
+npx skills add JI4JUN/pr-review-handler
 ```
-## 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
+## License
-- 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.
+MIT

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@trashcodermaker/pi-pr-review-handler",
-  "version": "1.0.8",
-  "description": "Systematically process GitHub PR review comments: triage for validity, fix code, and post replies.",
+  "version": "1.1.0",
+  "description": "Systematically process GitHub PR review comments: triage for validity, fix code, and post replies. Pi package — install with `pi install npm:@trashcodermaker/pi-pr-review-handler`.",
   "type": "module",
   "license": "MIT",
   "private": false,
@@ -10,21 +10,24 @@
     "pi-skill",
     "pr-review",
     "github",
-    "code-review"
+    "code-review",
+    "agentskills"
   ],
   "publishConfig": {
     "access": "public"
   },
   "files": [
-    "SKILL.md",
-    "agents",
+    "skills",
     "README.md",
-    "README.zh.md",
     "LICENSE"
   ],
+  "scripts": {
+    "prepublishOnly": "node ../../scripts/sync-skill.mjs ."
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/JI4JUN/pr-review-handler.git"
+    "url": "https://github.com/JI4JUN/pr-review-handler.git",
+    "directory": "packages/pi"
   },
   "homepage": "https://github.com/JI4JUN/pr-review-handler#readme",
   "bugs": {

package/{SKILL.md → skills/pr-review-handler/SKILL.md} RENAMED Viewed

@@ -37,17 +37,19 @@ Checkpoints: after Phase 1 (user confirms verdicts) and after Phase 3 (user appr
 ### Platform mapping
-Each role maps to a different agent depending on the platform. Agent specs for reference are in `agents/` relative to this skill.
+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.
-| 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 |
+| 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) |
-**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).
+**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.
-**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.
+**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
@@ -142,9 +144,7 @@ comments:
   - <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.
+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
@@ -189,7 +189,7 @@ 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.
+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:

package/README.zh.md DELETED Viewed

@@ -1,169 +0,0 @@
-# PR Review Handler
-> 系统地处理 GitHub PR review 评论：判断有效性、修复代码、发布回复。
-[![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 上点个 star！
-[项目简介](#项目简介) • [快速开始](#快速开始) • [工作原理](#工作原理) • [使用方法](#使用方法) • [环境要求](#环境要求) • [支持的平台](#支持的平台)
-[English version](./README.md)
-## 项目简介
-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/{agents → skills/pr-review-handler/agents}/implementation-agent.md RENAMED Viewed

File without changes

/package/{agents → skills/pr-review-handler/agents}/triage-agent.md RENAMED Viewed

File without changes