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.

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.