clownfish-cloud-pr

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 opt any PR into ClawSweeper-reviewed Clownfish 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

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:

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:

npm run create-job -- \
  --repo openclaw/openclaw \
  --refs 123,456 \
  --prompt-file /tmp/clownfish-prompt.md

From a ClawSweeper report:

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/<cluster-id> 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:

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/<cluster-id>, 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

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:

/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 for existing Clownfish PRs and for PRs explicitly opted into clownfish:automerge.

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 on any open target-repo PR:

/clownfish automerge

The router verifies the commenter is a maintainer, adds clownfish:automerge, creates a durable adopted job under jobs/<owner>/inbox/automerge-<owner>-<repo>-<pr>.md when the PR is not already backed by a Clownfish job, dispatches ClawSweeper for the current PR head, and waits for trusted ClawSweeper markers. needs-changes / fix-required dispatches the normal repair worker. The worker updates the source branch when safe, otherwise opens a credited replacement or returns needs_human. 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:

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/<cluster-id>.
• For adopted automerge PRs, the worker may repair the source branch only when GitHub reports it is safe to update; router-owned merge still requires a fresh ClawSweeper pass for the exact head.
• 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.