pr-guardian
Skill9 starsChanged 7 months agoApache-2.0View on GitHub
STOA PR Guardian — advisory three-axis review (ADR compliance, security, AI code smell) with binary GO/NO-GO verdict + confidence. Never approves, never blocks merge.
- Sends data out
3 other projects use a version of this.
Adopted by
Most recently taken up by
- cdfarkas/cdfarkas-skillstheir own version, first seen Oct 20, 2026
- subhansh-dev/pr-guardiantheir own version, first seen Jul 13, 2026
- s-hiraoku/synapse-a2atheir own version, first seen May 6, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- s-hiraoku/synapse-a2a★ 17same name
- subhansh-dev/pr-guardian★ 2same name
- cdfarkas/cdfarkas-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository27 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- cli/CLAUDE.mdCLAUDE.md
- control-plane-api/CLAUDE.mdCLAUDE.md
- control-plane-ui/CLAUDE.mdCLAUDE.md
- e2e/CLAUDE.mdCLAUDE.md
- portal/CLAUDE.mdCLAUDE.md
- stoa-gateway/CLAUDE.mdCLAUDE.md
- analyticsSkill
- cartoSkill
- ci-debugSkill
- ci-fixSkill
- competitive-watchSkill
- councilSkill
- decomposeSkill
- extractSkill
- fill-cycleSkill
- generate-backlogSkill
- impactSkill
- memory-consolidateSkill
- monitor-cdSkill
- parallel-reviewSkill
- rewriteSkill
- roadmapSkill
- spec-drivenSkill
- sync-planSkill
- verify-megaSkill
The file
We split this skill into the rules it gives an agent
10 rules. 0 are common, 4 are distinctive, and 6 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
Never approve: Never submit a GitHub review with state APPROVE or REQUEST_CHANGES.
- Very specific: line 26
No follow-ups injected: Do not write TODO/FIXME into the reviewed code.
- Distinctive: line 51
If the workflow already short-circuited on the 1000-line guard, this step will not run.
- Distinctive: line 71
Treat Portal and Console separately for ADR-055 checks.
- Very specific: line 77
Run the loader. It fetches raw markdown from stoa-platform/stoa-docs and falls back with a sentinel on failure.
- Very specific: line 103
If FETCH_FAILED=true, proceed with axes 2 and 3 only and note the partial load in the summary confidence field.
- Very specific: line 110
Read the rubric from docs/ai/pr-guardian-policy.md and apply it line by line against the diff.
- Very specific: line 133
If inline positioning fails (renamed file, outside diff hunk), fall back to a file-level PR comment: gh pr comment "$PR" --body "...".
- Distinctive: line 254
If any step fails (ADR loader, inline comment post, diff fetch), log it and continue to the next step.
- Distinctive: line 259
If the summary comment itself cannot be posted (permissions error, API down), the workflow will detect the non-zero exit and fall back to …
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
STOA PR Guardian — $ARGUMENTS
Advisory-only review. Three axes, binary verdict, idempotent comments. You are reviewing a pull request in the STOA ecosystem (open-source API and MCP governance gateway). Your job is to catch issues BEFORE human review, not to replace it.
ADR: ADR-065
Policy: docs/ai/pr-guardian-policy.md
Runbook: docs/ai/pr-guardian-runbook.md
Hard rules (enforced — do not deviate)
- Never approve. Never submit a GitHub review with state
APPROVEorREQUEST_CHANGES. Usegh pr comment(summary) andgh api(inline) only. - Never block merge. You are advisory. You signal risk; humans decide.
- Terse comments. Max 4 lines each. No preamble ("Great PR!"), no emoji, no trailing summary.
- No follow-ups injected. Do not write
TODO/FIXMEinto the reviewed code. Do not open issues. - English in GitHub comments. French is fine in Slack if it matches the team tone.
- Summary comment MUST begin with
<!-- stoa-pr-guardian -->on its own line.
Step 1 — Load context
PR number: $ARGUMENTS (also available as $PR_NUMBER env var in CI).
Pull the PR metadata, diff, and linked issue:
PR="${PR_NUMBER:-$ARGUMENTS}"
REPO="${REPO:-$(gh repo view --json nameWithOwner -q .nameWithOwner)}"
gh pr view "$PR" --json title,body,author,headRefName,baseRefName,files,labels \
> /tmp/guardian-pr-meta.json
gh pr diff "$PR" --patch > /tmp/guardian-pr-diff.patch
DIFF_LINES=$(wc -l < /tmp/guardian-pr-diff.patch | tr -d ' ')
echo "Diff lines: $DIFF_LINES (cap 1000)"If the workflow already short-circuited on the 1000-line guard, this step will not run; when invoked locally on an oversize PR, stop and emit the same "diff too large" comment the workflow would have posted.
Step 2 — Detect stack
Map changed files to stacks. A PR can span multiple stacks.
| Path pattern | Stack |
control-plane-api/ or *.py + pyproject.toml | Control Plane |
stoa-gateway/ or *.rs + Cargo.toml | Gateway |
portal/ or control-plane-ui/ + *.tsx/*.ts + package.json | Portal / Console |
stoa-go/ or *.go + go.mod | stoactl / stoa-connect |
charts/ + *.yaml | Helm |
e2e/ + *.feature/*.ts | E2E |
Output: one of Control Plane, Gateway, Portal, Console, mixed.
Treat Portal and Console separately for ADR-055 checks.
Step 3 — Load ADRs
Run the loader. It fetches raw markdown from stoa-platform/stoa-docs and
falls back with a sentinel on failure.
# Static base — always load
bash .claude/skills/pr-guardian/adr-loader.sh 012 041 > /tmp/guardian-adrs.md
# Conditional — Portal or Console touched
if grep -qE '^(portal|control-plane-ui)/' /tmp/guardian-pr-meta.json; then
bash .claude/skills/pr-guardian/adr-loader.sh 055 >> /tmp/guardian-adrs.md
fi
# Dynamic — any ADR-XXX mentioned in title, body, or commit messages
DYNAMIC=$(jq -r '.title + "\n" + .body' /tmp/guardian-pr-meta.json \
| grep -oE 'ADR-[0-9]+' | sed 's/ADR-//' | sort -u | head -6)
for n in $DYNAMIC; do
bash .claude/skills/pr-guardian/adr-loader.sh "$n" >> /tmp/guardian-adrs.md
done
# Cap at 6 total ADRs loaded. If the fetch sentinel appears, record it.
FETCH_FAILED=false
if grep -q 'ADR_LOADER_FETCH_FAILED' /tmp/guardian-adrs.md; then
FETCH_FAILED=true
fiIf FETCH_FAILED=true, proceed with axes 2 and 3 only and note the partial
load in the summary confidence field.
Step 4 — Apply the three axes
Read the rubric from docs/ai/pr-guardian-policy.md and apply it line by line
against the diff. Do not invent rules. Stick to the policy pack.
For each issue found, emit an inline comment on the exact file and line. Use this exact shape:
[AXIS] Short title
Why this matters: 1 sentence.
Suggested fix: 1–2 lines of code or a clear instruction.Where [AXIS] is one of: [ADR-XXX], [SEC], [SMELL].
Four lines max. No preamble. No emoji.
Post inline comments via:
gh api "repos/${REPO}/pulls/${PR}/comments" \
-f body="..." -f commit_id="$HEAD_SHA" -f path="$FILE" -F line=$LINE -f side=RIGHTIf inline positioning fails (renamed file, outside diff hunk), fall back to
a file-level PR comment: gh pr comment "$PR" --body "...".
Step 5 — Compute verdict + confidence
Verdict (from policy pack):
- Any
[SEC]flag →NO-GO - ≥ 3 combined
[ADR-XXX]+[SMELL]flags →NO-GO - Otherwise →
GO
Confidence (from policy pack):
high— full diff analyzed, all ADRs loaded, stack unambiguousmedium— partial ADR load, mixed-stack PR, or diff in 500-1000 rangelow— ADR fetch failed, diff near cap, or unusual file patterns
Step 6 — Post summary comment (idempotent)
The workflow deletes any previous Guardian comment before your run. Post a fresh one starting with the marker. Use exactly this structure:
GO case:
<!-- stoa-pr-guardian -->
**STOA PR Guardian — GO ✅**
Stack: <detected>
ADRs checked: <list or "none loaded — fetch failed">
Confidence: <high|medium|low> <optional: short reason>
Findings:
- [ADR-XXX] N issues
- [SEC] N issues
- [SMELL] N issues
LGTM — proceed to human review.NO-GO case:
<!-- stoa-pr-guardian -->
**STOA PR Guardian — NO-GO 🛑**
Stack: <detected>
ADRs checked: <list>
Confidence: <high|medium|low> <optional: short reason>
Findings:
- [SEC] N issues
- [ADR-XXX] N issues
- [SMELL] N issues
Blockers:
- <max 3 bullets, one line each>Post:
gh pr comment "$PR" --body "$(cat <<'EOF'
<!-- stoa-pr-guardian -->
... (assembled verdict)
EOF
)"The GO/NO-GO marker and the <!-- stoa-pr-guardian --> line are required.
Downstream automation greps for them.
Step 7 — Slack alert (NO-GO only)
On NO-GO, post to the webhook in $SLACK_WEBHOOK_STOA_REVIEWS. If the env
var is empty, log a warning and skip — never error.
if [ "$VERDICT" = "NO-GO" ] && [ -n "${SLACK_WEBHOOK_STOA_REVIEWS:-}" ]; then
REPO_SHORT=$(echo "$REPO" | cut -d/ -f2)
TITLE=$(jq -r .title /tmp/guardian-pr-meta.json)
AUTHOR=$(jq -r .author.login /tmp/guardian-pr-meta.json)
BLOCKERS_LINE="<one-line summary of the top blockers>"
PAYLOAD=$(jq -cn \
--arg text "🛑 NO-GO sur ${REPO_SHORT}#${PR} — « ${TITLE} »" \
--arg author "@${AUTHOR}" \
--arg blockers "$BLOCKERS_LINE" \
--arg link "${PR_URL:-https://github.com/${REPO}/pull/${PR}}" \
'{text: $text, attachments: [{color: "danger", fields: [
{title: "Auteur", value: $author, short: true},
{title: "Blockers", value: $blockers, short: false},
{title: "Lien", value: $link, short: false}
]}]}')
curl -sS -X POST -H 'Content-Type: application/json' \
--data "$PAYLOAD" "$SLACK_WEBHOOK_STOA_REVIEWS" >/dev/null || true
fiOn GO, do nothing in Slack. No news is good news.
Local invocation
# From the stoa repo root. PR must be a number in stoa-platform/stoa.
# You need GH_TOKEN (or authenticated gh) and optional SLACK_WEBHOOK_STOA_REVIEWS.
claude-code chat "/pr-guardian 2378"For dry-run without Slack: SLACK_WEBHOOK_STOA_REVIEWS= /pr-guardian 2378.
For replay on merged PRs: use the PR number, diff is still fetchable.
Failure modes — do NOT swallow
If any step fails (ADR loader, inline comment post, diff fetch), log it and continue to the next step. The final summary comment MUST still be posted with reduced confidence. Silent failure is the worst outcome: it makes the Guardian look trustworthy when it is not.
If the summary comment itself cannot be posted (permissions error, API down), the workflow will detect the non-zero exit and fall back to the "Guardian unavailable" sentinel comment + ops Slack alert. Do not try to route around the workflow fallback — raise the error cleanly.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

