docs: external orchestration frameworks, pr-triage skill, GitHub Actions templates
Added: - guide/third-party-tools.md: External Orchestration Frameworks section (Ruflo + Athena Flow) with architectural distinction from multi-instance tools - examples/skills/pr-triage/: 3-phase PR backlog management skill (audit, deep review via parallel agents, validated comment posting) - examples/github-actions/: claude-code-review.yml + .coderabbit.yaml + prompts/code-review.md — AI-powered PR review GitHub Actions workflow - docs/resource-evaluations/073-athena-flow-workflow-runtime.md (2/5 Watch) - docs/resource-evaluations/074-ruflo-multi-agent-orchestration.md (3/5 Pertinent) Updated: - examples/README.md + examples/github-actions/README.md: new templates indexed - machine-readable/reference.yaml: new entries for github-actions + pr-triage Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
18a6e0ce5c
commit
0bdb34b2a4
12 changed files with 1079 additions and 4 deletions
|
|
@ -17,7 +17,7 @@ Annotated templates that teach you **why** patterns work, not just how to config
|
|||
| [`agents/`](./agents/) | Custom AI personas for specialized tasks | 9 |
|
||||
| [`commands/`](./commands/) | Slash commands (workflow automation) | 26 |
|
||||
| [`hooks/`](./hooks/) | Event-driven security & automation scripts | 31 |
|
||||
| [`skills/`](./skills/) | Reusable knowledge modules — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux) | 13 |
|
||||
| [`skills/`](./skills/) | Reusable knowledge modules — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux) | 14 |
|
||||
| [`claude-md/`](./claude-md/) | CLAUDE.md configuration profiles | 6 |
|
||||
| [`config/`](./config/) | Settings, MCP, git templates | 5 |
|
||||
| [`memory/`](./memory/) | CLAUDE.md memory file templates | 2 |
|
||||
|
|
@ -67,7 +67,7 @@ Annotated templates that teach you **why** patterns work, not just how to config
|
|||
| [implementer.md](./agents/implementer.md) | Mechanical execution — bounded scope | Haiku |
|
||||
| [architecture-reviewer.md](./agents/architecture-reviewer.md) | Architecture & design review — read-only | Opus |
|
||||
|
||||
### Skills (13) — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux)
|
||||
### Skills (14) — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux)
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
|
|
@ -84,6 +84,7 @@ Annotated templates that teach you **why** patterns work, not just how to config
|
|||
| [ccboard/](./skills/ccboard/) | Comprehensive TUI/Web dashboard for Claude Code monitoring |
|
||||
| [guide-recap/](./skills/guide-recap/) | Transform CHANGELOG entries into social content (LinkedIn, Twitter/X, Slack) |
|
||||
| [release-notes-generator/](./skills/release-notes-generator/) | Generate release notes in 3 formats from git commits |
|
||||
| [pr-triage/](./skills/pr-triage/) | 3-phase PR backlog management (audit, deep review, validated comments) |
|
||||
|
||||
### Commands (26)
|
||||
|
||||
|
|
|
|||
51
examples/github-actions/.coderabbit.yaml
Normal file
51
examples/github-actions/.coderabbit.yaml
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
# CodeRabbit configuration — copy to your repo root as .coderabbit.yaml
|
||||
# Docs: https://docs.coderabbit.ai/guides/configure-coderabbit
|
||||
#
|
||||
# CodeRabbit Pro: $15/dev/month — adds Q&A, sequence diagrams, interactive walkthrough
|
||||
# Free tier: unlimited public repos
|
||||
|
||||
reviews:
|
||||
# Language for review comments (default: en)
|
||||
request_changes_workflow: false
|
||||
high_level_summary: true
|
||||
poem: false
|
||||
review_status: true
|
||||
collapse_walkthrough: false
|
||||
|
||||
# Severity labels used in CodeRabbit comments
|
||||
# Maps to: Nitpick, Minor, Major, Critical
|
||||
path_filters:
|
||||
# Ignore generated files and lockfiles
|
||||
- "!**/node_modules/**"
|
||||
- "!**/*.lock"
|
||||
- "!**/dist/**"
|
||||
- "!**/build/**"
|
||||
- "!**/__generated__/**"
|
||||
- "!**/migrations/**" # Remove this if you want DB migration reviews
|
||||
|
||||
path_instructions:
|
||||
# Focus deeper on security-sensitive paths
|
||||
- path: "src/server/api/**"
|
||||
instructions: |
|
||||
Focus on: authentication/authorization checks, input validation,
|
||||
SQL injection risks, rate limiting, and sensitive data exposure.
|
||||
- path: "src/components/**"
|
||||
instructions: |
|
||||
Focus on: React best practices, accessibility (ARIA, keyboard nav),
|
||||
performance (memo, useMemo, unnecessary re-renders), and XSS risks.
|
||||
- path: "prisma/**"
|
||||
instructions: |
|
||||
Focus on: migration safety, index coverage for queried fields,
|
||||
cascade delete risks, and data integrity constraints.
|
||||
|
||||
# Auto-approve low-risk PRs (docs, tests only)
|
||||
auto_review:
|
||||
enabled: true
|
||||
drafts: false
|
||||
base_branches:
|
||||
- main
|
||||
- develop
|
||||
|
||||
chat:
|
||||
# Allow @coderabbitai commands in PR comments
|
||||
auto_reply: true
|
||||
|
|
@ -149,6 +149,91 @@ cp examples/github-actions/claude-issue-triage.yml .github/workflows/
|
|||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## Multi-Model Review Setup
|
||||
|
||||
Running Claude alongside other automated reviewers (Gemini, Greptile, CodeRabbit) surfaces issues that any single model misses. The pattern: each service reviews independently, then Claude synthesizes the consensus.
|
||||
|
||||
**Why multi-model?**
|
||||
Each model has blind spots. Points raised by 2+ independent reviewers are high-signal; unique catches from each model add coverage you'd otherwise miss.
|
||||
|
||||
### Recommended stack ($30/month flat)
|
||||
|
||||
| Service | Cost | Strength |
|
||||
|---------|------|----------|
|
||||
| **Claude Code Review** (this workflow) | Included in Anthropic plan | Deep reasoning, codebase-aware |
|
||||
| **Gemini Code Assist** | $0 (included in Google Workspace) | Independent LLM, different training data |
|
||||
| **Greptile** | ~$30/month flat | Cross-file context, dependency graphs |
|
||||
|
||||
**Alternative**: CodeRabbit Pro ($15/dev/month) adds interactive Q&A and sequence diagrams.
|
||||
|
||||
### Setup
|
||||
|
||||
**Step 1: Install Gemini Code Assist**
|
||||
|
||||
1. GitHub Marketplace → search "Gemini Code Assist"
|
||||
2. Install and authorize on your repo
|
||||
3. Gemini will automatically review new PRs (posts as `gemini-code-assist[bot]`)
|
||||
4. Optional config via `.gemini/config.yaml`:
|
||||
```yaml
|
||||
code_review:
|
||||
comment_severity_threshold: MEDIUM
|
||||
max_comments_per_review: 20
|
||||
```
|
||||
|
||||
**Step 2: Install Greptile**
|
||||
|
||||
1. [greptile.com](https://greptile.com) → connect GitHub account
|
||||
2. Select your repo — Greptile indexes the codebase (~5 min)
|
||||
3. Configure in dashboard: target branches, focus paths
|
||||
4. Reviews post as `greptile[bot]` comments on PRs
|
||||
|
||||
**Step 3: Enable synthesis job**
|
||||
|
||||
In `claude-code-review.yml`, remove `false &&` from the synthesis job condition:
|
||||
|
||||
```yaml
|
||||
# Before (disabled):
|
||||
if: |
|
||||
false &&
|
||||
(github.event_name == 'pull_request' ...
|
||||
|
||||
# After (enabled):
|
||||
if: |
|
||||
(github.event_name == 'pull_request' ...
|
||||
```
|
||||
|
||||
**Step 4: Configure CodeRabbit (optional)**
|
||||
|
||||
Copy `.coderabbit.yaml` from this directory to your repo root. Edit `path_instructions` to match your stack.
|
||||
|
||||
### How the synthesis works
|
||||
|
||||
The `multi-reviewer-synthesis` job in `claude-code-review.yml`:
|
||||
|
||||
1. Waits 5 minutes after the Claude review (external bots post within 2-3 min)
|
||||
2. Collects all reviews and comments via GitHub API
|
||||
3. Skips silently if fewer than 2 reviewers have posted
|
||||
4. Claude identifies consensus (same finding flagged by 2+ reviewers) vs. unique catches
|
||||
5. Posts a structured synthesis comment on the PR
|
||||
|
||||
### Files in this directory
|
||||
|
||||
```
|
||||
examples/github-actions/
|
||||
├── README.md # This file
|
||||
├── claude-code-review.yml # Main review + optional synthesis job
|
||||
├── .coderabbit.yaml # CodeRabbit config (copy to repo root)
|
||||
├── claude-pr-auto-review.yml # Inline prompt auto-review (alternative)
|
||||
├── claude-security-review.yml # Security-focused scan
|
||||
├── claude-issue-triage.yml # Issue triage workflow
|
||||
└── prompts/
|
||||
└── code-review.md # Externalized review prompt (copy to .github/prompts/)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Customization
|
||||
|
||||
### Model Selection
|
||||
|
|
@ -247,8 +332,9 @@ These workflows consume Anthropic API credits:
|
|||
```
|
||||
examples/github-actions/
|
||||
├── README.md # This file
|
||||
├── claude-code-review.yml # Prompt-based review (recommended)
|
||||
├── claude-pr-auto-review.yml # Inline prompt auto-review
|
||||
├── claude-code-review.yml # Prompt-based review + optional synthesis job
|
||||
├── .coderabbit.yaml # CodeRabbit config (copy to repo root)
|
||||
├── claude-pr-auto-review.yml # Inline prompt auto-review (alternative)
|
||||
├── claude-security-review.yml # Security scanning workflow
|
||||
├── claude-issue-triage.yml # Issue triage workflow
|
||||
└── prompts/
|
||||
|
|
|
|||
|
|
@ -74,3 +74,134 @@ jobs:
|
|||
body: '⚠️ **Claude review failed** — Check the Actions log for details. A human reviewer should cover this PR.'
|
||||
});
|
||||
}
|
||||
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
# OPTIONAL: Multi-Reviewer Synthesis
|
||||
#
|
||||
# Enable this job when you have external reviewers posting on PRs:
|
||||
# - Gemini Code Assist (free via Google Workspace)
|
||||
# - Greptile (~$30/month flat, cross-file analysis)
|
||||
# - CodeRabbit Pro ($15/dev/month)
|
||||
#
|
||||
# How it works:
|
||||
# 1. Waits 5 minutes for external reviewers to post their feedback
|
||||
# 2. Collects all reviews and comments via GitHub API
|
||||
# 3. Claude synthesizes: identifies consensus (2+ reviewers) vs. unique catches
|
||||
#
|
||||
# To enable: remove the `if: false` condition below.
|
||||
# To install external reviewers: see examples/github-actions/README.md#multi-model-review
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
multi-reviewer-synthesis:
|
||||
needs: claude-review
|
||||
if: |
|
||||
false &&
|
||||
(
|
||||
(github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
|
||||
(github.event_name == 'issue_comment' &&
|
||||
github.event.issue.pull_request != null &&
|
||||
contains(github.event.comment.body, '/claude-review'))
|
||||
)
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Wait for external reviewers
|
||||
run: |
|
||||
echo "Waiting 5 minutes for external reviewers to post..."
|
||||
sleep 300
|
||||
|
||||
- name: Collect all PR reviews and comments
|
||||
id: collect
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
script: |
|
||||
const prNumber = context.payload.pull_request?.number ?? context.payload.issue?.number;
|
||||
|
||||
// Fetch structured reviews (from Greptile, CodeRabbit, Gemini bots)
|
||||
const { data: reviews } = await github.rest.pulls.listReviews({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
pull_number: prNumber,
|
||||
});
|
||||
|
||||
// Fetch issue comments (bot summaries posted as comments)
|
||||
const { data: comments } = await github.rest.issues.listComments({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: prNumber,
|
||||
});
|
||||
|
||||
const reviewData = reviews
|
||||
.filter(r => r.body && r.body.length > 20)
|
||||
.map(r => ({ reviewer: r.user.login, state: r.state, body: r.body.slice(0, 1500) }));
|
||||
|
||||
const commentData = comments
|
||||
.filter(c => c.body && c.body.length > 50)
|
||||
.map(c => ({ author: c.user.login, body: c.body.slice(0, 1500) }));
|
||||
|
||||
const uniqueReviewers = new Set([
|
||||
...reviewData.map(r => r.reviewer),
|
||||
...commentData.map(c => c.author),
|
||||
]);
|
||||
|
||||
// Skip synthesis if only 1 reviewer posted (no consensus to surface)
|
||||
if (uniqueReviewers.size < 2) {
|
||||
core.setOutput('skip', 'true');
|
||||
core.setOutput('reason', `Only ${uniqueReviewers.size} reviewer found — need 2+ for synthesis`);
|
||||
return;
|
||||
}
|
||||
|
||||
core.setOutput('skip', 'false');
|
||||
core.setOutput('pr_number', prNumber.toString());
|
||||
core.setOutput('data', JSON.stringify({ reviews: reviewData, comments: commentData }));
|
||||
|
||||
- name: Skip notice
|
||||
if: steps.collect.outputs.skip == 'true'
|
||||
run: echo "Synthesis skipped — ${{ steps.collect.outputs.reason }}"
|
||||
|
||||
- name: Claude synthesis
|
||||
if: steps.collect.outputs.skip == 'false'
|
||||
uses: anthropics/claude-code-action@v1
|
||||
with:
|
||||
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
|
||||
model: claude-sonnet-4-6
|
||||
# mcp__github__create_issue_comment posts a plain comment (not a review)
|
||||
allowed_tools: >-
|
||||
mcp__github__create_issue_comment
|
||||
direct_prompt: |
|
||||
You are synthesizing automated code review feedback for PR #${{ steps.collect.outputs.pr_number }}.
|
||||
|
||||
All reviews and comments collected:
|
||||
|
||||
${{ steps.collect.outputs.data }}
|
||||
|
||||
Your task:
|
||||
1. Group findings by theme (security, performance, correctness, architecture)
|
||||
2. Identify consensus: any finding raised by 2+ reviewers is high-signal
|
||||
3. Surface unique catches — important issues only one reviewer flagged
|
||||
4. Post a synthesis using `mcp__github__create_issue_comment` with this structure:
|
||||
|
||||
---
|
||||
## Multi-Reviewer Synthesis
|
||||
|
||||
> Reviewed by: [comma-separated reviewer names]
|
||||
|
||||
### Consensus (raised by 2+ reviewers)
|
||||
| Finding | Reviewers | Severity |
|
||||
|---------|-----------|----------|
|
||||
| [finding] | [name1], [name2] | Must Fix / Should Fix |
|
||||
|
||||
### Unique catches
|
||||
**[Reviewer]:** [what they caught that others missed — critical items only]
|
||||
|
||||
### Recommendation
|
||||
[Overall: approve / request changes / needs discussion]
|
||||
---
|
||||
|
||||
Rules:
|
||||
- Only include consensus findings that are actionable (skip style/nitpick consensus)
|
||||
- For unique catches, only surface items of 🔴 Must Fix or 🟡 Should Fix severity
|
||||
- If all reviewers agree the PR is clean: state that directly and skip the tables
|
||||
|
|
|
|||
|
|
@ -39,6 +39,22 @@ For any file that looks non-trivial, use `Read` to see the full implementation c
|
|||
|
||||
---
|
||||
|
||||
## Step 1b — Load Stack-Specific Skills (Optional)
|
||||
|
||||
If your project has skill guides in `.claude/skills/`, load the relevant ones based on what the diff touches. Run `Read` on matching paths if they exist:
|
||||
|
||||
| If the diff contains... | Load this guide |
|
||||
|------------------------|-----------------|
|
||||
| `auth`, `session`, `token`, `password` | `.claude/skills/security-guardian/authentication/` |
|
||||
| `sql`, `query`, `prisma`, `db` | `.claude/skills/postgres-*/SKILL.md` or your DB guide |
|
||||
| `input`, `form`, `upload`, `file` | `.claude/skills/security-guardian/input-validation/` |
|
||||
| `api`, `endpoint`, `route`, `middleware` | Your API conventions doc |
|
||||
| `payment`, `stripe`, `billing` | Your payment integration guide |
|
||||
|
||||
Skip this step entirely if no matching skills exist or the diff is small.
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — Analyze Changes
|
||||
|
||||
Review each changed file through these lenses:
|
||||
|
|
|
|||
392
examples/skills/pr-triage/SKILL.md
Normal file
392
examples/skills/pr-triage/SKILL.md
Normal file
|
|
@ -0,0 +1,392 @@
|
|||
---
|
||||
name: pr-triage
|
||||
description: >
|
||||
3-phase PR backlog management: audit open PRs, deep review selected ones, draft and post
|
||||
review comments with mandatory validation. Args: "all" to review all, PR numbers to focus
|
||||
(e.g. "42 57"), "en"/"fr" for language, no arg = audit only in French.
|
||||
tags: [github, pr, triage, review, maintainer, multi-agent]
|
||||
---
|
||||
|
||||
# PR Triage
|
||||
|
||||
3-phase workflow for maintainers: automated audit of all open PRs, opt-in deep review via parallel agents, and validated comment posting.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
| Skill | Usage | Output |
|
||||
|-------|-------|--------|
|
||||
| `/pr-triage` | Sort, review, and comment on a PR backlog | Triage table + reviews + posted comments |
|
||||
| `/review-pr` | Review a single PR in depth | Inline PR review |
|
||||
|
||||
**Triggers**:
|
||||
- Manually: `/pr-triage` or `/pr-triage all` or `/pr-triage 42 57`
|
||||
- Proactively: when >5 PRs open without review, or stale PR >14 days detected
|
||||
|
||||
---
|
||||
|
||||
## Language
|
||||
|
||||
- Check the argument passed to the skill
|
||||
- If `en` or `english` → tables and summary in English
|
||||
- If `fr`, `french`, or no argument → French (default)
|
||||
- Note: GitHub comments (Phase 3) are ALWAYS in English (international audience)
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Thresholds used throughout the workflow. Edit to match your project:
|
||||
|
||||
| Parameter | Default | Description |
|
||||
|-----------|---------|-------------|
|
||||
| `staleness_days` | 14 | Days without activity before flagging as stale |
|
||||
| `overlap_threshold` | 50% | Shared files % to flag as overlapping |
|
||||
| `cluster_min_prs` | 3 | Author PR count to trigger cluster suggestion |
|
||||
| `xl_cutoff_additions` | 1000 | Additions above which a PR is classified XL |
|
||||
| `xl_cutoff_files` | 10 | Changed files above which a PR is "too large" |
|
||||
|
||||
---
|
||||
|
||||
## Preconditions
|
||||
|
||||
```bash
|
||||
git rev-parse --is-inside-work-tree
|
||||
gh auth status
|
||||
```
|
||||
|
||||
If either fails, stop and explain what is missing.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Audit (always executed)
|
||||
|
||||
### Data Gathering (parallel commands)
|
||||
|
||||
```bash
|
||||
# Repo identity
|
||||
gh repo view --json nameWithOwner -q .nameWithOwner
|
||||
|
||||
# Open PRs with full metadata (body for cross-reference issues)
|
||||
gh pr list --state open --limit 50 \
|
||||
--json number,title,author,createdAt,updatedAt,additions,deletions,changedFiles,isDraft,mergeable,reviewDecision,statusCheckRollup,body
|
||||
|
||||
# Collaborators (to distinguish internal from external PRs)
|
||||
gh api "repos/{owner}/{repo}/collaborators" --jq '.[].login'
|
||||
```
|
||||
|
||||
**Collaborators fallback**: if `gh api .../collaborators` returns 403/404:
|
||||
```bash
|
||||
# Extract authors from last 10 merged PRs
|
||||
gh pr list --state merged --limit 10 --json author --jq '.[].author.login' | sort -u
|
||||
```
|
||||
If still ambiguous, ask via `AskUserQuestion`.
|
||||
|
||||
For each PR, fetch existing reviews AND changed files:
|
||||
|
||||
```bash
|
||||
gh api "repos/{owner}/{repo}/pulls/{num}/reviews" \
|
||||
--jq '[.[] | .user.login + ":" + .state] | join(", ")'
|
||||
|
||||
# Changed files (required for overlap detection)
|
||||
gh pr view {num} --json files --jq '[.files[].path] | join(",")'
|
||||
```
|
||||
|
||||
**Rate-limiting note**: fetching files requires N API calls (1 per PR). For repos with 20+ PRs, prioritize candidates for overlap detection (same functional domain, same author).
|
||||
|
||||
**Note**: `author` is an object `{login: "..."}` — always extract `.author.login`.
|
||||
|
||||
### Analysis
|
||||
|
||||
**Size classification**:
|
||||
| Label | Additions |
|
||||
|-------|-----------|
|
||||
| XS | < 50 |
|
||||
| S | 50–200 |
|
||||
| M | 200–500 |
|
||||
| L | 500–1000 |
|
||||
| XL | > 1000 |
|
||||
|
||||
Size format: `+{additions}/-{deletions}, {files} files ({label})`
|
||||
|
||||
**Detections**:
|
||||
- **Overlaps**: compare file lists across PRs — if >50% files in common → cross-reference
|
||||
- **Clusters**: author with 3+ open PRs → suggest review order (smallest first)
|
||||
- **Staleness**: no activity for >14 days → flag "stale"
|
||||
- **CI status**: via `statusCheckRollup` → `clean` / `unstable` / `dirty`
|
||||
- **Reviews**: approved / changes_requested / none
|
||||
|
||||
**PR ↔ Issue linking**:
|
||||
- Scan each PR `body` for `fixes #N`, `closes #N`, `resolves #N` (case-insensitive)
|
||||
- If found, display in the table: `Fixes #42` in the Action/Status column
|
||||
|
||||
**Categorization**:
|
||||
|
||||
_Internal PRs_: author in collaborators list
|
||||
|
||||
_External — Ready_: additions ≤ 1000 AND files ≤ 10 AND `mergeable` ≠ `CONFLICTING` AND CI clean/unstable
|
||||
|
||||
_External — Problematic_: any of:
|
||||
- additions > 1000 OR files > 10
|
||||
- OR `mergeable` == `CONFLICTING` (merge conflict)
|
||||
- OR CI dirty (statusCheckRollup contains failures)
|
||||
- OR overlap with another open PR (>50% shared files)
|
||||
|
||||
### Output — Triage Table
|
||||
|
||||
```
|
||||
## Open PRs ({count})
|
||||
|
||||
### Internal PRs
|
||||
| PR | Title | Size | CI | Status |
|
||||
| -- | ----- | ---- | -- | ------ |
|
||||
|
||||
### External — Ready for Review
|
||||
| PR | Author | Title | Size | CI | Reviews | Action |
|
||||
| -- | ------ | ----- | ---- | -- | ------- | ------ |
|
||||
|
||||
### External — Problematic
|
||||
| PR | Author | Title | Size | Problem | Recommended Action |
|
||||
| -- | ------ | ----- | ---- | ------- | ------------------ |
|
||||
|
||||
### Summary
|
||||
- Quick wins: {XS/S PRs ready to merge}
|
||||
- Risks: {overlaps, XL sizes, CI dirty}
|
||||
- Clusters: {authors with 3+ PRs}
|
||||
- Stale: {PRs with no activity >14d}
|
||||
- Overlaps: {PRs touching the same files}
|
||||
```
|
||||
|
||||
0 PRs → display `No open PRs.` and stop.
|
||||
|
||||
### Automatic Copy
|
||||
|
||||
After displaying the triage table, copy to clipboard using platform-appropriate command:
|
||||
|
||||
```bash
|
||||
# Detect platform and copy
|
||||
UNAME=$(uname -s)
|
||||
if [ "$UNAME" = "Darwin" ]; then
|
||||
pbcopy <<'EOF'
|
||||
{full triage table}
|
||||
EOF
|
||||
elif command -v xclip &>/dev/null; then
|
||||
echo "{full triage table}" | xclip -selection clipboard
|
||||
elif command -v wl-copy &>/dev/null; then
|
||||
echo "{full triage table}" | wl-copy
|
||||
elif command -v clip.exe &>/dev/null; then
|
||||
echo "{full triage table}" | clip.exe
|
||||
fi
|
||||
```
|
||||
|
||||
Confirm: `Triage table copied to clipboard.` (EN) / `Tableau copié dans le presse-papier.` (FR)
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Deep Review (opt-in)
|
||||
|
||||
### PR Selection
|
||||
|
||||
**If argument passed**:
|
||||
- `"all"` → all external PRs
|
||||
- Numbers (`"42 57"`) → only those PRs
|
||||
- No argument → propose via `AskUserQuestion`
|
||||
|
||||
**If no argument**, display:
|
||||
|
||||
```
|
||||
question: "Which PRs do you want to review in depth?"
|
||||
header: "Deep Review"
|
||||
multiSelect: true
|
||||
options:
|
||||
- label: "All external"
|
||||
description: "Review {N} external PRs with parallel code-reviewer agents"
|
||||
- label: "Problematic only"
|
||||
description: "Focus on {M} risky PRs (CI dirty, too large, overlaps)"
|
||||
- label: "Ready only"
|
||||
description: "Review {K} PRs ready to merge"
|
||||
- label: "Skip"
|
||||
description: "Stop here — audit only"
|
||||
```
|
||||
|
||||
**Draft PR behavior**:
|
||||
- Draft PRs are EXCLUDED from "All external" and "Ready only"
|
||||
- Draft PRs are INCLUDED in "Problematic only" (they need attention)
|
||||
- To review a draft: type its number explicitly (e.g. `42`)
|
||||
|
||||
If "Skip" → end workflow.
|
||||
|
||||
### Executing Reviews
|
||||
|
||||
For each selected PR, launch a `code-reviewer` agent via **Task tool in parallel**:
|
||||
|
||||
```
|
||||
subagent_type: code-reviewer
|
||||
model: sonnet
|
||||
prompt: |
|
||||
Review PR #{num}: "{title}" by @{author}
|
||||
|
||||
**Metadata**: +{additions}/-{deletions}, {changedFiles} files ({size_label})
|
||||
**CI**: {ci_status} | **Reviews**: {existing_reviews} | **Draft**: {isDraft}
|
||||
|
||||
**PR Body**:
|
||||
{body}
|
||||
|
||||
**Diff**:
|
||||
{gh pr diff {num} output}
|
||||
|
||||
Apply your security and architecture expertise. Use the project-specific checklist
|
||||
from the SKILL.md Configuration section if available.
|
||||
|
||||
Return structured review:
|
||||
### Critical Issues
|
||||
### Important Issues
|
||||
### Suggestions
|
||||
### What's Good
|
||||
|
||||
Be specific: quote file:line, explain the issue, suggest the fix.
|
||||
```
|
||||
|
||||
**Fallback if parallel agents unavailable**: run reviews sequentially, one PR at a time. Notify user: `Running sequential review (parallel agents not available).`
|
||||
|
||||
Fetch diff via:
|
||||
```bash
|
||||
gh pr diff {num}
|
||||
gh pr view {num} --json body,title,author -q '{body: .body, title: .title, author: .author.login}'
|
||||
```
|
||||
|
||||
Aggregate all reports. Display a summary after all reviews complete.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Comments (mandatory validation)
|
||||
|
||||
### Draft Generation
|
||||
|
||||
For each reviewed PR, generate a GitHub comment using the template `templates/review-comment.md`.
|
||||
|
||||
**Rules**:
|
||||
- Language: **English** (international audience)
|
||||
- Tone: professional, constructive, factual
|
||||
- Always include at least 1 positive point
|
||||
- Quote code lines when relevant (format `file:42`)
|
||||
|
||||
### Display and Validation
|
||||
|
||||
**Display ALL drafted comments** in format:
|
||||
|
||||
```
|
||||
---
|
||||
### Draft — PR #{num}: {title}
|
||||
|
||||
{full comment}
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
Then request validation via `AskUserQuestion`:
|
||||
|
||||
```
|
||||
question: "These comments are ready. Which ones do you want to post?"
|
||||
header: "Post Comments"
|
||||
multiSelect: true
|
||||
options:
|
||||
- label: "All ({N} comments)"
|
||||
description: "Post on all reviewed PRs"
|
||||
- label: "PR #{x} — {title_truncated}"
|
||||
description: "Post only on this PR"
|
||||
- label: "None"
|
||||
description: "Cancel — post nothing"
|
||||
```
|
||||
|
||||
(Generate one option per PR + "All" + "None")
|
||||
|
||||
### Posting
|
||||
|
||||
For each validated comment:
|
||||
|
||||
```bash
|
||||
gh pr comment {num} --body-file - <<'REVIEW_EOF'
|
||||
{comment}
|
||||
REVIEW_EOF
|
||||
```
|
||||
|
||||
Confirm each post: `Comment posted on PR #{num}: {title}`
|
||||
|
||||
If "None" → `No comments posted. Workflow complete.`
|
||||
|
||||
---
|
||||
|
||||
## Project-Specific Checklist
|
||||
|
||||
Add your stack's checklist to the agent prompt in Phase 2. Examples by stack:
|
||||
|
||||
**Node.js / TypeScript**:
|
||||
- No `any` type without explicit justification
|
||||
- `async/await` error handling (try/catch or `.catch()`)
|
||||
- No unhandled promise rejections
|
||||
- Input validation at API boundaries
|
||||
|
||||
**Python**:
|
||||
- Type hints on all public functions
|
||||
- Exception specificity (no bare `except:`)
|
||||
- Resource cleanup (`with` statements, context managers)
|
||||
- No mutable default arguments
|
||||
|
||||
**Rust**:
|
||||
- `Result<T, E>` with `.context()` for error chain (no `.unwrap()` in production code)
|
||||
- No `clone()` on hot paths without justification
|
||||
- `lazy_static!` or `once_cell` for static regex
|
||||
- Lifetime annotations where ownership is non-obvious
|
||||
|
||||
**Go**:
|
||||
- Explicit error handling (no `_` discard without comment)
|
||||
- `defer` for resource cleanup
|
||||
- Context propagation in concurrent code
|
||||
- No goroutine leaks
|
||||
|
||||
**Generic** (stack-agnostic):
|
||||
- No secrets or hardcoded credentials
|
||||
- New public functions have tests
|
||||
- Breaking changes documented in PR body
|
||||
- Dependencies added have clear justification
|
||||
|
||||
---
|
||||
|
||||
## Edge Cases
|
||||
|
||||
| Situation | Behavior |
|
||||
|-----------|----------|
|
||||
| 0 open PRs | Display `No open PRs.` + stop |
|
||||
| Draft PR | Show in table, skip for review unless explicitly selected |
|
||||
| Unknown CI | Display `?` in CI column |
|
||||
| Review agent timeout | Show partial error, continue with others |
|
||||
| `gh pr diff` empty | Skip this PR, notify user |
|
||||
| Very large PR (>5000 additions) | Warn: "Partial review, diff truncated" |
|
||||
| Collaborators API 403/404 | Fallback to last 10 merged PR authors |
|
||||
| Parallel agents unavailable | Run sequential reviews, notify user |
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Always derive owner/repo via `gh repo view`, never hardcode
|
||||
- Use `gh` CLI (not `curl` GitHub API) except for collaborators list
|
||||
- `statusCheckRollup` can be null → treat as `?`
|
||||
- `mergeable` can be `MERGEABLE`, `CONFLICTING`, or `UNKNOWN` → treat `UNKNOWN` as `?`
|
||||
- Never post without explicit user validation in chat
|
||||
- Drafted comments must be visible BEFORE any `gh pr comment`
|
||||
|
||||
---
|
||||
|
||||
## Related: /review-pr
|
||||
|
||||
| | `/pr-triage` | `/review-pr` |
|
||||
|--|-------------|--------------|
|
||||
| **Scope** | Full PR backlog | Single PR |
|
||||
| **Use when** | Catching up after accumulation, periodic triage | Reviewing a specific incoming PR |
|
||||
| **Phases** | 3 (audit + deep review + comments) | 1 (review only) |
|
||||
| **Agents** | Parallel sub-agents per PR | Single session |
|
||||
| **Output** | Triage table + review reports + GitHub comments | Inline review |
|
||||
| **Validation** | AskUserQuestion before posting | Manual decision |
|
||||
|
||||
**Decision rule**: use `/pr-triage` for backlog triage (5+ PRs), `/review-pr` for focused review of a single PR.
|
||||
62
examples/skills/pr-triage/templates/review-comment.md
Normal file
62
examples/skills/pr-triage/templates/review-comment.md
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
# Review Comment Template
|
||||
|
||||
Use this template to generate GitHub PR review comments. Fill in each section based on the code-reviewer agent output. Comments are posted in **English** (international audience).
|
||||
|
||||
---
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
## Review
|
||||
|
||||
**Scope**: Security, code quality, performance, test coverage, architecture
|
||||
|
||||
### Summary
|
||||
|
||||
{1–2 sentences: overall assessment. Be direct — what's the main takeaway?}
|
||||
|
||||
### Critical Issues
|
||||
|
||||
{List blocking issues that must be fixed before merge. For each:}
|
||||
{- `file:42` — Description of the problem. Why it matters. Suggested fix.}
|
||||
|
||||
{If none: "None found."}
|
||||
|
||||
### Important Issues
|
||||
|
||||
{List significant issues that should be fixed. For each:}
|
||||
{- `file:42` — Description. Why it matters. Suggested fix.}
|
||||
|
||||
{If none: "None found."}
|
||||
|
||||
### Suggestions
|
||||
|
||||
{List nice-to-haves and minor improvements. For each:}
|
||||
{- Description. Context. Optional fix.}
|
||||
|
||||
{If none: omit this section.}
|
||||
|
||||
### What's Good
|
||||
|
||||
{Always include at least 1 positive point. Be specific — what works well and why.}
|
||||
{- Description of what's done right.}
|
||||
|
||||
---
|
||||
*Automated review via Claude Code `/pr-triage` — add your project-specific checks in SKILL.md*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Formatting Rules
|
||||
|
||||
**Citation format**: `file:42` or `` `code snippet` `` for inline references
|
||||
|
||||
**Issue severity**:
|
||||
- Critical: security vulnerability, data loss risk, broken functionality, missing test for new feature
|
||||
- Important: error handling gap, performance regression, scope creep, missing validation
|
||||
- Suggestion: naming, DRY opportunity, documentation, style
|
||||
|
||||
**Tone**: Professional, constructive, factual. Challenge the code, not the person.
|
||||
No superlatives ("great", "amazing", "perfect"). No filler ("as mentioned", "it's worth noting").
|
||||
|
||||
**Length**: Aim for 200–400 words. Long enough to be useful, short enough to be read.
|
||||
Loading…
Add table
Add a link
Reference in a new issue