From 9264a8e21a28af1fee3649f06a3c9b562f5fc06e Mon Sep 17 00:00:00 2001 From: Gustavo Madeira Santana Date: Thu, 19 Feb 2026 20:50:24 -0500 Subject: [PATCH] chore: move skills to maintainers repository --- .agents/archive/PR_WORKFLOW_V1.md | 181 --------- .agents/archive/merge-pr-v1/SKILL.md | 304 --------------- .../archive/merge-pr-v1/agents/openai.yaml | 4 - .agents/archive/prepare-pr-v1/SKILL.md | 336 ----------------- .../archive/prepare-pr-v1/agents/openai.yaml | 4 - .agents/archive/review-pr-v1/SKILL.md | 253 ------------- .../archive/review-pr-v1/agents/openai.yaml | 4 - .agents/maintainers.md | 1 + .agents/skills/PR_WORKFLOW.md | 245 ------------- .agents/skills/merge-pr/SKILL.md | 101 ----- .agents/skills/merge-pr/agents/openai.yaml | 4 - .agents/skills/mintlify/SKILL.md | 345 ------------------ .agents/skills/prepare-pr/SKILL.md | 127 ------- .agents/skills/prepare-pr/agents/openai.yaml | 4 - .agents/skills/review-pr/SKILL.md | 142 ------- .agents/skills/review-pr/agents/openai.yaml | 4 - 16 files changed, 1 insertion(+), 2058 deletions(-) delete mode 100644 .agents/archive/PR_WORKFLOW_V1.md delete mode 100644 .agents/archive/merge-pr-v1/SKILL.md delete mode 100644 .agents/archive/merge-pr-v1/agents/openai.yaml delete mode 100644 .agents/archive/prepare-pr-v1/SKILL.md delete mode 100644 .agents/archive/prepare-pr-v1/agents/openai.yaml delete mode 100644 .agents/archive/review-pr-v1/SKILL.md delete mode 100644 .agents/archive/review-pr-v1/agents/openai.yaml create mode 100644 .agents/maintainers.md delete mode 100644 .agents/skills/PR_WORKFLOW.md delete mode 100644 .agents/skills/merge-pr/SKILL.md delete mode 100644 .agents/skills/merge-pr/agents/openai.yaml delete mode 100644 .agents/skills/mintlify/SKILL.md delete mode 100644 .agents/skills/prepare-pr/SKILL.md delete mode 100644 .agents/skills/prepare-pr/agents/openai.yaml delete mode 100644 .agents/skills/review-pr/SKILL.md delete mode 100644 .agents/skills/review-pr/agents/openai.yaml diff --git a/.agents/archive/PR_WORKFLOW_V1.md b/.agents/archive/PR_WORKFLOW_V1.md deleted file mode 100644 index 1cb6ab653b5..00000000000 --- a/.agents/archive/PR_WORKFLOW_V1.md +++ /dev/null @@ -1,181 +0,0 @@ -# PR Workflow for Maintainers - -Please read this in full and do not skip sections. -This is the single source of truth for the maintainer PR workflow. - -## Triage order - -Process PRs **oldest to newest**. Older PRs are more likely to have merge conflicts and stale dependencies; resolving them first keeps the queue healthy and avoids snowballing rebase pain. - -## Working rule - -Skills execute workflow. Maintainers provide judgment. -Always pause between skills to evaluate technical direction, not just command success. - -These three skills must be used in order: - -1. `review-pr` — review only, produce findings -2. `prepare-pr` — rebase, fix, gate, push to PR head branch -3. `merge-pr` — squash-merge, verify MERGED state, clean up - -They are necessary, but not sufficient. Maintainers must steer between steps and understand the code before moving forward. - -Treat PRs as reports first, code second. -If submitted code is low quality, ignore it and implement the best solution for the problem. - -Do not continue if you cannot verify the problem is real or test the fix. - -## Coding Agent - -Use ChatGPT 5.3 Codex High. Fall back to 5.2 Codex High or 5.3 Codex Medium if necessary. - -## PR quality bar - -- Do not trust PR code by default. -- Do not merge changes you cannot validate with a reproducible problem and a tested fix. -- Keep types strict. Do not use `any` in implementation code. -- Keep external-input boundaries typed and validated, including CLI input, environment variables, network payloads, and tool output. -- Keep implementations properly scoped. Fix root causes, not local symptoms. -- Identify and reuse canonical sources of truth so behavior does not drift across the codebase. -- Harden changes. Always evaluate security impact and abuse paths. -- Understand the system before changing it. Never make the codebase messier just to clear a PR queue. - -## Rebase and conflict resolution - -Before any substantive review or prep work, **always rebase the PR branch onto current `main` and resolve merge conflicts first**. A PR that cannot cleanly rebase is not ready for review — fix conflicts before evaluating correctness. - -- During `prepare-pr`: rebase onto `main` as the first step, before fixing findings or running gates. -- If conflicts are complex or touch areas you do not understand, stop and escalate. -- Prefer **rebase** for linear history; **squash** when commit history is messy or unhelpful. - -## Commit and changelog rules - -- Create commits with `scripts/committer "" `; avoid manual `git add`/`git commit` so staging stays scoped. -- Follow concise, action-oriented commit messages (e.g., `CLI: add verbose flag to send`). -- During `prepare-pr`, use this commit subject format: `fix: (openclaw#) thanks @`. -- Group related changes; avoid bundling unrelated refactors. -- Changelog workflow: keep the latest released version at the top (no `Unreleased`); after publishing, bump the version and start a new top section. -- When working on a PR: add a changelog entry with the PR number and thank the contributor. -- When working on an issue: reference the issue in the changelog entry. -- Pure test additions/fixes generally do **not** need a changelog entry unless they alter user-facing behavior or the user asks for one. - -## Co-contributor and clawtributors - -- If we squash, add the PR author as a co-contributor in the commit body using a `Co-authored-by:` trailer. -- When maintainer prepares and merges the PR, add the maintainer as an additional `Co-authored-by:` trailer too. -- Avoid `--auto` merges for maintainer landings. Merge only after checks are green so the maintainer account is the actor and attribution is deterministic. -- For squash merges, set `--author-email` to a reviewer-owned email with fallback candidates; if merge fails due to author-email validation, retry once with the next candidate. -- If you review a PR and later do work on it, land via merge/squash (no direct-main commits) and always add the PR author as a co-contributor. -- When merging a PR: leave a PR comment that explains exactly what we did, include the SHA hashes, and record the comment URL in the final report. -- When merging a PR from a new contributor: run `bun scripts/update-clawtributors.ts` to add their avatar to the README "Thanks to all clawtributors" list, then commit the regenerated README. - -## Review mode vs landing mode - -- **Review mode (PR link only):** read `gh pr view`/`gh pr diff`; **do not** switch branches; **do not** change code. -- **Landing mode (exception path):** use only when normal `review-pr -> prepare-pr -> merge-pr` flow cannot safely preserve attribution or cannot satisfy branch protection. Create an integration branch from `main`, bring in PR commits (**prefer rebase** for linear history; **merge allowed** when complexity/conflicts make it safer), apply fixes, add changelog (+ thanks + PR #), run full gate **locally before committing** (`pnpm build && pnpm check && pnpm test`), commit, merge back to `main`, then `git switch main` (never stay on a topic branch after landing). Important: the contributor needs to be in the git graph after this! - -## Pre-review safety checks - -- Before starting a review when a GH Issue/PR is pasted: use an isolated `.worktrees/pr-` checkout from `origin/main`. Do not require a clean main checkout, and do not run `git pull` in a dirty main checkout. -- PR review calls: prefer a single `gh pr view --json ...` to batch metadata/comments; run `gh pr diff` only when needed. -- PRs should summarize scope, note testing performed, and mention any user-facing changes or new flags. -- Read `docs/help/submitting-a-pr.md` ([Submitting a PR](https://docs.openclaw.ai/help/submitting-a-pr)) for what we expect from contributors. - -## Unified workflow - -Entry criteria: - -- PR URL/number is known. -- Problem statement is clear enough to attempt reproduction. -- A realistic verification path exists (tests, integration checks, or explicit manual validation). - -### 1) `review-pr` - -Purpose: - -- Review only: correctness, value, security risk, tests, docs, and changelog impact. -- Produce structured findings and a recommendation. - -Expected output: - -- Recommendation: ready, needs work, needs discussion, or close. -- `.local/review.md` with actionable findings. - -Maintainer checkpoint before `prepare-pr`: - -``` -What problem are they trying to solve? -What is the most optimal implementation? -Can we fix up everything? -Do we have any questions? -``` - -Stop and escalate instead of continuing if: - -- The problem cannot be reproduced or confirmed. -- The proposed PR scope does not match the stated problem. -- The design introduces unresolved security or trust-boundary concerns. - -### 2) `prepare-pr` - -Purpose: - -- Make the PR merge-ready on its head branch. -- Rebase onto current `main` first, then fix blocker/important findings, then run gates. -- In fresh worktrees, bootstrap dependencies before local gates (`pnpm install --frozen-lockfile`). - -Expected output: - -- Updated code and tests on the PR head branch. -- `.local/prep.md` with changes, verification, and current HEAD SHA. -- Final status: `PR is ready for /mergepr`. - -Maintainer checkpoint before `merge-pr`: - -``` -Is this the most optimal implementation? -Is the code properly scoped? -Is the code properly reusing existing logic in the codebase? -Is the code properly typed? -Is the code hardened? -Do we have enough tests? -Do we need regression tests? -Are tests using fake timers where appropriate? (e.g., debounce/throttle, retry backoff, timeout branches, delayed callbacks, polling loops) -Do not add performative tests, ensure tests are real and there are no regressions. -Do you see any follow-up refactors we should do? -Take your time, fix it properly, refactor if necessary. -Did any changes introduce any potential security vulnerabilities? -``` - -Stop and escalate instead of continuing if: - -- You cannot verify behavior changes with meaningful tests or validation. -- Fixing findings requires broad architecture changes outside safe PR scope. -- Security hardening requirements remain unresolved. - -### 3) `merge-pr` - -Purpose: - -- Merge only after review and prep artifacts are present and checks are green. -- Use deterministic squash merge flow (`--match-head-commit` + explicit subject/body with co-author trailer), then verify the PR ends in `MERGED` state. -- If no required checks are configured on the PR, treat that as acceptable and continue after branch-up-to-date validation. - -Go or no-go checklist before merge: - -- All BLOCKER and IMPORTANT findings are resolved. -- Verification is meaningful and regression risk is acceptably low. -- Docs and changelog are updated when required. -- Required CI checks are green and the branch is not behind `main`. - -Expected output: - -- Successful merge commit and recorded merge SHA. -- Worktree cleanup after successful merge. -- Comment on PR indicating merge was successful. - -Maintainer checkpoint after merge: - -- Were any refactors intentionally deferred and now need follow-up issue(s)? -- Did this reveal broader architecture or test gaps we should address? -- Run `bun scripts/update-clawtributors.ts` if the contributor is new. diff --git a/.agents/archive/merge-pr-v1/SKILL.md b/.agents/archive/merge-pr-v1/SKILL.md deleted file mode 100644 index 0956699eb55..00000000000 --- a/.agents/archive/merge-pr-v1/SKILL.md +++ /dev/null @@ -1,304 +0,0 @@ ---- -name: merge-pr -description: Merge a GitHub PR via squash after /prepare-pr. 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 deterministic squash merge (`--match-head-commit` + explicit co-author trailer), then clean up the worktree after success. - -## Inputs - -- Ask for PR number or URL. -- If missing, use `.local/prep.env` from the worktree if present. -- 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 use `gh pr merge --auto` for maintainer landings. -- 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. Move to the repo root and retry. -- Read `.local/review.md`, `.local/prep.md`, and `.local/prep.env` in the worktree. Do not skip. -- Always merge with `--match-head-commit "$PREP_HEAD_SHA"` to prevent racing stale or changed heads. -- Clean up `.worktrees/pr-` only after confirmed `MERGED`. - -## Completion Criteria - -- Ensure `gh pr merge` succeeds. -- Ensure PR state is `MERGED`, never `CLOSED`. -- Record the merge SHA. -- Leave a PR comment with merge SHA and prepared head SHA, and capture the comment URL. -- 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 -repo_root=$(git rev-parse --show-toplevel) -cd "$repo_root" -gh auth status - -WORKTREE_DIR=".worktrees/pr-" -cd "$WORKTREE_DIR" -``` - -Run all commands inside the worktree directory. - -## Load Local Artifacts (Mandatory) - -Expect these files from earlier steps: - -- `.local/review.md` from `/review-pr` -- `.local/prep.md` from `/prepare-pr` -- `.local/prep.env` from `/prepare-pr` - -```sh -ls -la .local || true - -for required in .local/review.md .local/prep.md .local/prep.env; do - if [ ! -f "$required" ]; then - echo "Missing $required. Stop and run /review-pr then /prepare-pr." - exit 1 - fi -done - -sed -n '1,120p' .local/review.md -sed -n '1,120p' .local/prep.md -source .local/prep.env -``` - -## Steps - -1. Identify PR meta and verify prepared SHA still matches - -```sh -pr_meta_json=$(gh pr view --json number,title,state,isDraft,author,headRefName,headRefOid,baseRefName,headRepository,body) -printf '%s\n' "$pr_meta_json" | jq '{number,title,state,isDraft,author:.author.login,head:.headRefName,headSha:.headRefOid,base:.baseRefName,headRepo:.headRepository.nameWithOwner,body}' -pr_title=$(printf '%s\n' "$pr_meta_json" | jq -r .title) -pr_number=$(printf '%s\n' "$pr_meta_json" | jq -r .number) -pr_head_sha=$(printf '%s\n' "$pr_meta_json" | jq -r .headRefOid) -contrib=$(printf '%s\n' "$pr_meta_json" | jq -r .author.login) -is_draft=$(printf '%s\n' "$pr_meta_json" | jq -r .isDraft) - -if [ "$is_draft" = "true" ]; then - echo "ERROR: PR is draft. Stop and run /prepare-pr after draft is cleared." - exit 1 -fi - -if [ "$pr_head_sha" != "$PREP_HEAD_SHA" ]; then - echo "ERROR: PR head changed after /prepare-pr (expected $PREP_HEAD_SHA, got $pr_head_sha). Re-run /prepare-pr." - exit 1 -fi -``` - -2. Run sanity checks - -Stop if any are true: - -- PR is a draft. -- Required checks are failing. -- Branch is behind main. - -If checks are pending, wait for completion before merging. Do not use `--auto`. -If no required checks are configured, continue. - -```sh -gh pr checks --required --watch --fail-fast || true -checks_json=$(gh pr checks --required --json name,bucket,state 2>/tmp/gh-checks.err || true) -if [ -z "$checks_json" ]; then - checks_json='[]' -fi -required_count=$(printf '%s\n' "$checks_json" | jq 'length') -if [ "$required_count" -eq 0 ]; then - echo "No required checks configured for this PR." -fi -printf '%s\n' "$checks_json" | jq -r '.[] | "\(.bucket)\t\(.name)\t\(.state)"' - -failed_required=$(printf '%s\n' "$checks_json" | jq '[.[] | select(.bucket=="fail")] | length') -pending_required=$(printf '%s\n' "$checks_json" | jq '[.[] | select(.bucket=="pending")] | length') -if [ "$failed_required" -gt 0 ]; then - echo "Required checks are failing, run /prepare-pr." - exit 1 -fi -if [ "$pending_required" -gt 0 ]; then - echo "Required checks are still pending, retry /merge-pr when green." - exit 1 -fi - -git fetch origin main -git fetch origin pull//head:pr- --force -git merge-base --is-ancestor origin/main pr- || (echo "PR branch is behind main, run /prepare-pr" && exit 1) -``` - -If anything is failing or behind, stop and say to run `/prepare-pr`. - -3. Merge PR with explicit attribution metadata - -```sh -reviewer=$(gh api user --jq .login) -reviewer_id=$(gh api user --jq .id) -coauthor_email=${COAUTHOR_EMAIL:-"$contrib@users.noreply.github.com"} -if [ -z "$coauthor_email" ] || [ "$coauthor_email" = "null" ]; then - contrib_id=$(gh api users/$contrib --jq .id) - coauthor_email="${contrib_id}+${contrib}@users.noreply.github.com" -fi - -gh_email=$(gh api user --jq '.email // ""' || true) -git_email=$(git config user.email || true) -mapfile -t reviewer_email_candidates < <( - printf '%s\n' \ - "$gh_email" \ - "$git_email" \ - "${reviewer_id}+${reviewer}@users.noreply.github.com" \ - "${reviewer}@users.noreply.github.com" | awk 'NF && !seen[$0]++' -) -[ "${#reviewer_email_candidates[@]}" -gt 0 ] || { echo "ERROR: could not resolve reviewer author email"; exit 1; } -reviewer_email="${reviewer_email_candidates[0]}" - -cat > .local/merge-body.txt < /prepare-pr -> /merge-pr. - -Prepared head SHA: $PREP_HEAD_SHA -Co-authored-by: $contrib <$coauthor_email> -Co-authored-by: $reviewer <$reviewer_email> -Reviewed-by: @$reviewer -EOF - -run_merge() { - local email="$1" - local stderr_file - stderr_file=$(mktemp) - if gh pr merge \ - --squash \ - --delete-branch \ - --match-head-commit "$PREP_HEAD_SHA" \ - --author-email "$email" \ - --subject "$pr_title (#$pr_number)" \ - --body-file .local/merge-body.txt \ - 2> >(tee "$stderr_file" >&2) - then - rm -f "$stderr_file" - return 0 - fi - merge_err=$(cat "$stderr_file") - rm -f "$stderr_file" - return 1 -} - -merge_err="" -selected_merge_author_email="$reviewer_email" -if ! run_merge "$selected_merge_author_email"; then - if printf '%s\n' "$merge_err" | rg -qi 'author.?email|email.*associated|associated.*email|invalid.*email' && [ "${#reviewer_email_candidates[@]}" -ge 2 ]; then - selected_merge_author_email="${reviewer_email_candidates[1]}" - echo "Retrying once with fallback author email: $selected_merge_author_email" - run_merge "$selected_merge_author_email" || { echo "ERROR: merge failed after fallback retry"; exit 1; } - else - echo "ERROR: merge failed" - exit 1 - fi -fi -``` - -Retry is allowed exactly once when the error is clearly author-email validation. - -4. Verify PR state and capture merge SHA - -```sh -state=$(gh pr view --json state --jq .state) -if [ "$state" != "MERGED" ]; then - echo "Merge not finalized yet (state=$state), waiting up to 15 minutes..." - for _ in $(seq 1 90); do - sleep 10 - state=$(gh pr view --json state --jq .state) - if [ "$state" = "MERGED" ]; then - break - fi - done -fi - -if [ "$state" != "MERGED" ]; then - echo "ERROR: PR state is $state after waiting. Leave worktree and retry /merge-pr later." - exit 1 -fi - -merge_sha=$(gh pr view --json mergeCommit --jq '.mergeCommit.oid') -if [ -z "$merge_sha" ] || [ "$merge_sha" = "null" ]; then - echo "ERROR: merge commit SHA missing." - exit 1 -fi - -commit_body=$(gh api repos/:owner/:repo/commits/$merge_sha --jq .commit.message) -contrib=${contrib:-$(gh pr view --json author --jq .author.login)} -reviewer=${reviewer:-$(gh api user --jq .login)} -printf '%s\n' "$commit_body" | rg -q "^Co-authored-by: $contrib <" || { echo "ERROR: missing PR author co-author trailer"; exit 1; } -printf '%s\n' "$commit_body" | rg -q "^Co-authored-by: $reviewer <" || { echo "ERROR: missing reviewer co-author trailer"; exit 1; } - -echo "merge_sha=$merge_sha" -``` - -5. PR comment - -Use a multiline heredoc with interpolation enabled. - -```sh -ok=0 -comment_output="" -for _ in 1 2 3; do - if comment_output=$(gh pr comment -F - <" --force -git branch -D temp/pr- 2>/dev/null || true -git branch -D pr- 2>/dev/null || true -git branch -D pr--prep 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/archive/merge-pr-v1/agents/openai.yaml b/.agents/archive/merge-pr-v1/agents/openai.yaml deleted file mode 100644 index 9c10ae4d271..00000000000 --- a/.agents/archive/merge-pr-v1/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -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/archive/prepare-pr-v1/SKILL.md b/.agents/archive/prepare-pr-v1/SKILL.md deleted file mode 100644 index 91c4508a07a..00000000000 --- a/.agents/archive/prepare-pr-v1/SKILL.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -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 /review-pr. Never merge or push to main. ---- - -# Prepare PR - -## Overview - -Prepare a PR head branch for merge with review fixes, green gates, and deterministic merge handoff artifacts. - -## Inputs - -- Ask for PR number or URL. -- If missing, use `.local/pr-meta.env` from the PR worktree if present. -- If ambiguous, ask. - -## Safety - -- Never push to `main` or `origin/main`. Push only to the PR head branch. -- Never run `git push` without explicit remote and branch. 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 .`. - -## Execution Rule - -- Execute the workflow. Do not stop after printing the TODO checklist. -- If delegating, require the delegate to run commands and capture outputs. - -## Completion Criteria - -- Rebase PR commits onto `origin/main`. -- Fix all BLOCKER and IMPORTANT items from `.local/review.md`. -- Commit prep changes with required subject format. -- Run required gates and pass (`pnpm test` may be skipped only for high-confidence docs-only changes). -- Push the updated HEAD back to the PR head branch. -- Write `.local/prep.md` and `.local/prep.env`. -- 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 -repo_root=$(git rev-parse --show-toplevel) -cd "$repo_root" -gh auth status - -WORKTREE_DIR=".worktrees/pr-" -if [ ! -d "$WORKTREE_DIR" ]; then - git fetch origin main - git worktree add "$WORKTREE_DIR" -b temp/pr- origin/main -fi -cd "$WORKTREE_DIR" -mkdir -p .local -``` - -Run all commands inside the worktree directory. - -## Load Review Artifacts (Mandatory) - -```sh -if [ ! -f .local/review.md ]; then - echo "Missing .local/review.md. Run /review-pr first and save findings." - exit 1 -fi - -if [ ! -f .local/pr-meta.env ]; then - echo "Missing .local/pr-meta.env. Run /review-pr first and save metadata." - exit 1 -fi - -sed -n '1,220p' .local/review.md -source .local/pr-meta.env -``` - -## Steps - -1. Identify PR meta with one API call - -```sh -pr_meta_json=$(gh pr view --json number,title,author,headRefName,headRefOid,baseRefName,headRepository,headRepositoryOwner,body) -printf '%s\n' "$pr_meta_json" | jq '{number,title,author:.author.login,head:.headRefName,headSha:.headRefOid,base:.baseRefName,headRepo:.headRepository.nameWithOwner,headRepoOwner:.headRepositoryOwner.login,headRepoName:.headRepository.name,body}' - -pr_number=$(printf '%s\n' "$pr_meta_json" | jq -r .number) -contrib=$(printf '%s\n' "$pr_meta_json" | jq -r .author.login) -head=$(printf '%s\n' "$pr_meta_json" | jq -r .headRefName) -pr_head_sha_before=$(printf '%s\n' "$pr_meta_json" | jq -r .headRefOid) -head_owner=$(printf '%s\n' "$pr_meta_json" | jq -r '.headRepositoryOwner.login // empty') -head_repo_name=$(printf '%s\n' "$pr_meta_json" | jq -r '.headRepository.name // empty') -head_repo_url=$(printf '%s\n' "$pr_meta_json" | jq -r '.headRepository.url // empty') - -if [ -n "${PR_HEAD:-}" ] && [ "$head" != "$PR_HEAD" ]; then - echo "ERROR: PR head branch changed from $PR_HEAD to $head. Re-run /review-pr." - exit 1 -fi -``` - -2. Fetch PR head and rebase on latest `origin/main` - -```sh -git fetch origin pull//head:pr- --force -git checkout -B pr--prep pr- -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. - -3. 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. - -4. Optional quick feedback tests before full gates - -Targeted tests are optional quick feedback, not a substitute for full gates. - -If running targeted tests in a fresh worktree: - -```sh -if [ ! -x node_modules/.bin/vitest ]; then - pnpm install --frozen-lockfile -fi -``` - -5. Commit prep fixes with required subject format - -Use `scripts/committer` with explicit file paths. - -Required subject format: - -- `fix: (openclaw#) thanks @` - -```sh -commit_msg="fix: (openclaw#$pr_number) thanks @$contrib" -scripts/committer "$commit_msg" ... -``` - -If there are no local changes, do not create a no-op commit. - -Post-commit validation (mandatory): - -```sh -subject=$(git log -1 --pretty=%s) -echo "$subject" | rg -q "openclaw#$pr_number" || { echo "ERROR: commit subject missing openclaw#$pr_number"; exit 1; } -echo "$subject" | rg -q "thanks @$contrib" || { echo "ERROR: commit subject missing thanks @$contrib"; exit 1; } -``` - -6. Decide verification mode and run required gates before pushing - -If you are highly confident the change is docs-only, you may skip `pnpm test`. - -High-confidence docs-only criteria (all must be true): - -- Every changed file is documentation-only (`docs/**`, `README*.md`, `CHANGELOG.md`, `*.md`, `*.mdx`, `mintlify.json`, `docs.json`). -- No code, runtime, test, dependency, or build config files changed (`src/**`, `extensions/**`, `apps/**`, `package.json`, lockfiles, TS/JS config, test files, scripts). -- `.local/review.md` does not call for non-doc behavior fixes. - -Suggested check: - -```sh -changed_files=$(git diff --name-only origin/main...HEAD) -non_docs=$(printf "%s\n" "$changed_files" | grep -Ev '^(docs/|README.*\.md$|CHANGELOG\.md$|.*\.md$|.*\.mdx$|mintlify\.json$|docs\.json$)' || true) - -docs_only=false -if [ -n "$changed_files" ] && [ -z "$non_docs" ]; then - docs_only=true -fi - -echo "docs_only=$docs_only" -``` - -Bootstrap dependencies in a fresh worktree before gates: - -```sh -if [ ! -d node_modules ]; then - pnpm install --frozen-lockfile -fi -``` - -Run required gates: - -```sh -pnpm build -pnpm check - -if [ "$docs_only" = "true" ]; then - echo "Docs-only change detected with high confidence; skipping pnpm test." | tee -a .local/prep.md -else - pnpm test -fi -``` - -Require all required gates to pass. If something fails, fix, commit, and rerun. Allow at most 3 fix-and-rerun cycles. - -7. Push safely to the PR head branch - -Build `prhead` from owner/name first, then validate remote branch SHA before push. - -```sh -if [ -n "$head_owner" ] && [ -n "$head_repo_name" ]; then - head_repo_push_url="https://github.com/$head_owner/$head_repo_name.git" -elif [ -n "$head_repo_url" ] && [ "$head_repo_url" != "null" ]; then - case "$head_repo_url" in - *.git) head_repo_push_url="$head_repo_url" ;; - *) head_repo_push_url="$head_repo_url.git" ;; - esac -else - echo "ERROR: unable to determine PR head repo push URL" - exit 1 -fi - -git remote add prhead "$head_repo_push_url" 2>/dev/null || git remote set-url prhead "$head_repo_push_url" - -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 - -remote_sha=$(git ls-remote prhead "refs/heads/$head" | awk '{print $1}') -if [ -z "$remote_sha" ]; then - echo "ERROR: remote branch refs/heads/$head not found on prhead" - exit 1 -fi -if [ "$remote_sha" != "$pr_head_sha_before" ]; then - echo "ERROR: expected remote SHA $pr_head_sha_before, got $remote_sha. Re-fetch metadata and rebase first." - exit 1 -fi - -git push --force-with-lease=refs/heads/$head:$pr_head_sha_before prhead HEAD:$head || push_failed=1 -``` - -If lease push fails because head moved, perform one automatic retry: - -```sh -if [ "${push_failed:-0}" = "1" ]; then - echo "Lease push failed, retrying once with fresh PR head..." - - pr_head_sha_before=$(gh pr view --json headRefOid --jq .headRefOid) - git fetch origin pull//head:pr--latest --force - git rebase pr--latest - - pnpm build - pnpm check - if [ "$docs_only" != "true" ]; then - pnpm test - fi - - git push --force-with-lease=refs/heads/$head:$pr_head_sha_before prhead HEAD:$head -fi -``` - -8. Verify PR head and base relation (Mandatory) - -```sh -prep_head_sha=$(git rev-parse HEAD) -pr_head_sha_after=$(gh pr view --json headRefOid --jq .headRefOid) - -if [ "$prep_head_sha" != "$pr_head_sha_after" ]; then - echo "ERROR: pushed head SHA does not match PR head SHA." - exit 1 -fi - -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" && exit 1) -git branch -D pr--verify 2>/dev/null || true -``` - -9. Write prep summary artifacts (Mandatory) - -Write `.local/prep.md` and `.local/prep.env` for merge handoff. - -```sh -contrib_id=$(gh api users/$contrib --jq .id) -coauthor_email="${contrib_id}+${contrib}@users.noreply.github.com" - -cat > .local/prep.env < origin/main -else - git worktree add "$WORKTREE_DIR" -b temp/pr- origin/main - cd "$WORKTREE_DIR" -fi - -# Create local scratch space that persists across /review-pr to /prepare-pr to /merge-pr -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 -pr_meta_json=$(gh pr view --json number,title,state,isDraft,author,baseRefName,headRefName,headRefOid,headRepository,url,body,labels,assignees,reviewRequests,files,additions,deletions,statusCheckRollup) -printf '%s\n' "$pr_meta_json" | jq '{number,title,url,state,isDraft,author:.author.login,base:.baseRefName,head:.headRefName,headSha:.headRefOid,headRepo:.headRepository.nameWithOwner,additions,deletions,files:(.files|length),body}' - -cat > .local/pr-meta.env <" -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" || echo "Could not assign reviewer, continuing" -``` - -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- --force -mb=$(git merge-base origin/main pr-) - -# Show only this PR patch relative to merge-base, not total branch drift -git diff --stat "$mb"..pr- -git diff "$mb"..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- -# git branch --show-current -# ...inspect files... - -git checkout temp/pr- -git checkout -B temp/pr- origin/main -git branch --show-current -``` - -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. - -If you run local tests in the worktree, bootstrap dependencies first: - -```sh -if [ ! -x node_modules/.bin/vitest ]; then - pnpm install --frozen-lockfile -fi -``` - -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 /prepare-pr, only flag it here. - -12. Answer the key question - -Decide if /prepare-pr 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 /prepare-pr | 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/archive/review-pr-v1/agents/openai.yaml b/.agents/archive/review-pr-v1/agents/openai.yaml deleted file mode 100644 index f6593499507..00000000000 --- a/.agents/archive/review-pr-v1/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -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." diff --git a/.agents/maintainers.md b/.agents/maintainers.md new file mode 100644 index 00000000000..2bbb9c6203e --- /dev/null +++ b/.agents/maintainers.md @@ -0,0 +1 @@ +Maintainer skills now live in [`openclaw/maintainers`](https://github.com/openclaw/maintainers/). diff --git a/.agents/skills/PR_WORKFLOW.md b/.agents/skills/PR_WORKFLOW.md deleted file mode 100644 index 8696ba1b69e..00000000000 --- a/.agents/skills/PR_WORKFLOW.md +++ /dev/null @@ -1,245 +0,0 @@ -# PR Workflow for Maintainers - -Please read this in full and do not skip sections. -This is the single source of truth for the maintainer PR workflow. - -## Working rule - -Skills execute workflow. Maintainers provide judgment. -Always pause between skills to evaluate technical direction, not just command success. - -These three skills must be used in order: - -1. `review-pr` — review only, produce findings -2. `prepare-pr` — rebase, fix, gate, push to PR head branch -3. `merge-pr` — squash-merge, verify MERGED state, clean up - -They are necessary, but not sufficient. Maintainers must steer between steps and understand the code before moving forward. - -Treat PRs as reports first, code second. -If submitted code is low quality, ignore it and implement the best solution for the problem. - -Do not continue if you cannot verify the problem is real or test the fix. - -## Script-first contract - -Skill runs should invoke these wrappers automatically. You only need to run them manually when debugging or doing an explicit script-only run: - -- `scripts/pr-review ` -- `scripts/pr review-checkout-main ` or `scripts/pr review-checkout-pr ` while reviewing -- `scripts/pr review-guard ` before writing review outputs -- `scripts/pr review-validate-artifacts ` after writing outputs -- `scripts/pr-prepare init ` -- `scripts/pr-prepare validate-commit ` -- `scripts/pr-prepare gates ` -- `scripts/pr-prepare push ` -- Optional one-shot prepare: `scripts/pr-prepare run ` -- `scripts/pr-merge ` (verify-only; short form remains backward compatible) -- `scripts/pr-merge verify ` (verify-only) -- Optional one-shot merge: `scripts/pr-merge run ` - -These wrappers run shared preflight checks and generate deterministic artifacts. They are designed to work from repo root or PR worktree cwd. - -## Required artifacts - -- `.local/pr-meta.json` and `.local/pr-meta.env` from review init. -- `.local/review.md` and `.local/review.json` from review output. -- `.local/prep-context.env` and `.local/prep.md` from prepare. -- `.local/prep.env` from prepare completion. - -## Structured review handoff - -`review-pr` must write `.local/review.json`. -In normal skill runs this is handled automatically. Use `scripts/pr review-artifacts-init ` and `scripts/pr review-tests ...` manually only for debugging or explicit script-only runs. - -Minimum schema: - -```json -{ - "recommendation": "READY FOR /prepare-pr", - "findings": [ - { - "id": "F1", - "severity": "IMPORTANT", - "title": "Missing changelog entry", - "area": "CHANGELOG.md", - "fix": "Add a Fixes entry for PR #" - } - ], - "tests": { - "ran": ["pnpm test -- ..."], - "gaps": ["..."], - "result": "pass" - } -} -``` - -`prepare-pr` resolves all `BLOCKER` and `IMPORTANT` findings from this file. - -## Coding Agent - -Use ChatGPT 5.3 Codex High. Fall back to 5.2 Codex High or 5.3 Codex Medium if necessary. - -## PR quality bar - -- Do not trust PR code by default. -- Do not merge changes you cannot validate with a reproducible problem and a tested fix. -- Keep types strict. Do not use `any` in implementation code. -- Keep external-input boundaries typed and validated, including CLI input, environment variables, network payloads, and tool output. -- Keep implementations properly scoped. Fix root causes, not local symptoms. -- Identify and reuse canonical sources of truth so behavior does not drift across the codebase. -- Harden changes. Always evaluate security impact and abuse paths. -- Understand the system before changing it. Never make the codebase messier just to clear a PR queue. - -## Rebase and conflict resolution - -Before any substantive review or prep work, **always rebase the PR branch onto current `main` and resolve merge conflicts first**. A PR that cannot cleanly rebase is not ready for review — fix conflicts before evaluating correctness. - -- During `prepare-pr`: rebase onto `main` as the first step, before fixing findings or running gates. -- If conflicts are complex or touch areas you do not understand, stop and escalate. -- Prefer **rebase** for linear history; **squash** when commit history is messy or unhelpful. - -## Commit and changelog rules - -- In normal `prepare-pr` runs, commits are created via `scripts/committer "" `. Use it manually only when operating outside the skill flow; avoid manual `git add`/`git commit` so staging stays scoped. -- Follow concise, action-oriented commit messages (e.g., `CLI: add verbose flag to send`). -- During `prepare-pr`, use concise, action-oriented subjects **without** PR numbers or thanks; reserve `(#) thanks @` for the final merge/squash commit. -- Group related changes; avoid bundling unrelated refactors. -- Changelog workflow: keep the latest released version at the top (no `Unreleased`); after publishing, bump the version and start a new top section. -- When working on a PR: add a changelog entry line with the PR number `(#)` and `thanks @` when author metadata is available (mandatory in this workflow). -- When working on an issue: reference the issue in the changelog entry. -- In this workflow, changelog is always required even for internal/test-only changes. - -## Gate policy - -In fresh worktrees, dependency bootstrap is handled by wrappers before local gates. Manual equivalent: - -```sh -pnpm install --frozen-lockfile -``` - -Gate set: - -- Always: `pnpm build`, `pnpm check` -- `pnpm test` required unless high-confidence docs-only criteria pass. - -## Co-contributor and clawtributors - -- If we squash, add the PR author as a co-contributor in the commit body using a `Co-authored-by:` trailer. -- When maintainer prepares and merges the PR, add the maintainer as an additional `Co-authored-by:` trailer too. -- Avoid `--auto` merges for maintainer landings. Merge only after checks are green so the maintainer account is the actor and attribution is deterministic. -- For squash merges, set `--author-email` to a reviewer-owned email with fallback candidates; if merge fails due to author-email validation, retry once with the next candidate. -- If you review a PR and later do work on it, land via merge/squash (no direct-main commits) and always add the PR author as a co-contributor. -- When merging a PR: leave a PR comment that explains exactly what we did, include the SHA hashes, and record the comment URL in the final report. -- Manual post-merge step for new contributors: run `bun scripts/update-clawtributors.ts` to add their avatar to the README "Thanks to all clawtributors" list, then commit the regenerated README. - -## Review mode vs landing mode - -- **Review mode (PR link only):** read `gh pr view`/`gh pr diff`; **do not** switch branches; **do not** change code. -- **Landing mode (exception path):** use only when normal `review-pr -> prepare-pr -> merge-pr` flow cannot safely preserve attribution or cannot satisfy branch protection. Create an integration branch from `main`, bring in PR commits (**prefer rebase** for linear history; **merge allowed** when complexity/conflicts make it safer), apply fixes, add changelog (+ thanks + PR #), run full gate **locally before committing** (`pnpm build && pnpm check && pnpm test`), commit, merge back to `main`, then `git switch main` (never stay on a topic branch after landing). Important: the contributor needs to be in the git graph after this! - -## Pre-review safety checks - -- Before starting a review when a GH Issue/PR is pasted: `review-pr`/`scripts/pr-review` should create and use an isolated `.worktrees/pr-` checkout from `origin/main` automatically. Do not require a clean main checkout, and do not run `git pull` in a dirty main checkout. -- PR review calls: prefer a single `gh pr view --json ...` to batch metadata/comments; run `gh pr diff` only when needed. -- PRs should summarize scope, note testing performed, and mention any user-facing changes or new flags. -- Read `docs/help/submitting-a-pr.md` ([Submitting a PR](https://docs.openclaw.ai/help/submitting-a-pr)) for what we expect from contributors. - -## Unified workflow - -Entry criteria: - -- PR URL/number is known. -- Problem statement is clear enough to attempt reproduction. -- A realistic verification path exists (tests, integration checks, or explicit manual validation). - -### 1) `review-pr` - -Purpose: - -- Review only: correctness, value, security risk, tests, docs, and changelog impact. -- Produce structured findings and a recommendation. - -Expected output: - -- Recommendation: ready, needs work, needs discussion, or close. -- `.local/review.md` with actionable findings. - -Maintainer checkpoint before `prepare-pr`: - -``` -What problem are they trying to solve? -What is the most optimal implementation? -Can we fix up everything? -Do we have any questions? -``` - -Stop and escalate instead of continuing if: - -- The problem cannot be reproduced or confirmed. -- The proposed PR scope does not match the stated problem. -- The design introduces unresolved security or trust-boundary concerns. - -### 2) `prepare-pr` - -Purpose: - -- Make the PR merge-ready on its head branch. -- Rebase onto current `main` first, then fix blocker/important findings, then run gates. -- In fresh worktrees, bootstrap dependencies before local gates (`pnpm install --frozen-lockfile`). - -Expected output: - -- Updated code and tests on the PR head branch. -- `.local/prep.md` with changes, verification, and current HEAD SHA. -- Final status: `PR is ready for /merge-pr`. - -Maintainer checkpoint before `merge-pr`: - -``` -Is this the most optimal implementation? -Is the code properly scoped? -Is the code properly reusing existing logic in the codebase? -Is the code properly typed? -Is the code hardened? -Do we have enough tests? -Do we need regression tests? -Are tests using fake timers where appropriate? (e.g., debounce/throttle, retry backoff, timeout branches, delayed callbacks, polling loops) -Do not add performative tests, ensure tests are real and there are no regressions. -Do you see any follow-up refactors we should do? -Did any changes introduce any potential security vulnerabilities? -Take your time, fix it properly, refactor if necessary. -``` - -Stop and escalate instead of continuing if: - -- You cannot verify behavior changes with meaningful tests or validation. -- Fixing findings requires broad architecture changes outside safe PR scope. -- Security hardening requirements remain unresolved. - -### 3) `merge-pr` - -Purpose: - -- Merge only after review and prep artifacts are present and checks are green. -- Use deterministic squash merge flow (`--match-head-commit` + explicit subject/body with co-author trailer), then verify the PR ends in `MERGED` state. -- If no required checks are configured on the PR, treat that as acceptable and continue after branch-up-to-date validation. - -Go or no-go checklist before merge: - -- All BLOCKER and IMPORTANT findings are resolved. -- Verification is meaningful and regression risk is acceptably low. -- Changelog is updated (mandatory) and docs are updated when required. -- Required CI checks are green and the branch is not behind `main`. - -Expected output: - -- Successful merge commit and recorded merge SHA. -- Worktree cleanup after successful merge. -- Comment on PR indicating merge was successful. - -Maintainer checkpoint after merge: - -- Were any refactors intentionally deferred and now need follow-up issue(s)? -- Did this reveal broader architecture or test gaps we should address? -- Run `bun scripts/update-clawtributors.ts` if the contributor is new. diff --git a/.agents/skills/merge-pr/SKILL.md b/.agents/skills/merge-pr/SKILL.md deleted file mode 100644 index 91b7c4aa4e2..00000000000 --- a/.agents/skills/merge-pr/SKILL.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -name: merge-pr -description: Script-first deterministic squash merge with strict required-check gating, head-SHA pinning, and reliable attribution/commenting. ---- - -# Merge PR - -## Overview - -Merge a prepared PR only after deterministic validation. - -## Inputs - -- Ask for PR number or URL. -- If missing, use `.local/prep.env` from the PR worktree. - -## Safety - -- Never use `gh pr merge --auto` in this flow. -- Never run `git push` directly. -- Require `--match-head-commit` during merge. -- Wrapper commands are cwd-agnostic; you can run them from repo root or inside the PR worktree. - -## Execution Contract - -1. Validate merge readiness: - -```sh -scripts/pr-merge verify -``` - -Backward-compatible verify form also works: - -```sh -scripts/pr-merge -``` - -2. Run one-shot deterministic merge: - -```sh -scripts/pr-merge run -``` - -3. Capture and report these values in a human-readable summary (not raw `key=value` lines): - -- Merge commit SHA -- Merge author email -- Merge completion comment URL -- PR URL - -## Steps - -1. Validate artifacts - -```sh -require=(.local/review.md .local/review.json .local/prep.md .local/prep.env) -for f in "${require[@]}"; do - [ -s "$f" ] || { echo "Missing artifact: $f"; exit 1; } -done -``` - -2. Validate checks and branch status - -```sh -scripts/pr-merge verify -source .local/prep.env -``` - -`scripts/pr-merge` treats “no required checks configured” as acceptable (`[]`), but fails on any required `fail` or `pending`. - -3. Merge deterministically (wrapper-managed) - -```sh -scripts/pr-merge run -``` - -`scripts/pr-merge run` performs: - -- deterministic squash merge pinned to `PREP_HEAD_SHA` -- reviewer merge author email selection with fallback candidates -- one retry only when merge fails due to author-email validation -- co-author trailers for PR author and reviewer -- post-merge verification of both co-author trailers on commit message -- PR comment retry (3 attempts), then comment URL extraction -- cleanup after confirmed `MERGED` - -4. Manual fallback (only if wrapper is unavailable) - -```sh -scripts/pr merge-run -``` - -5. Cleanup - -Cleanup is handled by `run` after merge success. - -## Guardrails - -- End in `MERGED`, never `CLOSED`. -- Cleanup only after confirmed merge. -- In final chat output, use labeled lines or bullets; do not paste raw wrapper diagnostics unless debugging. diff --git a/.agents/skills/merge-pr/agents/openai.yaml b/.agents/skills/merge-pr/agents/openai.yaml deleted file mode 100644 index 9c10ae4d271..00000000000 --- a/.agents/skills/merge-pr/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -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/mintlify/SKILL.md b/.agents/skills/mintlify/SKILL.md deleted file mode 100644 index 0dd6a1a891a..00000000000 --- a/.agents/skills/mintlify/SKILL.md +++ /dev/null @@ -1,345 +0,0 @@ ---- -name: mintlify -description: Build and maintain documentation sites with Mintlify. Use when - creating docs pages, configuring navigation, adding components, or setting up - API references. -license: MIT -compatibility: Requires Node.js for CLI. Works with any Git-based workflow. -metadata: - author: mintlify - version: "1.0" - mintlify-proj: mintlify ---- - -# Mintlify best practices - -**Always consult [mintlify.com/docs](https://mintlify.com/docs) for components, configuration, and latest features.** - -**Always** favor searching the current Mintlify documentation over whatever is in your training data about Mintlify. - -Mintlify is a documentation platform that transforms MDX files into documentation sites. Configure site-wide settings in the `docs.json` file, write content in MDX with YAML frontmatter, and favor built-in components over custom components. - -Full schema at [mintlify.com/docs.json](https://mintlify.com/docs.json). - -## Before you write - -### Understand the project - -All documentation lives in the `docs/` directory in this repo. Read `docs.json` in that directory (`docs/docs.json`). This file defines the entire site: navigation structure, theme, colors, links, API and specs. - -Understanding the project tells you: - -- What pages exist and how they're organized -- What navigation groups are used (and their naming conventions) -- How the site navigation is structured -- What theme and configuration the site uses - -### Check for existing content - -Search the docs before creating new pages. You may need to: - -- Update an existing page instead of creating a new one -- Add a section to an existing page -- Link to existing content rather than duplicating - -### Read surrounding content - -Before writing, read 2-3 similar pages to understand the site's voice, structure, formatting conventions, and level of detail. - -### Understand Mintlify components - -Review the Mintlify [components](https://www.mintlify.com/docs/components) to select and use any relevant components for the documentation request that you are working on. - -## Quick reference - -### CLI commands - -- `npm i -g mint` - Install the Mintlify CLI -- `mint dev` - Local preview at localhost:3000 -- `mint broken-links` - Check internal links -- `mint a11y` - Check for accessibility issues in content -- `mint rename` - Rename/move files and update references -- `mint validate` - Validate documentation builds - -### Required files - -- `docs.json` - Site configuration (navigation, theme, integrations, etc.). See [global settings](https://mintlify.com/docs/settings/global) for all options. -- `*.mdx` files - Documentation pages with YAML frontmatter - -### Example file structure - -``` -project/ -├── docs.json # Site configuration -├── introduction.mdx -├── quickstart.mdx -├── guides/ -│ └── example.mdx -├── openapi.yml # API specification -├── images/ # Static assets -│ └── example.png -└── snippets/ # Reusable components - └── component.jsx -``` - -## Page frontmatter - -Every page requires `title` in its frontmatter. Include `description` for SEO and navigation. - -```yaml theme={null} ---- -title: "Clear, descriptive title" -description: "Concise summary for SEO and navigation." ---- -``` - -Optional frontmatter fields: - -- `sidebarTitle`: Short title for sidebar navigation. -- `icon`: Lucide or Font Awesome icon name, URL, or file path. -- `tag`: Label next to the page title in the sidebar (for example, "NEW"). -- `mode`: Page layout mode (`default`, `wide`, `custom`). -- `keywords`: Array of terms related to the page content for local search and SEO. -- Any custom YAML fields for use with personalization or conditional content. - -## File conventions - -- Match existing naming patterns in the directory -- If there are no existing files or inconsistent file naming patterns, use kebab-case: `getting-started.mdx`, `api-reference.mdx` -- Use root-relative paths without file extensions for internal links: `/getting-started/quickstart` -- Do not use relative paths (`../`) or absolute URLs for internal pages -- When you create a new page, add it to `docs.json` navigation or it won't appear in the sidebar - -## Organize content - -When a user asks about anything related to site-wide configurations, start by understanding the [global settings](https://www.mintlify.com/docs/organize/settings). See if a setting in the `docs.json` file can be updated to achieve what the user wants. - -### Navigation - -The `navigation` property in `docs.json` controls site structure. Choose one primary pattern at the root level, then nest others within it. - -**Choose your primary pattern:** - -| Pattern | When to use | -| ------------- | ---------------------------------------------------------------------------------------------- | -| **Groups** | Default. Single audience, straightforward hierarchy | -| **Tabs** | Distinct sections with different audiences (Guides vs API Reference) or content types | -| **Anchors** | Want persistent section links at sidebar top. Good for separating docs from external resources | -| **Dropdowns** | Multiple doc sections users switch between, but not distinct enough for tabs | -| **Products** | Multi-product company with separate documentation per product | -| **Versions** | Maintaining docs for multiple API/product versions simultaneously | -| **Languages** | Localized content | - -**Within your primary pattern:** - -- **Groups** - Organize related pages. Can nest groups within groups, but keep hierarchy shallow -- **Menus** - Add dropdown navigation within tabs for quick jumps to specific pages -- **`expanded: false`** - Collapse nested groups by default. Use for reference sections users browse selectively -- **`openapi`** - Auto-generate pages from OpenAPI spec. Add at group/tab level to inherit - -**Common combinations:** - -- Tabs containing groups (most common for docs with API reference) -- Products containing tabs (multi-product SaaS) -- Versions containing tabs (versioned API docs) -- Anchors containing groups (simple docs with external resource links) - -### Links and paths - -- **Internal links:** Root-relative, no extension: `/getting-started/quickstart` -- **Images:** Store in `/images`, reference as `/images/example.png` -- **External links:** Use full URLs, they open in new tabs automatically - -## Customize docs sites - -**What to customize where:** - -- **Brand colors, fonts, logo** → `docs.json`. See [global settings](https://mintlify.com/docs/settings/global) -- **Component styling, layout tweaks** → `custom.css` at project root -- **Dark mode** → Enabled by default. Only disable with `"appearance": "light"` in `docs.json` if brand requires it - -Start with `docs.json`. Only add `custom.css` when you need styling that config doesn't support. - -## Write content - -### Components - -The [components overview](https://mintlify.com/docs/components) organizes all components by purpose: structure content, draw attention, show/hide content, document APIs, link to pages, and add visual context. Start there to find the right component. - -**Common decision points:** - -| Need | Use | -| -------------------------- | ----------------------- | -| Hide optional details | `` | -| Long code examples | `` | -| User chooses one option | `` | -| Linked navigation cards | `` in `` | -| Sequential instructions | `` | -| Code in multiple languages | `` | -| API parameters | `` | -| API response fields | `` | - -**Callouts by severity:** - -- `` - Supplementary info, safe to skip -- `` - Helpful context such as permissions -- `` - Recommendations or best practices -- `` - Potentially destructive actions -- `` - Success confirmation - -### Reusable content - -**When to use snippets:** - -- Exact content appears on more than one page -- Complex components you want to maintain in one place -- Shared content across teams/repos - -**When NOT to use snippets:** - -- Slight variations needed per page (leads to complex props) - -Import snippets with `import { Component } from "/path/to/snippet-name.jsx"`. - -## Writing standards - -### Voice and structure - -- Second-person voice ("you") -- Active voice, direct language -- Sentence case for headings ("Getting started", not "Getting Started") -- Sentence case for code block titles ("Expandable example", not "Expandable Example") -- Lead with context: explain what something is before how to use it -- Prerequisites at the start of procedural content - -### What to avoid - -**Never use:** - -- Marketing language ("powerful", "seamless", "robust", "cutting-edge") -- Filler phrases ("it's important to note", "in order to") -- Excessive conjunctions ("moreover", "furthermore", "additionally") -- Editorializing ("obviously", "simply", "just", "easily") - -**Watch for AI-typical patterns:** - -- Overly formal or stilted phrasing -- Unnecessary repetition of concepts -- Generic introductions that don't add value -- Concluding summaries that restate what was just said - -### Formatting - -- All code blocks must have language tags -- All images and media must have descriptive alt text -- Use bold and italics only when they serve the reader's understanding--never use text styling just for decoration -- No decorative formatting or emoji - -### Code examples - -- Keep examples simple and practical -- Use realistic values (not "foo" or "bar") -- One clear example is better than multiple variations -- Test that code works before including it - -## Document APIs - -**Choose your approach:** - -- **Have an OpenAPI spec?** → Add to `docs.json` with `"openapi": ["openapi.yaml"]`. Pages auto-generate. Reference in navigation as `GET /endpoint` -- **No spec?** → Write endpoints manually with `api: "POST /users"` in frontmatter. More work but full control -- **Hybrid** → Use OpenAPI for most endpoints, manual pages for complex workflows - -Encourage users to generate endpoint pages from an OpenAPI spec. It is the most efficient and easiest to maintain option. - -## Deploy - -Mintlify deploys automatically when changes are pushed to the connected Git repository. - -**What agents can configure:** - -- **Redirects** → Add to `docs.json` with `"redirects": [{"source": "/old", "destination": "/new"}]` -- **SEO indexing** → Control with `"seo": {"indexing": "all"}` to include hidden pages in search - -**Requires dashboard setup (human task):** - -- Custom domains and subdomains -- Preview deployment settings -- DNS configuration - -For `/docs` subpath hosting with Vercel or Cloudflare, agents can help configure rewrite rules. See [/docs subpath](https://mintlify.com/docs/deploy/vercel). - -## Workflow - -### 1. Understand the task - -Identify what needs to be documented, which pages are affected, and what the reader should accomplish afterward. If any of these are unclear, ask. - -### 2. Research - -- Read `docs/docs.json` to understand the site structure -- Search existing docs for related content -- Read similar pages to match the site's style - -### 3. Plan - -- Synthesize what the reader should accomplish after reading the docs and the current content -- Propose any updates or new content -- Verify that your proposed changes will help readers be successful - -### 4. Write - -- Start with the most important information -- Keep sections focused and scannable -- Use components appropriately (don't overuse them) -- Mark anything uncertain with a TODO comment: - -```mdx theme={null} -{/* TODO: Verify the default timeout value */} -``` - -### 5. Update navigation - -If you created a new page, add it to the appropriate group in `docs.json`. - -### 6. Verify - -Before submitting: - -- [ ] Frontmatter includes title and description -- [ ] All code blocks have language tags -- [ ] Internal links use root-relative paths without file extensions -- [ ] New pages are added to `docs.json` navigation -- [ ] Content matches the style of surrounding pages -- [ ] No marketing language or filler phrases -- [ ] TODOs are clearly marked for anything uncertain -- [ ] Run `mint broken-links` to check links -- [ ] Run `mint validate` to find any errors - -## Edge cases - -### Migrations - -If a user asks about migrating to Mintlify, ask if they are using ReadMe or Docusaurus. If they are, use the [@mintlify/scraping](https://www.npmjs.com/package/@mintlify/scraping) CLI to migrate content. If they are using a different platform to host their documentation, help them manually convert their content to MDX pages using Mintlify components. - -### Hidden pages - -Any page that is not included in the `docs.json` navigation is hidden. Use hidden pages for content that should be accessible by URL or indexed for the assistant or search, but not discoverable through the sidebar navigation. - -### Exclude pages - -The `.mintignore` file is used to exclude files from a documentation repository from being processed. - -## Common gotchas - -1. **Component imports** - JSX components need explicit import, MDX components don't -2. **Frontmatter required** - Every MDX file needs `title` at minimum -3. **Code block language** - Always specify language identifier -4. **Never use `mint.json`** - `mint.json` is deprecated. Only ever use `docs.json` - -## Resources - -- [Documentation](https://mintlify.com/docs) -- [Configuration schema](https://mintlify.com/docs.json) -- [Feature requests](https://github.com/orgs/mintlify/discussions/categories/feature-requests) -- [Bugs and feedback](https://github.com/orgs/mintlify/discussions/categories/bugs-feedback) diff --git a/.agents/skills/prepare-pr/SKILL.md b/.agents/skills/prepare-pr/SKILL.md deleted file mode 100644 index d2834a84b4a..00000000000 --- a/.agents/skills/prepare-pr/SKILL.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -name: prepare-pr -description: Script-first PR preparation with structured findings resolution, deterministic push safety, and explicit gate execution. ---- - -# Prepare PR - -## Overview - -Prepare the PR head branch for merge after `/review-pr`. - -## Inputs - -- Ask for PR number or URL. -- If missing, use `.local/pr-meta.env` if present in the PR worktree. - -## Safety - -- Never push to `main`. -- Only push to PR head with explicit `--force-with-lease` against known head SHA. -- Do not run `git clean -fdx`. -- Wrappers are cwd-agnostic; run from repo root or PR worktree. - -## Execution Contract - -1. Run setup: - -```sh -scripts/pr-prepare init -``` - -2. Resolve findings from structured review: - -- `.local/review.json` is mandatory. -- Resolve all `BLOCKER` and `IMPORTANT` items. - -3. Commit scoped changes with concise subjects (no PR number/thanks; those belong on the final merge/squash commit). - -4. Run gates via wrapper. - -5. Push via wrapper (includes pre-push remote verification, one automatic lease-retry path, and post-push API propagation retry). - -Optional one-shot path: - -```sh -scripts/pr-prepare run -``` - -## Steps - -1. Setup and artifacts - -```sh -scripts/pr-prepare init - -ls -la .local/review.md .local/review.json .local/pr-meta.env .local/prep-context.env -jq . .local/review.json >/dev/null -``` - -2. Resolve required findings - -List required items: - -```sh -jq -r '.findings[] | select(.severity=="BLOCKER" or .severity=="IMPORTANT") | "- [\(.severity)] \(.id): \(.title) => \(.fix)"' .local/review.json -``` - -Fix all required findings. Keep scope tight. - -3. Update changelog/docs (changelog is mandatory in this workflow) - -```sh -jq -r '.changelog' .local/review.json -jq -r '.docs' .local/review.json -``` - -Changelog gate requirement: - -- `CHANGELOG.md` must include a newly added changelog entry line. -- When PR author metadata is available, that same changelog entry line must include `(#) thanks @`. - -4. Commit scoped changes - -Use concise, action-oriented subject lines without PR numbers/thanks. The final merge/squash commit is the only place we include PR numbers and contributor thanks. - -Use explicit file list: - -```sh -scripts/committer "fix: " ... -``` - -5. Run gates - -```sh -scripts/pr-prepare gates -``` - -6. Push safely to PR head - -```sh -scripts/pr-prepare push -``` - -This push step includes: - -- robust fork remote resolution from owner/name, -- pre-push remote SHA verification, -- one automatic rebase + gate rerun + retry if lease push fails, -- post-push PR-head propagation retry, -- idempotent behavior when local prep HEAD is already on the PR head, -- post-push SHA verification and `.local/prep.env` generation. - -7. Verify handoff artifacts - -```sh -ls -la .local/prep.md .local/prep.env -``` - -8. Output - -- Summarize resolved findings and gate results. -- Print exactly: `PR is ready for /merge-pr`. - -## Guardrails - -- Do not run `gh pr merge` in this skill. -- Do not delete worktree. diff --git a/.agents/skills/prepare-pr/agents/openai.yaml b/.agents/skills/prepare-pr/agents/openai.yaml deleted file mode 100644 index 290b1b5ab61..00000000000 --- a/.agents/skills/prepare-pr/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -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 deleted file mode 100644 index f5694ca2c41..00000000000 --- a/.agents/skills/review-pr/SKILL.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -name: review-pr -description: Script-first review-only GitHub pull request analysis. Use for deterministic PR review with structured findings handoff to /prepare-pr. ---- - -# Review PR - -## Overview - -Perform a read-only review and produce both human and machine-readable outputs. - -## Inputs - -- Ask for PR number or URL. -- If missing, always ask. - -## Safety - -- Never push, merge, or modify code intended to keep. -- Work only in `.worktrees/pr-`. -- Wrapper commands are cwd-agnostic; you can run them from repo root or inside the PR worktree. - -## Execution Contract - -1. Run wrapper setup: - -```sh -scripts/pr-review -``` - -2. Use explicit branch mode switches: - -- Main baseline mode: `scripts/pr review-checkout-main ` -- PR-head mode: `scripts/pr review-checkout-pr ` - -3. Before writing review outputs, run branch guard: - -```sh -scripts/pr review-guard -``` - -4. Write both outputs: - -- `.local/review.md` with sections A through J. -- `.local/review.json` with structured findings. - -5. Validate artifacts semantically: - -```sh -scripts/pr review-validate-artifacts -``` - -## Steps - -1. Setup and metadata - -```sh -scripts/pr-review -ls -la .local/pr-meta.json .local/pr-meta.env .local/review-context.env .local/review-mode.env -``` - -2. Existing implementation check on main - -```sh -scripts/pr review-checkout-main -rg -n "" -S src extensions apps || true -git log --oneline --all --grep "" | head -20 -``` - -3. Claim PR - -```sh -gh_user=$(gh api user --jq .login) -gh pr edit --add-assignee "$gh_user" || echo "Could not assign reviewer, continuing" -``` - -4. Read PR description and diff - -```sh -scripts/pr review-checkout-pr -gh pr diff - -source .local/review-context.env -git diff --stat "$MERGE_BASE"..pr- -git diff "$MERGE_BASE"..pr- -``` - -5. Optional local tests - -Use the wrapper for target validation and executed-test verification: - -```sh -scripts/pr review-tests [ ...] -``` - -6. Initialize review artifact templates - -```sh -scripts/pr review-artifacts-init -``` - -7. Produce review outputs - -- Fill `.local/review.md` sections A through J. -- Fill `.local/review.json`. - -Minimum JSON shape: - -```json -{ - "recommendation": "READY FOR /prepare-pr", - "findings": [ - { - "id": "F1", - "severity": "IMPORTANT", - "title": "...", - "area": "path/or/component", - "fix": "Actionable fix" - } - ], - "tests": { - "ran": [], - "gaps": [], - "result": "pass" - }, - "docs": "up_to_date|missing|not_applicable", - "changelog": "required" -} -``` - -8. Guard + validate before final output - -```sh -scripts/pr review-guard -scripts/pr review-validate-artifacts -``` - -## Guardrails - -- Keep review read-only. -- Do not delete worktree. -- Use merge-base scoped diff for local context to avoid stale branch drift. diff --git a/.agents/skills/review-pr/agents/openai.yaml b/.agents/skills/review-pr/agents/openai.yaml deleted file mode 100644 index f6593499507..00000000000 --- a/.agents/skills/review-pr/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -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."