From 0a485924757174995a7bd6feae5b2da6e20bc58d Mon Sep 17 00:00:00 2001 From: Gustavo Madeira Santana Date: Thu, 5 Feb 2026 19:36:25 -0500 Subject: [PATCH] add PR review workflow templates --- .agents/skills/merge-pr/SKILL.md | 185 ++++++++++++++ .agents/skills/merge-pr/agents/openai.yaml | 4 + .agents/skills/prepare-pr/SKILL.md | 248 +++++++++++++++++++ .agents/skills/prepare-pr/agents/openai.yaml | 4 + .agents/skills/review-pr/SKILL.md | 228 +++++++++++++++++ .agents/skills/review-pr/agents/openai.yaml | 4 + 6 files changed, 673 insertions(+) create mode 100644 .agents/skills/merge-pr/SKILL.md create mode 100644 .agents/skills/merge-pr/agents/openai.yaml create mode 100644 .agents/skills/prepare-pr/SKILL.md create mode 100644 .agents/skills/prepare-pr/agents/openai.yaml create mode 100644 .agents/skills/review-pr/SKILL.md create mode 100644 .agents/skills/review-pr/agents/openai.yaml diff --git a/.agents/skills/merge-pr/SKILL.md b/.agents/skills/merge-pr/SKILL.md new file mode 100644 index 000000000..83e3eb473 --- /dev/null +++ b/.agents/skills/merge-pr/SKILL.md @@ -0,0 +1,185 @@ +--- +name: merge-pr +description: Merge a GitHub PR via squash after /preparepr. Use when asked to merge a ready PR. Do not push to main or modify code. Ensure the PR ends in MERGED state and clean up worktrees after success. +--- + +# Merge PR + +## Overview + +Merge a prepared PR via `gh pr merge --squash` and clean up the worktree after success. + +## Inputs + +- Ask for PR number or URL. +- If missing, auto-detect from conversation. +- If ambiguous, ask. + +## Safety + +- Use `gh pr merge --squash` as the only path to `main`. +- Do not run `git push` at all during merge. +- Do not run gateway stop commands. Do not kill processes. Do not touch port 18792. + +## Execution Rule + +- Execute the workflow. Do not stop after printing the TODO checklist. +- If delegating, require the delegate to run commands and capture outputs. + +## Known Footguns + +- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/Development/openclaw`, not `~/openclaw`. +- Read `.local/review.md` and `.local/prep.md` in the worktree. Do not skip. +- Clean up the real worktree directory `.worktrees/pr-` only after a successful merge. +- Expect cleanup to remove `.local/` artifacts. + +## Completion Criteria + +- Ensure `gh pr merge` succeeds. +- Ensure PR state is `MERGED`, never `CLOSED`. +- Record the merge SHA. +- Run cleanup only after merge success. + +## First: Create a TODO Checklist + +Create a checklist of all merge steps, print it, then continue and execute the commands. + +## Setup: Use a Worktree + +Use an isolated worktree for all merge work. + +```sh +cd ~/Development/openclaw +# Sanity: confirm you are in the repo +git rev-parse --show-toplevel + +WORKTREE_DIR=".worktrees/pr-" +``` + +Run all commands inside the worktree directory. + +## Load Local Artifacts (Mandatory) + +Expect these files from earlier steps: + +- `.local/review.md` from `/reviewpr` +- `.local/prep.md` from `/preparepr` + +```sh +ls -la .local || true + +if [ -f .local/review.md ]; then + echo "Found .local/review.md" + sed -n '1,120p' .local/review.md +else + echo "Missing .local/review.md. Stop and run /reviewpr, then /preparepr." + exit 1 +fi + +if [ -f .local/prep.md ]; then + echo "Found .local/prep.md" + sed -n '1,120p' .local/prep.md +else + echo "Missing .local/prep.md. Stop and run /preparepr first." + exit 1 +fi +``` + +## Steps + +1. Identify PR meta + +```sh +gh pr view --json number,title,state,isDraft,author,headRefName,baseRefName,headRepository,body --jq '{number,title,state,isDraft,author:.author.login,head:.headRefName,base:.baseRefName,headRepo:.headRepository.nameWithOwner,body}' +contrib=$(gh pr view --json author --jq .author.login) +head=$(gh pr view --json headRefName --jq .headRefName) +head_repo_url=$(gh pr view --json headRepository --jq .headRepository.url) +``` + +2. Run sanity checks + +Stop if any are true: + +- PR is a draft. +- Required checks are failing. +- Branch is behind main. + +```sh +# Checks +gh pr checks + +# Check behind main +git fetch origin main +git fetch origin pull//head:pr- +git merge-base --is-ancestor origin/main pr- || echo "PR branch is behind main, run /preparepr" +``` + +If anything is failing or behind, stop and say to run `/preparepr`. + +3. Merge PR and delete branch + +If checks are still running, use `--auto` to queue the merge. + +```sh +# Check status first +check_status=$(gh pr checks 2>&1) +if echo "$check_status" | grep -q "pending\|queued"; then + echo "Checks still running, using --auto to queue merge" + gh pr merge --squash --delete-branch --auto + echo "Merge queued. Monitor with: gh pr checks --watch" +else + gh pr merge --squash --delete-branch +fi +``` + +If merge fails, report the error and stop. Do not retry in a loop. +If the PR needs changes beyond what `/preparepr` already did, stop and say to run `/preparepr` again. + +4. Get merge SHA + +```sh +merge_sha=$(gh pr view --json mergeCommit --jq '.mergeCommit.oid') +echo "merge_sha=$merge_sha" +``` + +5. Optional comment + +Use a literal multiline string or heredoc for newlines. + +```sh +gh pr comment -F - <<'EOF' +Merged via squash. + +- Merge commit: $merge_sha + +Thanks @$contrib! +EOF +``` + +6. Verify PR state is MERGED + +```sh +gh pr view --json state --jq .state +``` + +7. Clean up worktree only on success + +Run cleanup only if step 6 returned `MERGED`. + +```sh +cd ~/Development/openclaw + +git worktree remove ".worktrees/pr-" --force + +git branch -D temp/pr- 2>/dev/null || true +git branch -D pr- 2>/dev/null || true +``` + +## Guardrails + +- Worktree only. +- Do not close PRs. +- End in MERGED state. +- Clean up only after merge success. +- Never push to main. Use `gh pr merge --squash` only. +- Do not run `git push` at all in this command. diff --git a/.agents/skills/merge-pr/agents/openai.yaml b/.agents/skills/merge-pr/agents/openai.yaml new file mode 100644 index 000000000..9c10ae4d2 --- /dev/null +++ b/.agents/skills/merge-pr/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Merge PR" + short_description: "Merge GitHub PRs via squash" + default_prompt: "Use $merge-pr to merge a GitHub PR via squash after preparation." diff --git a/.agents/skills/prepare-pr/SKILL.md b/.agents/skills/prepare-pr/SKILL.md new file mode 100644 index 000000000..82c07759b --- /dev/null +++ b/.agents/skills/prepare-pr/SKILL.md @@ -0,0 +1,248 @@ +--- +name: prepare-pr +description: Prepare a GitHub PR for merge by rebasing onto main, fixing review findings, running gates, committing fixes, and pushing to the PR head branch. Use after /reviewpr. Never merge or push to main. +--- + +# Prepare PR + +## Overview + +Prepare a PR branch for merge with review fixes, green gates, and an updated head branch. + +## Inputs + +- Ask for PR number or URL. +- If missing, auto-detect from conversation. +- If ambiguous, ask. + +## Safety + +- Never push to `main` or `origin/main`. Push only to the PR head branch. +- Never run `git push` without specifying remote and branch explicitly. Do not run bare `git push`. +- Do not run gateway stop commands. Do not kill processes. Do not touch port 18792. +- Do not run `git clean -fdx`. +- Do not run `git add -A` or `git add .`. Stage only specific files changed. + +## Execution Rule + +- Execute the workflow. Do not stop after printing the TODO checklist. +- If delegating, require the delegate to run commands and capture outputs. + +## Known Footguns + +- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/openclaw`. +- Do not run `git clean -fdx`. +- Do not run `git add -A` or `git add .`. + +## Completion Criteria + +- Rebase PR commits onto `origin/main`. +- Fix all BLOCKER and IMPORTANT items from `.local/review.md`. +- Run gates and pass. +- Commit prep changes. +- Push the updated HEAD back to the PR head branch. +- Write `.local/prep.md` with a prep summary. +- Output exactly: `PR is ready for /mergepr`. + +## First: Create a TODO Checklist + +Create a checklist of all prep steps, print it, then continue and execute the commands. + +## Setup: Use a Worktree + +Use an isolated worktree for all prep work. + +```sh +cd ~/openclaw +# Sanity: confirm you are in the repo +git rev-parse --show-toplevel + +WORKTREE_DIR=".worktrees/pr-" +``` + +Run all commands inside the worktree directory. + +## Load Review Findings (Mandatory) + +```sh +if [ -f .local/review.md ]; then + echo "Found review findings from /reviewpr" +else + echo "Missing .local/review.md. Run /reviewpr first and save findings." + exit 1 +fi + +# Read it +sed -n '1,200p' .local/review.md +``` + +## Steps + +1. Identify PR meta (author, head branch, head repo URL) + +```sh +gh pr view --json number,title,author,headRefName,baseRefName,headRepository,body --jq '{number,title,author:.author.login,head:.headRefName,base:.baseRefName,headRepo:.headRepository.nameWithOwner,body}' +contrib=$(gh pr view --json author --jq .author.login) +head=$(gh pr view --json headRefName --jq .headRefName) +head_repo_url=$(gh pr view --json headRepository --jq .headRepository.url) +``` + +2. Fetch the PR branch tip into a local ref + +```sh +git fetch origin pull//head:pr- +``` + +3. Rebase PR commits onto latest main + +```sh +# Move worktree to the PR tip first +git reset --hard pr- + +# Rebase onto current main +git fetch origin main +git rebase origin/main +``` + +If conflicts happen: + +- Resolve each conflicted file. +- Run `git add ` for each file. +- Run `git rebase --continue`. + +If the rebase gets confusing or you resolve conflicts 3 or more times, stop and report. + +4. Fix issues from `.local/review.md` + +- Fix all BLOCKER and IMPORTANT items. +- NITs are optional. +- Keep scope tight. + +Keep a running log in `.local/prep.md`: + +- List which review items you fixed. +- List which files you touched. +- Note behavior changes. + +5. Update `CHANGELOG.md` if flagged in review + +Check `.local/review.md` section H for guidance. +If flagged and user-facing: + +- Check if `CHANGELOG.md` exists. + +```sh +ls CHANGELOG.md 2>/dev/null +``` + +- Follow existing format. +- Add a concise entry with PR number and contributor. + +6. Update docs if flagged in review + +Check `.local/review.md` section G for guidance. +If flagged, update only docs related to the PR changes. + +7. Commit prep fixes + +Stage only specific files: + +```sh +git add ... +``` + +Preferred commit tool: + +```sh +committer "fix: (#) (thanks @$contrib)" +``` + +If `committer` is not found: + +```sh +git commit -m "fix: (#) (thanks @$contrib)" +``` + +8. Run full gates before pushing + +```sh +pnpm install +pnpm build +pnpm ui:build +pnpm check +pnpm test +``` + +Require all to pass. If something fails, fix, commit, and rerun. Allow at most 3 fix and rerun cycles. If gates still fail after 3 attempts, stop and report the failures. Do not loop indefinitely. + +9. Push updates back to the PR head branch + +```sh +# Ensure remote for PR head exists +git remote add prhead "$head_repo_url.git" 2>/dev/null || git remote set-url prhead "$head_repo_url.git" + +# Use force with lease after rebase +# Double check: $head must NOT be "main" or "master" +echo "Pushing to branch: $head" +if [ "$head" = "main" ] || [ "$head" = "master" ]; then + echo "ERROR: head branch is main/master. This is wrong. Stopping." + exit 1 +fi +git push --force-with-lease prhead HEAD:$head +``` + +10. Verify PR is not behind main (Mandatory) + +```sh +git fetch origin main +git fetch origin pull//head:pr--verify --force +git merge-base --is-ancestor origin/main pr--verify && echo "PR is up to date with main" || echo "ERROR: PR is still behind main, rebase again" +git branch -D pr--verify 2>/dev/null || true +``` + +If still behind main, repeat steps 2 through 9. + +11. Write prep summary artifacts (Mandatory) + +Update `.local/prep.md` with: + +- Current HEAD sha from `git rev-parse HEAD`. +- Short bullet list of changes. +- Gate results. +- Push confirmation. +- Rebase verification result. + +Create or overwrite `.local/prep.md` and verify it exists and is non-empty: + +```sh +git rev-parse HEAD +ls -la .local/prep.md +wc -l .local/prep.md +``` + +12. Output + +Include a diff stat summary: + +```sh +git diff --stat origin/main..HEAD +git diff --shortstat origin/main..HEAD +``` + +Report totals: X files changed, Y insertions(+), Z deletions(-). + +If gates passed and push succeeded, print exactly: + +``` +PR is ready for /mergepr +``` + +Otherwise, list remaining failures and stop. + +## Guardrails + +- Worktree only. +- Do not delete the worktree on success. `/mergepr` may reuse it. +- Do not run `gh pr merge`. +- Never push to main. Only push to the PR head branch. +- Run and pass all gates before pushing. diff --git a/.agents/skills/prepare-pr/agents/openai.yaml b/.agents/skills/prepare-pr/agents/openai.yaml new file mode 100644 index 000000000..290b1b5ab --- /dev/null +++ b/.agents/skills/prepare-pr/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Prepare PR" + short_description: "Prepare GitHub PRs for merge" + default_prompt: "Use $prepare-pr to prep a GitHub PR for merge without merging." diff --git a/.agents/skills/review-pr/SKILL.md b/.agents/skills/review-pr/SKILL.md new file mode 100644 index 000000000..00cef64ac --- /dev/null +++ b/.agents/skills/review-pr/SKILL.md @@ -0,0 +1,228 @@ +--- +name: review-pr +description: Review-only GitHub pull request analysis with the gh CLI. Use when asked to review a PR, provide structured feedback, or assess readiness to land. Do not merge, push, or make code changes you intend to keep. +--- + +# Review PR + +## Overview + +Perform a thorough review-only PR assessment and return a structured recommendation on readiness for /preparepr. + +## Inputs + +- Ask for PR number or URL. +- If missing, always ask. Never auto-detect from conversation. +- If ambiguous, ask. + +## Safety + +- Never push to `main` or `origin/main`, not during review, not ever. +- Do not run `git push` at all during review. Treat review as read only. +- Do not stop or kill the gateway. Do not run gateway stop commands. Do not kill processes on port 18792. + +## Execution Rule + +- Execute the workflow. Do not stop after printing the TODO checklist. +- If delegating, require the delegate to run commands and capture outputs, not a plan. + +## Known Failure Modes + +- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/openclaw`. +- Do not stop after printing the checklist. That is not completion. + +## Writing Style for Output + +- Write casual and direct. +- Avoid em dashes and en dashes. Use commas or separate sentences. + +## Completion Criteria + +- Run the commands in the worktree and inspect the PR directly. +- Produce the structured review sections A through J. +- Save the full review to `.local/review.md` inside the worktree. + +## First: Create a TODO Checklist + +Create a checklist of all review steps, print it, then continue and execute the commands. + +## Setup: Use a Worktree + +Use an isolated worktree for all review work. + +```sh +cd ~/Development/openclaw +# Sanity: confirm you are in the repo +git rev-parse --show-toplevel + +WORKTREE_DIR=".worktrees/pr-" +git fetch origin main + +# Reuse existing worktree if it exists, otherwise create new +if [ -d "$WORKTREE_DIR" ]; then + cd "$WORKTREE_DIR" + git checkout temp/pr- 2>/dev/null || git checkout -b temp/pr- + git fetch origin main + git reset --hard origin/main +else + git worktree add "$WORKTREE_DIR" -b temp/pr- origin/main + cd "$WORKTREE_DIR" +fi + +# Create local scratch space that persists across /reviewpr to /preparepr to /mergepr +mkdir -p .local +``` + +Run all commands inside the worktree directory. +Start on `origin/main` so you can check for existing implementations before looking at PR code. + +## Steps + +1. Identify PR meta and context + +```sh +gh pr view --json number,title,state,isDraft,author,baseRefName,headRefName,headRepository,url,body,labels,assignees,reviewRequests,files,additions,deletions --jq '{number,title,url,state,isDraft,author:.author.login,base:.baseRefName,head:.headRefName,headRepo:.headRepository.nameWithOwner,additions,deletions,files:.files|length,body}' +``` + +2. Check if this already exists in main before looking at the PR branch + +- Identify the core feature or fix from the PR title and description. +- Search for existing implementations using keywords from the PR title, changed file paths, and function or component names from the diff. + +```sh +# Use keywords from the PR title and changed files +rg -n "" -S src packages apps ui || true +rg -n "" -S src packages apps ui || true + +git log --oneline --all --grep="" | head -20 +``` + +If it already exists, call it out as a BLOCKER or at least IMPORTANT. + +3. Claim the PR + +Assign yourself so others know someone is reviewing. Skip if the PR looks like spam or is a draft you plan to recommend closing. + +```sh +gh_user=$(gh api user --jq .login) +gh pr edit --add-assignee "$gh_user" +``` + +4. Read the PR description carefully + +Use the body from step 1. Summarize goal, scope, and missing context. + +5. Read the diff thoroughly + +Minimum: + +```sh +gh pr diff +``` + +If you need full code context locally, fetch the PR head to a local ref and diff it. Do not create a merge commit. + +```sh +git fetch origin pull//head:pr- +# Show changes without modifying the working tree + +git diff --stat origin/main..pr- +git diff origin/main..pr- +``` + +If you want to browse the PR version of files directly, temporarily check out `pr-` in the worktree. Do not commit or push. Return to `temp/pr-` and reset to `origin/main` afterward. + +```sh +# Use only if needed +# git checkout pr- +# ...inspect files... + +git checkout temp/pr- +git reset --hard origin/main +``` + +6. Validate the change is needed and valuable + +Be honest. Call out low value AI slop. + +7. Evaluate implementation quality + +Review correctness, design, performance, and ergonomics. + +8. Perform a security review + +Assume OpenClaw subagents run with full disk access, including git, gh, and shell. Check auth, input validation, secrets, dependencies, tool safety, and privacy. + +9. Review tests and verification + +Identify what exists, what is missing, and what would be a minimal regression test. + +10. Check docs + +Check if the PR touches code with related documentation such as README, docs, inline API docs, or config examples. + +- If docs exist for the changed area and the PR does not update them, flag as IMPORTANT. +- If the PR adds a new feature or config option with no docs, flag as IMPORTANT. +- If the change is purely internal with no user-facing impact, skip this. + +11. Check changelog + +Check if `CHANGELOG.md` exists and whether the PR warrants an entry. + +- If the project has a changelog and the PR is user-facing, flag missing entry as IMPORTANT. +- Leave the change for /preparepr, only flag it here. + +12. Answer the key question + +Decide if /preparepr can fix issues or the contributor must update the PR. + +13. Save findings to the worktree + +Write the full structured review sections A through J to `.local/review.md`. +Create or overwrite the file and verify it exists and is non-empty. + +```sh +ls -la .local/review.md +wc -l .local/review.md +``` + +14. Output the structured review + +Produce a review that matches what you saved to `.local/review.md`. + +A) TL;DR recommendation + +- One of: READY FOR /preparepr | NEEDS WORK | NEEDS DISCUSSION | NOT USEFUL (CLOSE) +- 1 to 3 sentences. + +B) What changed + +C) What is good + +D) Security findings + +E) Concerns or questions (actionable) + +- Numbered list. +- Mark each item as BLOCKER, IMPORTANT, or NIT. +- For each, point to file or area and propose a concrete fix. + +F) Tests + +G) Docs status + +- State if related docs are up to date, missing, or not applicable. + +H) Changelog + +- State if `CHANGELOG.md` needs an entry and which category. + +I) Follow ups (optional) + +J) Suggested PR comment (optional) + +## Guardrails + +- Worktree only. +- Do not delete the worktree after review. +- Review only, do not merge, do not push. diff --git a/.agents/skills/review-pr/agents/openai.yaml b/.agents/skills/review-pr/agents/openai.yaml new file mode 100644 index 000000000..f65934995 --- /dev/null +++ b/.agents/skills/review-pr/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Review PR" + short_description: "Review GitHub PRs without merging" + default_prompt: "Use $review-pr to perform a thorough, review-only GitHub PR review."