From ade863e08f932a520ffc68ccd2f92b28fcae67fb Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 29 Apr 2026 06:47:49 +0100 Subject: [PATCH] docs: update Clownfish automerge skill --- .agents/skills/clownfish-cloud-pr/SKILL.md | 78 +++++++++++++++++----- 1 file changed, 63 insertions(+), 15 deletions(-) diff --git a/.agents/skills/clownfish-cloud-pr/SKILL.md b/.agents/skills/clownfish-cloud-pr/SKILL.md index 4c7c384884f..2e5371187ad 100644 --- a/.agents/skills/clownfish-cloud-pr/SKILL.md +++ b/.agents/skills/clownfish-cloud-pr/SKILL.md @@ -1,6 +1,6 @@ --- 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, or a custom maintainer prompt. +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 @@ -8,13 +8,35 @@ description: Use when launching Clownfish in GitHub Actions to create or update 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. -## Create One Job +## 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 \ @@ -30,7 +52,8 @@ npm run create-job -- \ 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. +inspect the exact job body and `--force` only after deciding the duplicate check +is stale. ## Ask For A Replacement PR @@ -68,18 +91,7 @@ npm run dispatch -- jobs/openclaw/inbox/clawsweeper-openclaw-openclaw-123.md \ ``` Do not use `--dispatch` until the job is committed and pushed; the workflow -reads the job path from GitHub. Execute/fix gates are closed unless the repo -variables are literally `1`; open them only for the 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 -``` - -Reset `CLOWNFISH_ALLOW_EXECUTE=0` and `CLOWNFISH_ALLOW_FIX_PR=0` after the -window. Keep `CLOWNFISH_ALLOW_MERGE=0` unless Peter explicitly opens the merge -gate. +reads the job path from GitHub. ## Maintainer Comment Commands @@ -94,6 +106,7 @@ Supported commands: /clownfish fix ci /clownfish address review /clownfish rebase +/clownfish automerge /clownfish explain /clownfish stop @openclaw-clownfish fix ci @@ -112,12 +125,47 @@ 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.