From 017c8a8ed4822632e08bf14c00a560684bbbd385 Mon Sep 17 00:00:00 2001
From: keinstn <kei.sj.nstn@gmail.com>
Date: Thu, 25 Jun 2026 05:35:11 +0900
Subject: [PATCH] feat: add review npm script and docs

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 README.md    | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 package.json |  1 +
 2 files changed, 53 insertions(+)

diff --git a/README.md b/README.md
index a236676..7165ab1 100644
--- a/README.md
+++ b/README.md
@@ -252,6 +252,58 @@ npm run triage [TRIAGE.md]
 Running every 30 minutes keeps the `ai-ready` queue populated without human intervention — pair
 it with a Baton instance polling the same board.
 
+## Review (agent PR review)
+
+The `scripts/review/` companion CLI automates the `Agent Review` loop for Baton-managed pull
+requests. It loads `REVIEW.md`, checks the configured GitHub Projects v2 board for issues in the
+review state, and runs the review agent against the current PR head inside an isolated workspace.
+
+**Minimal `REVIEW.md` config**
+
+```yaml
+tracker:
+  token: $GITHUB_TOKEN
+  owner: my-org
+  owner_type: organization
+  project_number: 5
+  status_field: Status
+  active_states: [Agent Review]
+
+workspace:
+  root: ~/baton_review_workspaces
+
+hooks:
+  after_create: |
+    gh repo clone "$BATON_ISSUE_REPO" . -- --depth 50 --no-single-branch
+  before_run: |
+    git fetch origin
+    BRANCH="agent/$BATON_ISSUE_IDENTIFIER"
+    git switch -C "$BRANCH" --track "origin/$BRANCH"
+
+agent:
+  kind: copilot   # or: claude_code
+```
+
+See [`examples/REVIEW.md`](examples/REVIEW.md) for the full reference config with inline
+comments, the review prompt template, and the branch-reset behavior used to review the pushed PR
+head.
+
+**Run once**
+
+```sh
+npm run review [REVIEW.md]
+# or: npx tsx scripts/review/index.ts [REVIEW.md]
+```
+
+**Run on a schedule (cron)**
+
+```sh
+*/5 * * * * cd /path/to/repo && npx tsx scripts/review/index.ts path/to/REVIEW.md
+```
+
+Running every few minutes keeps the review queue moving without manual intervention — pair it with
+a Baton implementation workflow that opens and updates the PR.
+
 ## How it works (one paragraph)
 
 Every `polling.interval_ms`, Baton queries the configured Project board for issues whose Status is
diff --git a/package.json b/package.json
index 66dc514..b6b3925 100644
--- a/package.json
+++ b/package.json
@@ -19,6 +19,7 @@
     "lint": "biome check .",
     "test": "vitest run",
     "triage": "tsx scripts/triage/index.ts",
+    "review": "tsx scripts/review/index.ts",
     "version-packages": "changeset version && npm install --package-lock-only"
   },
   "dependencies": {