From e2ba3dd0990d31167f48bfd0f33f273f0e426514 Mon Sep 17 00:00:00 2001
From: Andrew Ridgway <ar17787@gmail.com>
Date: Tue, 18 Aug 2026 22:03:39 +1000
Subject: [PATCH] docs: document pr_reviewer manual-trigger workflow in
 AGENTS.md

The pr_reviewer webhook only fires on PR open and does not re-trigger on
branch updates or recall. Document the manual API trigger and the loop of
posting the review + response to the PR as comments, so future sessions
can iterate on reviews.

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
---
 AGENTS.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 05be289..5feeec8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -341,6 +341,50 @@ All three must pass for merges to main.
 - Look at test examples in `tests/` for testing patterns
 - Check `.github/workflows/ci.yml` for what CI expects
 
+## PR Review Workflow (pr_reviewer)
+
+The `pr_reviewer` service (deployed in the `pr-reviewer` namespace, NodePort 30001) reviews pull requests on `git.aridgwayweb.com`. **Important:** the webhook only fires on PR *open* — it does **not** re-trigger on branch updates or recall. To iterate on a review, you must **manually trigger** the review via the API, then write both the review output and your response to the PR as comments.
+
+### Manual trigger
+
+```bash
+# 1. Gather the changed file contents
+# 2. POST to the review endpoint with the files
+curl -X POST http://192.168.178.160:30001/api/v1/review \
+  -H "Content-Type: application/json" \
+  -d '{
+    "pr_id": "1",
+    "title": "<PR title>",
+    "repo": {"name": "armistace/steward_mirror", "url": "https://git.aridgwayweb.com/armistace/steward_mirror"},
+    "source": {"branch": "feat/matrix-appservice"},
+    "target": {"branch": "main"},
+    "files": [{"path": "steward/bot/core.py", "status": "modified", "content": "<file contents>"}]
+  }'
+```
+
+The response contains `results.code_review`, `results.security_review`, `results.infra_review`, and `results.summary`.
+
+### Posting results to the PR
+
+The webhook does not post the manual review to the PR. You must post it yourself via the gitea API:
+
+```bash
+TOKEN="<gitea token>"
+# Post the review output
+curl -X POST -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
+  -d "{\"body\": \"<review text>\"}" \
+  "https://git.aridgwayweb.com/api/v1/repos/armistace/steward_mirror/issues/1/comments"
+# Post your response addressing each finding
+```
+
+### Iteration loop
+
+1. Manually trigger the review (above) with the current branch's file contents.
+2. Post the review output to the PR as a comment.
+3. Fix the actionable findings, commit, and push to the branch.
+4. Post a response comment addressing each finding (fixed / already handled / deferred).
+5. Re-trigger the review manually and repeat until the review passes.
+
 ## Key Files to Know
 
 | File | Purpose |