agentleFS
stoa-platformstoa-platform/stoa/.claude/skills/pr-guardian/SKILL.md

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

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
  1. Very specific:

    Never approve: Never submit a GitHub review with state APPROVE or REQUEST_CHANGES.

    line 23
  2. Very specific:

    No follow-ups injected: Do not write TODO/FIXME into the reviewed code.

    line 26
  3. Distinctive:

    If the workflow already short-circuited on the 1000-line guard, this step will not run.

    line 51
  4. Distinctive:

    Treat Portal and Console separately for ADR-055 checks.

    line 71
  5. Very specific:

    Run the loader. It fetches raw markdown from stoa-platform/stoa-docs and falls back with a sentinel on failure.

    line 77
  6. Very specific:

    If FETCH_FAILED=true, proceed with axes 2 and 3 only and note the partial load in the summary confidence field.

    line 103
  7. Very specific:

    Read the rubric from docs/ai/pr-guardian-policy.md and apply it line by line against the diff.

    line 110
  8. Very specific:

    If inline positioning fails (renamed file, outside diff hunk), fall back to a file-level PR comment: gh pr comment "$PR" --body "...".

    line 133
  9. Distinctive:

    If any step fails (ADR loader, inline comment post, diff fetch), log it and continue to the next step.

    line 254
  10. Distinctive:

    If the summary comment itself cannot be posted (permissions error, API down), the workflow will detect the non-zero exit and fall back to …

    line 259

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 APPROVE or REQUEST_CHANGES. Use gh pr comment (summary) and gh 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/FIXME into 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 patternStack
control-plane-api/ or *.py + pyproject.tomlControl Plane
stoa-gateway/ or *.rs + Cargo.tomlGateway
portal/ or control-plane-ui/ + *.tsx/*.ts + package.jsonPortal / Console
stoa-go/ or *.go + go.modstoactl / stoa-connect
charts/ + *.yamlHelm
e2e/ + *.feature/*.tsE2E

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
fi

If 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=RIGHT

If 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 unambiguous
  • medium — partial ADR load, mixed-stack PR, or diff in 500-1000 range
  • low — 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
fi

On 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.