@zephyrdeng/pi-review 0.12.1 → 0.13.0

package/extensions/rv-prompts.ts

@@ -52,7 +52,7 @@ export type RvParsed = {
   /** Panel width: independent reviewers for one gate (and each loop round). */
   reviewers?: number;
   reviewersError?: string;
-  /** Named panel preset (e.g. code-experts). Cannot combine with --reviewers. */
+  /** Named panel preset (e.g. code-experts). If both panel and reviewers are set, panel wins. */
   panel?: string;
   /** Per-reviewer model overrides: id=provider/model (repeatable). */
   reviewerModels?: string[];
@@ -403,31 +403,31 @@ export function validateRvParsed(parsed: RvParsed): RvValidation {
   if (parsed.until !== undefined && parsed.strategy !== "loop") {
     return { ok: false, message: "--until is only valid with /rv-loop." };
   }
-  if (parsed.reviewers !== undefined && parsed.panel) {
-    return { ok: false, message: "--reviewers cannot be used with --panel" };
-  }
+  // panel + reviewers is allowed at parse time; builders prefer panel (see preferPanelShape).
   if (parsed.reviewers !== undefined && (parsed.reviewers < 1 || parsed.reviewers > RV_MAX_REVIEWERS)) {
     return { ok: false, message: `--reviewers must be between 1 and ${RV_MAX_REVIEWERS}` };
   }
+  const shape = preferPanelShape(parsed);
   const hasPanelOnlyOptions =
     parsed.consensus !== undefined ||
     parsed.minAgree !== undefined ||
     parsed.consensusModel !== undefined ||
     parsed.concurrency !== undefined ||
     (parsed.reviewerModels?.length ?? 0) > 0;
-  if (parsed.reviewers === 1 && hasPanelOnlyOptions) {
+  if (shape.reviewers === 1 && !shape.panel && hasPanelOnlyOptions) {
     return { ok: false, message: "panel options require --reviewers > 1 or --panel" };
   }
   if (parsed.minAgree !== undefined) {
     if (parsed.consensus && parsed.consensus !== "quorum") {
       return { ok: false, message: "--min-agree is only valid with --consensus quorum" };
     }
-    if (parsed.reviewers !== undefined && parsed.minAgree > parsed.reviewers) {
-      return { ok: false, message: `--min-agree ${parsed.minAgree} cannot exceed reviewers ${parsed.reviewers}` };
+    // Named panels resolve width later; only compare against explicit numeric width.
+    if (shape.reviewers !== undefined && parsed.minAgree > shape.reviewers) {
+      return { ok: false, message: `--min-agree ${parsed.minAgree} cannot exceed reviewers ${shape.reviewers}` };
     }
   }
-  if (parsed.concurrency !== undefined && parsed.reviewers !== undefined && parsed.concurrency > parsed.reviewers) {
-    return { ok: false, message: `--concurrency ${parsed.concurrency} cannot exceed reviewers ${parsed.reviewers}` };
+  if (parsed.concurrency !== undefined && shape.reviewers !== undefined && parsed.concurrency > shape.reviewers) {
+    return { ok: false, message: `--concurrency ${parsed.concurrency} cannot exceed reviewers ${shape.reviewers}` };
   }
   for (const flag of FLAGS_REQUIRING_VALUE) {
     if (parsed.target === flag) {
@@ -445,6 +445,17 @@ export function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'"'"'`)}'`;
 }
 
+/** Prefer named panel over numeric width when both appear (matches CLI/tool soft-resolve). */
+export function preferPanelShape(parsed: Pick<RvParsed, "panel" | "reviewers">): {
+  panel?: string;
+  reviewers?: number;
+} {
+  if (parsed.panel !== undefined && parsed.reviewers !== undefined) {
+    return { panel: parsed.panel };
+  }
+  return { panel: parsed.panel, reviewers: parsed.reviewers };
+}
+
 /** Same optional flags for initial review and --continue follow-up (all optional). */
 export function buildPiReviewArgv(parsed: RvParsed, target: string): string[] {
   const parts = ["pi-review"];
@@ -470,8 +481,9 @@ export function buildPiReviewArgv(parsed: RvParsed, target: string): string[] {
   if (parsed.model) parts.push("--model", parsed.model);
   if (parsed.thinking) parts.push("--thinking", parsed.thinking);
   if (parsed.noStream) parts.push("--no-stream");
-  if (parsed.panel) parts.push("--panel", parsed.panel);
-  if (parsed.reviewers !== undefined) parts.push("--reviewers", String(parsed.reviewers));
+  const shape = preferPanelShape(parsed);
+  if (shape.panel) parts.push("--panel", shape.panel);
+  if (shape.reviewers !== undefined) parts.push("--reviewers", String(shape.reviewers));
   for (const mapping of parsed.reviewerModels ?? []) parts.push("--reviewer-model", mapping);
   if (parsed.consensus) parts.push("--consensus", parsed.consensus);
   if (parsed.minAgree !== undefined) parts.push("--min-agree", String(parsed.minAgree));
@@ -488,12 +500,13 @@ export function formatPiReviewCommandLine(parsed: RvParsed, target: string): str
 
 /** Build the native pi_review tool call instruction without dropping panel config. */
 export function buildPiReviewToolCallInstruction(parsed: RvParsed, target: string): string {
+  const shape = preferPanelShape(parsed);
   const fields: string[] = [
     `target=${JSON.stringify(target)}`,
     `mode=${JSON.stringify(parsed.mode)}`,
   ];
-  if (parsed.panel) fields.push(`panel=${JSON.stringify(parsed.panel)}`);
-  if (parsed.reviewers !== undefined) fields.push(`reviewers=${parsed.reviewers}`);
+  if (shape.panel) fields.push(`panel=${JSON.stringify(shape.panel)}`);
+  if (shape.reviewers !== undefined) fields.push(`reviewers=${shape.reviewers}`);
   if (parsed.reviewerModels?.length) fields.push(`reviewerModels=${JSON.stringify(parsed.reviewerModels)}`);
   if (parsed.consensus) fields.push(`consensus=${JSON.stringify(parsed.consensus)}`);
   if (parsed.minAgree !== undefined) fields.push(`minAgree=${parsed.minAgree}`);
@@ -502,10 +515,10 @@ export function buildPiReviewToolCallInstruction(parsed: RvParsed, target: strin
   if (parsed.model) fields.push(`model=${JSON.stringify(parsed.model)}`);
   if (parsed.thinking) fields.push(`thinking=${JSON.stringify(parsed.thinking)}`);
   // Default panel when /rv has no explicit width/preset: keep code-experts.
-  if (parsed.strategy === "panel" && !parsed.panel && parsed.reviewers === undefined) {
+  if (parsed.strategy === "panel" && !shape.panel && shape.reviewers === undefined) {
     fields.push(`panel=${JSON.stringify("code-experts")}`);
   }
-  return `Call pi_review with ${fields.join(", ")}. Treat target as a natural-language review request. Do not expand directory targets into multi-file lists. Do not drop panel/reviewers/reviewerModels/consensus fields.`;
+  return `Call pi_review with ${fields.join(", ")}. Treat target as a natural-language review request. Do not expand directory targets into multi-file lists. Pass only one of panel or reviewers (if both appear, panel wins). Keep reviewerModels/consensus/minAgree when provided.`;
 }
 
 export function orchestrationLocaleNote(locale: RvLocale = "en"): string {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zephyrdeng/pi-review",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Isolated AI-powered code and plan reviews from the command line",
   "type": "module",
   "author": "ZephyrDeng <zephyrTang@aliyun.com>",

package/skills/pi-review/SKILL.md

@@ -27,7 +27,7 @@ node ../../bin/pi-review.js --help
 |------|-------------------------|
 | **Pi** (`/rv`) | New panel reviews call the native `pi_review` API tool, shown to users as **Pi Review Panel**, which launches the packaged CLI in event mode and renders live reviewer state. Continuations, kept sessions, `/rv-loop`, and explicit `--no-stream` use the shell CLI. |
 | **Pi terminal** | Foreground `pi-review`; text deltas stream live by default. |
-| **Claude Code / Codex / Cursor** and similar agent hosts | These hosts buffer a shell tool's output until the command exits, so a foreground run looks like a silent wait. **Panel review (`--reviewers`/`--panel`) default: `--ui web --ui-url-file <path>` + background run** — get the dashboard in front of the user: on Claude Code the CLI auto-open lands in the system default browser; on Codex open the `--ui-url-file` URL in the host's built-in browser (the CLI cannot reach a GUI there); hand over the URL as fallback either way. **Single review / `loop` default: `--progress-log <path>` + background run + tail the log** (`--ui web` requires an active panel and rejects `loop`). See [references/codex-tools.md](./references/codex-tools.md). Map skill mentions of `Bash` to your host shell tool. |
+| **Claude Code / Codex / Cursor / agy (Antigravity)** and similar agent hosts | These hosts buffer a shell tool's output until the command exits, so a foreground run looks like a silent wait. **Panel review (`--reviewers`/`--panel`) default: `--ui web --ui-url-file <path>` + background run** — get the dashboard in front of the user: on Claude Code the CLI auto-open lands in the system default browser; on Codex open the `--ui-url-file` URL in the host's built-in browser (the CLI cannot reach a GUI there); on agy prefer the host browser / share the URL the same way; hand over the URL as fallback either way. **Single review / `loop` default: `--progress-log <path>` + background run + tail the log** (`--ui web` requires an active panel and rejects `loop`). See [references/codex-tools.md](./references/codex-tools.md). Map skill mentions of `Bash` to your host shell tool. |
 | Scripts / CI | Foreground is fine; add `--no-stream` only when the caller must buffer until exit (cannot combine with `--progress-log`). |
 
 `--progress-log <path>` tees a compact `--mode json` event stream to a file for outside observation and debugging (each `message_update` reduces its cumulative message snapshots to `usage` to keep the file small; add `--progress-log-raw` for the verbatim stream); it is never a prerequisite for metrics. Token usage accumulates by default, and `pi-review` writes milestone notices (`pi-review: review started`, `pi-review: tool <name> started/finished`, `pi-review: review finished`) to stderr.

package/skills/pi-review/references/codex-tools.md

@@ -1,6 +1,6 @@
-# Agent host tool notes (Codex / Claude Code)
+# Agent host tool notes (Codex / Claude Code / Cursor / agy)
 
-Skills may use Claude Code tool names. On **Codex** or **Claude Code**, map them to your native tools:
+Skills may use Claude Code tool names. On **Codex**, **Claude Code**, **Cursor**, or **agy (Antigravity)**, map them to your native tools:
 
 | Skill references | Typical host equivalent |
 |-----------------|-------------------------|
@@ -10,13 +10,13 @@ Skills may use Claude Code tool names. On **Codex** or **Claude Code**, map them
 
 This file is **pi-review–specific** and ships with the pi-review package.
 
-## Long-running `pi-review` (default on Codex / Claude Code)
+## Long-running `pi-review` (default on Codex / Claude Code / Cursor / agy)
 
 Native shell tools on these hosts **buffer stdout/stderr until the command exits**. A multi-minute foreground `pi-review` run looks like a silent wait, then one large dump — never promise live foreground streaming. Which side channel to use depends on the run type: panel review gets the browser dashboard; single review and `loop` get the tailed progress log.
 
 ### Panel review: browser dashboard (default)
 
-`--reviewers <n>` or `--panel <name>` activates panel review. On Codex, Claude Code, or Cursor, default to the dashboard instead of a tailed log:
+`--reviewers <n>` or `--panel <name>` activates panel review. On Codex, Claude Code, Cursor, or agy, default to the dashboard instead of a tailed log:
 
 1. Run `pi-review --reviewers <n> --ui web --ui-url-file <path> -- <target>` (or `--panel <name>`) in the **background**. Pass `--no-ui-open` only when the user asked not to open a browser (CI, remote shells).
 2. Read `<path>` shortly after launch — it is written atomically as soon as the dashboard server is ready, well before reviewers finish (poll a few times a second for a couple of seconds if the file is not there yet). Then get the dashboard in front of the user: on **Claude Code** the CLI auto-open already lands in the system default browser; on **Codex** the CLI cannot reach a GUI browser, so open the URL from `<path>` in the host's built-in browser yourself. Share the URL either way as a fallback: *"Dashboard opened in your browser (URL: `<url>`). I'll report back when the review completes."*
@@ -32,7 +32,7 @@ Native shell tools on these hosts **buffer stdout/stderr until the command exits
 
 **Pi interactive (`/rv`)**: foreground `pi-review`, default streaming. Text deltas appear live on the terminal; no `--progress-log`/`--ui web` unless the user asked — Pi already renders panel progress natively.
 
-See the parent skill: sections *Default workflow by host* and *Streaming vs agent hosts (Claude Code / Codex)*.
+See the parent skill section *Default workflow by host* (Claude Code / Codex / Cursor / agy row).
 
 ### Loop closeout
 

package/skills/pi-review/references/model-selection.md

@@ -2,7 +2,7 @@
 
 Use this after `pi-review models` (or `pi-review models <search>`). **Never invent** `provider/model` IDs—only IDs that appear in that output.
 
-## Workflow (Claude Code, Codex, Cursor, Pi parent agent)
+## Workflow (Claude Code, Codex, Cursor, agy, Pi parent agent)
 
 1. Run `pi-review models` (narrow with search if the user named a vendor or model family).
 2. Infer **review profile** from the target (see table below).