From 35cccbeb68cd4e3291b69b9cf259353016bb75d6 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 29 Apr 2026 10:16:05 +0100 Subject: [PATCH] docs: unify clawsweeper skill --- .agents/skills/clawsweeper/SKILL.md | 315 +++++++++++++++------ .agents/skills/clownfish-cloud-pr/SKILL.md | 171 ----------- 2 files changed, 230 insertions(+), 256 deletions(-) delete mode 100644 .agents/skills/clownfish-cloud-pr/SKILL.md diff --git a/.agents/skills/clawsweeper/SKILL.md b/.agents/skills/clawsweeper/SKILL.md index 08b315f1e92..d128f97b1d1 100644 --- a/.agents/skills/clawsweeper/SKILL.md +++ b/.agents/skills/clawsweeper/SKILL.md @@ -1,35 +1,58 @@ --- name: clawsweeper -description: Inspect ClawSweeper commit-review and issue/PR-sweeper reports for OpenClaw, including recent per-commit reports, finding summaries, GitHub Checks, Actions monitoring, manual backfills, and report links. +description: Use for all ClawSweeper work: OpenClaw issue/PR sweep reports, commit-review reports, repair jobs, cloud fix PRs, comment commands, trusted ClawSweeper-reviewed automerge, GitHub Actions monitoring, permissions, gates, and manual backfills. --- # ClawSweeper -ClawSweeper lives at `~/Projects/clawsweeper`. Use this skill when Peter asks -about ClawSweeper reports, commit-review checks, recent findings, historic -backfills, or whether the sweeper/dispatch lane is healthy. +ClawSweeper lives at `~/Projects/clawsweeper`. It is the one OpenClaw +maintenance bot for sweeping, commit review, repair jobs, and guarded fix PRs. +Use this skill whenever Peter asks about reports, findings, dispatch health, +repair/cloud PR creation, comment commands, automerge, permissions, or gates. ## Start ```bash cd ~/Projects/clawsweeper -git status --short +git status --short --branch git pull --ff-only -pnpm run build +pnpm run build:all ``` -Do not overwrite unrelated local edits. If the tree is dirty, inspect status -and keep report-reading commands read-only unless Peter asked to commit. +Do not overwrite unrelated edits. If the tree is dirty, inspect first and keep +read-only report work read-only unless Peter asked to commit. -## Recent Commit Reports +## One Bot, One App -Canonical reports are flat: +Use the ClawSweeper repo and the `openclaw-ci` GitHub App. Use only +`CLAWSWEEPER_*` configuration for this automation. + +Required app setup: + +- `CLAWSWEEPER_APP_CLIENT_ID`: public app client ID for `openclaw-ci`. +- `CLAWSWEEPER_APP_PRIVATE_KEY`: private key used only inside + `actions/create-github-app-token` steps. +- Target app permissions: read target scan context; write issues and pull + requests; optional Checks write for commit check runs; optional Actions write + on `openclaw/clawsweeper` for app-token dispatch/cancellation. + +Token boundary: + +- Codex workers do not get mutation credentials. +- Review workers run with stripped secret/token env. +- Deterministic scripts own comments, labels, branch pushes, PR creation, + closes, and merges through short-lived GitHub App tokens. +- Merge and write gates default closed. + +## Commit Reports + +Canonical commit reports: ```text records//commits/<40-char-sha>.md ``` -Use the lister instead of browsing date folders: +Use the lister: ```bash pnpm commit-reports -- --since 6h @@ -39,100 +62,222 @@ pnpm commit-reports -- --repo openclaw/openclaw --author steipete --since 7d pnpm commit-reports -- --since 24h --json ``` -One report per commit. Reruns overwrite the same SHA-named file. Results: -`nothing_found`, `findings`, `inconclusive`, `failed`, `skipped_non_code`. +Results: `nothing_found`, `findings`, `inconclusive`, `failed`, +`skipped_non_code`. One report per SHA; reruns overwrite the SHA-named report. -## Monitor Actions +Manual rerun/backfill: -Receiver lane in `openclaw/clawsweeper`: +```bash +gh workflow run commit-review.yml --repo openclaw/clawsweeper \ + -f target_repo=openclaw/openclaw \ + -f commit_sha= \ + -f before_sha= \ + -f create_checks=false \ + -f enabled=true +``` + +Use `create_checks=true` only when Peter explicitly wants target commit Check +Runs. Add `-f additional_prompt="..."` for focused one-off review instructions. + +## Sweep Reports + +Issue/PR reports live at: + +```text +records//items/.md +records//closed/.md +``` + +Lead with counts, concrete findings, and report links. Do not post unsolicited +GitHub comments from report-reading work. Public surfaces are markdown reports, +durable ClawSweeper review comments, and optional checks. + +Useful commands: + +```bash +pnpm run status +pnpm run audit +pnpm run reconcile +pnpm run apply-decisions -- --dry-run +``` + +## Create One Repair Job + +Create a job from issue/PR refs and a maintainer prompt: + +```bash +pnpm run repair:create-job -- \ + --repo openclaw/openclaw \ + --refs 123,456 \ + --prompt-file /tmp/clawsweeper-prompt.md +``` + +Create from an existing ClawSweeper report: + +```bash +pnpm run repair:create-job -- \ + --from-report ../clawsweeper/records/openclaw-openclaw/items/123.md +``` + +The job creator checks for an existing open PR, body match, or remote +`clawsweeper/` branch before writing another job. Use `--dry-run` +to inspect. Use `--force` only after deciding the duplicate guard is stale. + +Validate, commit, then dispatch: + +```bash +pnpm run repair:validate-job -- jobs/openclaw/inbox/clawsweeper-openclaw-openclaw-123.md +pnpm run repair:dispatch -- jobs/openclaw/inbox/clawsweeper-openclaw-openclaw-123.md \ + --mode autonomous \ + --runner blacksmith-4vcpu-ubuntu-2404 \ + --execution-runner blacksmith-16vcpu-ubuntu-2404 \ + --model gpt-5.5 +``` + +Do not dispatch a just-created job before the job file is committed and pushed; +the workflow reads the job path from GitHub. + +## Replacement PRs + +For a useful but uneditable/stale/unsafe source PR, make the maintainer prompt +explicit: + +```md +Treat #123 as useful source work. If the source branch cannot be safely updated +because it is uneditable, stale, draft-only, unmergeable, or unsafe, create a +narrow ClawSweeper replacement PR instead of waiting. Preserve the source PR +author as co-author, credit the source PR in the replacement PR body, and close +only that source PR after the replacement PR is opened. +``` + +The worker should emit `repair_strategy=replace_uneditable_branch` and list the +source PR URL in `source_prs`. The deterministic executor opens or updates +`clawsweeper/`, adds non-bot source authors as `Co-authored-by` +trailers, and closes superseded source PRs only after replacement exists. + +## Gates + +Open execution windows intentionally and close them after the run: + +```bash +gh variable set CLAWSWEEPER_REPAIR_ALLOW_EXECUTE --repo openclaw/clawsweeper --body 1 +gh variable set CLAWSWEEPER_REPAIR_ALLOW_FIX_PR --repo openclaw/clawsweeper --body 1 +gh variable set CLAWSWEEPER_REPAIR_ALLOW_MERGE --repo openclaw/clawsweeper --body 0 +gh variable set CLAWSWEEPER_REPAIR_ALLOW_AUTOMERGE --repo openclaw/clawsweeper --body 0 +``` + +Reset execute/fix gates to `0` after the window. Keep merge gates closed unless +Peter explicitly opens a merge/automerge window. + +Important gates: + +- `CLAWSWEEPER_REPAIR_ALLOW_EXECUTE`: allows deterministic write lanes. +- `CLAWSWEEPER_REPAIR_ALLOW_FIX_PR`: allows branch repair/replacement PRs. +- `CLAWSWEEPER_REPAIR_ALLOW_MERGE`: allows merge-capable applicators. +- `CLAWSWEEPER_REPAIR_ALLOW_AUTOMERGE`: allows comment-router automerge. +- `CLAWSWEEPER_REPAIR_COMMENT_ROUTER_EXECUTE`: lets scheduled comment routing + post replies and dispatch repair. + +## Comment Commands + +Maintainers can use: + +```text +/clawsweeper status +/clawsweeper fix ci +/clawsweeper address review +/clawsweeper rebase +/clawsweeper automerge +/clawsweeper explain +/clawsweeper stop +@openclaw-clawsweeper fix ci +``` + +Default accepted maintainers: `OWNER`, `MEMBER`, `COLLABORATOR`; fallback +repository permission accepts `admin`, `maintain`, or `write`. Contributor +comments are ignored without a reply. + +Run router manually: + +```bash +pnpm run repair:comment-router -- --repo openclaw/openclaw --lookback-minutes 180 +pnpm run repair:comment-router -- --repo openclaw/openclaw --execute --wait-for-capacity +``` + +Scheduled routing stays dry unless +`CLAWSWEEPER_REPAIR_COMMENT_ROUTER_EXECUTE=1`. + +## Trusted Automerge + +`/clawsweeper automerge` opts an existing PR into the bounded loop. The router: + +- verifies maintainer authorization; +- labels the PR `clawsweeper:automerge`; +- dispatches ClawSweeper review for the current head SHA; +- creates or reuses a durable adopted job; +- repairs at most the configured caps; +- merges only when ClawSweeper passed the exact current head, checks are green, + GitHub says mergeable, no human-review label is present, and both merge gates + are open. + +If ClawSweeper passes while merge gates are closed, it labels +`clawsweeper:merge-ready` and comments instead of merging. `/clawsweeper stop` +adds `clawsweeper:human-review`. + +Repair caps: + +```bash +CLAWSWEEPER_REPAIR_MAX_REPAIRS_PER_PR=5 +CLAWSWEEPER_REPAIR_MAX_REPAIRS_PER_HEAD=1 +``` + +## Security Boundary + +Do not stage security-sensitive work for ClawSweeper Repair. Route vulnerability +reports, CVE/GHSA/advisory work, leaked secrets/tokens/keys, plaintext secret +storage, SSRF, XSS, CSRF, RCE, auth bypass, privilege escalation, and sensitive +data exposure to central OpenClaw security handling. + +For adopted automerge jobs, trust deterministic ClawSweeper security markers, +labels, and job frontmatter; do not infer security handling from vague prose. + +## Monitoring + +Receiver workflows: ```bash gh run list --repo openclaw/clawsweeper --workflow "ClawSweeper Commit Review" \ --limit 12 --json databaseId,displayTitle,event,status,conclusion,createdAt,updatedAt,url -gh run list --repo openclaw/clawsweeper --workflow "ClawSweeper Commit Review" \ - --status in_progress --limit 20 --json databaseId,displayTitle,event,status,createdAt,url +gh run list --repo openclaw/clawsweeper --workflow "repair cluster worker" \ + --limit 12 --json databaseId,displayTitle,event,status,conclusion,createdAt,updatedAt,url +gh run list --repo openclaw/clawsweeper --workflow "repair comment router" \ + --limit 12 --json databaseId,displayTitle,event,status,conclusion,createdAt,updatedAt,url ``` -Target dispatcher in `openclaw/openclaw`: +Target dispatcher: ```bash gh run list --repo openclaw/openclaw --workflow "ClawSweeper Dispatch" \ --event push --limit 8 --json databaseId,displayTitle,event,status,conclusion,headSha,url -git ls-remote https://github.com/openclaw/openclaw.git refs/heads/main ``` -Check the target commit's published report check: +Target commit check: ```bash gh api "repos/openclaw/openclaw/commits//check-runs?per_page=100" \ --jq '.check_runs[] | select(.name=="ClawSweeper Commit Review") | [.status,.conclusion,.details_url] | @tsv' ``` -## Manual Commit Rerun / Backfill +## Reading Output -Use the receiver workflow when Peter asks to rerun a specific commit report, -review a specific commit, or backfill a historic range. Reruns overwrite the -same canonical report file: -`records//commits/<40-char-sha>.md`. +For findings or failures, summarize: -Single-commit rerun: +- target repo, item/PR/commit, run, report path +- result, confidence, severity, and exact blocker +- affected files or cluster refs +- validation commands and whether they passed +- whether mutation gates were open or closed +- next deterministic action -```bash -gh workflow run commit-review.yml --repo openclaw/clawsweeper \ - -f target_repo=openclaw/openclaw \ - -f commit_sha= \ - -f before_sha= \ - -f create_checks=false \ - -f enabled=true -``` - -Historic range backfill: - -```bash -gh workflow run commit-review.yml --repo openclaw/clawsweeper \ - -f target_repo=openclaw/openclaw \ - -f commit_sha= \ - -f before_sha= \ - -f create_checks=false \ - -f enabled=true -``` - -Use `create_checks=true` only when Peter explicitly wants target commit check -runs. Checks are opt-in; markdown reports are the primary surface. - -For a targeted rerun with extra instructions, add `additional_prompt`: - -```bash --f additional_prompt="Review this commit with focus on ." -``` - -After dispatch, monitor and then pull the regenerated report: - -```bash -gh run list --repo openclaw/clawsweeper --workflow "ClawSweeper Commit Review" \ - --limit 5 --json databaseId,displayTitle,status,conclusion,url -gh run watch --repo openclaw/clawsweeper --interval 30 --exit-status -git pull --ff-only -sed -n '1,180p' records/openclaw-openclaw/commits/.md -``` - -## Report Reading - -Lead with counts and useful findings: - -```bash -pnpm commit-reports -- --since 24h -pnpm commit-reports -- --since 24h --findings -``` - -If findings exist, open the markdown report and summarize: - -- SHA and author/co-authors -- result, confidence, severity, check conclusion -- concrete finding and affected file -- whether the report includes tests/live checks -- GitHub report URL: - `https://github.com/openclaw/clawsweeper/blob/main/` - -Do not post GitHub comments from this lane. Commit Sweeper's public surfaces are -markdown reports and the `ClawSweeper Commit Review` check. +Keep the broom small: one cluster, one branch, one PR, narrow proof, clear +owner-visible evidence. diff --git a/.agents/skills/clownfish-cloud-pr/SKILL.md b/.agents/skills/clownfish-cloud-pr/SKILL.md deleted file mode 100644 index 2e5371187ad..00000000000 --- a/.agents/skills/clownfish-cloud-pr/SKILL.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -name: clownfish-cloud-pr -description: Use when launching Clownfish in GitHub Actions to create or update one guarded GitHub implementation PR from issue/PR refs, a ClawSweeper report, a custom maintainer prompt, or to opt an existing Clownfish PR into ClawSweeper-reviewed cloud automerge. ---- - -# Clownfish Cloud PR - -Use this skill when the user wants Codex to ask Clownfish to create a PR in the -cloud from issue/PR refs plus a custom prompt. - -## Start - -```bash -cd ~/Projects/clownfish -git status --short --branch -gh variable list --repo openclaw/clownfish --json name,value \ - --jq 'map(select(.name|test("^CLOWNFISH_"))) | sort_by(.name) | .[] | {name,value}' -``` - -Keep merge gated unless Peter explicitly opens it. Execute/fix gates are closed -unless the repo variables are literally `1`; normal fix-PR work needs an -intentional execution window: - -```bash -gh variable set CLOWNFISH_ALLOW_EXECUTE --repo openclaw/clownfish --body 1 -gh variable set CLOWNFISH_ALLOW_FIX_PR --repo openclaw/clownfish --body 1 -gh variable set CLOWNFISH_ALLOW_MERGE --repo openclaw/clownfish --body 0 -gh variable set CLOWNFISH_ALLOW_AUTOMERGE --repo openclaw/clownfish --body 0 -``` - -Reset `CLOWNFISH_ALLOW_EXECUTE=0` and `CLOWNFISH_ALLOW_FIX_PR=0` after the -window. If those vars are absent or not `1`, execute/autonomous workflow runs -stay plan-only/no-mutation. - -## Create One Job - -From refs and a custom prompt: - -```bash -npm run create-job -- \ - --repo openclaw/openclaw \ - --refs 123,456 \ - --prompt-file /tmp/clownfish-prompt.md -``` - -From a ClawSweeper report: - -```bash -npm run create-job -- \ - --from-report ../clawsweeper/records/openclaw-openclaw/items/123.md -``` - -The script checks for an existing open PR/body match and remote branch named -`clownfish/` before writing a duplicate job. Use `--dry-run` to -inspect the exact job body and `--force` only after deciding the duplicate check -is stale. - -## Ask For A Replacement PR - -The skill can trigger replacement PR writing through the normal `create-job` -and `dispatch` path. Put the maintainer decision in the prompt: - -```md -Treat #123 as useful source work. If the source branch cannot be safely updated -because it is uneditable, stale, draft-only, unmergeable, or unsafe, create a -narrow Clownfish replacement PR instead of waiting. Preserve the source PR -author as co-author, credit the source PR in the replacement PR body, and close -only that source PR after the replacement PR is opened. -``` - -The worker should emit `repair_strategy=replace_uneditable_branch` and list the -source PR URL in `source_prs`. The deterministic executor opens or updates -`clownfish/`, adds non-bot source PR authors as `Co-authored-by` -trailers, and closes the superseded source PR only after the replacement PR -exists. New replacement PRs are blocked when the touched area already has -`CLOWNFISH_MAX_ACTIVE_PRS_PER_AREA` open Clownfish PRs. - -## Validate And Dispatch - -```bash -npm run validate:job -- jobs/openclaw/inbox/clawsweeper-openclaw-openclaw-123.md -npm run render -- jobs/openclaw/inbox/clawsweeper-openclaw-openclaw-123.md --mode autonomous >/tmp/clownfish-rendered-prompt.md -git add jobs/openclaw/inbox/clawsweeper-openclaw-openclaw-123.md -git commit -m "chore: add ClawSweeper promoted job" -git push origin main -npm run dispatch -- jobs/openclaw/inbox/clawsweeper-openclaw-openclaw-123.md \ - --mode autonomous \ - --runner blacksmith-4vcpu-ubuntu-2404 \ - --execution-runner blacksmith-16vcpu-ubuntu-2404 \ - --model gpt-5.5 -``` - -Do not use `--dispatch` until the job is committed and pushed; the workflow -reads the job path from GitHub. - -## Maintainer Comment Commands - -Clownfish can also be asked from target repo comments, but only by maintainers. -Use `/clownfish ...` or `@openclaw-clownfish ...`; do not use `@clownfish` -because that is a separate GitHub user. - -Supported commands: - -```text -/clownfish status -/clownfish fix ci -/clownfish address review -/clownfish rebase -/clownfish automerge -/clownfish explain -/clownfish stop -@openclaw-clownfish fix ci -``` - -The router accepts `OWNER`, `MEMBER`, and `COLLABORATOR` comments by default. -Contributor comments are ignored without a reply. Repair commands dispatch -`cluster-worker.yml` only for existing Clownfish PRs with the `clownfish` label -or `clownfish/*` branch. - -```bash -npm run comment-router -- --repo openclaw/openclaw --lookback-minutes 180 -npm run comment-router -- --repo openclaw/openclaw --execute --wait-for-capacity -``` - -Scheduled routing stays dry until `CLOWNFISH_COMMENT_ROUTER_EXECUTE=1` is set in -`openclaw/clownfish` repo variables. - -## Bounded ClawSweeper-Reviewed Automerge - -Use this only for an existing Clownfish PR that maps back to a `clownfish/*` -branch and job file: - -```text -/clownfish automerge -``` - -The router verifies the commenter is a maintainer, adds -`clownfish:automerge`, dispatches ClawSweeper for the current PR head, and -waits for trusted ClawSweeper markers. `needs-changes` / `fix-required` -dispatches the normal repair worker. `pass`, `approved`, or `no-changes` may -merge only when the marker SHA matches the current PR head, checks are green, -GitHub says the PR is mergeable, no `clownfish:human-review` label is present, -and both merge gates are open: - -```bash -gh variable set CLOWNFISH_ALLOW_MERGE --repo openclaw/clownfish --body 1 -gh variable set CLOWNFISH_ALLOW_AUTOMERGE --repo openclaw/clownfish --body 1 -``` - -The actual merge command is pinned with GitHub's head-match guard, so a branch -push after ClawSweeper reviewed cannot merge an unreviewed head. If either -merge gate is closed when ClawSweeper passes, Clownfish labels the PR -`clownfish:merge-ready` only after readiness checks have passed; failing checks, -stale heads, conflicts, draft state, or human-review labels must not get that -label. Pause with `/clownfish stop`, which adds `clownfish:human-review`. - -The repair loop is capped by `CLOWNFISH_CLAWSWEEPER_MAX_REPAIRS_PER_PR` -(default `5`) and `CLOWNFISH_CLAWSWEEPER_MAX_REPAIRS_PER_HEAD` (default `1`). - -## Guardrails - -- One cluster, one branch, one PR: `clownfish/`. -- No security-sensitive work. -- New replacement PRs are capped per touched area by - `CLOWNFISH_MAX_ACTIVE_PRS_PER_AREA`. -- Do not merge from Clownfish unless Peter explicitly asks. -- Do not open `CLOWNFISH_ALLOW_AUTOMERGE` unless Peter explicitly asks for an - automerge window. -- Do not close duplicates before the fix PR path exists, lands, or is proven - unnecessary. -- Codex workers do not get GitHub tokens; deterministic scripts own writes.